# Decisions

Architectural decision records (ADRs) for this project. Each ADR captures a single
decision: the context that forced it, what we chose, and what changed
afterwards. ADRs are append-only; if a decision is later reversed, a new ADR
supersedes the old one and the old one is left in place with a note.

These are written for future maintainers and contributors who need to know
_why_ the codebase looks the way it does. They are not user-facing — the
day-to-day docs live under [Core Reference](/core/project_architecture) and
[For AI Agents](/ai_agents/overview).

## Index

| ID                                                           | Title                                                                  | Status   | Shipped    |
| ------------------------------------------------------------ | ---------------------------------------------------------------------- | -------- | ---------- |
| [0001](/decisions/0001_capability_kernel_and_tool_prefix)    | Capability kernel and tool-name prefix model                           | Accepted | v3.0.0     |
| [0002](/decisions/0002_v3_scope_and_consolidation_deferrals) | v3.0.0 scope cuts and tool-consolidation deferrals                     | Accepted | v3.0.0     |
| [0003](/decisions/0003_p0_wait_for_design)                   | P0 — `wait_for` design                                                 | Accepted | v3.0.0     |
| [0004](/decisions/0004_p1_keyboard_dialog_navigate)          | P1 — keyboard, dialog, and navigate decisions                          | Accepted | v3.0.0     |
| [0005](/decisions/0005_p2_fill_form_hover_select_option)     | P2 — `fill_form`, `hover`, and the `select_option` drop                | Accepted | v3.0.0     |
| [0006](/decisions/0006_platform_view_capture_routing)        | Platform-view capture routing (`captureHints`, host upgrade, recovery) | Accepted | Unreleased |
| [0007](/decisions/0007_web_headful_tab_capture)              | Web tab capture (macOS SCK + CDP; SCK → CDP → flutter_layer)           | Accepted | Unreleased |
| [0008](/decisions/0008_web_agent_invoke_js_only)             | Web agent invoke — JS-only path                                          | Accepted | Unreleased |
| [0010](/decisions/0010-intentcall-extract)                   | intentcall Phase 7 — monorepo extract and publish                        | Accepted | Unreleased |
| [0011](/decisions/0011_dogfood_tracker_evidence_split)       | Dogfood tracker vs `.showcase` runtime artifacts                         | Accepted | Unreleased |
| [0012](/decisions/0012_fmtk_cli_alias_and_harness_boundary)  | `fmtk` CLI alias and harness boundary                                    | Accepted | Unreleased |

## Format

Each ADR has the same shape:

- **Status** — proposed, accepted, deprecated, or superseded by another ADR.
- **Context** — the problem and constraints at the time of the decision.
- **Decision** — what we did, in one or two paragraphs.
- **Consequences** — what changed, what's now hard or easy, what we paid.
- **Notes** — load-bearing details future readers will need (e.g.
  non-obvious post-implementation findings).

ADRs are short on purpose. The full deliberation lives in git history; the ADR
is the compressed answer.
