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/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