@aperant/framework 0.6.2

package/docs/design-taste.md

@@ -0,0 +1,187 @@
+# Design Taste (C26)
+
+Aperant's default `apt:design` output used to look like generic-SaaS-Tailwind
+— rounded-gray cards, soft shadows, a blue primary button. Every competitor
+ships the same baseline, so UI generated by Aperant looked identical to UI
+generated by anything else.
+
+The **design-taste standard** fixes this. A project declares an aesthetic
+direction in `.aperant/design/taste.yaml` (palette, type, motion, density,
+anti-patterns). `apt:design` reads it on every run and injects it as a
+TASTE_BLOCK into its prompts so generated screens reflect *project identity*
+instead of template aesthetics.
+
+This is a v1 scope: markdown + YAML authoring, no runtime CSS consumer. The
+runtime tokens consumer is [C27](./spec-gaps.md#c27) and lands later.
+
+## Overview
+
+| Concept         | Where it lives                                            |
+|-----------------|-----------------------------------------------------------|
+| Active taste    | `.aperant/design/taste.yaml` (project-local, opt-in)      |
+| Reference library | `packages/framework/templates/design-taste/*.yaml`      |
+| Consumer skill  | `packages/framework/skills/apt-design/SKILL.md`           |
+| Picker skill    | `packages/framework/skills/apt-setup/SKILL.md` (Batch 3b-design) |
+
+No schema validator is shipped in v1 — agents consume the file best-effort
+and unknown fields are ignored. Extend freely.
+
+## Schema Reference
+
+```yaml
+# Required canonical fields — keep all six so downstream consumers always
+# have a floor.
+direction: brutalist | editorial | enterprise-clean | playful | <custom string>
+
+palette:
+  bg:       "#RRGGBB"   # page background
+  fg:       "#RRGGBB"   # primary text / ink
+  muted:    "#RRGGBB"   # metadata, captions, secondary labels
+  accent:   "#RRGGBB"   # primary interactive affordance (links, primary btns)
+  border:   "#RRGGBB"   # hairline dividers, outlines
+  surface:  "#RRGGBB"   # cards, table headers, subtle groupings
+  # Optional: accent2, accent3, success, warning, danger, mono
+
+type:
+  display: ["Font A", "Font B", "fallback"]   # headings / display faces
+  body:    ["Font A", "fallback"]              # long-form body copy
+  # Optional:
+  # ui:      ["Font A", ...]                   # labels / UI chrome if different from body
+  # mono:    ["Font A", ...]
+  # scale:   tight | compact | cozy | loose    # leading + body size vocab
+  # weights: [400, 500, 600, 700]
+  # measure: 68ch                              # max line length
+  # letter_spacing_headings: -0.02em
+
+motion:
+  speed: instant | fast | medium | slow        # 0-80 | 120-180 | 220-320 | 320-480 ms
+  ease:  "cubic-bezier(...)" | "linear"
+  hover: none | subtle | underline | lift | <custom verb>
+  # Optional: enter, exit — named motion vocabulary for enter/exit transitions
+
+density: compact | cozy | roomy                # default density for product surfaces
+
+anti_patterns:
+  - "Free-form strings listing things the direction explicitly rejects"
+  - "Use anti_patterns to capture 'this is what generic SaaS would do, don't do that'"
+```
+
+## Reference Directions
+
+### Brutalist
+
+Raw, utilitarian, unafraid of ugly. Dense information, loud contrast, square
+corners, monospace display. Think Craigslist, early Basecamp, Are.na.
+
+**Pick this when:** the product is a tool and should feel like one. Dense
+data surfaces, power-user flows, intentional refusal of marketing polish.
+
+**Signature moves:** 2px solid borders, no shadows, invert-on-hover,
+`density: compact`, motion snaps instantly.
+
+### Editorial
+
+Magazine-like, reading-first, generous rhythm. Serif body type, warm paper
+neutrals, slow confident motion. Think The New Yorker app, Stripe Press,
+long-form documentation readers.
+
+**Pick this when:** content is the product. Newsletters, research tools,
+docs sites, knowledge-base UX. Users come to read.
+
+**Signature moves:** 68ch max measure, serif body, `density: roomy`,
+cubic-bezier ease over 320–480ms, links reveal underline on hover.
+
+### Enterprise-Clean
+
+Trustworthy, quiet, dense-when-it-counts. Cool neutral base, single blue
+accent, disciplined spacing. Think Stripe Dashboard, Linear enterprise mode,
+Vercel.
+
+**Pick this when:** B2B admin, billing consoles, compliance tools — any
+surface where "looks professional" is a ship criterion. Not the same as
+generic SaaS; this direction commits to IBM-adjacent discipline rather than
+defaulting to rounded-gray cards.
+
+**Signature moves:** single sans across the UI, 14px body for data density,
+subtle 4% hover tint (no scale), motion under 200ms.
+
+### Playful
+
+Saturated, bouncy, high-personality. Cream base, multi-color accent system,
+rounded geometry, spring motion. Think Duolingo, Arc Browser, Figma
+marketing.
+
+**Pick this when:** consumer or creative tools, onboarding-heavy apps,
+anywhere delight matters more than density.
+
+**Signature moves:** 12–16px corner radii, spring easing with overshoot,
+display-face headings, `density: cozy` with roomy heroes.
+
+## Consumption by apt:design
+
+`apt:design` does the following on every run:
+
+1. Reads `.aperant/design/taste.yaml` during its Load Context step.
+2. If present, renders a `TASTE_BLOCK` markdown snippet and prepends it to
+   Stage 1 wireframe output and the `## Handoff` section of the final
+   `design.md`.
+3. Wireframing chooses density, corner radius, spacing, and motion vocab
+   consistent with the direction, and rejects any component matching an
+   entry in `anti_patterns`.
+4. If the file is absent, the skill emits a fallback note telling the user
+   to run `/apt:setup` or copy a template manually, and proceeds with
+   generic-SaaS-Tailwind conventions.
+
+The planner (`apt:plan`) reads the handoff TASTE_BLOCK alongside the screen
+inventory, so subtasks written later reference the declared aesthetic.
+
+## Picking a taste
+
+Two paths:
+
+**Via `/apt:setup`:**
+
+Run `/apt:setup`, pick "Pipeline" (or "Everything" for a fresh run), and
+answer the "Design Taste" question. The skill copies the chosen template to
+`.aperant/design/taste.yaml` and prompts for overwrite confirmation if one
+already exists.
+
+**By hand:**
+
+```bash
+mkdir -p .aperant/design
+cp packages/framework/templates/design-taste/editorial.yaml .aperant/design/taste.yaml
+```
+
+Then edit `.aperant/design/taste.yaml` to taste. Fonts, palette, motion
+vocabulary, and anti-patterns are all free-form — the file is a prompt for
+the design skill, not a strict schema.
+
+## FAQ
+
+**Do I have to commit `.aperant/design/taste.yaml`?**
+Up to you. Solo projects can leave it gitignored. Team projects usually
+commit it so every collaborator's `apt:design` output matches.
+
+**Can I write a custom direction?**
+Yes. `direction` accepts any string. Copy the closest starter and edit.
+Downstream consumers only rely on the six canonical fields.
+
+**How does this relate to C27?**
+C27 generates runtime CSS tokens (custom properties, Tailwind theme entries)
+from this same file, so the UI your executor writes *actually renders* in
+the declared palette/type/motion. C26 is the authoring surface; C27 is the
+compile target. They ship in that order.
+
+**What if the project already has a brand / design system?**
+Two options: (a) encode it into `.aperant/design/taste.yaml` by hand (the
+schema is expressive enough for most), or (b) wait for C27, which includes
+`apt:scan --design` — a brownfield scan that synthesizes tokens from
+existing component code.
+
+## Related
+
+- [spec-gaps.md §C26](../../../docs/frameworks/spec-gaps.md#c26) — origin gap
+- [spec-gaps.md §C27](../../../docs/frameworks/spec-gaps.md#c27) — runtime consumer (follow-up)
+- `packages/framework/templates/design-taste/README.md` — schema + starter library
+- `packages/framework/skills/apt-design/SKILL.md` — consumer skill

package/docs/design-tokens.md

@@ -0,0 +1,147 @@
+# Design tokens (C27)
+
+**Status:** v1 shipped.
+
+`apt-tools design-scan` is the design-system sibling to `/apt:scan`. It walks UI source files and extracts a plain-JSON inventory of **colors**, **spacing**, **typography**, **radii**, and **shadows** currently in use. The output feeds `/apt:design`, which injects it into the Stage 1 wireframe so new screens match the existing aesthetic rather than defaulting to generic Tailwind.
+
+Brownfield projects almost always have a design system embedded in their component code but no documentation. This command is the docs — generated on demand, zero-dep, regex-only, fast.
+
+## CLI
+
+```bash
+apt-tools design-scan <project-dir> [--out <path>] [--root <subdir>]
+```
+
+| Flag       | Default                                        | Purpose                                                             |
+|------------|------------------------------------------------|---------------------------------------------------------------------|
+| `--out`    | `<project-dir>/.aperant/design/tokens.json`    | Override the output location (used by tests + one-off scans)        |
+| `--root`   | the project root                               | Limit the walker to a subdirectory (e.g. `--root packages/ui/src`)  |
+
+All output is JSON. On success:
+
+```json
+{
+  "status": "ok",
+  "command": "design-scan",
+  "written": "<absolute path to tokens.json>",
+  "summary": {
+    "files_scanned": 317,
+    "files_skipped": 0,
+    "colors": { "hex": 214, "rgb": 52, "hsl": 0, "tailwind": 161, "css_vars": 27 },
+    "spacing": { "raw": 94, "tailwind_scale": 35 },
+    "typography": { "font_families": 2, "font_sizes_raw": 26, "tailwind_sizes": 7, "line_heights": 0 },
+    "radii": { "raw": 4, "tailwind": 8 },
+    "shadows": { "raw": 11, "tailwind": 6 }
+  }
+}
+```
+
+## Output file shape
+
+`.aperant/design/tokens.json` conforms to `DesignTokensSchema` (see `src/cli/design/schema.mjs`). Every slice is a plain object of sorted, deduped string arrays.
+
+```jsonc
+{
+  "version": 1,
+  "generated_at": "2026-04-15T12:34:56.000Z",
+  "project_root": "/abs/path/to/project",
+  "scan": { "files_scanned": 317, "files_skipped": 0 },
+  "colors": {
+    "hex": ["#0f172a", "#a1b2c3"],
+    "rgb": ["rgb( 255, 255, 255 )"],
+    "hsl": ["hsl(200deg 50% 40%)"],
+    "tailwind": ["blue-500", "slate-900"],
+    "css_vars": ["--color-primary"]
+  },
+  "spacing": {
+    "raw": ["1rem", "16px"],
+    "tailwind_scale": ["0", "1", "2", "4", "8"]
+  },
+  "typography": {
+    "font_families": ["Inter", "JetBrains Mono"],
+    "font_sizes_raw": ["14px"],
+    "tailwind_sizes": ["sm", "base", "lg"],
+    "line_heights": ["1.5"]
+  },
+  "radii": {
+    "raw": ["4px"],
+    "tailwind": ["sm", "md", "lg", "full"]
+  },
+  "shadows": {
+    "raw": ["0 1px 2px rgba(0,0,0,0.1)"],
+    "tailwind": ["sm", "default", "lg"]
+  }
+}
+```
+
+## Extraction rules
+
+Scanning is regex-only (no AST / CSS parser). The matchers live in `src/cli/design/extract.mjs` and are individually exported so unit tests can assert against each.
+
+### Colors
+- **Hex:** `#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`, lowercased, deduped.
+- **Functional:** `rgb()` / `rgba()` / `hsl()` / `hsla()` — whole expression captured; internal whitespace collapsed to single spaces.
+- **Tailwind palette:** `(bg|text|border|ring|from|to|via|fill|stroke|outline|divide|placeholder|caret|accent|decoration)-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-(50|100|200|300|400|500|600|700|800|900|950)`, plus neutral aliases `white | black | transparent | current | inherit`. Utility prefix is stripped so `bg-slate-900` and `text-slate-900` both record as `slate-900`.
+- **CSS custom properties:** `--color-*` names only (values are not captured — the color extractors above already find them).
+
+### Spacing
+- **Raw:** integer or decimal literal + `px` / `rem` / `em`, bounded at 4 digits and with an identifier-boundary check so `foo16px` doesn't match.
+- **Tailwind scale:** `(p|m|gap|space|inset|top|right|bottom|left|w|h|min-w|max-w|min-h|max-h)[xytrbl]?-(0|0.5|1|1.5|…|px|auto)`. The prefix must be preceded by a class-context boundary (whitespace, quote, backtick, `{`, `(`, `[`, or start of text) and the numeric value rejects leading zeros on multi-digit integers — without these rules, identifier-embedded tokens like `wt-001` or `pr-001` in fixture data match `w-001` / `p-001` and pollute the scale. `full` / `screen` sentinels are dropped.
+
+### Typography
+- **font-family:** declaration value split on commas; each part trimmed and unquoted.
+- **font-size:** declaration value captured verbatim.
+- **Tailwind sizes:** `text-(xs|sm|base|lg|xl|2xl|…|9xl)` — sorted by scale order. `text-red-500` and `text-left` are excluded by the enum.
+- **line-height:** declaration value captured verbatim.
+
+### Radii
+- **border-radius:** declaration value captured verbatim.
+- **Tailwind:** `rounded(-t|-r|-b|-l|-tl|-tr|-bl|-br)?(-size)?` where `size ∈ {sm, md, lg, xl, 2xl, 3xl, full, none}`. A bare `rounded` is recorded as `default`.
+
+### Shadows
+- **box-shadow:** declaration value captured verbatim.
+- **Tailwind:** `shadow(-(sm|md|lg|xl|2xl|inner|none))?`. Color utilities like `shadow-slate-500` are not recognized as size tokens — the bare `shadow` fragment is recorded as `default` instead, keeping the shadow bucket palette-free.
+
+## Scanned paths
+
+**Extensions:** `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.html`, `.vue`, `.svelte`, `.mdx`, plus `tailwind.config.{js,ts,mjs,cjs}` by filename.
+
+**Excluded directories:** `node_modules`, `dist`, `build`, `.next`, `out`, `.aperant`, `.git`, `coverage`, `.turbo`, `.cache`, `.vercel`, and any other hidden `.foo` directory (except `.aperant` and `.git`, which are still excluded by name).
+
+**Caps:** 2000 files maximum; 256 KB per file. Over-size files are counted in `scan.files_skipped`.
+
+## Consumer: `/apt:design`
+
+When `.aperant/design/tokens.json` exists, `/apt:design` Step 1 reads it and builds a `{TOKENS_BLOCK}` summary that's injected into the Stage 1 wireframe:
+
+```markdown
+## Design Tokens (existing)
+- Colors: {N} hex values, {M} Tailwind palette tokens (e.g., slate-900, blue-500)
+  and {K} `--color-*` CSS vars. Examples: {first 3 hex}, {first 3 tailwind}.
+- Spacing scale (Tailwind): 0, 1, 2, 4, 6, 8, 12, 16
+- Typography: font families Inter, JetBrains Mono; Tailwind sizes xs, sm, base, lg
+- Radii (Tailwind): sm, md, lg, full
+- Shadows (Tailwind): sm, md, lg
+Source: .aperant/design/tokens.json — generated by `apt-tools design-scan`.
+```
+
+Stage 2's self-critique grows a matching "Aesthetic consistency" check: if the wireframe introduces colors / spacing / radii that aren't present in the token set, the critique flags it as a gap.
+
+## Relationship to `/apt:scan`
+
+`apt:scan` captures what the app **does** (features, wiring, components) under `.aperant/features/`. `design-scan` captures how the app **looks** (colors, spacing, typography, radii, shadows) under `.aperant/design/`. Same cadence — run both after `/apt:setup` on a brownfield project, and again after major UI changes. They are independent; neither one calls the other.
+
+## v1 limits
+
+- **Regex-only.** No AST parsing of TS/JSX, no CSS parser. Computed class names (`bg-${variant}-500`) are invisible to the scanner. For parity with the rest of apt-tools (zero deps) we chose text extraction over precision.
+- **No motion curves.** `transition-timing-function`, animation easings, and Tailwind's motion utilities are deferred to a follow-up milestone.
+- **No semantic deduplication.** `#fff`, `#ffffff`, and `rgb(255, 255, 255)` are treated as three separate tokens because normalization across formats would require a color parser.
+- **No dark/light pairing.** Semantic roles (`primary`, `background`, `foreground`) aren't inferred; the CSS var names are captured but not linked to their values.
+- **No theme expansion.** Tailwind config values beyond what the config file literally mentions are not enumerated — the scanner reads the file as plain text, not as a config module.
+
+## Follow-ups
+
+- **v2 motion-curve extractor** — capture `cubic-bezier()` + named easings.
+- **AST-aware pass** — optional `--ast` flag that uses TypeScript's compiler API to resolve computed class names (costlier, disabled by default).
+- **Color normalization** — dedup `#fff` ↔ `#ffffff` ↔ `rgb(255,255,255)` via a tiny parser.
+- **Planner + executor awareness** — teach `apt:plan` and `apt:execute` to read `tokens.json` and surface tokens in their context, not just `apt:design`.

package/docs/docs-coherence.md

@@ -0,0 +1,103 @@
+# Docs coherence
+
+## What this guarantees
+
+After `/apt:run` completes, the framework holds two invariants:
+
+1. **Internal state is coherent.** `implementation_plan.json`, `build-progress.json`, `.aperant/features/REGISTRY.md`, `.aperant/roadmap/**/milestones.json`, `.aperant/project_index.json`, and `.aperant/tasks/**` agree with each other. The `all-subtasks-complete` hard gate passes without force-bypass.
+2. **External prose drift is surfaced, not silently edited.** If the task's diff invalidates a claim in `CLAUDE.md` / `AGENTS.md` / a package `README.md` / anything under `docs/**`, the reviewer emits a `docs-drift` finding with file:line anchors. The user runs `/apt:docs` to resolve — the framework never auto-edits external prose.
+
+This document is the authoritative reference for how those guarantees are implemented.
+
+## Policy model
+
+`.aperant/config.json.docs_policy` is a flat map:
+
+```jsonc
+{
+  "docs_policy": {
+    "CLAUDE.md": "flag-drift",
+    "AGENTS.md": "flag-drift",
+    "packages/*/README.md": "flag-drift",
+    "docs/**": "flag-drift",
+    ".aperant/roadmap/**/milestones.json": "auto-update",
+    ".aperant/features/REGISTRY.md": "auto-update",
+    ".aperant/features/*.json": "auto-update",
+    ".aperant/project_index.json": "auto-update",
+    ".aperant/tasks/**": "auto-update"
+  }
+}
+```
+
+Values:
+
+| Kind | Behavior |
+|------|----------|
+| `auto-update` | Reviewer/executor patch the surface inline via the matching `apt-tools` subcommand. Safe for files the framework already owns. |
+| `flag-drift` | Reviewer emits a finding. Never auto-edited. Default for external prose. |
+| `skip` | Audit ignores the surface entirely. |
+
+Missing `docs_policy` → defaults from [`packages/framework/templates/docs-policy-defaults.json`](../templates/docs-policy-defaults.json) apply (drift-prevention test in [`packages/framework/src/__tests__/docs-audit-policy.test.ts`](../src/__tests__/docs-audit-policy.test.ts) keeps JSON + constant in lock-step).
+
+## Matching rules
+
+`matchSurfaceToPolicy(path, policy)` ([source](../src/cli/docs-audit/policy.mjs)):
+
+1. Literal-path match beats any glob (`CLAUDE.md` > `**`).
+2. Among globs, the longer pattern wins (`docs/readme/**` > `docs/**`).
+3. `**` is less specific than `*` — double-star penalty in the scoring function.
+4. Unmatched paths return `null` (no default coercion).
+
+Ties are broken by definition order (`Map` iteration).
+
+## The CLI verbs
+
+| Verb | Purpose | Called from |
+|------|---------|-------------|
+| `apt-tools task complete-subtask` | Atomic plan ↔ build-progress sync | `/apt:execute` §3e |
+| `apt-tools features-audit [--apply-stubs]` | Features-registry audit | `/apt:execute` post-step (with `--apply-stubs`); `/apt:review` Pass 6 (report-only) |
+| `apt-tools docs-audit` | Docs-coherence audit (external + internal) | `/apt:review` Pass 6 |
+| `apt-tools roadmap rollup` | Recompute a single milestone's rollup status | Manual + lifecycle auto-call |
+
+All verbs emit structured JSON. Every audit is idempotent; re-running on a clean tree returns `{status: "ok", findings: []}` with exit 0 — safe for CI and pre-commit.
+
+## How the planner enforces this
+
+`packages/framework/prompts/planner.md` §3.9 "Docs-Impact Enumeration" is a mandatory pre-finalize step. For every planned diff file, the planner:
+
+1. Loads the policy (config override or defaults).
+2. Resolves the policy for each touched surface.
+3. Emits a paired `doc-*` subtask for each `flag-drift` or `auto-update` surface.
+
+The rule is deliberately permissive — a no-op doc subtask costs nothing; a missed drift costs a review-time finding.
+
+Committable `.aperant/` state (roadmap, context notes, decisions, features, project.json) is separately enforced by the artifact-lifecycle contract — see [`artifact-lifecycle.md`](artifact-lifecycle.md). The planner doesn't need to plan doc subtasks for those files; the per-subtask drift check in `/apt:execute` §3e-drift + the `/apt:ship` §0.5 pre-PR audit catch any uncommitted drift automatically.
+
+## How the reviewer enforces this
+
+`packages/framework/skills/apt-review/SKILL.md` Pass 6 "Docs-Coherence Audit" runs after the existing 5 passes. It invokes `apt-tools docs-audit` and `apt-tools features-audit` against the task's diff, buckets by policy:
+
+- `auto-update` findings → applied inline via the fix loop (iterations 1-2).
+- `flag-drift` findings → written to `review_findings.md` with shape `{category: 'docs-drift', severity: 'warning', file, line, stale_claim, evidence_from_diff, suggested_rewrite?, policy: 'flag-drift'}`.
+
+Iterations 3-4 are verification-only; they never auto-edit external prose regardless of iteration.
+
+## Adding a new policy surface
+
+1. Add an entry to `DEFAULT_DOCS_POLICY` in [`packages/framework/src/cli/docs-audit/policy.mjs`](../src/cli/docs-audit/policy.mjs).
+2. Mirror the entry in [`packages/framework/templates/docs-policy-defaults.json`](../templates/docs-policy-defaults.json) (drift test enforces byte-equality).
+3. Extend [`packages/framework/skills/apt-setup/SKILL.md`](../skills/apt-setup/SKILL.md) Batch 7 so users can toggle the surface at setup time.
+4. Ensure the Batch 7 structure test in [`packages/framework/src/__tests__/apt-setup-batch7-structure.test.ts`](../src/__tests__/apt-setup-batch7-structure.test.ts) still passes (it asserts every default surface is mentioned in the skill prose).
+
+## Non-goals
+
+- Auto-editing external prose. Even on `auto-update`, the policy only lets internal-state files patch. External surfaces (CLAUDE.md etc.) ship with `flag-drift`; the audit never applies rewrites to them.
+- `/apt:docs` replacement. `/apt:docs` remains the user-invoked path to RESOLVE drift. Pass 6 only DETECTS.
+- Benchmark integration. Follow-up milestone `C23-DOCS` tracks wiring docs-coherence assertions into the scenario benchmark.
+
+## Cross-references
+
+- [apt-planner agent def §3.9](../agents/apt-planner.md)
+- [apt-review SKILL Pass 6](../skills/apt-review/SKILL.md)
+- [apt-execute SKILL §3e / §3e-features](../skills/apt-execute/SKILL.md)
+- [apt-setup Batch 7](../skills/apt-setup/SKILL.md)

package/docs/intents.md

@@ -0,0 +1,119 @@
+# Intent taxonomy
+
+The Aperant Framework classifies every skill under one **intent**. Intents
+let the host LLM reason about *what kind of work* a skill does without
+reading the full SKILL.md body — they're the semantic axis the router
+envelope is built around.
+
+The set has two tiers:
+
+1. A **closed core enum** that every shipping Aperant skill must draw
+   from (keeps LLM classification precision high).
+2. An **`x-*` prefix** for vertical-specific custom intents that haven't
+   graduated yet (unblocks marketing, sales, ML, gamedev, compliance,
+   and any other domain the framework grows into without polluting the
+   core).
+
+Both tiers are enforced by `SkillFrontmatterSchema`
+(`src/cli/skill-author/contract.mjs`) and cross-checked at install time
+by `apt-tools check`.
+
+## Core enum (closed set)
+
+| Intent | One-line meaning | Shipping example |
+|---|---|---|
+| `implement` | Build or change code to ship a feature/fix | `apt:plan`, `apt:execute`, `apt:run`, `apt:quick` |
+| `capture` | Preserve state — notes, pause/resume artifacts, docs | `apt:pause`, `apt:resume`, `apt:docs` |
+| `discuss` | Facilitate conversation before committing | `apt:discuss`, `apt:roundtable` |
+| `investigate` | Read-only exploration of code or state | `apt:scan`, `apt:stress-test` |
+| `design` | Produce design artifacts (wireframes, mockups, tokens) | `apt:design`, `apt:mockup` |
+| `ship` | Finalize + verify + deliver a change | `apt:verify`, `apt:review`, `apt:pr-review`, `apt:ship`, `apt:verify-proof` |
+| `configure` | Author or tune framework/project settings | `apt:setup`, `apt:author-skill`, `apt:terminal`, `apt:update`, `apt:roadmap` |
+| `debug` | Investigation-first diagnosis without a known cause | `apt:debug` |
+
+These values are the exact strings expected in a skill's `intent` field.
+They're exported as the `CORE_INTENTS` frozen array from
+`src/cli/skill-author/contract.mjs`.
+
+**Core intents change only via the promotion path below.** Adding a
+skill that doesn't fit any core intent? Use the `x-*` prefix; promote
+once it has company.
+
+## Custom `x-*` intents
+
+For use cases the core enum doesn't cover:
+
+```yaml
+intent: x-marketing-draft
+```
+
+The `x-*` prefix signals to the LLM + to maintainers that this intent
+is vertical-specific and hasn't graduated yet. Schema enforcement
+(`CUSTOM_INTENT_REGEX = /^x-[a-z][a-z0-9-]*$/`) keeps the namespace
+clean — uppercase, underscores, and bare-prefix `x-` are rejected.
+
+### Promotion path
+
+A custom `x-*` intent may be promoted to the core enum when it meets
+all three criteria:
+
+1. **≥3 shipping skills use the intent.** Proven demand, not speculative.
+2. **The proposer files a single PR** editing the `CORE_INTENTS` array
+   in `src/cli/skill-author/contract.mjs` + updating the table in this
+   file + adding a changelog line. No infrastructure changes are
+   required — the schema already accepts either shape.
+3. **A framework minor bump accompanies the promotion** (intents are
+   visible in the router envelope; adding to the core is a public
+   surface change).
+
+Demoting an intent — removing a value from `CORE_INTENTS` — is a
+**breaking change** (MAJOR bump), because existing SKILL.md files that
+declare the demoted value start failing schema validation. Think hard
+before promoting: the bar is "this vertical is here to stay."
+
+### Registered `x-*` intents
+
+The following `x-*` intents are currently in use in shipping framework skills.
+Update this table when adding a new `x-*` intent.
+
+| Intent | Skill(s) | Introduced | Description |
+|---|---|---|---|
+| `x-personas` | `apt:personas` | 0.3.x (C48) | Discover and persist product personas grounded in code signal + PROJECT.md |
+| `x-document` | `apt:create-docs` | 0.3.x (C49) | Generate persona-first product docs from the features registry + personas roster |
+
+### Keeping drift in check
+
+Today `apt-tools check` validates intents by schema shape. A future
+`apt-tools audit intents` command will list every `x-*` intent in use
+across the installed framework tree, with counts, so maintainers can
+see promotion candidates without digging. Until that lands, the
+maintainer responsibility documented here is the governance.
+
+## Host-detection maintenance
+
+`detectHost()` (in `src/cli/host/detect.mjs`) recognizes all 14
+installed runtimes via their published env vars. Some of those env
+vars are best-effort — see the TODO comments beside each branch for
+the CLI's docs URL and the maintenance cadence.
+
+**Cadence: every quarter.** At the start of each quarter (Jan, Apr,
+Jul, Oct) re-verify every runtime's documented env vars against its
+current CLI docs; file a framework-scope task if a CLI rotated its
+env-var surface. The next checkpoint after 0.3.0 ships is Q3-2026
+(July 2026).
+
+Each runtime's detection lives in exactly one `else if` branch in
+`detect.mjs`. The structural test
+`src/__tests__/host-detect-all-runtimes.test.ts` pins the
+env-var → CLI mapping with one positive case per runtime — when a CLI
+rotates its vars, that test fails first and provides the upgrade
+signal.
+
+## See also
+
+- [`CHANGELOG.md`](../CHANGELOG.md) — 0.3.0 envelope break + full
+  list of removed / added fields.
+- [`VERSIONING.md`](../VERSIONING.md) — semver tiers + pre-1.0
+  stability policy.
+- [`schemas/skill-frontmatter.json`](../schemas/skill-frontmatter.json)
+  — the ship-ready contract third-party tooling links against.