docs-ai — Curated Product and Design Records #

This directory is Prowl's curated, durable record of how the onevcat fork evolved. Each numbered folder documents a substantial feature or a non-trivial, decision-shaping fix: the plan that preceded the work and the resulting implementation. It exists so that humans and agents can answer "why is it built this way?" without archaeology through git history.

It is not a working-note archive. Reviews, audits, routine investigations, status reports, test runs, and small/docs-only changes stay in their normal task or Git context unless onevcat explicitly asks for a docs-ai/ record.

Structure #

docs-ai/NNN-<slug>/
  000-plan.md      # plan before implementation (RFC-like)
  001-action.md    # what was actually done, verified against the code
  002-<topic>.md   # amendments: follow-up waves, corrections, or one record per slice of a multi-PR entry (indexed in 000-plan.md)
  <living>.md      # non-numbered = living doc (runbook/ledger/reference), updated in place

Rules for writing new entries live in the write-ai-doc skill (.claude/skills/write-ai-doc/SKILL.md). In short: select only qualifying product work, then plan first, act second, amend in place for in-frame follow-ups, and open a new numbered entry for large pivots. An entry delivered across several PRs records each slice as an amendment (002+, shipped with its PR) and writes 001-action.md once, when the last slice lands, summarizing them. Numbered files are immutable history; non-numbered files are living documents.

Entries 001–045 were backfilled on 2026-07-12 from PRs, commits, and the former doc-onevcat/ directory, which was dissolved into this one (historical plans were absorbed into the entries; operational docs became living files — see the index below; originals remain in git history). Backfilled plans are retrospective reconstructions; each is marked as such.

Living documents hosted here:

• 001-fork-bootstrap-and-release-pipeline/release-runbook.md — fork sync & release runbook
• 007-ghostty-embedding-integration/ghostty-fork-sync.md — Ghostty fork/submodule upgrade runbook
• 012-keybinding-system/architecture.md — keybinding system reference
• 013-prowl-cli/contracts/ — normative CLI contracts
• 017-upstream-sync-process/upstream-ledger.md — upstream review ledger (baseline + decisions)
• 020-observability/runbook.md — observability/diagnostics runbook
• 063-agent-workflows/dsl-spec.md — Agent Workflow DSL (prowl.workflow/v1) normative spec
• 063-agent-workflows/release-plan.md — release/order plan shared by 063 and 064
• 064-agent-completion-signals/research-agent-completion-signals.md — per-runtime completion-signal matrix
• 064-agent-completion-signals/agent-contracts-runbook.md — runtime contract inventory, low-cost model routes, implemented inventory/preflight and eight-runtime headless checks, plus remaining interactive acceptance
• 068 agent state providers — shared architecture and one living contract/plan per runtime
• 070-app-localization/glossary.md — Simplified Chinese glossary for the String Catalog

Some entries also host verbatim historical attachments migrated from doc-onevcat (e.g. 023-shelf-mode/jank-investigation.md, 017-.../batch-2026-07-06-post-v0.10.5.md, 045-.../research-cli-session-identity.md); they are frozen records, not living docs.

What is not here: reviews, audits, routine investigations, test reports, working notes, small polish PRs (git history covers them), and current user-facing behavior (docs/ is the agent-facing manual for that).

Index #