scriveno 2.0.12 → 2.6.0

package/README.md

@@ -2,13 +2,14 @@
 
 [![CI](https://github.com/aihxp/scriveno/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/scriveno/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-2.0.12-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.6.0-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/scriveno.svg)](https://www.npmjs.com/package/scriveno)
 [![Downloads](https://img.shields.io/npm/dm/scriveno.svg)](https://www.npmjs.com/package/scriveno)
 [![Status CLI](https://img.shields.io/badge/status%20CLI-scriveno%20status-blue)](docs/runtime-support.md#shared-auto-invoke-engine)
 [![Route Intelligence](https://img.shields.io/badge/route%20intelligence-agent%20lanes-blue)](docs/auto-invoke-policy.md)
 [![Runtime Smoke](https://img.shields.io/badge/runtime%20smoke-install%20checks-blue)](docs/runtime-support.md#runtime-smoke-and-agent-checks)
 [![Safe Apply](https://img.shields.io/badge/safe%20apply-visible%20gates-blue)](docs/auto-invoke-policy.md#safe-apply-and-audit-commands)
+[![First Run](https://img.shields.io/badge/first%20run-executable%20proof-blue)](docs/quick-proof.md)
 [![Quick Proof](https://img.shields.io/badge/quick%20proof-10%20minute%20path-blue)](docs/quick-proof.md)
 [![Starter Sets](https://img.shields.io/badge/starter%20sets-goal%20paths-blue)](docs/starter-sets.md)
 
@@ -36,7 +37,7 @@ scriveno sync --check
 
 Scriveno is a command system that turns your AI coding agent into a voice-preserving writing studio. It supports 50 work types -- novels, screenplays, research papers, technical guides, runbooks, scripture commentaries, comics, memoirs -- each with its own adaptive vocabulary and toolset.
 
-The wedge comes first: Scriveno profiles the writer, loads that voice into every drafting step, and keeps each unit on fresh context so the prose stays specific to the project. From there, it expands into 112 writing commands covering the rest of the pipeline:
+The wedge comes first: Scriveno profiles the writer, loads that voice into every drafting step, and keeps each unit on fresh context so the prose stays specific to the project. From there, it expands into 113 writing commands covering the rest of the pipeline:
 
 - **Create** -- Set up a project with tailored context files. Progressive onboarding, never overwhelming.
 - **Write** -- Discuss, plan, draft, and revise one unit at a time. The drafter agent loads your Voice DNA and writes in *your* voice, not generic AI prose.
@@ -56,16 +57,19 @@ Everything adapts to your work type. A novel uses `/scr:draft` for chapters. A s
 npx scriveno@latest
 
 # In Claude Code:
+/scr-first-run     # Run the guided proof path first
 /scr-new-work        # Start a fresh project
 /scr-demo            # Explore a pre-built sample first
 /scr-next            # The universal "what should I do now" command
 /scr-help            # See what's available for your work type
 
 # Other slash-command runtimes currently keep /scr:*:
+/scr:first-run
 /scr:new-work
 /scr:next
 
 # In Codex, use the generated $scr-* skills:
+$scr-first-run
 $scr-new-work
 $scr-demo
 $scr-next
@@ -137,6 +141,8 @@ For sacred and historical texts, Voice DNA is supplemented by 10 sacred voice re
 
 **Interactive:** interactive fiction, game narrative
 
+**Speech:** speech
+
 **Sacred & historical:** scripture (Biblical, Quranic, Torah, Vedic, Buddhist, generic), commentary/exegesis, devotional, liturgical text, historical chronicle, historical account, mythological collection, religious epic, sermon, homiletic collection
 
 Each work type has its own structural hierarchy and **industry-standard word count and page range guidance** -- a novel targets 70,000-100,000 words across 20-35 chapters, a screenplay targets 90-120 pages across 3-5 acts. These ranges guide outlining, progress tracking, and drafter pacing. The runnable command ids stay stable, while Scriveno adapts the wording around them -- a Torah commentary still runs `/scr:plan 3`, but frames that work as planning Parashah 3.
@@ -195,7 +201,7 @@ Scriveno is built on five principles:
 - [Quick Proof](docs/quick-proof.md) -- 10-minute proof-first route through install checks, the demo, and the next draft
 - [Starter Sets](docs/starter-sets.md) -- Small command paths for drafting, polishing, publishing, translation, sacred commentary, and repair
 - [Getting Started](docs/getting-started.md) -- Install to first draft in 10 minutes
-- [Command Reference](docs/command-reference.md) -- All 112 commands with usage, flags, and examples
+- [Command Reference](docs/command-reference.md) -- All 113 commands with usage, flags, and examples
 - [Work Types Guide](docs/work-types.md) -- How 50 work types adapt Scriveno's vocabulary
 - [Voice DNA Guide](docs/voice-dna.md) -- The 15+ dimension voice profiling system
 - [Creative Context](docs/creative-context.md) -- Writer-native context routing, craft notes, and core-loop memory
@@ -240,11 +246,11 @@ Scriveno currently ships installer targets for these AI tooling environments:
 
 ## Status
 
-**Version:** 2.0.12
+**Version:** 2.6.0
 
-Scriveno's core command surface is stable across 112 commands, 50 work types, and 11 installer targets. The current repo baseline includes shipped planning milestones through `v2.0 Publishing Cover Packaging`, plus the creative-context, record-store, branching-next, runtime-sync, adaptive concierge, human-first writing-safeguard, authenticity-diagnostic, domain-grilling, installer-marker cleanup, cross-runtime agent metadata, visible automation status, the shared `scriveno status --project .` auto-invoke engine, route-intelligence lanes, safe apply reporting, runtime smoke checks, agent availability checks, route graph audits, the full audit repair pass through `2.0.11`, and the first-run proof surface in `2.0.12`. See [Quick Proof](docs/quick-proof.md) for the fastest proof path, [Shipped Assets](docs/shipped-assets.md) for the canonical asset inventory, and [Runtime Support](docs/runtime-support.md) for the runtime compatibility matrix.
+Scriveno's core command surface is stable across 113 commands, 50 work types, and 11 installer targets. The current repo baseline includes shipped planning milestones through `v2.0 Publishing Cover Packaging`, plus the creative-context, record-store, branching-next, runtime-sync, adaptive concierge, human-first writing-safeguard, authenticity-diagnostic, domain-grilling, installer-marker cleanup, cross-runtime agent metadata, visible automation status, the shared `scriveno status --project .` auto-invoke engine, route-intelligence lanes, safe apply reporting, runtime smoke checks, agent availability checks, route graph audits, the full audit repair pass through `2.0.11`, the first-run proof surface in `2.5.0`, and the executable `/scr:first-run` path. See [Quick Proof](docs/quick-proof.md) for the fastest proof path, [Shipped Assets](docs/shipped-assets.md) for the canonical asset inventory, and [Runtime Support](docs/runtime-support.md) for the runtime compatibility matrix.
 
-Version `2.0.12` publishes Scriveno under the package name `scriveno`, so the current install command is `npx scriveno@latest`. The older `scriveno-cli` package name is historical and was unpublished during the rename, so npm cannot attach a deprecation notice to it while it has no active registry record. The older `scriven-cli` package remains on npm only as a deprecated legacy name that points users to `scriveno`. Do not treat either legacy package name as active unless a deliberate compatibility shim is republished. See [CHANGELOG](CHANGELOG.md) for the full list and [docs/release-notes.md](docs/release-notes.md) for the public-facing summary.
+Version `2.6.0` publishes Scriveno under the package name `scriveno`, so the current install command is `npx scriveno@latest`. The older `scriveno-cli` package name is historical and was unpublished during the rename, so npm cannot attach a deprecation notice to it while it has no active registry record. The older `scriven-cli` package remains on npm only as a deprecated legacy name that points users to `scriveno`. Do not treat either legacy package name as active unless a deliberate compatibility shim is republished. See [CHANGELOG](CHANGELOG.md) for the full list and [docs/release-notes.md](docs/release-notes.md) for the public-facing summary.
 
 Package history is tracked in [CHANGELOG.md](CHANGELOG.md), and the public-facing summary for this release is in [docs/release-notes.md](docs/release-notes.md).
 

package/agents/voice-checker.md

@@ -147,6 +147,16 @@ Map the band to the existing tiers:
 - **60-74, Mixed signals (notable) / leaning AI:** Fail. Noticeable drift. Offer to re-draft problem sections.
 - **Below 60, Reads AI-generated:** Severe. Clustered dead-giveaways, uniform rhythm, or chat-artifact contamination. Do not proceed. Recommend re-drafting with an updated STYLE-GUIDE.md or running `/scr:voice-test` to recalibrate.
 
+### Normalized drift (for callers that need a 0-1 figure)
+
+Some callers -- `/scr:draft`, `/scr:autopilot`, and the `voice.drift_threshold` config knob -- need drift on a 0-1 scale rather than this 0-100 score. Convert with:
+
+```
+drift = (100 - score) / 100
+```
+
+So a score of 100 is 0.00 drift, 90 is 0.10, 70 is 0.30, 60 is 0.40. The default `drift_threshold` of 0.3 therefore means "pause or offer a re-draft when the voice score falls below 70" -- the FAIL band and worse. This is the single definition of drift; callers reference it rather than inventing their own scale.
+
 Before finalizing a low score, re-read the strongest human markers you found and ask whether the band is honestly supported. Scoring genuine careful human prose low because it is formal or clean is this check's worst failure.
 
 ## Tone

package/bin/install.js

@@ -821,6 +821,7 @@ function printHelp() {
   console.log(BANNER);
   console.log(`Usage:
   scriveno
+  scriveno first-run --project .
   scriveno status --project .
   scriveno status . --json
   scriveno status --project . --apply-safe
@@ -843,6 +844,7 @@ Options:
   --version           Show the Scriveno package version
 
 Status options:
+  first-run           Print the guided first-run path and proof checklist
   status              Inspect a project and recommend the next command
   --project <path>    Project root to inspect (default: current directory)
   --trigger <name>    Status trigger label (default: scriveno status)
@@ -878,8 +880,11 @@ function parseArgs(argv) {
     syncCheck: false,
   };
 
-  if (argv[0] === 'status') {
-    options.command = 'status';
+  if (argv[0] === 'status' || argv[0] === 'first-run') {
+    options.command = argv[0];
+    if (argv[0] === 'first-run') {
+      options.statusTrigger = 'scriveno first-run';
+    }
     for (let i = 1; i < argv.length; i++) {
       const arg = argv[i];
       if (arg === '--help' || arg === '-h') {
@@ -1011,6 +1016,82 @@ function runStatus({ projectRoot, trigger, json, applySafe }) {
   return safeApply ? { analysis, safeApply } : analysis;
 }
 
+function buildFirstRunGuide({ projectRoot }) {
+  const analysis = autoInvokeEngine.analyzeProject(projectRoot);
+  const smoke = autoInvokeEngine.inspectRuntimeSmoke();
+  const routes = autoInvokeEngine.buildRouteGraph();
+  return {
+    projectRoot,
+    recommendation: analysis.recommendation,
+    commandShapes: {
+      claudeCode: ['/scr-first-run', '/scr-demo', '/scr-next'],
+      standardSlash: ['/scr:first-run', '/scr:demo', '/scr:next'],
+      codex: ['$scr-first-run', '$scr-demo', '$scr-next'],
+      guided: ['Follow the generated local-MCP setup notes'],
+    },
+    firstPath: [
+      '/scr:demo',
+      'cd scriveno-demo',
+      '/scr:next',
+      '/scr:draft 5',
+      '/scr:editor-review 5',
+    ],
+    proofArtifacts: [
+      'docs/quick-proof.md',
+      'docs/starter-sets.md',
+      'data/proof/first-run/README.md',
+      'data/proof/runtime-parity/README.md',
+      'data/proof/watchmaker-flow/README.md',
+      'data/proof/voice-dna/README.md',
+    ],
+    checks: {
+      smokeOk: smoke.ok,
+      commandCount: routes.commandCount,
+      expectedAgents: smoke.expectedAgents,
+    },
+  };
+}
+
+function formatFirstRunGuide(guide) {
+  return [
+    'Scriveno first-run guide',
+    `Project: ${guide.projectRoot}`,
+    `Current recommendation: ${guide.recommendation.command}`,
+    '',
+    'Runtime command shapes:',
+    `- Claude Code: ${guide.commandShapes.claudeCode.join(', ')}`,
+    `- Standard slash-command runtimes: ${guide.commandShapes.standardSlash.join(', ')}`,
+    `- Codex: ${guide.commandShapes.codex.join(', ')}`,
+    `- Guided targets: ${guide.commandShapes.guided.join(', ')}`,
+    '',
+    'Recommended first path:',
+    ...guide.firstPath.map((step, index) => `${index + 1}. ${step}`),
+    '',
+    'Proof artifacts:',
+    ...guide.proofArtifacts.map((artifact) => `- ${artifact}`),
+    '',
+    'Checks:',
+    `- runtime smoke: ${guide.checks.smokeOk ? 'ok' : 'needs install refresh'}`,
+    `- command count: ${guide.checks.commandCount}`,
+    `- expected agents: ${guide.checks.expectedAgents.join(', ')}`,
+    '',
+    'Next commands:',
+    '- /scr:demo: Create the isolated watchmaker demo project.',
+    '- /scr:next: Let Scriveno inspect the current project state.',
+    '- /scr:new-work: Start a real project instead of using the demo.',
+  ].join('\n');
+}
+
+function runFirstRun({ projectRoot, json }) {
+  const guide = buildFirstRunGuide({ projectRoot });
+  if (json) {
+    console.log(JSON.stringify(guide, null, 2));
+  } else {
+    console.log(formatFirstRunGuide(guide));
+  }
+  return guide;
+}
+
 function runSyncCheck({ projectRoot, json }) {
   const analysis = autoInvokeEngine.analyzeProject(projectRoot);
   const safeApply = autoInvokeEngine.collectSafeApplyActions(projectRoot, { analysis, trigger: 'scriveno sync --check' });
@@ -1496,6 +1577,14 @@ async function main() {
     return;
   }
 
+  if (parsed.command === 'first-run') {
+    runFirstRun({
+      projectRoot: parsed.statusProjectRoot,
+      json: parsed.statusJson,
+    });
+    return;
+  }
+
   if (parsed.command === 'sync') {
     runSyncCheck({
       projectRoot: parsed.statusProjectRoot,

package/commands/scr/autopilot-publish.md

@@ -78,7 +78,7 @@ Continuity check: 1 warning
 Proceeding with export. Review full reports after completion.
 ```
 
-**Quality gate policy (D-09):** Always proceed to the export pipeline regardless of quality gate results. The quality gate is advisory -- it gives the writer information, not a veto. Even if voice check scores FAIL (below 60) or continuity check finds major contradictions, log the warnings and continue.
+**Quality gate policy (D-09):** The quality gate is advisory and never blocks. Always proceed to the export pipeline, including when the voice check or continuity check finds problems. autopilot-publish is the unattended path: it does not stop to ask the writer and it does not abort the run. The gate exists to make problems visible, not to veto. One case gets extra visibility: when the voice score is below 60 (the voice-checker's "Reads AI-generated / do not proceed" band), flag it prominently in the quality-gate summary, write the full voice-check report to the output directory, and list it as the top issue in the final completion report with an explicit recommendation to re-draft the flagged units before publishing. Still finish the export so the run stays unattended; the writer decides whether to publish the package or re-draft after reading the report.
 
 ---
 

package/commands/scr/autopilot-translate.md

@@ -56,8 +56,8 @@ RTL_LANGUAGES = ["ar", "he", "ur", "fa", "yi", "ps", "sd"]
 CJK_LANGUAGES = ["zh", "ja", "ko"]
 ```
 
-- RTL languages receive `--text-direction rtl` when passed to export commands
-- CJK languages receive appropriate font and spacing flags
+- RTL languages: `/scr:multi-publish` derives text direction from the language code, so no extra flag is needed
+- CJK languages: `/scr:multi-publish` applies CJK font and spacing handling from the language code
 - All other languages default to LTR
 
 Log the detection:
@@ -123,9 +123,8 @@ Log drift annotation counts:
 
 If `--skip-publish` is NOT set:
 - Determine text direction for this language (RTL/LTR/CJK from Step 2)
-- Run `/scr:multi-publish --language {lang}` for all available export formats
-- For RTL languages, pass `--text-direction rtl` to ensure correct PDF and EPUB output
-- For CJK languages, pass `--cjk-mode` to enable CJK-specific line breaking and font handling
+- Run `/scr:multi-publish --languages {lang}` for all available export formats
+- RTL and CJK output is handled automatically: `/scr:multi-publish` sets text direction and CJK line breaking from the language code, so no extra flags are required
 
 If `--skip-publish` IS set:
 - Log: `"[fr] Phase 6/6: Multi-publish skipped (--skip-publish)."`
@@ -209,7 +208,7 @@ Next Steps:
 
 - **NEVER** skip the glossary phase -- term consistency across the manuscript depends on it
 - **NEVER** run cultural adaptation before translation is complete for that language
-- **NEVER** export RTL languages without setting `--text-direction rtl` -- the PDF and EPUB will be unreadable
+- **ALWAYS** confirm the language code is correct before export; `/scr:multi-publish` uses it to set RTL direction and CJK handling, and a wrong code yields unreadable PDF and EPUB
 - **NEVER** continue past a blocking error without logging it -- all errors must appear in the completion summary
 - **NEVER** modify the source manuscript -- translation works on copies in `.manuscript/translation/{lang}/`
 

package/commands/scr/autopilot.md

@@ -88,7 +88,7 @@ The writer trusts the pipeline. Autopilot runs until the entire manuscript is co
 **Pause behavior:** Run until ALL units are complete. Pause ONLY on these conditions:
 
 1. **Continuity contradiction** the agent cannot resolve (e.g., a character is in two places at once, a previously established fact is contradicted)
-2. **Voice drift** exceeding `config.voice.drift_threshold` (default 0.3). After each unit, compare the drafted prose against STYLE-GUIDE.md. If drift exceeds threshold, pause.
+2. **Voice drift** exceeding `config.voice.drift_threshold` (default 0.3). After each unit, run the voice-checker agent against STYLE-GUIDE.md to get an Overall score (0-100). Compute normalized drift as `drift = (100 - score) / 100` (see the "Normalized drift" section of `voice-checker.md`) and pause when `drift` exceeds the threshold -- at the default 0.3 that means a voice score below 70, the voice-checker's FAIL band.
 3. **Plot hole** with no clear resolution path (e.g., a setup with no payoff, a character motivation gap)
 4. **Missing critical information** that prevents drafting (character motivation gap, setting inconsistency, unresolved plot dependency)
 5. **Record drift** against `.manuscript/RECORD.md` that the agent cannot resolve safely (e.g., a promised payoff is contradicted, an open thread is closed without being recorded, or a next-unit obligation is skipped)
@@ -108,7 +108,7 @@ The writer trusts the pipeline. Autopilot runs until the entire manuscript is co
 **On completion:** Show a comprehensive summary:
 - Total units drafted
 - Total word count
-- Voice consistency score across the manuscript
+- Voice consistency: the voice-checker Overall score (0-100), averaged across the units that were voice-checked during the run
 - Open record threads, reader promises, and unresolved next-unit obligations from RECORD.md
 - Any flags or issues encountered during the run
 - List of any quality gate pauses that occurred and how they were resolved
@@ -223,7 +223,7 @@ If the command stops because a prerequisite is missing, suggest the command that
 
 - **NEVER** run without updating STATE.md -- resume depends on accurate state
 - **NEVER** show raw git output in writer mode (when `developer_mode` is `false`)
-- **NEVER** skip the voice comparison after drafting -- even if the voice-check command from Phase 4 is not yet available, use the drafter's built-in self-check (Step 4 in drafter.md)
+- **NEVER** skip the voice comparison after drafting -- run the voice-checker agent against STYLE-GUIDE.md; if the host runtime cannot spawn it, fall back to the drafter's built-in self-check (Step 4 in drafter.md)
 - **NEVER** re-draft a unit that STATE.md shows as already submitted -- submitted means the writer approved it
 - **NEVER** skip stages in the chain (discuss-plan-draft-review-submit) unless the writer explicitly says "skip"
 - **NEVER** continue past a quality gate pause in full-auto without writer input -- the whole point is that these are conditions the pipeline cannot resolve alone

package/commands/scr/beta-reader.md

@@ -1,10 +1,13 @@
 ---
-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.
+argument-hint: "[N] [--focus <area>]"
 ---
 
-# /scr:beta-reader -- Cross-AI Peer Review
+# /scr:beta-reader -- Reader-Perspective Review
 
-Simulate a beta reader's experience of the manuscript.
+Simulate a beta reader's experience of the manuscript using a fresh-context reader persona.
+
+This command simulates an independent reader in a fresh context using the same model, not a second or external AI. Genuine cross-AI review would require an external CLI call that Scriveno does not currently wire.
 
 ## Usage
 ```

package/commands/scr/build-ebook.md

@@ -153,7 +153,7 @@ Apply tradition data to `.manuscript/output/metadata.yaml` (before STEP 3f write
   - `tibetan` script -> `bo`
   - `devanagari` script -> `sa` (Sanskrit)
   - `latin` script -> use the project language from config.json (default `en`)
-- Set `font-family:` to the first entry in the manifest's `font_stack`.
+- Set `mainfont:` to the first entry in the manifest's `font_stack`. (For the EPUB itself the non-Latin font is applied through `scriveno-epub.css`; `mainfont` keeps the metadata key aligned with the print build.)
 
 If `rtl: true` in the manifest, add `--metadata dir=rtl` to the Pandoc invocation in STEP 4.
 

package/commands/scr/build-print.md

@@ -156,7 +156,7 @@ Apply tradition data to `.manuscript/output/metadata.yaml` (before STEP 3f write
   - `tibetan` script -> `bo`
   - `devanagari` script -> `sa` (Sanskrit)
   - `latin` script -> use the project language from config.json (default `en`)
-- Set `font-family:` to the first entry in the manifest's `font_stack`.
+- Set `mainfont:` to the first entry in the manifest's `font_stack`. (`mainfont` is the Pandoc variable the Typst book/chapbook templates read for the body font; `font-family` is not.)
 
 If `rtl: true` in the manifest, add `--metadata dir=rtl` to the Pandoc invocation in STEP 4.
 
@@ -415,7 +415,7 @@ estimated_pages = Math.round(word_count / manifest.trim_sizes[trim].wpp)
 
 Compare against `manifest.max_pages`:
 - For paperback: compare against `manifest.max_pages.paperback`
-- For hardcover: only KDP hardcover applies -- compare against `manifest.max_pages.hardcover` only if `--hardcover` flag is passed (otherwise use paperback limit)
+- For hardcover: the hardcover page limit applies to KDP only. Compare against `manifest.max_pages.hardcover` only if `--hardcover` was passed AND the platform is `kdp` AND the manifest defines `max_pages.hardcover`. For any other platform (for example `ingram`, which defines only `max_pages.paperback`), ignore `--hardcover` for the page-limit check and use `manifest.max_pages.paperback`.
 
 If `estimated_pages` exceeds the limit:
 

package/commands/scr/continuity-check.md

@@ -1,5 +1,6 @@
 ---
 description: Automated continuity verification to scan for narrative contradictions across the manuscript.
+argument-hint: "[N]"
 ---
 
 # /scr:continuity-check -- Scan for Narrative Contradictions

package/commands/scr/copy-edit.md

@@ -1,5 +1,6 @@
 ---
 description: Perform a correctness pass for grammar, spelling, punctuation, and consistency.
+argument-hint: "[N]"
 ---
 
 # /scr:copy-edit -- Grammar and Correctness Pass

package/commands/scr/demo.md

@@ -31,6 +31,7 @@ Demo project created at ./scriveno-demo/
 
 Try any of these to see Scriveno in action:
   cd scriveno-demo
+  /scr:first-run             See the guided proof path and runtime-specific command shapes
   /scr:progress              See where the project is
   /scr:next                  Let Scriveno pick your next move
   /scr:draft 5               Watch the drafter produce scene 5 in the established voice

package/commands/scr/dialogue-audit.md

@@ -1,5 +1,6 @@
 ---
 description: Audit dialogue for character voice differentiation, attribution clarity, and talking-head detection.
+argument-hint: "[N]"
 ---
 
 # /scr:dialogue-audit -- Character Dialogue Quality Audit

package/commands/scr/discussion-questions.md

@@ -1,5 +1,6 @@
 ---
 description: Generate reading group discussion questions exploring themes, characters, and craft.
+argument-hint: "[--count <N>]"
 ---
 
 # /scr:discussion-questions -- Reading Group Discussion Questions

package/commands/scr/draft.md

@@ -35,7 +35,7 @@ Require `.manuscript/plans/{N}-*-PLAN.md` files to exist. If none exist, also ch
 
 3. **Save drafted output** to `.manuscript/drafts/body/{N}-{A}-DRAFT.md`.
 
-4. **After all atomic units in the unit are drafted, do a voice-check pass.** Load the full drafted unit, compare against STYLE-GUIDE.md, flag any scenes that drift from the voice profile by more than the configured threshold. If drift is detected, offer to re-draft the problem scenes.
+4. **After all atomic units in the unit are drafted, run a voice-check pass.** Invoke the installed `voice-checker.md` agent in a fresh context on the drafted unit -- the same agent `/scr:voice-check` uses. It loads the unit and STYLE-GUIDE.md and returns an Overall score (0-100). Convert to normalized drift (`drift = (100 - score) / 100`; see the "Normalized drift" section of `voice-checker.md`) and, if drift exceeds `config.voice.drift_threshold` (default 0.3, i.e. a voice score below 70), flag the scenes that drove the score down and offer to re-draft them. If the host runtime cannot spawn the voice-checker, fall back to the drafter's built-in self-check (Step 4 in `drafter.md`) and say so in the status block.
 
 5. **Update RECORD.md.** After drafting, extract what the new draft establishes on page. Update `.manuscript/RECORD.md` with only durable, reader-visible changes:
    - established facts, claims, events, definitions, procedures, objects, relationships, or constraints
@@ -51,7 +51,7 @@ Require `.manuscript/plans/{N}-*-PLAN.md` files to exist. If none exist, also ch
 
 7. **Update STATE.md:** mark unit as drafted, note word count, flag any voice-check issues.
 
-8. **Tell the writer:** "Drafted {unit} {N}: X words across Y {atomic_units}. Voice consistency: Z%. Updated RECORD.md with what the draft established. Ready for editor review? Run `/scr:editor-review N` or `/scr:next`."
+8. **Tell the writer:** "Drafted {unit} {N}: X words across Y {atomic_units}. Voice consistency: Z% (the voice-checker Overall score for this unit; omit this figure if the voice-check could not run). Updated RECORD.md with what the draft established. Ready for editor review? Run `/scr:editor-review N` or `/scr:next`."
 
 ## Agent and Automation Status
 

package/commands/scr/export.md

@@ -341,7 +341,7 @@ title: "[title from config.json]"
 subtitle: "[subtitle if available]"
 author:
   - name: "[author from config.json]"
-language: "[language from config.json, default en-US]"
+lang: "[language from config.json, default en-US]"
 rights: "Copyright [year] [author]. All rights reserved."
 date: "[current year]"
 description: "[description if available]"

package/commands/scr/first-run.md

@@ -0,0 +1,128 @@
+---
+description: Run the guided first-run path through install checks, demo proof, starter choices, and next commands.
+argument-hint: "[--proof] [--runtime <runtime>]"
+---
+
+# First Run
+
+You are guiding a writer through Scriveno's first 10 minutes. This command is the executable version of Quick Proof: it should orient the writer, check what can be checked, point at the demo, and keep the next choice small.
+
+Use the shared CLI guide first when local command execution is available:
+
+```bash
+scriveno first-run --project "$PWD"
+node bin/install.js first-run --project "$PWD"
+```
+
+If the CLI is unavailable, follow the same steps manually from this command file.
+
+## What to do
+
+1. **Run the first-run guide.** Prefer `scriveno first-run --project "$PWD"`. It reports project status, runtime command shapes, demo steps, proof artifacts, and installed-surface checks.
+2. **Show the runtime-specific command shape.**
+   - 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`
+   - Guided targets: use the generated local-MCP setup notes
+3. **If no project exists, recommend the demo first.** The safest first action is `/scr:demo`, because it creates `./scriveno-demo/` instead of touching the writer's actual project.
+4. **Point at proof artifacts.** Name these files:
+   - `docs/quick-proof.md`
+   - `docs/starter-sets.md`
+   - `data/proof/first-run/README.md`
+   - `data/proof/runtime-parity/README.md`
+   - `data/proof/watchmaker-flow/README.md`
+   - `data/proof/voice-dna/README.md`
+5. **Keep the first action small.** Do not list the full command catalog. Offer one recommended command and at most three alternatives.
+
+## Recommended first-run path
+
+Use this sequence when the writer wants to try Scriveno immediately:
+
+```text
+/scr:demo
+cd scriveno-demo
+/scr:next
+/scr:draft 5
+/scr:editor-review 5
+```
+
+Translate those command shapes for the active host when needed:
+
+- Claude Code: `/scr-demo`, `/scr-next`, `/scr-draft 5`, `/scr-editor-review 5`
+- Codex: `$scr-demo`, `$scr-next`, `$scr-draft 5`, `$scr-editor-review 5`
+
+## Output shape
+
+Use this structure:
+
+```markdown
+First-run path:
+1. Check the installed surface.
+2. Open the demo.
+3. Inspect the proof bundle.
+4. Draft the planned fifth unit.
+5. Review the result.
+
+Recommended now:
+- `/scr:demo`: Create the isolated watchmaker demo project.
+
+Proof artifacts:
+- `data/proof/first-run/README.md`
+- `data/proof/runtime-parity/README.md`
+- `data/proof/voice-dna/README.md`
+
+Next commands:
+- `/scr:demo`: Create the isolated demo project.
+- `/scr:next`: Let Scriveno inspect the current project state.
+- `/scr:new-work`: Start a real project instead of using the demo.
+```
+
+## Agent and automation status
+
+`/scr:first-run` is read-only unless the writer explicitly chooses a follow-up command such as `/scr:demo`.
+
+```text
+Automation status:
+Trigger: /scr:first-run
+Spawned agents:
+- none
+Candidate agents:
+- drafter after /scr:draft 5 in the demo
+- voice-checker after drafting
+Local operations:
+- first-run guide: read-only
+- status sweep: read-only when the CLI is available
+Candidate local helpers:
+- scriveno smoke --json
+- scriveno routes --json
+Manual gates:
+- writer chooses whether to create the demo or start a real project
+Auto-invoked:
+- none
+Why: first-run orients and recommends; it does not mutate files until the writer picks a follow-up command
+```
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+## Tone
+
+Calm, direct, and proof-first. The writer is trying to decide whether Scriveno is worth trusting, so show concrete paths and files instead of broad claims.

package/commands/scr/help.md

@@ -34,12 +34,13 @@ You are helping the user navigate Scriveno commands. Load Scriveno's installed/s
 
 ## The "getting started" view (no project yet)
 
-Ask the user what they want to do. Don't list 170 commands -- show them this:
+Ask the user what they want to do. Don't list all 113 commands -- show them this:
 
 ```
 Scriveno -- ready to start.
 
 What do you want to do?
+  /scr:first-run       Run the guided first-run proof path
   /scr:new-work        Start a new project (novel, runbook, screenplay, paper, etc.)
   /scr:demo            Explore a pre-built sample project first
   /scr:import <file>   Bring in an existing manuscript

package/commands/scr/line-edit.md

@@ -1,5 +1,6 @@
 ---
 description: Perform a line-level prose quality pass with inline annotations.
+argument-hint: "[N]"
 ---
 
 # /scr:line-edit -- Line-Level Prose Quality Pass

package/commands/scr/map-manuscript.md

@@ -1,5 +1,6 @@
 ---
 description: Spawn parallel analysis agents to understand an existing manuscript's voice, structure, characters, and themes.
+argument-hint: "[area]"
 ---
 
 # /scr:map-manuscript -- Analyze Existing Manuscript

package/commands/scr/multi-publish.md

@@ -199,7 +199,7 @@ Determine text direction from language code:
 
 Set the appropriate direction for Pandoc and Typst output:
 - Pandoc: `--variable dir=rtl` or `--variable dir=ltr`
-- Typst: Uses `text-dir` parameter (already prepared in Phase 5 template)
+- Typst: the book interior template reads the Pandoc `dir` variable set above to orient text
 
 #### 5d. Number Formatting
 
@@ -238,7 +238,7 @@ title: "[translated title]"
 subtitle: "[translated subtitle]"
 author:
   - name: "[author name]"
-language: "[lang code]"
+lang: "[lang code]"
 dir: "[ltr or rtl]"
 rights: "Copyright [year] [author]. [Translated rights statement]."
 date: "[current year]"
@@ -274,6 +274,7 @@ pandoc .manuscript/translation/{lang}/assembled-manuscript.md \
 pandoc .manuscript/translation/{lang}/assembled-manuscript.md \
   -o .manuscript/output/translations/{lang}/manuscript-{lang}.pdf \
   --pdf-engine=typst \
+  --template=data/export-templates/scriveno-book.typst \
   --metadata-file=.manuscript/translation/{lang}/metadata.yaml \
   --toc --toc-depth=1 \
   -V dir={ltr|rtl}

package/commands/scr/new-character.md

@@ -1,5 +1,6 @@
 ---
 description: Build a complete character profile through guided interactive interview.
+argument-hint: "<name>"
 ---
 
 # /scr:new-character -- Interactive Character Creation

package/commands/scr/new-work.md

@@ -69,7 +69,7 @@ Always create `RECORD.md` from `templates/RECORD.md` without renaming it. It is
 Write `.manuscript/config.json` by starting from `templates/config.json` and filling the project-specific values. The generated config must include the shared settings blocks that later commands read:
 ```json
 {
-  "scriveno_version": "2.0.12",
+  "scriveno_version": "2.6.0",
   "work_type": "<chosen>",
   "group": "<group>",
   "command_unit": "<unit>",

package/commands/scr/originality-check.md

@@ -1,5 +1,6 @@
 ---
 description: Scan drafted prose for AI-generated patterns and unintentional similarity to published works.
+argument-hint: "[N]"
 ---
 
 # /scr:originality-check -- AI Pattern & Similarity Scan