@godxjp/ui 19.6.0 → 20.1.0

package/docs/navigation/pagination.tsx

@@ -235,6 +235,58 @@ export default function Demo() {
             />
           </CardContent>
         </Card>
+
+        {/* Ant Design parity surface — showQuickJumper / size / align / responsive */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>showQuickJumper · size · align (Ant Design パリティ)</CardTitle>
+            <CardDescription>
+              showQuickJumper はページ番号を直接入力するフィールド(Enter または goButton
+              で確定、範囲外はクランプ)。size=&quot;sm&quot; はバーに --control-height
+              を一度だけ再束縛するので、ページボタン・サイズ変更・ジャンプ欄が同時に縮む。align
+              は論理軸(start / center / end)。responsive は既定で有効で、モバイル幅では simple
+              形態に畳む。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="lg">
+              <div id="antd-pagination-jumper">
+                <Pagination
+                  ariaLabel="クイックジャンパー付きページネーション"
+                  value={3}
+                  total={95}
+                  pageSize={10}
+                  showTotal
+                  showSizeChanger
+                  showQuickJumper
+                  onValueChange={() => {}}
+                />
+              </div>
+              <div id="antd-pagination-sm">
+                <Pagination
+                  ariaLabel="小サイズ・中央寄せのページネーション"
+                  value={3}
+                  total={95}
+                  pageSize={10}
+                  size="sm"
+                  align="center"
+                  showQuickJumper={{ goButton: "移動" }}
+                  onValueChange={() => {}}
+                />
+              </div>
+              <div id="antd-pagination-start">
+                <Pagination
+                  ariaLabel="先頭寄せのページネーション"
+                  value={3}
+                  total={95}
+                  pageSize={10}
+                  align="start"
+                  onValueChange={() => {}}
+                />
+              </div>
+            </Flex>
+          </CardContent>
+        </Card>
       </Flex>
     </PageContainer>
   );

package/docs/navigation/steps.tsx

@@ -259,6 +259,43 @@ export default function Demo() {
             </Flex>
           </CardContent>
         </Card>
+
+        {/* Ant Design parity surface — percent + navigation */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>percent · navigation (Ant Design パリティ)</CardTitle>
+            <CardDescription>
+              percent は antd と同じく「現在ステップ」の進捗のみ(0–100
+              にクランプ)。マーカーの周りに確定アークを描き、role=&quot;progressbar&quot;
+              として読み上げられる。type=&quot;navigation&quot; は antd
+              のスラブ型ナビゲーションバーで、既定のヘアライン
+              コネクタは切られ、代わりにシェブロンで繋がる。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="lg">
+              <div id="antd-steps-percent">
+                <Steps
+                  value={1}
+                  percent={40}
+                  items={[{ title: "申込" }, { title: "審査" }, { title: "完了" }]}
+                />
+              </div>
+              <div id="antd-steps-navigation">
+                <Steps
+                  type="navigation"
+                  value={1}
+                  onValueChange={() => {}}
+                  items={[
+                    { title: "申込", description: "受付済" },
+                    { title: "審査", description: "書類確認中" },
+                    { title: "完了", description: "未着手" },
+                  ]}
+                />
+              </div>
+            </Flex>
+          </CardContent>
+        </Card>
       </Flex>
     </PageContainer>
   );

package/docs/navigation/tabs.tsx

@@ -46,6 +46,17 @@ const journalItems = [
 
 export default function Demo() {
   const [activeTab, setActiveTab] = useState("pending");
+  const [editableTabs, setEditableTabs] = useState([
+    { value: "je-0042", label: "JE-0042", content: <Text as="p">売上計上 ¥480,000</Text> },
+    { value: "je-0043", label: "JE-0043", content: <Text as="p">仕入計上 ¥120,000</Text> },
+    {
+      value: "je-0040",
+      label: "JE-0040 (固定)",
+      content: <Text as="p">給与支払 ¥2,800,000</Text>,
+      closable: false,
+    },
+  ]);
+  const [editableTab, setEditableTab] = useState("je-0042");
 
   return (
     <PageContainer
@@ -106,7 +117,7 @@ export default function Demo() {
             <CardTitle level={2}>320px stress · 長いローカライズラベル</CardTitle>
             <CardDescription>
               狭いコンテナでも長いラベルはクリップされず、水平タブリストが自身でスクロールする
-              。compact navigation への変換は Tabs API に存在しないため擬似実装しない —
+              。compact navigation への変換は Tabs API に存在しないため擬似実装しない ·
               スクロールが意図した縮退動作。
             </CardDescription>
           </CardHeader>
@@ -308,6 +319,91 @@ export default function Demo() {
             </Flex>
           </CardContent>
         </Card>
+
+        {/* Ant Design parity surface — editable-card + extra + centered + placement + size */}
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Editable card · onEdit / extra / hideAdd</CardTitle>
+            <CardDescription>
+              variant=&quot;editable-card&quot; は Ant Design の editable-card。タブ内の ×
+              はポインタ用ショートカット(aria-hidden)で、キーボードでは Delete /
+              Backspace(aria-keyshortcuts)。追加ボタンは tablist の外にある本物の button。extra は
+              antd の tabBarExtraContent を論理軸(start / end)にしたもの。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Tabs
+              id="antd-editable-card"
+              variant="editable-card"
+              value={editableTab}
+              onValueChange={setEditableTab}
+              onEdit={(target, action) => {
+                if (action === "add") {
+                  const next = `tab-${editableTabs.length + 1}`;
+                  setEditableTabs([
+                    ...editableTabs,
+                    {
+                      value: next,
+                      label: `新規 ${editableTabs.length + 1}`,
+                      content: <Text as="p">新規タブ {next}</Text>,
+                    },
+                  ]);
+                  setEditableTab(next);
+                  return;
+                }
+                const rest = editableTabs.filter((item) => item.value !== target);
+                setEditableTabs(rest);
+                if (target === editableTab && rest[0]) setEditableTab(rest[0].value);
+              }}
+              extra={{
+                end: (
+                  <Button size="sm" variant="outline">
+                    一括操作
+                  </Button>
+                ),
+              }}
+              items={editableTabs}
+            />
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>tabPlacement · size · centered</CardTitle>
+            <CardDescription>
+              tabPlacement は antd 6.6.2 の名前で、値は論理軸(top / bottom / start / end)。start /
+              end は tablist を縦方向のロービングフォーカスに切り替える。size はライブラリの control
+              band(sm / md / lg)に対応。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="lg">
+              <Tabs
+                id="antd-centered"
+                defaultValue="pending"
+                variant="line"
+                centered
+                items={journalItems}
+              />
+              <Tabs
+                id="antd-bottom"
+                defaultValue="pending"
+                variant="card"
+                tabPlacement="bottom"
+                size="sm"
+                items={journalItems}
+              />
+              <Tabs
+                id="antd-start"
+                defaultValue="pending"
+                variant="line"
+                tabPlacement="start"
+                size="lg"
+                items={journalItems}
+              />
+            </Flex>
+          </CardContent>
+        </Card>
       </Flex>
     </PageContainer>
   );

package/docs/query/button-refetch.tsx

@@ -81,6 +81,7 @@ function VariantBlock() {
           <ButtonRefetch query={query} variant="ghost" label="ghost" />
           <ButtonRefetch query={query} variant="destructive" label="destructive" />
           <ButtonRefetch query={query} variant="link" label="link" />
+          <ButtonRefetch query={query} variant="bare" label="bare" />
         </Flex>
       </CardContent>
     </Card>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "19.6.0",
-  "godxUiMcp": "19.6.0",
+  "version": "20.1.0",
+  "godxUiMcp": "20.1.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -30,6 +30,9 @@
     "scripts/visual-audit-rules.mjs",
     "scripts/audit-hook.mjs",
     "scripts/init-agent-kit.mjs",
+    "scripts/init-guinea-pig.mjs",
+    "scripts/guinea-pig-skill.md",
+    "scripts/consumer-rule.md",
     "scripts/postinstall.mjs",
     "scripts/_agent-setup.mjs",
     "scripts/cli.mjs",
@@ -82,6 +85,22 @@
       "types": "./dist/components/charts/compact-bar-trend.d.ts",
       "import": "./dist/components/charts/compact-bar-trend.js"
     },
+    "./charts/line-chart": {
+      "types": "./dist/components/charts/line-chart.d.ts",
+      "import": "./dist/components/charts/line-chart.js"
+    },
+    "./charts/bar-chart": {
+      "types": "./dist/components/charts/bar-chart.d.ts",
+      "import": "./dist/components/charts/bar-chart.js"
+    },
+    "./charts/area-chart": {
+      "types": "./dist/components/charts/area-chart.d.ts",
+      "import": "./dist/components/charts/area-chart.js"
+    },
+    "./charts/pie-chart": {
+      "types": "./dist/components/charts/pie-chart.d.ts",
+      "import": "./dist/components/charts/pie-chart.js"
+    },
     "./ui": {
       "types": "./dist/components/ui/index.d.ts",
       "import": "./dist/components/ui/index.js"
@@ -308,10 +327,12 @@
     "format": "prettier --check .",
     "format:fix": "prettier --write .",
     "test": "vitest run",
+    "test:manual": "vitest run --config vitest.manual.config.ts",
     "test:visual:auth-login": "node scripts/auth-shell-login-visual.mjs",
     "test:visual:auth-registration": "node scripts/auth-shell-registration-visual.mjs",
     "test:visual:topbar-collision": "node scripts/topbar-collision-visual.mjs",
     "test:visual:table-collection-cjk": "node scripts/table-collection-cjk-visual.mjs",
+    "test:visual:chart-cjk-axis": "node scripts/chart-cjk-axis-visual.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "check:example-imports": "node scripts/check-example-imports.mjs",
@@ -335,8 +356,8 @@
     "check:frame-runtime": "pnpm check:data-entry-frame-runtime && pnpm check:data-entry-touch-aria && pnpm check:layout-nav-frames && pnpm check:provider-feedback-query-runtime && pnpm check:layout-nav-closure && pnpm check:final-touch-rtl && pnpm check:data-table-pagination-wrap && pnpm check:button-icon-xs",
     "verify": "pnpm typecheck && pnpm lint && pnpm format && pnpm build && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:frame-coverage && pnpm test",
     "verify:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm check:contrast && pnpm check:visual-audit && pnpm test",
-    "verify:ci": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:mcp-prop-sync && pnpm test",
-    "verify:ci:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:mcp-prop-sync",
+    "verify:ci": "pnpm verify:ci:static && pnpm check:frame-contracts && pnpm test",
+    "verify:ci:static": "pnpm build && pnpm check:packed-public-contract && pnpm typecheck && pnpm typecheck:docs && pnpm lint && pnpm preview:build && pnpm check:registry && pnpm check:example-imports && pnpm check:core-isolation && pnpm check:no-consumer-coupling && pnpm check:use-client && pnpm check:prop-vocabulary && pnpm check:token-tiers && pnpm check:no-external-assets && pnpm check:token-scale-bypass && pnpm check:no-antd-runtime && pnpm check:dist-tokens-resolve && pnpm check:no-hardcoded-geometry && pnpm check:no-hardcoded-css-values && pnpm check:no-inline-magic-numbers && pnpm check:no-tailwind-class-assertions && pnpm check:control-sizing && pnpm check:rtl && pnpm check:typography && pnpm check:mcp-lockstep && pnpm check:mcp-sync && pnpm check:doc-prop-existence && pnpm check:mcp-catalog-coverage && pnpm check:mcp-orphans && pnpm check:mcp-pattern-imports && pnpm check:audit-sync && pnpm check:gate-coverage && pnpm check:mcp-prop-sync",
     "verify:browser": "pnpm check:contrast && pnpm check:visual-audit",
     "verify:release": "pnpm verify:static && pnpm check:frame-contracts && pnpm check:frame-coverage && pnpm check:frame-axe",
     "verify:publish-tree": "pnpm build && pnpm check:packed-public-contract && pnpm check:use-client && pnpm check:dist-tokens-resolve",
@@ -365,9 +386,6 @@
     "check:rtl": "node scripts/check-rtl.mjs",
     "check:typography": "node scripts/check-typography.mjs",
     "gen:component-tokens": "node scripts/gen-component-tokens.mjs",
-    "gen:antd-tokens": "node scripts/gen-antd-tokens.mjs",
-    "check:antd-tokens": "node scripts/gen-antd-tokens.mjs --check",
-    "report:antd-tokens": "node scripts/gen-antd-tokens.mjs --report",
     "check:no-antd-runtime": "node scripts/check-no-antd-runtime.mjs",
     "gen:email-tokens": "node scripts/gen-email-tokens.mjs",
     "check:core-isolation": "node scripts/check-core-isolation.mjs",
@@ -384,6 +402,7 @@
     "dev": "node scripts/dev.mjs",
     "prepublishOnly": "pnpm run build",
     "check:audit-sync": "node scripts/check-audit-sync.mjs",
+    "check:gate-coverage": "node scripts/check-gate-coverage.mjs",
     "check:contrast": "node scripts/check-contrast.mjs",
     "visual-audit": "node scripts/visual-audit.mjs",
     "check:visual-audit": "node scripts/visual-audit-smoke.mjs",
@@ -451,6 +470,7 @@
     "@radix-ui/react-toggle": "^1.1.18",
     "@radix-ui/react-toggle-group": "^1.1.19",
     "@radix-ui/react-tooltip": "^1.2.16",
+    "@react-aria/utils": "^3.34.1",
     "@tanstack/react-table": "^9.2.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -460,6 +480,7 @@
     "input-otp": "^1.5.0",
     "lucide-react": "^1.37.0",
     "qrcode.react": "4.2.0",
+    "react-aria-components": "^1.21.1",
     "react-day-picker": "^10.0.1",
     "react-resizable-panels": "^4.12.3",
     "sonner": "^2.0.8",
@@ -483,7 +504,6 @@
     "@types/react-dom": "^19.2.5",
     "@vitejs/plugin-react": "^6.1.1",
     "@vitest/coverage-v8": "^4.1.11",
-    "antd": "6.6.2",
     "axe-core": "^4.13.0",
     "eslint": "^10.9.1",
     "eslint-plugin-react": "^7.37.5",

package/scripts/_agent-setup.mjs

@@ -4,10 +4,15 @@
  * NON-DESTRUCTIVE: it only creates a missing file or ADDS a missing key, never
  * overwrites existing config.
  */
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /** The godxjp-ui MCP server — pulled on demand via npx (no extra dependency to ship). */
+/** This package's own root — the source of the version we stamp with. */
+const SELF_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
 export const MCP_SERVER = { command: "npx", args: ["@godxjp/ui-mcp"] };
 export const MCP_KEY = "godx-ui";
 
@@ -16,7 +21,47 @@ export const AUDIT_HOOK_CMD = "node node_modules/@godxjp/ui/scripts/audit-hook.m
 export const PRIMER_CMD = "cat .claude/godxjp-ui-workflow.md";
 
 /** The per-session workflow mandate the SessionStart hook injects into the agent. */
-export const WORKFLOW_MD = `# @godxjp/ui — mandatory workflow (read every session)
+export const KIT_VERSION = readJson(join(SELF_ROOT, "package.json"))?.version ?? "0.0.0";
+
+const STAMP = (v) => `<!-- godxjp-ui:version ${v} -->`;
+const STAMP_RE = /<!-- godxjp-ui:version ([^\s]+) -->/;
+
+/** The version stamped in `text`, or null when it predates stamping. */
+export function stampedVersion(text) {
+  return text?.match(STAMP_RE)?.[1] ?? null;
+}
+
+/**
+ * A stamp that tracks the CONTENT, for the files this package owns outright.
+ *
+ * A version stamp answers "which release wrote this", which is the wrong question for a file whose
+ * whole job is to carry current guidance. Measured: editing `consumer-rule.md` without bumping the
+ * package left two of three consumers holding the previous text, with a stamp that read as current
+ * and nothing anywhere reporting a difference. The rules are edited far more often than the
+ * version moves — most of all while they are being written, which is exactly when a stale copy
+ * does the most damage.
+ *
+ * So the digest goes in alongside the version: the version stays for humans reading the file, and
+ * the digest is what the refresh actually compares. Identical body → still a no-op.
+ */
+const DIGEST_RE = /<!-- godxjp-ui:digest ([0-9a-f]{12}) -->/;
+const digestOf = (body) => createHash("sha256").update(body).digest("hex").slice(0, 12);
+const OWNED_STAMP = (body) => `${STAMP(KIT_VERSION)}\n<!-- godxjp-ui:digest ${digestOf(body)} -->`;
+
+/** The content digest stamped in `text`, or null when it predates digest stamping. */
+export function stampedDigest(text) {
+  return text?.match(DIGEST_RE)?.[1] ?? null;
+}
+
+/**
+ * Replace the MANAGED region of a file and leave everything else alone.
+ *
+ * Refreshing is only safe if it cannot eat hand-written content, so the contract is narrow: the
+ * region is delimited, and anything outside the delimiters survives byte-for-byte. A consumer that
+ * 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.
@@ -50,6 +95,7 @@ or change a component, page, or form — no exceptions.
 /** 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) -->
+${STAMP(KIT_VERSION)}
 ## @godxjp/ui — mandatory UI workflow (do NOT skip)
 
 This app uses @godxjp/ui. EVERY time you build or change UI:
@@ -82,6 +128,24 @@ function readJson(path) {
 }
 
 /** Ensure `.mcp.json` registers the godx-ui MCP server. Returns 'created' | 'added' | 'present'. */
+/**
+ * The version that wrote each managed artefact, stamped so `postinstall` can tell "already there"
+ * apart from "already there and STALE".
+ *
+ * Everything below used to be install-once: `ensureMcpJson` returned early on a present key,
+ * `writeWorkflowMd` on a present file, `ensureClaudeMd` on a present marker. So `npm update
+ * @godxjp/ui` brought new components, new audit rules and new catalog entries — and left the
+ * agent reading whatever guidance shipped the day the package was FIRST installed. The library
+ * moved; the instructions for using it did not.
+ */
+export function refreshBlock(current, next, startMarker, endMarker) {
+  const i = current.indexOf(startMarker);
+  if (i < 0) return current.replace(/\s*$/, "") + "\n\n" + next;
+  const j = endMarker ? current.indexOf(endMarker, i) : -1;
+  const tail = j < 0 ? "" : current.slice(j + endMarker.length);
+  return current.slice(0, i) + next + tail;
+}
+
 export function ensureMcpJson(root) {
   const path = join(root, ".mcp.json");
   const json = readJson(path) ?? {};
@@ -127,7 +191,14 @@ export function ensureClaudeHooks(root) {
 export function writeWorkflowMd(root) {
   const path = join(root, ".claude", "godxjp-ui-workflow.md");
   mkdirSync(dirname(path), { recursive: true });
-  if (existsSync(path)) return false;
+  // This file is owned entirely by the package — the CLAUDE.md block tells the consumer to edit
+  // it, but nothing else reads from it, so a stale copy is pure loss. Rewrite when the stamp moves.
+  if (existsSync(path)) {
+    const cur = readFileSync(path, "utf8");
+    if (stampedVersion(cur) === KIT_VERSION) return false;
+    writeFileSync(path, WORKFLOW_MD);
+    return "refreshed";
+  }
   writeFileSync(path, WORKFLOW_MD);
   return true;
 }
@@ -139,7 +210,16 @@ export function writeWorkflowMd(root) {
 export function ensureClaudeMd(root) {
   const path = join(root, "CLAUDE.md");
   const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
-  if (existing?.includes("godxjp-ui:start")) return "present";
+  if (existing?.includes("godxjp-ui:start")) {
+    // Present — but at WHICH version? Refresh only the delimited block; anything the consumer
+    // wrote around it is untouched.
+    if (stampedVersion(existing) === KIT_VERSION) return "present";
+    writeFileSync(
+      path,
+      refreshBlock(existing, CLAUDE_MD_BLOCK, "<!-- godxjp-ui:start", "<!-- godxjp-ui:end -->"),
+    );
+    return "refreshed";
+  }
   if (existing == null) {
     writeFileSync(path, CLAUDE_MD_BLOCK);
     return "created";
@@ -157,3 +237,102 @@ export function shouldSkip(root) {
   if (pkg.name === "@godxjp/ui" || pkg.name === "@godxjp/ui-mcp") return "self";
   return null;
 }
+
+/**
+ * Keep an opted-in guinea-pig skill current.
+ *
+ * The file is co-authored: sections 0–7 come from this package, and section 8 onward is whatever
+ * the repo wrote about ITSELF — its package manager, its audit baseline, its deliberate
+ * exceptions. So the refresh replaces the head and keeps the tail, which is the only split that
+ * lets the guidance move without eating the consumer's own notes.
+ *
+ * Only runs where `.guinea-pig-optin` exists: the skill carries an obligation to fix things
+ * UPSTREAM, and pushing that into a repo that never asked for it would tell its agent to go edit
+ * a library it has no mandate over.
+ */
+export function refreshGuineaPigSkill(root) {
+  const dir = join(root, ".claude", "skills", "godx-ui-guinea-pig");
+  const target = join(dir, "SKILL.md");
+  const optin = join(dir, ".guinea-pig-optin");
+  if (!existsSync(optin) || !existsSync(target)) return false;
+
+  const base = readFileSync(join(SELF_ROOT, "scripts", "guinea-pig-skill.md"), "utf8");
+  /*
+   * The marker tracks the BASE TEXT, not the release — the same correction the consumer rule file
+   * needed, for the same reason. A version marker means editing this skill without cutting a
+   * release reaches nobody, and the skill is edited far more often than the version moves. The
+   * digest covers only the base: everything from the `# 8.` marker down belongs to the repo and
+   * must not make the package's own content look changed.
+   *
+   * `<version>:<digest>` rather than a bare digest, so the file still says which release wrote it
+   * to anyone reading it. Only the digest half is compared.
+   */
+  const stamp = `${KIT_VERSION}:${digestOf(base)}`;
+  if (readFileSync(optin, "utf8").trim().split(":").pop() === digestOf(base)) return false;
+
+  const current = readFileSync(target, "utf8");
+  const marker = "\n---\n\n# 8. ";
+  const i = current.indexOf(marker);
+  writeFileSync(target, base.replace(/\s*$/, "") + "\n" + (i < 0 ? "" : current.slice(i)));
+  writeFileSync(optin, `${stamp}\n`);
+  return true;
+}
+
+/** The stamp `init-guinea-pig` writes on a fresh install, so the first refresh is a no-op. */
+export function guineaPigStamp() {
+  return `${KIT_VERSION}:${digestOf(readFileSync(join(SELF_ROOT, "scripts", "guinea-pig-skill.md"), "utf8"))}`;
+}
+
+/**
+ * Install the common consumer rules as a PATH-TRIGGERED file, and wire them into `.ai/rules`.
+ *
+ * The skill and this file say overlapping things on purpose, because they fire at different
+ * moments: a skill loads when the TASK matches its description — once, at the start — while an
+ * `.ai/rules` entry loads every time an agent touches a file under its glob. Measured over one
+ * session: a dashboard file was edited dozens of times and the skill was never re-read, so the
+ * laws that mattered were out of context for every edit after the first.
+ *
+ * The glob is DETECTED, not assumed. A rule wired to a directory the repo does not have is a rule
+ * that never fires, which is worse than no rule at all — it looks installed.
+ *
+ * Unlike the skill, this file is owned OUTRIGHT by the package and is rewritten whole. That is the
+ * honest shape for `.ai/rules`, where the convention is one file per concern and the index loads
+ * them all: a repo with something of its own to say writes its own rule file instead of editing
+ * 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) =>
+    existsSync(join(root, d)),
+  );
+  if (!uiDir) return false;
+
+  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`;
+  // 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}`;
+  const next = `${OWNED_STAMP(managed)}\n${managed}`;
+
+  if (existsSync(target) && stampedDigest(readFileSync(target, "utf8")) === digestOf(managed)) {
+    return false;
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(target, next);
+
+  // Only touch the index when the repo keeps one; a missing index means the repo reads rule files
+  // directly, and inventing one would change how it loads everything else.
+  const index = join(dir, "index.md");
+  if (existsSync(index)) {
+    const cur = readFileSync(index, "utf8");
+    if (!cur.includes(".ai/rules/godxjp-ui.md")) {
+      writeFileSync(
+        index,
+        cur.replace(/\s*$/, "") + `\n| ${uiDir}/** | .ai/rules/godxjp-ui.md |\n`,
+      );
+    }
+  }
+  return uiDir;
+}