@ggui-ai/ui-gen 0.23.0 → 0.24.0

package/src/adapters/generation-dispatch.ts

@@ -33,11 +33,15 @@ import { buildSystemPrompt as buildSystemPromptWithFunnel } from "../harness/run
 // predicate against the full registry and passes the filtered result.
 import { REGISTRY as AXIS_CHECK_REGISTRY } from "../evaluation/axis-checks/registry.js";
 import { matches as axisCheckMatches } from "../evaluation/types-public.js";
-// Runtime-render default. The `createHarness` constructor accepts an
-// optional runtimeRender; this callsite injects
-// `DEFAULT_RUNTIME_RENDER_CHECK` so production keeps the happy-dom-
-// backed contract-wiring verification step.
+// Runtime-render check. The `createHarness` constructor accepts an
+// optional runtimeRender; this callsite wires the caller's instance
+// (`params.runtimeRender`) or, absent one, `DEFAULT_RUNTIME_RENDER_CHECK`,
+// so production keeps the happy-dom-backed contract-wiring verification
+// step. The dispatch never BUILDS a check: the instance carries the
+// concurrency cap, so its lifetime must be the caller's (one per
+// generator), never one per generation.
 import { DEFAULT_RUNTIME_RENDER_CHECK } from "../harness/check/runtime-render/adapter.js";
+import type { RuntimeRenderCheck } from "../harness/types-public.js";
 import { warmupRuntimeRenderProbe } from "../harness/check/runtime-render/index.js";
 import { assembleGenerationResult } from "../harness/coding/assemble-result.js";
 import {
@@ -54,10 +58,7 @@ import type {
 import type { ProviderName, ToolDefinition } from "./types.js";
 import type { QualityConfig } from "../evaluation/types-public.js";
 import type { AgentConfig } from "../harness/llm-router.js";
-import {
-  type GadgetDescriptor,
-  type JsonObject,
-} from "@ggui-ai/protocol";
+import { type GadgetDescriptor, type JsonObject } from "@ggui-ai/protocol";
 import { canvasForRendering, type CanvasClass, type DesignMode } from "../design-mode.js";
 import type { GenerationProfileInput } from "../boilerplate/styling-profile.js";
 
@@ -118,20 +119,38 @@ export interface GenerationDispatchParams {
    */
   fixtureProps?: JsonObject;
   /**
-   * Whether to wire `DEFAULT_RUNTIME_RENDER_CHECK` into the harness's
-   * check leg. When `true` (default), the probe runs every coding turn
-   * and feeds wiring-check failures back to the coding agent — useful
-   * for quality gating but ~3-5s per call adds wall-clock per turn.
+   * Whether to wire the runtime-render check (`runtimeRender` when given,
+   * else `DEFAULT_RUNTIME_RENDER_CHECK`) into the harness's check leg.
+   * When `true` (default), the runtime-render probe runs ONCE
+   * at the exit decision, after the coding turns, in an isolated
+   * subprocess — never on the per-turn hot path. Without an `evaluation`
+   * config that round is observe + one repair turn (ggui#1380): a
+   * recoverable render crash buys exactly one repair turn and one
+   * re-probe, then the generation serves what it has; a probe that timed
+   * out, could not run, or had nothing to probe never blocks and never
+   * repairs. With an `evaluation` config the probe is the evaluation
+   * round's exit gate. Its status and timing land on
+   * `evalResult.runtimeProbe` (and on the generation's metadata through
+   * `createUiGenerator`).
    *
-   * When `false`, the harness omits runtime-render from the in-loop
-   * check pipeline. Cloud production runs with this off (per the
-   * migration plan — probe was never in the production hot path).
-   * Bench callers can run the probe externally as a final post-gen
-   * check to get pass/fail visibility without slowing the loop.
+   * When `false`, the harness omits runtime-render entirely: no probe
+   * round runs, and a caller can run the probe externally as a final
+   * post-generation check instead.
    *
    * Default: `true`.
    */
   enableRuntimeRender?: boolean;
+  /**
+   * The runtime-render check to wire (ggui#1380) — built by the CALLER with
+   * `createRuntimeRenderCheck(config)` and kept for the caller's lifetime,
+   * because the check instance owns the probe's concurrency cap: one
+   * instance per generator bounds the workers a serving deployment has
+   * live at once; one per dispatch would give every generation its own
+   * free slots and bound nothing. Absent ⇒ `DEFAULT_RUNTIME_RENDER_CHECK`
+   * (the evaluation lane's bounds, no concurrency cap). Only read when
+   * `enableRuntimeRender` is on.
+   */
+  runtimeRender?: RuntimeRenderCheck;
   /**
    * Operator-registered gadget catalog forwarded to the
    * code-gen system prompt's `clientCapabilities — registered
@@ -200,7 +219,9 @@ export interface GenerationDispatchParams {
  * Map ProviderName ('claude' | 'openai' | 'google') to AgentConfig provider ('anthropic' | 'openai' | 'google').
  * The LLM router uses 'anthropic' while the rest of the codebase uses 'claude'.
  */
-function mapProviderForLLMRouter(provider: ProviderName): "anthropic" | "openai" | "google" | "openrouter" {
+function mapProviderForLLMRouter(
+  provider: ProviderName
+): "anthropic" | "openai" | "google" | "openrouter" {
   return provider === "claude" ? "anthropic" : provider;
 }
 
@@ -209,7 +230,7 @@ function mapProviderForLLMRouter(provider: ProviderName): "anthropic" | "openai"
  * provider-agnostic.
  */
 export async function dispatchGeneration(
-  params: GenerationDispatchParams,
+  params: GenerationDispatchParams
 ): Promise<GenerationResult> {
   // NOTE: userPrompt arrives already enriched with rendering context + contract
   // (including examples) from the caller (runner.ts / generator.ts).
@@ -294,17 +315,13 @@ export async function dispatchGeneration(
     // from '<package>'` lines for thin contract refs. The closure
     // capture below (systemPromptBuilder) wires the SAME catalog
     // into the HOW leg.
-    ...(params.appGadgets !== undefined
-      ? { appGadgets: params.appGadgets }
-      : {}),
+    ...(params.appGadgets !== undefined ? { appGadgets: params.appGadgets } : {}),
     // Forward the third-party wrapper `.d.ts` map so
     // `WhatLeg.gadgetTypes` reaches the coding-agent's typecheck
     // overlay (autoCommit → runTier0Checks → typecheck). The
     // systemPromptBuilder closure below also captures `gadgetTypes`
     // from `params` directly for the prompt `Type:` lines.
-    ...(params.gadgetTypes !== undefined
-      ? { gadgetTypes: params.gadgetTypes }
-      : {}),
+    ...(params.gadgetTypes !== undefined ? { gadgetTypes: params.gadgetTypes } : {}),
     // Design mode + canvas — the harness carries them to every leg.
     ...(params.designMode !== undefined ? { designMode: params.designMode } : {}),
     // ggui#1117 — the canvas is ALWAYS carried: a stated one, else the class
@@ -334,7 +351,15 @@ export async function dispatchGeneration(
     // prompt's gadget catalog renders a `Type:` line per third-party
     // gadget (the LLM sees a wrapper's real call shape it otherwise
     // can't know).
-    systemPromptBuilder: ({ userRequest, shellType, screen, axisDelta, designMode, canvas, profile }) =>
+    systemPromptBuilder: ({
+      userRequest,
+      shellType,
+      screen,
+      axisDelta,
+      designMode,
+      canvas,
+      profile,
+    }) =>
       buildSystemPromptWithFunnel(
         userRequest,
         shellType,
@@ -344,29 +369,30 @@ export async function dispatchGeneration(
         params.gadgetTypes,
         designMode,
         canvas,
-        profile,
+        profile
       ),
     // Pre-filtered axis-check registry. The `matches()` predicate
     // selects the checks relevant to this generation's axis vector.
     axisChecks: AXIS_CHECK_REGISTRY.filter((check) =>
-      axisCheckMatches(classification.vector, check),
+      axisCheckMatches(classification.vector, check)
     ),
-    // The default runtime-render check. Heavy deps (happy-dom + wire +
-    // design) stay on the dispatch side of the boundary; the skeleton
-    // createHarness defaults this to undefined.
+    // The runtime-render check, built under the caller's probe config.
+    // Heavy deps (happy-dom + wire + design) stay on the dispatch side of
+    // the boundary; the skeleton createHarness defaults this to undefined.
     //
     // Gated behind `enableRuntimeRender` (default true) so
     // benchmark/dev callers can opt out of in-loop probe execution and
     // run the probe externally as a final post-generation check.
-    runtimeRender: (params.enableRuntimeRender ?? true)
-      ? DEFAULT_RUNTIME_RENDER_CHECK
-      : undefined,
+    runtimeRender:
+      (params.enableRuntimeRender ?? true)
+        ? (params.runtimeRender ?? DEFAULT_RUNTIME_RENDER_CHECK)
+        : undefined,
   });
   console.log(
-    `[harness] id=${harness.id} name=${harness.name} workflow=${harness.process.workflow.name} overrides=${harness.meta.overrides.join(",") || "none"}`,
+    `[harness] id=${harness.id} name=${harness.name} workflow=${harness.process.workflow.name} overrides=${harness.meta.overrides.join(",") || "none"}`
   );
   console.log(
-    `[simple] axis-vector: ${JSON.stringify(classification.vector)} risk=${classification.riskTier}`,
+    `[simple] axis-vector: ${JSON.stringify(classification.vector)} risk=${classification.riskTier}`
   );
 
   // ── Guard: staged workflow is not wired on the dispatch path. ──
@@ -392,7 +418,7 @@ export async function dispatchGeneration(
         `This is a misconfiguration (probably pickProcessMode returning WORKFLOWS.staged). ` +
         `For staged-like behaviour, set process.mode="staged" + workflow.name="single_pass" instead — the A1 ` +
         `scaffold→fill phase machine lives inside the generate runner and fires without the workflow topology. ` +
-        `See ralph #3 report (2026-04-14) for the full rationale.`,
+        `See ralph #3 report (2026-04-14) for the full rationale.`
     );
   }
 
@@ -409,29 +435,58 @@ export async function dispatchGeneration(
   // resolveRunPolicyForProfile falls through to the identity
   // resolveRunPolicy — byte-identical to the default behavior.
   const { resolveRunPolicyForProfile } = await import("../harness/policy.js");
-  const resolvedPolicy = resolveRunPolicyForProfile(
-    process.env.GGUI_POLICY_PROFILE,
-    harness,
-    { provider: routerProvider, modelId: resolvedModel },
-  );
+  const resolvedPolicy = resolveRunPolicyForProfile(process.env.GGUI_POLICY_PROFILE, harness, {
+    provider: routerProvider,
+    modelId: resolvedModel,
+  });
 
-  // ── Axis-keyed primitives doc slice ──
-  // When the resolved policy flips to axis-keyed, rebuild the first-turn
-  // system prompt with a sliced PRIMITIVES_DOCUMENTATION derived from the
-  // classification. The slice typically cuts the system prompt by ~80 KB
-  // (~20K tokens). Surface awareness is preserved — the name-only primitive
-  // catalog already lives in the system prompt above the sliced block.
-  // Always logs `[simple] primitive-doc-bytes` telemetry so both modes
-  // are auditable post-hoc.
+  // ── The primitives reference the first-turn prompt carries ──
+  // The system prompt embeds PRIMITIVES_DOCUMENTATION (markdown) verbatim.
+  // Three policy knobs decide what is SENT in its place, composed in this
+  // order (ggui#1324, speed/002 — the slice applies to the format in force;
+  // slicing the markdown before the TS swap sent a sliced markdown doc about
+  // the size of the full TS doc, which speed/001 measured as a trim):
+  //   1. primitiveDocFormat: "markdown" (the embedded doc) or "ts" (its
+  //      TypeScript-interface form, ~55% smaller, same information);
+  //   2. primitiveDocSlice: "full", or an axis-keyed allowlist from the
+  //      classification ("axis-keyed", or "axis-keyed+contract" which adds the
+  //      inputs the contract implies) applied to THAT format's doc;
+  //   3. primitiveIndex: a name-only index that replaces whatever is left
+  //      (tool-driven docs; wins when on).
+  // Every cell logs `[simple] primitive-doc-bytes … mode=…` (the slice) and
+  // `[simple] system-prompt-bytes … doc-format=… doc-bytes=…` (what is sent),
+  // so a prompt-size claim is auditable from the log, not inferred.
   let systemPromptOverride: string | undefined;
   {
     const { PRIMITIVES_DOCUMENTATION } = await import("../validation/index.js");
     const fullBytes = Buffer.byteLength(PRIMITIVES_DOCUMENTATION, "utf8");
+    const docFormat = resolvedPolicy.context.primitiveDocFormat ?? "markdown";
+    const indexMode = resolvedPolicy.context.primitiveIndex ?? "off";
     const mode = resolvedPolicy.context.primitiveDocSlice ?? "full";
-    if (mode === "axis-keyed") {
-      const { computePrimitiveAllowlist, slicePrimitiveDocumentation } =
-        await import("../harness/primitive-slice.js");
+
+    let doc = PRIMITIVES_DOCUMENTATION;
+    if (docFormat === "ts" && indexMode === "off") {
+      const { PRIMITIVES_DOCUMENTATION_TS } = await import("../tools/get-primitives-ts.js");
+      doc = PRIMITIVES_DOCUMENTATION_TS;
+      const tsBytes = Buffer.byteLength(doc, "utf8");
+      console.log(
+        `[simple] primitive-doc-ts-bytes=${tsBytes} baseline=${fullBytes} drop=${((1 - tsBytes / fullBytes) * 100).toFixed(1)}%`
+      );
+    }
+    const formatBytes = Buffer.byteLength(doc, "utf8");
+
+    if (mode === "axis-keyed" || mode === "axis-keyed+contract") {
+      const {
+        computePrimitiveAllowlist,
+        computeContractPrimitives,
+        slicePrimitiveDocumentation,
+        slicePrimitiveDocumentationTs,
+      } = await import("../harness/primitive-slice.js");
       let allowlist = computePrimitiveAllowlist(classification);
+      if (mode === "axis-keyed+contract") {
+        const fromContract = computeContractPrimitives(effectiveContract);
+        allowlist = [...new Set([...allowlist, ...fromContract])].sort();
+      }
       // Apply policy-driven excludes — some policy profiles drop
       // near-synonym layout primitives (e.g. Row/Box/Spacer).
       const excludes = resolvedPolicy.context.primitiveDocExcludes ?? [];
@@ -439,61 +494,41 @@ export async function dispatchGeneration(
         const excludeSet = new Set(excludes);
         allowlist = allowlist.filter((p) => !excludeSet.has(p));
       }
-      const sliced = slicePrimitiveDocumentation(
-        PRIMITIVES_DOCUMENTATION,
-        allowlist,
-      );
-      const slicedBytes = Buffer.byteLength(sliced, "utf8");
+      doc =
+        docFormat === "ts" && indexMode === "off"
+          ? slicePrimitiveDocumentationTs(doc, allowlist)
+          : slicePrimitiveDocumentation(doc, allowlist);
+      const slicedBytes = Buffer.byteLength(doc, "utf8");
       const excludeTag = excludes.length ? ` excludes=${excludes.join(",")}` : "";
       console.log(
-        `[simple] primitive-doc-bytes=${slicedBytes} mode=axis-keyed baseline=${fullBytes} drop=${((1 - slicedBytes / fullBytes) * 100).toFixed(1)}% allowlist=${allowlist.length}/${allowlist.join(",")}${excludeTag}`,
-      );
-      systemPromptOverride = harness.how.systemPrompt.replace(
-        PRIMITIVES_DOCUMENTATION,
-        sliced,
+        `[simple] primitive-doc-bytes=${slicedBytes} mode=${mode} baseline=${formatBytes} drop=${((1 - slicedBytes / formatBytes) * 100).toFixed(1)}% allowlist=${allowlist.length}/${allowlist.join(",")}${excludeTag}`
       );
     } else {
       console.log(
-        `[simple] primitive-doc-bytes=${fullBytes} mode=full baseline=${fullBytes} drop=0.0%`,
+        `[simple] primitive-doc-bytes=${formatBytes} mode=full baseline=${formatBytes} drop=0.0%`
       );
     }
 
     // ── Tool-driven primitive docs ──
-    // Layers on top of axis-keyed slicing — if slicing already trimmed
-    // the doc, the index replaces whatever's left. When both are
-    // active, the index wins (it is a more aggressive cut). The two are
-    // mutually exclusive in practice via profile selection; this
-    // ordering just defines the tiebreak.
-    const indexMode = resolvedPolicy.context.primitiveIndex ?? "off";
+    // A name-only index replaces whatever is left (it is the more
+    // aggressive cut). The two are mutually exclusive in practice via
+    // profile selection; this ordering just defines the tiebreak.
     if (indexMode !== "off") {
       const { buildPrimitiveIndex } = await import("../harness/primitive-index.js");
-      const index = buildPrimitiveIndex(PRIMITIVES_DOCUMENTATION, indexMode);
-      const indexBytes = Buffer.byteLength(index, "utf8");
+      doc = buildPrimitiveIndex(PRIMITIVES_DOCUMENTATION, indexMode);
+      const indexBytes = Buffer.byteLength(doc, "utf8");
       console.log(
-        `[simple] primitive-index-bytes=${indexBytes} mode=${indexMode} baseline=${fullBytes} drop=${((1 - indexBytes / fullBytes) * 100).toFixed(1)}%`,
-      );
-      systemPromptOverride = (systemPromptOverride ?? harness.how.systemPrompt).replace(
-        PRIMITIVES_DOCUMENTATION,
-        index,
+        `[simple] primitive-index-bytes=${indexBytes} mode=${indexMode} baseline=${fullBytes} drop=${((1 - indexBytes / fullBytes) * 100).toFixed(1)}%`
       );
     }
 
-    // ── TypeScript-interface processed doc ──
-    // Replace the markdown-table doc with the TS-interface format
-    // version (~55% smaller, same info). Mutually exclusive with index
-    // modes.
-    const docFormat = resolvedPolicy.context.primitiveDocFormat ?? "markdown";
-    if (docFormat === "ts" && indexMode === "off") {
-      const { PRIMITIVES_DOCUMENTATION_TS } = await import("../tools/get-primitives-ts.js");
-      const tsBytes = Buffer.byteLength(PRIMITIVES_DOCUMENTATION_TS, "utf8");
-      console.log(
-        `[simple] primitive-doc-ts-bytes=${tsBytes} baseline=${fullBytes} drop=${((1 - tsBytes / fullBytes) * 100).toFixed(1)}%`,
-      );
-      systemPromptOverride = (systemPromptOverride ?? harness.how.systemPrompt).replace(
-        PRIMITIVES_DOCUMENTATION,
-        PRIMITIVES_DOCUMENTATION_TS,
-      );
+    if (doc !== PRIMITIVES_DOCUMENTATION) {
+      systemPromptOverride = harness.how.systemPrompt.replace(PRIMITIVES_DOCUMENTATION, doc);
     }
+    const sentPrompt = systemPromptOverride ?? harness.how.systemPrompt;
+    console.log(
+      `[simple] system-prompt-bytes=${Buffer.byteLength(sentPrompt, "utf8")} doc-format=${docFormat === "ts" && indexMode === "off" ? "ts" : docFormat} doc-bytes=${Buffer.byteLength(doc, "utf8")} mode=${indexMode !== "off" ? `index:${indexMode}` : mode}`
+    );
 
     // ── plan→impl pipeline augmentation ──
     // Append a 2-phase flow description when planFirstTurn is active so
@@ -548,7 +583,7 @@ export async function dispatchGeneration(
     console.error(
       `[dispatch] runHarness terminated: ${runResult.reason} ` +
         `(source=${runResult.finalSource ? runResult.finalSource.length + "B" : "null"}, ` +
-        `compiled=${runResult.finalCompiled ? runResult.finalCompiled.length + "B" : "null"})`,
+        `compiled=${runResult.finalCompiled ? runResult.finalCompiled.length + "B" : "null"})`
     );
   }
 
@@ -560,7 +595,11 @@ export async function dispatchGeneration(
   // `assembleGenerationResult` is async — the spread below must see the
   // RESOLVED result, never the promise (a spread promise is `{}`: every
   // consumer downstream lost `compiledCode` / `tokens` on 2026-09-09).
-  const result: GenerationResult = await assembleGenerationResult({ session, telemetry, source: finalSource });
+  const result: GenerationResult = await assembleGenerationResult({
+    session,
+    telemetry,
+    source: finalSource,
+  });
   // Record the arm this generation ran under (bench reports read it per
   // cell). The canvas is the one the free prompt stated: explicit when
   // passed, else the same shell × screen derivation the prompt used.
@@ -579,11 +618,13 @@ export async function dispatchGeneration(
  */
 function withArmRecord(
   result: GenerationResult,
-  params: Pick<GenerationDispatchParams, "designMode" | "canvas" | "shellType" | "screen">,
+  params: Pick<GenerationDispatchParams, "designMode" | "canvas" | "shellType" | "screen">
 ): GenerationResult {
   const recordedCanvas: CanvasClass | undefined =
     params.canvas ??
-    (params.designMode === "free" ? canvasForRendering(params.shellType, params.screen) : undefined);
+    (params.designMode === "free"
+      ? canvasForRendering(params.shellType, params.screen)
+      : undefined);
   return {
     ...result,
     ...(params.designMode !== undefined ? { designMode: params.designMode } : {}),

package/src/check/run-tier0.ts

@@ -295,6 +295,85 @@ function detectCertainDoubleWiredActions(
  * fallback ban it paints nothing.
  */
 const MANIFEST_TOKENS: ReadonlySet<string> = new Set(consumedTokenManifest);
+
+/**
+ * Role names retired by ggui#987 that generated code still invents, each
+ * with the manifest name that replaced it (ggui#1325). The self-check names
+ * the successor, so the model does not spend a turn guessing another name.
+ */
+const RETIRED_TOKEN_SUCCESSORS: ReadonlyMap<string, string> = new Map([
+  ['--ggui-color-surface', '--ggui-color-container'],
+  ['--ggui-color-onSurface', '--ggui-color-onContainer'],
+  ['--ggui-color-surfaceVariant', '--ggui-color-sunken'],
+  ['--ggui-color-onSurfaceVariant', '--ggui-color-onSunken'],
+]);
+
+/**
+ * The manifest names nearest an invented one (ggui#1325): a retired role's
+ * successor when there is one; otherwise the names sharing the invented
+ * name's longest family prefix at a segment boundary
+ * (`--ggui-motion-duration-normal` → fast, base, slow); otherwise the names
+ * sharing any of its segments of four letters or more
+ * (`--ggui-duration-slow` → the motion durations). Empty when nothing is
+ * near, so the hint falls back to the manifest's general shape.
+ */
+export function suggestManifestTokens(name: string): readonly string[] {
+  const successor = RETIRED_TOKEN_SUCCESSORS.get(name);
+  if (successor !== undefined) return [successor];
+  // Family prefixes at the name's own segment boundaries, longest first: for
+  // `--ggui-motion-duration-normal` that is `--ggui-motion-duration-`, then
+  // `--ggui-motion-`; an empty-suffix name such as `--ggui-color-` (the model
+  // stopped mid-name) is its own longest prefix, so it gets the colour family.
+  const segments = name.split('-').filter((segment) => segment.length > 0);
+  const own = name.endsWith('-') ? segments.length : segments.length - 1;
+  for (let n = own; n >= 2; n--) {
+    const prefix = `--${segments.slice(0, n).join('-')}-`;
+    const family = consumedTokenManifest.filter((token) => token.startsWith(prefix));
+    if (family.length > 0) return wordHitsFirst(name, rolesFirst(family));
+  }
+  const words = new Set(
+    segments
+      .slice(1)
+      .filter((segment) => segment.length >= 4)
+      .map((segment) => segment.toLowerCase()),
+  );
+  return rolesFirst(
+    consumedTokenManifest.filter((token) =>
+      token.split('-').some((segment) => words.has(segment.toLowerCase())),
+    ),
+  );
+}
+
+/**
+ * Names that carry the invented name's last word lead the list: `--ggui-color-inverse` names `inverseLink` and
+ * `inverseOutline` before the rest of the colour family, since those are what the model was reaching for. The word is
+ * the last segment when it has four letters or more; shorter or empty suffixes leave the order alone.
+ */
+function wordHitsFirst(name: string, family: readonly string[]): readonly string[] {
+  const word = name.slice(name.lastIndexOf('-') + 1).toLowerCase();
+  if (word.length < 4) return family;
+  const hit = (token: string): boolean => token.slice(token.lastIndexOf('-') + 1).toLowerCase().includes(word);
+  return [...family.filter(hit), ...family.filter((token) => !hit(token))];
+}
+
+/** Role names (a non-numeric last segment) before ramp steps, so the taught vocabulary leads a long family. */
+function rolesFirst(tokens: readonly string[]): readonly string[] {
+  const isRole = (token: string): boolean => !/^\d+$/.test(token.slice(token.lastIndexOf('-') + 1));
+  return [...tokens.filter(isRole), ...tokens.filter((token) => !isRole(token))];
+}
+
+/** The sentence that names the real token first (ggui#1325); empty when nothing in the manifest is near. */
+function offManifestHint(name: string): string {
+  const successor = RETIRED_TOKEN_SUCCESSORS.get(name);
+  if (successor !== undefined) {
+    return `"${name}" was retired (ggui#987); the current name is var(${successor}). `;
+  }
+  const near = suggestManifestTokens(name);
+  if (near.length === 0) return '';
+  const shown = near.slice(0, 8).map((token) => `var(${token})`).join(', ');
+  const more = near.length > 8 ? ` (and ${near.length - 8} more in that family)` : '';
+  return `Nearest names in the manifest: ${shown}${more}. `;
+}
 const TOKEN_REF_RE = /var\(\s*(--ggui-[a-zA-Z0-9-]+)/g;
 
 /** Map wire kind to the matching `@ggui-ai/wire` hook name. */
@@ -790,7 +869,7 @@ export async function runTier0Checks(
         subcategory: 'off-manifest-token',
         severity: 'critical',
         description: `Token "${name}" is not in the design system's token manifest — no theme defines it, so it renders unset.`,
-        fix: `Choose a token that exists: the closed vocabulary is the manifest the design-system docs list (colors: var(--ggui-color-primary-500), var(--ggui-color-onContainer), …; spacing: var(--ggui-spacing-4); type: var(--ggui-font-size-sm)). Never invent a name and never add a literal fallback.`,
+        fix: `${offManifestHint(name)}Choose a token that exists: the closed vocabulary is the manifest the design-system docs list (colors: var(--ggui-color-primary-500), var(--ggui-color-onContainer), …; spacing: var(--ggui-spacing-4); type: var(--ggui-font-size-sm)). Never invent a name and never add a literal fallback.`,
         line: lineNum,
       });
     }