Quell integration

design · draft · NLP and argumentation · edited 2026-11-06

Sketch. Nothing here is built; Quell has no debate, reading or dialogue code yet.

The player’s loop

flowchart TB
  READ["read in-world texts"] --> HL["highlight + take notes"]
  HL --> BANK[("statements collected")]
  BANK --> IN{"how the player argues"}
  IN --> FT["free text (dropped)"]
  IN --> TE["thinking editor"]
  FT --> DEB["debate an NPC"]
  TE --> DEB
  DEB -->|NPC answers| IN
  DEB -->|win or move on| NEXT["next area / next run"]
  NEXT -->|keep what you know| READ
  click FT href "debate-spike.html"
  click DEB href "debate-evaluation.html"

Reading. Highlights snap to authored statement spans (the map’s L-nodes), so a highlight is always a known statement. Notes stay free text.
Arguing. Two paths, both to be tried for how they feel:
- 🪦 Outdated Free text: the player types; a model parses it into a small map. Needs a runtime parse that works. Dropped (2026-11-06); thinking editor only.
- Thinking editor: the player links collected statements, premise → conclusion, and picks a lever. No model needed: every statement is already analysed, so the type follows by rule. Here the player does the ATIP typing, and that’s the learning.
Carrying over. A new run keeps some highlights, texts and conclusions.

Runtime pieces

flowchart LR
  subgraph Assets["content (RON)"]
    TXT[("texts + spans")]
    SB[("statement bank")]
    NPC[("NPC repertoires")]
  end
  subgraph Quell["Quell services"]
    RD["reading"]
    ARG["argue: editor<br/>or free-text parse (dropped)"]
    DB["debate"]
    DL["dialogue"]
  end
  CORE["q_pta (pure Rust):<br/>derive_code, lever options"]
  TXT --> RD --> ARG
  SB --> ARG --> DB
  NPC --> DB
  DB --> CORE
  DB --> DL
  click ARG href "debate-spike.html"
  click DB href "debate-evaluation.html"

q_pta: a pure library crate with the PTA table and a port of the editor’s deriveCode and leverOptions, checked against ra-inputs.json. A new lib/ crate also needs its own skill and a q-os map entry.
Assets: an exporter turns reviewed maps into RON: texts and spans, the statement bank, NPC repertoires.
Dialogue: misc/labs/nlp/examples/*.yarn sketch it in Yarn. bevy_yarnspinner isn’t evaluated yet.
Layout: services/{reading,notes,debate}, screens/debate, per bin/quell/docs/architecture.md. Tweakables are Resources.

Structure, not judgement

For now the game only checks structure: does the argument have a type, and does the lever fit it? Whether it’s good, and who wins, is later research.

What links here: Quell story progression: design, Arms and decisions, Open questions, Phases, Quell debate: plan map, NPC stances: data model, Debate, NLP and argumentation, Reading notes