chore: initialize POM 2 repo (docs guards green; release gates recorded NOT RUN pending install)

2026-08-19 10:31:00 +02:00
commit 7ffd00b5c5
111 changed files with 12522 additions and 0 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,54 @@
+# Architecture
+
+## Responsibility boundary
+
+```text
+Oh My Pi
+├── models and thinking levels
+├── native tools and approvals
+├── task agents and IRC
+├── todo, sessions, compaction, memory
+├── extension lifecycle and TUI
+└── optional Swarm extension
+
+POM
+├── stage contracts and authoritative transitions
+├── evidence, blockers, decisions, and provenance
+├── prompt stack and personality composition
+├── Hive mission planning and synthesis records
+├── artifact manifest and semantic versions
+├── deterministic validators
+├── Obsidian/Quartz knowledge projection
+├── Git stage checkpoints
+└── verified archive delivery
+```
+
+OMP executes; POM governs. POM never invents a parallel task runner, chat network, todo database, or session tree.
+
+## Runtime layers
+
+| Layer | Modules | Responsibility |
+|---|---|---|
+| Host integration | `index.ts`, `events.ts`, `command.ts` | Register commands, tools, lifecycle hooks, routing, and policy |
+| Terminal | `ui.ts`, `visual.ts`, `renderers.ts`, `themes.ts` | HUD, status, overlay, cards, themes, and thinking annotation |
+| Domain | `domain.ts`, `state.ts` | Stage contracts, schemas, transitions, blockers, evidence, versions |
+| Execution planning | `studio.ts`, `swarm.ts`, `router.ts`, `tool-profiles.ts` | Native task batches, optional DAGs, model roles, active tools |
+| Knowledge and persistence | `prompts.ts`, `persistence.ts`, `paths.ts` | Prompt provenance, canonical files, vault, manifests, ledgers |
+| Assurance | `validators.ts`, `policy.ts`, `zip.ts`, `exporter.ts`, `git.ts` | Gates, path safety, command guard, checkpoints, archive verification |
+
+## Truth hierarchy
+
+1. System and explicit user requirements.
+2. Canonical project files and `00_admin/project_state.json`.
+3. Artifact manifest, evidence records, and append-only ledgers.
+4. Native OMP todo/task/IRC/session state for live execution.
+5. Generated vault notes as navigational projections.
+6. Memory as reusable heuristics only—never story canon.
+
+## Stage transition invariant
+
+A stage can pass only when it is actively running, all prerequisites are complete, every acceptance criterion has file-backed evidence, no blocker remains open, and deterministic validation produced a report path.
+
+## Persistence
+
+POM stores state both in OMP's append-only session entries and in the canonical project file. File writes use unique temporary paths followed by rename. Manifest and ledger mutation is serialized within the process. Files are resolved through canonical paths and symbolic-link escapes are rejected.
--- a/docs/AUDIT.md
+++ b/docs/AUDIT.md
@@ -0,0 +1,32 @@
+# Release audit — POM 2.0.0
+
+Date: 2026-07-12
+
+## Automated verification
+
+`npm run verify` performs:
+
+1. Strict TypeScript check against real OMP packages.
+2. Production-code behavioral tests.
+3. Temporary-project runtime smoke test.
+4. Structural package, resource, agent-frontmatter, and theme-schema checks.
+5. `npm pack --dry-run`.
+
+Covered behaviors include stage ordering, active-run gates, evidence requirements, blocker lifecycle, traversal/symlink defense, destructive-command policy, validator behavior, native Hive translation, Swarm graph generation, ZIP member decompression, CRC validation, and malformed archive rejection.
+
+## Security posture
+
+- Canonical paths are resolved with `realpath`.
+- Symbolic-link escapes are rejected.
+- Empty canonical artifacts are rejected.
+- Manifest hashes and byte counts are remeasured.
+- Recursive destructive commands against the project root are blocked by default.
+- ZIP member names, methods, decompression, sizes, duplicate names, and CRC values are verified.
+
+The command policy is a guardrail, not an operating-system sandbox. Host approvals and normal filesystem permissions remain authoritative.
+
+## Known release boundary
+
+Bun and the `omp` executable are unavailable in this build environment. Therefore `omp plugin doctor` and a live interactive TUI smoke session were not run here. They remain mandatory host acceptance checks after installation.
+
+`npm audit` currently reports moderate issues in the development/host dependency tree. The release archive does not claim a zero-vulnerability dependency graph; operators should evaluate the host's current dependency advisories.
--- a/docs/BOUNDARY.md
+++ b/docs/BOUNDARY.md
@@ -0,0 +1,52 @@
+---
+title: Repository Wiki vs Generated Project Vault
+description: Clear boundary between extension documentation and project knowledge bases
+---
+
+# Repository Wiki vs Generated Project Vault
+
+These are two entirely separate documentation systems. Confusing them is a primary source of drift.
+
+## Repository Wiki (this site)
+
+| Property | Value |
+|---|---|
+| **Purpose** | Documents the POM 2 *extension* for operators, contributors, architects |
+| **Source** | `/home/loca/dev/omppmo/docs/`, `/home/loca/dev/omppmo/README.md`, `/home/loca/dev/omppmo/POM.yml`, `/home/loca/dev/omppmo/skills/pom/references/` |
+| **Audience** | Humans installing, developing, or auditing the extension |
+| **Build** | Quartz 5 (`npm run serve:dev` in this repo) |
+| **Deploy target** | `pom-omp.loca.zone` (or similar) |
+| **Content type** | Static extension documentation: install, commands, architecture, contracts, release process |
+
+## Generated Project Vault
+
+| Property | Value |
+|---|---|
+| **Purpose** | Knowledge projection for a *specific creative project* produced by POM stages |
+| **Source** | Created at runtime by `src/persistence.ts:226-239` (`bootstrapProject`) under the project root |
+| **Audience** | The author/editor working on that specific creative work |
+| **Build** | Quartz 5 (separate instance per project, configured by `config/config.yml` template) |
+| **Deploy target** | Project-specific domain (e.g., `my-novel.loca.zone`) |
+| **Content type** | Dynamic creative artifacts: canon, cast, timeline, manuscript, research, images |
+
+## Boundary rules
+
+1. **Repository wiki NEVER contains project-specific content** — no canon, no cast, no manuscript scenes
+2. **Generated vault NEVER contains extension documentation** — no install instructions, no command maps, no tool schemas
+3. **README.md's `content/` tree (lines 80-98) describes the *vault shape*, not this wiki** — do not mistake the example vault structure for this repository's documentation
+4. **POM.yml's `knowledge.vault` field describes the *generated* vault format** — Obsidian-flavoured Markdown compatible with Quartz 5, but each project gets its own Quartz config
+
+## Navigation consequence
+
+- This wiki has an "Operator → Generated Vault" link that explains the vault shape and points to `src/persistence.ts` as the owner
+- A generated vault has a "Meta → Extension docs" link pointing back to this wiki's URL
+- They are separate Quartz instances with separate `quartz.config.ts`, separate deployments, separate domains
+
+## Common confusion points
+
+| Confusion | Reality |
+|---|---|
+| "Where is the wiki for my novel?" | In your project's `content/`, deployed to your project's domain |
+| "Why doesn't `docs/` have my story bible?" | `docs/` is the *extension* wiki; your story bible is in `02_story_bible/` |
+| "Can I edit the extension docs from my project?" | No — edit `/home/loca/dev/omppmo/docs/` and rebuild the extension wiki |
+| "Does `pom vault` modify this wiki?" | No — `pom vault` inserts a mention into the *generated project's* production board |
--- a/docs/DESIGN_REVIEW.md
+++ b/docs/DESIGN_REVIEW.md
@@ -0,0 +1,53 @@
+# Terminal experience design review
+
+## Objective
+
+Make verified production progress emotionally legible without rewarding noise.
+
+## Surface hierarchy
+
+1. **Status line:** tiny peripheral facts—stage, percentage, gate, Hive, approval, retry.
+2. **HUD widget:** persistent production truth—contract, progress, evidence, blockers, active work.
+3. **Working message:** one sentence describing what is happening this moment.
+4. **Cards:** durable meaningful events—validation, Hive mission, blocker, milestone, archive.
+5. **Overlay:** deliberate operator choices—run, delegate, validate, evidence, vault, export, theme, settings.
+6. **Expanded tool result:** detailed evidence only on demand.
+
+## Density modes
+
+| Mode | HUD | Cards | Best use |
+|---|---|---|---|
+| `cinematic` | Three lines with stage track and coordination cue | Rich details | Focused creative sessions |
+| `rich` | Two evidence-focused lines | Detailed | Daily production |
+| `compact` | One line | Terse | Split panes and small terminals |
+| `minimal` | No widget; status and critical cards only | Essential | Remote/headless-adjacent use |
+
+## Motion modes
+
+- `off`: static semantic glyphs.
+- `subtle`: two-frame pulse only while meaningful work is active.
+- `full`: four-frame activity cue plus stronger live coordination feedback.
+
+Animation stops with work. Completion is represented by stable state, not perpetual motion.
+
+## Reward model
+
+Prominent visual changes are reserved for:
+
+- file-backed evidence accepted;
+- blocker opened or resolved;
+- agent ownership claimed or handed off;
+- deterministic validation passed;
+- authoritative stage completed;
+- archive decompressed and verified.
+
+A tool merely starting receives only a small activity cue.
+
+## Accessibility and correctness
+
+- Semantic theme tokens instead of hard-coded terminal escape sequences.
+- Unicode glyphs are supplementary; words and layout retain meaning.
+- Components use visual-width utilities and truncate safely.
+- Unchanged HUD frames reuse cached line arrays to reduce repaint work.
+- Minimal mode and motion-off provide low-stimulation operation.
+- POM Nocturne and Parchment preserve corresponding dark/light semantics.
--- a/docs/INVENTORY.md
+++ b/docs/INVENTORY.md
@@ -0,0 +1,45 @@
+# Package inventory
+
+## Runtime
+
+- 1 OMP extension entry point
+- 7 typed POM tools
+- 1 `/pom` command namespace
+- 1 `Alt+P` shortcut
+- 4 custom message renderers
+- 1 optional thinking renderer
+- Lifecycle coverage for restore, prompt augmentation, tools, approvals, retries, compaction, stop, and shutdown
+
+## Production resources
+
+- 9 stage contracts
+- 14 task-agent definitions
+- 13 prompt fragments
+- 3 scoped rules
+- 1 primary skill package
+- 2 OMP themes
+- 6 active-tool profiles including `auto`
+- 3 operating personalities
+- 4 terminal density modes
+- 3 motion modes
+
+## Assurance
+
+- 9 behavioral tests across 8 test files
+- 1 runtime smoke script
+- 1 structural/package verifier
+- Strict TypeScript configuration
+- npm pack dry-run
+
+## Canonical generated project areas
+
+- `00_admin` — state, manifest, ledgers, checksums, validation, Hive
+- `01_planning` — brief, genre, voice, story store, direction
+- `02_story_bible` — canon, cast, world, timeline, continuity, visual bible
+- `03_manuscript` — outline, scenes, chapters, complete manuscript
+- `04_images` — references, generated assets, briefs, approvals
+- `05_research` — source notes and rights records
+- `06_ledgers` — decisions, assumptions, revisions, continuity, quality, validation
+- `07_exports` — checkpoint and final archives plus reports
+- `content` — Obsidian/Quartz knowledge projection
+- `.omp` — host and POM project configuration plus prompt overrides
--- a/docs/OFFICIAL_SOURCES.md
+++ b/docs/OFFICIAL_SOURCES.md
@@ -0,0 +1,14 @@
+# OMP integration sources
+
+POM targets the public extension and TUI APIs exported by the installed OMP 16.4.x packages.
+
+Primary references:
+
+- OMP extension documentation: <https://github.com/can1357/oh-my-pi/blob/main/docs/extensions.md>
+- OMP TUI documentation: <https://github.com/can1357/oh-my-pi/blob/main/docs/tui.md>
+- OMP settings documentation: <https://github.com/can1357/oh-my-pi/blob/main/docs/settings.md>
+- OMP package and Swarm documentation: <https://github.com/can1357/oh-my-pi/blob/main/docs/user-facing-packages.md>
+- OMP repository: <https://github.com/can1357/oh-my-pi>
+- Quartz Obsidian compatibility: <https://quartz.jzhao.xyz/features/Obsidian-compatibility>
+
+Release compilation is performed against the actual TypeScript declarations installed from `@oh-my-pi/pi-coding-agent`, `@oh-my-pi/pi-tui`, and `@oh-my-pi/pi-utils`; POM does not ship replacement declaration shims.
--- a/docs/OWNERSHIP.md
+++ b/docs/OWNERSHIP.md
@@ -0,0 +1,37 @@
+---
+title: Wiki Ownership Table
+description: Canonical ownership of every fact category to prevent drift
+---
+
+# Wiki Ownership Table
+
+Every duplicated fact has exactly one canonical owner. Mirrors must cite the owner and must not introduce independent variants.
+
+| Fact category | Canonical owner | Mirrors (must cite owner) |
+|---|---|---|
+| Runtime contracts, stage machine, evidence rules | `src/state.ts`, `src/persistence.ts`, `src/domain.ts` | `docs/ARCHITECTURE.md`, `POM.yml`, `skills/pom/references/workflow.md` |
+| Package metadata, file allowlist, scripts | `package.json` | `README.md`, `docs/INVENTORY.md`, `RELEASE.json` |
+| Release verification evidence | `scripts/release-manifest.mjs` (evidence files in `00_admin/validation/`) | `RELEASE.json`, `README.md`, `docs/AUDIT.md` |
+| Operator command map | `src/command.ts` (completions, help text) | `README.md`, `POM.yml`, `skills/pom/references/commands.md` |
+| Tool actions, approvals, schemas | `src/tools.ts` | `docs/TOOL_MATRIX.md`, `POM.yml`, `skills/pom/references/commands.md` |
+| Generated project layout | `src/persistence.ts:226-239` (`bootstrapProject`) | `docs/INVENTORY.md`, `skills/pom/references/artifacts.md` |
+| Prompt precedence and composition | `src/prompts.ts:83-117` (`composePromptStack`, `renderStagePrompt`) | `POM.yml`, `README.md`, `skills/pom/references/workflow.md` |
+| Resource discovery advertisement | `src/events.ts:19-24` (`resources_discover`) | `skills/pom/references/commands.md`, `docs/ARCHITECTURE.md` |
+| Validation scopes and tool ownership | `src/tools.ts:138-148` (`pom_validate`), `src/state.ts` (`passStage`) | `docs/TOOL_MATRIX.md`, `POM.yml`, `skills/pom/references/qa.md` |
+| Theme schema and OMP integration | `@oh-my-pi/pi-coding-agent` (external) | `scripts/verify.mjs`, `config/config.yml`, `themes/*.json` |
+| Dependency requirements | `package.json` (`peerDependencies`, `engines.bun`) | `README.md`, `docs/SETTINGS.md`, `AGENTS.md` |
+
+## Mirror rules
+
+1. Every mirror page MUST include a "Source: `path:line`" reference to the canonical owner
+2. A mirror MUST NOT redefine a fact — only summarize, cross-reference, or contextualize
+3. When the canonical owner changes, all mirrors MUST be updated in the same PR
+4. Automated checks in `scripts/verify.mjs` or dedicated scripts validate mirror freshness
+5. `scripts/verify.mjs` already enforces: agent frontmatter shape, theme names/keys, prompt counts, command counts, tool counts, stage counts
+
+## Adding a new fact category
+
+1. Identify the single source file in `src/`, `scripts/`, or `package.json`
+2. Add a row to this table
+3. Update all existing mirrors to cite the new owner
+4. Add a verification check if the fact is drift-prone
--- a/docs/POM_ARCHITECTURE.mmd
+++ b/docs/POM_ARCHITECTURE.mmd
@@ -0,0 +1,33 @@
+flowchart TD
+  U[Operator] --> C[/pom command center]
+  C --> K[POM production kernel]
+  K --> S[Authoritative stage machine]
+  K --> P[Prompt stack and personality]
+  K --> H[Hive mission planner]
+  K --> V[Deterministic validation]
+  K --> A[Artifact and canon ledger]
+  K --> X[Verified export]
+
+  P --> O[Oh My Pi host]
+  H --> T[Native task agents]
+  H --> I[Native IRC]
+  H --> W[Optional Swarm DAG]
+  S --> R[Model and active-tool routing]
+  R --> O
+  T --> O
+  I --> O
+  W --> O
+
+  A --> F[Canonical project files]
+  A --> M[Manifest plus SHA-256]
+  F --> Q[Obsidian / Quartz vault]
+  V --> F
+  V --> M
+  V --> E[Acceptance evidence]
+  X --> Z[ZIP central directory + decompression + CRC]
+  S --> G[Git stage branch/checkpoint]
+
+  O --> UI[OMP TUI hooks]
+  UI --> HUD[HUD and status]
+  UI --> CARDS[Validation/Hive/milestone cards]
+  UI --> OVERLAY[Keyboard overlay]
--- a/docs/SETTINGS.md
+++ b/docs/SETTINGS.md
@@ -0,0 +1,60 @@
+# Settings
+
+## Oh My Pi host settings
+
+Use `<project>/.omp/config.yml`. POM creates a recommended file during project bootstrap and ships the same template at `config/config.yml`.
+
+Important host controls:
+
+| Key | POM purpose |
+|---|---|
+| `theme.dark/light` | Select POM Nocturne/Parchment after `/pom theme install` |
+| `statusLine.showHookStatus` | Display POM stage, gate, Hive, retry, and approval segments |
+| `terminal.showImages` | Show visual references and generated images in capable terminals |
+| `tools.intentTracing` | Expose semantic tool intent in the live experience |
+| artifact spill settings | Keep large tool output out of the conversation surface |
+| `task.batch` / concurrency | Support bounded specialist waves |
+| `compaction.strategy: snapcompact` | Preserve long-running production context |
+| one-at-a-time steering/follow-up | Keep autopilot continuation ordered |
+
+## POM settings
+
+Precedence:
+
+```text
+built-in defaults
+→ ~/.omp/agent/pom.json
+→ <project>/.omp/pom.json
+→ persisted project state for mutable experience fields
+```
+
+| Setting | Values | Purpose |
+|---|---|---|
+| `autoToolProfiles` | boolean | Route OMP active tools by stage |
+| `autoModelRouting` | boolean | Resolve and activate the stage model role |
+| `dashboardWidget` | boolean | Enable the persistent HUD |
+| `stopGuard` | boolean | Continue an active stage briefly, then force explicit blocking |
+| `defaultMode` | `autopilot`, `collaborative`, `strict-autopilot` | Select prompt personality |
+| `defaultView` | `cinematic`, `rich`, `compact`, `minimal` | Select terminal information density |
+| `defaultMotion` | `off`, `subtle`, `full` | Select activity animation intensity |
+| `defaultToolProfile` | `auto`, `creative`, `research`, `draft`, `audit`, `delivery` | Initial active-tool policy |
+| `maxStudioAgents` | 1–12 | Bound a Hive task batch |
+| `projectRootMode` | `child`, `cwd` | Create a child project or use the current directory |
+| `destructiveProjectCommands` | `block`, `allow` | Guard recursive destructive commands |
+| `gitMode` | `off`, `checkpoint`, `branch-per-stage` | Control production checkpoints |
+| `hudPlacement` | `aboveEditor`, `belowEditor` | Place the production HUD |
+| `showThinkingLane` | boolean | Annotate visible thinking with stage/execution lane |
+
+`/pom settings` persists view/motion in project state and HUD/thinking options in `.omp/pom.json`.
+
+## Compatibility and verification state
+
+| Requirement | Window | Source |
+|---|---|---|
+| `@oh-my-pi/pi-coding-agent` | `>=16.4.6 <17` | `peerDependencies` |
+| `@oh-my-pi/pi-tui` | `>=16.4.6 <17` | `peerDependencies` |
+| `@oh-my-pi/pi-utils` | `>=16.4.6 <17` | `peerDependencies` |
+| Bun | `>=1.3.14` | `engines.bun` |
+| Node.js + npm | Node 22 or newer | Local scripts and the `node:test` suite |
+
+Verification state is PARTIAL. `npm run smoke`, `npm run release:check`, and `node --import tsx --test tests/state.test.ts` pass. The full `npm run verify` gate is blocked: an npm registry outage left `node_modules` incomplete (OMP SDK peer packages, `@types/node`, `yauzl`, and the OMP theme schema that `scripts/verify.mjs` reads). Restore registry access, reinstall, then rerun the full gate. See the README sections Verification status and Registry outage and offline guidance.
--- a/docs/TOOL_MATRIX.md
+++ b/docs/TOOL_MATRIX.md
@@ -0,0 +1,38 @@
+# Tool matrix
+
+## POM tools
+
+| Tool | Approval | Responsibility |
+|---|---|---|
+| `pom_state` | write | Read/configure project state and record decisions, assumptions, or warnings |
+| `pom_stage` | write | Start, navigate, evidence, block, resolve, and pass stages (validation-gated) |
+| `pom_artifact` | write | Measure, hash, version, classify, and register a canonical artifact |
+| `pom_validate` | read | Run deterministic scoped checks and emit an expandable report card |
+| `pom_prompt` | read | List or retrieve bundled/project prompt fragments and provenance |
+| `pom_hive` | write | Plan native task batches, record IRC signals, and persist synthesis |
+| `pom_export` | write | Build and fully verify checkpoint or final archives |
+
+## Native OMP delegation
+
+| Primitive | POM use |
+|---|---|
+| `task` | Exactly one bounded batch per independent specialist wave |
+| IRC | Short ownership, dependency, alert, handoff, and completion signals |
+| todo | Exact phase plan for the active stage |
+| Swarm extension | Optional unattended parallel/sequential/pipeline DAG |
+| session entries | Append-only POM state restoration across branches |
+| model roles | Deep planning/audit versus sustained drafting |
+| active-tool profiles | Minimize context and risk for each stage |
+
+## Validation scopes
+
+| Scope | Checks |
+|---|---|
+| `quick` | State shape and basic invariants |
+| `stage` | Active stage contract, artifacts, evidence, and blockers |
+| `canon` | Canon-oriented artifacts and manifest metadata |
+| `continuity` | Timeline, continuity ledger, and unresolved issue markers |
+| `knowledge` | Vault structure and wikilink targets |
+| `files` | Manifest paths, sizes, hashes, duplicates, and symlinks |
+| `delivery` | All delivery prerequisites, rights metadata, checksums, and package structure |
+| `all` | Broad project validation; final delivery should still use `delivery` |
--- a/docs/VAULT.md
+++ b/docs/VAULT.md
@@ -0,0 +1,101 @@
+---
+title: Generated Project Vault Shape
+description: The canonical directory structure and content types created by bootstrapProject
+---
+
+# Generated Project Vault Shape
+
+Created by `src/persistence.ts:226-239` (`bootstrapProject`). This is the *project* knowledge base, not the extension wiki.
+
+## Top-level directories
+
+```
+<project-root>/
+├── 00_admin/                 # Canonical state, manifests, ledgers, checksums
+│   ├── project_state.json    # Active POM state (source of truth)
+│   ├── artifact_manifest.json
+│   ├── artifact_events.jsonl
+│   ├── SHA256SUMS.txt
+│   ├── validation/           # Gate reports (stage-N-scope-stamp.json)
+│   ├── hive/                 # Hive mission records
+│   └── swarms/               # Optional Swarm DAG definitions
+├── 01_planning/              # Stage 0-3 outputs
+│   ├── brief.md
+│   ├── genre.md
+│   ├── voice.md
+│   └── story_store.md
+├── 02_story_bible/           # Stage 4 outputs
+│   ├── canon.md
+│   ├── cast.md
+│   ├── world.md
+│   ├── timeline.md
+│   ├── continuity.md
+│   └── visual_bible/
+├── 03_manuscript/            # Stage 5-7 outputs
+│   ├── outline.md
+│   ├── scenes/
+│   └── chapters/
+├── 04_images/                # Visual assets
+│   ├── references/
+│   ├── generated/
+│   ├── briefs/
+│   └── approvals/
+├── 05_research/              # Source notes and rights
+│   ├── sources.md
+│   ├── notes.md
+│   ├── fact_invention.md
+│   └── rights.md
+├── 06_ledgers/               # Decisions, revisions, continuity, quality, validation
+│   ├── decisions.jsonl
+│   ├── assumptions.jsonl
+│   ├── revisions.jsonl
+│   ├── continuity.jsonl
+│   ├── quality.jsonl
+│   └── validation.jsonl
+├── 07_exports/               # Checkpoint and final archives
+│   ├── <slug>-checkpoint-<stamp>.zip
+│   ├── <slug>-final-<stamp>.zip
+│   └── <base>.verification.json
+├── content/                  # Obsidian/Quartz knowledge projection
+│   ├── index.md
+│   ├── canon/
+│   ├── cast/
+│   ├── timeline/
+│   ├── manuscript/
+│   └── research/
+└── .omp/                     # Host and POM project configuration
+    ├── config.yml            # OMP host settings (theme, task concurrency, etc.)
+    ├── pom.json              # POM project settings
+    └── prompts/              # Project-local prompt overrides
+```
+
+## Vault content conventions
+
+| Directory | Format | Purpose |
+|---|---|---|
+| `content/` | Markdown + YAML frontmatter + wikilinks | Human-navigable knowledge projection |
+| `00_admin/` | JSON/JSONL | Machine-readable canonical state and evidence |
+| `01_planning`–`05_research` | Markdown | Author-facing creative artifacts |
+| `06_ledgers` | JSONL | Append-only decision/revision/continuity logs |
+| `07_exports` | ZIP + JSON | Verified delivery archives with sidecars |
+| `.omp/` | YAML/JSON | Project-scoped configuration |
+
+## Quartz compatibility
+
+- `content/` is a valid Quartz 5 content vault
+- Frontmatter uses `title`, `tags`, `aliases`, `date`, `modified`
+- Wikilinks use `[[page]]` and `[[page|alias]]` syntax
+- Callouts use `> [!note]`, `> [!warning]`, `> [!important]`
+- Maps of content via `dataview` or manual index pages
+- `quartz.config.ts` for the project is generated from `config/config.yml` template
+
+## Source of truth hierarchy
+
+1. Project filesystem (`00_admin/project_state.json`, artifact files, ledgers)
+2. `content/` vault (navigable projection, derived from #1)
+3. OMP session state (append-only, never canonical)
+4. Memory (Mnemopi) — ephemeral, never canonical
+
+## Regeneration
+
+The vault is **not** regenerated from source on every change. It is incrementally updated by `src/persistence.ts` when artifacts are registered or state changes. To fully rebuild: `rm -rf content && /pom vault` (re-projects from canonical state).
--- a/docs/VERIFICATION.md
+++ b/docs/VERIFICATION.md
@@ -0,0 +1,156 @@
+---
+title: Documentation verification
+description: The six documentation-contract checks in scripts/check-docs.mjs and how to prove they fail
+---
+
+# Documentation verification
+
+`scripts/check-docs.mjs` is the drift detector for facts that are mirrored out of source into
+Markdown, `POM.yml`, `package.json`, and `RELEASE.json`. Every fact POM documents has exactly one
+canonical owner in `src/`, `scripts/`, or `package.json`; the checker fails when a mirror stops
+matching its owner.
+
+The checker is read-only, self-contained ESM, and imports only `node:fs`, `node:path`, and
+`node:url`. It never writes files, never runs a build, and needs no `node_modules`, so it stays
+runnable while the npm registry is unreachable.
+
+## Running the checker
+
+```bash
+node scripts/check-docs.mjs
+```
+
+Each check prints one line, with actionable detail indented beneath a failure:
+
+```text
+PASS  check 1/6 resource-package-parity
+PASS  check 2/6 command-parity
+      note: /pom resume is absent from src/command.ts HELP; allowlisted in KNOWN_COMMAND_DIVERGENCES
+FAIL  check 3/6 layout-contract
+      docs/INVENTORY.md:43 names "06_exports", which src/persistence.ts bootstrapProject never creates; the canonical names are 06_ledgers and 07_exports
+POM docs verification FAIL (1/6: layout-contract)
+```
+
+The final line is `POM docs verification PASS` with exit code 0, or
+`POM docs verification FAIL (<count>/6: <check names>)` with exit code 1. All six checks always
+run; one failure never hides another.
+
+## The six checks
+
+| # | Name | Canonical owner | Mirrors checked |
+|---|---|---|---|
+| 1 | `resource-package-parity` | `src/prompts.ts`, `src/themes.ts`, `src/events.ts` | `package.json` `files` |
+| 2 | `command-parity` | `src/command.ts` `HELP` | `README.md` command map, `POM.yml` `commands:` |
+| 3 | `layout-contract` | `src/persistence.ts` `bootstrapProject` | `docs/INVENTORY.md`, `skills/pom/references/artifacts.md` |
+| 4 | `prompt-order-contract` | `src/prompts.ts` `composePromptStack` and `renderStagePrompt` | `POM.yml` `prompt_precedence` |
+| 5 | `link-and-orphan` | the `docs/` tree on disk | every `docs/*.md` page |
+| 6 | `release-evidence` | `scripts/release-manifest.mjs` gate readers | `RELEASE.json` `verification` |
+
+### 1. resource-package-parity
+
+Defends the published tarball against missing runtime resources. The checker regex-matches
+`new URL("../<root>", import.meta.url)` in the three resource-loading modules, then asserts every
+discovered root is listed in `package.json` `files` and exists in the repository. The root list is
+derived from source on every run, so a newly bundled resource directory cannot be added in code and
+silently left out of the package.
+
+Historical defect: `prompts` was loaded by `src/prompts.ts` and `src/events.ts` but omitted from
+`package.json` `files`, so an installed copy of the extension shipped without any prompt fragments
+while the repository checkout worked. A hardcoded root list would not have caught it, and would
+rot the next time a root is added, so discovery failure is itself a failure: if the regex matches
+nothing the check reports a broken checker rather than an empty pass.
+
+### 2. command-parity
+
+Defends the advertised command surface. The verbs are extracted from the `HELP` template literal in
+`src/command.ts`, from the `## Command map` table in `README.md`, and from the `commands:` block in
+`POM.yml`. A bare `/pom` normalizes to the verb `dashboard`, and only the first token after `/pom`
+is significant, so `/pom theme install` contributes `theme`. The three sets must agree.
+
+Historical defect: `/pom settings` and `/pom doctor` were implemented and advertised by `HELP` but
+missing from both documented command maps, so operators had no written record of two shipped verbs.
+
+### 3. layout-contract
+
+Defends the generated project layout. `06_exports` and `06_logs` are forbidden in
+`docs/INVENTORY.md` and `skills/pom/references/artifacts.md`, and the canonical `06_ledgers` and
+`07_exports` must both appear in `docs/INVENTORY.md`. Failures cite the offending line numbers.
+
+Historical defect: docs described the export directory as `06_exports` and invented a `06_logs`
+directory. `bootstrapProject` creates neither, so operators looked for output in paths that never
+exist and scripted against directory names the kernel never writes.
+
+### 4. prompt-order-contract
+
+Defends prompt provenance ordering. `POM.yml` `prompt_precedence` must open with the immutable POM
+production law that `composePromptStack` prepends, must state that project-local fragments replace
+bundled fragments by matching ID, and must close with the executable stage contract. The stage
+contract must appear only as the final entry.
+
+Historical defect: the manifest listed the executable stage contract mid-list, contradicting
+`renderStagePrompt`, which appends it last. Anyone reasoning about prompt precedence from the
+manifest inferred the wrong effective law, since a later fragment overrides an earlier one.
+
+### 5. link-and-orphan
+
+Defends wiki navigability in two independent directions, reported separately. Every relative
+Markdown link in `docs/*.md` must resolve to a path that exists on disk, with fragments and query
+strings stripped and absolute, anchor-only, and scheme-qualified links skipped. Separately, every
+`docs/*.md` page except `index.md` must be linked from `docs/index.md` or `docs/navigation.md`.
+
+Historical defect: navigation entries used repository-root paths such as `README.md` and
+`skills/pom/references/commands.md` from inside `docs/`, where they resolve to `docs/README.md` and
+`docs/skills/...` and render as dead links. New pages were also added without a navigation entry,
+leaving them reachable only by direct URL. The reachability half applies to this page too: a new
+`docs/*.md` file, including `VERIFICATION.md`, must be linked from `docs/index.md` or
+`docs/navigation.md` or the check reports it as unreachable.
+
+### 6. release-evidence
+
+Defends release honesty. Every key under `RELEASE.json` `verification` must be an object carrying a
+`status` string of `PASS`, `FAIL`, `NOT RUN`, or `BLOCKED`. A bare string, number, null, or array
+value fails, and so does an unrecognized status. `scripts/release-manifest.mjs` produces these
+objects from evidence files under `00_admin/validation/`; this check is the regression guard that
+keeps them evidence-bound.
+
+Historical defect: the manifest carried hard-coded `"PASS"` strings for gates that had never been
+executed, so the release claimed verification it could not support.
+
+## Known divergences
+
+`KNOWN_COMMAND_DIVERGENCES` in `scripts/check-docs.mjs` is the only escape hatch, and it contains
+exactly one entry: `resume`. `/pom resume [state-path]` is documented in the `README.md` command map
+and in the `POM.yml` `commands:` block but is deliberately absent from `HELP`. `HELP` stays
+canonical for what the built-in help advertises, the docs keep the verb, and check 2 prints the
+divergence as a `note:` line so it stays visible while the check still passes deterministically. Any
+divergence not in the allowlist fails.
+
+## Mutation proofs
+
+Each row is a specified procedure for proving that a check actually defends its contract: apply the
+mutation, run `node scripts/check-docs.mjs`, confirm the named check reports `FAIL` with the
+expected message, then revert the mutation and confirm the run returns to
+`POM docs verification PASS`. Mutations are destructive edits to canonical files and must be
+reverted before any commit or package step. This section specifies the procedure and the expected
+output; it records no executed results, because the checker was not run when this page was written.
+
+| Check | Mutation to apply | Expected failure |
+|---|---|---|
+| 1 `resource-package-parity` | Remove `"prompts"` from the `files` array in `package.json` | `FAIL  check 1/6 resource-package-parity` — `package.json: files must contain "prompts" because src/prompts.ts and src/events.ts load it at runtime` |
+| 2 `command-parity` | Delete the `/pom status [--json]` row from the `## Command map` table in `README.md` | `FAIL  check 2/6 command-parity` — `/pom status is documented in src/command.ts HELP, POM.yml commands: but absent from README.md ## Command map` |
+| 3 `layout-contract` | Rename `06_ledgers` to `06_logs` on the ledger line of `skills/pom/references/artifacts.md` | `FAIL  check 3/6 layout-contract` — `skills/pom/references/artifacts.md:10 names "06_logs", which src/persistence.ts bootstrapProject never creates` |
+| 4 `prompt-order-contract` | In `POM.yml` `prompt_precedence`, move the executable stage contract entry above the project-local fragment entry so it is no longer last | `FAIL  check 4/6 prompt-order-contract` — `POM.yml: prompt_precedence must end with the executable stage contract appended by renderStagePrompt`, plus the misplaced-entry position |
+| 5 `link-and-orphan` | In `docs/index.md`, change the Package inventory link target from `INVENTORY.md` to `INVENTORY-old.md` | `FAIL  check 5/6 link-and-orphan` — `docs/index.md: broken relative link INVENTORY-old.md resolves to docs/INVENTORY-old.md, which does not exist on disk`, and `docs/INVENTORY.md: unreachable page` if `docs/navigation.md` no longer links it either |
+| 6 `release-evidence` | Replace the `verification.runtimeSmoke` object in `RELEASE.json` with the bare string `"PASS"` | `FAIL  check 6/6 release-evidence` — `RELEASE.json: verification.runtimeSmoke is the bare string "PASS"; every gate must be an evidence object carrying a status` |
+
+Row 5 mutates a link rather than deleting a file, so the mutation is a one-token edit and the revert
+is exact. Row 6 must be reverted by regenerating the manifest with `npm run release:manifest` rather
+than by hand, so the recorded hashes stay consistent with the packaged files.
+
+## Relationship to the other gates
+
+`node scripts/check-docs.mjs` is a documentation-contract gate, not a replacement for the release
+ladder in `package.json`. It complements `node scripts/verify.mjs`, which checks structure and
+counts, and `npm run release:check`, which proves `RELEASE.json` matches the packaged tree. The
+documentation checker is the only gate that reads prose, so it is the only one that can catch a doc
+that quietly contradicts source.
--- a/docs/index.md
+++ b/docs/index.md
@@ -0,0 +1,69 @@
+# POM 2 Documentation
+
+Welcome to the POM 2 documentation. This site is the single source of truth for operators, contributors, and architects.
+
+## Quick navigation
+
+| Audience | Entry points |
+|---|---|
+| Operator | [Install & verify](../README.md#install-and-verify) · [Production loop](../README.md#production-loop) · [Command map](../README.md#command-map) · [Settings](SETTINGS.md) |
+| Contributor | [AGENTS.md](../AGENTS.md) · [Architecture](ARCHITECTURE.md) · [Tool Matrix](TOOL_MATRIX.md) · [Development](../README.md#development) |
+| Architect | [Architecture](ARCHITECTURE.md) · [POM.yml](../POM.yml) · [Ownership](OWNERSHIP.md) · [Boundary](BOUNDARY.md) |
+| Release / Audit | [Inventory](INVENTORY.md) · [Audit](AUDIT.md) · [Design review](DESIGN_REVIEW.md) · [Official sources](OFFICIAL_SOURCES.md) · [Verification](VERIFICATION.md) |
+| Project vault | [Vault shape](VAULT.md) · [Repository vs vault boundary](BOUNDARY.md) |
+| Agent / Quick-ref | [Commands](../skills/pom/references/commands.md) · [Workflow](../skills/pom/references/workflow.md) · [Artifacts](../skills/pom/references/artifacts.md) · [Tool routing](../skills/pom/references/tool-routing.md) · [QA](../skills/pom/references/qa.md) · [UI](../skills/pom/references/ui.md) |
+
+Full sidebar: [navigation](navigation.md).
+
+## What is POM 2?
+
+POM 2 is an Oh My Pi (OMP) extension that governs long-form creative production with evidence-gated stages, canonical artifacts, prompt provenance, deterministic validation, Git checkpoints, and an Obsidian/Quartz-compatible knowledge base.
+
+- Package: `@jamminrebel/pom-omp` 2.0.0 (MIT, ESM)
+- Peer requirements: `@oh-my-pi/pi-coding-agent`, `@oh-my-pi/pi-tui`, `@oh-my-pi/pi-utils` `>=16.4.6 <17`
+- Host runtime: Bun `>=1.3.14`
+- Local scripts: Node 22+ / npm / tsx / tsc
+
+## Repository structure
+
+```
+pom-omp/
+├── src/                  # 25 TypeScript modules (no build step)
+├── tests/                # 8 test files, Node test runner
+├── scripts/              # verify.mjs, check-docs.mjs, release-manifest.mjs, smoke.ts
+├── docs/                 # This documentation
+├── agents/               # 14 pom-* task agent definitions
+├── prompts/              # 13 prompt fragments (bundled + project overrides)
+├── rules/                # 3 scoped production rules
+├── skills/pom/           # POM skill + 9 reference documents
+├── themes/               # pom-nocturne (dark), pom-parchment (light)
+├── config/               # OMP host config, POM defaults, MCP example
+├── README.md             # Operator landing page
+├── POM.yml               # Human-facing project manifest
+├── AGENTS.md             # Contributor guide + discrepancy ledger
+├── CHANGELOG.md          # Release history
+├── RELEASE.json          # Generated release manifest
+├── package.json          # Package metadata + scripts
+└── tsconfig.json         # Strict TS config (src/**/*.ts only)
+```
+
+## Documentation principles
+
+- Source beats docs. Every mirrored fact cites its canonical owner in `src/`, `scripts/`, or `package.json`. Narrative docs must not introduce independent variants. See [ownership](OWNERSHIP.md).
+- Audience separation. Operator flows in README; deep reference in `docs/`; agent-facing quick refs in `skills/pom/references/`; human manifest in `POM.yml`.
+- Release honesty. `RELEASE.json` verification fields are evidence-bound objects carrying a status of PASS, FAIL, NOT RUN, or BLOCKED. Hard-coded PASS strings are prohibited and rejected by [the documentation checks](VERIFICATION.md).
+- Generated versus repository. This wiki describes the extension. Generated project vaults live under a project's `content/` and are a separate branch. See [boundary](BOUNDARY.md) and [vault shape](VAULT.md).
+
+## Verification status
+
+Overall readiness is PARTIAL. `npm run smoke`, `npm run release:check`, and the state test pass; the full `npm run verify` gate is blocked by an npm registry outage that left `node_modules` incomplete. See [verification](VERIFICATION.md) and the README verification section for exact detail.
+
+## Contributing
+
+Read [AGENTS.md](../AGENTS.md) for code conventions, testing patterns, and governance invariants. Key rules:
+
+- No `dist/` or generated caches in source
+- Extensionless relative imports (`./state`, not `./state.ts`)
+- Throw `Error` for precondition/schema/config violations; tool failures use `isError: true`
+- Three runtime dependencies only: `crc-32`, `yauzl`, `yazl`
+- Run `npm run verify` before packaging or linking
--- a/docs/navigation.md
+++ b/docs/navigation.md
@@ -0,0 +1,60 @@
+---
+title: POM 2 Documentation
+description: Single source of truth for POM 2 operators, contributors, and architects
+---
+
+# Navigation
+
+This file defines the sidebar structure for the Quartz-rendered wiki. Landing page: [index](index.md).
+
+## Operator
+
+- [Install & verify](../README.md#install-and-verify)
+- [Production loop](../README.md#production-loop)
+- [Command map](../README.md#command-map)
+- [Settings](SETTINGS.md)
+
+## Contributor
+
+- [Repository guidelines](../AGENTS.md)
+- [Architecture](ARCHITECTURE.md)
+- [Tool matrix](TOOL_MATRIX.md)
+- [Development](../README.md#development)
+
+## Architect
+
+- [Architecture](ARCHITECTURE.md)
+- [Project manifest](../POM.yml)
+- [Ownership table](OWNERSHIP.md)
+- [Repository vs vault boundary](BOUNDARY.md)
+
+## Release / Audit
+
+- [Package inventory](INVENTORY.md)
+- [Audit log](AUDIT.md)
+- [Design review](DESIGN_REVIEW.md)
+- [Official sources](OFFICIAL_SOURCES.md)
+- [Verification and mutation proofs](VERIFICATION.md)
+
+## Project vault
+
+- [Generated vault shape](VAULT.md)
+- [Repository vs vault boundary](BOUNDARY.md)
+
+## Agent / Quick reference
+
+- [Commands](../skills/pom/references/commands.md)
+- [Workflow](../skills/pom/references/workflow.md)
+- [Artifacts](../skills/pom/references/artifacts.md)
+- [Agent studios](../skills/pom/references/agent-studios.md)
+- [Todo blueprints](../skills/pom/references/todo-blueprints.md)
+- [Tool routing](../skills/pom/references/tool-routing.md)
+- [QA](../skills/pom/references/qa.md)
+- [UI](../skills/pom/references/ui.md)
+
+## Meta
+
+- [Documentation index](index.md)
+- [This navigation file](navigation.md)
+- [Documentation principles](index.md#documentation-principles)
+- [Verification status](index.md#verification-status)