@aperant/framework 0.6.2 → 0.6.4

package/docs/design-taste.md

@@ -1,187 +0,0 @@
-# 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

@@ -1,147 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# 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

@@ -1,119 +0,0 @@
-# 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.