scriveno 2.0.5

package/docs/configuration.md

@@ -0,0 +1,228 @@
+# Configuration
+
+This guide covers the configuration surfaces Scriveno actually ships today: package-level installer metadata, shared constraint data, runtime install targets, and per-project `.manuscript/config.json`.
+
+## What is configurable
+
+Scriveno is intentionally narrow in where configuration lives:
+
+- `package.json` defines the npm package metadata, installer entrypoint, and supported Node baseline
+- `data/CONSTRAINTS.json` is the central registry for work types, command availability, adaptive terminology, and export rules
+- `bin/install.js` defines installer targets and where Scriveno writes commands, skills, agents, or guided setup assets
+- `.manuscript/config.json` stores project-specific writing settings after `/scr:new-work`
+
+There is no compiled app config, no environment-variable matrix for the core workflow, and no runtime dependency graph beyond Node.js for the installer.
+
+## Installer baseline
+
+The installer compatibility floor is:
+
+```json
+"engines": {
+  "node": ">=20.0.0"
+}
+```
+
+That same `>=20.0.0` floor is enforced in:
+
+- `package.json`
+- `bin/install.js`
+- `docs/runtime-support.md`
+
+For new installs, use a currently supported LTS release such as Node.js 24. Node.js 20 reached end of life on 2026-04-30, so it remains a compatibility floor, not the recommended fresh-install target.
+
+For runtime support details, use [Runtime Support](runtime-support.md). That document is the canonical compatibility matrix.
+
+## Shared Scriveno data
+
+Scriveno commands are designed to load the shared constraints file from an installed Scriveno location first:
+
+- global install: `~/.scriveno/data/CONSTRAINTS.json`
+- project install: `.scriveno/data/CONSTRAINTS.json`
+
+The repo-local copy at `data/CONSTRAINTS.json` is the authoring source of truth. The installer copies that data into the runtime-facing install location.
+
+`CONSTRAINTS.json` controls:
+
+- all 50 work types and 9 work-type groups
+- all shipped command registrations
+- adaptive renames and group-specific command behavior
+- export availability and prerequisite rules
+
+If a command or doc claim conflicts with `CONSTRAINTS.json`, fix the command or doc to match the constraints file.
+
+## Project config
+
+When a writer runs `/scr:new-work`, Scriveno creates `.manuscript/config.json`. The command file in [new-work.md](../commands/scr/new-work.md) defines the baseline shape:
+
+```json
+{
+  "scriveno_version": "2.0.5",
+  "work_type": "<chosen>",
+  "group": "<group>",
+  "command_unit": "<unit>",
+  "developer_mode": false,
+  "created_at": "<ISO timestamp>",
+  "autopilot": {
+    "enabled": false,
+    "profile": "guided"
+  }
+}
+```
+
+That `scriveno_version` value should track the current package release and the live `/scr:new-work` contract, not an older milestone snapshot.
+
+Every project gets those core keys. Additional blocks are added only when the work type requires them.
+
+### Technical writing projects
+
+Technical writing work types add a `technical` block seeded from `config_defaults` in `data/CONSTRAINTS.json`. That block is used to capture things like:
+
+- audience level
+- prerequisite knowledge
+- supported environment
+- supported versions
+- source-of-truth references
+- review mode
+
+Technical projects also swap in the specialized templates under `templates/technical/`.
+
+### Sacred and historical projects
+
+Sacred work types add top-level sacred profile keys seeded from `config_defaults` and `architectural_profiles.defaults_by_work_type.tradition`. New projects should not nest these values under a `sacred` object.
+
+The supported tradition profile slugs are:
+
+- `catholic`
+- `orthodox`
+- `tewahedo`
+- `protestant`
+- `jewish`
+- `islamic-hafs`
+- `islamic-warsh`
+- `pali`
+- `tibetan`
+- `sanskrit`
+
+Sacred project config can include:
+
+- `tradition`
+- `verse_numbering_system`
+- `calendar_system`
+- `translation_philosophy`
+- `canonical_alignment`
+- `annotation_traditions`
+- `doctrinal_framework`
+- `preserve_source_terms`
+- `transliteration_style`
+
+Sacred projects also load the template variants under `templates/sacred/`. Older projects with a nested `sacred` object are accepted as legacy input by commands that read these keys, but new projects should use the top-level shape.
+
+### Platform defaults
+
+Some work types can also set a top-level `platform`, seeded from `architectural_profiles.defaults_by_work_type.platform`. Ebook and print builders use this value when the writer does not pass `--platform`.
+
+The shipped ebook platform profile slugs are:
+
+- `kdp`
+- `ingram`
+- `apple`
+- `bn`
+- `d2d`
+- `kobo`
+- `google`
+- `smashwords`
+
+`/scr:build-ebook` validates the selected platform, loads `templates/platforms/{platform}/manifest.yaml`, checks that the manifest accepts EPUB, and carries the platform label plus `epub_variant` into the output metadata.
+
+### Drafter quality settings
+
+Starting in `1.6.0`, projects can include an optional `draft` block to tune how the drafter loads context and applies rule scaffolding. The block is optional; absent block falls back to the documented defaults.
+
+```json
+"draft": {
+  "rigor": "standard",
+  "context_profile": "standard",
+  "pitfalls_enabled": true
+}
+```
+
+- `draft.rigor`: `standard` (default) or `strict`. Strict prepends a per-sentence rules check, useful when routing to weaker models that need scaffolding to stay on-voice.
+- `draft.context_profile`: `minimal`, `standard` (default), or `full`. Controls how much context the drafter loads per atomic unit. Minimal trims THEMES, WORK, and off-stage CHARACTERS for short scenes; full loads cross-document references for sacred-work continuity.
+- `draft.pitfalls_enabled`: `true` (default) or `false`. When `false`, skip loading the per-work-type pitfall pack from `templates/pitfalls/<work_type>.md`. WRITING-RULES.md still loads. Use when the writer's voice deliberately leans into a trap (parody, pastiche, period voice).
+
+`/scr:settings` exposes all three knobs in its display and change flow. See [Drafter Quality](drafter-quality.md) for the full system, including model-tier recommendations and the override hierarchy (STYLE-GUIDE.md beats WRITING-RULES.md beats the pitfall pack).
+
+## Developer mode
+
+Scriveno defaults projects to:
+
+```json
+"developer_mode": false
+```
+
+That setting exists so non-technical writers can stay in writer-first language. In writer mode, Scriveno prefers terms like `save`, `version`, and `compare` instead of raw git terminology.
+
+The broader product behavior is described in [Getting Started](getting-started.md) and [README.md](../README.md). The repo does not currently ship a separate standalone developer-mode settings reference beyond the project config itself.
+
+## Installer targets
+
+`bin/install.js` currently defines 11 installer targets:
+
+- 8 command-directory runtimes
+- 2 skills or manifest-style runtimes
+- 1 guided local-MCP target for Perplexity Desktop
+
+The installer also decides whether the install is global or project-local and writes files into the matching runtime-specific directories. The target matrix and support framing live in [Runtime Support](runtime-support.md).
+
+Use `/scr:sync` when the source tree has changed and an installed runtime surface needs to be refreshed from that local source. Sync is intentionally narrower than update: it re-runs the installer for selected or detected runtimes and does not fetch a newer package release.
+
+## Export prerequisites
+
+Scriveno keeps export tools out of `package.json`. They are external prerequisites the agent invokes through the shell when needed.
+
+Current documented prerequisites include:
+
+- Pandoc
+- Typst
+- Ghostscript
+- ImageMagick
+- Afterwriting
+- Screenplain
+
+The authoritative guidance for those tools is split across:
+
+- [Publishing](publishing.md)
+- [Shipped Assets](shipped-assets.md)
+- [Runtime Support](runtime-support.md)
+
+## Changing configuration safely
+
+Use this rule of thumb:
+
+- change `data/CONSTRAINTS.json` for command availability, work-type structure, adaptive terminology, or export rules
+- change `bin/install.js` for runtime targets or install paths
+- change command files for workflow behavior
+- change `.manuscript/config.json` only as project state, not as product schema authoring
+
+After changing configuration surfaces, run:
+
+```bash
+npm test
+```
+
+And for release-facing changes, also run:
+
+```bash
+npm run release:check
+```
+
+## Related docs
+
+- [Getting Started](getting-started.md)
+- [Architecture](architecture.md)
+- [Contributing](contributing.md)
+- [Drafter Quality](drafter-quality.md)
+- [Voice DNA](voice-dna.md)
+- [Runtime Support](runtime-support.md)
+- [Publishing](publishing.md)

package/docs/context-protocol.md

@@ -0,0 +1,81 @@
+# Context preference protocol
+
+This is the canonical context-cost contract for Scriveno commands. The goal is to stop every session-aware command from independently re-loading STATE.md, OUTLINE.md, RECORD.md, config.json, and other orientation files when the auto-regenerated `.manuscript/CONTEXT.md` already summarizes them.
+
+It is part of the trust layer:
+- `STATE.md` -- structured snapshot (data)
+- `RECORD.md` -- compact established-content store
+- `.manuscript/CONTEXT.md` -- one-page narrative bootstrap (synthesis)
+- `.manuscript/HISTORY.log` -- append-only audit trail
+
+## The rule
+
+Before loading STATE.md, OUTLINE.md, or config.json individually, any command whose first action is "load orientation files" MUST do this check:
+
+```
+1. Read .manuscript/CONTEXT.md if it exists.
+2. Compare its `Updated` timestamp to .manuscript/STATE.md and to the
+   newest file in .manuscript/drafts/body/ (if drafts exist).
+3. If CONTEXT.md is fresher than both, USE IT for orientation. Skip
+   the raw-file loads unless you need a specific field CONTEXT.md
+   does not contain.
+4. If CONTEXT.md is missing, older than STATE.md, or older than the
+   newest draft, treat STATE.md as authoritative and continue with
+   the original load instructions. Suggest /scr:save (which
+   regenerates CONTEXT.md) at the end of the response.
+```
+
+Drafter commands and any command whose job is to *write* a draft, plan, or analysis do not skip raw-file loads -- they need the full source. The protocol applies to **orientation-only** reads at the start of session-aware commands.
+
+## Which fields CONTEXT.md provides
+
+CONTEXT.md (template at `templates/CONTEXT.md`) holds:
+
+- Project title and work type (substitute for `config.json` lookups)
+- Phase and active unit (substitute for STATE.md `Current phase` / `Current unit`)
+- Last 5 actions (substitute for STATE.md `Last actions` table)
+- Open items: drafted-but-not-reviewed, planned-but-not-drafted, voice warnings, continuity flags, scaffold markers (substitute for STATE.md `Pending`)
+- Record highlights: open threads, reader promises, and next-unit obligations (substitute for a full RECORD.md read when routing only needs orientation)
+- Suggested next step (substitute for `/scr:next` re-derivation)
+- Last `/scr:scan` verdict
+
+If a command needs something CONTEXT.md does NOT have (e.g. specific draft content, individual unit metadata, the full OUTLINE.md ordering), load only that specific file. CONTEXT.md replaces the orientation read, not every read.
+
+## How to apply
+
+Add this block at the top of `## What to do` (or equivalent), before the existing load instructions. Adapt prose lightly per command but keep the rule machine-readable:
+
+```markdown
+### STEP 0: BOOTSTRAP (context-cost protocol)
+
+Read `.manuscript/CONTEXT.md` first if it exists. If its `Updated` timestamp
+is newer than STATE.md and newer than the newest file in
+`.manuscript/drafts/body/`, treat it as your orientation source for the
+fields below (project title, work type, phase, current unit, last actions,
+open items, suggested next step). Skip the corresponding raw-file loads in
+STEP 1 unless you need a field CONTEXT.md does not surface.
+
+If CONTEXT.md is missing, stale, or contradicts STATE.md, fall back to the
+original loads. Note in your final response that CONTEXT.md should be
+regenerated on the next /scr:save.
+
+See `docs/context-protocol.md` for the full contract.
+```
+
+## Why pipe-delimited freshness, not file size
+
+Filesystem mtime is a cheap, durable signal that does not require parsing the file. Comparing one timestamp against two others (STATE.md, newest draft) is two `stat` calls. The alternative -- parsing CONTEXT.md to check internal coherence -- costs more tokens than just loading STATE.md, defeating the purpose.
+
+## When the protocol does not apply
+
+- **Drafter agents** (drafter.md, voice-checker.md, etc.) -- they need the full source files for fidelity.
+- **Read-only data display commands** (`/scr:progress`, `/scr:session-report`) -- already cheap; no orientation files to skip.
+- **First-write commands** (`/scr:new-work`, `/scr:import`) -- no CONTEXT.md exists yet.
+- **The CONTEXT.md regenerators themselves** (`/scr:save`, `/scr:pause-work`, `/scr:resume-work`) -- they MUST load the raw files to rebuild CONTEXT.md correctly. They are the *writers* of CONTEXT.md, not consumers.
+- **`/scr:scan`** -- its job is to detect drift, so it must read the raw files to compare against CONTEXT.md.
+
+## Expected savings
+
+For a typical session-aware command (`/scr:next`, `/scr:plan`, `/scr:export`, `/scr:publish`, etc.) that previously loaded STATE.md (~50 lines), config.json (~30 lines), OUTLINE.md (~100-300 lines), and a CONSTRAINTS.json adaptation slice, the bootstrap step replaces ~200-500 lines of raw orientation reads with one ~30-line CONTEXT.md read. Savings compound across chained commands (autopilot, publish presets).
+
+The protocol is a hint, not a hard gate. A command that misses an edge case can still load raw files explicitly. The cost is paid; correctness is preserved.