@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/references/pev-rationale.md

@@ -0,0 +1,137 @@
+---
+name: pev-rationale
+load-when: When you need the source citation + ecosystem-level rationale behind §Plan-Execute-Verify
+load-size-tokens: ~600
+required-for: [authoring §PEV revisions, defending the loop in a §Teach handoff, training a new skill on PEV]
+---
+
+# Plan-Execute-Verify — rationale + source citation
+
+The Plan-Execute-Verify (PEV) loop is the load-bearing closure on
+every senior-skill invocation in the AdiaUI skill ecosystem. This file
+captures the rationale + source citation so the skill is self-contained
+— consumer repos don't need to reach back to the substrate's
+`BORIS-feedback.md` or `VISION-extensibility.md` to understand why
+PEV is the discipline.
+
+## The principle
+
+> "Give Claude a way to verify its work. If Claude has that feedback
+> loop, it will 2-3x the quality."
+>
+> — Boris Cherny, Anthropic, 2026-05-22 (the most-cited Boris principle
+> in the AdiaUI senior-skill ecosystem)
+
+The principle is structural, not stylistic. A skill that *generates*
+without *verifying* is a skill that produces plausible-looking work
+products which may or may not be correct. Adding a verify step
+shifts the skill's output from "looks like X" to "behaves like X" —
+a strictly stronger guarantee, and one that the rest of the
+authoring discipline (PR review, ticket QA, FEEDBACK pipeline)
+relies on.
+
+## What the loop is
+
+**Plan** — name the verify-target up front. If you cannot name how
+you will know you succeeded, you do not have a plan, you have a vibe.
+The verify target must be **mechanically checkable** — a rendered
+DOM you can snapshot, a command exit-code you can assert, an audit
+output you can grep, an eval score you can compare against a floor.
+
+**Execute** — do the work. The middle is the part most people
+recognize as "the task."
+
+**Verify** — run the output against the real product or substrate.
+NOT against the skill's own self-checks. The skill might pass its
+internal P1–P5 binding-points and still produce wrong output.
+The verify step closes that gap.
+
+## What §SelfAudit checks vs what verify checks
+
+There are two distinct audit surfaces in the skill ecosystem, and
+they answer different questions:
+
+| Surface | What it checks | Where it lives |
+|---|---|---|
+| **§SelfAudit** (mechanical roster, `audit-kit-roster.mjs`) | Does the SKILL.md itself satisfy structural invariants? Are the H2 sections present? Is the cold-start band coherent? Is the §PEV binding in place (P1–P5)? | Substrate-level audit; runs in CI on the skill repo |
+| **Verify** (the loop closure for a task) | Did the OUTPUT this skill just produced actually behave as intended? Does the composed UI render? Did the eval pass the floor? Did the migration land cleanly in a consumer repo? | Per-task; runs against the artifact the skill produced |
+
+**Both are required.** §SelfAudit catches drift in the skill's own
+shape (sections missing, frontmatter wrong, citation broken). Verify
+catches drift in the work the skill produces (a generated UI that
+looks right but routes wrong; a migration sweep that landed but
+broke a downstream test).
+
+A skill that only does §SelfAudit is a skill that grades its own
+homework. A skill that only does verify is a skill with no
+structural integrity. Both gates fire on every invocation.
+
+## Why the loop is "load-bearing"
+
+The loop is load-bearing because:
+
+1. **It is the only thing that closes the gap between intent and outcome.**
+   Without verify, the agent's output is "I think I did the thing"
+   — a confidence claim from an LLM, not evidence.
+2. **It is what makes the skill trustable downstream.** A consumer
+   agent that invokes adia-ui-kit and gets back markup with no
+   verify result has no basis to ship that markup. A consumer agent
+   that gets back markup PLUS a "verified by rendering against the
+   playground" handle can ship with confidence.
+3. **It is the mechanism that converts "happy-path eval pass"
+   into actual user-facing quality.** Boris's 2-3x quality claim is
+   not about the agent being smarter — it is about the agent being
+   forced to check its own work against a real signal.
+
+## Concrete verify-targets per skill mode
+
+For adia-ui-kit specifically, the verify-target is mode-dependent:
+
+- **Modes 1–4 (composition)** — render the composed surface in a
+  real demo / playground / Playwright snapshot; compare against the
+  intent or the source mock.
+- **Mode 5 (recon / consultant)** — produce a diagnostic report
+  with verifiable findings (path + line + actual content quoted);
+  rerun the audit after any fix to confirm 0 findings.
+- **Mode 6 (feedback authoring)** — verify the ticket lands the
+  5-block structure + the omissions-defense scan completes with
+  no open accidents.
+- **Mode 14 (correction loop)** — verify the root cause is at the
+  correct layer (skill / codebase / substrate / spec); rerun the
+  failing case after the fix.
+
+The verify-target table in the cold-start band names these
+explicitly per mode.
+
+## Anti-patterns
+
+- **"Verify by self-checking the agent's own output"** — circular.
+  The agent is the writer; it cannot be the verifier of its own
+  pattern-matching.
+- **"Mechanical when available, manual when not"** — degraded
+  verify is not the same as verify. If the mechanical surface is
+  unavailable, name what's missing as a P1 finding and proceed
+  with the degraded surface only after explicit user acknowledgment.
+- **"Skip verify if the change is small"** — small changes have
+  small verify costs. Skipping verify is what produces the
+  silent-regression class that the FEEDBACK pipeline catches
+  hours/days later.
+
+## Source
+
+Boris's principle was articulated in his 2026-05-22 conversation
+about Claude's coding behavior. The principle is short ("give
+Claude a way to verify its work") but its structural implications
+are large (every skill ecosystem needs a verify step; every
+verify step needs a mechanically-checkable target). The AdiaUI
+senior-skill ecosystem encodes this as:
+
+- §PEV H2 in the cold-start band of every senior SKILL.md (P1)
+- A verify-target table naming the per-mode target (P2)
+- A §Teach cross-reference linking new knowledge back to PEV (P3)
+- PEV mentioned in the cold-start band (P4)
+- The skill.json description claiming a verify capability (P5)
+
+These 5 binding-points are mechanically checked by
+`scripts/skills/check-pev.mjs`. If they all pass, the skill is
+PEV-bound; if any fails, the skill cannot ship.

package/skills/adia-ui-kit/references/reasoning-gate.md

@@ -0,0 +1,146 @@
+---
+name: reasoning-gate
+load-when: Before any component output — the mandatory pre-generation reasoning gate. Covers the GenUI Plan template, the user-intent verification step, and the decomposition discipline
+load-size-tokens: ~1,900
+required-for:
+  - composition modes 1-4 cold-start
+  - any output the user has not pre-confirmed
+---
+
+# §0 — Reasoning Gate (mandatory before any component output)
+
+Based on `ref-gen-ui-systems` and the Generative UI Reasoning Ladder.
+
+### Why the gate exists
+
+LLMs naturally jump from "Build a CRM" to emitting `<card-ui>` or A2UI
+JSON. The result is visually plausible UI that is operationally wrong —
+missing task traces, unbound components, no decision support. The ladder
+forces the reasoning that produces correct UI.
+
+**A UI is a decision surface over a domain. Components and layouts are
+the output of correct reasoning — never the starting point.**
+
+> ⚠️ **And that reasoning includes a CATALOG SEARCH.** Once you've
+> derived "what component fits this decision rung?", your next step is
+> NOT to author a novel tag. Your next step is to **search
+> `packages/web-components/components/` + `packages/web-modules/`**
+> by keyword + intent, and confirm the catalog doesn't already cover
+> it. The 122 primitives + 5 module clusters absorb the vast majority
+> of real UI problems by design. See §1 (Catalog Lookup) for the
+> prior-art-first rule and search procedure. If the catalog truly
+> doesn't cover the case, file a FEEDBACK ticket (see §Team Tickets)
+> instead of inventing a one-off — substrate gaps are signal, and
+> v0.6.18's FB-10 (`text-ui` overlay attrs) is a real example of the
+> catalog catching up to natural consumer intent.
+
+### The 19-rung ladder (condensed)
+
+```
+0.  InputContext    — what's given; what's known, inferred, missing
+1.  Intent          — why the UI exists
+2.  Domain          — entities, relationships, metrics, rules, permissions
+3.  Role            — who uses it; uiDifferentiators per role
+4.  Task            — what users accomplish; requiredInformation per task
+5.  Decision        — what users determine; possibleActions per decision
+6.  Posture         — monitoring / acting / analyzing / configuring / creating / reviewing
+7.  IA              — areas derived from tasks (not entities)
+8.  AppShell        — shell pattern derived from posture
+9.  Navigation      — primary / secondary / contextual; role-scoped
+10. Surface         — page / panel / drawer / modal / popover / card / toast
+11. View            — route-level composition of sections
+12. Section         — semantic group; taskIds or decisionIds required
+13. Component       — justified by task + decision + binding
+14. DataBinding     — fieldMap, refreshPolicy, cachePolicy
+15. Interaction     — label, input, permission, result, optimisticUpdate, errorPath
+16. State           — local / server / derived / route / session / optimistic / permission
+17. Feedback        — loading + empty + error per data-driven component
+18. RenderPlan      — what to emit and in what format
+19. Validation      — does the output satisfy the intent?
+```
+
+### The Pre-Composition Rubric (5 gates)
+
+Before any HTML or A2UI JSON output, emit a `### GenUI Plan` block.
+
+**Carry-forward rule:** if the user's prompt already answers a field,
+carry it forward directly — do not re-interrogate. Only ask about fields
+that are genuinely missing. A prompt that says "Admin UI for Claims
+Management loading from /api/claims" has already answered `domain`,
+`tasks`, `bindings`, and `shell`. Only confirm missing pieces.
+
+#### GenUI Plan (emit format)
+
+```yaml
+intent:
+  user_goal: "[What is the user trying to accomplish?]"
+
+domain:
+  entities: "[Core nouns: Claim, Policy, Adjuster, Document…]"
+  metrics: "[Key numbers: open claims count, avg resolution time…]"
+
+tasks:
+  primary: "[Verbs: Review Claim, Assign Adjuster, Approve Payout…]"
+
+decisions:
+  key: "[What must the user determine? What action follows?]"
+
+bindings:
+  # Carry forward any endpoints the user provided.
+  # For each: endpoint, method (GET/POST/SSE), fieldMap stub.
+  # Example: GET /api/claims → table-ui.data via data-stream-src
+  sources: "[endpoint X → which component(s) consume it]"
+
+design_reference:
+  # If the user provided Figma boards, screenshots, or mockups:
+  # - Extract: layout intent, visual hierarchy, key component patterns
+  # - Map: design components → nearest AdiaUI primitives
+  # - Flag: anything the board shows that AdiaUI doesn't have
+  # DO NOT copy raw colors, spacing values, or font sizes from the board.
+  # Map them to the nearest --a-* token instead.
+  source: "[Figma link / screenshot / none]"
+  mapped_components: "[design component → AdiaUI equivalent]"
+  deviations: "[anything in the board AdiaUI can't express — flag for user]"
+
+structure:
+  posture: "[monitoring | acting | analyzing | configuring | creating | reviewing]"
+  shell: "[admin-shell | chat-shell | editor-shell | simple-shell | a2ui-root]"
+  views: "[list the views/routes this UI needs — e.g. claims list, claim detail]"
+```
+
+After emitting the plan, ask: *"Does this model look correct? May I
+proceed to generate the structure?"* — but omit questions about fields
+the user already answered.
+
+Only after confirmation (or in fully autonomous mode with pre-approval)
+proceed to §1 Catalog Lookup and §2 Composition.
+
+### Non-negotiable rules (from the ladder)
+
+- **Component justification:** every component must trace to `taskIds` or
+  `decisionIds`. A component with no task or decision trace must be removed.
+- **Decision actions:** every critical decision must have `possibleActions`.
+  A decision with no action is an observation, not a supported decision.
+- **Feedback completeness:** every data-driven component requires loading,
+  empty, and error states. Not optional.
+- **Role differentiation:** when multiple roles exist, each needs
+  `uiDifferentiators`. One interface for incompatible roles is an error.
+- **No unbound UI:** every data-driven component needs an explicit binding
+  (source, fieldMap, refreshPolicy). An unbound component is a mockup.
+
+### Anti-patterns (check before declaring done)
+
+| ID | Name | Symptom |
+|---|---|---|
+| AP-01 | Premature Rendering | Output starts with component vocabulary |
+| AP-02 | Generic Dashboard Syndrome | Metrics shown with no actions |
+| AP-03 | Component-First Thinking | Reasoning starts with component names |
+| AP-04 | Unbound UI | Components have no data source |
+| AP-05 | Actionless Interface | Operational surface with no actions |
+| AP-06 | Missing Feedback States | No loading, empty, or error states |
+| AP-07 | Role Collapse | One interface for incompatible roles |
+| AP-08 | Metric Without Decision | KPI card with empty decisionIds |
+| AP-09 | Surface Without Task | Surface with empty taskIds |
+| AP-10 | State Without Owner | State with no owner or reset condition |
+
+---

package/skills/adia-ui-kit/references/reasoning-methodologies.md

@@ -0,0 +1,112 @@
+---
+name: reasoning-methodologies
+load-when: When the user's request is ambiguous or novel — covers general-purpose reasoning priors (first-principles, root-cause, rate-limiting, decomposition over generation) that pre-empt jumping to skill-specific output
+load-size-tokens: ~1,300
+required-for:
+  - novel-task triage
+  - audit-mode root-cause analysis
+  - pre-output reasoning
+---
+
+# §ReasoningMethodologies — General-purpose priors that pre-empt skill content
+
+These are the reasoning postures every phase of this skill assumes you
+bring. They are not AdiaUI-specific — they are the priors that make this
+skill's phase map produce correct output. If you skip them, the skill
+phases produce locally-correct steps that compose into wrong outcomes.
+
+### 1. Decomposition over generation
+
+**If you can't explain the problem, you can't solve it.** Before writing
+a single component, name:
+
+- What this UI is *for* (the user task, not "a dashboard").
+- The first-principles decomposition (entities → tasks → decisions →
+  display + input affordances → component primitives).
+- Which decisions are *load-bearing* (changing them rewrites everything
+  below) vs *cosmetic* (changing them is a one-line override).
+
+Component selection is the **output** of decomposition, not the input.
+If the user says "build a table", the table is a hint about display
+shape, not a specification. Resolve the entity + the decisions it
+supports before reaching for `<table-ui>` — you may find `<feed-ui>` or
+`<kanban-ui>` was the right primitive.
+
+### 2. Root cause analysis before patching
+
+When a symptom appears (component renders wrong, state out of sync, CSS
+override doesn't take, ticket from a consumer), find the *root* before
+proposing a fix. The chain usually runs:
+
+```
+Symptom  →  Proximate cause  →  Mechanism  →  Root cause
+"button   "wrong --a-fg-     "token wrong  "consumer set
+ wrong     resolves"          for variant"  --a-fg in :root
+ color"                                      overriding the
+                                             variant scope"
+```
+
+The proximate cause justifies a workaround. The root cause justifies a
+substrate fix or a documented convention. **Skill-authoring should fix
+substrate or document discipline; never teach workarounds.**
+
+### 3. Rate-limiting factors
+
+For any system, name the *irreducible mechanic* that gates correctness
+or performance. Examples in this skill's domain:
+
+- The icon loader needs Phosphor installed *before* `static
+  requiredIcons` runs. Rate-limiter: install order.
+- `<table-ui>` paired with `<table-toolbar-ui>` works because the
+  toolbar dispatches scoped events. Rate-limiter: event scoping.
+- 9-package lockstep is enforced because internal `^MAJOR.MINOR.0` deps
+  lock to exact in npm pre-1.0. Rate-limiter: semver pre-1.0 semantics.
+
+Whenever a recipe in this skill exists, it exists because of a
+rate-limiting mechanic. Name the mechanic; *then* the recipe makes
+sense and can be adapted.
+
+### 4. First-principles audit before adopting a pattern
+
+When the repo already has a pattern (hand-rolled skeleton, custom
+shell, bespoke route mount), don't reflexively replace it with the
+substrate equivalent. Audit:
+
+- **Why does this pattern exist?** (predates substrate capability? a
+  deliberate carve-out? a workaround for a bug that's since shipped?)
+- **What does substrate now provide?** (loading prop? slot? token?
+  primitive?)
+- **What does replacement cost?** (1-line, 1-file, N-files, regression
+  surface, behavior delta.)
+- **What does keeping it cost?** (drift accumulates, future agents
+  cargo-cult the workaround, doc-currency suffers.)
+
+Adopt-or-keep is a *decision*, not a default. Document the decision in
+the diagnostic report — see §DiagnosticOutput.
+
+### 5. 5-way reachability check
+
+For any artifact (component, chunk, page, primitive, token) that is
+*supposed to be canonical*, verify it is reachable from at least these
+five surfaces — every miss is a class of bug:
+
+1. **Sitemap / index** — listed where consumers look.
+2. **Corpus / search index** — discoverable by name/keyword.
+3. **Harvester / generator output** — chunked or indexed by tooling.
+4. **Imports / module graph** — actually loaded by something.
+5. **Self-doc** — its own README/yaml/examples reference it.
+
+If a "canonical" artifact is reachable from <5, it isn't canonical;
+it's a draft, a dead branch, or a doc-currency miss. This is the gap
+class §Recon hunts for.
+
+### 6. Explain before you act
+
+Before any non-trivial change (substrate edit, migration sweep,
+diagnostic report), write the *why* in plain English. If you can't
+write the why in two sentences, you don't understand the change well
+enough to make it. The §0 GenUI Plan, the §Recon report, the
+§DiagnosticOutput, and every commit message in this repo follow this
+discipline.
+
+---

package/skills/adia-ui-kit/references/recon.md

@@ -0,0 +1,192 @@
+---
+name: recon
+load-when: Consultant-posture inventory — landing in a brownfield consumer repo and getting the 60-second read of what shipped, what state it's in, what gaps exist
+load-size-tokens: ~2,100
+required-for:
+  - mode 5 (consultant) first turn
+  - audit output authoring
+---
+
+# §Recon — 60-second inventory for a brownfield repo
+
+Run this **before** §Setup any time you land in a repo you didn't author.
+The goal is not to be exhaustive — it's to assemble enough context that
+your subsequent edits respect the repo's existing intent, conventions,
+and adoption state.
+
+### Why this exists
+
+Without recon, brownfield work produces three predictable failures:
+
+1. **Convention violation** — you write `[data-actions]` when the repo
+   has adopted `slot="action"`, or vice versa.
+2. **Substrate duplication** — you hand-roll a skeleton when the repo's
+   installed `@adia-ai/web-components` already ships `loading` on
+   `<stat-ui>` / `<table-ui>`.
+3. **ADR ignorance** — you propose a legacy shell shape that ADR-0024
+   retired, because the repo's own docs hint at it without flagging the
+   retirement.
+
+The §Recon checklist below catches all three classes in roughly 60
+seconds of disciplined inspection.
+
+### The Recon checklist (in order)
+
+Each step has an exact command and a one-line interpretation rule.
+
+**1 — Identify the repo's agent-entry file**
+
+```bash
+ls AGENTS.md CLAUDE.md .cursorrules 2>/dev/null
+```
+
+If present: **read it in full** before doing anything else. It usually
+contains hard rules, peer-agent baseline, and reading-order pointers.
+**If absent: this is itself a finding** — propose scaffolding from
+`assets/templates/` in §DiagnosticOutput.
+
+**2 — Identify the project tier**
+
+```bash
+ls package.json README.md .claude/docs/ specs/ .brain/ 2>/dev/null
+test -d apps && echo "monorepo-app-tier" || echo "single-package"
+test -d packages && echo "monorepo-substrate-tier" || true
+```
+
+Determine: substrate repo (publishes `@adia-ai/*`), consumer app (uses
+`@adia-ai/*`), or library (re-exports / wraps). Each implies different
+recon depth.
+
+**3 — Read the installed AdiaUI versions (and confirm declarations exist)**
+
+```bash
+# (a) What's declared in package.json?
+node -e "const p=require('./package.json'); const deps={...p.dependencies, ...p.devDependencies}; const adia=Object.entries(deps).filter(([k])=>k.startsWith('@adia-ai/')); console.log(JSON.stringify(Object.fromEntries(adia), null, 2))"
+
+# (b) What's installed in node_modules?
+ls node_modules/@adia-ai/ 2>/dev/null
+# For each: cat node_modules/@adia-ai/<pkg>/package.json | grep '"version"'
+
+# (c) CRITICAL CHECK — do imports exist for packages that aren't declared?
+# (This is the manifest-gap detection — see §GapDetection Gap class 0.)
+grep -rEn "from ['\"]@adia-ai/" --include='*.ts' --include='*.js' \
+  --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.svelte' \
+  src/ 2>/dev/null | head -10
+```
+
+Note the **3-tuple**: declared / installed / latest-published. Drift
+between any two is a gap class (see §GapDetection).
+
+**Halt-condition (Gap class 0):** if step (c) returns matches but step
+(a) returns `{}` empty, the manifest is gapped — source imports
+`@adia-ai/*` but `package.json` declares nothing. Vite will fail at
+`npm run dev` with "could not be resolved" / "Are they installed?" on
+the bare specifiers. **Do not compose any further UI** until the
+operator declares + installs the deps. See §GapDetection Gap class 0
+for the remediation shape. The 2026-05-23 `claims-ui-v9` incident is
+the canonical worked example: 5 imports against 0 declared deps,
+vite scanner halted dev-server boot.
+
+**4 — Read the canonical specs and ADRs**
+
+```bash
+ls .claude/docs/specs/ .claude/docs/ADRs/ .brain/adrs/ 2>/dev/null
+# Read the spec INDEX if present:
+test -f .claude/docs/specs/INDEX.md && head -80 .claude/docs/specs/INDEX.md
+# Scan ADR titles:
+for f in .brain/adrs/*.md .claude/docs/adrs/*.md; do head -3 "$f" 2>/dev/null; done
+```
+
+Specifically look for: which ADRs *exist*, which ones *describe
+retirement* of legacy shapes, which ones *introduce new canonical
+shapes*. Adoption state of each is a gap candidate.
+
+**5 — Read the most recent journal entry (if any)**
+
+```bash
+ls .claude/docs/journal/ .brain/journal/ 2>/dev/null
+find .claude/docs/journal/ -name '*.md' 2>/dev/null | sort | tail -3
+```
+
+The newest journal entry tells you what was last in flight, what was
+last shipped, and what hand-offs are open. If a peer agent is mid-arc,
+recon should pick up there.
+
+**6 — Inventory the actual UI surface**
+
+```bash
+# Find all admin/editor/chat shells in use:
+grep -rEn '<admin-shell|<editor-shell|<chat-shell|<chrome-shell' \
+  --include='*.html' --include='*.js' --include='*.jsx' \
+  --include='*.tsx' --include='*.vue' --include='*.svelte' .
+
+# Find raw <main> / <header> / <aside> patterns (likely legacy):
+grep -rEn '<main[ >]|<aside[ >]|<header[ >]' \
+  --include='*.html' . | head -20
+
+# Find hand-rolled skeletons (likely substrate-replaceable):
+grep -rEn 'skeleton|placeholder.*loading|class=".*loading"' \
+  --include='*.css' --include='*.html' . | head -20
+```
+
+These three grep families together map: **which shells exist**, **what
+hasn't been adopted yet**, **what has been hand-rolled**. Each finding
+is a candidate for §GapDetection.
+
+**7 — Check for hand-rolled primitives that substrate now provides**
+
+This is the highest-leverage finding class. Examples to look for:
+
+| Hand-rolled symptom (grep) | Substrate replacement (since) |
+|---|---|
+| `class=".*toast"` + custom CSS | `<feed-ui>` toast API (v0.6.11+) |
+| `class=".*skeleton"` + custom CSS | `loading` prop on `<stat-ui>` / `<table-ui>` (v0.6.18+) |
+| Custom `<div role="dialog">` | `<dialog-ui>` / `<drawer-ui>` |
+| Custom CSS / `@media` for breakpoints | `@bp` responsive attrs on `grid-ui` / `col-ui` / `row-ui` / `text-ui` / `block-ui` — `columns="2 4@md"`, `gap="2 4@md"`, `justify="start between@md"` |
+| Inline color hex / rgb | `--a-chrome-*` / `--a-data-*` semantic tokens |
+| Custom `<button class="primary">` | `<button-ui variant="primary">` |
+
+Each match here is a §GapDetection capability-drift finding. **Do not
+fix in recon** — note it for the report.
+
+**8 — Check doc currency**
+
+```bash
+# When was README / .claude/docs/ last touched?
+find README.md .claude/docs/ -name '*.md' -mtime -30 2>/dev/null | head -5
+# Are there obvious stale references? (versions, tags, retired shapes)
+grep -rEn 'v0\.[0-5]\.[0-9]+|@agent-ui-kit|AgentElement|--agent-' \
+  README.md .claude/docs/ 2>/dev/null | head -10
+```
+
+Stale doc references usually correlate with stale code. Note them.
+
+**9 — Run whatever verification gates exist**
+
+```bash
+# If the repo has its own gates, run them — they encode its conventions.
+test -f package.json && grep -E '"check:|"verify:|"smoke:|"lint:' package.json
+# Common shapes:
+npm run check 2>&1 | tail -20  # if check exists
+npm run lint 2>&1 | tail -5    # if lint exists
+```
+
+A failing gate is itself a finding. A *missing* gate (e.g. consumer has
+no `check:lockstep` equivalent) is also a finding.
+
+### Recon stop-conditions
+
+Stop the inventory when you can answer all of these:
+
+- What is this repo (tier, framework, rendering model)?
+- What AdiaUI versions does it consume (declared / installed / latest)?
+- Which ADRs has it adopted? Which has it not?
+- What shells / patterns are in use? What's hand-rolled?
+- Where is the doc currency (fresh, stale, missing)?
+- Are there peer agents mid-arc, or open hand-offs in the journal?
+
+Once you have answers to all six, proceed to §GapDetection. **Do not
+proceed to §Setup or §0 until the user has confirmed your
+§DiagnosticOutput** — otherwise you're authoring without context.
+
+---