scriveno 2.0.12 → 2.5.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.5.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
@@ -195,7 +199,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 +244,11 @@ Scriveno currently ships installer targets for these AI tooling environments:
 
 ## Status
 
-**Version:** 2.0.12
+**Version:** 2.5.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.5.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/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/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/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

@@ -40,6 +40,7 @@ Ask the user what they want to do. Don't list 170 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/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.5.0",
   "work_type": "<chosen>",
   "group": "<group>",
   "command_unit": "<unit>",

package/data/CONSTRAINTS.json

@@ -1,12 +1,13 @@
 {
   "$schema": "./constraints.schema.json",
-  "version": "2.0.12",
+  "version": "2.5.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": [

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

@@ -199,6 +199,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 +373,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
 
@@ -434,7 +436,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,6 +227,22 @@ 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.

package/docs/configuration.md

@@ -57,7 +57,7 @@ When a writer runs `/scr:new-work`, Scriveno creates `.manuscript/config.json`.
 
 ```json
 {
-  "scriveno_version": "2.0.12",
+  "scriveno_version": "2.5.0",
   "work_type": "<chosen>",
   "group": "<group>",
   "command_unit": "<unit>",

package/docs/getting-started.md

@@ -22,12 +22,13 @@ npx scriveno@latest
 
 This installs Scriveno into the runtime you choose. Command-directory and skills targets place files where the runtime expects them. Guided targets like Perplexity Desktop instead write setup assets and show the exact connector steps you need. Takes about 30 seconds.
 
-Once installed, Claude Code uses flat `/scr-*` commands such as `/scr-help` and `/scr-new-work`. Other command-directory runtimes currently keep `/scr:*`. Codex uses generated `$scr-*` skills such as `$scr-help` and `$scr-new-work`. Guided targets explain their supported setup path directly in the generated setup files.
+Once installed, Claude Code uses flat `/scr-*` commands such as `/scr-help`, `/scr-first-run`, and `/scr-new-work`. Other command-directory runtimes currently keep `/scr:*`. Codex uses generated `$scr-*` skills such as `$scr-help`, `$scr-first-run`, and `$scr-new-work`. Guided targets explain their supported setup path directly in the generated setup files.
 
 You can also ask Scriveno for a read-only project status from any terminal:
 
 ```
 scriveno status --project .
+scriveno first-run --project .
 scriveno status . --json
 scriveno status --project . --apply-safe
 scriveno sync --check
@@ -37,6 +38,8 @@ That status command is the same shared auto-invoke engine used by `/scr-next`, `
 
 Use `--apply-safe` when you want Scriveno to run the read-only checks and show which helpers are safe, skipped, or agent-ready. Use `sync --check` when you want the installed runtime surfaces checked too.
 
+If you want one guided proof path instead of separate checks, start with `scriveno first-run --project .`.
+
 ## Step 2: Explore the Demo (Optional)
 
 Not sure what Scriveno does? Try the demo before starting your own project:

package/docs/proof-artifacts.md

@@ -5,6 +5,7 @@ This document is the canonical index of Scriveno's proof layer. It points to con
 ## Start Here
 
 - Read **Quick Proof** if you want one 10-minute route through installation checks, demo inspection, runtime command shapes, and the next draft command.
+- Read **First-Run Proof** if you want the committed transcript artifact for `/scr:first-run`, `scriveno first-run --project .`, runtime smoke, and the demo flow.
 - Read the **Watchmaker Sample Flow** if you want one end-to-end writing workflow from setup through drafts, review, and next step.
 - Read **Voice DNA** if you want the shortest possible proof of how style guidance changes output on the same brief.
 - Read **Creative Context** if you want to see one craft choice travel through discuss, plan, draft, and review artifacts.
@@ -32,6 +33,14 @@ This document is the canonical index of Scriveno's proof layer. It points to con
 
 Start with the proof bundle if you want the curated version. Follow the underlying files if you want to inspect the raw sample directly.
 
+## First-Run Proof
+
+**What it proves:** Scriveno has an executable first-run guide and committed transcript artifacts for the first proof path.
+
+**Canonical artifact:** [data/proof/first-run/README.md](../data/proof/first-run/README.md)
+
+**Related parity artifact:** [data/proof/runtime-parity/README.md](../data/proof/runtime-parity/README.md)
+
 ## Voice DNA
 
 **What it proves:** Scriveno's style-guide layer changes draft behavior in visible ways when the same brief is written unguided versus guided.
@@ -57,6 +66,8 @@ Read the bundle in order if you want to inspect sentence rhythm, metaphor select
 - [Shipped Assets](shipped-assets.md) -- canonical inventory of the trust-critical files Scriveno actually bundles
 - [Quick Proof](quick-proof.md) -- 10-minute proof-first path through install checks, the demo, and the next draft
 - [Starter Sets](starter-sets.md) -- small command sets by writing goal
+- [data/proof/first-run/README.md](../data/proof/first-run/README.md) -- committed first-run transcript artifact
+- [data/proof/runtime-parity/README.md](../data/proof/runtime-parity/README.md) -- runtime surface evidence and host-parity boundary
 - [Runtime Support](runtime-support.md) -- canonical runtime matrix and installer-baseline framing
 - [Auto-Invoke Policy](auto-invoke-policy.md) -- proactive status, safe apply, local-helper, and agent-spawn boundaries
 - [Route Graph Audit](route-graph.md) -- generated route graph, automation lanes, and priority fixtures

package/docs/quick-proof.md

@@ -1,10 +1,11 @@
 # Quick Proof
 
-This is the shortest proof-first path through Scriveno. It is meant for a fresh user who wants to see real shipped artifacts, a demo manuscript, runtime expectations, and the first practical commands before reading the full manual.
+This is the shortest proof-first path through Scriveno. It is meant for a fresh user who wants to see real shipped artifacts, a demo manuscript, runtime expectations, and the first practical commands before reading the full manual. If your runtime supports Scriveno commands, the executable version of this page is `/scr:first-run`.
 
 ## What This Proves
 
 - Scriveno ships inspectable proof bundles, not only feature claims.
+- Scriveno ships `/scr:first-run` and `scriveno first-run --project .` as guided first-run surfaces.
 - The watchmaker demo includes real manuscript state, drafts, review notes, and a planned next unit.
 - Voice DNA changes output on the same brief, with guided and unguided samples side by side.
 - Runtime behavior is explicit: Claude Code is the primary reference runtime, Codex uses generated `$scr-*` skills, standard slash-command targets use `/scr:*`, and guided targets document their local setup path.
@@ -27,31 +28,35 @@ node bin/install.js --runtimes claude-code,cursor,gemini-cli,codex,opencode,copi
 ### 2. Check The Installed Surface
 
 ```bash
+scriveno first-run --project .
 scriveno status --project .
 scriveno smoke --json
 scriveno agents --json
 scriveno routes --json
 ```
 
-Expected result: the commands report installed surfaces, agent prompt availability, route lanes, and any manual gates. They do not mutate manuscript files.
+Expected result: the commands report the recommended first path, installed surfaces, agent prompt availability, route lanes, and any manual gates. They do not mutate manuscript files.
 
 ### 3. Open The Demo
 
 Claude Code:
 
 ```text
+/scr-first-run
 /scr-demo
 ```
 
 Standard slash-command runtimes:
 
 ```text
+/scr:first-run
 /scr:demo
 ```
 
 Codex:
 
 ```text
+$scr-first-run
 $scr-demo
 ```
 
@@ -72,6 +77,8 @@ Start here:
 - [data/proof/watchmaker-flow/README.md](../data/proof/watchmaker-flow/README.md)
 - [data/proof/voice-dna/README.md](../data/proof/voice-dna/README.md)
 - [data/proof/creative-context/README.md](../data/proof/creative-context/README.md)
+- [data/proof/first-run/README.md](../data/proof/first-run/README.md)
+- [data/proof/runtime-parity/README.md](../data/proof/runtime-parity/README.md)
 
 The fastest comparison is the Voice DNA pair:
 
@@ -147,6 +154,18 @@ Candidate local helpers: scan, save
 Manual gates: writer approval before publishing or overwriting exports
 ```
 
+```text
+> scriveno first-run --project .
+Scriveno first-run guide
+Current recommendation: /scr:new-work
+Recommended first path:
+1. /scr:demo
+2. cd scriveno-demo
+3. /scr:next
+4. /scr:draft 5
+5. /scr:editor-review 5
+```
+
 ```text
 > /scr:draft 5
 Loaded STYLE-GUIDE.md and the plan for unit 5.
@@ -169,6 +188,8 @@ No runtime claim here should be read as host-runtime parity proof. The repo prov
 ## Where To Go Next
 
 - [Starter Sets](starter-sets.md) for small command paths by writing goal
+- [data/proof/first-run/README.md](../data/proof/first-run/README.md) for committed first-run transcripts
+- [data/proof/runtime-parity/README.md](../data/proof/runtime-parity/README.md) for runtime parity evidence
 - [Getting Started](getting-started.md) for the complete first-project walkthrough
 - [Proof Artifacts](proof-artifacts.md) for the proof hub
 - [Runtime Support](runtime-support.md) for installation and support levels

package/docs/release-notes.md

@@ -2,6 +2,42 @@
 
 This document is the public-facing summary of what changed between package releases. For package history, see the root [CHANGELOG](../CHANGELOG.md).
 
+## 2.5.0 - 2026-05-16
+
+### What changed
+
+- Scriveno now ships `/scr:first-run`, an executable first-run path through install checks, demo proof, starter choices, and next commands.
+- The public CLI now supports `scriveno first-run --project .`, giving terminal users the same proof path without relying on host-specific slash-command behavior.
+- First-run guidance is connected to `/scr:help`, `/scr:demo`, Quick Proof, Starter Sets, Runtime Support, Shipped Assets, Command Reference, README launch copy, and architecture docs.
+- Scriveno now includes committed first-run and runtime-parity proof bundles under `data/proof/`.
+- Runtime smoke now validates the 113-command installed surface across Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic fallback.
+- README badges, package metadata, constraints metadata, generated config metadata, changelog, release notes, configuration docs, route graph docs, architecture docs, proof docs, and release tests are aligned on `2.5.0`.
+
+### Why it matters
+
+The previous release documented a stronger proof path. This release makes that path executable. A new writer can install Scriveno, run one first-run command, inspect proof artifacts, create the demo, and move into drafting without having to assemble the path from documentation.
+
+### Affected areas
+
+- first-run command surface
+- public CLI installer and smoke checks
+- proof artifact bundles
+- README badges and launch copy
+- runtime support matrix
+- command reference and route graph docs
+- package metadata and generated project examples
+- release-alignment tests
+
+### Verification
+
+- `npm run policy:check`
+- `node --test test/first-run-proof-surface.test.js test/adaptive-concierge.test.js test/auto-invoke-engine.test.js test/command-surface-coherence.test.js test/collaboration-trust-surface.test.js test/package.test.js test/phase15-proof-artifacts-positioning.test.js`
+- `npm test`
+- `npm run release:check`
+- `git diff --check`
+- `scriveno first-run --project .`
+- `scriveno smoke --json`
+
 ## 2.0.12 - 2026-05-16
 
 ### What changed

package/docs/route-graph.md

@@ -13,9 +13,9 @@ The text report summarizes command count, graph edges, agent-capable routes, loc
 
 ## Current Shape
 
-As of `2.0.12`, the route graph contains:
+As of `2.5.0`, the route graph contains:
 
-- 112 commands
+- 113 commands
 - intent-order edges from `command_intents`
 - dependency-chain edges from `dependencies.core_chain`
 - automation lanes from `getCommandAutomationPolicy()`

package/docs/runtime-support.md

@@ -69,12 +69,13 @@ Node is not a runtime dependency for Scriveno's markdown command system itself.
 
 Scriveno docs use `/scr:*` as the shared command id format unless a host-specific example is needed. Installed command surfaces differ by runtime:
 
-- Claude Code: `/scr-demo`, `/scr-new-work`, `/scr-next`
-- Standard command-directory runtimes: `/scr:demo`, `/scr:new-work`, `/scr:next`
-- Codex: `$scr-demo`, `$scr-new-work`, `$scr-next`
+- Claude Code: `/scr-first-run`, `/scr-demo`, `/scr-new-work`, `/scr-next`
+- Standard command-directory runtimes: `/scr:first-run`, `/scr:demo`, `/scr:new-work`, `/scr:next`
+- Codex: `$scr-first-run`, `$scr-demo`, `$scr-new-work`, `$scr-next`
 - Guided targets: follow the generated setup instructions and connector recipe
 
 Use [Quick Proof](quick-proof.md) for the 10-minute proof route and [Starter Sets](starter-sets.md) for goal-based command paths.
+Use [Runtime Parity Evidence](../data/proof/runtime-parity/README.md) for the committed boundary between install-surface proof and host-runtime parity proof.
 
 ## Shared Auto-Invoke Engine
 

package/docs/sacred-texts.md

@@ -292,5 +292,5 @@ Here is a quick walkthrough for starting a sacred writing project:
 ## See Also
 
 - [Getting Started](getting-started.md) -- Install Scriveno and create your first project
-- [Command Reference](command-reference.md) -- Full reference for all 112 commands, including the [Sacred Exclusive](command-reference.md#sacred-exclusive) section
+- [Command Reference](command-reference.md) -- Full reference for all 113 commands, including the [Sacred Exclusive](command-reference.md#sacred-exclusive) section
 - [README](../README.md) -- Project overview and feature list

package/docs/shipped-assets.md

@@ -123,6 +123,8 @@ Sacred commands read top-level sacred profile keys in new projects and preserve
 - `docs/configuration.md` -- canonical project config and package metadata reference
 - `data/proof/watchmaker-flow/README.md` -- canonical sample-flow proof bundle rooted in shipped demo files
 - `data/proof/voice-dna/README.md` -- canonical Voice DNA proof bundle
+- `data/proof/first-run/README.md` -- committed transcript artifact for the executable first-run path
+- `data/proof/runtime-parity/README.md` -- runtime install-surface evidence and host-parity boundary
 - `commands/scr/export.md` -- source of truth for export command behavior
 - `docs/publishing.md` -- user-facing explanation of export formats and publishing packages
 - `docs/contributing.md` -- contributor-facing guidance for extending export support

package/docs/starter-sets.md

@@ -4,6 +4,14 @@ Scriveno has a large command surface because it covers many kinds of writing. St
 
 Each set is intentionally small. Use `/scr-next`, `/scr:next`, or `$scr-next` whenever you are unsure which command should come next.
 
+## First 10 Minutes
+
+- `/scr:first-run` runs the guided proof path and shows runtime-specific command shapes.
+- `/scr:demo` creates the isolated watchmaker demo.
+- `/scr:next` inspects the demo state and recommends the next move.
+- `/scr:draft` drafts the planned fifth unit.
+- `/scr:editor-review` reviews the new draft.
+
 ## Draft A Book
 
 - `/scr:new-work` creates the project and work-type context.

package/docs/voice-dna.md

@@ -293,5 +293,5 @@ See [docs/drafter-quality.md](drafter-quality.md) for the full system, including
 - [Proof Artifacts](proof-artifacts.md) -- inspect the Voice DNA before/after bundle first if you want the fastest concrete evidence
 - [Getting Started](getting-started.md) -- Install Scriveno and write your first draft
 - [Drafter Quality](drafter-quality.md) -- the three rule layers, the `draft` config block, and model-tier recommendations
-- [Command Reference](command-reference.md) -- Full list of all 112 commands with usage and examples
+- [Command Reference](command-reference.md) -- Full list of all 113 commands with usage and examples
 - [Work Types Guide](work-types.md) -- How work types adapt Scriveno's vocabulary and commands

package/docs/work-types.md

@@ -335,5 +335,5 @@ Your work type is stored in `.manuscript/config.json` and can be changed later b
 ## See Also
 
 - [Getting Started](getting-started.md) -- Install Scriveno and write your first draft
-- [Command Reference](command-reference.md) -- Full list of all 112 commands with usage and examples
+- [Command Reference](command-reference.md) -- Full list of all 113 commands with usage and examples
 - [Voice DNA Guide](voice-dna.md) -- How Scriveno profiles and preserves your writing voice

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scriveno",
-  "version": "2.0.12",
+  "version": "2.5.0",
   "description": "Spec-driven creative writing, publishing, and translation pipeline for AI coding agents. From blank page to published book.",
   "bin": {
     "scriveno": "bin/install.js"

package/templates/config.json

@@ -1,5 +1,5 @@
 {
-  "scriveno_version": "2.0.12",
+  "scriveno_version": "2.5.0",
   "work_type": "",
   "group": "",
   "command_unit": "",