@godxjp/ui 23.2.1 → 23.4.0

package/docs/general/typography.tsx

@@ -1,5 +1,14 @@
 import { useTranslation } from "@godxjp/ui/i18n";
-import { Button, Heading, Text, VisuallyHidden } from "@godxjp/ui/general";
+import {
+  Button,
+  Heading,
+  Link,
+  Paragraph,
+  Text,
+  Title,
+  Typography,
+  VisuallyHidden,
+} from "@godxjp/ui/general";
 import {
   Card,
   CardContent,
@@ -231,6 +240,59 @@ export default function Demo() {
             </Flex>
           </CardContent>
         </Card>
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>antd Typography · Title / Paragraph / Link</CardTitle>
+            <CardDescription>
+              antd の Typography をそのまま移植したもの。Text と Heading は変わらず、Title は 5
+              段階、Paragraph は rows 付きの ellipsis、Link は target=&quot;_blank&quot; に rel
+              を自動で付けます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Typography>
+                <Title level={3}>請求サマリー</Title>
+                <Paragraph>今月の請求は 3 件です。明細は各行のリンクから確認できます。</Paragraph>
+                <Link href="#typography">変更履歴を見る</Link>
+              </Typography>
+
+              <Title level={5}>内訳（level 5 · Heading にはない段）</Title>
+
+              <Paragraph ellipsis={{ rows: 2, expandable: true }}>
+                ログイン画面の余白が狭く、パスワード再設定リンクが本文と重なって見えます。
+                発生条件は 390px 幅の端末で、日本語ロケールのときのみです。
+                再現手順とスクリーンショットは添付の通りです。
+              </Paragraph>
+            </Flex>
+          </CardContent>
+        </Card>
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>copyable · editable · 装飾</CardTitle>
+            <CardDescription>
+              antd の copyable / editable と、7 つの装飾フラグ。装飾は本物の要素を包むので、意味が
+              スクリーンリーダーにも届きます。
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="sm">
+              <Text mono copyable>
+                RC-204881
+              </Text>
+              <Text editable>案件名をここで直接編集できます</Text>
+              <Text type="secondary">
+                type=&quot;secondary&quot;（tone=&quot;muted&quot; と同じ軸）
+              </Text>
+              <Text disabled>disabled · 使えないことを示します</Text>
+              <Text>
+                <Text code>npm run build</Text> と <Text keyboard>Ctrl</Text> +{" "}
+                <Text keyboard>S</Text>、<Text mark>強調</Text>、<Text delete>取り消し</Text>、
+                <Text strong>強い</Text>、<Text italic>斜体</Text>
+              </Text>
+            </Flex>
+          </CardContent>
+        </Card>
         <Card>
           <CardHeader>
             <CardTitle level={2}>{t("textExamples.preservedText")}</CardTitle>

package/docs/layout/draggable-panel.tsx

@@ -0,0 +1,127 @@
+import { useState } from "react";
+import { DraggablePanel, Flex, PageContainer } from "@godxjp/ui/layout";
+import type { DraggablePanelPositionProp } from "@godxjp/ui/layout";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Badge,
+  Descriptions,
+} from "@godxjp/ui/data-display";
+import { Button, Text } from "@godxjp/ui/general";
+
+/**
+ * DraggablePanel · a floating surface the person using it can MOVE.
+ *
+ * The case it exists for: an assistant docked to a corner covers the thing the
+ * person is asking about. Drag it by the title-bar handle, or focus the handle
+ * and use the arrow keys. The position is REPORTED to the page below, never
+ * stored by the library.
+ */
+export default function Demo() {
+  const [position, setPosition] = useState<DraggablePanelPositionProp>({ x: 0, y: 0 });
+  const [open, setOpen] = useState(true);
+  const [pinned, setPinned] = useState(false);
+
+  return (
+    <PageContainer
+      title="DraggablePanel"
+      subtitle="floating movable surface · handle drag, arrow-key nudge, viewport-bounded"
+    >
+      <Flex direction="col" gap="lg">
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>Reported position</CardTitle>
+            <CardDescription>
+              Drag the panel by its handle, or focus the handle and press an arrow key. Hold Shift
+              for the larger step. Every frame and every nudge reports the clamped offset through
+              onPositionChange; the page below decides whether to remember it.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Flex direction="col" gap="md">
+              <Descriptions
+                items={[
+                  { label: "x", value: String(Math.round(position.x)) },
+                  { label: "y", value: String(Math.round(position.y)) },
+                ]}
+              />
+              <Flex gap="sm" wrap>
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => {
+                    setPosition({ x: 0, y: 0 });
+                  }}
+                >
+                  角に戻す
+                </Button>
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => {
+                    setPinned((value) => !value);
+                  }}
+                >
+                  {pinned ? "移動を許可" : "その場に固定"}
+                </Button>
+                <Button
+                  variant="outline"
+                  size="sm"
+                  onClick={() => {
+                    setOpen(true);
+                  }}
+                >
+                  パネルを開く
+                </Button>
+              </Flex>
+            </Flex>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle level={2}>What it is not</CardTitle>
+            <CardDescription>
+              ResizablePanel resizes panes WITHIN a layout, Sheet is pinned to an edge, and Popover
+              is anchored to its trigger. None of them can be repositioned by the viewer, which is
+              what a floating assistant needs.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <Text size="sm" tone="muted">
+              The panel is a labelled region, not a dialog: it interrupts nothing, traps no focus
+              and dims no page, so the work behind it stays usable while it is open.
+            </Text>
+          </CardContent>
+        </Card>
+      </Flex>
+
+      {open ? (
+        <DraggablePanel
+          title="アシスタント"
+          placement="bottom-end"
+          width="sm"
+          disabled={pinned}
+          position={position}
+          onPositionChange={setPosition}
+          onClose={() => {
+            setOpen(false);
+          }}
+          extra={<Badge tone="info">β</Badge>}
+        >
+          <Flex direction="col" gap="sm">
+            <Text size="sm">
+              この請求書の消費税区分について質問できます。テキストは選択できます。掴むのはタイトルバーのハンドルだけです。
+            </Text>
+            <Text size="xs" tone="muted">
+              キーボード: ハンドルにフォーカスして矢印キー · Shift で大きく移動
+            </Text>
+          </Flex>
+        </DraggablePanel>
+      ) : null}
+    </PageContainer>
+  );
+}

package/docs/navigation/conversations.tsx

@@ -0,0 +1,176 @@
+import { useState } from "react";
+
+import { ChatBubbleList, type ChatMessageProp } from "@godxjp/ui/data-display";
+import { ChatComposer } from "@godxjp/ui/data-entry";
+import { Text } from "@godxjp/ui/general";
+import {
+  AppShell,
+  Flex,
+  MasterDetail,
+  PageContainer,
+  Sidebar,
+  type SidebarSectionProp,
+  Topbar,
+} from "@godxjp/ui/layout";
+import { Conversations, type ConversationsEntryProp } from "@godxjp/ui/navigation";
+import { Bot, MessageSquare, Pencil, Settings, Trash2, Users } from "lucide-react";
+
+/**
+ * Conversations — the session rail of a chat surface (Ant Design X `Conversations`).
+ *
+ * This page is the whole surface gh#559 is about: the rail on the left, the feed and the composer
+ * on the right. They were shipped one half at a time, and the missing half is why every consumer
+ * hand-rolled a stack of full-width Buttons — one tab stop per conversation, no per-row menu, no
+ * recency buckets.
+ *
+ * The three cards below are one axis each, at rest, so the API is visible without clicking:
+ * the live surface, the recency buckets (`groupable`), and the flat rail with a divider and a
+ * disabled row. Composed only from real @godxjp/ui components.
+ */
+const sections: SidebarSectionProp[] = [
+  {
+    label: "アシスタント",
+    items: [
+      { id: "chat", label: "チャット", icon: MessageSquare },
+      { id: "agents", label: "エージェント", icon: Bot },
+      { id: "members", label: "メンバー", icon: Users },
+    ],
+  },
+  { label: "管理", items: [{ id: "settings", label: "設定", icon: Settings }] },
+];
+
+/** The rail's data, bucketed by recency — the `group` field is what `groupable` reads. */
+const HISTORY: ConversationsEntryProp[] = [
+  { key: "invoice", label: "請求書の下書きを直す", group: "今日" },
+  { key: "expense", label: "経費精算の規則をまとめる", group: "今日" },
+  { key: "travel", label: "出張手当の確認", group: "過去7日間" },
+  { key: "onboarding", label: "入社手続きのチェックリスト", group: "過去7日間" },
+  { key: "payroll", label: "給与計算の締め日について", group: "それ以前" },
+];
+
+/** A flat rail — no buckets, one rule, one archived row. */
+const FLAT: ConversationsEntryProp[] = [
+  { key: "invoice", label: "請求書の下書きを直す", icon: <MessageSquare /> },
+  { key: "expense", label: "経費精算の規則をまとめる", icon: <MessageSquare /> },
+  { type: "divider", key: "rule" },
+  { key: "archived", label: "アーカイブ済みの相談", icon: <MessageSquare />, disabled: true },
+];
+
+const TRANSCRIPT: Record<string, ChatMessageProp[]> = {
+  invoice: [
+    { id: "m1", role: "user", content: "先月分の請求書の下書きを直したいです。" },
+    {
+      id: "m2",
+      role: "assistant",
+      content: "差分は3件でした。金額、支払期日、宛名のうちどれから直しますか。",
+    },
+  ],
+  expense: [
+    { id: "m1", role: "user", content: "経費精算の規則を3行でまとめてください。" },
+    {
+      id: "m2",
+      role: "assistant",
+      content: "領収書は原本、申請は当月末まで、3万円以上は事前承認が要ります。",
+    },
+  ],
+};
+
+export default function ConversationsDoc() {
+  const [active, setActive] = useState("invoice");
+  const [draft, setDraft] = useState("");
+
+  const menu = {
+    items: [
+      { key: "rename", label: "名前を変更", icon: <Pencil /> },
+      { key: "delete", label: "削除", icon: <Trash2 />, danger: true },
+    ],
+  };
+
+  return (
+    <AppShell
+      sidebar={
+        <Sidebar
+          activeId="chat"
+          sections={sections}
+          onSelect={() => {}}
+          product={{ name: "CoreDesk", role: "アシスタント", color: "hsl(var(--primary))" }}
+        />
+      }
+      topbar={<Topbar />}
+    >
+      <PageContainer
+        title="会話の履歴"
+        subtitle="過去の会話を選び、名前を変更し、不要になったものを消す · チャット面の左半分。"
+      >
+        {/* THE SURFACE. The rail is the master; the feed and the composer are the detail. */}
+        <MasterDetail
+          rail="master"
+          railWidth="compact"
+          masterViewport="compact"
+          masterLabel="会話の履歴"
+          detailLabel="選択中の会話"
+          detailId="assistant-transcript"
+          master={
+            <Conversations
+              label="会話の履歴"
+              items={HISTORY}
+              activeKey={active}
+              onActiveChange={setActive}
+              groupable={{ collapsible: true }}
+              creation={{ label: "新しい会話", onClick: () => setActive("invoice") }}
+              menu={menu}
+            />
+          }
+        >
+          <Flex direction="col" gap="md">
+            <ChatBubbleList
+              label="会話"
+              className="h-96"
+              items={TRANSCRIPT[active] ?? []}
+              roles={{
+                assistant: { placement: "start", variant: "filled" },
+                user: { placement: "end" },
+              }}
+            />
+            <ChatComposer
+              aria-label="メッセージ"
+              value={draft}
+              onValueChange={setDraft}
+              onSubmit={() => setDraft("")}
+              placeholder="メッセージを入力"
+            />
+          </Flex>
+        </MasterDetail>
+
+        {/* BUCKETS, EXPANDED. `groupable` with no options groups but never collapses. */}
+        <Flex direction="col" gap="sm">
+          <Text size="sm" weight="medium">
+            recency buckets · groupable
+          </Text>
+          <Text size="xs" tone="muted">
+            バケットの見出しは同じローヴィング順に入るので、畳む操作もレールを離れずに届く。
+          </Text>
+          <Conversations
+            label="会話の履歴（分類のみ）"
+            items={HISTORY}
+            defaultActiveKey="travel"
+            groupable
+            menu={menu}
+          />
+        </Flex>
+
+        {/* FLAT, WITH A RULE AND A DISABLED ROW. */}
+        <Flex direction="col" gap="sm">
+          <Text size="sm" weight="medium">
+            flat rail · divider and a disabled row
+          </Text>
+          <Text size="xs" tone="muted">
+            無効な行は見えるが選べず、矢印キーの巡回からも外れる。無効なコントロールは
+            フォーカスを受け取らないため。
+          </Text>
+          <Conversations label="会話の履歴（フラット）" items={FLAT} defaultActiveKey="invoice" />
+        </Flex>
+      </PageContainer>
+    </AppShell>
+  );
+}

package/docs/roadmap/parity-audit-layout-navigation-general.md

@@ -14,8 +14,9 @@ ahead of it: `AppShell` (three navigation scopes, nav rail, mobile drawer), `Mob
 `AuthShell`, `LegalDocumentShell`, `ErrorSurface`, `AppLauncher` and `AppProvider` have no antd
 counterpart at all, and `Breadcrumb`, `Separator`, `Toolbar` and `Pagination` are already carrying
 explicit antd-parity work in their prop docs. The "missing features vs Ant Design" complaint does
-**not** originate here — most of what antd ships in `Space`, `Divider`, `Grid`, `Anchor`, `Affix`,
-`FloatButton` and `App` is genuinely a composition or an existing primitive in this system (§4.2).
+**not** originate here — most of what antd ships in `Space`, `Divider`, `Grid`, `Anchor`, `Affix`
+and `App` is genuinely a composition or an existing primitive in this system (§4.2). `FloatButton`
+was on that list and should not have been: it shipped in gh#558. See the struck-through row in §4.2.
 
 What is real, ordered by how badly it hurts:
 
@@ -420,20 +421,20 @@ an editing lifecycle to the typographic primitive would make every `<Text>` in t
 
 ### 4.2 These antd components are **compositions** here, not gaps
 
-| antd                                        | Why it is not a gap                                                                                                                                                                                                                        | Build it with                                                                                                        |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `Space`                                     | `gap` already lives on the layout primitive, with a counted escape hatch (`data-gap-raw`). C3 fails outright.                                                                                                                              | `Flex gap` / `ResponsiveGrid gap`                                                                                    |
-| `Divider`                                   | Exists.                                                                                                                                                                                                                                    | `Separator` (`src/props/components/layout.prop.ts:567`)                                                              |
-| `Grid` / `Row` / `Col`                      | Exists, in the house `{base,sm,md,lg}` count model rather than a 12-column raster.                                                                                                                                                         | `ResponsiveGrid` + `ResponsiveGrid.Item span` (`src/components/layout/responsive-grid.tsx:115`)                      |
-| `Affix`                                     | C1/C2/C3 all fail — it is `position: sticky` with a JS shim, and antd's own docs now recommend the CSS property. Sticky chrome is already a first-class slot here.                                                                         | `PageContainer toolbar` (`layout.prop.ts:82-88`), `PageContainer stickyFooter`, `Toolbar sticky`, `DataTable sticky` |
-| `Anchor`                                    | C1/C7 fail — the one real use (a long document with a contents rail) is already owned end-to-end, including scroll-spy, hash deep-linking, focus handoff and `aria-current="location"`. A second general Anchor would duplicate it.        | `LegalDocumentShell` (`layout.prop.ts:1279-1331`)                                                                    |
-| `FloatButton` / `BackTop`                   | C1/C2 fail — layout + content + colour, positioned by the screen that wants it. `BackTop` additionally competes with the shell's own scroll ownership (`MobileShell` is deliberately the only scroll container, `layout.prop.ts:504-507`). | `Button shape="pill" size="icon-lg"` placed by the page; a token for the inset if one is missing                     |
-| `Layout.Header` / `Content` / `Footer`      | Bare boxes in antd; real slots here.                                                                                                                                                                                                       | `AppShell topbar` / `children` / `footer`, `Topbar`, `PageContainer`                                                 |
-| `App` (static-method context)               | The context problem it solves does not exist here — nothing is imperative.                                                                                                                                                                 | `AppProvider` + `Toaster` + declarative `Dialog`/`AlertDialog`                                                       |
-| `PageHeader` (removed from antd core)       | Exists, and is wider.                                                                                                                                                                                                                      | `PageContainer` (`layout.prop.ts:64-139`)                                                                            |
-| `Result`                                    | Exists for HTTP statuses; the non-HTTP shapes are an empty state with an action.                                                                                                                                                           | `ErrorSurface` / `EmptyState`                                                                                        |
-| `Menu` `items` config array as the only API | Both dialects exist already: config-array for the route rails, compound parts for the overlay menus.                                                                                                                                       | `Sidebar.sections` / `NavList.items` · `DropdownMenu*`                                                               |
-| `Dropdown.Button`                           | Two existing primitives plus the proposed `ButtonGroup`.                                                                                                                                                                                   | `ButtonGroup` + `Button` + `DropdownMenu`                                                                            |
+| antd                                        | Why it is not a gap                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Build it with                                                                                                          |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `Space`                                     | `gap` already lives on the layout primitive, with a counted escape hatch (`data-gap-raw`). C3 fails outright.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `Flex gap` / `ResponsiveGrid gap`                                                                                      |
+| `Divider`                                   | Exists.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `Separator` (`src/props/components/layout.prop.ts:567`)                                                                |
+| `Grid` / `Row` / `Col`                      | Exists, in the house `{base,sm,md,lg}` count model rather than a 12-column raster.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `ResponsiveGrid` + `ResponsiveGrid.Item span` (`src/components/layout/responsive-grid.tsx:115`)                        |
+| `Affix`                                     | C1/C2/C3 all fail — it is `position: sticky` with a JS shim, and antd's own docs now recommend the CSS property. Sticky chrome is already a first-class slot here.                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `PageContainer toolbar` (`layout.prop.ts:82-88`), `PageContainer stickyFooter`, `Toolbar sticky`, `DataTable sticky`   |
+| `Anchor`                                    | C1/C7 fail — the one real use (a long document with a contents rail) is already owned end-to-end, including scroll-spy, hash deep-linking, focus handoff and `aria-current="location"`. A second general Anchor would duplicate it.                                                                                                                                                                                                                                                                                                                                                                                              | `LegalDocumentShell` (`layout.prop.ts:1279-1331`)                                                                      |
+| ~~`FloatButton` / `BackTop`~~ **SHIPPED**   | **This row was wrong, and it is kept struck through rather than deleted so the reversal is legible.** It read C1/C2 as failing; the repo owner's 2026-09-12 decision (docs/DESIGN-AUTHORITY.md — antd IS the standard, ported 100% first) settles the question the other way, and gh#558 supplied the C1 case the row denied: pinning a `Button` to a corner requires `position: fixed` at the call site, which `ui-audit` blocks with no legal spelling. The `BackTop`-vs-shell-scroll objection was real and is answered by antd's own `target` prop, which points BackTop at a shell's scroll region instead of the document. | `FloatButton` (`src/components/general/float-button.tsx`), insets on `--float-button-offset-block-end` / `-inline-end` |
+| `Layout.Header` / `Content` / `Footer`      | Bare boxes in antd; real slots here.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `AppShell topbar` / `children` / `footer`, `Topbar`, `PageContainer`                                                   |
+| `App` (static-method context)               | The context problem it solves does not exist here — nothing is imperative.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `AppProvider` + `Toaster` + declarative `Dialog`/`AlertDialog`                                                         |
+| `PageHeader` (removed from antd core)       | Exists, and is wider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `PageContainer` (`layout.prop.ts:64-139`)                                                                              |
+| `Result`                                    | Exists for HTTP statuses; the non-HTTP shapes are an empty state with an action.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `ErrorSurface` / `EmptyState`                                                                                          |
+| `Menu` `items` config array as the only API | Both dialects exist already: config-array for the route rails, compound parts for the overlay menus.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `Sidebar.sections` / `NavList.items` · `DropdownMenu*`                                                                 |
+| `Dropdown.Button`                           | Two existing primitives plus the proposed `ButtonGroup`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `ButtonGroup` + `Button` + `DropdownMenu`                                                                              |
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@godxjp/ui",
-  "version": "23.2.1",
-  "godxUiMcp": "23.2.1",
+  "version": "23.4.0",
+  "godxUiMcp": "23.4.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -397,7 +397,8 @@
     "check:number-input-step-target": "node scripts/check-number-input-step-target.mjs",
     "check:mcp-token-sync": "node scripts/gen-component-tokens.mjs --check",
     "check:email-token-sync": "node scripts/gen-email-tokens.mjs --check",
-    "check:focus-ring-paint": "node scripts/check-focus-ring-paint.mjs"
+    "check:focus-ring-paint": "node scripts/check-focus-ring-paint.mjs",
+    "typecheck:mcp": "node node_modules/typescript-7/bin/tsc --noEmit -p mcp/tsconfig.json"
   },
   "peerDependencies": {
     "@hookform/resolvers": "^5.2.0",
@@ -412,11 +413,26 @@
     "zod": "^4.4.0"
   },
   "peerDependenciesMeta": {
-    "recharts": {
+    "@hookform/resolvers": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
       "optional": true
     },
     "playwright": {
       "optional": true
+    },
+    "react-hook-form": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    },
+    "recharts": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "dependencies": {

package/scripts/_agent-setup.mjs

@@ -10,8 +10,17 @@
  * The guarantee is now structural: a file that exists but cannot be read, parsed, or recognised is
  * NEVER written to. We leave a `.godxjp-ui-suggested` sidecar next to it and say so.
  */
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -205,9 +214,31 @@ function readJson(path) {
  * write manufactured the precondition for the overwrite.
  */
 function writeFileAtomic(path, data) {
-  const tmp = `${path}.godxjp-ui-tmp`;
-  writeFileSync(tmp, data);
-  renameSync(tmp, path);
+  // UNIQUE temp name. A fixed `${path}.godxjp-ui-tmp` is a shared mutable file: two installs
+  // running at once — a workspace installing packages in parallel is enough — write over each
+  // other's temp and `rename` whichever finished last.
+  const tmp = `${path}.godxjp-ui-tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    writeFileSync(tmp, data);
+    // `rename` does NOT carry the target's permissions: the new file is born under the process
+    // umask. A `.mcp.json` the consumer had chmod 600 would come back 644 after the first sync,
+    // silently, because the CONTENT would be right. This happens on every write, not only under
+    // contention, which makes it the worse half of the two.
+    try {
+      chmodSync(tmp, statSync(path).mode & 0o7777);
+    } catch {
+      // No existing file (a create), or a filesystem that will not report/set the mode. Either
+      // way the default is correct and this must not abort the write.
+    }
+    renameSync(tmp, path);
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // Nothing to clean up.
+    }
+    throw error;
+  }
 }
 
 /**

package/scripts/guinea-pig-skill.md

@@ -131,6 +131,20 @@ những thứ ấy trên PR. **Tới được bước này KHÔNG phải là đ
 một câu hỏi, không phải một chướng ngại. Nếu bạn tin cổng ấy sai thì nói ra và
 đưa số đo, đừng lặng lẽ sửa nó.
 
+**VÀ ĐỪNG NGỒI CHỜ CI.** Đẩy nhánh, mở PR, rồi đi làm việc khác. Không có vòng lặp
+`until … gh pr checks … sleep` nào cả. CI chạy là việc của CI; nếu cần theo dõi thì
+mở một agent nền, đừng chặn người đang điều phối. Đo được ngày 12/09/2026: một lượt
+ngồi poll bốn shard đã ăn hơn một tiếng đồng hồ của chủ dự án để nhìn một thanh tiến
+trình, trong khi có việc khác đang xếp hàng.
+
+**Và full suite thì chạy theo LỊCH, không nằm trong vòng lặp sửa code của ai.** Cùng
+ngày, tôi thêm bốn shard vitest vào làn PR của kho DS và đặt chúng thành required
+check, để bịt một khoảng trống có thật (hai commit vào `main` đỏ qua một làn nhanh
+xanh). Khoảng trống là thật và phép đo trung thực — nhưng nó chỉ định giá **máy**.
+Máy chưa bao giờ là phần đắt. Từ lúc ấy mọi PR phải chờ bốn shard mới merge được.
+Đã hoàn nguyên. Một hàng rào làm người điều phối phải chờ không rẻ hơn một `main`
+đỏ; nó chỉ dời chi phí sang con đường duy nhất không song song hoá được.
+
 ### Bước 6 — Khép vòng
 
 Phát hành → nâng gói ở consumer → **gỡ vá tạm** → **gỡ mọi chú thích "chờ