scriveno 2.0.7 → 2.0.8

package/README.md

@@ -2,9 +2,10 @@
 
 [![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.7-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.0.8-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)
 
 **[scriveno on npm](https://www.npmjs.com/package/scriveno)**
 
@@ -18,6 +19,9 @@ Scriveno is best understood as **AI-native longform writing software built aroun
 
 ```bash
 npx scriveno@latest
+
+# Optional project status check
+scriveno status --project .
 ```
 
 ---
@@ -68,6 +72,19 @@ If you want the shortest proof-first route, read [Proof Artifacts](docs/proof-ar
 
 ---
 
+## Proactive status
+
+Scriveno ships a shared read-only status engine for every installer target. The public CLI is:
+
+```bash
+scriveno status --project .
+scriveno status . --json
+```
+
+It inspects disk evidence such as `.manuscript/`, `STATE.md`, `CONTEXT.md`, review files, translation work, exports, and history, then recommends the safest next command. The engine does not mutate files and does not spawn agents by itself. Command surfaces such as `/scr-next`, `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` call it when local command execution is available, then fall back to embedded markdown logic when a host cannot run Node. See [Auto-Invoke Policy](docs/auto-invoke-policy.md) and [Runtime Support](docs/runtime-support.md#shared-auto-invoke-engine).
+
+---
+
 ## The Voice DNA system
 
 Scriveno's core insight: drafted prose should sound like *you*, not like an AI. Before drafting begins, `/scr:profile-writer` builds a detailed voice profile across 15+ dimensions:
@@ -171,6 +188,7 @@ Scriveno is built on five principles:
 - [Contributing](docs/contributing.md) -- How to add commands, agents, work types, and templates
 - [Architecture](docs/architecture.md) -- How Scriveno works under the hood
 - [Configuration](docs/configuration.md) -- Package, installer, constraints, and `.manuscript/config.json` surfaces
+- [Auto-Invoke Policy](docs/auto-invoke-policy.md) -- Shared status engine, visible automation status, and agent-spawn boundaries
 - [Development](docs/development.md) -- Contributor workflow for changing commands, templates, installer logic, and docs
 - [Testing](docs/testing.md) -- What the test suite covers and which checks to run before shipping
 - [Release Notes](docs/release-notes.md) -- Public summary of what changed between package releases
@@ -195,7 +213,7 @@ Scriveno currently ships installer targets for these AI tooling environments:
 - **Perplexity Desktop** (guided local-MCP setup)
 - **Generic (SKILL.md)** fallback
 
-**Installer baseline:** `Node.js >=20.0.0` for `npx scriveno@latest` and `bin/install.js`. For new installs, use a currently supported LTS such as Node.js 24; Node.js 20 is now a compatibility floor, not the recommended fresh-install target.
+**Installer baseline:** `Node.js >=20.0.0` for `npx scriveno@latest`, `bin/install.js`, and `scriveno status --project .`. For new installs, use a currently supported LTS such as Node.js 24; Node.js 20 is now a compatibility floor, not the recommended fresh-install target.
 
 **Support note:** Claude Code is the primary reference runtime and now installs a flat `/scr-*` command surface. The environments listed above are installer targets, not a claim that every host runtime has verified parity today. Codex currently installs a skill-native `$scr-*` surface, while Perplexity Desktop is a guided local-MCP target rather than a writable command runtime. See the [runtime compatibility matrix](docs/runtime-support.md) for install type, support level, and verification status.
 
@@ -203,11 +221,11 @@ Scriveno currently ships installer targets for these AI tooling environments:
 
 ## Status
 
-**Version:** 2.0.7
+**Version:** 2.0.8
 
- 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, and proactive auto-invoke visibility work through `2.0.7`. See [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 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, and the shared `scriveno status --project .` auto-invoke engine through `2.0.8`. See [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.7` 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.0.8` 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

@@ -6,6 +6,7 @@ const os = require('os');
 const readline = require('readline');
 const crypto = require('crypto');
 const architecturalProfiles = require('../lib/architectural-profiles.js');
+const autoInvokeEngine = require('../lib/auto-invoke-engine.js');
 
 const PKG_ROOT = path.join(__dirname, '..');
 const PKG = require('../package.json');
@@ -820,6 +821,8 @@ function printHelp() {
   console.log(BANNER);
   console.log(`Usage:
   scriveno
+  scriveno status --project .
+  scriveno status . --json
   scriveno --runtimes codex,claude-code --global --writer --silent
 
 Options:
@@ -834,6 +837,12 @@ Options:
   --help              Show this help text
   --version           Show the Scriveno package version
 
+Status options:
+  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)
+  --json              Print machine-readable status JSON
+
 Runtime keys:
   ${Object.keys(RUNTIMES).join(', ')}
 `);
@@ -841,6 +850,7 @@ Runtime keys:
 
 function parseArgs(argv) {
   const options = {
+    command: 'install',
     runtimeKeys: [],
     installDetected: false,
     isGlobal: null,
@@ -848,8 +858,44 @@ function parseArgs(argv) {
     silent: false,
     showHelp: false,
     showVersion: false,
+    statusProjectRoot: process.cwd(),
+    statusTrigger: 'scriveno status',
+    statusJson: false,
   };
 
+  if (argv[0] === 'status') {
+    options.command = 'status';
+    for (let i = 1; i < argv.length; i++) {
+      const arg = argv[i];
+      if (arg === '--help' || arg === '-h') {
+        options.showHelp = true;
+      } else if (arg === '--version' || arg === '-v') {
+        options.showVersion = true;
+      } else if (arg === '--json') {
+        options.statusJson = true;
+      } else if (arg === '--project') {
+        const value = argv[i + 1];
+        if (!value) throw new Error('--project requires a value for status');
+        options.statusProjectRoot = value;
+        i++;
+      } else if (arg.startsWith('--project=')) {
+        options.statusProjectRoot = arg.slice('--project='.length);
+      } else if (arg === '--trigger') {
+        const value = argv[i + 1];
+        if (!value) throw new Error('--trigger requires a value');
+        options.statusTrigger = value;
+        i++;
+      } else if (arg.startsWith('--trigger=')) {
+        options.statusTrigger = arg.slice('--trigger='.length);
+      } else if (arg.startsWith('-')) {
+        throw new Error(`Unknown status argument "${arg}"`);
+      } else {
+        options.statusProjectRoot = arg;
+      }
+    }
+    return options;
+  }
+
   function addRuntimeList(value) {
     for (const key of String(value).split(',').map((item) => item.trim()).filter(Boolean)) {
       if (!Object.prototype.hasOwnProperty.call(RUNTIMES, key)) {
@@ -901,6 +947,16 @@ function parseArgs(argv) {
   return options;
 }
 
+function runStatus({ projectRoot, trigger, json }) {
+  const analysis = autoInvokeEngine.analyzeProject(projectRoot);
+  if (json) {
+    console.log(JSON.stringify(analysis, null, 2));
+  } else {
+    console.log(autoInvokeEngine.formatReport(analysis, { trigger }));
+  }
+  return analysis;
+}
+
 function resolveInstallRequest(parsed, detectedRuntimeKeys, { isTTY }) {
   const hasRuntimeDirective = parsed.runtimeKeys.length > 0 || parsed.installDetected;
   const hasModifierOverrides = parsed.isGlobal !== null || parsed.developerMode !== null;
@@ -1324,6 +1380,15 @@ async function main() {
     return;
   }
 
+  if (parsed.command === 'status') {
+    runStatus({
+      projectRoot: parsed.statusProjectRoot,
+      trigger: parsed.statusTrigger,
+      json: parsed.statusJson,
+    });
+    return;
+  }
+
   const detectedRuntimeKeys = Object.entries(RUNTIMES).filter(([, runtime]) => runtime.detect()).map(([key]) => key);
   const installRequest = resolveInstallRequest(parsed, detectedRuntimeKeys, { isTTY: Boolean(process.stdin.isTTY) });
 
@@ -1545,11 +1610,13 @@ function installGuidedRuntime(runtime, isGlobal, dataDir, log) {
 function writeSharedAssets(dataDir, runtimeKeys, isGlobal, developerMode, installMode, log) {
   fs.mkdirSync(path.join(dataDir, 'templates'), { recursive: true });
   fs.mkdirSync(path.join(dataDir, 'data'), { recursive: true });
+  fs.mkdirSync(path.join(dataDir, 'lib'), { recursive: true });
   const templateResult = copyDirWithPreservation(path.join(PKG_ROOT, 'templates'), path.join(dataDir, 'templates'));
   const dataResult = copyDirWithPreservation(path.join(PKG_ROOT, 'data'), path.join(dataDir, 'data'));
+  const libResult = copyDirWithPreservation(path.join(PKG_ROOT, 'lib'), path.join(dataDir, 'lib'));
   const sum = (r) => r.fresh + r.replaced + r.backedUp;
-  log(`  ${c('green', 'OK')} ${sum(templateResult)} templates + ${sum(dataResult)} data files -> ${c('dim', dataDir)}`);
-  const totalBackedUp = templateResult.backedUp + dataResult.backedUp;
+  log(`  ${c('green', 'OK')} ${sum(templateResult)} templates + ${sum(dataResult)} data files + ${sum(libResult)} lib files -> ${c('dim', dataDir)}`);
+  const totalBackedUp = templateResult.backedUp + dataResult.backedUp + libResult.backedUp;
   if (totalBackedUp > 0) {
     log(`  ${c('yellow', 'i')} Preserved ${totalBackedUp} user-modified file(s) as .backup.<timestamp>`);
   }
@@ -1706,6 +1773,7 @@ module.exports = {
   RUNTIMES,
   parseArgs,
   resolveInstallRequest,
+  runStatus,
   collectCommandEntries,
   collectAgentEntries,
   assertNoSkillNameCollisions,
@@ -1754,4 +1822,10 @@ module.exports = {
   // Per-work-type pitfall packs
   listPitfallPacks: architecturalProfiles.listPitfallPacks,
   getPitfallPackPath: architecturalProfiles.getPitfallPackPath,
+  // Shared proactive status engine
+  autoInvokeEngine,
+  analyzeProject: autoInvokeEngine.analyzeProject,
+  formatAutoInvokeReport: autoInvokeEngine.formatReport,
+  getRuntimeAgentSupport: autoInvokeEngine.getRuntimeAgentSupport,
+  listRuntimeAgentSupport: autoInvokeEngine.listRuntimeAgentSupport,
 };

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

package/commands/scr/next.md

@@ -8,6 +8,17 @@ You are routing the writer to the right next step in their workflow. This comman
 
 Follow the auto-invoke policy. In the source repository it is documented at `docs/auto-invoke-policy.md`. `/scr:next` is Level 1 only by default: it may inspect disk state and suggest the safest next command, but it does not spawn agents or mutate files unless autopilot mode explicitly routes into another command.
 
+Use the shared executable engine before falling back to manual inspection. Try the first available path:
+
+```bash
+scriveno status --project "$PWD" --trigger /scr:next
+node lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:next
+node "$HOME/.scriveno/lib/auto-invoke-engine.js" --project "$PWD" --trigger /scr:next
+node .scriveno/lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:next
+```
+
+This engine is installed into Scriveno shared assets for every runtime, including Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic skill fallback. If the engine is not present, perform the read-only sweep below.
+
 ## What to do
 
 1. **Check for `.manuscript/` directory.** If none, the writer has no project. Run `/scr:new-work` to start one (or tell them to).

package/commands/scr/progress.md

@@ -9,6 +9,17 @@ You are showing the writer their current project progress.
 
 Follow the auto-invoke policy. In the source repository it is documented at `docs/auto-invoke-policy.md`. `/scr:progress` is read-only: it can count, compare, and recommend, but it must not spawn agents or write files.
 
+Use the shared executable engine before falling back to manual counts. Try the first available path:
+
+```bash
+scriveno status --project "$PWD" --trigger /scr:progress
+node lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:progress
+node "$HOME/.scriveno/lib/auto-invoke-engine.js" --project "$PWD" --trigger /scr:progress
+node .scriveno/lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:progress
+```
+
+This engine is installed into Scriveno shared assets for every runtime, including Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic skill fallback. If the engine is not present, perform the read-only progress logic below.
+
 ## Prerequisites
 
 - `.manuscript/STATE.md` must exist

package/commands/scr/session-report.md

@@ -9,6 +9,17 @@ You are summarizing the writer's current session. Your job is to compute actiona
 
 Follow the auto-invoke policy. In the source repository it is documented at `docs/auto-invoke-policy.md`. `/scr:session-report` is read-only and does not spawn agents.
 
+Use the shared executable engine for the read-only status portion before computing session-specific metrics. Try the first available path:
+
+```bash
+scriveno status --project "$PWD" --trigger /scr:session-report
+node lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:session-report
+node "$HOME/.scriveno/lib/auto-invoke-engine.js" --project "$PWD" --trigger /scr:session-report
+node .scriveno/lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:session-report
+```
+
+This engine is installed into Scriveno shared assets for every runtime, including Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic skill fallback. If the engine is not present, continue with the read-only report logic below.
+
 ## What to do
 
 1. **Read STATE.md "Last actions" table** to get the full history of actions.

package/commands/scr/sync.md

@@ -11,6 +11,17 @@ This command is for local runtime drift: Codex skills, Codex command mirrors, Cl
 
 This is not a package upgrade command. Do not fetch a newer Scriveno release, do not change npm dependencies, and do not modify manuscript content. If the writer wants a newer published package version, that belongs to a future `/scr:update` command.
 
+The auto-invoke status engine is a shared runtime asset. It is copied for every install target and can be checked with one of these paths:
+
+```bash
+scriveno status --project "$PWD" --trigger /scr:sync
+node lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:sync
+node "$HOME/.scriveno/lib/auto-invoke-engine.js" --project "$PWD" --trigger /scr:sync
+node .scriveno/lib/auto-invoke-engine.js --project "$PWD" --trigger /scr:sync
+```
+
+Use it for read-only project status and next-command reasoning. Use `bin/install.js` for runtime file synchronization.
+
 ## Prerequisites
 
 - Node.js >=20.0.0

package/data/CONSTRAINTS.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./constraints.schema.json",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "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."

package/docs/architecture.md

@@ -349,6 +349,12 @@ Codex uses a skill-native variation of this strategy. The installer generates on
 
 **Guided local-MCP (type: `guided-mcp`).** Writes setup assets and connector recipes for runtimes that expose a documented local-MCP surface instead of a writable slash-command directory. Perplexity Desktop currently fits this model: Scriveno writes a setup guide and filesystem-server command recipe under `.scriveno/perplexity/`, and the user adds that command inside Perplexity Desktop's Connectors UI.
 
+### Shared status engine
+
+Scriveno also ships `lib/auto-invoke-engine.js`, exposed through `scriveno status --project .` and `scriveno status . --json`. The installer copies this library into the shared Scriveno asset directory for global and project installs, so command surfaces can call a single read-only status engine before falling back to embedded markdown logic.
+
+The engine checks disk evidence only: project presence, STATE.md, CONTEXT.md freshness, review files, translation work, exports, history, and save signals. It recommends the next command, but it does not mutate files and does not spawn agents by itself. That boundary keeps proactive behavior portable across Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic fallback.
+
 ### Installation modes
 
 The installer supports two scopes:
@@ -360,7 +366,7 @@ The user chooses during installation. Guided local-MCP targets still write their
 
 ### Runtime credibility
 
-Scriveno's installer compatibility floor is `Node.js >=20.0.0`. For new installs, prefer a currently supported LTS such as Node.js 24. The compatibility floor applies to `npx scriveno@latest`, `bin/install.js`, and the repo's JavaScript test suite, not to the markdown command system once files are installed.
+Scriveno's installer compatibility floor is `Node.js >=20.0.0`. For new installs, prefer a currently supported LTS such as Node.js 24. The compatibility floor applies to `npx scriveno@latest`, `bin/install.js`, `scriveno status --project .`, the shared status engine, and the repo's JavaScript test suite, not to the markdown command system once files are installed.
 
 This architecture doc is intentionally about mechanics: detection rules, install path shapes, `commands` versus `skills` versus `guided-mcp`, and global versus project scope. For the authoritative runtime matrix, support levels, and verification status, see [`docs/runtime-support.md`](runtime-support.md).
 

package/docs/auto-invoke-policy.md

@@ -2,6 +2,8 @@
 
 Scriveno can be proactive, but it must be proactive from disk evidence. Commands should inspect `.manuscript/`, reports, timestamps, config, and installed runtime surfaces before choosing an automatic helper.
 
+The executable policy lives in `lib/auto-invoke-engine.js` and is exposed through `scriveno status --project .`. The installer copies it to `.scriveno/lib/auto-invoke-engine.js` for project installs and `~/.scriveno/lib/auto-invoke-engine.js` for global installs, so every runtime can use the same read-only status logic.
+
 ## Cross-Platform Agent Rules
 
 Scriveno agent prompts live in `agents/*.md`. Each host runtime exposes them differently:
@@ -10,6 +12,7 @@ Scriveno agent prompts live in `agents/*.md`. Each host runtime exposes them dif
 - Codex installs `$scr-*` skills, mirrored command files, agent prompts, and `.toml` metadata so Codex can expose agent types.
 - Cursor, Gemini CLI, OpenCode, Copilot, Windsurf, and Antigravity install nested command directories and agent prompts in their runtime-specific agent directories.
 - Manus and the generic skill runtime bundle `SKILL.md`, commands, and agents inside the skill directory.
+- All runtimes share the same installed auto-invoke engine under the Scriveno shared asset directory.
 
 When a host supports native fresh-context spawning, use the native agent or subagent mechanism. When it does not, load the installed agent prompt from the active runtime and run it in an isolated fresh context. When the action is only a file operation, report `Agent: none`.
 

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

package/docs/getting-started.md

@@ -24,6 +24,15 @@ This installs Scriveno into the runtime you choose. Command-directory and skills
 
 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.
 
+You can also ask Scriveno for a read-only project status from any terminal:
+
+```
+scriveno status --project .
+scriveno status . --json
+```
+
+That status command is the same shared auto-invoke engine used by `/scr-next`, `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` when local command execution is available. It recommends the next safest command, but does not mutate files or spawn agents by itself.
+
 ## Step 2: Explore the Demo (Optional)
 
 Not sure what Scriveno does? Try the demo before starting your own project:
@@ -181,6 +190,8 @@ $scr-next
 
 `/scr-next` reads your project state and runs the right next step automatically. A writer who only ever types `/scr-next` in Claude Code can complete an entire manuscript from start to finish.
 
+For a terminal-readable version of the same project-state reasoning, run `scriveno status --project .`.
+
 Beyond the core workflow, Scriveno offers:
 
 - **Revision** -- `/scr-editor-review`, `/scr-line-edit`, `/scr-continuity-check`
@@ -194,5 +205,6 @@ For the full command list, see [Command Reference](command-reference.md).
 If you want the trust surfaces around installation and shipping details, continue with:
 
 - [Runtime Support](runtime-support.md) -- installer targets, support levels, and verification status
+- [Auto-Invoke Policy](auto-invoke-policy.md) -- status engine, visible automation, and agent-spawn boundaries
 - [Shipped Assets](shipped-assets.md) -- what the npm package actually includes on the trust-critical surface
 - [Release Notes](release-notes.md) -- what changed in the latest package release

package/docs/release-notes.md

@@ -2,6 +2,41 @@
 
 This document is the public-facing summary of what changed between package releases. For package history, see the root [CHANGELOG](../CHANGELOG.md).
 
+## 2.0.8 - 2026-05-16
+
+### What changed
+
+- Scriveno now exposes proactive project status through `scriveno status --project .` and `scriveno status . --json`.
+- A shared read-only engine at `lib/auto-invoke-engine.js` computes status from disk evidence and recommends the safest next command.
+- The installer copies the engine into Scriveno shared assets for global and project installs, so Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Windsurf, Antigravity, Manus, Perplexity Desktop, and the generic fallback can share the same status contract.
+- `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` now try the public status CLI first, then fall back to source, global, or project engine paths.
+- The README now includes a status CLI badge, quick-start status command, proactive status section, and a direct Auto-Invoke Policy link.
+- Package and shipped metadata are aligned on `2.0.8`.
+
+### Why it matters
+
+The previous release made automation visible. This release makes the safest read-only part executable as a real package surface. Users and host runtimes can now ask Scriveno what the project needs next without relying on a hidden background process or a Codex-only path.
+
+The engine still does not mutate files or spawn agents by itself. It gives a consistent, inspectable status answer; command workflows decide what to run next.
+
+### Affected areas
+
+- public CLI
+- shared auto-invoke engine
+- installer shared assets
+- `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync`
+- README badges and launch copy
+- runtime support and auto-invoke documentation
+- release metadata and package contents
+- regression tests for CLI output, JSON output, install assets, and package inclusion
+
+### Verification
+
+- `node --test`
+- `npm run release:check`
+- `npm pack --dry-run --json`
+- `git diff --check`
+
 ## 2.0.7 - 2026-05-16
 
 ### What changed

package/docs/runtime-support.md

@@ -10,9 +10,11 @@ Node is required for:
 
 - running `npx scriveno@latest`
 - executing `bin/install.js`
+- running `scriveno status --project .`
+- executing the shared auto-invoke status engine at `lib/auto-invoke-engine.js`
 - running the repo's JavaScript test suite
 
-Node is not a runtime dependency for Scriveno's markdown command system itself. Once installed, Scriveno's command files, agent prompts, templates, and constraints are read by the host AI coding agent.
+Node is not a runtime dependency for Scriveno's markdown command system itself. Once installed, Scriveno's command files, agent prompts, templates, constraints, and shared auto-invoke engine are read by the host AI coding agent. Runtimes that can run local shell commands can call the engine directly; runtimes that cannot should use the same command text as a fallback contract.
 
 ## Evidence Levels
 
@@ -61,6 +63,25 @@ Node is not a runtime dependency for Scriveno's markdown command system itself.
 - Manus Desktop and the generic skills fallback install a manifest `SKILL.md`, mirrored command files, and agent prompts inside the skill bundle.
 - Perplexity Desktop receives setup assets for a local-MCP connector. It does not receive writable command or agent prompt directories from the installer.
 
+## Shared Auto-Invoke Engine
+
+Every install target receives the same read-only status engine through Scriveno's shared asset directory:
+
+- global installs: `~/.scriveno/lib/auto-invoke-engine.js`
+- project installs: `.scriveno/lib/auto-invoke-engine.js`
+- source checkouts: `lib/auto-invoke-engine.js`
+
+The engine computes proactive state from disk evidence: missing or stale context, unresolved review files, translation work, stale exports, missing history, and the recommended next command. It does not mutate manuscript files and does not spawn agents. Host commands such as `/scr:next`, `/scr:progress`, `/scr:session-report`, and `/scr:sync` should call it first when local command execution is available, then fall back to their embedded markdown logic when the host cannot run Node.
+
+The public CLI entrypoint is:
+
+```bash
+scriveno status --project .
+scriveno status . --json
+```
+
+The JSON form is intended for CI, host adapters, and future runtime smoke tests.
+
 ## What Scriveno Proves Today
 
 Scriveno currently proves all of the following in-repo:

package/lib/auto-invoke-engine.js

@@ -0,0 +1,520 @@
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_RUNTIME_SUPPORT = {
+  'claude-code': {
+    label: 'Claude Code',
+    surface: 'flat commands plus agent prompts',
+    nativeSpawn: 'host-supported when Claude Code exposes agents',
+    fallback: 'load prompt from .claude/agents',
+    metadata: 'none',
+  },
+  codex: {
+    label: 'Codex',
+    surface: 'skills, command mirrors, agent prompts, and metadata',
+    nativeSpawn: 'host-supported when Codex exposes agent roles',
+    fallback: 'load prompt from .codex/agents',
+    metadata: 'toml',
+  },
+  cursor: {
+    label: 'Cursor',
+    surface: 'nested commands plus agent prompts',
+    nativeSpawn: 'host-supported when Cursor exposes agents',
+    fallback: 'load prompt from .cursor/agents',
+    metadata: 'none',
+  },
+  'gemini-cli': {
+    label: 'Gemini CLI',
+    surface: 'nested commands plus agent prompts',
+    nativeSpawn: 'host-supported when Gemini CLI exposes agents',
+    fallback: 'load prompt from .gemini/agents',
+    metadata: 'none',
+  },
+  opencode: {
+    label: 'OpenCode',
+    surface: 'nested commands plus agent prompts',
+    nativeSpawn: 'host-supported when OpenCode exposes agents',
+    fallback: 'load prompt from .config/opencode/agents',
+    metadata: 'none',
+  },
+  copilot: {
+    label: 'GitHub Copilot',
+    surface: 'nested commands plus agent prompts',
+    nativeSpawn: 'host-supported when Copilot exposes agents',
+    fallback: 'load prompt from .github/agents',
+    metadata: 'none',
+  },
+  windsurf: {
+    label: 'Windsurf',
+    surface: 'nested commands plus agent prompts',
+    nativeSpawn: 'host-supported when Windsurf exposes agents',
+    fallback: 'load prompt from .windsurf/agents',
+    metadata: 'none',
+  },
+  antigravity: {
+    label: 'Antigravity',
+    surface: 'nested commands plus agent prompts',
+    nativeSpawn: 'host-supported when Antigravity exposes agents',
+    fallback: 'load prompt from .gemini/antigravity/agents',
+    metadata: 'none',
+  },
+  manus: {
+    label: 'Manus Desktop',
+    surface: 'bundled skill, mirrored commands, and agent prompts',
+    nativeSpawn: 'host-supported when Manus exposes skill agents',
+    fallback: 'load prompt from bundled agents directory',
+    metadata: 'none',
+  },
+  'perplexity-desktop': {
+    label: 'Perplexity Desktop',
+    surface: 'guided local MCP setup',
+    nativeSpawn: 'not assumed',
+    fallback: 'read project files through the filesystem connector',
+    metadata: 'none',
+  },
+  generic: {
+    label: 'Generic (SKILL.md)',
+    surface: 'bundled skill, mirrored commands, and agent prompts',
+    nativeSpawn: 'not assumed',
+    fallback: 'load prompt from bundled agents directory',
+    metadata: 'none',
+  },
+};
+
+const REVIEW_KEYWORDS = [
+  'TODO',
+  'FIXME',
+  'UNRESOLVED',
+  'NEEDS REVISION',
+  'QUESTION: Blocking',
+  'VOICE DRIFT',
+  'CONTINUITY',
+];
+
+function pathExists(filePath) {
+  try {
+    fs.accessSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function safeStat(filePath) {
+  try {
+    return fs.statSync(filePath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function readText(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return '';
+    throw err;
+  }
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    if (err instanceof SyntaxError) return null;
+    throw err;
+  }
+}
+
+function listFiles(dir, options = {}) {
+  const { extensions = null, recursive = true } = options;
+  if (!pathExists(dir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (recursive) out.push(...listFiles(fullPath, options));
+    } else if (!extensions || extensions.includes(path.extname(entry.name))) {
+      out.push(fullPath);
+    }
+  }
+  return out;
+}
+
+function newestMtime(files) {
+  let newest = 0;
+  for (const file of files) {
+    const stat = safeStat(file);
+    if (stat && stat.mtimeMs > newest) newest = stat.mtimeMs;
+  }
+  return newest;
+}
+
+function countMarkdownFiles(dir) {
+  return listFiles(dir, { extensions: ['.md'], recursive: true }).length;
+}
+
+function containsAny(text, keywords) {
+  const haystack = text.toUpperCase();
+  return keywords.some((keyword) => haystack.includes(keyword.toUpperCase()));
+}
+
+function scanReviewSignals(manuscriptDir) {
+  const reviewDirs = [
+    'reviews',
+    'reports',
+    'voice',
+    'continuity',
+    'translation',
+  ].map((name) => path.join(manuscriptDir, name));
+  const files = reviewDirs.flatMap((dir) => listFiles(dir, { extensions: ['.md', '.txt'], recursive: true }));
+  const pending = [];
+  for (const file of files) {
+    const text = readText(file);
+    if (containsAny(text, REVIEW_KEYWORDS)) {
+      pending.push(path.relative(manuscriptDir, file));
+    }
+  }
+  return pending;
+}
+
+function findNewestOutput(manuscriptDir) {
+  const outputDirs = [
+    path.join(manuscriptDir, 'output'),
+    path.join(manuscriptDir, 'build'),
+    path.join(manuscriptDir, 'exports'),
+  ];
+  return newestMtime(outputDirs.flatMap((dir) => listFiles(dir, { recursive: true })));
+}
+
+function detectTranslationSignal(manuscriptDir, config) {
+  const translationDir = path.join(manuscriptDir, 'translation');
+  const configuredTargets = [
+    ...(Array.isArray(config?.target_languages) ? config.target_languages : []),
+    ...(Array.isArray(config?.translation?.target_languages) ? config.translation.target_languages : []),
+    ...(Array.isArray(config?.translations) ? config.translations : []),
+  ];
+  const translationFiles = listFiles(translationDir, { recursive: true });
+  if (translationFiles.length > 0 || configuredTargets.length > 0) {
+    return {
+      state: 'follow-up available',
+      count: translationFiles.length,
+      configuredTargets,
+    };
+  }
+  return {
+    state: 'none',
+    count: 0,
+    configuredTargets: [],
+  };
+}
+
+function detectHistorySignal(manuscriptDir) {
+  const historyPath = path.join(manuscriptDir, 'HISTORY.log');
+  if (!pathExists(historyPath)) {
+    return { state: 'missing', lastFailed: false };
+  }
+  const lines = readText(historyPath).split(/\r?\n/).filter(Boolean);
+  const last = lines[lines.length - 1] || '';
+  return {
+    state: 'present',
+    lastFailed: /\b(fail|failed|error|blocked)\b/i.test(last),
+  };
+}
+
+function detectContextSignal(manuscriptDir, draftFiles) {
+  const contextPath = path.join(manuscriptDir, 'CONTEXT.md');
+  const statePath = path.join(manuscriptDir, 'STATE.md');
+  const contextStat = safeStat(contextPath);
+  const stateStat = safeStat(statePath);
+  const newestDraft = newestMtime(draftFiles);
+
+  if (!contextStat) {
+    return { state: 'missing', suggest: '/scr:save' };
+  }
+  if (stateStat && contextStat.mtimeMs < stateStat.mtimeMs) {
+    return { state: 'stale', suggest: '/scr:scan' };
+  }
+  if (newestDraft > 0 && contextStat.mtimeMs < newestDraft) {
+    return { state: 'stale', suggest: '/scr:save' };
+  }
+  return { state: 'fresh', suggest: null };
+}
+
+function detectExportSignal(manuscriptDir, sourceFiles) {
+  const newestSource = newestMtime(sourceFiles);
+  const newestOutput = findNewestOutput(manuscriptDir);
+  if (newestOutput === 0) {
+    return { state: sourceFiles.length ? 'missing' : 'none', suggest: sourceFiles.length ? '/scr:export' : null };
+  }
+  if (newestSource > newestOutput) {
+    return { state: 'stale', suggest: '/scr:export' };
+  }
+  return { state: 'fresh', suggest: null };
+}
+
+function detectSaveSignal(historySignal, draftFiles) {
+  if (draftFiles.length === 0) return { state: 'clean', suggest: null };
+  if (historySignal.state === 'missing') return { state: 'unsaved manuscript changes', suggest: '/scr:save' };
+  return { state: 'clean', suggest: null };
+}
+
+function chooseRecommendation(signals, counts) {
+  if (!signals.hasProject) {
+    return {
+      command: '/scr:new-work',
+      reason: 'No .manuscript directory was found.',
+      alternatives: ['/scr:demo', '/scr:import', '/scr:profile-writer'],
+    };
+  }
+  if (!signals.hasState) {
+    return {
+      command: '/scr:scan',
+      reason: 'The project is missing STATE.md.',
+      alternatives: ['/scr:health', '/scr:next'],
+    };
+  }
+  if (signals.history.lastFailed) {
+    return {
+      command: '/scr:troubleshoot',
+      reason: 'The last history entry appears to have failed.',
+      alternatives: ['/scr:scan', '/scr:health'],
+    };
+  }
+  if (signals.context.state === 'stale') {
+    return {
+      command: signals.context.suggest || '/scr:scan',
+      reason: 'CONTEXT.md is older than the current project state.',
+      alternatives: ['/scr:progress', '/scr:resume-work'],
+    };
+  }
+  if (signals.reviews.count > 0) {
+    return {
+      command: '/scr:editor-review',
+      reason: `${signals.reviews.count} review signal(s) still look unresolved.`,
+      alternatives: ['/scr:voice-check', '/scr:continuity-check', '/scr:progress'],
+    };
+  }
+  if (counts.drafts === 0) {
+    return {
+      command: '/scr:plan',
+      reason: 'No draft files were found yet.',
+      alternatives: ['/scr:discuss', '/scr:draft', '/scr:voice-test'],
+    };
+  }
+  if (signals.translation.state !== 'none') {
+    return {
+      command: '/scr:back-translate',
+      reason: 'Translation work exists and may need a verification pass.',
+      alternatives: ['/scr:cultural-adaptation', '/scr:multi-publish', '/scr:progress'],
+    };
+  }
+  if (signals.export.state === 'stale' || signals.export.state === 'missing') {
+    return {
+      command: signals.export.suggest || '/scr:export',
+      reason: `Export output is ${signals.export.state}.`,
+      alternatives: ['/scr:publish', '/scr:progress', '/scr:save'],
+    };
+  }
+  if (signals.save.state !== 'clean') {
+    return {
+      command: signals.save.suggest || '/scr:save',
+      reason: 'Draft files exist without a current history signal.',
+      alternatives: ['/scr:progress', '/scr:scan'],
+    };
+  }
+  return {
+    command: '/scr:next',
+    reason: 'Project state looks consistent; continue with the lifecycle route.',
+    alternatives: ['/scr:progress', '/scr:editor-review', '/scr:save'],
+  };
+}
+
+function analyzeProject(projectRoot = process.cwd(), options = {}) {
+  const root = path.resolve(projectRoot);
+  const manuscriptDir = options.manuscriptDir || path.join(root, '.manuscript');
+  const hasProject = pathExists(manuscriptDir);
+  const statePath = path.join(manuscriptDir, 'STATE.md');
+  const config = readJson(path.join(manuscriptDir, 'config.json')) || {};
+
+  if (!hasProject) {
+    const signals = {
+      hasProject: false,
+      hasState: false,
+      context: { state: 'none', suggest: null },
+      history: { state: 'none', lastFailed: false },
+      reviews: { state: 'none', count: 0, files: [] },
+      translation: { state: 'none', count: 0, configuredTargets: [] },
+      export: { state: 'none', suggest: null },
+      save: { state: 'clean', suggest: null },
+    };
+    const recommendation = chooseRecommendation(signals, { drafts: 0 });
+    return {
+      projectRoot: root,
+      manuscriptDir,
+      commandUnit: config.command_unit || 'unit',
+      workType: config.work_type || '',
+      counts: { drafts: 0, plans: 0, reviews: 0 },
+      signals,
+      recommendation,
+    };
+  }
+
+  const draftFiles = listFiles(path.join(manuscriptDir, 'drafts'), { extensions: ['.md'], recursive: true });
+  const planCount = countMarkdownFiles(path.join(manuscriptDir, 'plans'));
+  const reviewFiles = scanReviewSignals(manuscriptDir);
+  const historySignal = detectHistorySignal(manuscriptDir);
+  const sourceFiles = [
+    statePath,
+    path.join(manuscriptDir, 'OUTLINE.md'),
+    path.join(manuscriptDir, 'RECORD.md'),
+    path.join(manuscriptDir, 'STYLE-GUIDE.md'),
+    ...draftFiles,
+  ].filter(pathExists);
+
+  const signals = {
+    hasProject: true,
+    hasState: pathExists(statePath),
+    context: detectContextSignal(manuscriptDir, draftFiles),
+    history: historySignal,
+    reviews: {
+      state: reviewFiles.length ? 'pending' : 'none',
+      count: reviewFiles.length,
+      files: reviewFiles,
+    },
+    translation: detectTranslationSignal(manuscriptDir, config),
+    export: detectExportSignal(manuscriptDir, sourceFiles),
+    save: detectSaveSignal(historySignal, draftFiles),
+  };
+  const counts = {
+    drafts: draftFiles.length,
+    plans: planCount,
+    reviews: reviewFiles.length,
+  };
+  const recommendation = chooseRecommendation(signals, counts);
+  return {
+    projectRoot: root,
+    manuscriptDir,
+    commandUnit: config.command_unit || 'unit',
+    workType: config.work_type || '',
+    counts,
+    signals,
+    recommendation,
+  };
+}
+
+function formatProactiveChecks(analysis) {
+  const { signals } = analysis;
+  const stateLine = signals.hasProject
+    ? `  State: ${signals.hasState ? 'fresh' : 'missing, suggest /scr:scan'}`
+    : '  Project: missing, suggest /scr:new-work';
+  return [
+    'Proactive checks:',
+    stateLine,
+    `  Session: ${signals.context.state}${signals.context.suggest ? `, suggest ${signals.context.suggest}` : ''}`,
+    `  Reviews: ${signals.reviews.count ? `${signals.reviews.count} pending, suggest /scr:editor-review` : 'none'}`,
+    `  Translation: ${signals.translation.state}`,
+    `  Export: ${signals.export.state}${signals.export.suggest ? `, suggest ${signals.export.suggest}` : ''}`,
+    `  Save: ${signals.save.state}${signals.save.suggest ? `, suggest ${signals.save.suggest}` : ''}`,
+  ].join('\n');
+}
+
+function formatAutomationStatus(analysis, options = {}) {
+  const trigger = options.trigger || '/scr:next';
+  const localOperation = options.localOperation || 'auto-invoke engine: read-only';
+  const autoInvoked = options.autoInvoked || `${analysis.recommendation.command}: no`;
+  return [
+    'Automation status:',
+    `Trigger: ${trigger}`,
+    'Spawned agents:',
+    '- none',
+    'Local operations:',
+    `- ${localOperation}`,
+    `- state route computed: ${analysis.signals.hasProject ? 'yes' : 'no project'}`,
+    'Auto-invoked:',
+    `- ${autoInvoked}`,
+    `Why: ${analysis.recommendation.reason}`,
+  ].join('\n');
+}
+
+function formatRecommendation(analysis) {
+  const lines = [
+    `${analysis.recommendation.command} is the recommended next command.`,
+    analysis.recommendation.reason,
+    '',
+    'Next commands:',
+    `- \`${analysis.recommendation.command}\`: Run the highest-confidence next step from disk state.`,
+  ];
+  for (const command of analysis.recommendation.alternatives.slice(0, 3)) {
+    lines.push(`- \`${command}\`: Use this alternate path if it better matches the writer's intent.`);
+  }
+  return lines.join('\n');
+}
+
+function formatReport(analysis, options = {}) {
+  return [
+    formatProactiveChecks(analysis),
+    '',
+    formatAutomationStatus(analysis, options),
+    '',
+    formatRecommendation(analysis),
+  ].join('\n');
+}
+
+function getRuntimeAgentSupport(runtimeKey) {
+  return DEFAULT_RUNTIME_SUPPORT[runtimeKey] || null;
+}
+
+function listRuntimeAgentSupport() {
+  return Object.entries(DEFAULT_RUNTIME_SUPPORT).map(([key, value]) => ({
+    key,
+    ...value,
+  }));
+}
+
+function parseCliArgs(argv) {
+  const out = {
+    projectRoot: process.cwd(),
+    trigger: '/scr:next',
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--project') {
+      out.projectRoot = argv[++i] || out.projectRoot;
+    } else if (arg.startsWith('--project=')) {
+      out.projectRoot = arg.slice('--project='.length);
+    } else if (arg === '--trigger') {
+      out.trigger = argv[++i] || out.trigger;
+    } else if (arg.startsWith('--trigger=')) {
+      out.trigger = arg.slice('--trigger='.length);
+    } else if (arg === '--json') {
+      out.json = true;
+    }
+  }
+  return out;
+}
+
+if (require.main === module) {
+  const args = parseCliArgs(process.argv.slice(2));
+  const analysis = analyzeProject(args.projectRoot);
+  if (args.json) {
+    console.log(JSON.stringify(analysis, null, 2));
+  } else {
+    console.log(formatReport(analysis, { trigger: args.trigger }));
+  }
+}
+
+module.exports = {
+  DEFAULT_RUNTIME_SUPPORT,
+  analyzeProject,
+  formatProactiveChecks,
+  formatAutomationStatus,
+  formatRecommendation,
+  formatReport,
+  getRuntimeAgentSupport,
+  listRuntimeAgentSupport,
+  parseCliArgs,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scriveno",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "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.7",
+  "scriveno_version": "2.0.8",
   "work_type": "",
   "group": "",
   "command_unit": "",