@godxjp/ui 26.1.0 → 26.3.0

package/dist/components/data-entry/chat-composer.d.ts

@@ -31,6 +31,7 @@ export declare const ChatComposer: React.ForwardRefExoticComponent<Omit<React.HT
     onCancel?: () => void;
     loading?: import("../../props/index.js").PendingProp;
     submitType?: import("./chat-composer.js").ChatComposerSubmitTypeProp;
+    allowEmptySubmit?: boolean;
     placeholder?: import("../../props/index.js").PlaceholderProp;
     disabled?: import("../../props/index.js").DisabledProp;
     readOnly?: boolean;

package/dist/components/data-entry/chat-composer.js

@@ -4,6 +4,7 @@ import * as React from "react";
 import { SendHorizontal, Square } from "lucide-react";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { cn } from "../../lib/utils.js";
+import { isApplePlatform } from "../../lib/platform.js";
 import { omitFieldA11y, pickFieldA11y, useFieldIdentity } from "../../lib/field-a11y.js";
 import { Button } from "../general/button.js";
 import { Textarea } from "./textarea.js";
@@ -23,6 +24,7 @@ const ChatComposer = React.forwardRef(
     onCancel,
     loading = false,
     submitType = "enter",
+    allowEmptySubmit = false,
     placeholder,
     disabled = false,
     readOnly = false,
@@ -57,12 +59,13 @@ const ChatComposer = React.forwardRef(
     const rest = omitFieldA11y(props);
     const identity = useFieldIdentity({ id, name, "data-field": props["data-field"] });
     const surface = controlSurfaceAttrs({ status, size });
-    const canSubmit = isSendable(draft) && !disabled && !readOnly && !loading;
+    const canSubmit = (allowEmptySubmit || isSendable(draft)) && !disabled && !readOnly && !loading;
     const submit = React.useCallback(() => {
+      if (disabled || readOnly || loading) return;
       const text = innerRef.current?.value ?? draft;
-      if (!isSendable(text) || disabled || readOnly || loading) return;
-      onSubmit?.(text);
-    }, [draft, disabled, readOnly, loading, onSubmit]);
+      if (isSendable(text)) onSubmit?.(text);
+      else if (allowEmptySubmit) onSubmit?.("");
+    }, [draft, disabled, readOnly, loading, allowEmptySubmit, onSubmit]);
     const handleKeyDown = (event) => {
       onKeyDown?.(event);
       if (event.defaultPrevented) return;
@@ -70,7 +73,11 @@ const ChatComposer = React.forwardRef(
       if (composing.current || event.nativeEvent.isComposing || event.nativeEvent.keyCode === 229) {
         return;
       }
-      const wantsSend = submitType === "enter" ? !event.shiftKey : event.shiftKey;
+      const wantsSend = submitType === "modEnter" ? (
+        // ⌘ on Apple platforms, Ctrl everywhere else — the other one is left alone, because
+        // Ctrl+Enter on a Mac is not the convention a Mac user reaches for.
+        isApplePlatform() ? event.metaKey : event.ctrlKey
+      ) : submitType === "enter" ? !event.shiftKey : event.shiftKey;
       if (!wantsSend) return;
       event.preventDefault();
       submit();

package/dist/components/query/mutation-feedback.d.ts

@@ -3,5 +3,7 @@ export type { AlertMutationFeedbackProp, AlertMutationFeedbackProp as AlertMutat
 /**
  * Inline mutation error — renders nothing when idle/success.
  * Prefer toast for transient saves; use this for blocking form sections (SimulatorPage).
+ * Inside a form that received a server error bag (`FormRoot errors` / `Form errors`), a validation
+ * error is the fields' to show, so it is skipped by default (gh#690).
  */
-export declare function AlertMutationFeedback({ mutation, onRetry, showRetry, pending, className, }: AlertMutationFeedbackProp): import("react").JSX.Element | null;
+export declare function AlertMutationFeedback({ mutation, onRetry, showRetry, pending, ignoreValidationErrors, className, }: AlertMutationFeedbackProp): import("react").JSX.Element | null;

package/dist/components/query/mutation-feedback.js

@@ -1,15 +1,25 @@
 "use client";
 import { Fragment, jsx } from "react/jsx-runtime";
 import { AlertQueryError } from "../feedback/alert.js";
+import { useFormErrorsRegistry } from "../data-entry/form-errors.js";
+import { classifyQueryError } from "../../lib/query-error.js";
 function AlertMutationFeedback({
   mutation,
   onRetry,
   showRetry = true,
   pending,
+  ignoreValidationErrors,
   className
 }) {
+  const registry = useFormErrorsRegistry();
+  const bagShowsErrors = registry !== null && Object.values(registry.errors).some(
+    (entry) => Array.isArray(entry) ? entry.some(Boolean) : Boolean(entry)
+  );
   if (mutation.isPending && pending) return /* @__PURE__ */ jsx(Fragment, { children: pending });
   if (!mutation.isError || mutation.error == null) return null;
+  if ((ignoreValidationErrors ?? bagShowsErrors) && classifyQueryError(mutation.error).category === "validation") {
+    return null;
+  }
   return /* @__PURE__ */ jsx(
     AlertQueryError,
     {

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.1.0",
+  "version": "26.3.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/i18n/messages/en.json

@@ -169,7 +169,8 @@
       "send": "Send message",
       "cancel": "Stop generating",
       "hintEnter": "Enter to send · Shift + Enter for a new line",
-      "hintShiftEnter": "Shift + Enter to send · Enter for a new line"
+      "hintShiftEnter": "Shift + Enter to send · Enter for a new line",
+      "hintModEnter": "{modifier} + Enter to send · Enter for a new line"
     },
     "chatSuggestion": {
       "label": "Suggestions",

package/dist/i18n/messages/ja.json

@@ -166,7 +166,8 @@
       "send": "メッセージを送信",
       "cancel": "生成を停止",
       "hintEnter": "Enter で送信 · Shift + Enter で改行",
-      "hintShiftEnter": "Shift + Enter で送信 · Enter で改行"
+      "hintShiftEnter": "Shift + Enter で送信 · Enter で改行",
+      "hintModEnter": "{modifier} + Enter で送信 · Enter で改行"
     },
     "chatSuggestion": {
       "label": "候補",

package/dist/i18n/messages/vi.json

@@ -166,7 +166,8 @@
       "send": "Gửi tin nhắn",
       "cancel": "Dừng tạo câu trả lời",
       "hintEnter": "Enter để gửi · Shift + Enter để xuống dòng",
-      "hintShiftEnter": "Shift + Enter để gửi · Enter để xuống dòng"
+      "hintShiftEnter": "Shift + Enter để gửi · Enter để xuống dòng",
+      "hintModEnter": "{modifier} + Enter để gửi · Enter để xuống dòng"
     },
     "chatSuggestion": {
       "label": "Gợi ý",

package/dist/lib/platform.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether the user agent runs on an Apple platform (macOS, iOS, iPadOS), where the primary
+ * shortcut modifier is ⌘ (`metaKey`) rather than Ctrl (`ctrlKey`).
+ *
+ * `navigator.userAgentData.platform` is the standards answer (Chromium); `navigator.platform` is
+ * the deprecated but universally present fallback (Safari and Firefox still report `MacIntel` /
+ * `iPhone` / `iPad` there). Outside a browser there is no platform, so the answer is `false` — a
+ * server render therefore describes the Ctrl shortcut.
+ */
+export declare function isApplePlatform(): boolean;

package/dist/lib/platform.js

@@ -0,0 +1,9 @@
+function isApplePlatform() {
+  if (typeof navigator === "undefined") return false;
+  const data = navigator.userAgentData;
+  const platform = data?.platform || navigator.platform || "";
+  return /mac|iphone|ipad|ipod/i.test(platform);
+}
+export {
+  isApplePlatform
+};

package/dist/lib/utils.d.ts

@@ -1,2 +1,3 @@
 import { type ClassValue } from "clsx";
 export declare function cn(...inputs: ClassValue[]): string;
+export { isApplePlatform } from "./platform.js";

package/dist/lib/utils.js

@@ -3,6 +3,8 @@ import { twMerge } from "tailwind-merge";
 function cn(...inputs) {
   return twMerge(clsx(inputs));
 }
+import { isApplePlatform } from "./platform.js";
 export {
-  cn
+  cn,
+  isApplePlatform
 };

package/dist/props/components/data-entry.prop.d.ts

@@ -294,9 +294,9 @@ export type FormFieldProp = {
      *
      * `before` is for a helper the reader needs BEFORE they answer rather than after: the
      * secondary language of a bilingual form, a unit or format note, a pick-one-of-these
-     * preamble. `labelAddon` cannot carry that — it is an inline row beside the label with no
-     * wrap, sized for a chip or a help button, so a full sentence squeezes the label instead of
-     * taking its own line. Putting the second line inside `label` does work, but costs the
+     * preamble. `labelAddon` cannot carry that — it belongs to the label row, sized for a chip, a
+     * help button or a short text action; in a horizontal/inline field it wraps under the label
+     * inside the label column, so a full sentence stacks there instead of above the input. Putting the second line inside `label` does work, but costs the
      * string-label fallbacks (`aria-label`, `FieldNameContext`), which fire only when `label` is
      * a plain string.
      *
@@ -308,7 +308,11 @@ export type FormFieldProp = {
     validateStatus?: "success" | "warning" | "error" | "validating";
     hasFeedback?: boolean;
     feedback?: React.ReactNode;
-    /** Optional control rendered inline after the label (e.g. a help button). */
+    /**
+     * Optional control rendered after the label (e.g. a help button, a short text action). In a
+     * horizontal/inline field the label row wraps: an addon that does not fit beside the label
+     * drops to its own line under it, capped to the label column, never into the control column.
+     */
     labelAddon?: React.ReactNode;
     /** Override the Form's layout for this field only. */
     layout?: FormLayoutProp;
@@ -341,9 +345,9 @@ export type FormFieldProp = {
      *
      * `before` is for a helper the reader needs BEFORE they answer rather than after: the
      * secondary language of a bilingual form, a unit or format note, a pick-one-of-these
-     * preamble. `labelAddon` cannot carry that — it is an inline row beside the label with no
-     * wrap, sized for a chip or a help button, so a full sentence squeezes the label instead of
-     * taking its own line. Putting the second line inside `label` does work, but costs the
+     * preamble. `labelAddon` cannot carry that — it belongs to the label row, sized for a chip, a
+     * help button or a short text action; in a horizontal/inline field it wraps under the label
+     * inside the label column, so a full sentence stacks there instead of above the input. Putting the second line inside `label` does work, but costs the
      * string-label fallbacks (`aria-label`, `FieldNameContext`), which fire only when `label` is
      * a plain string.
      *
@@ -355,7 +359,11 @@ export type FormFieldProp = {
     validateStatus?: "success" | "warning" | "error" | "validating";
     hasFeedback?: boolean;
     feedback?: React.ReactNode;
-    /** Optional control rendered inline after the label (e.g. a help button). */
+    /**
+     * Optional control rendered after the label (e.g. a help button, a short text action). In a
+     * horizontal/inline field the label row wraps: an addon that does not fit beside the label
+     * drops to its own line under it, capped to the label column, never into the control column.
+     */
     labelAddon?: React.ReactNode;
     /** Override the Form's layout for this field only. */
     layout?: FormLayoutProp;
@@ -1774,10 +1782,13 @@ export type BranchScopePickerProp = FieldA11yProps & {
  *
  * `enter` (default) is the chat convention: `Enter` sends, `Shift+Enter` inserts a newline.
  * `shiftEnter` is the inverse, for composers that hold long, deliberately multi-line drafts.
- * Neither ever fires while an IME conversion is in flight.
+ * `modEnter` is this library's extension (antd X has only the first two; see
+ * docs/DESIGN-AUTHORITY.md): `⌘+Enter` on Apple platforms, `Ctrl+Enter` elsewhere sends, while
+ * `Enter` and `Shift+Enter` both insert a newline — the record-comment convention.
+ * None of them ever fires while an IME conversion is in flight.
  * @see ChatComposer
  */
-export type ChatComposerSubmitTypeProp = "enter" | "shiftEnter";
+export type ChatComposerSubmitTypeProp = "enter" | "shiftEnter" | "modEnter";
 /**
  * @see ChatComposer — the message input of a conversation (Ant Design X `Sender`; the industry
  * calls the control a *composer*, so that is what it is named).
@@ -1797,7 +1808,8 @@ export type ChatComposerProp = Omit<React.HTMLAttributes<HTMLDivElement>, "onSub
     onValueChange?: OnValueChangeProp<string>;
     /**
      * Send the draft. Receives the text as typed; never fires for an empty or whitespace-only
-     * draft, and never while `loading`, `disabled` or `readOnly`.
+     * draft (unless `allowEmptySubmit`, which then passes `""`), and never while `loading`,
+     * `disabled` or `readOnly`.
      */
     onSubmit?: (value: string) => void;
     /** Stop the in-flight response. Only reachable while `loading`. */
@@ -1809,6 +1821,13 @@ export type ChatComposerProp = Omit<React.HTMLAttributes<HTMLDivElement>, "onSub
     loading?: PendingProp;
     /** Which keystroke sends and which breaks the line. Default `enter`. */
     submitType?: ChatComposerSubmitTypeProp;
+    /**
+     * Let an empty or whitespace-only draft be sent — for a composer whose `header`/`footer` carry
+     * payload of their own (a status change on a record). The send button stays enabled and both
+     * the button and the keyboard submit call `onSubmit("")`. Still blocked while `loading`,
+     * `disabled` or `readOnly`. Default `false`.
+     */
+    allowEmptySubmit?: boolean;
     /** Empty-state text of the draft box; pass it through `t()` at the call site. */
     placeholder?: PlaceholderProp;
     /** Disable the whole composer (draft box and every action). */

package/dist/props/components/query.prop.d.ts

@@ -31,6 +31,13 @@ export type AlertMutationFeedbackProp = {
     showRetry?: boolean;
     /** Optional inline pending slot while `mutation.isPending`. */
     pending?: React.ReactNode;
+    /**
+     * Skip rendering when the error classifies as a validation error (`classifyQueryError` category
+     * `"validation"`: 400/422). `true` skips every such error. When omitted, the alert is skipped only
+     * inside a `FormRoot`/`Form` whose `errors` bag holds at least one message (the fields show it;
+     * `FormErrors` shows unclaimed keys); an empty/absent bag still renders the alert.
+     */
+    ignoreValidationErrors?: boolean;
     className?: ClassNameProp;
 };
 type QueryRefetchLike = Pick<UseQueryResult<unknown>, "isFetching" | "refetch">;

package/dist/props/registry.d.ts

@@ -2048,6 +2048,10 @@ export declare const COMPONENT_PROP_REGISTRY: {
             readonly field: "pending";
             readonly local: true;
             readonly reason: "Inline pending ReactNode slot, not boolean PendingProp state.";
+        }, {
+            readonly field: "ignoreValidationErrors";
+            readonly local: true;
+            readonly reason: "Query-error category filter; defaults on inside a Form whose error bag holds messages.";
         }, "ClassNameProp"];
     };
     readonly ButtonRefetchProp: {

package/dist/props/registry.js

@@ -2401,6 +2401,11 @@ const COMPONENT_PROP_REGISTRY = {
         local: true,
         reason: "Inline pending ReactNode slot, not boolean PendingProp state."
       },
+      {
+        field: "ignoreValidationErrors",
+        local: true,
+        reason: "Query-error category filter; defaults on inside a Form whose error bag holds messages."
+      },
       "ClassNameProp"
     ]
   },

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/form-layout.css

@@ -99,9 +99,16 @@
     column-gap: var(--form-label-gap);
     row-gap: var(--space-stack-xs);
   }
+
   .ui-form-field[data-collapse-below="false"]:is([data-layout="horizontal"], [data-layout="inline"])
     > .ui-form-field-label {
     min-block-size: var(--control-height);
+    flex-wrap: wrap;
+  }
+  .ui-form-field[data-collapse-below="false"]:is([data-layout="horizontal"], [data-layout="inline"])
+    > .ui-form-field-label
+    > * {
+    max-inline-size: 100%;
   }
   .ui-form-field[data-collapse-below="false"][data-label-align="end"]:is(
       [data-layout="horizontal"],
@@ -125,6 +132,12 @@
     .ui-form-field[data-collapse-below="sm"]:is([data-layout="horizontal"], [data-layout="inline"])
       > .ui-form-field-label {
       min-block-size: var(--control-height);
+      flex-wrap: wrap;
+    }
+    .ui-form-field[data-collapse-below="sm"]:is([data-layout="horizontal"], [data-layout="inline"])
+      > .ui-form-field-label
+      > * {
+      max-inline-size: 100%;
     }
     .ui-form-field[data-collapse-below="sm"][data-label-align="end"]:is(
         [data-layout="horizontal"],
@@ -149,6 +162,12 @@
     .ui-form-field[data-collapse-below="md"]:is([data-layout="horizontal"], [data-layout="inline"])
       > .ui-form-field-label {
       min-block-size: var(--control-height);
+      flex-wrap: wrap;
+    }
+    .ui-form-field[data-collapse-below="md"]:is([data-layout="horizontal"], [data-layout="inline"])
+      > .ui-form-field-label
+      > * {
+      max-inline-size: 100%;
     }
     .ui-form-field[data-collapse-below="md"][data-label-align="end"]:is(
         [data-layout="horizontal"],
@@ -173,6 +192,12 @@
     .ui-form-field[data-collapse-below="lg"]:is([data-layout="horizontal"], [data-layout="inline"])
       > .ui-form-field-label {
       min-block-size: var(--control-height);
+      flex-wrap: wrap;
+    }
+    .ui-form-field[data-collapse-below="lg"]:is([data-layout="horizontal"], [data-layout="inline"])
+      > .ui-form-field-label
+      > * {
+      max-inline-size: 100%;
     }
     .ui-form-field[data-collapse-below="lg"][data-label-align="end"]:is(
         [data-layout="horizontal"],
@@ -197,6 +222,12 @@
     .ui-form-field[data-collapse-below="xl"]:is([data-layout="horizontal"], [data-layout="inline"])
       > .ui-form-field-label {
       min-block-size: var(--control-height);
+      flex-wrap: wrap;
+    }
+    .ui-form-field[data-collapse-below="xl"]:is([data-layout="horizontal"], [data-layout="inline"])
+      > .ui-form-field-label
+      > * {
+      max-inline-size: 100%;
     }
     .ui-form-field[data-collapse-below="xl"][data-label-align="end"]:is(
         [data-layout="horizontal"],

package/dist/styles/layout.css

@@ -96,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;
   }
 

package/dist/styles/shell-layout.css

@@ -1434,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"] {
@@ -2040,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/DESIGN-AUTHORITY.md

@@ -257,6 +257,15 @@ in page CSS.
   `onClose`, because `onClose` already means overlay dismiss across Dialog/Drawer and would read
   as closing a surface, not removing one applied filter chip. Implemented on `Badge` — the DS chip
   primitive — rather than adding a separate `Tag` export beside `Badge`.
+- **`ChatComposer.submitType="modEnter"` and `ChatComposer.allowEmptySubmit`.** Ant Design X
+  `Sender.submitType` is only `"enter" | "shiftEnter"`, and `Sender` never submits an empty draft.
+  A comment composer on a record needs the convention GitHub, Jira, Linear and GitLab share —
+  `Enter` breaks the line, `⌘+Enter` (Apple platforms, `metaKey`) / `Ctrl+Enter` (elsewhere,
+  `ctrlKey`) sends — and needs to post a status change with no text (gh#693). `"modEnter"` extends
+  antd's union rather than renaming it, so both antd values keep their meaning; its hint is
+  `dataEntry.chatComposer.hintModEnter` with `{modifier}` from `isApplePlatform()`
+  (`@godxjp/ui/lib/utils`). `allowEmptySubmit` (default `false`, antd's behaviour) sends `""`,
+  still never while `loading` / `disabled` / `readOnly`.
 
 **A knob that only a fork could reach is not parity either.** antd's `components`,
 `filterDropdown`, `classNames`/`styles` semantic maps and `prefixCls` all exist to let a consumer

package/docs/data-entry/chat-composer.tsx

@@ -14,9 +14,12 @@ import {
   ChatComposer,
   ChatSuggestion,
   FormField,
+  Select,
   type ChatSuggestionItemProp,
 } from "@godxjp/ui/data-entry";
 import { Button, Text } from "@godxjp/ui/general";
+import { useTranslation } from "@godxjp/ui/i18n";
+import { isApplePlatform } from "@godxjp/ui/lib/utils";
 import {
   AppShell,
   Flex,
@@ -34,7 +37,8 @@ import { Bot, MessageSquare, Paperclip, Settings, Smile, Sparkles, Users } from
  *
  * The first card is the real screen: a live assistant transcript whose composer sends, streams and
  * cancels, with `/` slash commands and `@` mentions wired to the same draft. Every card after it
- * exists so the whole API is visible AT REST — both `submitType` values, all four `size` steps,
+ * exists so the whole API is visible AT REST — every `submitType` value (including the record-
+ * comment bar: `modEnter` + `allowEmptySubmit`), all four `size` steps,
  * every slot, and each non-default state — without having to click anything.
  *
  * Composed only from real @godxjp/ui components.
@@ -91,6 +95,20 @@ const OPENING: Message[] = [
   },
 ];
 
+/** Record statuses for the comment bar — a status change is postable without any text. */
+const STATUSES = [
+  { value: "open", label: "未対応" },
+  { value: "inProgress", label: "処理中" },
+  { value: "resolved", label: "処理済み" },
+  { value: "closed", label: "完了" },
+];
+
+interface Comment {
+  id: number;
+  body: string;
+  status: string | null;
+}
+
 /** One transcript line. The message FEED is ChatBubbleList's job; here it only sets the scene. */
 function Line({ message }: { message: Message }) {
   const mine = message.author === "you";
@@ -110,6 +128,8 @@ function Line({ message }: { message: Message }) {
 }
 
 export default function Demo() {
+  const { t } = useTranslation();
+
   // ── Card 1: the live screen ───────────────────────────────────────────────────────────────
   const [messages, setMessages] = useState<Message[]>(OPENING);
   const [draft, setDraft] = useState("");
@@ -142,6 +162,24 @@ export default function Demo() {
   const [shiftDraft, setShiftDraft] = useState("Enter は改行、Shift + Enter で送信");
   const [lastSent, setLastSent] = useState<string>("—");
 
+  // ── Card 2b: the record-comment bar (modEnter + allowEmptySubmit) ──────────────────────────
+  const [commentDraft, setCommentDraft] = useState("");
+  const [status, setStatus] = useState("open");
+  const [savedStatus, setSavedStatus] = useState("open");
+  const [comments, setComments] = useState<Comment[]>([]);
+
+  function postComment(text: string) {
+    const changed = status !== savedStatus;
+    // An empty draft with no status change carries nothing — the consumer decides, not the box.
+    if (!text && !changed) return;
+    setComments((current) => [
+      ...current,
+      { id: current.length + 1, body: text, status: changed ? status : null },
+    ]);
+    setSavedStatus(status);
+    setCommentDraft("");
+  }
+
   // ── Card 3: the four size steps ───────────────────────────────────────────────────────────
   const [sizeDrafts, setSizeDrafts] = useState<Record<string, string>>({
     xs: "xs",
@@ -286,6 +324,68 @@ export default function Demo() {
             </CardContent>
           </Card>
 
+          {/* ── 2b. Record comment bar ───────────────────────────────────────────────────── */}
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>
+                submitType=&quot;modEnter&quot; · allowEmptySubmit · 課題へのコメント
+              </CardTitle>
+              <CardDescription>
+                Enter と Shift + Enter は改行、⌘ + Enter（Mac）/ Ctrl + Enter（Windows・Linux）で
+                投稿します。allowEmptySubmit により本文が空でも送信でき、ステータスだけを
+                変更できます（onSubmit には空文字が渡ります）。
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Flex direction="col" gap="md">
+                {comments.length === 0 ? (
+                  <Text size="sm" tone="muted">
+                    まだコメントはありません
+                  </Text>
+                ) : (
+                  comments.map((comment) => (
+                    <Flex key={comment.id} direction="col" gap="xs">
+                      {comment.status ? (
+                        <Badge tone="info">
+                          ステータス：
+                          {STATUSES.find((option) => option.value === comment.status)?.label}
+                        </Badge>
+                      ) : null}
+                      {comment.body ? <Text>{comment.body}</Text> : null}
+                    </Flex>
+                  ))
+                )}
+                <ChatComposer
+                  aria-label="課題へのコメント"
+                  submitType="modEnter"
+                  allowEmptySubmit
+                  value={commentDraft}
+                  onValueChange={setCommentDraft}
+                  onSubmit={postComment}
+                  placeholder="コメントを入力"
+                  submitLabel="コメントを投稿"
+                  footer={
+                    <Flex direction="row" gap="sm" align="center" justify="between" wrap>
+                      <Select
+                        size="sm"
+                        aria-label="ステータス"
+                        value={status}
+                        onValueChange={setStatus}
+                        clearable={false}
+                        options={STATUSES}
+                      />
+                      <Text size="xs" tone="muted">
+                        {t("dataEntry.chatComposer.hintModEnter", {
+                          modifier: isApplePlatform() ? "⌘" : "Ctrl",
+                        })}
+                      </Text>
+                    </Flex>
+                  }
+                />
+              </Flex>
+            </CardContent>
+          </Card>
+
           {/* ── 3. Every size step ───────────────────────────────────────────────────────── */}
           <Card>
             <CardHeader>

package/docs/query/mutation-feedback.tsx

@@ -4,15 +4,19 @@ import { QueryClient, QueryClientProvider, useMutation } from "@tanstack/react-q
 
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@godxjp/ui/data-display";
 import { FormField, Input } from "@godxjp/ui/data-entry";
+import { FormFieldControl, FormRoot, useZodForm } from "@godxjp/ui/form";
 import { Button } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
 import { AlertMutationFeedback } from "@godxjp/ui/query";
+import { z } from "zod";
 
 /**
  * AlertMutationFeedback · inline mutation error below a form's submit. Renders
  * NOTHING while idle/successful; surfaces the error + a retry when useMutation
  * fails. Composed from real @godxjp/ui + @tanstack/react-query. (This demo fires
- * the mutation once on mount so the error state is visible.)
+ * the mutation once on mount so the error state is visible.) Inside a FormRoot
+ * that received `errors`, a 400/422 validation error is skipped by default —
+ * the fields already show the bag — while a 5xx still renders the alert.
  */
 const queryClient = new QueryClient();
 
@@ -54,6 +58,59 @@ function Block() {
   );
 }
 
+type SaveError = Error & { status: number; errors?: Record<string, string[]> };
+
+function saveError(status: number, message: string, errors?: Record<string, string[]>) {
+  return Object.assign(new Error(message), { status, errors }) as SaveError;
+}
+
+const schema = z.object({ code: z.string() });
+
+function InFormBlock() {
+  const form = useZodForm(schema, { defaultValues: { code: "BTY-0012" } });
+  const mutation = useMutation<void, SaveError, number>({
+    mutationFn: async (status) => {
+      throw status === 422
+        ? saveError(422, "The given data was invalid.", {
+            code: ["取引先コードが重複しています"],
+          })
+        : saveError(500, "サーバーエラーが発生しました (500)");
+    },
+  });
+
+  useEffect(() => {
+    mutation.mutate(422);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle level={2}>取引先の登録 · FormRoot errors</CardTitle>
+        <CardDescription>
+          A 422 shows on the field only; a 500 still renders the alert.
+        </CardDescription>
+      </CardHeader>
+      <CardContent>
+        <FormRoot form={form} errors={mutation.error?.errors} onSubmit={() => mutation.mutate(422)}>
+          <FormFieldControl name="code" label="取引先コード">
+            {(field) => <Input {...field} value={String(field.value ?? "")} />}
+          </FormFieldControl>
+          <AlertMutationFeedback mutation={mutation} onRetry={() => mutation.mutate(500)} />
+          <Flex direction="row" wrap justify="end" gap="sm">
+            <Button variant="outline" type="button" onClick={() => mutation.mutate(500)}>
+              500 を再現
+            </Button>
+            <Button type="submit" loading={mutation.isPending}>
+              保存
+            </Button>
+          </Flex>
+        </FormRoot>
+      </CardContent>
+    </Card>
+  );
+}
+
 export default function Demo() {
   return (
     <QueryClientProvider client={queryClient}>
@@ -63,6 +120,7 @@ export default function Demo() {
       >
         <Flex direction="col" gap="lg">
           <Block />
+          <InFormBlock />
         </Flex>
       </PageContainer>
     </QueryClientProvider>

package/package.json

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

package/scripts/_agent-setup.mjs

@@ -45,12 +45,32 @@ function mcpEntryMatches(a, b) {
   return keysA.every((k) => envA[k] === envB[k]);
 }
 
-function mcpConfigMismatchMessage(root, existing, expected) {
+/**
+ * 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");
+}
+
+/** True when an `mcpServers` entry launches the catalog server, under any key or launcher flags. */
+function runsUiMcp(entry) {
+  const parts = [entry?.command, ...(Array.isArray(entry?.args) ? entry.args : [])];
+  return parts.some((part) => typeof part === "string" && /(^|\/)@godxjp\/ui-mcp(@|$)/.test(part));
+}
+
+function mcpConfigMismatchMessage(root, existing, expected, key = MCP_KEY) {
   const ui = readConsumerUiMetadata(root);
   const pin = expected.args?.[0] ?? "@godxjp/ui-mcp";
   const ver = ui?.version ?? "(unknown)";
   return (
-    `present (custom godx-ui MCP entry — not overwritten; expected ${pin} with ` +
+    `present (custom godx-ui MCP entry${key === MCP_KEY ? "" : ` under key "${key}"`} — not overwritten, ` +
+    `no duplicate added; expected ${pin} with ` +
     `env.GODX_UI_VERSION=${ver} from node_modules/@godxjp/ui)`
   );
 }
@@ -252,7 +272,18 @@ function readJsonFile(path) {
   // writing the result back is the same data loss by a different door, so it is a refusal too.
   if (json === null || typeof json !== "object" || Array.isArray(json))
     return { state: "wrong-shape" };
-  return { state: "ok", json };
+  return { state: "ok", json, indent: indentOf(raw) };
+}
+
+/**
+ * The indentation the file already uses — a tab, or the width of the first indented line — so a
+ * rewrite changes only the keys it touches. Re-serialising at a fixed 2 turned a one-entry edit
+ * into a whole-file diff in a repo formatted at 4 (gh#692).
+ */
+function indentOf(raw) {
+  const first = raw.match(/\n([ \t]+)\S/);
+  if (!first) return 2;
+  return first[1].startsWith("\t") ? "\t" : first[1].length;
 }
 
 /** The sentence that goes in the refusal, so a consumer knows which of the three it hit. */
@@ -347,7 +378,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) {
@@ -368,15 +403,25 @@ export function ensureMcpJson(root) {
     return refuseAndSuggest(path, suggested, "`mcpServers` is not an object");
   }
   json.mcpServers = json.mcpServers ?? {};
-  if (json.mcpServers[MCP_KEY]) {
-    if (!mcpEntryMatches(json.mcpServers[MCP_KEY], expected)) {
-      return mcpConfigMismatchMessage(root, json.mcpServers[MCP_KEY], expected);
+  const indent = read.state === "ok" ? read.indent : 2;
+  // The catalog server may already be registered under ANOTHER key — `godxjp-ui`, `ui`, whatever
+  // the repo chose. Looking only at MCP_KEY added a second copy of the same server beside it, at
+  // a different version (gh#692). Whatever key runs @godxjp/ui-mcp is the entry.
+  const key = json.mcpServers[MCP_KEY]
+    ? MCP_KEY
+    : Object.keys(json.mcpServers).find((name) => runsUiMcp(json.mcpServers[name]));
+  if (key) {
+    if (mcpEntryMatches(json.mcpServers[key], expected)) return "present";
+    if (!isPackageWrittenMcpEntry(json.mcpServers[key])) {
+      return mcpConfigMismatchMessage(root, json.mcpServers[key], expected, key);
     }
-    return "present";
+    json.mcpServers[key] = expected;
+    writeFileAtomic(path, JSON.stringify(json, null, indent) + "\n");
+    return "refreshed";
   }
   const created = read.state === "missing";
   json.mcpServers[MCP_KEY] = expected;
-  writeFileAtomic(path, JSON.stringify(json, null, 2) + "\n");
+  writeFileAtomic(path, JSON.stringify(json, null, indent) + "\n");
   return created ? "created" : "added";
 }
 
@@ -430,7 +475,7 @@ export function ensureClaudeHooks(root) {
     added.push("SessionStart:workflow-primer");
   }
 
-  writeFileAtomic(path, JSON.stringify(json, null, 2) + "\n");
+  writeFileAtomic(path, JSON.stringify(json, null, read.state === "ok" ? read.indent : 2) + "\n");
   return added;
 }
 

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);