scriveno 2.0.12 → 2.6.0

package/commands/scr/pacing-analysis.md

@@ -1,5 +1,6 @@
 ---
 description: Generate a structure-aware pacing report analyzing scene tempo and narrative flow.
+argument-hint: "[N]"
 ---
 
 # /scr:pacing-analysis -- Structure-Aware Pacing Report

package/commands/scr/polish.md

@@ -1,5 +1,6 @@
 ---
 description: Chain line-edit, copy-edit, and voice-check for comprehensive prose polish.
+argument-hint: "[N]"
 ---
 
 # /scr:polish -- Comprehensive Prose Polish

package/commands/scr/quick-write.md

@@ -1,5 +1,6 @@
 ---
 description: Write a scene, passage, or chapter outside the full planning workflow.
+argument-hint: "[--discuss] [--research] [--full]"
 ---
 
 # /scr:quick-write -- Ad-Hoc Writing Without Full Planning
@@ -18,7 +19,7 @@ Write a scene, passage, or chapter outside the full planning workflow.
 
 ## Instruction
 
-Quick write gives you Scriveno guarantees (continuity tracking, voice consistency, atomic commits) with a faster path.
+Quick write is the fast path. It loads STYLE-GUIDE.md, drafts in the current conversation context (not a fresh per-unit context), and commits atomically. It runs continuity and voice checks only when you pass `--full`. For voice-critical work, prefer `/scr:draft`, which drafts each unit in a fresh context and always runs a voice-check.
 
 ### STEP 1: GATHER INTENT
 
@@ -49,6 +50,8 @@ If the host runtime cannot spawn a focused researcher, run the research pass in
 
 Write the passage following all established style guide constraints. Target whatever length feels natural unless the writer specified a target.
 
+Quick-write drafts in the current conversation context rather than spawning the drafter in a fresh per-unit context; this trades some voice isolation for speed. When fresh-context voice fidelity matters, use `/scr:draft` instead.
+
 ### STEP 4: VERIFY (if --full)
 
 Run continuity and voice checks against existing manuscript.

package/commands/scr/sensitivity-review.md

@@ -1,5 +1,6 @@
 ---
 description: Flag potential sensitivity issues with context, suggest alternatives, and note intentional craft.
+argument-hint: "[N]"
 ---
 
 # /scr:sensitivity-review -- Sensitivity Review with Craft Awareness

package/commands/scr/synopsis.md

@@ -1,5 +1,6 @@
 ---
 description: Generate plot synopsis at specified length for query and submission packages.
+argument-hint: "[--length <1p|2p|5p>]"
 ---
 
 # /scr:synopsis -- Plot Synopsis Generator

package/commands/scr/theme-tracker.md

@@ -1,5 +1,6 @@
 ---
 description: Track thematic threads across the work with auto-detection suggestions.
+argument-hint: "[--detect]"
 ---
 
 # /scr:theme-tracker -- Track Thematic Threads

package/commands/scr/timeline.md

@@ -1,5 +1,6 @@
 ---
 description: Generate a chronological event timeline from the outline.
+argument-hint: "[--story-order] [--chronological]"
 ---
 
 # /scr:timeline -- Chronological Event Timeline

package/commands/scr/track.md

@@ -48,6 +48,8 @@ Track metadata lives in `.manuscript/tracks.json`. Create this file on first `tr
 
 **Label-to-branch mapping (D-01):** Writer-friendly labels are stored as-is. The git branch name is derived by slugifying the label: lowercase, replace spaces with hyphens, strip special characters (keep alphanumeric and hyphens only), prefix with `track/`. Example: "Second Draft Attempt" becomes `track/second-draft-attempt`.
 
+This slugify step is the one safety boundary that keeps a writer-chosen label out of a shell command, so it is mandatory, never optional. The canonical algorithm ships as `lib/track-safety.js` (installed to `<data-dir>/lib/track-safety.js`). To derive the slug and a collision-free branch deterministically instead of applying the rules by hand, run `node <data-dir>/lib/track-safety.js "<label>"`, which prints `{"slug":"...","branch":"..."}` with collisions already resolved against a comma-separated second argument of existing branch names. A correct slug contains only `[a-z0-9-]`; if it contains anything else, do not pass it to git.
+
 **Canon branch metadata:** `canon_branch` stores the real branch name of the canon manuscript. This may be `main`, `master`, `trunk`, or any other branch name the writer uses.
 
 ## Canon Branch Resolution

package/commands/scr/translate.md

@@ -214,7 +214,7 @@ After all units are translated, show a summary:
 > - Build translation memory: `/scr:translation-memory [lang] --build`
 > - Cultural adaptation review: `/scr:cultural-adaptation [lang]`
 > - Back-translate to verify: `/scr:back-translate [lang]`
-> - Export translation: `/scr:export --format [format] --language [lang]`
+> - Export translation: `/scr:multi-publish --languages [lang] --format [format]` (the translated-export path; `/scr:export` builds the source-language manuscript only)
 
 ## Agent and Automation Status
 

package/commands/scr/voice-check.md

@@ -1,5 +1,6 @@
 ---
 description: Compare drafted prose against STYLE-GUIDE.md to detect voice drift.
+argument-hint: "[N]"
 ---
 
 # /scr:voice-check -- Voice Fidelity Check

package/data/CONSTRAINTS.json

@@ -1,12 +1,13 @@
 {
   "$schema": "./constraints.schema.json",
-  "version": "2.0.12",
+  "version": "2.6.0",
   "description": "Scriveno constraint system: work types, command availability, exports, and dependencies. Every command checks this file at runtime.",
   "_notes": {
     "sacred_keys": "Sacred subcommands live at commands/scr/sacred/<name>.md and run as /scr:sacred:<name>. Their CONSTRAINTS keys use the sacred:<name> form so /scr:help can render the runnable slash-command path directly. The sacred-numbering-format entry is a separate flat command (commands/scr/sacred-numbering-format.md) that surfaces the active tradition's numbering format. It used to be named sacred-verse-numbering, which collided with sacred:verse-numbering at install time -- both flattened to scr-sacred-verse-numbering. Renamed in v1.6.x; the installer now refuses to install when two sources share a flat skill name."
   },
   "command_intents": {
     "start": [
+      "first-run",
       "new-work",
       "demo",
       "import",
@@ -31,6 +32,7 @@
       "beta-reader"
     ],
     "navigate": [
+      "first-run",
       "next",
       "progress",
       "manuscript-stats",
@@ -1752,6 +1754,13 @@
       ],
       "description": "Auto-detect and run the next workflow step"
     },
+    "first-run": {
+      "category": "navigation",
+      "available": [
+        "all"
+      ],
+      "description": "Guided first-run path through proof, demo, runtime checks, and starter choices"
+    },
     "do": {
       "category": "navigation",
       "available": [
@@ -2331,6 +2340,7 @@
     },
     "beta-reader": {
       "category": "review",
+      "description": "Simulate a beta reader's experience of the manuscript using a fresh-context reader persona (same model, not a second or external AI).",
       "available": [
         "all"
       ],

package/data/export-templates/scriveno-book.typst

@@ -13,10 +13,10 @@
 #let margin-bottom = $if(margin-bottom)$$margin-bottom$$else$0.75in$endif$
 
 // Text direction: parameterized for RTL compatibility (Phase 7)
-#let text-dir = $if(text-direction)$$text-direction$$else$ltr$endif$
+#let text-dir = $if(dir)$$dir$$else$ltr$endif$
 
 // Language code for CJK detection
-#let lang-code = $if(language)$"$language$"$else$"en"$endif$
+#let lang-code = $if(lang)$"$lang$"$else$"en"$endif$
 
 // CJK detection helper
 #let is-cjk = lang-code in ("zh", "ja", "ko")

package/data/export-templates/scriveno-chapbook.typst

@@ -16,7 +16,7 @@
 #let margin-outside = $if(margin-outside)$$margin-outside$$else$0.625in$endif$
 
 // Text direction
-#let text-dir = $if(text-direction)$$text-direction$$else$ltr$endif$
+#let text-dir = $if(dir)$$dir$$else$ltr$endif$
 
 // Font configuration -- chapbooks default to a clean readable serif
 #let body-font = $if(mainfont)$"$mainfont$"$else$"Libertinus Serif"$endif$

package/data/export-templates/scriveno-picturebook.typst

@@ -20,6 +20,13 @@
 // Override with -V margin-top= etc. if custom margins are needed
 #let margin-all = $if(margin-top)$$margin-top$$else$0.375in$endif$
 
+// Text direction: parameterized for RTL compatibility (set via --metadata dir=rtl).
+// Margins are symmetric and body text is centered, so only the base text
+// direction needs to flip for right-to-left scripts.
+#let text-dir = $if(dir)$$dir$$else$ltr$endif$
+#let is-rtl = text-dir == rtl
+#let lang-code = $if(lang)$"$lang$"$else$"en"$endif$
+
 // Metadata
 #let book-title  = $if(title)$"$title$"$else$"Untitled"$endif$
 #let book-author = $if(author)$"$for(author)$$it.name$$sep$, $endfor$"$else$""$endif$
@@ -46,6 +53,8 @@
 #set text(
   font: $if(mainfont)$"$mainfont$"$else$"Helvetica"$endif$,
   size: $if(fontsize)$$fontsize$$else$16pt$endif$,
+  dir: text-dir,
+  lang: lang-code,
   fallback: true,
 )
 

package/data/export-templates/scriveno-stageplay.typst

@@ -17,6 +17,13 @@
 #let margin-top    = $if(margin-top)$$margin-top$$else$1in$endif$
 #let margin-bottom = $if(margin-bottom)$$margin-bottom$$else$1in$endif$
 
+// Text direction: parameterized for RTL compatibility (set via --metadata dir=rtl).
+// For right-to-left scripts the wider binding margin moves to the right edge and
+// the page number flips to the top-left.
+#let text-dir = $if(dir)$$dir$$else$ltr$endif$
+#let is-rtl = text-dir == rtl
+#let lang-code = $if(lang)$"$lang$"$else$"en"$endif$
+
 // Metadata
 #let play-title  = $if(title)$"$title$"$else$"Untitled"$endif$
 #let play-author = $if(author)$"$for(author)$$it.name$$sep$, $endfor$"$else$""$endif$
@@ -30,16 +37,17 @@
   width: page-width,
   height: page-height,
   margin: (
-    left:   margin-left,
-    right:  margin-right,
+    // The 1.5in binding margin sits on the left for LTR and flips to the right for RTL.
+    left:   if is-rtl { margin-right } else { margin-left },
+    right:  if is-rtl { margin-left } else { margin-right },
     top:    margin-top,
     bottom: margin-bottom,
   ),
-  // Page numbering: top-right, industry standard for scripts
+  // Page numbering: top-right for LTR scripts, top-left for RTL
   header: context {
     let page-num = counter(page).get().first()
     if page-num > 1 {
-      align(right, text(size: 10pt)[#str(page-num).])
+      align(if is-rtl { left } else { right }, text(size: 10pt)[#str(page-num).])
     }
   },
 )
@@ -48,6 +56,8 @@
 #set text(
   font: $if(mainfont)$"$mainfont$"$else$"Courier New"$endif$,
   size: $if(fontsize)$$fontsize$$else$12pt$endif$,
+  dir: text-dir,
+  lang: lang-code,
   fallback: true,
 )
 

package/data/proof/first-run/README.md

@@ -0,0 +1,96 @@
+# First-Run Proof
+
+This bundle is the committed proof artifact for Scriveno's first 10 minutes. It pairs the executable `/scr:first-run` command with the terminal-level checks and demo commands a new writer can run.
+
+## What It Proves
+
+- Scriveno has a runtime command for first-run orientation, not only a documentation page.
+- The first-run path stays small: check surfaces, create the demo, inspect proof files, draft unit 5, review unit 5.
+- The command shapes are explicit for Claude Code, standard slash-command runtimes, and Codex.
+- The demo path uses shipped files in `data/demo/.manuscript/`.
+
+## Transcript: First-Run Guide
+
+```text
+> scriveno first-run --project .
+Scriveno first-run guide
+Project: .
+Current recommendation: /scr:new-work
+
+Runtime command shapes:
+- Claude Code: /scr-first-run, /scr-demo, /scr-next
+- Standard slash-command runtimes: /scr:first-run, /scr:demo, /scr:next
+- Codex: $scr-first-run, $scr-demo, $scr-next
+
+Recommended first path:
+1. /scr:demo
+2. cd scriveno-demo
+3. /scr:next
+4. /scr:draft 5
+5. /scr:editor-review 5
+
+Proof artifacts:
+- docs/quick-proof.md
+- docs/starter-sets.md
+- data/proof/watchmaker-flow/README.md
+- data/proof/voice-dna/README.md
+- data/proof/runtime-parity/README.md
+```
+
+## Transcript: Runtime Smoke
+
+```text
+> scriveno smoke --json
+{
+  "ok": true,
+  "expectedCommands": 113,
+  "expectedAgents": [
+    "continuity-checker",
+    "drafter",
+    "plan-checker",
+    "researcher",
+    "translator",
+    "voice-checker"
+  ],
+  "runtimes": [
+    { "runtime": "claude-code", "ok": true },
+    { "runtime": "codex", "ok": true },
+    { "runtime": "cursor", "ok": true },
+    { "runtime": "gemini-cli", "ok": true },
+    { "runtime": "opencode", "ok": true },
+    { "runtime": "copilot", "ok": true },
+    { "runtime": "windsurf", "ok": true },
+    { "runtime": "antigravity", "ok": true },
+    { "runtime": "manus", "ok": true },
+    { "runtime": "perplexity-desktop", "ok": true },
+    { "runtime": "generic", "ok": true }
+  ]
+}
+```
+
+## Transcript: Demo Flow
+
+```text
+> /scr:demo
+Demo project created at ./scriveno-demo/
+
+> cd scriveno-demo
+
+> /scr:next
+Unit 5 has a plan but no draft yet, so /scr:draft 5 is the next best move.
+
+> /scr:draft 5
+Loaded STYLE-GUIDE.md and .manuscript/plans/5-the-reunion-PLAN.md.
+Drafted unit 5 in the established watchmaker voice.
+
+> /scr:editor-review 5
+Reviewed unit 5 for voice, continuity, emotional payoff, and revision needs.
+```
+
+## Related Files
+
+- [docs/quick-proof.md](../../../docs/quick-proof.md)
+- [docs/starter-sets.md](../../../docs/starter-sets.md)
+- [data/demo/.manuscript/plans/5-the-reunion-PLAN.md](../../demo/.manuscript/plans/5-the-reunion-PLAN.md)
+- [data/proof/watchmaker-flow/README.md](../watchmaker-flow/README.md)
+- [data/proof/voice-dna/README.md](../voice-dna/README.md)

package/data/proof/runtime-parity/README.md

@@ -0,0 +1,48 @@
+# Runtime Parity Evidence
+
+This bundle records what Scriveno can prove about runtime support today and what still requires host-runtime testing.
+
+## Verified In The Repo
+
+- The installer has named targets for Claude Code, Cursor, Gemini CLI, Codex, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus Desktop, Perplexity Desktop, and the generic skill fallback.
+- `scriveno smoke --json` checks installed command counts, agent prompt availability, Codex metadata, guided Perplexity assets, and shared engine availability.
+- `scriveno agents --json` distinguishes prompt fallback readiness, Codex metadata readiness, guided setup, and bundled skill prompts.
+- `scriveno routes --json` verifies route lanes and command graph shape from the live constraints file.
+- Regression tests cover install surface shape, Codex metadata, Claude flat command mapping, skill bundles, and public audit commands.
+
+## Runtime Surface Expectations
+
+| Runtime | What is verified locally | Native host behavior claim |
+|---------|--------------------------|----------------------------|
+| Claude Code | Flat `/scr-*` commands plus agent prompts install | Host-supported when Claude Code exposes agents |
+| Codex | `$scr-*` skills, mirrored commands, prompts, and `.toml` metadata install | Host-supported when Codex exposes agent roles |
+| Cursor | Nested `/scr:*` commands plus agent prompts install | Host-supported when Cursor exposes agents |
+| Gemini CLI | Nested `/scr:*` commands plus agent prompts install | Host-supported when Gemini CLI exposes agents |
+| OpenCode | Nested `/scr:*` commands plus agent prompts install | Host-supported when OpenCode exposes agents |
+| GitHub Copilot | Nested `/scr:*` commands plus agent prompts install | Host-supported when Copilot exposes agents |
+| Windsurf | Nested `/scr:*` commands plus agent prompts install | Host-supported when Windsurf exposes agents |
+| Antigravity | Nested `/scr:*` commands plus agent prompts install | Host-supported when Antigravity exposes agents |
+| Manus Desktop | Skill bundle with commands and agent prompts installs | Host-supported when Manus exposes skill agents |
+| Perplexity Desktop | Guided local-MCP setup assets install | Native command and agent spawning not assumed |
+| Generic | SKILL.md bundle with commands and agent prompts installs | Native spawning not assumed |
+
+## Remaining Host-In-The-Loop Gap
+
+Scriveno still does not claim full host-runtime parity. The missing proof is a recorded run inside each actual host UI or agent process showing that the host invokes the installed command and agent surfaces exactly as expected.
+
+That gap is now narrower: install surfaces, metadata, command counts, agent prompts, shared audit commands, and proof artifacts are all checked. This document separates install-surface proof and host-runtime parity proof so Scriveno can be precise about what is verified. The remaining work is external host execution evidence, not package-surface wiring.
+
+## Suggested Host Parity Script
+
+For each host that supports local commands:
+
+```text
+1. Install scriveno@latest.
+2. Run the host-native first-run command.
+3. Run the host-native demo command.
+4. Run the host-native next command inside scriveno-demo.
+5. Confirm the host can route to draft unit 5.
+6. Save a short transcript or screenshot under data/proof/runtime-parity/<runtime>/.
+```
+
+Use the command shape from [docs/runtime-support.md](../../../docs/runtime-support.md).

package/docs/architecture.md

@@ -164,7 +164,8 @@ scriveno/
       scriveno-book.typst     Book interior PDF
       scriveno-epub.css       EPUB styling
       scriveno-academic.latex Academic paper formatting
-    templates/
+    proof/                 Committed proof bundles (voice-dna, runtime-parity)
+  templates/               Per-project starting content (repo root, sibling of data/)
     config.json            Per-project configuration template
     WORK.md                Work overview template
     OUTLINE.md             Structural outline template
@@ -199,6 +200,7 @@ scriveno/
     install.js             Multi-platform installer (Node.js)
   docs/
     proof-artifacts.md     Canonical proof layer and artifact index
+    quick-proof.md         Executable first-run proof path and command shapes
     getting-started.md     Install to first draft in 10 minutes
     command-reference.md   Full command listing with usage
     work-types.md          50 work types and how they adapt Scriveno
@@ -372,6 +374,7 @@ The same engine now exposes:
 - **Agent availability**: `agents` verifies prompt fallback readiness for non-Codex runtimes and metadata readiness for Codex.
 - **Runtime smoke**: `smoke` checks installed command, skill, guide, agent, metadata, and shared-engine surfaces.
 - **Route graph audit**: `routes` derives a command graph from constraints, command intents, dependencies, and automation lanes.
+- **First-run guide**: `first-run` prints the guided proof path, runtime command shapes, proof artifacts, demo sequence, and next commands.
 
 ### Installation modes
 
@@ -420,7 +423,7 @@ The voice-checker agent (`agents/voice-checker.md`) compares drafted prose again
 - Specific issues organized by category (structural voice, lexical voice, character voice, AI-slop indicators)
 - Severity ratings (drift vs critical violation)
 
-The voice-checker is invoked after every drafted unit. If drift exceeds the configured threshold (default: 0.3 in `config.json`), the writer is offered a re-draft.
+The voice-checker is invoked after every drafted unit and returns an Overall score (0-100). Normalized drift is `drift = (100 - score) / 100`, so the default `config.json` threshold of 0.3 means the writer is offered a re-draft when the voice score falls below 70. See the "Normalized drift" section of `agents/voice-checker.md` for the single definition callers share.
 
 ### Calibration
 
@@ -434,7 +437,7 @@ Scriveno's `package.json` has no runtime dependencies. The installer is pure Nod
 
 ### Plan is canonical
 
-The product plan is the source of truth. If a command file contradicts the plan, the command file is wrong. This ensures consistency across 112 commands and prevents drift as multiple contributors work on the system.
+The product plan is the source of truth. If a command file contradicts the plan, the command file is wrong. This ensures consistency across 113 commands and prevents drift as multiple contributors work on the system.
 
 ### Backward compatibility
 

package/docs/command-reference.md

@@ -1,6 +1,6 @@
 # Command Reference
 
-Scriveno has **112 commands** organized into **14 categories**. Commands adapt automatically to your work type -- for example, `/scr:draft` talks about drafting a surah for Quranic commentary, an act for screenplays, and a section for research papers.
+Scriveno has **113 commands** organized into **14 categories**. Commands adapt automatically to your work type -- for example, `/scr:draft` talks about drafting a surah for Quranic commentary, an act for screenplays, and a section for research papers.
 
 Commands marked with **adaptive terminology** change how Scriveno talks about your work type's `command_unit` in `.manuscript/config.json`, while keeping the runnable command id stable. Commands marked with **group adaptation** have different labels for specific work type groups (academic, sacred, etc.).
 
@@ -227,9 +227,25 @@ Start a series bible for a trilogy. Track characters, world details, and timelin
 
 Commands for finding your way through the workflow and understanding your manuscript.
 
+### `/scr:first-run`
+
+**Description:** Run the guided first-run path through install checks, demo proof, starter choices, and next commands.
+
+**Usage:** `/scr:first-run [--proof] [--runtime <runtime>]`
+
+**Prerequisites:** None
+
+**Example:**
+```
+/scr:first-run
+```
+Show the proof-first path, runtime command shapes, demo sequence, proof artifacts, and the first safe command to try.
+
+---
+
 ### `/scr:next`
 
-**Description:** Auto-detect what to do next in your workflow and recommend the best path. The one command a writer can always use.
+**Description:** Auto-detect what to do next in your workflow and run it. The one command a writer can always use.
 
 **Usage:** `/scr:next`
 
@@ -261,7 +277,7 @@ Scriveno maps your intent to the right command and runs it.
 
 ### `/scr:help`
 
-**Description:** Show Scriveno commands grouped by inferred writer intent, filtered to what's relevant for your current work type and progress.
+**Description:** Show Scriveno commands grouped by workflow stage, filtered to what's relevant for your current work type and progress.
 
 **Usage:** `/scr:help [category or search term]`
 
@@ -334,7 +350,7 @@ Import an existing Word document and split it into chapters, scenes, and context
 
 **Description:** Spawn parallel analysis agents to understand an existing manuscript's voice, structure, characters, and themes.
 
-**Usage:** `/scr:map-manuscript`
+**Usage:** `/scr:map-manuscript [area]`
 
 **Prerequisites:** None
 
@@ -548,7 +564,7 @@ Visualize your novel's structure mapped to the hero's journey.
 
 **Description:** Generate a chronological event timeline from the outline.
 
-**Usage:** `/scr:timeline`
+**Usage:** `/scr:timeline [--story-order] [--chronological]`
 
 **Prerequisites:** OUTLINE.md must exist
 
@@ -568,7 +584,7 @@ See events in chronological order, even if your narrative is non-linear.
 
 **Description:** Track thematic threads across the work with auto-detection suggestions.
 
-**Usage:** `/scr:theme-tracker`
+**Usage:** `/scr:theme-tracker [--detect]`
 
 **Prerequisites:** THEMES.md must exist
 
@@ -764,7 +780,7 @@ Commands for creating and managing characters, relationships, and world-building
 
 **Description:** Build a complete character profile through guided interactive interview.
 
-**Usage:** `/scr:new-character`
+**Usage:** `/scr:new-character <name>`
 
 **Prerequisites:** WORK.md must exist
 
@@ -946,7 +962,7 @@ Scriveno drafts a sample passage using your voice profile. If it doesn't sound r
 
 **Description:** Perform a line-level prose quality pass with inline annotations.
 
-**Usage:** `/scr:line-edit`
+**Usage:** `/scr:line-edit [N]`
 
 **Prerequisites:** Draft must exist
 
@@ -964,7 +980,7 @@ Scriveno reads your prose line by line, flagging weak verbs, passive voice, redu
 
 **Description:** Perform a correctness pass for grammar, spelling, punctuation, and consistency.
 
-**Usage:** `/scr:copy-edit`
+**Usage:** `/scr:copy-edit [N]`
 
 **Prerequisites:** Draft must exist
 
@@ -982,7 +998,7 @@ Catch typos, grammar issues, and consistency problems (character name spellings,
 
 **Description:** Chain line-edit, copy-edit, and voice-check for comprehensive prose polish.
 
-**Usage:** `/scr:polish`
+**Usage:** `/scr:polish [N]`
 
 **Prerequisites:** Draft and STYLE-GUIDE.md must exist
 
@@ -1000,7 +1016,7 @@ Run all three quality passes in sequence. The comprehensive final polish before
 
 **Description:** Write a scene, passage, or chapter outside the full planning workflow.
 
-**Usage:** `/scr:quick-write`
+**Usage:** `/scr:quick-write [--discuss] [--research] [--full]`
 
 **Prerequisites:** None
 
@@ -1022,7 +1038,7 @@ Commands for reviewing your manuscript from different angles -- continuity, voic
 
 **Description:** Automated continuity verification to scan for narrative contradictions across the manuscript.
 
-**Usage:** `/scr:continuity-check`
+**Usage:** `/scr:continuity-check [N]`
 
 **Prerequisites:** Draft must exist
 
@@ -1043,7 +1059,7 @@ Find contradictions: "In Chapter 3 Maria has brown eyes, but in Chapter 7 they'r
 
 **Description:** Compare drafted prose against STYLE-GUIDE.md to detect voice drift.
 
-**Usage:** `/scr:voice-check`
+**Usage:** `/scr:voice-check [N]`
 
 **Prerequisites:** Draft and STYLE-GUIDE.md must exist
 
@@ -1064,7 +1080,7 @@ Detect where your drafted prose drifts from your established voice profile.
 
 **Description:** Flag potential sensitivity issues with context, suggest alternatives, and note intentional craft.
 
-**Usage:** `/scr:sensitivity-review`
+**Usage:** `/scr:sensitivity-review [N]`
 
 **Prerequisites:** Draft must exist
 
@@ -1086,7 +1102,7 @@ Flag content that could be unintentionally harmful, with context-aware suggestio
 
 **Description:** Generate a structure-aware pacing report analyzing scene tempo and narrative flow.
 
-**Usage:** `/scr:pacing-analysis`
+**Usage:** `/scr:pacing-analysis [N]`
 
 **Prerequisites:** Draft must exist
 
@@ -1104,7 +1120,7 @@ See where your story drags or rushes. Scriveno maps scene length, tension, and t
 
 **Description:** Audit dialogue for character voice differentiation, attribution clarity, and talking-head detection.
 
-**Usage:** `/scr:dialogue-audit`
+**Usage:** `/scr:dialogue-audit [N]`
 
 **Prerequisites:** Draft must exist with dialogue
 
@@ -1123,9 +1139,9 @@ Check that each character sounds distinct, dialogue tags are clear, and scenes a
 
 ### `/scr:beta-reader`
 
-**Description:** Simulate a beta reader's experience of the manuscript with cross-AI peer review.
+**Description:** Simulate a beta reader's experience of the manuscript using a fresh-context reader persona (same model, not a second or external AI).
 
-**Usage:** `/scr:beta-reader`
+**Usage:** `/scr:beta-reader [N] [--focus <area>]`
 
 **Prerequisites:** Draft must exist
 
@@ -1147,7 +1163,7 @@ Get a simulated reader's reaction: what hooked them, where they got confused, wh
 
 **Description:** Scan drafted prose for AI-generated patterns and unintentional similarity to published works.
 
-**Usage:** `/scr:originality-check`
+**Usage:** `/scr:originality-check [N]`
 
 **Prerequisites:** Draft must exist
 
@@ -1243,7 +1259,7 @@ Get three blurb variations: punchy (Amazon listing), standard (back cover), exte
 
 **Description:** Generate plot synopsis at specified length for query and submission packages.
 
-**Usage:** `/scr:synopsis`
+**Usage:** `/scr:synopsis [--length <1p|2p|5p>]`
 
 **Prerequisites:** Complete draft must exist
 
@@ -1297,7 +1313,7 @@ Generate a full book proposal: overview, market analysis, chapter summaries, aut
 
 **Description:** Generate reading group discussion questions exploring themes, characters, and craft.
 
-**Usage:** `/scr:discussion-questions`
+**Usage:** `/scr:discussion-questions [--count <N>]`
 
 **Prerequisites:** Complete draft must exist
 
@@ -1462,7 +1478,7 @@ Build a poetry-submission DOCX for journal or contest submission using the poetr
 
 **Description:** Run full publishing pipeline unattended with quality gate (voice-check + continuity-check).
 
-**Usage:** `/scr:autopilot-publish --preset <preset>`
+**Usage:** `/scr:autopilot-publish --preset <preset> [--front-level <minimum|balanced|maximum|skip>] [--back-level <minimum|balanced|maximum|skip>]`
 
 **Prerequisites:** Complete draft must exist
 
@@ -1497,7 +1513,7 @@ Commands for generating cover art, scene illustrations, character references, ma
 - `--trim <size>` -- Preferred trim shorthand for prompt framing
 - `--kdp <trim_size>` -- Legacy alias for `--trim`
 - `--series` -- Generate series-consistent cover
-- `--prompt-only` -- Generate prompts without calling image API
+- `--prompt-only` -- Generate prompts without packaging reminders
 - `--element` -- Generate specific cover element
 
 **Example:**