@godxjp/ui 26.0.0 → 26.2.0

package/dist/components/data-entry/select.d.ts

@@ -26,7 +26,10 @@ export type SelectCompoundProp = FieldA11yProps & {
     form?: string;
     children?: React.ReactNode;
 };
-export type SelectProp = SelectDataProp | SelectCompoundProp;
+export type SelectProp = SelectDataProp | (SelectCompoundProp & {
+    mode?: undefined;
+    labelInValue?: undefined;
+});
 /**
  * Select — one component for every single-select. Use the compound API for full control
  * (`<Select><SelectTrigger/><SelectContent><SelectItem/></SelectContent></Select>`), OR the

package/dist/components/layout/page-container.js

@@ -33,6 +33,12 @@ function useFooterReveal(enabled) {
 function PageContainerInset({ className, children, ...props }) {
   return /* @__PURE__ */ jsx("div", { className: cn("ui-page-container-inset", className), ...props, children });
 }
+function footerPadStyle(footerPad) {
+  const style = padStyle(footerPad, void 0);
+  const end = style?.paddingInlineEnd ?? style?.padding;
+  if (end === void 0) return style;
+  return { ...style, paddingInlineEnd: `calc(${end} + var(--page-footer-content-slack))` };
+}
 function PageContainerRoot({
   title,
   subtitle,
@@ -150,7 +156,7 @@ function PageContainerRoot({
         ),
         toolbar != null && /* @__PURE__ */ jsx("div", { className: "ui-page-toolbar", style: padStyle(toolbarPad, void 0), children: toolbar }),
         children != null && /* @__PURE__ */ jsx("div", { className: "ui-page-body", children }),
-        footer && /* @__PURE__ */ jsx("footer", { className: "ui-page-footer", style: padStyle(footerPad, void 0), children: footer })
+        footer && /* @__PURE__ */ jsx("footer", { className: "ui-page-footer", style: footerPadStyle(footerPad), children: footer })
       ]
     }
   );

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "26.0.0",
+  "version": "26.2.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/styles/control.css

@@ -1119,7 +1119,7 @@
   }
 
   .ui-segmented-item:not([data-state="checked"]):not([data-disabled]):hover {
-    background: hsl(var(--segmented-item-hover-background));
+    background: hsl(var(--segmented-item-hover-background, var(--accent)));
     color: hsl(var(--segmented-item-hover-color));
   }
   .ui-segmented-item:not([data-state="checked"]):not([data-disabled]):active {
@@ -2722,7 +2722,7 @@
   }
 
   .ui-control--filled:hover:not(:disabled):not([readonly]):not([data-disabled]) {
-    background-color: hsl(var(--control-variant-filled-hover-background));
+    background-color: hsl(var(--control-variant-filled-hover-background, var(--accent)));
   }
 
   .ui-control--borderless {
@@ -2939,7 +2939,7 @@
   }
 
   .ui-slider-dot[data-active="true"] {
-    border-color: hsl(var(--slider-dot-active-border-color));
+    border-color: hsl(var(--slider-dot-active-border-color, var(--primary)));
   }
 
   .ui-slider-tooltip {
@@ -3053,14 +3053,14 @@
   }
 
   .ui-radio-button[data-state="checked"] {
-    color: hsl(var(--choice-button-selected-color));
-    border-color: hsl(var(--choice-button-selected-border-color));
+    color: hsl(var(--choice-button-selected-color, var(--primary)));
+    border-color: hsl(var(--choice-button-selected-border-color, var(--primary)));
   }
 
   .ui-radio-button-bar[data-button-style="solid"] .ui-radio-button[data-state="checked"] {
-    color: hsl(var(--choice-button-solid-color));
-    background: hsl(var(--choice-button-solid-background));
-    border-color: hsl(var(--choice-button-solid-background));
+    color: hsl(var(--choice-button-solid-color, var(--primary-foreground)));
+    background: hsl(var(--choice-button-solid-background, var(--primary)));
+    border-color: hsl(var(--choice-button-solid-background, var(--primary)));
   }
 
   .ui-radio-button[data-disabled] {

package/dist/styles/float-button-layout.css

@@ -143,7 +143,7 @@
     content: "";
     inset: 0;
     background: conic-gradient(
-      var(--float-button-progress-color) var(--float-button-progress-offset),
+      var(--float-button-progress-color, hsl(var(--primary))) var(--float-button-progress-offset),
       var(--float-button-progress-track-color) var(--float-button-progress-offset)
     );
     mask: radial-gradient(

package/dist/styles/focus-ring.css

@@ -53,7 +53,7 @@
   .ui-otp-slot[data-active="true"],
   .ui-otp-group[data-appearance="grouped"]:has(.ui-otp-slot[data-active="true"]) {
     outline: var(--focus-ring-width) solid
-      hsl(var(--focus-outline-color) / var(--focus-ring-opacity, 1));
+      hsl(var(--focus-outline-color, var(--focus-ring-color, var(--ring))) / var(--focus-ring-opacity, 1));
     outline-offset: var(--focus-ring-offset);
 
     transition:

package/dist/styles/layout.css

@@ -1,5 +1,11 @@
 
 
+@property --page-footer-content-slack {
+  syntax: "<length-percentage>";
+  inherits: false;
+  initial-value: 0px;
+}
+
 @layer components {
 
   .ui-separator {
@@ -90,7 +96,14 @@
   }
 
   .ui-brand-glow {
-    background-image: var(--brand-glow);
+    background-image: var(
+      --brand-glow,
+      radial-gradient(
+        ellipse var(--brand-glow-size) at var(--brand-glow-position),
+        hsl(var(--brand-glow-color, var(--primary)) / var(--brand-glow-alpha)),
+        transparent 70%
+      )
+    );
     pointer-events: none;
   }
 
@@ -616,6 +629,14 @@
     max-inline-size: var(--page-measure-medium);
   }
 
+  .ui-page-container[data-measure="narrow"] .ui-page-footer {
+    --page-footer-content-slack: max(0px, 100% - var(--page-measure-narrow));
+  }
+
+  .ui-page-container[data-measure="medium"] .ui-page-footer {
+    --page-footer-content-slack: max(0px, 100% - var(--page-measure-medium));
+  }
+
   .ui-page-container--flush .ui-page-toolbar,
   .ui-page-container--flush .ui-page-body {
     padding-inline-start: 0;
@@ -867,6 +888,7 @@
     align-items: stretch;
     gap: var(--space-inline-sm);
     padding-top: var(--space-stack-md);
+    padding-inline-end: calc(var(--space-page-active-x) + var(--page-footer-content-slack));
     border-top: var(--page-footer-divider, 1px solid hsl(var(--border)));
   }
 

package/dist/styles/shell-layout.css

@@ -291,6 +291,10 @@
     max-inline-size: var(--app-shell-page-max-width);
   }
 
+  .app-main :where(.ui-page-footer) {
+    --page-footer-content-slack: max(0px, 100% - var(--app-shell-page-max-width));
+  }
+
   .ui-auth-shell {
     --control-height: var(--auth-shell-control-height);
     --heading-h1: var(--auth-shell-heading-size);
@@ -1430,8 +1434,8 @@
   }
 
   .ui-app-launcher-tile:hover {
-    background: hsl(var(--app-launcher-tile-hover-background));
-    color: hsl(var(--app-launcher-tile-hover-color));
+    background: hsl(var(--app-launcher-tile-hover-background, var(--accent)));
+    color: hsl(var(--app-launcher-tile-hover-color, var(--accent-foreground)));
   }
 
   .ui-app-launcher-tile[aria-current="page"] {
@@ -2036,14 +2040,14 @@
   }
 
   .ui-topbar-item:hover {
-    background: hsl(var(--topbar-item-hover-background));
-    color: hsl(var(--topbar-item-hover-color));
+    background: hsl(var(--topbar-item-hover-background, var(--accent)));
+    color: hsl(var(--topbar-item-hover-color, var(--accent-foreground)));
   }
 
   .ui-topbar-item:active,
   .ui-topbar-item[data-state="open"] {
     background: hsl(var(--topbar-item-active-background));
-    color: hsl(var(--topbar-item-hover-color));
+    color: hsl(var(--topbar-item-hover-color, var(--accent-foreground)));
   }
 
   .ui-topbar-item:disabled,

package/dist/tokens/components/control.css

@@ -35,7 +35,7 @@
   --number-input-touch-height: var(--band-height-2xl);
 
   --control-variant-filled-background: var(--muted);
-  --control-variant-filled-hover-background: var(--accent);
+  --control-variant-filled-hover-background: initial;
 
   --control-count-font-size: var(--font-size-sm);
   --control-count-color: var(--muted-foreground);
@@ -58,7 +58,7 @@
   --slider-dot-size: var(--slider-track-height);
   --slider-dot-background: var(--background);
   --slider-dot-border-color: var(--border);
-  --slider-dot-active-border-color: var(--primary);
+  --slider-dot-active-border-color: initial;
   --slider-tooltip-background: var(--popover);
   --slider-tooltip-color: var(--popover-foreground);
   --slider-tooltip-font-size: var(--font-size-xs);
@@ -69,10 +69,11 @@
   --choice-button-background: var(--background);
   --choice-button-color: var(--foreground);
   --choice-button-border-color: var(--input);
-  --choice-button-selected-color: var(--primary);
-  --choice-button-selected-border-color: var(--primary);
-  --choice-button-solid-background: var(--primary);
-  --choice-button-solid-color: var(--primary-foreground);
+
+  --choice-button-selected-color: initial;
+  --choice-button-selected-border-color: initial;
+  --choice-button-solid-background: initial;
+  --choice-button-solid-color: initial;
 
   --toggle-focus-ring-width: var(--stroke-lg);
   --toggle-focus-ring-alpha: 1;

package/dist/tokens/components/float-button.css

@@ -32,7 +32,7 @@
 
   --float-button-progress-offset: 0turn;
   --float-button-progress-width: var(--space-1);
-  --float-button-progress-color: hsl(var(--primary));
+  --float-button-progress-color: initial;
   --float-button-progress-track-color: hsl(var(--border));
 
   --float-button-motion-translate: var(--float-button-size);

package/dist/tokens/components/segmented.css

@@ -17,7 +17,7 @@
   --segmented-item-hover-color: var(--foreground);
   --segmented-item-selected-color: var(--foreground);
 
-  --segmented-item-hover-background: var(--accent);
+  --segmented-item-hover-background: initial;
   --segmented-item-active-background: var(--secondary);
 
   --segmented-item-selected-background: var(--background);

package/dist/tokens/components/shell.css

@@ -110,8 +110,8 @@
   --topbar-item-radius: var(--radius-sharp);
   --topbar-item-color: var(--muted-foreground);
 
-  --topbar-item-hover-background: var(--accent);
-  --topbar-item-hover-color: var(--accent-foreground);
+  --topbar-item-hover-background: initial;
+  --topbar-item-hover-color: initial;
   --topbar-item-active-background: var(--secondary);
 
   --topbar-item-badge-offset-block: var(--space-1);
@@ -158,8 +158,8 @@
   --app-launcher-tile-min-height: var(--control-height-comfortable);
   --app-launcher-tile-radius: var(--radius);
   --app-launcher-tile-color: var(--foreground);
-  --app-launcher-tile-hover-background: var(--accent);
-  --app-launcher-tile-hover-color: var(--accent-foreground);
+  --app-launcher-tile-hover-background: initial;
+  --app-launcher-tile-hover-color: initial;
 
   --app-launcher-tile-current-background: initial;
   --app-launcher-mark-size: 2.5rem;

package/dist/tokens/foundation.css

@@ -100,19 +100,16 @@
 
   --shadow-glow: 0 0 0 0 transparent;
 
-  --brand-glow-color: var(--primary);
+  --brand-glow-color: initial;
   --brand-glow-alpha: 0.18;
   --brand-glow-size: 60% 50%;
   --brand-glow-position: 50% 0%;
-  --brand-glow: radial-gradient(
-    ellipse var(--brand-glow-size) at var(--brand-glow-position),
-    hsl(var(--brand-glow-color) / var(--brand-glow-alpha)),
-    transparent 70%
-  );
+  --brand-glow: initial;
 
   --focus-outline: 1;
   --focus-outline-weight: var(--stroke-hairline);
-  --focus-outline-color: var(--focus-ring-color, var(--ring));
+
+  --focus-outline-color: initial;
 
   --control-outline-width: calc(var(--stroke-md) * var(--focus-outline));
   --focus-outline-offset: 0px;

package/docs/CUSTOMER-THEMING.md

@@ -243,6 +243,9 @@ The interaction states are **derived from the `--primary` in scope, at the eleme
 | `--control-outline` | **yes** — the focused field's halo (`--control-outline-alpha` stays per theme) | light `h s calc(l - 5.3)`, dark `h calc(s * 0.99) calc(l - 25.1)` |
 | `--primary-border` | **yes** (painted by no package surface; kept for the measurement in DESIGN-AUTHORITY) | light `h calc(s * 0.68) calc(l + 16)`, dark `h calc(s * 0.467) calc(l * 0.27043)` |
 | `--sidebar-item-active-foreground` | **yes** — defaults to the live `--primary-active` | — |
+| `--focus-outline-color` | **yes, through `--ring`** — every keyboard-focus outline (gh#687) | `var(--focus-ring-color, var(--ring))`, read at the focused element — so it follows the `--ring` you set in the scope |
+| Radio button bar selected (`--choice-button-*`), Slider active dot, BackTop progress, `.ui-brand-glow` | **yes** (gh#687) | `var(--primary)` / `var(--primary-foreground)` at the call site |
+| Topbar item / AppLauncher tile / Segmented / filled-control hover | **follow `--accent`** (gh#687) | `var(--accent)` / `var(--accent-foreground)` at the call site |
 | `--primary-foreground` | **no — set it** | the label on a filled primary; you choose it for your seed |
 | `--ring` | **only on the element that declares `--primary`** — set it in a nested scope | `var(--primary)` on `:root` / `.dark`. `--ring` is a public role read as `hsl(var(--ring))` in consumer CSS, so it cannot become a live default; a scope below `<html>` inherits the root's |
 | `--destructive-*`, `--control-outline-error` | no — not brand | literals |
@@ -251,6 +254,7 @@ On the package seed these produce exactly the identity kit values the tier used
 
 **Rules that come with it:**
 
+- **No token tier binds to a scoped role at `:root`.** Every knob whose default is `--primary`, `--primary-foreground`, `--ring`, `--accent` or `--accent-foreground` is `initial`, with the role as the call-site fallback — `--ring` itself is the one exception (above). `tenant-scope-freeze-687.test.ts` holds it.
 - **Override a state only by setting its knob** (`--primary-hover: 221 90% 72%`). A set knob wins over the derived default, in its own scope and below.
 - **Read a state through its fallback, not bare.** The four knobs are `initial` so that the default can resolve at the painting element (docs/TOKENS.md, the freeze rule). `hsl(var(--primary-hover))` on its own therefore paints nothing — use the utility (`bg-primary-hover`) or `hsl(var(--primary-hover, from hsl(var(--primary)) var(--primary-hover-channels)))`.
 - **Label polarity.** The theme's pair steps AWAY from that theme's default label: `darken` under a light label, `lighten` under a dark one, which keeps a label that clears 4.5:1 at rest at 4.5:1 in hover and pressed for every seed (measured, `derived-seed-sweep.test.ts`). If your seed needs the OTHER polarity of label (a pale yellow with dark text in the light theme), point the pair at it too — `applyPrimaryColor()` does this automatically from the label it picks:

package/docs/layout/app-shell-states.tsx

@@ -3,6 +3,7 @@ import { AppShell, Flex, PageContainer, Sidebar, Topbar } from "@godxjp/ui/layou
 import type { SidebarSectionProp } from "@godxjp/ui/layout";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
 import { Button, Text } from "@godxjp/ui/general";
+import { Input } from "@godxjp/ui/data-entry";
 import {
   Bell,
   Building2,
@@ -24,11 +25,13 @@ import {
  * single page:
  *
  *   ?topbarSpan=content|full   ?navRail=start|end|top|bottom   ?collapsed=1   ?sidebar=none
- *   ?responsive=docked   ?measure=narrow|medium   ?footer=1
+ *   ?responsive=docked   ?measure=narrow|medium   ?footer=1|row
  *
  * `measure` and `footer` feed `scripts/check-app-shell-page-width.mjs` (gh#672): the page is fluid
  * in the main column at every sidebar state, and a sticky footer band always spans `.app-main`,
  * even when a service caps content with `--app-shell-page-max-width` or the page sets `measure`.
+ * The footer's CONTENT sits in the same column as the body (gh#682), so the two shapes a footer
+ * takes are both rendered: `footer=1` an end-aligned action group, `footer=row` a full-row composer.
  *
  * With no query it is `topbarSpan="full"` without a rail — the state gh#474 found collapsing
  * `main` into a 170px implicit track below 900px, with the page actions laid out past the edge.
@@ -66,12 +69,12 @@ function readState() {
     responsiveNavigation:
       params.get("responsive") === "docked" ? ("docked" as const) : ("drawer" as const),
     measure: (["narrow", "medium"] as const).find((m) => m === params.get("measure")),
-    hasFooter: params.get("footer") === "1",
+    footer: (["1", "row"] as const).find((f) => f === params.get("footer")),
   };
 }
 
 export default function Demo() {
-  const [{ topbarSpan, navRail, collapsed, hasSidebar, responsiveNavigation, measure, hasFooter }] =
+  const [{ topbarSpan, navRail, collapsed, hasSidebar, responsiveNavigation, measure, footer }] =
     useState(readState);
   const [activeId, setActiveId] = useState("dashboard");
   const strip = navRail === "top" || navRail === "bottom";
@@ -121,16 +124,23 @@ export default function Demo() {
         subtitle="株式会社アクメ · 2026年5月"
         measure={measure}
         footer={
-          hasFooter ? (
+          footer === "1" ? (
             <Flex gap="sm" align="center" justify="end">
               <Button size="sm" variant="outline">
                 下書き保存
               </Button>
               <Button size="sm">コメントを送信する</Button>
             </Flex>
+          ) : footer === "row" ? (
+            <Flex grow gap="sm" align="center">
+              <Flex grow>
+                <Input aria-label="コメント" placeholder="コメントを入力" />
+              </Flex>
+              <Button size="sm">送信</Button>
+            </Flex>
           ) : undefined
         }
-        stickyFooter={hasFooter}
+        stickyFooter={footer !== undefined}
         extra={
           <Flex gap="sm" wrap>
             <Button size="sm" variant="outline">

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "26.0.0",
-  "godxUiMcp": "26.0.0",
+  "version": "26.2.0",
+  "godxUiMcp": "26.2.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/scripts/_agent-setup.mjs

@@ -45,6 +45,19 @@ function mcpEntryMatches(a, b) {
   return keysA.every((k) => envA[k] === envB[k]);
 }
 
+/**
+ * True when `entry` is the shape THIS package writes (`npx @godxjp/ui-mcp@<pin>`, env at most
+ * GODX_UI_VERSION), whatever pin and version it carries. Such an entry is ours to move forward on
+ * upgrade: treating it as custom left consumers on the MCP of the release they first installed
+ * (a `@godxjp/ui-mcp@25.4.0` pin survived the upgrade to 26.x).
+ */
+function isPackageWrittenMcpEntry(entry) {
+  if (entry?.command !== "npx") return false;
+  const args = entry.args ?? [];
+  if (args.length !== 1 || !/^@godxjp\/ui-mcp@[^\s]+$/.test(args[0])) return false;
+  return Object.keys(entry.env ?? {}).every((key) => key === "GODX_UI_VERSION");
+}
+
 function mcpConfigMismatchMessage(root, existing, expected) {
   const ui = readConsumerUiMetadata(root);
   const pin = expected.args?.[0] ?? "@godxjp/ui-mcp";
@@ -347,7 +360,11 @@ export function refreshBlock(current, next, startMarker, endMarker) {
   if (!endMarker) return null;
   const j = current.indexOf(endMarker, first);
   if (j < 0) return null;
-  return current.slice(0, first) + next + current.slice(j + endMarker.length);
+  // `next` ends in its own newline, and the old block's newline is still the first character after
+  // the end marker — keeping both grew the file by one blank line on every refresh.
+  let tail = current.slice(j + endMarker.length);
+  if (next.endsWith("\n") && tail.startsWith("\n")) tail = tail.slice(1);
+  return current.slice(0, first) + next + tail;
 }
 
 export function ensureMcpJson(root) {
@@ -369,10 +386,13 @@ export function ensureMcpJson(root) {
   }
   json.mcpServers = json.mcpServers ?? {};
   if (json.mcpServers[MCP_KEY]) {
-    if (!mcpEntryMatches(json.mcpServers[MCP_KEY], expected)) {
+    if (mcpEntryMatches(json.mcpServers[MCP_KEY], expected)) return "present";
+    if (!isPackageWrittenMcpEntry(json.mcpServers[MCP_KEY])) {
       return mcpConfigMismatchMessage(root, json.mcpServers[MCP_KEY], expected);
     }
-    return "present";
+    json.mcpServers[MCP_KEY] = expected;
+    writeFileAtomic(path, JSON.stringify(json, null, 2) + "\n");
+    return "refreshed";
   }
   const created = read.state === "missing";
   json.mcpServers[MCP_KEY] = expected;

package/scripts/cli.mjs

@@ -18,13 +18,74 @@ const MAP = {
   "visual-audit": "visual-audit.mjs",
 };
 
+// `<command> --help` is answered HERE: the scripts take free positional arguments, so a `--help`
+// forwarded to ui-audit used to be read as nothing and ran a full audit instead of printing help.
+const HELP = {
+  "init-agent": `godxjp-ui init-agent
+
+  Install the agent forcing-kit into the current consumer app (run it from the app root):
+    .mcp.json                  the godx-ui MCP server
+    .claude/settings.json      a PostToolUse hook that audits every Write/Edit of a .tsx file
+    .claude/godxjp-ui-workflow.md
+    CLAUDE.md                  the godxjp-ui mandate block
+  Idempotent. Refuses inside the @godxjp/ui repo itself. Restart the agent afterwards.`,
+  "sync-rules": `godxjp-ui sync-rules
+
+  Refresh the package-owned agent files for the installed @godxjp/ui version: the godx-ui entry in
+  .mcp.json, the managed CLAUDE.md block, .claude/godxjp-ui-workflow.md and .ai/rules/godxjp-ui.md.
+  It is the postinstall step, run by hand — use it when the app installs with ignore-scripts=true,
+  where postinstall never runs and the rules go stale. Silent no-op in CI and when opted out.`,
+  audit: `godxjp-ui audit [dir …] [--changed] [--format json] [--quiet] [--rules]
+
+  Static UI-standardization audit over source (regex, no browser, fast). Exits non-zero on errors.
+    dir …           directories or files to scan
+    --changed       scan what this branch changed vs origin/main (committed, staged, untracked);
+                    fails rather than reporting clean when origin/main cannot be resolved
+    --format json   machine-readable findings
+    --quiet         print errors only (warnings hidden)
+    --rules         print the rule catalog as JSON and exit
+  Pre-commit:  npx godxjp-ui audit resources/js || exit 1`,
+  "visual-audit": `godxjp-ui visual-audit [--format json] [--strict] <baseUrl> [route …]
+
+  Runtime audit (Playwright + axe-core) against an app you are ALREADY running locally.
+    baseUrl         the running app, e.g. http://localhost:5173
+    route …         paths appended to baseUrl (default "/")
+    --strict        exit non-zero on any finding, not only errors
+    --format json   machine-readable findings
+    --rules         print the visual rule catalog as JSON and exit
+  Needs the playwright peer installed.`,
+};
+
+const USAGE = `usage: godxjp-ui <command> [args]
+
+commands:
+  init-agent     install the agent forcing-kit (MCP + auto-audit hook + CLAUDE.md mandate)
+  sync-rules     refresh package-owned agent rules (postinstall, by hand)
+  audit          static UI audit over source
+  visual-audit   runtime audit (Playwright + axe-core) against a running app
+
+godxjp-ui <command> --help   details and flags for one command`;
+
+const isHelp = (arg) => arg === "--help" || arg === "-h" || arg === "help";
 const [cmd, ...rest] = process.argv.slice(2);
+
+if (cmd === undefined || isHelp(cmd)) {
+  const topic = isHelp(cmd) ? rest[0] : undefined;
+  console.log(topic && HELP[topic] ? HELP[topic] : USAGE);
+  process.exit(cmd === undefined ? 1 : 0);
+}
 const script = MAP[cmd];
 if (!script) {
-  console.error("usage: godxjp-ui <init-agent | sync-rules | audit | visual-audit> [args]");
+  console.error(`unknown command: ${cmd}\n\n${USAGE}`);
   process.exit(1);
 }
+if (rest.includes("--help") || rest.includes("-h")) {
+  console.log(HELP[cmd]);
+  process.exit(0);
+}
 const env =
-  cmd === "sync-rules" ? { ...process.env, INIT_CWD: process.env.INIT_CWD ?? process.cwd() } : process.env;
+  cmd === "sync-rules"
+    ? { ...process.env, INIT_CWD: process.env.INIT_CWD ?? process.cwd() }
+    : process.env;
 const r = spawnSync("node", [join(HERE, script), ...rest], { stdio: "inherit", env });
 process.exit(r.status ?? 0);