@weatherboard/gyde-design 0.4.0 → 0.4.2

package/README.md

@@ -70,7 +70,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: Another-Iteration/gyde@v1
+      - uses: Weatherboard-Studio/gyde@v1
         with:
           fail-on: new
 ```
@@ -135,6 +135,8 @@ against all five.
 | `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. |
+| `ruleindex.mjs` | Every rule as data — id, name, intent, fix shape. Describes; never decides. |
+| `selfgate.mjs` | Emits a scaffold and gates it. Gyde held to its own rules. |
 
 ## Measured, on the three repositories it was built from
 
@@ -168,6 +170,65 @@ into their repository.
 product's; a scaffolder that clobbers has taken ownership of something it does
 not own, silently.
 
+## The rules, as data
+
+A rule id reaches you three times — in a finding, in the `rules` stamp inside
+`gyde-allowance.json`, and in a failing gate — and every time it is a bare slug.
+`optional-prop` says what matched. It does not say what the rule defends or what
+the fix looks like.
+
+So the rules are also available as data:
+
+```js
+import { rules, rulesJson } from "@weatherboard/gyde-design/ruleindex.mjs";
+
+rules();
+// [
+//   {
+//     id: "optional-prop",
+//     name: "Optional prop",
+//     intent: "A prop a caller may omit, leaving the component to make the decision silently.",
+//     fix: "Make it required. Where absence is itself a real answer, make it required and NULLABLE …",
+//   },
+//   …
+// ]
+```
+
+`rules()` returns frozen entries sorted by id; `rulesJson()` is the same thing as
+a JSON string, and `node ruleindex.mjs` prints it. Use it to generate a rules
+page, to give an agent the fix shape alongside the finding, or to diff what a
+version change means.
+
+**It describes and it never decides.** Nothing in the scan, the ledger or the
+gate reads it, and nothing may start to: a description that can change a verdict
+is a second copy of the rule kept in prose, and it will disagree with the first
+one quietly. The predicates stay in `rules.mjs`, `props.mjs`, `compound.mjs` and
+`docdrift.mjs`.
+
+Completeness is checked in both directions, against the `rules` stamp that a
+real `gate` run wrote rather than a list typed out beside it. A rule implemented
+and not described fails; a rule described and not implemented fails too — an
+index naming a rule nobody runs is the shape that reads as coverage.
+
+## Gyde is held to its own rules
+
+`npm run verify` emits a scaffold into a temporary directory, runs
+`gyde-design gate` over it through the CLI, and fails unless the recorded
+baseline is **zero**.
+
+The check is on the baseline and not on the exit code, and that distinction is
+the whole of it. A first `gate` on a tree with no ledger RECORDS what it finds
+and exits 1 on purpose; the second run then passes whatever the first recorded.
+So a scaffold shipping ten violations gates green — correctly, for a customer
+adopting Gyde, and uselessly as a check on ourselves.
+
+That is not hypothetical. The scaffold emitted on 2026-09-15 carried ten
+`optional-prop` findings across all five seed components, and the consuming
+repository found them, not us. The emitted set now declares every prop required,
+nullable where absence is a real answer, with the ordinary values in
+`defaults.ts` — exported from the package barrel, because an escape hatch behind
+a deep import into `src/` is one the boundary rules forbid you to use.
+
 ## Rules that go quiet
 
 A rule that matched nothing anywhere is reported as **suspicious**, not clean.
@@ -246,6 +307,13 @@ 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.
 
+For an existing product-owned design system, run `gyde-design guidance .` to
+check whether the generated guide matches its current component exports. Run
+`gyde-design guidance . --write` to refresh the guide, then review the diff.
+This command updates only `.gyde/design-system.md` and refuses to replace a
+handwritten file. It lists component names without guessing their props or
+claiming theme APIs that Gyde has not verified in that product.
+
 ## Not built yet
 
 Build-pipeline wiring for a compiled token layer — moot while the emitted tokens

package/agentdocs.mjs

@@ -122,6 +122,9 @@ export function agentDoc({
    * requirements rather than as facts about the implementation.
    */
   verified = true,
+  // An older Gyde-emitted set may predate the app theme controller. Its
+  // component metadata is verified, but this optional capability is absent.
+  themeChoice = verified,
 } = {}) {
   const closure = verified
     ? `**Never pass \`className\` or \`style\` to a design-system component.** They do not
@@ -184,13 +187,47 @@ 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
+${verified ? `## 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.
 
+` : ""}
+
+${themeChoice ? `## App theme choice
+
+The design-system package supplies \`src/theme-bootstrap.js\` and exports
+\`${systemPackage}/theme-choice\`. The product must wire both into its app shell:
+
+1. Put the **contents** of \`theme-bootstrap.js\` in a synchronous inline script
+   in the document head, before any stylesheet or app script can paint. Use the
+   framework's raw-text import/build facility and the site's CSP nonce or hash.
+   A module script, effect, or hydrated provider is too late for first paint.
+2. Start \`startThemeChoice()\` once in browser app startup, after the document
+   root exists. Keep the returned controller across route changes and call
+   \`stop()\` at app teardown. Use \`setChoice("light" | "dark" | "system")\`
+   for the preference control; subscribe for its selected and resolved state.
+3. When a router replaces the document root or owns the root's \`data-theme\`,
+   call \`reconcile()\` after navigation. The controller also observes root
+   replacement and repairs external attribute changes. Keep local route theme
+   overrides on inner containers so they do not overwrite the global choice.
+
+The storage key is scoped to this design-system package. \`system\` is an
+explicit stored choice that removes \`data-theme\` from the document root and
+lets \`prefers-color-scheme\` decide. Unavailable storage keeps the current tab
+working, without persistence. Changes from another tab and bfcache restoration
+are reconciled by the controller.
+
+**Rendered regression evidence belongs in this app's browser CI.** Test both
+system preferences, stored light and dark on reload before first paint, route
+navigation and root replacement, a change from another tab, and back/forward
+cache restoration. Assert the root attribute, computed colour and
+\`color-scheme\`, and capture screenshots in both palettes. Gyde's static gate
+cannot prove when the head script runs or what a browser actually paints.
+` : ""}
+
 ## The components
 
 ${verified

package/catalogue.mjs

@@ -49,8 +49,16 @@
  */
 export const CATALOGUE_ENTRIES = {
   Button: {
+    defaults: "BUTTON_DEFAULTS",
     purpose: "The one action a view wants, and every lesser action beside it.",
     replaces: ["a styled <button>", "an <a> that looks like a button"],
+    /**
+     * G-127. `onClick` is required-nullable and is NOT in BUTTON_DEFAULTS —
+     * deliberately, because "this button does nothing" should be typed out at
+     * the call site rather than inherited. The catalogue is a call site, so it
+     * types it out.
+     */
+    handlers: ["onClick"],
     states: [
       { label: "accent / filled", props: { tone: "accent", emphasis: "filled", size: "md" }, children: "Save changes" },
       { label: "neutral / outline", props: { tone: "neutral", emphasis: "outline", size: "md" }, children: "Cancel" },
@@ -60,6 +68,7 @@ export const CATALOGUE_ENTRIES = {
     ],
   },
   Text: {
+    defaults: "TEXT_DEFAULTS",
     purpose: "Every piece of prose, at the role it plays rather than the size it is.",
     replaces: ["a <p> with a font-size", "a <span> with a colour"],
     states: [
@@ -71,6 +80,7 @@ export const CATALOGUE_ENTRIES = {
     ],
   },
   Card: {
+    defaults: "CARD_DEFAULTS",
     purpose: "A bordered surface. The only one, which is the point.",
     replaces: ["a div with a border and a radius", "a panel", "a well"],
     states: [
@@ -81,6 +91,7 @@ export const CATALOGUE_ENTRIES = {
     ],
   },
   Checkbox: {
+    defaults: "CHECKBOX_DEFAULTS",
     purpose: "A binary choice that is part of a form.",
     replaces: ["an <input type=checkbox> with a label beside it"],
     controlled: { checked: false },
@@ -92,6 +103,7 @@ export const CATALOGUE_ENTRIES = {
     ],
   },
   Select: {
+    defaults: "SELECT_DEFAULTS",
     purpose: "One of a known set of options.",
     replaces: ["a <select>", "a dropdown built from a button and a list"],
     controlled: { value: "b" },
@@ -138,11 +150,26 @@ const lit = (v) =>
  */
 function exampleJsx(name, state, entry) {
   const props = { ...(entry.controlled ?? {}), ...state.props };
-  const attrs = Object.entries(props).map(([k, v]) => `${k}=${lit(v)}`);
+
+  /**
+   * G-127. The defaults spread comes FIRST, and it is not decoration.
+   *
+   * Every prop on every seed component is required now (G-68), so an example
+   * listing only the props it is demonstrating does not compile. The catalogue
+   * was already in that state before anyone noticed — `onClick` has been
+   * required for longer than this comment, and every emitted Button example
+   * omitted it — because nothing in this repository type-checks what it emits.
+   * It still does not; the gate checks the shape, not the types. So keep this
+   * spread, and if you add a required prop to a component, add it to
+   * `defaults.ts` or to `handlers` below.
+   */
+  const attrs = entry.defaults ? [`{...${entry.defaults}}`] : [];
+  attrs.push(...Object.entries(props).map(([k, v]) => `${k}=${lit(v)}`));
 
   // A controlled component needs a handler. The catalogue holds no state on
   // purpose — what is being reviewed is the rendering, not the interaction.
   if (entry.controlled) attrs.push("onChange={() => {}}");
+  for (const h of entry.handlers ?? []) attrs.push(`${h}={() => {}}`);
 
   const open = `<${name} ${attrs.join(" ")}`;
   return state.children ? `${open}>${state.children}</${name}>` : `${open} />`;
@@ -185,6 +212,10 @@ function entriesSource(components, systemPackage) {
     );
   }
 
+  const defaultsUsed = components
+    .map((name) => CATALOGUE_ENTRIES[name].defaults)
+    .filter(Boolean);
+
   const blocks = components.map((name) => {
     const e = CATALOGUE_ENTRIES[name];
     const states = e.states.map((s) =>
@@ -208,7 +239,7 @@ ${states}
  * component name to \`undefined\` and pass while covering nothing.
  */
 import type { ReactNode } from "react";
-import { ${components.join(", ")} } from "${systemPackage}";
+import { ${[...components, ...defaultsUsed].join(", ")} } from "${systemPackage}";
 
 export type Example = { label: string; node: ReactNode };
 export type Entry = { name: string; purpose: string; replaces: readonly string[]; notes: readonly string[]; examples: readonly Example[] };

package/cli.mjs

@@ -34,7 +34,7 @@ import {
 } from "./boundaries.mjs";
 import { emitTokens, emitSystem, emitConfig, SEED_COMPONENTS, SCAFFOLD_VERSION, NOT_UPGRADEABLE } from "./emit.mjs";
 import { emitCatalogue } from "./catalogue.mjs";
-import { emitAgentDocs } from "./agentdocs.mjs";
+import { agentDoc, emitAgentDocs } from "./agentdocs.mjs";
 import { emitWorkflow } from "./workflow.mjs";
 import { buildManifest, readManifest, writeManifest, applyUpgrade, formatUpgrade, MANIFEST } from "./upgrade.mjs";
 import { exportedComponents, renderableComponents, checkWiring, formatWiring, WIRING } from "./wiring.mjs";
@@ -46,8 +46,9 @@ import { migrationProgress, formatMigration } from "./migration.mjs";
 import { checkStyleX, formatStyleX, checkClosedStyling, formatClosedStyling } from "./stylex.mjs";
 import { blocksAt, formatSchedule, SCHEDULE } from "./enforcement.mjs";
 import { buildUsage, guidance, formatUsage } from "./usage.mjs";
-import { record, gate, formatGate, adopt, LEDGER_NOTE } from "./ratchet.mjs";
+import { record, gate, formatGate, adopt, trim, formatTrim, LEDGER_NOTE } from "./ratchet.mjs";
 import { loadRules } from "./rules.mjs";
+import { validateScopeShape, checkScopeAgreement, formatScope } from "./scope.mjs";
 
 /**
  * The single source of what would be written.
@@ -197,13 +198,30 @@ const PRIMITIVES = [
 function readConfig(root) {
   const path = join(root, "gyde.config.json");
   if (!existsSync(path)) return { present: false, design: {} };
+  let json;
   try {
-    const json = JSON.parse(readFileSync(path, "utf8"));
-    return { present: true, design: json.design || {} };
+    json = JSON.parse(readFileSync(path, "utf8"));
   } catch (e) {
     throw new Error(`gyde.config.json exists but could not be parsed: ${e.message}\n` +
       "Refusing to continue on a default — a misread config is how a project ends up measured against a scope nobody chose.");
   }
+  const design = json.design || {};
+
+  /**
+   * G-123. The schema half, applied at the one place the config is read.
+   *
+   * Here rather than in `gate` alone because a malformed scope is wrong on
+   * every command: `init` would scaffold a package nobody can import, and the
+   * cheapest place to find that out is before anything is written. This needs
+   * only the string, so it costs nothing and works on an empty repository.
+   */
+  const shape = validateScopeShape(design.scope);
+  if (!shape.ok) {
+    throw new Error(`gyde.config.json: ${shape.error}\n` +
+      "A scope names the packages the emitted code imports, so a wrong one produces imports that resolve to nothing.");
+  }
+
+  return { present: true, design };
 }
 
 /** What the repository already uses, read from manifests rather than assumed. */
@@ -538,6 +556,42 @@ function cmdUpgrade(root, config, { dryRun }) {
   return result.conflicts.length ? 1 : 0;
 }
 
+/** Refresh the generated component guide from a product's current exports. */
+function cmdGuidance(root, config, { write }) {
+  const design = config.design || {};
+  const systemPath = design.systemPath || "packages/design-system";
+  const components = renderableComponents(root, systemPath);
+  if (!components) {
+    console.error(`cannot read renderable components from ${systemPath}; guidance was not changed`);
+    return 1;
+  }
+  const systemPackage = design.systemPackage || systemPackageName(root, systemPath);
+  if (!systemPackage) {
+    console.error(`cannot read a package name from ${systemPath}; guidance was not changed`);
+    return 1;
+  }
+
+  const path = join(root, ".gyde", "design-system.md");
+  const next = agentDoc({ components, systemPackage, verified: false });
+  const current = existsSync(path) ? readFileSync(path, "utf8") : null;
+  if (current === next) {
+    console.log("component guidance matches the current design-system exports");
+    return 0;
+  }
+  if (!write) {
+    console.error("component guidance is stale; run `gyde-design guidance . --write` and review the diff");
+    return 1;
+  }
+  if (current !== null && !current.startsWith("<!-- GENERATED BY GYDE")) {
+    console.error("refusing to overwrite a component guide Gyde did not generate");
+    return 1;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, next);
+  console.log("wrote .gyde/design-system.md from the current design-system exports; review the diff");
+  return 0;
+}
+
 /**
  * The gate.
  *
@@ -596,12 +650,57 @@ function writeEvidence(root, result, { ok, why, clientBoundary = null, enforceme
   }, null, 2) + "\n");
 }
 
-function cmdGate(root, config) {
+/** The design system package's own `name`, read from disk. Null when there is no package there. */
+function systemPackageName(root, systemPath) {
+  try {
+    return JSON.parse(readFileSync(join(root, systemPath, "package.json"), "utf8")).name ?? null;
+  } catch { return null; }
+}
+
+function cmdGate(root, config, { recordNewRules = false, trimLedger = false } = {}) {
   const design = config.design || {};
   const ledgerPath = join(root, "gyde-allowance.json");
-  const roots = exportedComponents(root, design.systemPath || "packages/design-system");
+  const systemPath = design.systemPath || "packages/design-system";
+
+  /**
+   * G-123. Before anything is measured or recorded.
+   *
+   * First because a disagreeing scope invalidates the run rather than adding a
+   * finding to it: the emitted code imports packages that are not there, and
+   * recording a baseline underneath that would commit a number taken against a
+   * repository Gyde has misread. It is also the cheapest failure available,
+   * which is the order `verify` uses and this command should too.
+   *
+   * The workspace is discovered once here and shared with the checks below.
+   * Two `discover` calls in one run can disagree about which packages exist,
+   * and this file has done that before.
+   */
+  const ws = discover(root);
+  const scopeCheck = checkScopeAgreement({
+    declared: design.scope,
+    packages: ws.packages,
+    systemPath,
+    systemPackageName: systemPackageName(root, systemPath),
+  });
+  if (!scopeCheck.ok) {
+    console.error(formatScope(scopeCheck));
+    writeEvidence(root, null, { ok: false, why: `design.scope does not agree with the repository: ${scopeCheck.why}` });
+    return 1;
+  }
+
+  const roots = exportedComponents(root, systemPath);
   const result = scan(root, { config: { ...design, componentRoots: roots ? new Set(roots) : null } });
 
+  // G-113. `--trim` on a repository with no ledger must NOT fall through to the
+  // baseline-recording path below. That path writes a ledger from scratch, which
+  // is the largest possible add, and reaching it by typing the word "trim" is
+  // exactly the confusion this command exists to remove.
+  if (trimLedger && !existsSync(ledgerPath)) {
+    console.error("no gyde-allowance.json here — there is nothing to trim.");
+    console.error("`gate` records a baseline when none exists; `gate --trim` never creates one.");
+    return 1;
+  }
+
   if (!existsSync(ledgerPath)) {
     const led = record(result.findings, {
       recorded: process.env.GYDE_DATE || null,
@@ -624,9 +723,42 @@ function cmdGate(root, config) {
     return 1;
   }
 
+  /**
+   * G-113. The only command that takes a shortening, and it does nothing else.
+   *
+   * It runs before the gate's verdict and returns, because it is not a
+   * judgement. Both other writers end with "This run recorded a baseline rather
+   * than judging one. It is not a pass." and return non-zero; this keeps that,
+   * for the same reason. `gate --trim` wired into CI would otherwise be a gate
+   * that always passes, which is the failure mode this whole file is arranged
+   * against. Judging is what plain `gate` is for, and it is one command away.
+   */
+  if (trimLedger) {
+    const t = trim(ledger, result.findings);
+    console.log(formatTrim(t));
+    if (!t.ok) {
+      writeEvidence(root, result, { ok: false, why: `refused to trim: ${t.refusals.length} entry(ies) would be added or raised` });
+      return 1;
+    }
+    writeFileSync(ledgerPath, JSON.stringify(t.ledger, null, 2) + "\n");
+    console.log("");
+    console.log("wrote gyde-allowance.json — review the diff before committing it.");
+    console.log("");
+    console.log("This run rewrote the ledger rather than judging one. It is not a pass.");
+    console.log("Run `gyde design gate .` to judge the tree.");
+    writeEvidence(root, result, { ok: false, why: `trimmed the ledger ${t.before} → ${t.after}; nothing was judged` });
+    return 1;
+  }
+
   const verdict = gate([{ name: "design-system", findings: result.findings, ledger }]);
   console.log(formatGate(verdict));
 
+  // G-123. Printed on the passing path too. A check that is only visible when
+  // it fails is one nobody can tell ran, which is the same defect as the key
+  // that guarded nothing.
+  console.log("");
+  console.log(formatScope(scopeCheck));
+
   // G-99. No gate and no verdict change — the ratchet was already correct for a
   // migration. This subtracts two numbers the ledger has carried since G-52, so
   // that "not started" and "not visible from here" stop reading the same.
@@ -636,22 +768,43 @@ function cmdGate(root, config) {
     console.log(formatMigration(migrationProgress(result.findings, ledger, { migrating })));
   }
 
-  // G-68. Written, not just reported. An adoption that stays in stdout is
-  // adopted again on the next run, so the rule reports forever and ratchets
-  // never — which is the to-do-list-nobody-reads failure LEDGER_NOTE names.
-  if (verdict.adopted.length) {
-    writeFileSync(ledgerPath, JSON.stringify(
-      adopt(ledger, verdict.adopted, { rules: result.rulesRun }), null, 2) + "\n");
+  /**
+   * G-108. `gate` does not write the ledger. It reads one and judges against it.
+   *
+   * G-68 wrote it whenever a rule was adopted, which made the gate's own
+   * execution a way for a ledger to grow: running it on a laptop against a
+   * consumer whose baseline predated `optional-prop` would have added 80
+   * entries, unasked. "A ledger may only ever get shorter" cannot survive a
+   * command that lengthens one as a side effect of measuring.
+   *
+   * The write now happens only when somebody typed the words, and it still
+   * exits non-zero — it recorded a baseline for these rules, it did not judge
+   * one, and that distinction is the same one the no-ledger path above makes.
+   */
+  if (recordNewRules && verdict.newRules.length) {
+    const before = ledger.total ?? 0;
+    const entries = verdict.failures.filter((f) => f.kind === "unrecorded-rule");
+    const next = adopt(ledger, entries, { rules: result.rulesRun });
+    writeFileSync(ledgerPath, JSON.stringify(next, null, 2) + "\n");
+    console.log("");
+    console.log(`recorded ${entries.length} entry(ies) for ${verdict.newRules.length} rule(s) not previously named: ${verdict.newRules.join(", ")}`);
+    console.log(`gyde-allowance.json: ${before} → ${next.total} findings. This ledger got LONGER, which is the`);
+    console.log("one case where that is allowed — a new rule finds drift that was always there.");
+    console.log("Review the diff before committing it; it is a decision, not a formality.");
+    console.log("");
+    console.log("This run recorded a baseline rather than judging one. It is not a pass.");
+    writeEvidence(root, result, { ok: false, why: `recorded a baseline for ${verdict.newRules.length} new rule(s); nothing was judged` });
+    return 1;
   }
 
   // G-67. Deliberately NOT a ledger finding. A crossing is a runtime defect
   // rather than style debt, so allowancing one would record "this renders
   // undefined props, and that is fine for now" as a committed number. It is
   // gated on the product's own template version instead — see BLOCKS_FROM.
-  // Discovered once and shared by every check below. Calling `discover` per
-  // check re-walks the workspace and, more importantly, lets two checks in the
-  // same run disagree about which packages exist.
-  const ws = discover(root);
+  // The workspace was discovered once at the top of this command and is shared
+  // by every check below. Calling `discover` per check re-walks the workspace
+  // and, more importantly, lets two checks in the same run disagree about which
+  // packages exist.
   const cb = checkClientBoundary(root, { packages: ws.packages });
   const cbBlocks = clientBoundaryBlocks(readManifest(root)?.version);
   if (cb.crossings.length || cb.unresolved.length) {
@@ -714,15 +867,27 @@ function cmdGate(root, config) {
 }
 
 function main(argv) {
-  const [cmd, pathArg] = argv;
+  const [cmd] = argv;
+  // G-108. The path is the first non-flag argument, not argv[1]. `gate
+  // --record-new-rules` would otherwise resolve "--record-new-rules" as a
+  // directory and die with "no such path" — a usage error reported as a missing
+  // repository, which is the least helpful sentence available.
+  const pathArg = argv.slice(1).find((a) => !a.startsWith("-"));
   if (!cmd || ["-h", "--help", "help"].includes(cmd)) {
-    console.log("gyde design <scan|plan|init|gate|tokens> [path]");
+    console.log("gyde design <scan|plan|init|gate|upgrade|guidance|tokens> [path]");
     console.log("  scan    measure a repository as it is");
     console.log("  plan    say what scaffolding would be emitted; write nothing");
     console.log("  init    write exactly what plan described; never overwrites");
     console.log("  gate    fail on anything new since the committed ledger");
+    console.log("          (--record-new-rules to record a rule the ledger does not name");
+    console.log("           as existing debt; writes the ledger and still exits non-zero)");
+    console.log("          (--trim to remove entries the scan no longer produces and lower");
+    console.log("           counts that have fallen; never adds, never raises, refuses if it");
+    console.log("           would; writes the ledger and still exits non-zero)");
     console.log("  upgrade take a new template version; never merges a conflict");
     console.log("          (--dry-run to see the decisions and write nothing)");
+    console.log("  guidance check the generated component guide against current exports");
+    console.log("          (--write to refresh only that guide; never changes provenance)");
     console.log("  tokens  print the generated stylesheet for the seed dictionary");
     return 0;
   }
@@ -740,8 +905,12 @@ function main(argv) {
   if (cmd === "scan") return cmdScan(root, config);
   if (cmd === "plan") return cmdPlan(root, config);
   if (cmd === "init") return cmdInit(root, config);
-  if (cmd === "gate") return cmdGate(root, config);
+  if (cmd === "gate") return cmdGate(root, config, {
+    recordNewRules: argv.includes("--record-new-rules"),
+    trimLedger: argv.includes("--trim"),
+  });
   if (cmd === "upgrade") return cmdUpgrade(root, config, { dryRun: argv.includes("--dry-run") });
+  if (cmd === "guidance") return cmdGuidance(root, config, { write: argv.includes("--write") });
   console.error(`unknown command: ${cmd}`);
   return 1;
 }