@godxjp/ui 32.5.0 → 32.7.0

package/dist/tokens/components/legal-document.css

@@ -8,6 +8,10 @@
 
   --legal-document-toc-width: 15rem;
 
+  --legal-document-page-padding-inline: initial;
+
+  --legal-document-title-font-size: initial;
+
   --legal-document-toc-inset-block-start: var(--space-6);
 
   --legal-document-toc-max-height: calc(100dvh - var(--space-12));

package/docs/CONSUMER-RULES.md

@@ -1,12 +1,13 @@
-# @godxjp/ui — the ten consumer rules
+# @godxjp/ui — the consumer rules
 
-Read this once; the audit enforces it. Everything else in `docs/` is for contributors.
+Read this once; the audit enforces it. What the audit cannot see (how a screen is composed, what it
+should look like) is in the package's `DESIGN.md`. Everything else in `docs/` is for contributors.
 
 1. Load styles with `import "@godxjp/ui/styles.css"` (precompiled, no Tailwind needed) or `@import "@godxjp/ui/styles"` (Tailwind v4). Neither ships font files: fonts are opt-in since v32 (`pnpm add @fontsource/noto-sans-jp @fontsource/m-plus-2`, then `@import "@godxjp/ui/styles/fonts.css"` after the styles import; the GoDX preset does this for you). Never cherry-pick `*-layout.css`.
-2. **Mount `<AppProvider defaultLocale="…">` once, at the root.** Without it the kit's OWN strings (dialog close/cancel/delete, counters, picker labels) fall to the resting locale `vi` and pickers to UTC — measured in a Japanese app as Vietnamese buttons, silently (gh#1005). A development build now warns once when a kit component renders outside it; `syncI18nLocale(locale, fallback)` is the escape for an app that truly cannot mount the provider. Every page is `<PageContainer title subtitle extra footer>`; its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
+2. **Mount `<AppProvider defaultLocale="…">` once, at the root.** Without it the kit's OWN strings (dialog close/cancel/delete, counters, picker labels) fall to the resting locale (`<html lang>` when it names a registered locale, else `en`) and pickers to UTC (gh#1005). A development build now warns once when a kit component renders outside it; `syncI18nLocale(locale, fallback)` is the escape for an app that truly cannot mount the provider. Every page is `<PageContainer title extra footer>` (a `subtitle` only when it adds a fact the title does not); its sections are spaced by the page. Group items inside a section with `<Flex direction="col" gap>` or `<ResponsiveGrid>`.
 3. No Tailwind layout on your own elements: no `flex`, `grid`, `gap-*`, `p-*`, `m-*`, `space-*`. Rows are `<Flex>` (default row), stacks are `<Flex direction="col">`, grids are `<ResponsiveGrid>`.
 4. No hand-rolled surfaces: no `rounded-* border bg-*` divs. A box is `Card`, a pill is `Badge`, a person is `Avatar`, a row is `ListRow`, a label/value pair is `Descriptions`, an empty area is `EmptyState`, a read-only sample of a colour the USER chose is `Swatch`. A LIST of those rows is `<Flex as="ul" marker="none" direction="col" gap="none">` with `<ListRow as="li">` children — `marker="none"` keeps the `<ul>`, the `<li>` semantics and the gap token while dropping the bullet and the indent. Never a raw `<ul>`/`<ol>` (it carries no gap token), never `<div role="list">` + `<div role="listitem">`, and never a wrapper around each row: the divider is `:not(:last-child)` among siblings, so a row alone in its own wrapper is always the last one and EVERY divider disappears silently. A bulleted prose list is the same `<Flex as="ul">` without `marker`.
-5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below. **Fields live in a `<Form layout="horizontal" labelWidth controlWidth>`** — never a group of `FormField`s without one, never a hand-rolled `<Flex>` row of fields (a row that belongs together is `<SpaceCompact>` or `<Form columns>`); size each control for its content with `controlWidth` (GOV.UK text-input width: a port ~7rem, a short enum ~10rem); three or more fields is a page, not a Dialog. The audit rules are `formfield-needs-form`, `dialog-form-too-big` and `select-width-hint`. **A case the kit cannot express is an issue, not a hand-roll:** open it on godx-jp/godxjp-ui, use the nearest valid composition, and mark it `// TODO(godxjp-ui#<n>)` (gh#998). **One action row, one Button size:** every `Button` under one parent takes the same `size` — a missing size is `default`, and `icon-sm` pairs with `sm`, `icon-xs` with `xs`, `icon` with default. Never `size="sm"` beside a default Button. The audit rules are `mixed-button-size` (static) and `mixed-button-height` (visual-audit, within 0.5px) (gh#1084).
+5. Real controls only: `Button`, `Input`, `Select`, `Textarea`, `Checkbox`… never raw `<button>`/`<input>`; a labelled control lives in `<FormField label>`. A Select outside a form takes `width="auto"`. **A disabled control's reason is visible text, never a tooltip** — see below. **Fields live in a `<Form layout="horizontal" labelWidth controlWidth>`** — never a group of `FormField`s without one, never a hand-rolled `<Flex>` row of fields (a row that belongs together is `<Flex attached>` or `<Form columns>`); size each control for its content with `controlWidth` (GOV.UK text-input width: a port ~7rem, a short enum ~10rem); three or more fields is a page, not a Dialog. The audit rules are `formfield-needs-form`, `dialog-form-too-big` and `select-width-hint`. **A case the kit cannot express is an issue, not a hand-roll:** open it on godx-jp/godxjp-ui, use the nearest valid composition, and mark it `// TODO(godxjp-ui#<n>)` (gh#998). **One action row, one Button size:** every `Button` under one parent takes the same `size` — a missing size is `default`, and `icon-sm` pairs with `sm`, `icon-xs` with `xs`, `icon` with default. Never `size="sm"` beside a default Button. The audit rules are `mixed-button-size` (static) and `mixed-button-height` (visual-audit, within 0.5px) (gh#1084).
 6. Text is `<Text>` / `<Heading>` with `tone`, `size`, `weight`, `truncate`, `mono` — not `className="text-muted-foreground font-semibold"`. A STANDALONE glyph is `<Icon as={Lock} size="sm" tone="muted" />` from `@godxjp/ui/general`: a bare lucide icon carries its own `width="24" height="24"` and only four places re-size it for you (`Button`, a `DropdownMenuItem`, a `TopbarItem`, a `ListRow` leading slot), so everywhere else — in a `Text`, a table cell, an `<a>` — it draws at 24px beside 14px type. `size-4` and `w-[16px]` are closed to you by rules 3 and 8, and `size={16}` hard-codes a number the theme owns; `Icon` puts the glyph on the `--icon-size-*` scale (`2xs…4xl`) instead, and is `aria-hidden` unless you give it a `label` (then it is `role="img"` with that name). The audit rule is `lucide-icon-needs-size`.
 7. Colours are semantic tokens (`tone="destructive"`, `bg-primary`), never palette names, hex, or `bg-black` / `text-white`.
 8. Sizes come from props (`size`, `width`, `columns`), never `w-[240px]` / `max-h-[420px]`.
@@ -16,7 +17,7 @@ Read this once; the audit enforces it. Everything else in `docs/` is for contrib
     the table reads as a second box inside the card, and a wide one runs past the card entirely.
     (`flush` alone is enough: it drops the border, the radius and the inline padding. `tight` is a
     different knob — it governs the header band, not the body's edges.)
-11. Run `node node_modules/@godxjp/ui/scripts/ui-audit.mjs --changed` before every review; a browser sweep with `visual-audit.mjs` is a separate, heavier run — do it when the work is a visual review, not on every change; `visual-audit.mjs <url>` on the running app. Zero errors is the bar.
+11. Run `npx @godxjp/ui audit --changed` before every review (the package bin, so it works from a workspace package whose `node_modules` is hoisted to the repo root); a browser sweep with `npx @godxjp/ui visual-audit <url>` on the running app is a separate, heavier run — do it when the work is a visual review, not on every change. Zero errors is the bar.
 
 **Opting a deliberate exception out.** Name the rule; the block form also has to say why.
 

package/docs/README.md

@@ -2,7 +2,7 @@
 
 | Doc                                          | Purpose                                                                                                                                                                                                               |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [CONSUMER-RULES.md](./CONSUMER-RULES.md)     | **Start here if you build an app with @godxjp/ui** — the ten rules the audit enforces (styles entry, layout owners, real primitives, tokens)                                                                          |
+| [CONSUMER-RULES.md](./CONSUMER-RULES.md)     | **Start here if you build an app with @godxjp/ui** — the rules the audit enforces (styles entry, layout owners, real primitives, tokens)                                                                          |
 | [DEVELOPMENT.md](./DEVELOPMENT.md)           | **Contributor guideline** — role/boundary, architecture, how to add/extend, verify                                                                                                                                    |
 | [COMPONENTS.md](./COMPONENTS.md)             | Component catalog by taxonomy group                                                                                                                                                                                   |
 | [PROPS-VOCABULARY.md](./PROPS-VOCABULARY.md) | Atomic prop types (`*Prop` suffix)                                                                                                                                                                                    |

package/docs/migrations/v32.md

@@ -28,9 +28,11 @@ Off-cycle approved: owner, 2026-10-09 — the single v32 batch decided on godx-j
   renders none.
 - The email brand mark has no default label.
 - The GoDX look ships as `godxPreset` (`@godxjp/ui/themes/godx`) plus `@godxjp/ui/themes/godx.css`.
-- Since 32.0.1, `@godxjp/ui/themes/godx-tokens.css` holds the GoDX colours without the fonts, for a
-  shadow root that embeds `@godxjp/ui/styles/core` (`@font-face` only works in the document). Add it
-  after `styles/core` there; `godx.css` imports it, so a page needs only `godx.css`.
+- Since 32.0.1, `@godxjp/ui/themes/godx-tokens.css` holds the GoDX colours without the fonts.
+  `godx.css` is `fonts.css` (which imports `@fontsource/noto-sans-jp` and `@fontsource/m-plus-2`)
+  plus `godx-tokens.css`. Import `godx-tokens.css` instead of `godx.css` when the app bundles or
+  hosts its own fonts, and in a shadow root that embeds `@godxjp/ui/styles/core` (`@font-face`
+  only works in the document). Never import both. Put it after the base stylesheet.
 - A script that READS the GoDX colours from `themes/godx.css` (a token sync, a design-system
   export) must read `themes/godx-tokens.css` instead: since 32.0.1, `godx.css` holds only two
   `@import` lines.
@@ -84,7 +86,7 @@ packages. The codemod rewrites every import below; the "you finish" column is pr
 | `Title`, `Paragraph`, `Typography`                                                                                                                                                                                 | `Heading`, `Text as="p"`, `Prose` | the antd compatibility shims are removed                               |
 | `SkeletonAvatar`, `SkeletonButton`, `SkeletonImage`, `SkeletonNode`                                                                                                                                                | —                                 | removed: use `SkeletonArticle avatar` or a sized `Skeleton`            |
 | `FloatButton`, `DraggablePanel`, `PageCover`, `Masonry`, `LegalDocumentShell`, `Marquee`, `TextDiff`, `OrgChart`, `Carousel`, `TimelineGrid`, `RangeTimeline`, `EmojiPicker`, `SortableList`, `MegaMenu`, `Anchor` | same names from `@godxjp/ui/lab`  | nothing: same API, opt-in subpath                                      |
-| `ChatBubble`, `ChatBubbleList`, `ChatComposer`, `ChatSuggestion`, `Conversations`, `ThoughtChain`, `Welcome`, `Attachments`                                                                                        | same names from `@godxjp/chat`    | install `@godxjp/chat`                                                 |
+| `ChatBubble`, `ChatBubbleList`, `ChatComposer`, `ChatSuggestion`, `Conversations`, `ThoughtChain`, `Welcome`, `Attachments`                                                                                        | same names from `@godxjp/chat`    | add `@godxjp/chat` as a NEW dependency, same version as `@godxjp/ui`   |
 
 Unchanged: `SplitPane` stays (its merge into `MasterDetail` failed the parity test), `Actions` stays
 in `@godxjp/ui/general`, and `FilterBar` stays an alias of `Toolbar`. The `./ui/*` subpaths are
@@ -92,7 +94,10 @@ deprecated re-exports and will be removed in a later major.
 
 ## How to upgrade
 
-1. Upgrade all six packages to the latest 32.0.x together (`@godxjp/chat` only if you use the chat components).
+1. Upgrade all six packages to the latest 32.0.x together. An app that imports `ChatSuggestion` or
+   any other chat component from `@godxjp/ui` must ADD `@godxjp/chat` to its `package.json` — it
+   is a new dependency, not a rename — at the same version as `@godxjp/ui` (the packages release
+   in lockstep). Without it the build fails on the first chat import.
 2. Run `npx godxjp-ui codemod v32 <src> --dry-run`, review, then run it without `--dry-run`. Use
    `--godx` for GoDX products.
    The 32.0.0 codemod imported the fonts twice under `--godx` (`fonts.css` and `godx.css`, which

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "32.5.0",
-  "godxUiMcp": "32.5.0",
+  "version": "32.7.0",
+  "godxUiMcp": "32.7.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,6 +28,7 @@
   "description": "React UI framework built on design tokens: accessible components, a controlled prop vocabulary, and a machine-readable catalog for coding agents.",
   "files": [
     "LICENSE",
+    "DESIGN.md",
     "agent",
     "dist",
     "scripts/ui-audit.mjs",

package/scripts/_agent-setup.mjs

@@ -15,6 +15,7 @@ import {
   chmodSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   realpathSync,
   renameSync,
@@ -78,7 +79,11 @@ function mcpConfigMismatchMessage(root, existing, expected, key = MCP_KEY) {
 }
 
 /** Commands wired into the consumer's .claude/settings.json. */
-export const AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.mjs";
+// `npx --no-install` resolves @godxjp/ui up the node_modules chain, so the hook also works from a
+// workspace package whose install is hoisted to the repo root (gh#1296); it never downloads.
+export const AUDIT_HOOK_CMD = "npx --no-install @godxjp/ui audit-hook";
+/** The pre-#1296 default, rewritten to AUDIT_HOOK_CMD when found verbatim (a custom command is kept). */
+const LEGACY_AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.mjs";
 export const PRIMER_CMD = "cat .claude/godxjp-ui-workflow.md";
 
 /** What `.claude/settings.json` would get, used only for the `.godxjp-ui-suggested` sidecar. */
@@ -97,7 +102,12 @@ export const KIT_VERSION = readJson(join(SELF_ROOT, "package.json"))?.version ??
  * node_modules). Returns null when absent — caller falls back to this package's release train.
  */
 export function readConsumerUiMetadata(root) {
-  const uiPkg = readJson(join(root, "node_modules/@godxjp/ui/package.json"));
+  // Up the node_modules chain: a workspace package has @godxjp/ui hoisted to the repo root (gh#1296).
+  let uiPkg;
+  for (let dir = resolve(root); ; dir = dirname(dir)) {
+    uiPkg = readJson(join(dir, "node_modules/@godxjp/ui/package.json"));
+    if (uiPkg || dirname(dir) === dir) break;
+  }
   if (!uiPkg?.version) return null;
   return {
     version: String(uiPkg.version),
@@ -167,87 +177,62 @@ function resyncVersionStamp(text) {
  * appended repo-specific sections keeps them.
  */
 export const WORKFLOW_MD = `${STAMP(KIT_VERSION)}
-# @godxjp/ui — mandatory workflow (read every session)
-
-You are building UI in an app that uses @godxjp/ui. Follow this EVERY time you create
-or change a component, page, or form — no exceptions.
-
-## The rules the audit enforces (docs/CONSUMER-RULES.md in node_modules/@godxjp/ui)
-- Styles: \`@import "@godxjp/ui/styles"\` or \`@godxjp/ui/styles/core\` (no fonts). Never cherry-pick layers.
-- Layout: sections of a page are spaced by \`PageContainer\`; siblings go in \`<Flex direction="col" gap>\` /
+# @godxjp/ui — workflow (read every session)
+
+Follow this every time you create or change a page, component or form.
+
+## Before JSX
+1. **Design target.** Read \`node_modules/@godxjp/ui/DESIGN.md\` (MCP \`get_design\`): tokens,
+   scarcity rules, screen anatomy, do/don't.
+2. **Route.** \`route_consumer_task "<task>"\` → \`compose-a-screen\` for app screens. The
+   marketing skills (soft, minimalist, brutalist, gpt-tasteskill, imagegen-*) are for landing
+   pages only.
+3. **Exemplar.** \`get_exemplar\` with archetype list | detail | form | settings | dashboard |
+   approval. Match its structure; it is the visual target.
+4. **Discover, then look up.** \`search_components "<area>"\` first, \`get_component <Name>\`
+   second — \`get_component\` cannot find a name you do not already have (a consumer hand-rolled
+   the shipped \`OrgSwitcher\` and \`TopbarItem\` this way). Code already in this repo is not the
+   authority: search even when a neighbouring file seems to answer. Never guess a prop.
+
+## Contract (ui-audit enforces it; full text in node_modules/@godxjp/ui/docs/CONSUMER-RULES.md)
+- Styles: \`@import "@godxjp/ui/styles"\` (or \`import "@godxjp/ui/styles.css"\`); fonts are opt-in
+  via \`@godxjp/ui/styles/fonts.css\`. Never cherry-pick layers.
+- Layout: \`PageContainer\` spaces sections; siblings go in \`<Flex direction="col" gap>\` /
   \`<ResponsiveGrid>\`. No \`flex\` / \`grid\` / \`gap-*\` / \`p-*\` / \`m-*\` on your own elements.
-- Surfaces: \`Card\` / \`Badge\` / \`Avatar\` / \`ListRow\` / \`Descriptions\` / \`EmptyState\` — never a
-  \`rounded border\` div. Text is \`<Text tone size weight truncate>\`, never utility classes.
-
-## Before writing UI
-1. **DISCOVERY BEFORE LOOKUP — in this order, every time.**
-   1. \`search_components "<the area you are about to build>"\` FIRST. This is the only call that
-      answers "what already exists here". Ask it before the first line of JSX, not after.
-   2. \`get_component <Name>\` second, once you know the name.
-   \`get_component\` answers "how do I use X" and is USELESS for finding X — you can only look up a
-   name you already have. Skipping step 1 is how a consumer hand-rolled an organization switcher
-   the package ships (\`OrgSwitcher\`) and built three topbar cells out of Buttons instead of
-   \`TopbarItem\`: both were one \`search_components\` call away, and neither was ever searched for.
-   **Existing code in this repo is NOT the authority.** Reading a neighbouring file and copying it
-   is the most common way this rule gets skipped — measured: of four fresh agents given a vague UI
-   task, all four answered correctly but two never called the MCP at all, saying the answer was
-   already in the code. They were only right because that code had just been fixed; a week earlier
-   the same files hand-rolled a switcher and put Buttons in topbar slots, and both agents would
-   have copied it. Search the catalog even when a local file looks like it already answers you.
-   Also \`list_audit_rules\`, \`list_visual_checks\`. Never guess a prop; never hand-roll what a
-   primitive already does.
-2. **Real primitives only.** No raw \`<input>/<select>/<button>/<textarea>/<table>\`, no
-   styled-div fakes. A labelled control ALWAYS goes in \`<FormField label=…>\` (it owns the
-   label↔control wiring, error/aria, AND the field rhythm). Never pair a bare \`<Label>\`
-   with an \`<Input>\`.
-3. **Tokens, not literals.** Semantic colour tokens (bg-primary, text-muted-foreground),
-   token spacing/size/radius/type — no raw palette (bg-blue-600), no hex, no arbitrary
-   \`[13px]\`. No emoji in product UI. Logical CSS (ms-/me-/ps-/pe-) for RTL.
-
-## After writing UI
-4. **Audit (runs automatically too).** \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs\`
-   — fix every finding. A PostToolUse hook also runs it on each edit and feeds findings back.
-5. **Before a visual review**, run the runtime audit against the running app:
-   \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\` (axe + contrast + layout).
+- Surfaces: \`Card\` / \`Badge\` / \`Avatar\` / \`ListRow\` / \`Descriptions\` / \`EmptyState\`, never a
+  \`rounded border\` div. Text is \`<Text tone size weight>\`.
+- Real controls only; a labelled control sits in \`<FormField label>\` inside a \`<Form>\`.
+- Semantic tokens only: no hex, palette names, arbitrary \`[13px]\`, emoji. Logical CSS (ms-/me-).
+- Screen composition (what the audit cannot see) is in \`.ai/rules/godxjp-ui.md\`.
+
+## After JSX
+5. \`npx @godxjp/ui audit <files>\` — zero errors (a PostToolUse hook also runs it on each edit).
+   Run it from the package that owns the files; \`--help\` lists the flags.
+6. Screenshot at 390 / 768 / 1280 next to the exemplar, list the top 3 differences, fix them,
+   repeat — at most 3 rounds.
+7. Before a visual review: \`npx @godxjp/ui visual-audit <url>\` (axe + contrast + layout).
+
+In a workspace, \`node_modules/@godxjp/ui\` may be hoisted to the repo root: read its files there,
+or through the MCP (\`get_design\`, \`get_rule\`).
 `;
 
 /** Delimited block appended to the consumer's CLAUDE.md — loaded into the agent's context
- * every turn (the most reliable "ensure it reads the rules"). Markers keep it idempotent. */
-export const CLAUDE_MD_BLOCK = `<!-- godxjp-ui:start (managed by @godxjp/ui — edit .claude/godxjp-ui-workflow.md instead) -->
+ * every turn, so it carries only the default path and points at the workflow for the rest.
+ * Markers keep it idempotent. */
+export const CLAUDE_MD_BLOCK = `<!-- godxjp-ui:start (managed by @godxjp/ui — rewritten by npx godxjp-ui sync-rules) -->
 ${STAMP(KIT_VERSION)}
-## @godxjp/ui — mandatory UI workflow (do NOT skip)
-
-This app uses @godxjp/ui. EVERY time you build or change UI:
-
-0. **Ten rules** — read \`node_modules/@godxjp/ui/docs/CONSUMER-RULES.md\` once. Styles via
-   \`@godxjp/ui/styles\` or \`styles/core\` (never cherry-pick layers). Page sections are spaced by
-   \`PageContainer\`; siblings go in \`<Flex direction="col" gap>\` / \`<ResponsiveGrid>\`; no
-   \`flex\`/\`grid\`/\`gap-*\`/\`p-*\`/\`m-*\` on your own elements; boxes are \`Card\`/\`Badge\`/
-   \`ListRow\`/\`Descriptions\`, never a \`rounded border\` div; text is \`<Text tone size weight>\`.
-1. **DISCOVERY BEFORE LOOKUP — in this order, every time.**
-   1. \`search_components "<the area you are about to build>"\` FIRST. This is the only call that
-      answers "what already exists here". Ask it before the first line of JSX, not after.
-   2. \`get_component <Name>\` second, once you know the name.
-   \`get_component\` answers "how do I use X" and is USELESS for finding X — you can only look up a
-   name you already have. Skipping step 1 is how a consumer hand-rolled an organization switcher
-   the package ships (\`OrgSwitcher\`) and built three topbar cells out of Buttons instead of
-   \`TopbarItem\`: both were one \`search_components\` call away, and neither was ever searched for.
-   **Existing code in this repo is NOT the authority.** Reading a neighbouring file and copying it
-   is the most common way this rule gets skipped — measured: of four fresh agents given a vague UI
-   task, all four answered correctly but two never called the MCP at all, saying the answer was
-   already in the code. They were only right because that code had just been fixed; a week earlier
-   the same files hand-rolled a switcher and put Buttons in topbar slots, and both agents would
-   have copied it. Search the catalog even when a local file looks like it already answers you.
-   Also \`list_audit_rules\`, \`list_visual_checks\`. Never guess a prop; never hand-roll what a
-   primitive already does.
-2. **Real primitives only.** No raw \`<input>/<select>/<button>/<textarea>/<table>\`. A labelled
-   control ALWAYS goes in \`<FormField label=…>\` — never a bare \`<Label>\`+\`<Input>\`. Semantic
-   tokens, not raw palette/hex/arbitrary values. No emoji in product UI. Logical CSS for RTL.
-3. **Scan after writing.** \`node node_modules/@godxjp/ui/scripts/ui-audit.mjs <files>\` and fix
-   every finding (a PostToolUse hook runs this automatically and feeds findings back). Before a
-   visual review: \`node node_modules/@godxjp/ui/scripts/visual-audit.mjs <url>\` (axe + layout).
-
-Full guide: \`.claude/godxjp-ui-workflow.md\`.
+## @godxjp/ui — UI workflow
+
+Before any JSX for a screen:
+1. Read \`node_modules/@godxjp/ui/DESIGN.md\` (MCP \`get_design\`).
+2. \`route_consumer_task\` → \`compose-a-screen\`; \`search_components\` before hand-rolling anything.
+3. \`get_exemplar\` (list | detail | form | settings | dashboard | approval) — match its structure.
+
+After building:
+4. \`npx @godxjp/ui audit <files>\` — zero errors.
+5. Screenshot at 390 / 768 / 1280 beside the exemplar; fix the top 3 differences; max 3 rounds.
+
+Rules: \`node_modules/@godxjp/ui/docs/CONSUMER-RULES.md\`. Details: \`.claude/godxjp-ui-workflow.md\`.
 <!-- godxjp-ui:end -->
 `;
 
@@ -550,7 +535,13 @@ export function ensureClaudeHooks(root) {
     (arr ?? []).some((g) => (g.hooks ?? []).some((h) => (h.command ?? "").includes(cmd)));
 
   json.hooks.PostToolUse = json.hooks.PostToolUse ?? [];
-  if (!has(json.hooks.PostToolUse, "audit-hook.mjs")) {
+  for (const group of json.hooks.PostToolUse)
+    for (const hook of group.hooks ?? [])
+      if (hook.command === LEGACY_AUDIT_HOOK_CMD) {
+        hook.command = AUDIT_HOOK_CMD;
+        added.push("PostToolUse:auto-audit (workspace-safe command)");
+      }
+  if (!has(json.hooks.PostToolUse, "audit-hook")) {
     json.hooks.PostToolUse.push({
       matcher: "Write|Edit|MultiEdit",
       hooks: [{ type: "command", command: AUDIT_HOOK_CMD }],
@@ -719,16 +710,86 @@ export function guineaPigStamp() {
  * this one. The file says so at the top, because the first draft preserved nothing and silently
  * ate a note left inside it — measured, and the reason for that banner.
  */
-export function ensureConsumerRules(root) {
-  const uiDir = ["resources/js", "app/javascript", "src/components", "src", "app"].find((d) =>
+const UI_FILE = /\.(tsx|jsx)$/;
+const NOT_UI_DIR = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "vendor",
+  "coverage",
+  "public",
+  "storage",
+]);
+
+/** Does `dir` hold a .tsx/.jsx file within a few levels? Bounded, so a large tree costs little. */
+function holdsUi(dir, depth = 5) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  if (entries.some((e) => e.isFile() && UI_FILE.test(e.name))) return true;
+  if (depth === 0) return false;
+  return entries.some(
+    (e) =>
+      e.isDirectory() &&
+      !e.name.startsWith(".") &&
+      !NOT_UI_DIR.has(e.name) &&
+      holdsUi(join(dir, e.name), depth - 1),
+  );
+}
+
+/**
+ * Every directory that actually holds the consumer's UI, as `paths:` globs without the `/**`
+ * (gh#1296). A fixed `src` never fired in an app whose screens live in `web/` or
+ * `resources/js/`, so the rules looked installed and loaded on no edit. Conventional nested roots
+ * first (`resources/js`, `apps/*\/src`, …), then any other top-level directory holding .tsx/.jsx.
+ * A repo with no UI files yet (a fresh scaffold) falls back to the first conventional directory
+ * that exists.
+ */
+function detectUiDirs(root) {
+  const subdirs = (rel) => {
+    try {
+      return readdirSync(join(root, rel), { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !NOT_UI_DIR.has(e.name))
+        .map((e) => e.name)
+        .sort();
+    } catch {
+      return [];
+    }
+  };
+  const found = [];
+  const add = (glob, dirs) => {
+    if (dirs.some((d) => holdsUi(join(root, d)))) found.push(glob);
+  };
+  for (const rel of ["resources/js", "app/javascript"]) add(rel, [rel]);
+  for (const parent of ["apps", "packages"]) {
+    const dirs = subdirs(parent)
+      .map((name) => `${parent}/${name}/src`)
+      .filter((d) => existsSync(join(root, d)));
+    if (dirs.length) add(`${parent}/*/src`, dirs);
+  }
+  for (const name of subdirs("")) {
+    if (!found.some((glob) => glob.split("/")[0] === name)) add(name, [name]);
+  }
+  if (found.length) return found;
+  const scaffold = ["resources/js", "app/javascript", "src/components", "src", "app"].find((d) =>
     existsSync(join(root, d)),
   );
-  if (!uiDir) return false;
+  return scaffold ? [scaffold] : [];
+}
+
+export function ensureConsumerRules(root) {
+  const uiDirs = detectUiDirs(root);
+  if (uiDirs.length === 0) return false;
+  const uiDir = uiDirs.join(", ");
 
   const dir = join(root, ".ai", "rules");
   const target = join(dir, "godxjp-ui.md");
   const body = readFileSync(join(SELF_ROOT, "scripts", "consumer-rule.md"), "utf8");
-  const front = `---\npaths:\n    - '${uiDir}/**'\n---\n\n`;
+  const front = `---\npaths:\n${uiDirs.map((d) => `    - '${d}/**'\n`).join("")}---\n\n`;
   // The digest covers the FRONT MATTER too: the detected glob is part of what makes this file
   // correct, and a repo that grows a `resources/js` after shipping with `src` needs the rewrite.
   const managed = `${front}${body}`;
@@ -772,7 +833,8 @@ export function ensureConsumerRules(root) {
     if (!cur.includes(".ai/rules/godxjp-ui.md")) {
       writeFileAtomic(
         index,
-        cur.replace(/\s*$/, "") + `\n| ${uiDir}/** | .ai/rules/godxjp-ui.md |\n`,
+        cur.replace(/\s*$/, "") +
+          `\n| ${uiDirs.map((d) => `${d}/**`).join(", ")} | .ai/rules/godxjp-ui.md |\n`,
       );
     }
   }
@@ -807,7 +869,9 @@ export function runSyncRules(root, { dryRun = false } = {}) {
     if (!refused && !(r === "present" && md === "present" && !wf && !skill && !rules)) {
       lines.push(
         `\n  @godxjp/ui → MCP in .mcp.json (${r}); workflow mandate in CLAUDE.md (${md}).\n` +
-          (rules ? `  common consumer rules in .ai/rules/godxjp-ui.md (glob ${rules}/**).\n` : "") +
+          (rules
+            ? `  common consumer rules in .ai/rules/godxjp-ui.md (UI dirs: ${rules}).\n`
+            : "") +
           (skill ? "  guinea-pig skill refreshed to this version (your section 8 kept).\n" : "") +
           "  Your agent now has live component + audit guidance. Restart it to pick up the MCP.\n" +
           "  For auto-audit on every edit (PostToolUse + SessionStart hooks):\n" +

package/scripts/cli.mjs

@@ -16,6 +16,7 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const MAP = {
   "init-agent": "init-agent-kit.mjs",
   audit: "ui-audit.mjs",
+  "audit-hook": "audit-hook.mjs",
   "visual-audit": "visual-audit.mjs",
   "prune-css": "prune-css.mjs",
   codemod: "codemod.mjs",
@@ -55,8 +56,14 @@ const HELP = {
                     fails rather than reporting clean when origin/main cannot be resolved
     --format json   machine-readable findings
     --quiet         print errors only (warnings hidden)
+    --base=<ref>    with --changed, diff against <ref> instead of origin/main
     --rules         print the rule catalog as JSON and exit
+    --consumer      inside the @godxjp/ui repo only: apply the consumer rules (always on in an app)
   Pre-commit:  npx godxjp-ui audit resources/js || exit 1`,
+  "audit-hook": `godxjp-ui audit-hook
+
+  The Claude Code PostToolUse hook init-agent wires in: reads the hook payload on stdin and audits
+  the .tsx file that was just written or edited, feeding findings back to the agent. Not for humans.`,
   "prune-css": `godxjp-ui prune-css <src dir/glob …> [--out <file>] [--fonts]
 
   Emit a stylesheet with only the component CSS layers your app uses (gh#971). Scans the given
@@ -95,6 +102,7 @@ commands:
   init-agent     install the agent forcing-kit (MCP + auto-audit hook + CLAUDE.md mandate)
   sync-rules     write/refresh package-owned agent rules (--dry-run previews)
   audit          static UI audit over source
+  audit-hook     the per-edit audit hook (wired by init-agent)
   visual-audit   runtime audit (Playwright + axe-core) against a running app
   prune-css      emit a stylesheet with only the CSS layers your app uses