@adia-ai/adia-ui-forge 0.1.3 → 0.8.0

package/skills/{adia-ui-release → adia-release}/scripts/insert-stub.mjs

@@ -11,7 +11,7 @@
 //     --previous-version 0.6.21 \
 //     --packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
 //
-// Phase 2 of the adia-ui-release skill. Replaces the inline stub-
+// Part of the adia-release skill. Replaces the inline stub-
 // insertion pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21
 // cycles.
 

package/skills/{adia-ui-release → adia-release}/scripts/package-paths.mjs

@@ -35,6 +35,12 @@ export function resolvePackageDir(repo, pkg) {
     const nested = path.join('a2ui', m[1]);
     if (fs.existsSync(path.join(repo, 'packages', nested))) return nested;
   }
+  // Plugins live under packages/plugins/<name> but carry the flat name form
+  // (adia-ui-forge) in the release tooling — same name-vs-path split as a2ui.
+  if (/^adia-ui-/.test(pkg)) {
+    const nested = path.join('plugins', pkg);
+    if (fs.existsSync(path.join(repo, 'packages', nested))) return nested;
+  }
   return pkg; // fall through with the original arg so the not-found error names what was asked for
 }
 

package/skills/{adia-ui-release → adia-release}/scripts/promote-unreleased.mjs

@@ -11,7 +11,7 @@
 //   node promote-unreleased.mjs --version 0.6.22 --date 2026-05-22 \
 //     --packages web-components,web-modules --dry
 //
-// Phase 2 of the adia-ui-release skill. Replaces the inline heading-swap
+// Part of the adia-release skill. Replaces the inline heading-swap
 // pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21 cycles.
 //
 // Exits:

package/skills/{adia-ui-release → adia-release}/scripts/release-pack.mjs

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 // release-pack.mjs — full-cycle orchestrator for an AdiaUI lockstep release.
 //
-// Chains the 6 Phase-1/2/3 CLI helpers (bump · promote-unreleased ·
-// insert-stub · tag-lockstep · dispatch-publish · make-ledger) plus the
-// non-helper steps (lockfile · pre-flight gates · git commit · F-N1 ·
-// push · GH releases · site deploy) into one walked sequence with 3
-// operator checkpoints (before tag, before push, before publish) per
-// SKILL.md §Posture.
+// Chains the 5 CLI helpers (bump · promote-unreleased · insert-stub ·
+// tag-lockstep · dispatch-publish) plus the non-helper steps (lockfile ·
+// pre-flight gates · git commit · F-N1 · push · GH releases · site
+// deploy) into one walked sequence with 3 operator checkpoints (before
+// tag, before push, before publish) per SKILL.md operator checkpoints.
 //
 // MODES:
 //   --mode cut          (Mode 1 — peer pre-staged [Unreleased] or pure stub)
@@ -33,8 +32,8 @@
 //   --skip-gates         : (DEBUG ONLY) skip pre-flight (don't ship anything!)
 //   --skip-site          : skip the EXE deploy step (rare; for offline cycles)
 //
-// PHASE 4 of the adia-ui-release skill. Mechanizes the 11-step cycle from
-// references/cycle-happy-path.md while preserving operator judgment at
+// Part of the adia-release skill. Mechanizes the cut procedure from
+// references/cut-procedure.md while preserving operator judgment at
 // the 3 mutating-checkpoint boundaries.
 
 import { execSync } from 'node:child_process';
@@ -274,7 +273,7 @@ function step7Fn1(args) {
 // THE BATCH-PUSH SKIP (bit the v0.7.14 cut): `git push origin <10 tags>` in one
 // invocation fires the push-on-tag `create` event ONCE for the whole ref-set,
 // and GitHub Actions routinely drops it — ZERO publish-on-tag workflows trigger.
-// (Memory: feedback_publish_workflow_batch_push; recovery-paths.md §Scenario 7.)
+// (recovery-paths.md §Scenario 7 — the batch-tag-push publish-skip.)
 // Pushing each per-package tag separately gives the per-package publish-<pkg>.yml
 // `on: push: tags:` trigger its own create event. The umbrella tag is pushed
 // last (it triggers nothing — convention only).
@@ -341,15 +340,9 @@ async function step10GhAndSite(args) {
   }
   sh('npm run build:site', args);
   sh(`rsync -az --delete dist/ ${args.host}:/srv/adia-ui/dist/`, args);
-  sh(`curl -s -o /dev/null -w "EXE gen-ui: HTTP %{http_code}\\n" https://${args.host}/site/gen-ui/`, args);
-}
-
-// ── Step 11 — Ledger ─────────────────────────────────────────────
-function step11Ledger(args) {
-  console.log('\n=== Step 11 — Audit-history ledger ===');
-  const cmd = `node ${SCRIPT_DIR}/make-ledger.mjs --version ${args.version} --date ${args.date} --summary "<TODO: paste from commit message>" --note "Shipped via release-pack.mjs mode=${args.mode}"`;
-  sh(cmd, args);
-  console.log('\n  Edit the generated ledger to fill in scope/verification details, then commit + push.');
+  // Verify a deployed CONTENT FILE, never an SPA route — the docs site
+  // returns HTTP 200 + a blank shell for ANY unmatched route (v0.7.4 trap).
+  sh(`curl -s -o /dev/null -w "EXE host.css: HTTP %{http_code}\\n" https://${args.host}/packages/web-components/styles/host.css`, args);
 }
 
 // ── Main ─────────────────────────────────────────────────────────
@@ -357,7 +350,7 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   // Fail-fast guard: refuse to git/npm/gh/curl against a non-monorepo directory.
   assertMonorepoRoot(REPO);
-  console.log(`adia-ui-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
+  console.log(`adia-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
   step1ReBaseline(args);
   step3PreFlight(args);
   step4PromoteAndBump(args);
@@ -367,9 +360,8 @@ async function main() {
   await step8Push(args);
   await step9Publish(args);
   await step10GhAndSite(args);
-  step11Ledger(args);
   rl.close();
-  console.log('\n✓ release-pack complete. Don\'t forget to commit + push the ledger.');
+  console.log('\n✓ release-pack complete. Verify against the npm registry + GH releases, then author the release notes.');
 }
 
 main().catch((e) => {

package/skills/{adia-ui-release → adia-release}/scripts/tag-lockstep.mjs

@@ -8,7 +8,7 @@
 //   node tag-lockstep.mjs --version 0.6.22 --delete     # delete existing tags
 //   node tag-lockstep.mjs --version 0.6.22 --dry        # print commands without running
 //
-// Phase 2 of the adia-ui-release skill. Mechanizes the tag loop used
+// Part of the adia-release skill. Mechanizes the tag loop used
 // every cycle.
 
 import { execSync } from 'node:child_process';
@@ -25,6 +25,10 @@ const PER_PACKAGE_NAMES = [
   'a2ui-mcp',
   'a2ui-retrieval',
   'a2ui-validator',
+  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note);
+  // their `adia-ui-*-v*` tags trigger publish-adia-ui-{factory,forge}.yml.
+  'adia-ui-factory',
+  'adia-ui-forge',
 ];
 
 function parseArgs(argv) {

package/skills/adia-site-docs/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: adia-site-docs
+description: >-
+  Review or author pages under site/pages/{architecture,getting-started,
+  guides,patterns,reference}/ — the 34-page docs site. Use when asked to add
+  or edit a getting-started/architecture/guides/patterns/reference page,
+  review a site docs page for consistency, fix a callout that reads as plain
+  text, or explain why an inline-code chip or a demo gallery looks broken.
+  NOT for a component's own .examples.html demo (adia-author) or any
+  pure-primitive-composition training-harvest page (governed by
+  composition-and-examples.md's no-style-block rule; owner: adia-a2ui).
+disable-model-invocation: false
+user-invocable: true
+---
+
+# adia-site-docs
+
+Every page under `site/pages/{architecture,getting-started,guides,patterns,
+reference}/` shares one skeleton: `<header><h1>` + a deck `<p>`, then numbered
+`<section data-section data-property="...">` blocks, each opening
+`<h2 variant="section">` with an optional `<p data-note>` subtitle. Two
+archetypes ride it — narrative/explainer (architecture, getting-started,
+guides: prose + `<code-ui>` + tables, no live demos) and reference/gallery
+(patterns, reference: the same skeleton plus `<preview-ui>` demo rows and a
+near-universal closing "Guidance for agents" callout).
+
+Full decomposition, the 4 concrete rules, and the training-harvest-surface
+boundary this skill does NOT cover: read
+[`../../../../../.claude/docs/conventions/site-pages-authoring.md`](../../../../../.claude/docs/conventions/site-pages-authoring.md)
+in full before authoring or reviewing — it is the source of record; this
+skill routes to it and enforces it, it does not restate it.
+
+## Task shape → action
+
+| Task shape | Do |
+| --- | --- |
+| New page in an owned category | Read the convention doc's template section; copy the shared skeleton from a sibling page in the same category (narrative archetype vs. reference/gallery archetype). |
+| Callout / "meta content" block | `<alert-ui variant="warning\|info\|...">` with `<div slot="content">` (never `<span>` — the transpiler only treats `p`/`div`/`ul`/`ol` as prose; a `<span>` silently reorders mixed inline content on regen) for rich text — never a bare `data-*` attribute. A whole multi-heading section aimed at a different reader (not a short callout) is NOT `alert-ui`'s job either (wrong shape) — currently there's no working distinguishing treatment for this case beyond the heading text itself; see the convention doc's rule 2 for what's been tried and why it doesn't render. |
+| Tamed admin-shell demo | Add `class="demo-frame"` to the shell instance + a page-local `<style>` block setting only `--demo-frame-height` (and any genuinely page-specific extra). That's `site/site.css`'s `.demo-frame` utility already covering `position`/`border`/`overflow`/`.demo-body` padding. |
+| A surface needs to read as "its own distinct object" against the page background (a chip, a pill) | Reuse `--a-canvas-well-strong` (`packages/web-components/styles/colors/semantics/core.css`) — verified ≥3:1 (WCAG 2.2 SC 1.4.11) in both schemes. `--a-canvas-well` alone is for a subtly-sunken panel; a new candidate token always runs through `color:color-verify` first. |
+| "Is this page consistent?" / review request | Check the page against the convention doc's rules 1–4 by name; a finding names the specific rule violated, not just "this looks off." |
+| Anything touching a real UI primitive not already listed above | Audit `packages/web-components/components/` before inventing markup (this repo's standing rule) — a fake `data-*`/`class` convention with no CSS is exactly the defect class this skill exists to prevent. |
+
+## Verify after any change
+
+- `npm run check:links` — intra-repo links across the touched pages.
+- `node scripts/build/site-a2ui.mjs --page <route>` for every page whose
+  **markup** changed — regenerates the compiled A2UI artifact the
+  docs-transpiler produces from this source; a CSS-only fix needs no regen.
+- `color:color-verify` for any new or changed token used for text or
+  UI-component contrast — prove the ratio, don't estimate it.
+- `npm run check:lightningcss-build` after any CSS change (`site/site.css`
+  or a component's own `.css`).
+- **Visually verify any `alert-ui`/rich-slotted-content change in a
+  browser after regenerating** — a `valid:true` transpiler result and a
+  correct raw-HTML source do not prove the rendered order is correct;
+  the compiled `site-a2ui/pages/*.json` artifact is what's served, and
+  a wrong container tag (`<span>` instead of `<div>`) silently reorders
+  content while still passing schema validation. This is not optional
+  for this one content shape.
+
+A check that cannot run (missing script, no network for a build step) is a
+named blocker in the report — flag it and stop; never mark the page done on
+an assumed pass.
+
+Done when the touched page(s) pass the checks above and, for a reviewed
+page, every finding cites the specific rule in `site-pages-authoring.md` it
+violates.

package/skills/adia-site-docs/evals/audit-report.md

@@ -0,0 +1,30 @@
+# skill-review — adia-site-docs
+
+Skill: packages/plugins/adia-ui-forge/skills/adia-site-docs/SKILL.md · Standards: skill-authoring-standards · Lint: clean
+Verdict: PASS (no blocking finding)
+
+Lint verbatim: `skill-postwrite-invocation-lint · clean · .../adia-site-docs/SKILL.md`
+
+| ID | Verdict | Severity | Evidence (file:line) | Fix |
+|----|---------|----------|----------------------|-----|
+| R1 | PASS | — | SKILL.md:40 ("Never restate position/border/overflow…"), :41 (`--a-canvas-well-strong` verified ≥3:1), :43 (audit primitives before inventing markup) — each survives deletion; removing any re-admits a concrete defect class. | — |
+| R2 | PASS | — | Desc SKILL.md:4-8 front-loads verbatim user phrasings ("add or edit a … page", "review a site docs page", "fix a callout that reads as plain text"); fences use the parseable `NOT for X (owner)` form :9-12. Corpus routing (evals/routing-corpus.json) covers 16 should-fire + 6 adversarial. | — |
+| R3 | PASS w/ note | minor | Species=procedural (intent.md:3); dials explicit and agree (SKILL.md:13-14); name head `adia-site-docs` is a domain-noun, not the generic zero-derivation verb the standard prescribes for procedural — but it matches the whole plugin's `adia-<domain>` grammar (sibling adia-author is identically formed). Consistent within the estate; flagged only for the record. | Keep — estate naming convention governs; no change. |
+| R4 | PASS w/ note | minor | Load-bearing rows instantiate concrete actions (SKILL.md:38-43). Negative imperatives run to ~4 ("do NOT invent" :38, "never a bare data-*" :39, "Never restate" :40, "don't reach for a raw ramp step without color-verify" :41) — at/over the ≤3 hard-gate guideline. | Optional: demote the two style-choice negatives (:38, :41) to positive form; reserve NEVER for :39/:40 catastrophic invariants. |
+| R5 | PASS | — | Deliberately routes to `.claude/docs/conventions/site-pages-authoring.md` (SKILL.md:28-32) rather than copying rules 1-4; convention doc confirmed present with matching `### 1..4` headings. Drift pair avoided by design — the strongest dimension. | — |
+| R6 | PASS | — | Task-shape contract table up front (SKILL.md:34-43); verify steps + stopping predicate at tail (:45-58); body 59 lines (well under 500 / 5,000-token head); reference one level deep. | — |
+| R7 | PASS w/ gap | minor | Output contract present (review finding "cites the specific rule … it violates" :57-58); stopping predicate present ("Done when …" :56). No *named failure branches* (e.g. "if `check:links` cannot run → report blocker, do not mark done"). | Add one failure branch to the Verify section for a check that cannot run. |
+| R8 | PASS | — | Numeric anchors on load-bearing dims: "34-page" (:5,20), "≥3:1 (WCAG 2.2 SC 1.4.11)" (:41), "rules 1-4" (:42,57). No vague quantifiers on load-bearing lines. | — |
+
+## Additional evidence (non-scored hygiene)
+
+- **Phantom fence paths** (minor): description fences `site/pages/examples/**` and `site/pages/gen-ui/**` (SKILL.md:11); neither directory currently exists under `site/pages/` (only architecture, getting-started, guides, patterns, reference). The fence spends description budget on surfaces that are not yet present. Keep if these are planned training-harvest surfaces (intent.md:52 treats them as governed by composition-and-examples.md); otherwise trim to reclaim characters. Not blocking — the fence is still correct if/when those surfaces land, and adversarial-02 tests it.
+- **intent.md citation drift** (minor, not in payload): intent.md:64 cites `evals/evals.json`, but the shipped corpus is `evals/routing-corpus.json`. intent.md is a forge artifact, not skill payload, so it does not affect triggering — but repair the citation in the same edit to keep the record honest.
+
+## Top 3
+
+1. (minor) R7 — add one named failure branch to the Verify section (a check that cannot run → report blocker, do not mark done); procedural bodies owe an explicit failure branch, currently absent (SKILL.md:45-58).
+2. (minor) R4 — negative-imperative count sits at ~4; demote the two style-choice negatives (:38 section shape, :41 ramp step) to positive phrasing, reserving hard gates for the two real invariants (:39 fabricated data-*, :40 restated demo-frame CSS).
+3. (minor) Phantom fence — reconcile `site/pages/examples/**` and `site/pages/gen-ui/**` (SKILL.md:11): confirm they are planned surfaces or trim the fence; and fix the `evals.json` → `routing-corpus.json` citation in intent.md:64.
+
+No blocking or major findings. The skill's reference-don't-restate discipline (R5) and measured contrast anchor (R8) are its strongest features.

package/skills/adia-site-docs/evals/routing-corpus.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-site-docs routing accuracy corpus",
+  "version": "1.0.0",
+  "purpose": "Routing-eval corpus for adia-site-docs (adia-forge plugin). Each phrase declares whether adia-site-docs SHOULD be the routing target. Scored by the estate's TF-IDF routing-eval runner against the skill's description (heuristic token overlap).",
+  "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
+  "license": "internal",
+  "scope": "adia-site-docs routing — does this phrase activate adia-site-docs?",
+
+  "minimums_per_spec": {
+    "trigger_phrases": 16,
+    "adversarial_phrases": 6,
+    "task_shapes_covered": "new-page, review-page, callout-fix, demo-frame-consistency, contrast-token, sibling-boundary",
+    "adversarial_fraction": "27%"
+  },
+
+  "phrases": [
+    {
+      "id": "site-docs-review-01",
+      "phrase": "review this site docs page for consistency",
+      "should_route_to_site_docs": true,
+      "expected_shape": "review-page",
+      "rationale": "Canonical review-a-page task shape."
+    },
+    {
+      "id": "site-docs-review-02",
+      "phrase": "does this callout look like plain text to you",
+      "should_route_to_site_docs": true,
+      "expected_shape": "callout-fix",
+      "rationale": "Symptom description matching Defect 2 (fabricated data-alert)."
+    },
+    {
+      "id": "site-docs-review-03",
+      "phrase": "why is the code background not visible on this page",
+      "should_route_to_site_docs": true,
+      "expected_shape": "contrast-token",
+      "rationale": "Symptom description matching Defect 1 (inline-code contrast)."
+    },
+    {
+      "id": "site-docs-new-page-01",
+      "phrase": "add a new pattern page under site/pages/patterns",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "Explicit site/pages/patterns path mention."
+    },
+    {
+      "id": "site-docs-new-page-02",
+      "phrase": "author a new getting-started guide page",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "getting-started/ is one of this skill's 5 owned categories."
+    },
+    {
+      "id": "site-docs-new-page-03",
+      "phrase": "write a new architecture explainer page for the docs site",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "architecture/ is one of this skill's 5 owned categories."
+    },
+    {
+      "id": "site-docs-new-page-04",
+      "phrase": "create a reference page documenting the MCP tools",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "reference/ is one of this skill's 5 owned categories."
+    },
+    {
+      "id": "site-docs-demo-frame-01",
+      "phrase": "this demo page needs a tamed static frame like the other pattern pages",
+      "should_route_to_site_docs": true,
+      "expected_shape": "demo-frame-consistency",
+      "rationale": "Matches the .demo-frame consolidation rule."
+    },
+    {
+      "id": "site-docs-demo-frame-02",
+      "phrase": "add a new admin-shell demo to this patterns page without duplicating the taming CSS",
+      "should_route_to_site_docs": true,
+      "expected_shape": "demo-frame-consistency",
+      "rationale": "Direct match on rule 3 (reuse .demo-frame)."
+    },
+    {
+      "id": "site-docs-review-04",
+      "phrase": "is this site page consistent with our authoring conventions",
+      "should_route_to_site_docs": true,
+      "expected_shape": "review-page",
+      "rationale": "Direct convention-compliance ask."
+    },
+    {
+      "id": "site-docs-review-05",
+      "phrase": "audit site/pages/guides for the same callout bug we found elsewhere",
+      "should_route_to_site_docs": true,
+      "expected_shape": "review-page",
+      "rationale": "Explicit guides/ path + defect-class reference."
+    },
+    {
+      "id": "site-docs-callout-01",
+      "phrase": "this warning box on the docs page has no background at all",
+      "should_route_to_site_docs": true,
+      "expected_shape": "callout-fix",
+      "rationale": "Symptom description matching the fabricated data-alert defect."
+    },
+    {
+      "id": "site-docs-new-page-05",
+      "phrase": "what's the shared skeleton every site docs page should follow",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "Direct ask about the template decomposition this skill carries."
+    },
+    {
+      "id": "site-docs-contrast-01",
+      "phrase": "what token should a new chip-like surface use to stay readable against the page background",
+      "should_route_to_site_docs": true,
+      "expected_shape": "contrast-token",
+      "rationale": "Direct match on rule 1 (--a-canvas-well-strong)."
+    },
+    {
+      "id": "site-docs-review-06",
+      "phrase": "check the patterns pages for any other unstyled data attributes like data-alert",
+      "should_route_to_site_docs": true,
+      "expected_shape": "review-page",
+      "rationale": "Direct defect-class sweep request."
+    },
+    {
+      "id": "site-docs-new-page-06",
+      "phrase": "scaffold a new getting-started/theming-dark-mode.html page",
+      "should_route_to_site_docs": true,
+      "expected_shape": "new-page",
+      "rationale": "Explicit new-file-under-owned-category shape."
+    },
+
+    {
+      "id": "site-docs-adversarial-01",
+      "phrase": "review this component's own demo gallery in its .examples.html file",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "packages/web-components/components/*/*.examples.html is adia-author's remit, not this skill's."
+    },
+    {
+      "id": "site-docs-adversarial-02",
+      "phrase": "fix this gen-ui training exemplar page under site/pages/examples",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "site/pages/examples/** is the pure-primitive-composition training-harvest surface governed by composition-and-examples.md + adia-a2ui, explicitly fenced out."
+    },
+    {
+      "id": "site-docs-adversarial-03",
+      "phrase": "tune the zettel retrieval threshold for the chunk corpus",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "A2UI pipeline internals belong to adia-a2ui, unrelated to site/pages authoring."
+    },
+    {
+      "id": "site-docs-adversarial-04",
+      "phrase": "add a new prop to the button-ui primitive",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "Primitive authoring is adia-author's remit."
+    },
+    {
+      "id": "site-docs-adversarial-05",
+      "phrase": "cut the next npm release for the 9 @adia-ai packages",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "Release engineering is adia-release's remit, unrelated to docs-page authoring."
+    },
+    {
+      "id": "site-docs-adversarial-06",
+      "phrase": "deploy the docs site to ui-kit.exe.xyz",
+      "should_route_to_site_docs": false,
+      "expected_shape": "sibling-boundary",
+      "rationale": "Deploy operations are adia-deploy's remit; this skill authors content, it doesn't ship it."
+    }
+  ],
+
+  "evaluator_notes": "Adversarial phrases 1-2 specifically test the two hardest-to-distinguish fences (component .examples.html vs site/pages/patterns/*.html; site/pages/examples/** vs site/pages/{architecture,getting-started,guides,patterns,reference}/**) — both surfaces are literally *.html under similar-looking paths, so the description must lean on the explicit path lists, not just 'site pages' as a phrase."
+}

package/skills/adia-site-docs/intent.md

@@ -0,0 +1,72 @@
+# intent — adia-site-docs
+status: shipped
+species: procedural
+dials: { disable-model-invocation: false, user-invocable: true }
+freedom: medium
+type: capability-uplift
+
+Note: this intent record was filled directly from an already-approved
+plan (`.claude/plans/enchanted-singing-globe.md`, "Site docs review +
+authoring method") and this session's own research (3 parallel Explore
+agents surveying `site/pages/`'s structure, a color-contrast root-cause
+investigation, and a review of existing tooling) rather than a live
+turn-by-turn interview — the operator confirmed the plan, including
+"doc + a dedicated skill" as the Phase 4 method depth, before this
+skill was forged. Slots below are answered from that record, not
+fabricated dialogue.
+
+## trigger
+should:
+  - "review this site docs page"
+  - "add a new pattern page under site/pages/patterns"
+  - "why does this callout look like plain text"
+  - "author a new page under site/pages/getting-started"
+  - "is this site page consistent with our conventions"
+should_not:
+  - "review this component demo gallery" (packages/web-components/components/*/*.examples.html — adia-author)
+  - "fix this gen-ui training exemplar page" (site/pages/examples/**, site/pages/gen-ui/** — composition-and-examples.md's no-style-block rule + adia-a2ui)
+
+## delta
+Without this skill, Claude (or a human author) reaches for whatever
+looks locally plausible on a `site/pages/*.html` page and repeats the
+defect classes this session found and fixed: a fabricated `data-*`
+attribute standing in for a real primitive (16 of 34 pages had
+`data-alert="warning|info"` with ZERO matching CSS anywhere — dead
+markup that silently renders as plain paragraphs), a hand-rolled
+`<style>` block duplicating an existing shared utility (4 pages
+independently reinvented the same "tame this admin-shell demo" CSS),
+and a background token picked for its "feels dark and subtle" name
+rather than its actual measured contrast (inline `<code>` used
+`--a-canvas-well`, verified via `color:color-verify` at ~1.1:1 against
+the page background — WCAG 2.2 SC 1.4.11 wants ≥3:1). All three are
+now fixed at the shared-CSS/token level (cascades to all 34 pages),
+but a NEW page authored without this skill's guidance would
+re-introduce the same classes on page 35. Deleted after a month: the
+next contributor re-invents a `data-tip`/`data-caution` variant of the
+same dead-attribute bug, or a 5th hand-rolled demo-taming `<style>`
+block, because nothing routes them to `alert-ui` or `.demo-frame`
+before they start typing.
+
+## fences
+- NOT for `packages/web-components/components/*/*.examples.html` component demo pages (adia-author)
+- NOT for `site/pages/examples/**`, `site/pages/gen-ui/**`, `packages/a2ui/corpus/exemplars/**` — pure primitive-composition training-harvest surfaces with their own no-style-block rule (`composition-and-examples.md`, adia-a2ui)
+- NOT for the A2UI generation pipeline itself, chunk corpus, or MCP tools (adia-a2ui)
+
+## assertions
+1. A new callout block the skill produces uses `<alert-ui variant="...">` with a `[slot="content"]` wrapper for rich text — never a bare `data-*` attribute with no matching CSS.
+2. A new tamed-demo page the skill produces adds `class="demo-frame"` plus only a page-local `--demo-frame-height` override — it does not restate `position`/`border`/`overflow`/`.demo-body` padding.
+3. When asked to review an existing page, the skill's output names the specific rule from `site-pages-authoring.md` a defect violates (not just "this looks off").
+4. The skill's own description correctly declines to fire on a component `.examples.html` demo or a `site/pages/examples/**` training page (see `should_not` above) and instead names the owning sibling skill.
+
+## gates
+P0 route:      PASS — 2026-07-14 — knowledge/procedure needed on demand (author or review a site/pages doc), not mechanically checkable (hook), not always-true-every-turn (entry file), no tool-wall/parallelism need (agent). Skill.
+P1 intent:     PASS — 2026-07-14 — slots filled from the approved plan + this session's research; operator confirmed the plan's Phase 4 scope (doc + dedicated skill) via AskUserQuestion before forging began.
+P2 evals:      PASS — 2026-07-14 — see evals/routing-corpus.json (trigger cases, matching this repo's adia-author sibling's own eval-file convention) and assertions above (behavioral). No literal fresh-session baseline captured (this is a same-session, plan-driven forge, not an interactive intent interview) — the delta section above records the concrete "without this skill" failure mode from direct evidence (the 3 defect classes this session found and fixed) in place of a baseline transcript.
+P3 draft:      PASS — 2026-07-14 — SKILL.md + evals/routing-corpus.json exist; both dials explicit; body 61 lines, well under the 500-line budget.
+P4 language:   PASS — 2026-07-14 — self-audited against the 5 instantiation checks: task-shape rows commit to concrete actions (not descriptions); ~3 hard-gate ceiling held (never restate demo-frame properties, never a bare data-* callout, don't reach for a raw ramp step without color-verify); numeric anchors present (>=3:1, 34-page, 4 rules); contracts (task-shape table) precede the verify-steps tail; the labeled good/bad alert-ui pair lives in the referenced convention doc rather than duplicated here (reference, never restate).
+P5 validate:   PASS — 2026-07-14 — skill_lint.py clean; skill-auditor FLOOR audit verdict PASS (report at evals/audit-report.md), 3 minor non-blocking findings, all fixed same-change (phantom fence trimmed to reference composition-and-examples.md by name rather than specific paths; 2 negative imperatives demoted to positive form; intent.md's routing-corpus.json citation corrected). No fence-reciprocity step run against adia-author's own evals — adia-author's corpus already covers "primitive authoring" as should_route_to_author:true, which is the correct answer for those phrases; no reciprocal edit needed there.
+
+## rulings
+- Accepted with note: no literal fresh-session baseline transcript (P2) — this forge ran from an already-approved plan's research rather than a live interview; the delta section's direct evidence substitutes. Not re-litigated.
+- Accepted with note: convention doc lives at `.claude/docs/conventions/site-pages-authoring.md`, not inside this skill's own `references/` — deliberate, to avoid a drift pair with the doc that's also linked from `document-routing.md`.
+- Post-ship correction (same session, before task close): the skill's own Rule-2 example used `<span slot="content">` — a real bug, not just a style choice. `scripts/build/lib/docs-transpiler.mjs`'s `PROSE_CONTAINERS` only recognizes `p`/`div`/`ul`/`ol`; `<span>` fell to a different decomposition path that silently reordered mixed inline content (a leading `<strong>` rendered AFTER the surrounding text, bold dropped) once the compiled `site-a2ui/pages/*.json` regenerated — invisible to schema validation (`valid:true`) and to a raw-HTML read, only caught by a live-browser check. Fixed in SKILL.md, the convention doc, and all 16 already-migrated `site/pages/*.html` files (`<span>` → `<div>`). Added "visually verify" as a non-optional Verify step for this content shape.