scriveno 2.7.1 → 2.8.0

package/commands/scr/export.md

@@ -1,6 +1,6 @@
 ---
 description: Compile and export manuscript to publication-ready formats.
-argument-hint: "[--format <format>] [--formatted] [--print-ready] [--skip-validate]"
+argument-hint: "[--format <format>] [--formatted] [--print-ready] [--skip-validate] [--check]"
 ---
 
 # /scr:export -- Manuscript Export
@@ -11,11 +11,13 @@ Assemble the manuscript from OUTLINE.md and export to the specified format. Hand
 
 ```
 /scr:export                                  # interactive picker
-/scr:export --format <format> [--formatted] [--print-ready] [--skip-validate]
+/scr:export --format <format> [--formatted] [--print-ready] [--skip-validate] [--check]
 ```
 
 If `--format` is omitted, run the interactive picker (see STEP 0). Otherwise jump straight to STEP 1 with the requested format.
 
+If `--check` is passed, check format availability and required external tools, print a readiness report, and stop before assembling or writing export files.
+
 ---
 
 ### STEP 0: INTERACTIVE PICKER (only when --format is omitted)
@@ -135,6 +137,8 @@ Then **stop**.
 
 **Check for scaffold markers in `.manuscript/drafts/`.**
 
+If `--check` was passed, skip the scaffold-marker scan and proceed to STEP 2. Tool check mode verifies readiness of external commands only; it does not certify manuscript content.
+
 Scan all `.md` files in `.manuscript/drafts/` for:
 - Lines containing `[Fill in` (covers `[Fill in:]`, `[Fill in or delete:]`)
 - Lines containing `[Delete if not applicable:]`
@@ -217,6 +221,27 @@ Proceed to STEP 2.
 
 Check for required external tools based on the requested format.
 
+**Tool gate rules:**
+
+1. Never silently substitute one tool for another. For example, do not use WeasyPrint when Typst is missing, and do not use Calibre when Pandoc is missing.
+2. Record the tool command that was checked and, when available, the detected version.
+3. If `--check` was passed, do not create `.manuscript/output/`, do not assemble the manuscript, and do not run conversion commands. Print the report and stop after this step.
+4. If a required tool is missing, stop and show install instructions. Do not attempt a degraded export.
+
+Use this readiness report shape in `--check` mode:
+
+```text
+Export Tool Check
+=================
+Format: pdf --print-ready
+
+[PASS] pandoc .......... pandoc 3.x
+[PASS] typst ........... typst 0.x
+[SKIP] ghostscript ..... not required for this format
+
+Result: ready
+```
+
 **For markdown:** No external tools needed. Skip to Step 3.
 
 **For docx, epub, latex, query-package:** Check for Pandoc:
@@ -269,6 +294,22 @@ If not found, provide install instructions (`pip install screenplain`) and stop.
 
 **For fountain:** No external tools needed.
 
+**For kdp-package:** Check for Pandoc and Typst. If either tool is missing, stop before building the package.
+
+**For ingram-package:** Check for Pandoc, Typst, and Ghostscript (`gs`). If any required tool is missing, stop before building the package.
+
+**For query-package and submission-package:** Check for Pandoc.
+
+**Optional screenplay PDF:** Afterwriting is optional for `fountain`. If it is missing, do not fail the Fountain export; report it as optional. If `--check` is passed, show it as optional with install guidance:
+
+```bash
+command -v afterwriting >/dev/null 2>&1
+```
+
+> Optional: To generate a formatted screenplay PDF, install Afterwriting with `npm i -g afterwriting`.
+
+If `--check` was passed, stop here after printing the readiness report.
+
 ---
 
 ### STEP 3: ASSEMBLE MANUSCRIPT

package/commands/scr/health.md

@@ -1,6 +1,6 @@
 ---
 description: Diagnose and repair common project state issues.
-argument-hint: "[--repair]"
+argument-hint: "[--repair] [--context]"
 ---
 
 # Health
@@ -87,6 +87,39 @@ With `--repair`, fix what can be auto-fixed:
 
 After repair: re-run diagnostics and show the updated health report.
 
+## Context mode (--context)
+
+With `--context`, focus only on loaded-context health. This is a read-only guard for long projects and large unit sessions.
+
+1. Estimate the files an agent is likely to load before writing:
+   - `.manuscript/STYLE-GUIDE.md`
+   - `.manuscript/CONTEXT.md`
+   - `.manuscript/STATE.md`
+   - `.manuscript/OUTLINE.md`
+   - `.manuscript/RECORD.md`
+   - The newest plan, draft, and review files for the active unit
+2. Estimate tokens as `ceil(bytes / 4)`. This is intentionally simple and conservative.
+3. Classify the result:
+   - `ok`: under 45,000 estimated tokens
+   - `watch`: 45,000-79,999 estimated tokens
+   - `tight`: 80,000-119,999 estimated tokens
+   - `critical`: 120,000 or more estimated tokens
+4. Report the five largest loaded files so the writer can see what is making the session heavy.
+5. If the state is `watch`, suggest `/scr:health --context` again before the next large operation.
+6. If the state is `tight`, suggest `/scr:save` before drafting, review, translation, or export.
+7. If the state is `critical`, suggest `/scr:thread` or a fresh unit session before writing more prose.
+
+If the shared CLI engine is available, prefer it:
+
+```bash
+scriveno status --project "$PWD" --trigger "/scr:health --context"
+node lib/auto-invoke-engine.js --project "$PWD" --trigger "/scr:health --context"
+node "$HOME/.scriveno/lib/auto-invoke-engine.js" --project "$PWD" --trigger "/scr:health --context"
+node .scriveno/lib/auto-invoke-engine.js --project "$PWD" --trigger "/scr:health --context"
+```
+
+Return only the context-health portion of the report unless another health issue blocks the command.
+
 ## Automation Status
 
 Every response must include a compact status block:
@@ -100,6 +133,7 @@ Candidate agents:
 - none
 Local operations:
 - health checks run: {count}
+- context estimate run: {yes|no}
 - repairs applied: {count}
 Candidate local helpers:
 - /scr:scan or /scr:save when health detects repairable drift

package/commands/scr/help.md

@@ -34,7 +34,7 @@ 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 all 113 commands -- show them this:
+Ask the user what they want to do. Don't list all 115 commands -- show them this:
 
 ```
 Scriveno -- ready to start.

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.7.1",
+  "scriveno_version": "2.8.0",
   "work_type": "<chosen>",
   "group": "<group>",
   "command_unit": "<unit>",

package/commands/scr/proof-unit.md

@@ -0,0 +1,138 @@
+---
+description: Run one manuscript unit through a proof path from voice profile to export readiness.
+argument-hint: "[unit] [--demo] [--export-check]"
+---
+
+# Proof Unit
+
+You are proving that Scriveno can carry one unit through the real writing loop without losing the writer's voice.
+
+Follow the auto-invoke policy. In the source repository it is documented at `docs/auto-invoke-policy.md`. `/scr:proof-unit` coordinates existing commands. It should keep every step small and stop before any destructive or publishing action unless the writer explicitly confirms.
+
+## Goal
+
+Run one chosen unit through this vertical slice:
+
+1. Confirm project and voice context.
+2. Discuss or refine the unit shape.
+3. Plan the unit.
+4. Draft the unit with fresh context.
+5. Review the draft for voice, continuity, and revision issues.
+6. Check context health before another large operation.
+7. Check export prerequisites without writing final packages unless requested.
+
+The proof is successful only if the unit still sounds like the writer and the next production step is obvious.
+
+## Inputs
+
+- `unit`: The unit number or label. If omitted, infer it from `.manuscript/STATE.md`.
+- `--demo`: Prefer the demo project path and use its planned proof unit.
+- `--export-check`: Run `/scr:export --check` after review to verify external tools.
+
+If there is no `.manuscript/` directory, recommend `/scr:demo` or `/scr:new-work` before doing anything else.
+
+## Required Checks
+
+1. Read `.manuscript/STYLE-GUIDE.md` first. If it is missing or thin, suggest `/scr:profile-writer` or `/scr:voice-test` before drafting.
+2. Read `.manuscript/STATE.md`, `.manuscript/OUTLINE.md`, and `.manuscript/config.json`.
+3. Run context health with the shared engine when available:
+
+```bash
+scriveno status --project "$PWD" --trigger /scr:proof-unit
+node lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:proof-unit
+node "$HOME/.scriveno/lib/auto-invoke-engine.js" --project "$PWD" --trigger /scr:proof-unit
+node .scriveno/lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:proof-unit
+```
+
+4. If context health is `tight` or `critical`, stop before drafting and suggest `/scr:save`, `/scr:thread`, or a fresh unit session.
+5. Verify that the plan, draft, and review files are all unit-scoped. Do not load the whole manuscript into a drafting pass.
+
+## Execution Path
+
+Use the first missing step in order:
+
+1. Missing voice profile: `/scr:profile-writer` or `/scr:voice-test`.
+2. Missing unit discussion: `/scr:discuss <unit>`.
+3. Missing unit plan: `/scr:plan <unit>`.
+4. Missing unit draft: `/scr:draft <unit>`.
+5. Missing review: `/scr:editor-review <unit>`.
+6. Review flags voice drift: `/scr:voice-check <unit>`.
+7. Review flags continuity drift: `/scr:continuity-check <unit>`.
+8. Review passes and `--export-check` was provided: `/scr:export --check`.
+9. Review passes without export check: `/scr:submit <unit>` or `/scr:progress`.
+
+Do not run more than one prose-generating step without reporting back. The writer should see the proof path as a sequence of verified stops, not a silent batch.
+
+## Proof Report
+
+End with a compact proof report:
+
+```markdown
+Proof unit: Chapter 3
+Voice profile: present
+Plan: present
+Draft: present
+Review: present
+Context health: ok
+Export prerequisites: not checked
+
+Result: ready for submit, with no blocking voice drift found.
+```
+
+When something fails, name the missing file or blocking step and offer the direct command that fixes it.
+
+## Automation Status
+
+Every response must include a compact status block:
+
+```text
+Automation status:
+Trigger: /scr:proof-unit {unit}
+Spawned agents:
+- drafter when /scr:draft is the selected step
+- voice-checker when draft or voice review is selected
+- diagnostic worker when /scr:editor-review is selected
+Candidate agents:
+- drafter
+- voice-checker
+- continuity-checker
+Local operations:
+- project state inspected: yes
+- context health estimated: yes
+- export prerequisite check: {yes|no}
+Candidate local helpers:
+- /scr:health --context
+- /scr:export --check
+Manual gates:
+- publish or final package creation
+Auto-invoked:
+- {selected command}: {yes|no}
+Why: proof-unit coordinates the smallest real writing loop while keeping publishing actions explicit
+```
+
+## 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.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.
+
+## Tone
+
+Focused and evidence-first. The point is to build trust with one real unit, not to rush the whole manuscript.

package/commands/scr/publish.md

@@ -1,6 +1,6 @@
 ---
 description: "Publishing wizard or preset-driven pipeline. Chains export commands based on destination."
-argument-hint: "[--preset <preset>] [--all] [--skip-validate]"
+argument-hint: "[--preset <preset>] [--all] [--skip-validate] [--preflight]"
 ---
 
 # /scr:publish -- Publishing Wizard
@@ -10,12 +10,13 @@ You are the publishing wizard. Your job is to turn a completed manuscript into p
 ## Usage
 
 ```
-/scr:publish [--preset <preset>] [--all] [--skip-validate]
+/scr:publish [--preset <preset>] [--all] [--skip-validate] [--preflight]
 ```
 
 - `--preset <preset>` -- Run a named preset pipeline without questions
 - `--all` -- Run every preset available for the current work type
 - `--skip-validate` -- Skip the scaffold-marker gate (not recommended)
+- `--preflight` -- Check readiness and required tools, then stop before writing deliverables
 - No arguments -- Run the interactive wizard
 
 ---
@@ -124,6 +125,48 @@ Proceed to STEP 2.
 
 ---
 
+### STEP 1.7: PREFLIGHT MODE
+
+If `--preflight` was passed, run a readiness check only and stop before generating front matter, back matter, exports, packages, or history entries.
+
+Preflight must include:
+
+1. The validation gate from STEP 1.5 unless `--skip-validate` was also passed.
+2. The front-matter scaffold exclusion check from STEP 1.6a.
+3. The publishing prerequisite checklist from STEP 3a.
+4. Preset availability against `CONSTRAINTS.json`.
+5. External tool checks by calling the matching export checks:
+   - `share-pdf`: `/scr:export --format pdf --check`
+   - `share-docx`: `/scr:export --format docx --check`
+   - `share-epub`: `/scr:export --format epub --check`
+   - `kdp-ebook`: `/scr:export --format epub --check`
+   - `kdp-paperback`: `/scr:export --format pdf --print-ready --check` and `/scr:export --format kdp-package --check`
+   - `ingram-paperback`: `/scr:export --format pdf --print-ready --check` and `/scr:export --format ingram-package --check`
+   - `query-submission`: `/scr:export --format query-package --check`
+   - `submission-package`: `/scr:export --format submission-package --check`
+   - `screenplay-query`: `/scr:export --format fountain --check`, `/scr:export --format fdx --check`, and `/scr:export --format query-package --check`
+   - `all-formats`: check each available base format
+
+Use this report shape:
+
+```text
+Publishing Preflight
+====================
+Preset: kdp-paperback
+
+[PASS] manuscript validation
+[WARN] front matter ........ not generated
+[PASS] pandoc
+[PASS] typst
+[SKIP] ghostscript ......... not required until ingram-package
+
+Result: ready after 1 optional item
+```
+
+If preflight finds a blocking issue, stop and suggest the command that fixes it. Do not continue into STEP 2.
+
+---
+
 ### STEP 2: ROUTE
 
 **If `--preset` is given:** Validate the preset name against the known presets below. If valid, jump to STEP 4 (preset pipeline). If invalid, show the list of available presets and stop.

package/commands/scr/scan.md

@@ -38,8 +38,8 @@ Run every check. Do not stop on first finding. Bundle them all into one report.
 Read `STATE.md` for `Units drafted`, `Units planned`, `Units reviewed`, and `Total words`. Then count what is actually on disk:
 
 - **Units drafted** = files matching `.manuscript/drafts/body/*-DRAFT.md`
-- **Units planned** = files matching `.manuscript/*-*-PLAN.md` (numeric-prefixed plan files)
-- **Units reviewed** = files matching `.manuscript/*-EDITOR-NOTES.md`
+- **Units planned** = files matching `.manuscript/plans/*-PLAN.md`; legacy root-level `.manuscript/*-PLAN.md` also counts
+- **Units reviewed** = files matching `.manuscript/reviews/*-REVIEW.md`; legacy root-level `.manuscript/*-EDITOR-NOTES.md` also counts
 - **Total words** = `wc -w` summed across all `drafts/body/*-DRAFT.md` files
 
 For each metric where STATE.md value != filesystem value, emit:
@@ -67,7 +67,7 @@ For each orphan, emit one finding with the unit identifier and the file path.
 
 ### CHECK 3: Plan vs. draft alignment
 
-For each `*-PLAN.md` file in `.manuscript/`, check whether the corresponding `*-DRAFT.md` exists in `drafts/body/`. If a plan exists but no draft:
+For each `*-PLAN.md` file in `.manuscript/plans/` (and any legacy root-level `*-PLAN.md` file), check whether the corresponding `*-DRAFT.md` exists in `drafts/body/`. If a plan exists but no draft:
 
 ```
 INFO   Unit 8 has a plan ({N}-{A}-PLAN.md) but no draft yet.

package/commands/scr/surface.md

@@ -0,0 +1,149 @@
+---
+description: Inspect or change the installed Scriveno command profile.
+argument-hint: "[list|status|profile <core|writing|publishing|translation|specialist|full>] [--runtime <runtime>] [--dry-run]"
+---
+
+# Surface
+
+You are helping the writer keep Scriveno's installed command surface clear, small, and appropriate for the work they are doing.
+
+Follow the auto-invoke policy. In the source repository it is documented at `docs/auto-invoke-policy.md`. `/scr:surface` is a local installer helper. It does not spawn agents and should not edit a manuscript.
+
+## What This Command Does
+
+Use this command when the writer wants fewer commands, a publishing-only install, a translation-focused install, or a check of what profile is currently installed.
+
+Available profiles:
+
+- `core`: Main writing loop and orientation commands.
+- `writing`: Core workflow plus revision, structure, character, and quality commands.
+- `publishing`: Core workflow plus export, publishing, metadata, and platform packaging commands.
+- `translation`: Core workflow plus translation, localization, glossary, and multi-publish commands.
+- `specialist`: Core workflow plus sacred, illustration, collaboration, and utility surfaces.
+- `full`: Every Scriveno command.
+
+## Actions
+
+### `list`
+
+Run:
+
+```bash
+scriveno surface list
+```
+
+Report each profile, command count, and intended use.
+
+### `status`
+
+Run:
+
+```bash
+scriveno surface status
+```
+
+Report:
+
+- Installed profile from `.scriveno/settings.json` or `~/.scriveno/settings.json`
+- Installed runtimes
+- Scope (`project` or `global`)
+- Writer or developer mode
+- Suggested profile if the current one is much larger than the active workflow needs
+
+### `profile <name>`
+
+Before changing anything, run a dry run:
+
+```bash
+scriveno surface profile <name> --dry-run
+```
+
+If the writer confirms, reinstall that profile for the same runtime surface:
+
+```bash
+scriveno surface profile <name>
+```
+
+If no prior runtime is recorded, ask for one runtime target, then run:
+
+```bash
+scriveno surface profile <name> --runtimes codex --project
+```
+
+Use the active runtime name instead of `codex` when the writer is in Claude Code, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, or the generic skill fallback.
+
+## Safety Rules
+
+1. Prefer `--dry-run` before changing the installed surface.
+2. Do not delete custom user files. The installer cleans only Scriveno-owned command mirrors.
+3. Keep agents installed even when a smaller command profile is selected. Drafting, review, and translation still need their agent prompts when a profile includes those workflows.
+4. Do not imply that a smaller profile disables project data. It only changes the installed command surface.
+5. If the writer is unsure, recommend `writing` for active drafting and `full` for exploration.
+
+## Output Shape
+
+Use this shape:
+
+```markdown
+Surface profile: writing
+Installed runtimes: codex
+Scope: project
+
+Selected commands: 52 command files
+Best use: active drafting with revision and structure tools
+
+No files changed because this was a dry run.
+```
+
+## Automation Status
+
+Every response must include a compact status block:
+
+```text
+Automation status:
+Trigger: /scr:surface {args}
+Spawned agents:
+- none
+Candidate agents:
+- none
+Local operations:
+- surface profile inspected: {yes|no}
+- installer dry run: {yes|no}
+- installer profile change: {yes|no}
+Candidate local helpers:
+- scriveno surface list
+- scriveno surface status
+- scriveno surface profile <name> --dry-run
+Manual gates:
+- writer confirmation before changing installed runtimes
+Auto-invoked:
+- none
+Why: surface management changes installed command files, not manuscript prose
+```
+
+## 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.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.
+
+## Tone
+
+Clear and practical. Treat command-surface changes like workspace organization, not like a feature upsell.

package/data/CONSTRAINTS.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./constraints.schema.json",
-  "version": "2.7.1",
+  "version": "2.8.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."
@@ -3015,6 +3015,23 @@
       ],
       "description": "Diagnose and repair common project state issues"
     },
+    "surface": {
+      "category": "utility",
+      "available": [
+        "all"
+      ],
+      "description": "Inspect or change the installed Scriveno command profile"
+    },
+    "proof-unit": {
+      "category": "core",
+      "available": [
+        "all"
+      ],
+      "description": "Run one manuscript unit through a proof path from voice profile to export readiness",
+      "requires": [
+        "profile-writer"
+      ]
+    },
     "scan": {
       "category": "utility",
       "available": [

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

@@ -43,7 +43,7 @@ Proof artifacts:
 > scriveno smoke --json
 {
   "ok": true,
-  "expectedCommands": 113,
+  "expectedCommands": 115,
   "expectedAgents": [
     "continuity-checker",
     "drafter",

package/docs/architecture.md

@@ -439,7 +439,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 113 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 115 commands and prevents drift as multiple contributors work on the system.
 
 ### Backward compatibility