@weatherboard/gyde-design 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weatherboard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# Gyde — design system scaffolding and gate
+
+Gyde measures a repository's design system, scaffolds what is missing, and then
+keeps auditing what you build against it. It emits code you own, and it gates
+against a ledger that may only ever get shorter.
+
+```
+gyde-design scan <path>    measure a repository as it is
+gyde-design plan <path>    say what would be emitted; write nothing
+gyde-design init <path>    write it; never overwrites
+gyde-design gate <path>    fail on anything new since the committed ledger
+gyde-design tokens         print the stylesheet for the seed dictionary
+```
+
+## What Gyde is
+
+An **always-on creative director**. A product does not maintain its own review
+standards in-tree and hope they keep firing; it asks Gyde, and Gyde answers with
+a verdict.
+
+The boundary in one line: **Gyde decides whether it is valid; the product
+decides what it is.**
+
+**Gyde owns** the rules, the normalised representation they are written against,
+the ledger format, the templates, and the upgrade path that reaches an edited
+file.
+
+**Gyde never owns** your components, your token *values*, your content, layouts,
+brand or product decisions, or your repository. Everything Gyde emits is yours
+from the moment it is written, and Gyde will not overwrite it. Gyde enforces the
+token *contract*; the values belong to you.
+
+If design-system *logic* ends up living in your repo, that is a bug in the
+installation, not a feature of the product.
+
+### Authority
+
+The only sanctioned escape valve is the **allowance ledger**: per file, per
+rule, per count, and only ever ratcheting down. There is no env var, no skip
+flag, and no supported way to make a failing gate pass by editing a baseline
+upward.
+
+`gate` with no ledger records one and **exits non-zero**. Recording debt is the
+sanctioned way it enters — amnesty never — and a run that recorded rather than
+judged is not a pass.
+
+**Degraded mode fails loudly, never silently green.** If Gyde cannot run, the
+gate fails or reports "Gyde did not run" as an explicit state that CI treats as
+failure. There is no configuration in which "could not run" produces a pass.
+This is load-bearing, not a preference: the most expensive failures this tool
+was built against were checks that reported success without executing — a
+`paths:` filter skipping a job, a package filter matching nothing and exiting 0.
+
+## Installing it
+
+**Repository CI** takes Gyde as a GitHub Action. No dependency, no token, no
+`.npmrc`:
+
+```yaml
+# .github/workflows/gyde.yml
+name: Gyde
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  design-system:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: Another-Iteration/gyde@v1
+        with:
+          fail-on: new
+```
+
+Your dependency graph is untouched and no credential enters your CI. There is no
+install step inside the action either: the engine imports nothing but `node:`
+builtins, so checking the action out *is* the installation. A test pins that
+property, and a registry outage cannot fail your gate.
+
+**Laptops, sandboxes and agents** take the package, because neither runs GitHub
+Actions:
+
+```
+npm i -D @weatherboard/gyde-design
+```
+
+> The package name is under review as part of going public — see the scope
+> question in `docs/decisions/g-64-public.md`.
+
+`fail-on: none` still runs, still reports, still writes evidence, and still
+fails if the gate could not run. It only declines to block on the verdict, and
+it does so visibly. It is what an adopting repository uses for a fortnight while
+it decides whether the ledger is right. It is not what it uses forever.
+`continue-on-error` is not supported and never will be — it makes every failure
+look like a pass, which is the one outcome a gate exists to prevent.
+
+## The one idea
+
+Every design-system audit we had was written against one repository's spelling,
+and each was correct locally and useless one repository over. One matched
+Tailwind utilities; another matched CSS declarations; neither would have found
+anything in the other's repo.
+
+So the rules do not match source text. Five spellings of one decision —
+
+```
+rounded-lg              Tailwind utility
+border-radius: 8px      CSS declaration
+borderRadius: 8         JS / StyleX object
+borderRadius: radius.card
+var(--radius-card)      custom property
+```
+
+— all normalise to the same radius decision, and one rule asks the question it
+was always trying to ask: *is this tokenised?* `rules.test.mjs` proves it
+against all five.
+
+## The modules
+
+| | |
+| --- | --- |
+| `workspace.mjs` | Discovers packages from the workspace declaration, never from directory names. Classifies each; every exclusion carries a reason. |
+| `normalise.mjs` | Reduces Tailwind utilities, CSS declarations, JS/StyleX objects and cva strings to one representation. |
+| `rules.mjs` | The violation rules, written once against that representation. Refuses to load a rule without both a failing and a passing fixture. |
+| `scan.mjs` | Walks a tree, classifies, scores. Never emits a percentage without its denominator. |
+| `tokens.mjs` | The dictionary shape, its guarantees, and generators for CSS, plain constants and DTCG. |
+| `boundaries.mjs` | Import and dependency boundaries, the exemption register, and version-drift detection. |
+| `ratchet.mjs` | The allowance ledger. A cleared entry is deleted, never zeroed. |
+| `emit.mjs` | The seed components and the two structural modules. |
+| `catalogue.mjs` | The catalogue, generated from the same list the barrel is. |
+| `wiring.mjs` | Is the design system actually connected to the app that uses it? |
+| `usage.mjs` | Which component is used where, and what the product keeps reinventing. |
+| `upgrade.mjs` | Provenance, and the three-way classification that uses it. |
+| `agentdocs.mjs` | What an agent building the product reads before writing UI. |
+
+## Measured, on the three repositories it was built from
+
+De-identified, because the numbers are the evidence and the names are not.
+
+| | product files | decls | tokenised | findings |
+| --- | ---: | ---: | ---: | ---: |
+| System A — mature system, CSS-declaration styling | 176 | 379 | 98% | 9 |
+| System B — mature system, low application adoption | 1,801 | 7,361 | 15% | 6,078 |
+| System C — shadcn-style, utility-first page code | 394 | 2,642 | 8% | 2,437 |
+
+System A's 98% is corroboration worth having: that team independently reports
+96% adoption from a rule set built on entirely different premises. Two points
+apart is the best evidence available that the normalised form measures the same
+thing a hand-written rule set does.
+
+**The two low numbers are not the same number twice.** System B has a mature
+system its applications have not adopted. System C's apps import its UI package
+in 109 files and define zero bespoke components — its 8% is Tailwind utilities
+in page code, which is what shadcn expects you to write. A verdict that cannot
+tell those apart is worthless, which is why `scan` classifies before it scores.
+
+## Why plan and init share a call
+
+Both go through one `buildEmission()`. The dry run cannot describe a file the
+real run would not write, and that is structural rather than a promise — a
+scaffolder whose two modes can diverge is one nobody can review before it writes
+into their repository.
+
+`init` refuses to overwrite anything. Gyde emits once and the file becomes the
+product's; a scaffolder that clobbers has taken ownership of something it does
+not own, silently.
+
+## Rules that go quiet
+
+A rule that matched nothing anywhere is reported as **suspicious**, not clean.
+We have a recorded case of a rule reporting zero against 178 real hits with
+nobody able to tell. Silence and success must not render the same.
+
+## A number we got wrong
+
+The first version of the table above read System B at 12% and System C at 4,061
+findings. Every class inside a `className` attribute was counted twice, so
+utility-heavy repos were measured at roughly double. It was found end to end — a
+scaffolded fixture recorded seven findings for four real defects — and not by
+any fixture, which is worth remembering when reading the rest of this.
+
+## Two silences this makes audible
+
+**An app can score 100% adoption while rendering unstyled HTML.** If it imports
+design-system components but never the token stylesheet, every
+`var(--color-text)` resolves to nothing. Nothing throws, the build passes, and
+the audit is delighted — only system imports, no literal values. `wiring.mjs`
+checks the link, following `@import` across workspace packages, and reports
+"could not tell" as its own outcome rather than as "fine".
+
+**A component nobody renders looks identical to one used everywhere.**
+`usage.mjs` answers the two questions the audit cannot: *does the set already
+compose this?* and *is anybody using what we shipped?* Advisory, never blocking
+— a cluster of bespoke class names is evidence of a missing capability, and a
+gate that cannot tell that from a broken rule just makes the workaround harder
+to find.
+
+## A gap the catalogue cannot close
+
+A closed component set cannot force its own interactive states. `Select`'s open
+state is where theming across a portal boundary is proved, and exposing
+`defaultOpen` to demonstrate it would be an escape hatch opened for the
+catalogue's convenience. The generated catalogue records that as a note on the
+entry rather than printing "open" beside a control that is closed — a label that
+lies is worse than an admission.
+
+## The upgrade, which is the wedge
+
+Gyde emits a component set, the product edits it — editing it is the point —
+and later Gyde improves the template. Reaching a file somebody has been working
+in is shadcn's openly unsolved problem: three multi-year issues, and its own
+docs call re-syncing *"an ongoing responsibility rather than a solved problem"*.
+
+`init` records provenance: the template version and a hash of each file's exact
+emitted bytes. That is the missing third point, and with it every file is one of
+four cases:
+
+| | |
+| --- | --- |
+| neither changed | nothing to do |
+| Gyde changed only | safe to apply |
+| product changed only | their edit is the truth; left alone |
+| **both changed** | a **conflict** — reported, never merged |
+
+It never auto-merges, never touches a file it has no provenance for, never
+deletes a file it stopped emitting, and never restores one the product deleted.
+
+The subtle part: an **unapplied** change keeps its **old** baseline. Otherwise
+the next upgrade reads it as a product edit, and a conflict quietly becomes
+"yours" and is never offered again.
+
+## The one artefact that changes what gets written
+
+`.gyde/design-system.md` is generated from the same metadata as the barrel and
+the catalogue, so it cannot name a component that does not exist — the failure
+it replaces is a hand-written registry pointing at a superseded generation of
+its own components.
+
+Its most important section is what to do when the set *cannot* do the thing.
+Without it the honest agent and the lazy one produce the same bespoke CSS, and
+only one of them knew it was a compromise.
+
+Gyde does not write into your `CLAUDE.md`. It emits a fragment for you to
+include — that file is the last one a tool should edit unasked.
+
+## Not built yet
+
+Build-pipeline wiring for a compiled token layer — moot while the emitted tokens
+are plain CSS custom properties, and required the moment they are not.
+Service-side ledger and provenance storage; both are committed files where they
+want to be unforgeable. And the genericity check exists only as a test over the
+templates, not as a command anyone can run.
+
+## Status and licence
+
+Pre-1.0. The action tag `v1` names the action's input/output interface, which
+has been stable; the package is versioned independently and moves faster. No
+stability promise is made below 1.0.
+
+The licence is being decided as part of making this public. Until a `LICENSE`
+file lands, all rights are reserved.

package/adoption.mjs

@@ -0,0 +1,138 @@
+/**
+ * G-74 — one adoption number, and why it is a minimum rather than an average.
+ *
+ * A consumer reports 95% adoption. Gyde reports 15%. Both are correct, and
+ * until now nothing said so, which meant two teams could look at the same
+ * repository and disagree about whether the work was done.
+ *
+ * THE RECONCILIATION IS THAT THEY MEASURE DIFFERENT LAYERS.
+ *
+ *   token   of the style DECLARATIONS this code makes, how many come from the
+ *           dictionary?  (scan.mjs `adoption`)
+ *   markup  of the ELEMENTS that made a visual decision, how many are the
+ *           system's components?  (markup.mjs, G-73)
+ *
+ * They are close to orthogonal. A page of bare divs carrying semantic utility
+ * classes scores ~100% on token and ~0% on markup: every value it uses is from
+ * the dictionary and it is not using the component set at all. A page built
+ * from system components with a few hard-coded hex overrides scores the
+ * reverse. The 95%-against-15% spread is not a discrepancy to be resolved; it
+ * is two true statements about different things.
+ *
+ * CHARTER §2 makes the definition Gyde's: "What 'adoption' means is Gyde's; a
+ * product cannot redefine a metric locally." So this defines it.
+ *
+ * WHY THE MINIMUM, AND NOT THE AVERAGE.
+ *
+ * An average lets a product trade one layer against the other and report
+ * progress with nothing having improved. That is the same failure exactly — "an
+ * average is a number that can regress with nothing behind it regressing" —
+ * and it runs in both directions: it can also IMPROVE with nothing behind it
+ * improving. Tokenising a hundred hard-coded colours inside hand-rolled divs
+ * would move an average up while the component set stayed exactly as unused as
+ * it was.
+ *
+ * The minimum cannot be gamed that way. It says: a design system is adopted to
+ * the extent of its weakest layer, and the way to move the number is to fix
+ * the thing that is actually behind. It is also the number that matches what
+ * somebody means when they ask "are we on the design system?" — they do not
+ * mean "on average, partly".
+ *
+ * WHAT HAPPENS WHEN A LAYER CANNOT BE MEASURED IS THE LOAD-BEARING PART.
+ *
+ * If markup cannot be measured — no readable barrel — the overall number is
+ * NOT the token number. Reporting the layers that happened to work is how a
+ * headline silently inflates: the missing layer is usually the low one,
+ * because the repositories that cannot be attributed are the ones that have
+ * not adopted. So an unmeasured layer makes the overall figure `null` with the
+ * reason attached, and CHARTER §5 applies unchanged: "Gyde did not measure
+ * this" and "Gyde found nothing here" must never render the same.
+ */
+
+/** The layers, in the order a reader should meet them. */
+export const LAYERS = ["token", "markup"];
+
+/**
+ * Reconcile the layers into one figure.
+ *
+ * Each input is `{ used, of, percent }` — the shape scan.mjs already produces,
+ * with `percent: null` meaning "nothing to measure here" rather than zero.
+ */
+export function reconcile({ token = null, markup = null } = {}) {
+  const layers = {
+    token: normalise(token, "no styling declarations in product code"),
+    markup: normalise(markup, "no element made a visual decision"),
+  };
+
+  const measured = LAYERS.filter((k) => layers[k].percent !== null);
+  const missing = LAYERS.filter((k) => layers[k].percent === null);
+
+  // Nothing measurable at all is not 0%. It is a repository with no product
+  // surface to judge, and saying 0% would be an accusation.
+  if (measured.length === 0) {
+    return {
+      percent: null, layers, measured, missing,
+      why: "neither layer could be measured, so there is no adoption figure — this is not 0%",
+    };
+  }
+
+  // A partial measurement does not get a headline. The missing layer is
+  // usually the low one, so reporting what worked is how a number inflates.
+  if (missing.length > 0) {
+    return {
+      percent: null, layers, measured, missing,
+      why: `only ${measured.join(" and ")} could be measured; ` +
+           `reporting a figure without ${missing.join(" and ")} would overstate it`,
+    };
+  }
+
+  const weakest = measured.reduce((a, b) => (layers[a].percent <= layers[b].percent ? a : b));
+  return {
+    percent: layers[weakest].percent,
+    weakest,
+    layers, measured, missing,
+    why: `the weakest layer is ${weakest}; a design system is adopted to the extent of its weakest layer`,
+  };
+}
+
+function normalise(a, emptyWhy) {
+  if (!a) return { percent: null, used: null, of: null, why: "not measured" };
+  if (a.percent === null || a.of === 0) return { percent: null, used: a.used ?? 0, of: a.of ?? 0, why: emptyWhy };
+  return { percent: a.percent, used: a.used ?? a.tokenised ?? null, of: a.of };
+}
+
+export function formatAdoption(result) {
+  const L = [];
+  const { layers } = result;
+
+  const line = (name, label) => {
+    const l = layers[name];
+    return l.percent === null
+      ? `  ${label.padEnd(8)} n/a — ${l.why}`
+      : `  ${label.padEnd(8)} ${String(l.percent).padStart(3)}%  (${l.used} of ${l.of})`;
+  };
+
+  if (result.percent === null) {
+    L.push(`adoption     no single figure — ${result.why}`);
+  } else {
+    L.push(`adoption     ${result.percent}%  (${result.weakest}, the weakest layer)`);
+  }
+  L.push(line("token", "token"));
+  L.push(line("markup", "markup"));
+
+  if (result.percent !== null) {
+    const spread = Math.abs(layers.token.percent - layers.markup.percent);
+    if (spread >= 25) {
+      L.push("");
+      L.push(`  The layers are ${spread} points apart, which is the number worth reading.`);
+      L.push(layers.token.percent > layers.markup.percent
+        ? "  Style values are coming from the dictionary; the components are hand-rolled."
+        : "  The component set is being used; the values inside it are not from the dictionary.");
+    }
+  }
+
+  L.push("");
+  L.push("  The minimum, not the average. An average moves when one layer improves and");
+  L.push("  the other rots, which is progress reported with nothing behind it.");
+  return L.join("\n");
+}

package/agentdocs.mjs

@@ -0,0 +1,246 @@
+/**
+ * G-17 / G-56 — what an agent building the product needs to know, generated.
+ *
+ * @gyde-emits-source-for-another-repo
+ *
+ * WHY THIS IS NOT DOCUMENTATION.
+ *
+ * Every other module here judges code after it is written. This one is the only
+ * one that changes what gets written, and G-59's note is the argument: an agent
+ * that knows the component set uses it; an agent that does not gets audited for
+ * not using it, which is the expensive order. A gate that fires on the hundredth
+ * bespoke card has already let ninety-nine through.
+ *
+ * WHY IT IS GENERATED RATHER THAN WRITTEN.
+ *
+ * A hand-maintained component doc is the failure mode CHARTER names directly —
+ * docs that route agents to deleted components. The larger source repository
+ * has it today: a 433-line hand-written registry whose paths point at a
+ * superseded generation of its own components and whose Button lists four
+ * variants where the real one has nine. An agent reading that would confidently
+ * write against an API that does not exist.
+ *
+ * So this is derived from the same metadata as the barrel and the catalogue,
+ * and `agentdocs.test.mjs` asserts every component it names is exported and
+ * every exported component is named. A doc that can drift will drift.
+ *
+ * WHAT IT DELIBERATELY CONTAINS.
+ *
+ * Not prose about design philosophy. Three things an agent can act on:
+ * the components that exist and when each applies; the refusals, stated as
+ * rules with their reasons; and — the one most likely to be skipped — what to
+ * do when the set cannot do the thing. Without that last part the honest agent
+ * and the lazy one produce the same bespoke CSS.
+ */
+
+import { SEED_COMPONENTS } from "./emit.mjs";
+import { CATALOGUE_ENTRIES } from "./catalogue.mjs";
+
+/**
+ * The props an agent has to get right, per component.
+ *
+ * Derived from the catalogue's own example states rather than restated, so a
+ * prop cannot appear here and nowhere else. Required props are those present in
+ * every example — a prop the catalogue always passes is one the component needs.
+ */
+function propsFor(name) {
+  const entry = CATALOGUE_ENTRIES[name];
+  const controlled = Object.keys(entry.controlled ?? {});
+  const seen = new Map();
+
+  for (const state of entry.states) {
+    for (const [k, v] of Object.entries({ ...(entry.controlled ?? {}), ...state.props })) {
+      if (!seen.has(k)) seen.set(k, new Set());
+      seen.get(k).add(typeof v === "object" ? "…" : String(v));
+    }
+  }
+
+  const inEvery = [...seen.keys()].filter((k) =>
+    entry.states.every((s) => k in { ...(entry.controlled ?? {}), ...s.props }));
+
+  return [...seen.entries()].map(([prop, values]) => ({
+    prop,
+    required: inEvery.includes(prop),
+    // Sorted, so adding an example never reorders an existing line. A generated
+    // doc whose diff churns on unrelated edits is one people stop reading.
+    values: [...values].filter((v) => v !== "…").sort(),
+    controlled: controlled.includes(prop),
+  }));
+}
+
+const componentSection = (name) => {
+  const entry = CATALOGUE_ENTRIES[name];
+  const props = propsFor(name);
+  const req = props.filter((p) => p.required);
+  const opt = props.filter((p) => !p.required);
+
+  const line = (p) => {
+    const vals = p.values.length && p.values.length <= 6 ? ` — ${p.values.join(" | ")}` : "";
+    return `- \`${p.prop}\`${p.required ? " (required)" : ""}${vals}`;
+  };
+
+  return `### ${name}
+
+${entry.purpose}
+
+**Use instead of:** ${entry.replaces.join(", ")}.
+
+${req.map(line).join("\n")}${opt.length ? "\n" + opt.map(line).join("\n") : ""}
+${(entry.notes ?? []).map((n) => `\n> ${n}`).join("")}`;
+};
+
+/**
+ * The document.
+ *
+ * Written to be read by something that will act on it immediately, so the
+ * refusals come before the component list: an agent that reads only the first
+ * screen should still not reach for `className`.
+ */
+export function agentDoc({
+  components = SEED_COMPONENTS,
+  systemPackage = "@scaffold/design-system",
+  /**
+   * Did Gyde emit these components, or only read their names? (G-66)
+   *
+   * This is the difference between two documents that look alike and make
+   * completely different claims.
+   *
+   * `true` — the set Gyde emitted. Gyde has the catalogue metadata, so it can
+   * state each component's purpose and props, and it knows they refuse
+   * `className` because it wrote the refusal.
+   *
+   * `false` — the product's own components, discovered from its barrel. Gyde
+   * knows the NAMES and nothing else. Printing prop tables here would be
+   * inventing an API: System B exports a `Button`, Gyde's catalogue has
+   * a `Button`, and they are not the same component. A doc that confidently
+   * describes the wrong props is worse than one that says it does not know —
+   * it is the hand-maintained-registry failure this file exists to replace,
+   * reproduced automatically.
+   *
+   * The rules still apply either way; the gate enforces them regardless of who
+   * wrote the components. But in unverified mode they are stated as
+   * requirements rather than as facts about the implementation.
+   */
+  verified = true,
+} = {}) {
+  const closure = verified
+    ? `**Never pass \`className\` or \`style\` to a design-system component.** They do not
+accept them, on purpose. That refusal is the only reason the set means anything:
+a component that can be overridden will drift, and one escape hatch makes every
+other rule advisory.`
+    : `**Never pass \`className\` or \`style\` to a design-system component.** If you
+need an appearance the component does not offer, that is a gap to report — see
+below. A component that can be overridden will drift, and one escape hatch makes
+every other rule advisory.`;
+
+  return `<!-- GENERATED BY GYDE — regenerate rather than edit.
+     Every component named here is exported by the package: this list is read
+     from the barrel, not maintained by hand. A hand-maintained version routes
+     agents to components that no longer exist, which is the specific failure
+     this replaces.${verified ? "" : `
+     Names only. Gyde did not write these components and does not describe their
+     props — read the source for those.`} -->
+
+# The design system
+
+Everything visual in this product comes from \`${systemPackage}\`. Read this before
+writing any UI.
+
+## The rules, and why they exist
+
+**Never write a colour, a size, a radius, a spacing or a shadow at the call
+site.** They come from the token dictionary. A value spelled in a component is
+one nobody can change centrally, and it is what the audit fails on.
+
+${closure}
+
+**Do not import the primitive library directly.** The design system wraps it and
+keeps a closed API; importing it from an app walks around that wall. A boundary
+rule fails the build if you do.
+
+**Variants pick a tone and an emphasis. They never introduce a colour.** If the
+variant you want does not exist, that is a gap to file — see below.
+
+## When the set cannot do the thing
+
+This is the important part, and the one that decides whether this document is
+worth having.
+
+**A page that needs something the set cannot compose has found a gap in the set.
+That is a finding to file, not a licence to write bespoke CSS.**
+
+Concretely, in order:
+
+1. **Compose it** from what exists. Most "missing components" are two existing
+   ones next to each other.
+2. **If it genuinely cannot be composed**, say so in your output — name the
+   component you needed and what it would have done — and use the nearest
+   available component rather than inventing a styled \`div\`.
+3. **Do not** reach for a bespoke class name or an inline style to close the gap
+   quietly. That is the outcome that costs the most later: it looks like the
+   feature shipped and it means the set silently stopped covering the product.
+
+A gap you report becomes a component. A gap you paper over becomes a shadow
+system, and the measured cost of one of those is two applications reporting 0%
+adoption while nobody broke a single rule.
+
+## Runtime theming
+
+If a surface takes colours that are only known at request time — a per-tenant
+brand — do **not** reach for inline styles. Spread \`themeVars(theme)\` onto an
+element you already own and set the component's tone to \`themed\`. It returns
+CSS custom properties only, which is why it is not an escape hatch.
+
+## The components
+
+${verified
+  ? components.map(componentSection).join("\n\n")
+  : `These ${components.length} components are exported by \`${systemPackage}\`. **Use one of
+these before writing anything.** Gyde did not write them, so it does not
+describe their props here — a generated prop table for a component Gyde has
+never seen would be a guess, and a confident one. Read the component's source
+for its API.
+
+${components.map((c) => `- \`${c}\``).join("\n")}`}
+
+## Where to look
+
+${verified ? `- The catalogue renders every component in every state, in both themes. It boots
+  with nothing else running.
+` : `- The component's own source, for its props. Gyde does not have them.
+`}- \`gyde design scan\` reports what is tokenised, what is not, and which
+  vocabularies the product keeps reinventing.
+`;
+}
+
+/**
+ * The fragment a customer's own agent instructions include.
+ *
+ * Kept separate and short because it is pasted into a file Gyde does not own.
+ * A scaffolder that rewrote somebody's CLAUDE.md would be taking ownership of
+ * the one document that is most obviously theirs.
+ */
+export function agentInstructionsFragment({ docPath = ".gyde/design-system.md" } = {}) {
+  return `<!-- Add this to your agent instructions (CLAUDE.md, AGENTS.md, or equivalent).
+     Gyde does not edit that file — it is yours, and it is the last one a tool
+     should be writing into unasked. -->
+
+## Design system
+
+Before writing any UI, read [\`${docPath}\`](${docPath}). Its component list is
+read from the package's barrel rather than maintained by hand, so it cannot
+route you to a component that no longer exists.
+
+The three rules that matter most: no colour, size, radius or spacing spelled at
+the call site; no \`className\` or \`style\` on a design-system component; and if
+the set cannot compose what you need, report the gap rather than writing bespoke
+CSS around it.
+`;
+}
+
+export function emitAgentDocs({ components = SEED_COMPONENTS, systemPackage, path = ".gyde", verified = true } = {}) {
+  return {
+    [`${path}/design-system.md`]: agentDoc({ components, systemPackage, verified }),
+    [`${path}/agent-instructions-fragment.md`]: agentInstructionsFragment({ docPath: `${path}/design-system.md` }),
+  };
+}