scriveno 2.0.5

package/docs/development.md

@@ -0,0 +1,152 @@
+# Development
+
+This guide is for contributors working on Scriveno itself rather than using Scriveno as a writer.
+
+## Development model
+
+Scriveno is a pure skill and command system:
+
+- commands are markdown files in `commands/scr/`
+- agents are markdown files in `agents/`
+- templates are markdown or JSON files in `templates/`
+- the installer is the only Node-based executable surface in `bin/install.js`
+- `data/CONSTRAINTS.json` is the central registry for capabilities and adaptation
+
+There is no compiled app, frontend bundle, service, or dependency-heavy local dev stack to boot.
+
+## Local setup
+
+Scriveno’s local development requirements are intentionally small:
+
+- Node.js >=20.0.0 for the installer and test runner. Use a currently supported LTS such as Node.js 24 for new work.
+- npm for package scripts and publish tooling
+- git for normal repo history
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Today that mainly creates the lockfile context and standard npm metadata flow. The package remains dependency-free at runtime.
+
+## Important directories
+
+These are the main places contributors work:
+
+- `commands/scr/` for writer-facing commands
+- `commands/scr/sacred/` for sacred-exclusive subcommands
+- `agents/` for fresh-context worker agents like `drafter` and `voice-checker`
+- `templates/` for generated project scaffolding
+- `data/CONSTRAINTS.json` for work types, commands, adaptations, and export rules
+- `docs/` for shipped documentation
+- `test/` for Node test suites
+- `bin/install.js` for runtime installation behavior
+
+## Common contribution paths
+
+### Add or change a command
+
+1. Edit or add the markdown file under `commands/scr/`
+2. Register or update the command in `data/CONSTRAINTS.json`
+3. Update docs if the command surface or wording changed
+4. Add or update tests when the change affects trust, counts, adaptation, packaging, or installer behavior
+
+Use [Contributing](contributing.md) for the full command-authoring walkthrough.
+
+### Add a work type
+
+1. Add or update the work type under `data/CONSTRAINTS.json`
+2. Check its group, hierarchy, `command_unit`, and any `config_defaults`
+3. Update docs that reference work-type counts or examples
+4. Update tests that lock the visible work-type surface
+
+### Add templates or adaptation files
+
+1. Add the template under `templates/`, `templates/technical/`, or `templates/sacred/`
+2. Update the command logic or docs that describe the generated file set
+3. Verify the template is included by npm packaging if it is supposed to ship
+
+### Change installer behavior
+
+1. Edit `bin/install.js`
+2. Update docs that mention installer targets, runtime support, or setup paths
+3. Run the installer and package-oriented tests
+4. Dry-run packaging before release-sensitive changes
+
+## Working principles
+
+These constraints matter more than convenience:
+
+- keep the system markdown-first and dependency-light
+- preserve the Voice DNA pipeline
+- keep `>=20.0.0` as the installer compatibility floor unless the product plan changes
+- treat `docs/runtime-support.md` and `docs/shipped-assets.md` as trust-critical docs
+- avoid overstating runtime parity or shipped assets
+
+If a command file and the plan disagree, the plan is canonical and the command should be corrected.
+
+## Useful commands
+
+Run the full suite:
+
+```bash
+npm test
+```
+
+Run a smaller targeted subset while iterating:
+
+```bash
+node --test test/package.test.js test/constraints.test.js
+```
+
+Run the release gate before publishing:
+
+```bash
+npm run release:check
+```
+
+Start the installer locally:
+
+```bash
+npm start
+```
+
+Refresh installed runtime surfaces from this checkout after changing commands, agents, or installer-generated skills:
+
+```bash
+node bin/install.js --runtime codex --global --developer --silent
+```
+
+The writer-facing form of this maintenance operation is `/scr:sync`.
+
+## Docs and release workflow
+
+Docs are part of the shipped product. If you change visible behavior, update every affected documentation surface in the same pass: root docs, files under `docs/`, proof READMEs, template READMEs, and command markdown that exposes user-facing contracts.
+
+For release-oriented documentation surfaces, the main files are:
+
+- `README.md`
+- `CHANGELOG.md`
+- `docs/release-notes.md`
+- `docs/shipped-assets.md`
+- `docs/command-reference.md`
+- `templates/*/README.md` when shipped profiles or templates change
+- `.planning/` milestone summaries when you are still using the GSD planning layer
+
+## Before shipping
+
+A good pre-ship pass for Scriveno changes is:
+
+1. run the targeted tests for the touched surface
+2. run `npm test`
+3. run `npm run release:check` for package-facing changes
+4. review trust-sensitive docs for runtime, asset, and support claims
+
+## Related docs
+
+- [Architecture](architecture.md)
+- [Configuration](configuration.md)
+- [Testing](testing.md)
+- [Contributing](contributing.md)
+- [Release Notes](release-notes.md)

package/docs/drafter-quality.md

@@ -0,0 +1,127 @@
+# Drafter quality controls
+
+Scriveno's drafter agent loads three layers of rule context, in this order, on every atomic unit:
+
+1. **STYLE-GUIDE.md** (always, sovereign): the writer's Voice DNA. The drafter's primary loyalty.
+2. **WRITING-RULES.md** (optional, universal): human-first restraint, content integrity, register awareness, artifact cleanup, and canonical AI-tell don'ts that apply to all writing.
+3. **Pitfall pack** (optional, type-specific): traps unique to the project's `work_type`.
+
+Conflict resolution is top-down. STYLE-GUIDE.md beats WRITING-RULES.md beats the pitfall pack. The writer's voice is sovereign; the rule layers are scaffolding to keep weaker models from drifting into generic AI prose, not constraints to override the writer.
+
+## WRITING-RULES.md
+
+Ships as `templates/WRITING-RULES.md` and lands in every new project's `.manuscript/` via `/scr:new-work` and `/scr:import`. The file is a universal restraint layer covering:
+
+- Human-first restraint: do not over-correct prose that already sounds like the writer
+- Variance over substitution: fix the thought and rhythm, not only the suspect word
+- Factual integrity and content preservation
+- Soft-inference discipline for cause, timing, priority, quantity, and motive
+- Register-aware restraint for academic, technical, legal, sacred, journalistic, quoted, and period material
+- Stance discipline: edge or opinion only reacts to supplied material
+- Hedging and qualifiers
+- Throat-clearing and scaffolding
+- Balanced-both-sides constructions
+- Generic metaphors and dead figures
+- Symmetrical rhythm
+- Moralizing closings
+- Essay transitions in narrative
+- Abstract vagueness
+- Emotional telling
+- AI tics in dialogue
+- Chat artifacts, placeholder tokens, copied citation residue, and orphaned fences
+- Durable-doc wording that describes what is true now
+- Show-don't-tell triggers
+- Punctuation defaults (no em/en dashes, no emojis)
+- Diagnostic discipline (honest read): how the same rules read from the other side when prose is being evaluated rather than written
+
+The drafter, voice-checker, and originality-check all reference this as the canonical universal rulebook. If a writer's STYLE-GUIDE.md says they hedge, fragment, moralize, use period diction, or keep a formal register deliberately, that voice choice wins.
+
+The human-first additions are especially important for revision. They tell Scriveno to look for clusters before flagging AI-like prose, preserve mixed feelings and uneven rhythm, keep every required beat, avoid making unsupported details more specific just because the sentence would sound smoother, and avoid installing a new "humanized" signature.
+
+Editing commands should also report restraint. A good line-edit or polish pass can say what it deliberately left alone: a formal register, an earned list, a rough sentence that carries voice, or a loaded hedge that changes the claim if removed.
+
+The diagnostic layer is the evaluative counterpart and is deliberately separate from rewriting. `/scr:voice-check` and `/scr:originality-check` (and the voice-checker agent behind them) diagnose: they report an authenticity band (Reads human / Mixed signals / Reads AI-generated) first, then a 0-100 score, then flagged spans with reasons, and they never hand back a rewritten span. They run a scrutiny pre-check that matches scrutiny to evidence density (low density biases hard toward a high score, because over-flagging genuine human prose is the worst error a diagnostic can make), a false-positive audit with veto power that turns strong false positives into score-raising human markers, and an internal-consistency check for unearned register or sophistication seams. Every report carries a required "Reads as human (deliberately not flagged)" section and a caveat that the score is a heuristic read, not proof. The loop is diagnose, decide, transform (`/scr:line-edit`, `/scr:polish`, re-draft), re-verify; keeping diagnosis and rewriting in separate steps with the writer between them is what prevents a score-then-rewrite gaming loop, so the drafter self-check stays a write-to-the-voice judgement rather than a score chase, and no diagnostic carries a target score into a rewrite.
+
+## Pitfall packs
+
+Ship as `templates/pitfalls/<work_type>.md`. The drafter looks for a pack matching `config.work_type` in this order:
+
+1. `.manuscript/PITFALLS.md` (project-local override that the writer can author)
+2. `templates/pitfalls/<work_type>.md` (the installed pack)
+3. None: skip silently
+
+Initial coverage spans 8 work types (one per major group plus a second prose entry):
+
+| Pack | Group | Focus |
+|------|-------|-------|
+| `novel.md` | prose | filter words, POV breaches, dialogue traps, genre stock phrases |
+| `memoir.md` | prose | retrospective voice traps, sentimentality, self-presentation |
+| `screenplay.md` | script | unfilmable description, action-line bloat, on-the-nose dialogue |
+| `runbook.md` | technical | imperatives, missing preconditions, verification and rollback |
+| `research_paper.md` | academic | hedge stacks, citation hygiene, methodology traps |
+| `poetry_collection.md` | poetry | image cliches, diction traps, sentimentality, form pitfalls |
+| `comic.md` | visual | script-versus-art boundary, panel rhythm, caption voice |
+| `commentary.md` | sacred | register drift, anachronism, source-handling, doctrinal precision |
+
+A contributor adding `templates/pitfalls/<new_work_type>.md` is automatically picked up by `listPitfallPacks()` with no edit to library code or `CONSTRAINTS.json`.
+
+## The `draft` block in config.json
+
+Three knobs in `.manuscript/config.json`:
+
+```json
+"draft": {
+  "rigor": "standard",
+  "context_profile": "standard",
+  "pitfalls_enabled": true
+}
+```
+
+### `draft.rigor`
+
+- `standard` (default): the drafter applies WRITING-RULES.md and the pitfall pack during the Step 4 self-check. Rewrites if drift is detected.
+- `strict`: the drafter mentally checks each sentence against WRITING-RULES.md and the pitfall pack as it writes. Use when routing to weaker models that benefit from explicit per-sentence scaffolding.
+
+### `draft.context_profile`
+
+Controls how much context the drafter loads per atomic unit. Saves tokens on every invocation, which compounds across a manuscript of dozens or hundreds of units.
+
+- `minimal`: STYLE-GUIDE, WRITING-RULES, the unit's PLAN, the previous unit's tail, and CHARACTERS entries for figures actually appearing in the plan. Skips THEMES.md and WORK.md unless the plan references them.
+- `standard` (default): full context list. Preserves prior behavior for unmodified projects.
+- `full`: standard + full DOCTRINES.md and LINEAGES.md (not excerpts) for sacred works, plus reference passages when the orchestrator provides them. Use when the unit genuinely needs cross-document continuity.
+
+### `draft.pitfalls_enabled`
+
+When `false`, skip loading the pitfall pack. WRITING-RULES.md still loads. Use when the writer's voice deliberately leans into a pitfall (parody, pastiche, period voice, satire) and the pack is more interference than help.
+
+## Model tier recommendations
+
+Rough guidance for matching settings to model class. The writer's experience with the model is the final arbiter; treat these as starting points, not laws.
+
+| Model class | Typical use | Recommended `rigor` | Recommended `context_profile` |
+|-------------|------------|--------------------|------------------------------|
+| Frontier (Opus 4.x, GPT-4.x, Gemini 2.x Pro) | Long-form drafting, complex sacred or literary prose | `standard` | `standard` or `full` (when the unit needs continuity) |
+| Mid-tier (Sonnet 4.x, GPT-4 mini, Haiku 4.x) | Day-to-day drafting, most novels and screenplays | `standard` | `standard` |
+| Budget (Haiku, GPT-3.5, local 7-13B) | Bulk drafting of short scenes, repetitive structural work | `strict` | `minimal` |
+
+If voice fidelity drops below the writer's `voice.drift_threshold`, the first lever is `rigor: strict`. The second is to step up a model tier. The third is to recalibrate STYLE-GUIDE.md via `/scr:voice-test`.
+
+## Token economy
+
+The drafter's prompt cache benefits from a stable prefix. Loading order is fixed across invocations (STYLE-GUIDE.md, WRITING-RULES.md, pitfall pack first; unit-variable files last) so the host runtime's prompt cache hits the rule layers without recomputation. The `minimal` context profile compounds this: less tail variance per unit means more cache reuse across a long drafting session.
+
+## Backward compatibility
+
+All three layers are optional. Projects predating this feature keep working without modification:
+
+- WRITING-RULES.md absent: drafter falls back to inline "what you must never do" rules.
+- No pitfall pack for the work_type: drafter skips silently; line-edit falls back to broad genre cues.
+- `draft` block absent from config.json: drafter uses defaults (`standard` rigor, `standard` context_profile, pitfalls enabled).
+
+## See also
+
+- [`templates/WRITING-RULES.md`](../templates/WRITING-RULES.md): the canonical universal rulebook
+- [`templates/pitfalls/`](../templates/pitfalls/): per-work-type pitfall packs
+- [`agents/drafter.md`](../agents/drafter.md): the drafter agent's contract
+- [`agents/voice-checker.md`](../agents/voice-checker.md): the voice-drift gate
+- [`commands/scr/originality-check.md`](../commands/scr/originality-check.md): AI-pattern detection

package/docs/getting-started.md

@@ -0,0 +1,198 @@
+# Getting Started with Scriveno
+
+Go from zero to a drafted scene in under 10 minutes. This guide walks you through installation, project setup, and your first draft.
+
+Want evidence first? Start with [Proof Artifacts](proof-artifacts.md). The watchmaker sample flow and the Voice DNA before/after bundle give you the fastest way to inspect what Scriveno actually proves today.
+
+## Prerequisites
+
+- **An AI coding agent** -- Claude Code, Cursor, Gemini CLI, or another current Scriveno installer target
+- **Node.js >=20.0.0** -- needed for the installer only. For new installs, use a currently supported LTS such as Node.js 24.
+- That's it. No other dependencies for the core writing workflow.
+
+Before choosing a runtime, check [Runtime Support](runtime-support.md) for the current installer targets, install types, support levels, and verification status.
+
+## Step 1: Install Scriveno
+
+Run the installer in your terminal:
+
+```
+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.
+
+## Step 2: Explore the Demo (Optional)
+
+Not sure what Scriveno does? Try the demo before starting your own project:
+
+Claude Code:
+
+```
+/scr-demo
+```
+
+Codex:
+
+```
+$scr-demo
+```
+
+This creates a pre-built short story project -- a retired watchmaker who receives a letter from a daughter he never knew. The demo includes:
+
+- 4 fully drafted scenes with distinct voice and style
+- A complete voice profile (STYLE-GUIDE.md)
+- Character files, plot graph, and thematic threads
+- Editor notes on one scene so you can see the revision workflow
+- 1 planned-but-undrafted scene so you can watch the drafter work
+
+Explore at your own pace. When you're ready to start your own work, run `/scr-demo --clear` to clean up.
+
+If you want a curated reading path instead of jumping straight into the demo files, open [Proof Artifacts](proof-artifacts.md) first. It maps the watchmaker sample to the exact files worth inspecting.
+
+## Step 3: Start Your Project
+
+Create a new writing project:
+
+Claude Code:
+
+```
+/scr-new-work
+```
+
+Codex:
+
+```
+$scr-new-work
+```
+
+Scriveno asks just 3 questions -- what you're writing, your premise, and whether you have existing material. That's it. No long setup forms, no configuration wizards.
+
+From your answers, Scriveno generates your project structure:
+
+```
+.manuscript/
+  WORK.md          -- your project's identity
+  OUTLINE.md       -- structure and unit breakdown
+  RECORD.md        -- what the work has established
+  STYLE-GUIDE.md   -- your Voice DNA profile
+  CHARACTERS.md    -- cast and voice anchors
+  THEMES.md        -- thematic threads
+  PLOT-GRAPH.md    -- story arc and beats
+  STATE.md         -- workflow position tracker
+  config.json      -- project settings
+```
+
+Every file adapts to your work type. Writing a screenplay? You get acts and scenes. A research paper? Sections and argument maps. A runbook? Procedures and system maps. A Quran commentary? Surahs and doctrinal frameworks. Scriveno supports 50 work types with tradition-native vocabulary.
+
+## Step 4: Calibrate Your Voice
+
+Before you draft anything substantial, turn the STYLE-GUIDE template into a real voice profile:
+
+Claude Code:
+
+```
+/scr-profile-writer
+```
+
+Codex:
+
+```
+$scr-profile-writer
+```
+
+This interview builds your Voice DNA from your preferences, reference works, or a writing sample. When it finishes, run:
+
+Claude Code:
+
+```
+/scr-voice-test
+```
+
+Codex:
+
+```
+$scr-voice-test
+```
+
+That calibration pass writes a short sample and lets you say what sounds right or wrong before Scriveno starts drafting real units.
+
+## Step 5: Develop Your Story
+
+Before drafting, shape your ideas:
+
+Claude Code:
+
+```
+/scr-discuss
+```
+
+Codex:
+
+```
+$scr-discuss
+```
+
+This opens a collaborative conversation where you and the AI work through the creative decisions for your next unit -- pacing, voice, character dynamics, what to include, what to avoid. Scriveno picks the 3-4 most relevant questions for your specific scene rather than running through a checklist.
+
+Your decisions get saved to a context file that the drafter will use. Think of this as giving the drafter its marching orders.
+
+If you already refined your voice profile, you can also skip this step and draft with the defaults you've approved.
+
+## Step 6: Write Your First Draft
+
+Draft your first unit:
+
+Claude Code:
+
+```
+/scr-draft
+```
+
+Codex:
+
+```
+$scr-draft
+```
+
+The drafter loads your Voice DNA (STYLE-GUIDE.md) and writes in your voice, not generic AI prose. Each atomic unit (scene, beat, passage) is drafted in a fresh context to prevent voice drift and keep quality consistent across the entire work.
+
+After drafting, Scriveno runs a voice-check pass to flag anything that drifted from your established style. You'll see a summary like: "Drafted Chapter 1: 2,400 words across 3 scenes. Voice consistency: 94%."
+
+Your draft files appear in `.manuscript/` ready for you to read and revise.
+
+## What's Next
+
+Not sure what to do? There's one command that always knows:
+
+Claude Code:
+
+```
+/scr-next
+```
+
+Codex:
+
+```
+$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.
+
+Beyond the core workflow, Scriveno offers:
+
+- **Revision** -- `/scr-editor-review`, `/scr-line-edit`, `/scr-continuity-check`
+- **Publishing** -- `/scr-publish`, `/scr-export`, `/scr-cover-art`, `/scr-blurb`
+- **Collaboration** -- `/scr-track` for revision tracks (`create`, `compare`, `merge`, `propose`)
+- **Versions** -- `/scr-save`, `/scr-history`, `/scr-versions`, `/scr-compare`
+- **Navigation** -- `/scr-help`, `/scr-next`, `/scr-pause-work`
+
+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
+- [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/history-protocol.md

@@ -0,0 +1,96 @@
+# HISTORY.log Protocol
+
+`.manuscript/HISTORY.log` is the project's append-only chronological record of Scriveno commands that mutate state. It is the third leg of the context-integrity stool, alongside `STATE.md` (structured snapshot) and `.manuscript/CONTEXT.md` (one-page bootstrap). Where STATE.md records *what is true now* and CONTEXT.md narrates *where you are*, HISTORY.log records *how you got here, in order*.
+
+This document is the single source of truth for the line format. Every command that appends to HISTORY.log must follow this contract.
+
+---
+
+## Where it lives
+
+- Path: `.manuscript/HISTORY.log`
+- Committed to git (cross-session recovery is the whole point; do not gitignore)
+- Append-only. Commands never rewrite, truncate, or rotate the file. If size becomes a real problem (>10MB) the writer can manually archive it via `mv .manuscript/HISTORY.log .manuscript/HISTORY-{date}.log` and start a fresh file. Scriveno does not auto-rotate.
+
+## Line format
+
+One line per command invocation. UTF-8 text. No trailing whitespace. LF line endings. Pipe-delimited fields, with a single space on each side of every `|` for readability:
+
+```
+{ISO_TIMESTAMP} | {COMMAND} | {KEY=VALUE pairs, separated by " | "} | outcome={outcome}
+```
+
+### Fields
+
+| Field | Required | Format | Notes |
+|-------|----------|--------|-------|
+| `ISO_TIMESTAMP` | yes | `2026-05-10T17:14:33Z` (UTC, second precision) | Use UTC always. Local time loses meaning across collaborators. |
+| `COMMAND` | yes | `scr:save`, `scr:draft`, `scr:export`, etc. | Always prefix with `scr:`. Use the canonical slash-command name without the leading `/`. |
+| Key=value pairs | optional | `unit=12`, `level=balanced`, `format=epub`, `files=12-A-DRAFT.md,12-B-DRAFT.md` | Use lowercase keys. Multiple files comma-separated, no spaces. Quote values containing spaces with double quotes. |
+| `outcome` | yes | `outcome=ok`, `outcome=committed`, `outcome=skipped`, `outcome=failed:<reason>` | Last field on the line. The `outcome=` prefix lets `/scr:scan` parse a tail-of-log status quickly. |
+
+### Examples
+
+```
+2026-05-10T17:14:33Z | scr:save | message="Saved after drafting Chapter 12" | files=3 | outcome=committed
+2026-05-10T17:18:02Z | scr:draft | unit=13 | files=13-A-DRAFT.md,13-B-DRAFT.md | outcome=ok
+2026-05-10T17:22:45Z | scr:plan | unit=14 | outcome=ok
+2026-05-10T17:30:11Z | scr:export | format=epub | level=- | outcome=ok
+2026-05-10T17:32:08Z | scr:publish | preset=ebook-wide | front-level=balanced | back-level=balanced | outcome=ok
+2026-05-10T17:35:54Z | scr:front-matter | level=balanced | elements=4 | outcome=ok
+2026-05-10T17:40:02Z | scr:scan --fix | files=STATE.md,CONTEXT.md | outcome=fixed-2
+2026-05-10T17:45:16Z | scr:export | format=pdf | outcome=failed:typst-not-installed
+```
+
+## Which commands append
+
+These commands **must** append a line on every invocation that mutates state:
+
+- `/scr:save`
+- `/scr:draft`
+- `/scr:plan`
+- `/scr:export`
+- `/scr:publish`
+- `/scr:front-matter`
+- `/scr:back-matter`
+- `/scr:pause-work`
+- `/scr:resume-work`
+- `/scr:scan --fix`
+
+Other state-mutating commands **may** append a line; this list is the minimum. Read-only commands (`/scr:progress`, `/scr:history`, `/scr:next` when it does not invoke another command) do not append. When `/scr:next` routes to a state-mutating command, the routed command is responsible for the entry, not `/scr:next` itself.
+
+## How to append
+
+```bash
+echo "{ISO_TIMESTAMP} | {COMMAND} | {fields} | outcome={outcome}" >> .manuscript/HISTORY.log
+```
+
+Generate the timestamp with one of:
+
+```bash
+date -u +%Y-%m-%dT%H:%M:%SZ
+```
+
+Create the file if it does not exist:
+
+```bash
+touch .manuscript/HISTORY.log
+```
+
+If the command being recorded is itself a `/scr:save`, the append must happen **before** `git add`. The line is part of the same commit.
+
+## Reading HISTORY.log
+
+`/scr:scan` parses the last 50 lines on every run to detect malformed entries.
+
+`.manuscript/CONTEXT.md` shows the last 5 entries as the "Recent activity" table. The CONTEXT.md regenerator (in `/scr:save`, `/scr:pause-work`, `/scr:resume-work`) reads HISTORY.log directly for that table.
+
+`/scr:history` continues to show git-save history (writer-friendly version log). It does not read HISTORY.log -- the two surfaces are intentionally separate. Writers see saves; HISTORY.log is the AI-readable audit trail.
+
+## Why pipe-delimited and not JSON Lines
+
+JSON is more rigorously parseable but harder to scan visually. Pipe-delimited with a fixed prefix (`{timestamp} | scr:{command}`) is grepable at a glance, lets a writer open the file in any text editor and orient instantly, and stays readable in a `tail -f` window during long sessions. The format is regular enough that any future tooling can parse it with one regex.
+
+## Why append-only and not a database
+
+Scriveno's architecture rule is no compiled code, no runtime dependencies. A flat append-only log preserves that. Writers can `cat`, `grep`, and `tail` it. Git already provides durable storage, blame, and rewind. There is no parallel infrastructure to maintain.

package/docs/proof-artifacts.md

@@ -0,0 +1,56 @@
+# Proof Artifacts
+
+This document is the canonical index of Scriveno's proof layer. It points to concrete artifacts a prospective user can inspect when asking whether Scriveno's claims are earned by the repo.
+
+## Start Here
+
+- 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.
+
+## Watchmaker Sample Flow
+
+**What it proves:** Scriveno ships one credible writing workflow from setup context through drafted outcome, review evidence, and next-step continuity.
+
+**Canonical artifact:** [data/proof/watchmaker-flow/README.md](../data/proof/watchmaker-flow/README.md)
+
+**Underlying shipped files:**
+
+- [data/demo/.manuscript/WORK.md](../data/demo/.manuscript/WORK.md)
+- [data/demo/.manuscript/OUTLINE.md](../data/demo/.manuscript/OUTLINE.md)
+- [data/demo/.manuscript/STATE.md](../data/demo/.manuscript/STATE.md)
+- [data/demo/.manuscript/STYLE-GUIDE.md](../data/demo/.manuscript/STYLE-GUIDE.md)
+- [data/demo/.manuscript/drafts/body/1-the-letter-DRAFT.md](../data/demo/.manuscript/drafts/body/1-the-letter-DRAFT.md)
+- [data/demo/.manuscript/drafts/body/2-the-workshop-DRAFT.md](../data/demo/.manuscript/drafts/body/2-the-workshop-DRAFT.md)
+- [data/demo/.manuscript/drafts/body/3-the-pier-DRAFT.md](../data/demo/.manuscript/drafts/body/3-the-pier-DRAFT.md)
+- [data/demo/.manuscript/drafts/body/4-the-clock-DRAFT.md](../data/demo/.manuscript/drafts/body/4-the-clock-DRAFT.md)
+- [data/demo/.manuscript/reviews/2-the-workshop-REVIEW.md](../data/demo/.manuscript/reviews/2-the-workshop-REVIEW.md)
+- [data/demo/.manuscript/plans/5-the-reunion-PLAN.md](../data/demo/.manuscript/plans/5-the-reunion-PLAN.md)
+
+Start with the proof bundle if you want the curated version. Follow the underlying files if you want to inspect the raw sample directly.
+
+## 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.
+
+**Canonical artifact:** [data/proof/voice-dna/README.md](../data/proof/voice-dna/README.md)
+
+**Artifact bundle:**
+
+- [data/proof/voice-dna/STYLE-GUIDE-EXCERPT.md](../data/proof/voice-dna/STYLE-GUIDE-EXCERPT.md)
+- [data/proof/voice-dna/UNGUIDED-SAMPLE.md](../data/proof/voice-dna/UNGUIDED-SAMPLE.md)
+- [data/proof/voice-dna/GUIDED-SAMPLE.md](../data/proof/voice-dna/GUIDED-SAMPLE.md)
+
+Read the bundle in order if you want to inspect sentence rhythm, metaphor selection, dialogue restraint, and physical grounding at the same time.
+
+## Creative Context
+
+**What it proves:** Scriveno can preserve craft choices, character behavior, and subject movement across the core writing loop without adding labels to manuscript prose.
+
+**Canonical artifact:** [data/proof/creative-context/README.md](../data/proof/creative-context/README.md)
+
+## Related Trust Docs
+
+- [Shipped Assets](shipped-assets.md) -- canonical inventory of the trust-critical files Scriveno actually bundles
+- [Runtime Support](runtime-support.md) -- canonical runtime matrix and installer-baseline framing
+- [Release Notes](release-notes.md) -- summary of what changed in the latest package release