Glossary

The docs are dense with project-specific vocabulary. Here’s every term in one place.

Pipeline & structure

Abstract - the one-line topic you seed a project with; the only required human input.

Angle / Direction - one of three distinct framings the planner proposes for your abstract. You pick one (or --pick N); articles call them angles, books call them directions.

Unit - the atomic piece of writing the pipeline processes one at a time: a chapter (book) or a section (article).

Node / Agent - a single-purpose LLM call with a typed input and output (planner, writer, critic, …). Routed to its own model tier via models.yaml.

Orchestrator - the durable state machine that walks a project through its stages, persisting to disk before each advance.

Manuscript - the assembled, ordered output (manuscript.md) - title, byline, units, and references - that the exporters render.

The quality loop

Thesis - an article’s generated contestable claim: stakes, supporting arguments, a steelmanned counterargument with rebuttal, and non-goals. Injected into every writer and critic call; the critic blocks coverage that doesn’t advance it.

Divergent drafts - the first attempt at a unit sampled as N variants at different temperatures (0.7 / 1.0 / 1.2); the critic (or you) picks the strongest to refine.

Critic - the node that gates every commit: returns approve / revise / escalate and scores insight, clarity, structure, and evidence.

Insight score - the critic’s 1–5 rating of how non-obvious a draft is. Approval requires insight ≥ min_insight; a correct-but-generic draft gets a sharpening note.

Revise - a fresh draft + critique round, repeated up to max_revisions. Also the revise command, which rewrites one committed unit of a finished piece.

Escalation - what happens when the revision cap is hit in manual mode: a one-keypress menu (fix / instruct / approve / go-auto / read / stop). Autonomous mode commits the best draft instead.

Humanizer - the surgical pass that rewrites only the sentences a deterministic AI-tell scanner flags, preserving citations, numbers, and length. Never regenerates approved prose.

Cohesion pass - an optional whole-article smoothing of transitions and repetition before References; guarded against content loss.

Commit - persisting an approved unit: prose + summary (+ canon extraction for books) + the search index.

Craft & voice

Register - one of 11 genre profiles (nonfiction, technical, literary-fiction, genre-fiction, academic, journalism, copywriting, business, poetry, screenplay, children) that parameterizes the craft engine: it inverts the anti-slop rules, structure, and citation style per genre. register (empty = inferred from the topic/angle).

Field - a structural template within a register (the skeleton the writer fills). field.

Persona - a voice manner layered over the register - one of 46 (18 archetypes + 28 public-domain manners like shakespearean / wildean; no living authors, original-pastiche exemplars). Dropped and logged if it clashes with the register. persona.

Emotion - a per-run emotional target - one of 12. Instead of a cliché-generating symptom dictionary, it wires an anti-cliché deny-list into the detector plus a show-don’t-name cue. emotion.

Compositor - the layer that resolves the voice cascade register ⊃ field ⊃ persona ⊃ emotion ⊃ skills: it selects one voice and logs why, never stacks them (more layers is worse on a weak model).

Craft pass - surgical show-don’t-tell / de-passive edits run on each committed unit (craft_passes, default on).

Books & memory

Canon - a book’s durable memory: character facts, world rules, and a timeline, extracted from committed prose and searchable via a full-text index.

Consolidation - a periodic pro-tier pass (every consolidate_every chapters) that reads the whole canon, merges duplicates, and flags contradictions.

Production - the post-writing layer that decides and generates genre-aware front/back matter (epigraph, glossary, acknowledgments, …) and assembles the manuscript.

Research & media

Research (shallow) - one search query per unit → snippets → a short brief. On by default, cached 7 days.

Deep research - multi-query fan-out + full page-text fetch of the top sources + cross-source synthesis with numbered citations. Opt-in (deep_research: true).

Search provider - the web-search backend, set by search_provider: duckduckgo (default, no key) or firecrawl (needs FIRECRAWL_API_KEY; also switches deep-research scraping to Firecrawl). A missing key or a failure degrades back to DuckDuckGo.

Scrapo - the optional richer fetch backend that escalates HTTP → browser → stealth for hard pages; falls back to a stdlib fetcher.

Keyword pack - the piece’s search + social signals named in one flash call: primary and secondary keywords, a meta description, and per-platform hashtags. The primary keyword is threaded into the writer from the start; the pack drives the SEO audit and the promo variants. Persisted to keywords.json.

SEO, promotion & rewriting

SEO pass - a deterministic on-page audit (title/description lengths, keyword placement) plus the flash keyword pack, writing seo_report.md. It only edits the article and adds keywords/hashtags - it never posts or schedules anything. Runs automatically with auto_promote on, or via seo. See SEO & promotion.

Repurpose - generating a platform-native variant of a finished piece (X thread, LinkedIn post, newsletter teaser, TL;DR) plus headline variants, reusing the keyword pack. Local artifacts under promo/ only - nothing is posted anywhere. Via promote or auto_promote.

Restyle - re-voicing a finished manuscript into a target style (register) / persona / emotion in one flash call, preserving structure, citations, and facts. Writes restyled/<combo>.md; the original is untouched. The web dashboard’s Export tab exposes it as Rewrite.

Rejected - the log (rejected.jsonl) of items the pipeline dropped during figure reconciliation and commit - unused images, skipped suggestions - kept for review rather than silently discarded. Surfaced in the web dashboard’s Rejected tab.

Learning & trust

Craft skills - markdown lessons the learner distills from each finished piece, promoted candidate → trusted (or retired) on evidence. The efficacy signal is an ablation duel win-rate, with first-pass lift as the fallback. Thirteen ship built in and seed a new brain (seed-skills).

Ablation duel (skill duel) - the causal efficacy test (skill_duels, opt-in, default off). On a unit with an undecided skill, the writer drafts one extra variant with that skill held out and the critic compares it against the full-skill draft - a true counterfactual for whether the skill helped. Promotion/retirement run off a smoothed, sample-gated duel win-rate vs a 0.5 coin-flip (50/50) (≥5 duels to decide; ≥0.55 promotes, ≤0.45 retires). Surfaced in /skills as a duels (vs 50/50) column.

Distill (skill distillation) - a deterministic, non-destructive pass (skill_distill, opt-in, default off) that retires near-duplicate skills (textual Jaccard similarity ≥ 0.85), keeping the best duel-scored one per cluster so retrieval stays sharp.

Watch-list - the recurring issues the critic kept flagging, injected into future critic calls. With watch_blocking on (default) only clear, concrete violations block; borderline ones become nits. Set it false to make the list fully advisory.

Voice exemplars - admired passages you drop in voice/ (or mark with /praise), injected into every writer call as a register to match.

Version snapshot - every generated draft (variants, revisions, committed finals) saved under <project>/versions/ - git-for-writing, browsable with versions and read --v K.

Table read - a skeptical whole-piece cold read reporting where a real reader gets bored, confused, or loses trust. Report-only; feeds revise.

Eval - the quality scorecard: a judged 5-dimension rubric + deterministic metrics, written to eval_report.md.

Agentic mode

Agentic controller - the opt-in mode (agentic, default off) where, instead of the fixed order, a policy chooses each unit’s next move (draft / gather research / read canon) and the writer can call tools mid-draft. The fixed pipeline is the fallback; off = byte-identical to it.

Policy (default / llm / trace) - who the controller asks for the next move: default (always draft - the fixed pipeline), llm (an LLM controller decides), or trace (a policy learned from your own past runs).

Trace policy - the learned controller policy distilled from your accumulated action traces; it answers “does gathering before drafting actually improve the outcome here?” and abstains until it has ≥10 labelled units per arm (so a thin corpus falls back to the heuristic).

Action trace - the append-only agent_trace.jsonl log of every controller decision (the move, the reason, and the unit’s outcome label), shown by /trace.

Operations

Brain - the on-disk tree (brain/) that is both the data store and the resume checkpoint.

Fake mode - WRITINGAGENT_FAKE=1: every node returns deterministic placeholder output, so the whole pipeline runs offline with no API key.

Glimpse - the draft-opening preview shown per attempt in the run dashboard, so you can cancel a run going wrong before it costs more.

Telemetry - one local JSONL record per LLM call (model, tokens, cost, latency, error), attributed per node and per unit, surfaced by /dashboard and the web dashboard’s Telemetry / Cost views. Never leaves your machine.

Cost mode - cost_mode: budget (default) pins the spend-heavy knobs lean, routes the judgment nodes to the flash tier, and applies a per-unit token budget targeting ≤100k tokens/article; standard leaves them at full quality. See Cost & performance.

Flash routing - under budget mode, the judgment nodes (critic, judge, verifier, consolidation, diagram) are routed to the cheaper flash model tier instead of pro, where the quality cost is smallest.

Budget vs. ceiling - budget_tokens_per_unit (default 20 000) sizes the soft per-run budget (scales with unit count); max_run_tokens is a hard ceiling that pauses the run when hit (0 = unlimited) and always wins.

Interface & design

Web dashboard - the local browser UI (writing-agent web): a stdlib server that streams a live run over SSE and exposes the same runs, evals, artifacts, cost, and settings as the TUI. Binds 127.0.0.1 only, no auth, one job at a time. See Web dashboard.

SSE (Server-Sent Events) - the one-way, plain-HTTP streaming the web dashboard uses to push live run events (progress, verdicts, log lines) to the browser - no WebSocket, no extra deps.

Manuscript red - #a3341f, the single accent color of the editorial design system: the editor’s red pen, used for links, focus, and status.

Measure - the optimal reading line length (~66 characters) prose surfaces are constrained to across web, TUI, and print - a design-system rule, not a per-page choice.