# 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