coding-os 0.3.2__py3-none-any.whl

templates/_base/scaffold/docs/governance/scaffold-boundary-contract.md

@@ -0,0 +1,161 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-05-13 -->
+# Scaffold Boundary Contract
+
+> P: Defines `src/templates/<stack>/scaffold-boundary.yaml` — machine-readable subtree isolation rules so multi-stack projects (`src/mobile/` + `src/backend/` + `src/ai-service/`) can never write outside their lane.
+> R: Adding a new stack, debugging a `boundary mismatch` block, or auditing cross-stack import discipline.
+> S: Authoring code — read the per-stack `anatomy.md` instead.
+> N: [anatomy-contract.md](anatomy-contract.md), [docs-system.md](docs-system.md)
+
+> Nav: [Governance Index](./00-index.md)
+
+---
+
+## File location
+
+```
+src/templates/<stack>/scaffold-boundary.yaml
+```
+
+One file per stack. Ships alongside `stack.yaml`. The aggregator merges every installed stack's boundary at `cos init` into the consumer project's `.coding-os/scaffold-boundary.yaml`.
+
+## Schema
+
+```yaml
+version: 1
+stack: <stack-id>            # MUST equal stack.yaml::id
+roots:                       # Subtree(s) this stack owns. Relative to project root.
+  - <path>/                  # Trailing slash required. Conventionally under src/.
+file_patterns:               # Globs the stack OWNS (and only this stack may write).
+  - "**/*.<ext>"
+imports_from:                # Other-stack subtrees this stack MAY import from (read-only).
+  - <path>/
+forbids_writing_in:          # Other-stack subtrees this stack MUST NEVER write to.
+  - <path>/
+notes:                       # Optional free-text.
+  - <one-line>
+```
+
+Every field is required EXCEPT `notes`. Empty arrays (`forbids_writing_in: []`) are accepted; missing keys are rejected by the parser.
+
+## Field semantics
+
+### `version`
+
+Always `1` for now. Bump only if the schema changes incompatibly; old consumer projects pin their boundary file's version.
+
+### `stack`
+
+The stack id from `stack.yaml::id`. Validation: `re.fullmatch(r"[a-z0-9][a-z0-9-]{0,30}", stack)`. The aggregator rejects mismatches.
+
+### `roots`
+
+The directory (or directories) the stack writes into. A multi-stack project has each stack in its own root under `src/`:
+
+```
+project/
+  src/mobile/        ← react-native root
+  src/backend/       ← go-fiber root
+  src/ai-service/    ← fastapi root
+  src/shared/        ← imports_from target (cross-stack types/contracts)
+```
+
+A stack may declare multiple roots only when it legitimately produces files in disjoint trees. Two stacks claiming the same root = aggregator rejects at `cos init`.
+
+### `file_patterns`
+
+Globs whose match implies "this stack owns this file." `enforce-skill.sh` uses these to pick the matching skill on every Write/Edit. Typical:
+
+| Stack | file_patterns |
+|---|---|
+| nextjs | `src/frontend/**/*.{ts,tsx,js,jsx}` |
+| react-native | `src/mobile/**/*.{ts,tsx}` |
+| django | `src/backend/**/*.py` |
+| go-fiber | `src/backend/**/*.go` |
+| fastapi | `src/ai-service/**/*.py` |
+
+When two stacks could match (e.g. fastapi + django both want `**/*.py`), disambiguate with a more specific root prefix.
+
+### `imports_from`
+
+Whitelist of subtrees this stack's source may IMPORT from. Empty list = no cross-stack imports allowed. Standard convention:
+
+```yaml
+imports_from:
+  - src/shared/        # cross-stack types / contracts
+  - src/shared/types/
+```
+
+Avoid listing other stack roots here. If your react-native code needs go types, add a contract layer in `src/shared/` instead.
+
+### `forbids_writing_in`
+
+Hard list of subtrees this stack must never write to. PreToolUse Write/Edit hook blocks. Typical:
+
+```yaml
+# nextjs/scaffold-boundary.yaml
+forbids_writing_in:
+  - src/mobile/
+  - src/backend/
+  - src/ai-service/
+```
+
+If the agent's active stack-skill is `nextjs-react` and it tries to Write `src/backend/api.go`, the hook blocks with:
+
+```
+BLOCKED: stack 'nextjs' cannot write to src/backend/. Boundary defined at:
+  src/templates/nextjs/scaffold-boundary.yaml::forbids_writing_in
+Switch to the right skill or open a multi-stack task.
+```
+
+## Aggregation at `cos init`
+
+When `cos init -t nextjs,go-fiber,react-native` runs, the CLI:
+
+1. Reads each stack's `scaffold-boundary.yaml`.
+2. Validates every `roots` entry is unique across all installed stacks.
+3. Validates `imports_from` only references subtrees that exist in the merged set OR `src/shared/`.
+4. Writes `.coding-os/scaffold-boundary.yaml` in the consumer project — a flat list of every stack's boundary.
+
+The consumer project's hook reads `.coding-os/scaffold-boundary.yaml` at runtime; it does not re-read the meta-repo.
+
+## Hook integration
+
+`src/core/hooks/enforce-skill.sh` (PreToolUse Write|Edit) consults the consumer's `.coding-os/scaffold-boundary.yaml`:
+
+```
+on Write/Edit of <path>:
+  matched_stack = first stack whose file_patterns matches <path>
+  active_stack = active skill's owner stack (from .coding-os/<agent>/.role)
+
+  if matched_stack and matched_stack != active_stack:
+    if <path> in any active stack's forbids_writing_in:
+      BLOCK
+    else:
+      WARN  # cross-stack edit allowed but flagged
+```
+
+The hook is fire-and-forget for WARN, BLOCK for forbids — never silent.
+
+## Authoring rules
+
+- One file per stack. Multi-stack rules belong in the consumer project's aggregated copy.
+- Use forward-slash paths even on Windows hosts.
+- `roots` MUST end with `/` and conventionally start with `src/`; file_patterns MUST be globs.
+- Every `forbids_writing_in` entry MUST appear as a `roots` entry in another installed stack — otherwise the rule is unreachable.
+
+## Validation
+
+`tests/test_scaffold_boundary_contract.py` runs on every PR and asserts:
+
+- Every `src/templates/<stack>/scaffold-boundary.yaml` parses as YAML.
+- Required keys present; types match.
+- `stack` field equals enclosing dir name.
+- No two stacks share a root.
+- No `forbids_writing_in` entry references a path no installed stack owns.
+
+## Adding a stack
+
+1. Drop `src/templates/<stack>/scaffold-boundary.yaml` per schema above.
+2. Run `pytest tests/test_scaffold_boundary_contract.py -q` to verify.
+3. Run `make manifest-regen` so `src/core/scaffold_manifest.json` picks the new stack up.
+4. Run a smoke `cos init -t <stack> --debug` to confirm aggregation works.

templates/_base/scaffold/docs/governance/task-lifecycle.md

@@ -0,0 +1,125 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-05-08 | module:tasks -->
+# Task Lifecycle Policy
+
+> P: Canonical lifecycle for creating, executing, and closing tasks under the Scrumban model (`src/core/board_os/`).
+> R: Creating a task, transitioning status, or aligning task scripts and templates.
+> S: Reading existing task content unrelated to lifecycle change.
+> N: [docs-system.md](docs-system.md), [agent-workflow.md](agent-workflow.md), [_templates/task-detail.md](_templates/task-detail.md)
+
+> Nav: [Governance Index](./00-index.md) | [Docs Index](../00-index.md)
+
+## SSOT and Mirrors
+
+- `docs/tasks/TASK-###-slug.md` — **canonical detail file**. One per active or completed task. File frontmatter and body are the source of truth.
+- `src/core/board_os/db.py` (table `tasks`) — **derived mirror**. Mtime-incremental sync from the detail files; never edited by hand.
+- `cos board` / `cos board --web` — **live view** rendered from the DB.
+
+There is no flat `docs/tasks.md` index. Status is read from frontmatter, not from a top-level checkbox file.
+
+## Status States
+
+`icebox → in_progress → testing → complete`, plus `blocked` reachable from any state (and `emergency` / `archive` for the incident and retirement lanes).
+
+Transitions go through `cos task-*` (or the equivalent MCP tool). The CLI writes the detail-file frontmatter and the DB row atomically; manual edits to one side without the other create drift that the doctor will flag.
+
+## Required Artifacts
+
+For any task that is `in_progress`, `testing`, `blocked`, or `complete`:
+
+- A primary detail file at `docs/tasks/TASK-###-slug.md` authored from `src/templates/task-detail.md`.
+- A non-empty Work Log section once execution starts (transition gates check this).
+- An Outcome line at the top, plus Read First, Acceptance (Given/When/Then), and Rollback sections.
+- Optional companion reference docs only when the primary file would exceed the size cap (warn ≥1.5 k tokens, block ≥3 k — Rule 14).
+
+Backlog entries that are not yet started may live in `cos board` (icebox status) without a detail file. Detail file becomes required at the moment of first transition out of icebox.
+
+## Execution Rules
+
+- Move the task to `in_progress` before any substantial Write/Edit. Hooks block code edits without an active task marker.
+- Complexity Gate (AGENTS.md § Core Loop) runs in Classify before Orient. The gate's Dimension Map and Read List inform the rest of the loop and are recorded in the task's Notes when non-trivial.
+- Keep Work Log up to date as you go — one bullet per meaningful checkpoint. The CLI's `cos work-log TASK-NNN "note"` is preferred so the DB cache (`work_log_last_5`) stays fresh.
+- Use `Given / When / Then` for Acceptance criteria.
+- Move to `complete` only after Verification Matrix tests for the changed surface pass. Untested error paths fail the gate.
+- Search the repo and the graph before creating any new file, pattern, or rule. Reuse beats reinvention.
+
+## Primary Task File Contract
+
+Required sections in this order (template lives at `src/templates/task-detail.md`):
+
+- `## Outcome` — single sentence describing the externally visible result.
+- `## Read First` — annotated list of files and refs the executor should load before editing.
+- `## Acceptance` — numbered list, Given/When/Then format.
+- `## Work Log` — append-only bullets, newest at the bottom.
+- `## Rollback` — one-paragraph plan for backing the change out.
+
+Optional sections:
+
+- `## Notes` — working notes, findings, dimension maps for COMPLICATED+ tasks.
+- `## Dependencies` — only when the task is gated by other tasks; mirrored in the `depends_on` frontmatter.
+
+## Frontmatter Fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `id` | yes | matches the file name slug |
+| `title` | yes | one line, no trailing punctuation |
+| `swimlane` | yes | agent-defined; common: `infra`, `frontend`, `docs`, `research` |
+| `kind` | yes | one of `feature · bug · chore · spike · docs · refactor · test · security` |
+| `status` | yes | `icebox · in_progress · testing · blocked · complete · emergency · archive` |
+| `priority` | yes | `P1 · P2 · P3` |
+| `appetite` | yes | shape-up budget, e.g. `30m · 2h · 1d · 2w` |
+| `epic`, `labels` | no | grouping helpers |
+| `depends_on`, `blocked_by` | no | task IDs |
+| `references` | no | doc paths the task points at |
+| `created`, `started`, `completed` | auto | written by the CLI on transitions |
+| `agent_session` | auto | fingerprint of the agent that started the task |
+
+## CLI and MCP Surface
+
+| Action | CLI | MCP |
+|---|---|---|
+| View board | `cos board` / `cos board --web` | `cos_task_board` |
+| Create | `cos task-create --title "…" --swimlane … --kind …` | `cos_task_create` |
+| Start | `cos task-start TASK-NNN` | `cos_task_move` → `in_progress` |
+| Move to testing | `cos task-move TASK-NNN --to testing` | `cos_task_move` → `testing` |
+| Complete | `cos task-done TASK-NNN` | `cos_task_move` → `complete` |
+| Block | `cos task-move TASK-NNN --to blocked` | `cos_task_move` → `blocked` |
+| Append work log | `cos work-log TASK-NNN "note"` | `cos_work_log_append` |
+| Daily standup | `cos daily` | `cos_task_daily` |
+| WIP check | `cos wip` | `cos_task_wip_check` |
+| Pick next | `cos task-pick` | `cos_task_pick` |
+
+## The `make task-*` wrappers
+
+`cos task-*` is the canonical task interface. `src/templates/_base/Makefile.base` keeps a few `make task-*` targets purely as muscle-memory wrappers — each shells straight out to `cos`:
+
+| Wrapper | Delegates to |
+|---|---|
+| `make task-start TASK=098` | `cos task-start TASK-098` |
+| `make task-done TASK=098` | `cos task-done TASK-098` |
+| `make task-block TASK=098 REASON="…"` | `cos task-block TASK-098 --reason "…"` |
+| `make task-create` | prints the `cos task-create` usage (it needs `--swimlane` / `--kind`) |
+
+The legacy file-based task system — the `task-*.sh` scripts and the flat `docs/tasks.md` index — has been removed. `make task-*` provides nothing that `cos task-*` does not; new code and docs should always call `cos task-*` directly.
+
+## Script Output Convention
+
+| Prefix | Meaning | Stream |
+|---|---|---|
+| `OK:` | success | stdout |
+| `ERROR:` | fatal | stderr, exit 1 |
+| `WARN:` | non-fatal | stderr |
+| `INFO:` | progress / context | stdout |
+
+## Outcome Tracking
+
+After every transition into `complete` or `blocked`, the workflow records an outcome row to `coding-os.db` for the Learning Loop:
+
+| Field | Values | Source |
+|---|---|---|
+| outcome | `success · rework · partial · blocked` | agent assessment |
+| duration_min | integer | session elapsed time |
+| model | active model id | dispatcher |
+| skills_used | JSON array | skill enforcement hook |
+
+Outcomes feed pattern extraction every N completions. See [agent-workflow.md](agent-workflow.md) § Memory & Learning.

templates/_base/scaffold/docs/governance/wrapper-derivation.md

@@ -0,0 +1,50 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-05-10 -->
+# Wrapper Derivation Policy
+
+Purpose: Define how editor- and tool-specific wrapper files (`.claude/`, `.codex/`) stay thin, derived, and subordinate to canonical SSOT docs.
+Read when: Editing `.claude/rules/*` or adding future wrappers such as `.github/instructions`.
+Skip when: The task only changes canonical docs and does not touch wrappers.
+Read next: `docs-system.md`, `agent-workflow.md`, and `mcp-tool-inventory.md`
+
+> Nav: [Docs Index](../00-index.md) | [AGENTS](../../AGENTS.md)
+
+## Rule
+
+- Canonical truth lives in `docs/` and root SSOT files such as `AGENTS.md`.
+- Wrapper files are derived adapters for a specific tool runtime.
+- Wrappers must never become a second source of project truth.
+
+## Thin-Wrapper Contract
+
+- Each wrapper includes exactly one `Source of truth:` line.
+- Each wrapper includes 1-3 canonical refs.
+- Each wrapper keeps only routing, verification, or scope hints needed by that tool.
+- Each wrapper body stays short enough to avoid loading duplicate context.
+
+## What Wrappers May Contain
+
+- path/glob targeting
+- one-line source-of-truth pointer
+- a small set of canonical refs
+- one verification line
+
+## What Wrappers Must Not Contain
+
+- product or architecture decisions
+- API contract details
+- schema names or field lists
+- workflow rules that differ from SSOT
+- copied policy text that can drift
+
+## Verification
+
+- `make docs-lint`
+
+## Wrapper Surfaces
+
+The coding-os adapter system creates wrappers automatically:
+
+- `.claude/rules/*` (Claude adapter — symlinks to `src/core/rules/`)
+- `.codex/instructions.md` (Codex adapter — merged from `src/core/rules/` + `src/core/skills/`)
+
+Wrappers are regenerated by `coding-os init` and `coding-os add-adapter`. Manual edits to wrappers are discouraged — change the canonical source instead.

templates/_base/scaffold/docs/insights/00-index.md

@@ -0,0 +1,17 @@
+<!-- domain:ALL | layer:index | ssot:true | updated:{{DATE}} -->
+# Breakthroughs — Index
+
+Purpose: Human-readable log of breakthrough narratives filed back by `cos_learn_narrative`. Each file captures a non-obvious insight from a rework→success cycle so future work can avoid the same dead-ends.
+Read when: Starting a task that touches an area with past breakthroughs, or onboarding to the project.
+Skip when: The active task is routine and no related breakthrough is surfaced by `cos_learn_suggest` / `cos_doc_search`.
+Read next: The specific breakthrough file relevant to the area you're working on.
+
+> Nav: [Docs Index](../00-index.md)
+
+## How entries are created
+
+Every call to `cos_learn_narrative` writes one markdown file here in addition to the DB record. Files are named `<TASK-ID>-<slug>.md` and are safe to edit by humans (the next narrative call for the same task overwrites its own file, not yours).
+
+## Indexing
+
+This folder is registered in `.coding-os/rag-config.yaml` as `type: breakthrough` with `priority: 0.8`. `make docs-index` picks up new files automatically — they become searchable via `cos_doc_search(source_types="breakthrough")`.

templates/_base/scaffold/docs/ops/00-index.md

@@ -0,0 +1,59 @@
+<!-- domain:OPS | layer:index | ssot:true | updated:{{DATE}} -->
+# Operations — Index
+
+Purpose: Navigation hub for operational runbooks and procedures.
+Read when: Deploying, debugging production, responding to an incident, or onboarding to ops.
+Skip when: The task is purely development-time (no production impact).
+Read next: The specific runbook relevant to your situation.
+
+> Nav: [Docs Index](../00-index.md)
+
+## Suggested Runbooks
+
+Populate as the project matures:
+
+- `monitoring.md` — Alerts, dashboards, on-call rotation
+- `backup-recovery.md` — Backup schedule, restore procedure, RTO/RPO
+- `zero-downtime-deploy.md` — Blue/green or rolling deploy procedure
+- `secrets-rotation.md` — How to rotate API keys, passwords, tokens
+- `staging-refresh.md` — How to refresh staging from production (anonymized)
+- `incident-response.md` — Severity levels, escalation, post-mortem template
+- `go-live-checklist.md` — Pre-launch verification checklist
+- `database-migrations.md` — How to safely apply schema migrations in production
+
+## Format
+
+Each runbook follows this structure:
+
+```markdown
+# Runbook Title
+
+## When to use this
+
+(symptom or trigger)
+
+## Prerequisites
+
+(access, tools, credentials needed)
+
+## Procedure
+
+1. Step 1
+2. Step 2
+3. Verify: (how to confirm success)
+
+## Rollback
+
+(how to undo if step N fails)
+
+## Post-procedure
+
+(notification, documentation, follow-up)
+```
+
+## Authoring Rules
+
+- Runbooks must be testable. Run them in staging before adding to ops/.
+- Never reference secret values inline. Use environment variable names.
+- Each runbook lists prerequisites explicitly — no "obvious" assumptions.
+- Update the runbook immediately after any incident reveals a missing step.

templates/_base/scaffold/docs/ops/runbooks/00-index.md

@@ -0,0 +1,9 @@
+<!-- domain:CORE | layer:index | ssot:false | updated:2026-06-06 -->
+# Runbooks
+
+Purpose: Index of operational runbooks — what to do when something breaks or needs a routine operation.
+Read when: during an incident, or before authoring a runbook with `cos doc-new --layer runbook --path docs/ops/runbooks/<slug>.md`.
+
+> Nav: [docs/](../../)
+
+No runbooks yet. This directory is scaffolded so the doc-cheat-sheet's create-time routing lands somewhere real.

templates/_base/scaffold/docs/playbooks/00-index.md

@@ -0,0 +1,12 @@
+<!-- domain:CORE | layer:index | ssot:false | updated:2026-06-14 -->
+# Playbooks
+
+Purpose: Index of task-oriented playbooks for this project — step-by-step guides for recurring work.
+Read when: looking for a playbook, or before authoring one with `cos doc-new --layer playbook --path docs/playbooks/<slug>.md`.
+
+> Nav: [docs/](../)
+
+These stack-agnostic playbooks ship with every project; stacks may add their own alongside them.
+
+- [Security Review Playbook](security-review.md) — consistent security review path for risky changes before they are considered complete.
+- [Research & Validation Playbook](research-validation.md) — current-state technical research with source discipline, converted into repo-safe decisions.

templates/_base/scaffold/docs/playbooks/research-validation.md

@@ -0,0 +1,29 @@
+<!-- domain:ALL | layer:playbook | ssot:true | updated:2026-03-13 -->
+# Research & Validation Playbook
+
+Purpose: Perform current-state technical research with source discipline and convert findings into repo-safe decisions.
+Read when: The task requires up-to-date framework/package standards, compatibility checks, or external architectural validation.
+Skip when: The answer is stable in local SSOT and does not depend on recent facts.
+Read next: Relevant local SSOT file, then the official external source for the specific topic
+
+> Nav: [Docs Index](../00-index.md) | [Docs System](../governance/docs-system.md)
+
+## Source Order
+
+1. Official framework or specification docs
+2. Official package docs or package metadata
+3. Primary-source repository docs / changelogs
+4. Secondary sources only if primary sources are insufficient
+
+## Research Rules
+
+- Record concrete versions and dates when recency matters.
+- Prefer official framework docs, package compatibility tables, and web standards over secondary sources.
+- Treat vendor blogs, community posts, and tutorials as non-canonical unless confirmed elsewhere.
+- When a finding changes architecture or workflow, move it into SSOT and cite the source in the task/change log.
+
+## Output Rules
+
+- Distinguish observed facts from inference.
+- State why a source is trustworthy when the choice is non-obvious.
+- Keep recommendations implementation-oriented, not generic.

templates/_base/scaffold/docs/playbooks/security-review.md

@@ -0,0 +1,41 @@
+<!-- domain:SECURITY | layer:playbook | ssot:true | updated:2026-03-17 -->
+# Security Review Playbook
+
+Purpose: Apply a consistent security review path for risky changes before code or docs are considered complete.
+Read when: The task touches auth, cookies, payments, file uploads, redirects, HTML rendering, admin access, download authorization, or permission checks.
+Skip when: The task is purely cosmetic docs work with no behavioral/security impact.
+Read next: your stack's engineering rules and the relevant API-contract doc for the risky path
+
+> Nav: [Docs Index](../00-index.md) | [Docs System](../governance/docs-system.md)
+
+## Read Selection Guide
+
+> Complete lookup: AGENTS.md § Dimension Type Registry § Security Overlay (auto-loaded). This section adds detail for Orient phase.
+
+Security is an overlay playbook — read the sub-files that match your task's security dimensions.
+
+### Read Only If Relevant (read ALL that apply, not just one)
+
+- Auth / JWT / sessions / login flows — your stack's auth-pattern docs
+- Cookies / CSRF / CORS / rate limiting / HTTP headers — your stack's web-security docs
+- File downloads or signed URLs — your stack's download-authorization docs
+- User data, sessions, or account lifecycle (GDPR deletion) — your stack's compliance docs
+- `docs/engineering/*-rules.md` — the engineering rules for the layer you are touching
+
+## Review Checklist
+
+- Authentication and authorization paths are explicit
+- Cookie/session settings remain `httpOnly`, `secure` in production, `SameSite=Strict`
+- Payment and webhook flows remain idempotent
+- Upload/download flows validate content type and access scope
+- Admin routes and privileged endpoints are not conflated with public routes
+- Logs and error responses do not leak secrets or internal implementation details
+- Error responses do not leak internal details (no raw exception text, DB column names, or provider URLs)
+- All error handling is fail-closed (reject on uncertainty, not allow-and-log)
+- Permission boundaries enforce the project's RBAC model — verify role checks on every protected endpoint
+
+## Verification
+
+- Run the domain verification commands from the primary playbook
+- Add at least one targeted test or explicit manual check for the risky path
+- If docs changed, confirm security rules and examples use current stack terminology

templates/_base/scaffold/docs/prd/00-index.md

@@ -0,0 +1,43 @@
+<!-- domain:PRODUCT | layer:index | ssot:true | updated:{{DATE}} | module:docs -->
+# Product Requirements — Index
+
+Purpose: Navigation hub for the Product Requirements Document (PRD).
+Read when: Starting a feature task that needs product context, or onboarding to the project.
+Skip when: The active task already references a specific PRD section.
+Read next: The relevant numbered section below.
+
+> Nav: [Docs Index](../00-index.md)
+
+## Suggested Structure
+
+The PRD is split into focused files. Each section is optional — populate as the project grows. Recommended order:
+
+- `01-snapshot-vision.md` — One-paragraph elevator pitch + 3-year vision
+- `02-goals-kpis.md` — Business goals and measurable KPIs
+- `03-users-jobs.md` — Personas + jobs-to-be-done
+- `04-information-architecture.md` — Page tree, navigation, content types
+- `05-ux-conversion.md` — Conversion funnel, key flows, success metrics
+- `06-product-pricing.md` — Pricing model, plans, packaging
+- `07-policies-legal.md` — Terms, refund policy, content moderation
+- `08-functional-requirements.md` — Feature list with priorities
+- `09-data-model-apis.md` — High-level data model and API surface
+- `10-nfr-implementation.md` — Non-functional requirements (perf, security, scale)
+- `11-appendices.md` — Glossary, references, acknowledgements
+- `12-schema-erd.md` — Database schema diagram + table reference
+
+## Format
+
+Each PRD section follows the standard doc header:
+
+```html
+<!-- domain:PRODUCT | layer:spec | ssot:true | updated:YYYY-MM-DD -->
+```
+
+Followed by H1, then the four-line opening block (Purpose / Read when / Skip when / Read next).
+
+## Authoring Rules
+
+- Each section is the SSOT for its topic. Other docs link here, not the other way around.
+- When implementation deviates from PRD, update PRD first, then code.
+- Open product questions go in `../_meta/questions.md`, not inline.
+- Decisions with long-term impact go in `../architecture/adr/`, not in PRD.

templates/_base/scaffold/docs/prd/01-snapshot-vision.md

@@ -0,0 +1,56 @@
+<!-- domain:PRODUCT | layer:spec | ssot:true | updated:{{DATE}} | module:docs -->
+# 01 — Snapshot & Vision
+
+> P: Elevator pitch + 3-year vision for {{PROJECT_NAME}}. Authoritative one-paragraph product summary.
+> R: Onboarding, stakeholder briefing, or any task that needs the product framing in one read.
+> S: Already aligned on vision; jump to the relevant section under `00-index.md`.
+> N: [02-goals-kpis.md](./02-goals-kpis.md), [03-users-jobs.md](./03-users-jobs.md)
+
+> Nav: [PRD Index](./00-index.md)
+
+## Elevator Pitch
+
+<!--
+Replace this block with one paragraph (≤120 words):
+
+  - WHO is the user
+  - WHAT problem the product solves
+  - HOW it solves it (the differentiator, in one phrase)
+  - WHY it wins now (timing / structural advantage)
+-->
+
+_TODO: write the elevator pitch._
+
+## 3-Year Vision
+
+<!--
+Replace this block with 3 short bullets (≤25 words each):
+
+  - Year 1 outcome (must-ship to be a product at all)
+  - Year 2 outcome (positions the product in market)
+  - Year 3 outcome (defensible moat / category position)
+
+Avoid feature lists. Outcomes only.
+-->
+
+- _TODO: Year 1 outcome._
+- _TODO: Year 2 outcome._
+- _TODO: Year 3 outcome._
+
+## Non-Goals
+
+<!--
+Three to five things this product will NOT do. Saying "no" loudly here
+prevents scope creep down the line.
+-->
+
+- _TODO: explicit non-goal #1._
+- _TODO: explicit non-goal #2._
+- _TODO: explicit non-goal #3._
+
+## Authoring Notes
+
+- Update `updated:` in the header whenever you change vision or non-goals.
+- When the elevator pitch changes, follow the cascade: re-check `02-goals-kpis.md`, `03-users-jobs.md`, `08-functional-requirements.md`.
+- Long open questions go to `../_meta/questions.md`, not inline.
+- Decisions with long-term impact go to `../architecture/adr/`, not here.