@mandujs/core 0.51.0 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/design/__tests__/agents-link.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Issue #245 M5 — AGENTS.md / CLAUDE.md linker tests.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  buildAgentsDesignBlock,
+  DESIGN_LINK_MARKER_END,
+  DESIGN_LINK_MARKER_START,
+  linkAgentsToDesignMd,
+} from "../agents-link";
+
+describe("buildAgentsDesignBlock", () => {
+  it("contains markers, the canonical heading, and all 8 MCP tools", () => {
+    const block = buildAgentsDesignBlock();
+    expect(block).toContain(DESIGN_LINK_MARKER_START);
+    expect(block).toContain(DESIGN_LINK_MARKER_END);
+    expect(block).toContain("## Design System");
+    for (const tool of [
+      "mandu.design.get",
+      "mandu.design.prompt",
+      "mandu.component.list",
+      "mandu.design.check",
+      "mandu.design.extract",
+      "mandu.design.propose",
+      "mandu.design.patch",
+      "mandu.design.diff_upstream",
+    ]) {
+      expect(block).toContain(tool);
+    }
+  });
+
+  it("respects custom DESIGN.md filename", () => {
+    expect(buildAgentsDesignBlock("Stripe-DESIGN.md")).toContain("Stripe-DESIGN.md");
+  });
+});
+
+describe("linkAgentsToDesignMd", () => {
+  let TEST_DIR: string;
+  beforeEach(async () => {
+    TEST_DIR = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-design-link-"));
+  });
+  afterEach(async () => {
+    await fs.rm(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it("inserts the block at end of an existing AGENTS.md", async () => {
+    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# Existing\n\nSome notes.\n");
+    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    expect(result.changed).toBe(true);
+    expect(result.files.find((f) => f.path.endsWith("AGENTS.md"))?.action).toBe("inserted");
+    const after = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
+    expect(after).toContain("# Existing");
+    expect(after).toContain("Some notes.");
+    expect(after).toContain("## Design System");
+  });
+
+  it("is idempotent — running twice produces no diff on the second run", async () => {
+    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# X\n");
+    await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    const after1 = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
+    const second = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    const after2 = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
+    expect(after1).toBe(after2);
+    expect(second.files.find((f) => f.path.endsWith("AGENTS.md"))?.action).toBe("unchanged");
+  });
+
+  it("replaces an existing markered block when the body changed", async () => {
+    await fs.writeFile(
+      path.join(TEST_DIR, "AGENTS.md"),
+      `# X\n\n${DESIGN_LINK_MARKER_START}\n\n## Old block\n\n${DESIGN_LINK_MARKER_END}\n`,
+    );
+    await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    const after = await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8");
+    expect(after).not.toContain("## Old block");
+    expect(after).toContain("## Design System");
+  });
+
+  it("touches CLAUDE.md too when both exist", async () => {
+    await fs.writeFile(path.join(TEST_DIR, "AGENTS.md"), "# A\n");
+    await fs.writeFile(path.join(TEST_DIR, "CLAUDE.md"), "# C\n");
+    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    expect(result.files.filter((f) => f.action === "inserted")).toHaveLength(2);
+    expect(await fs.readFile(path.join(TEST_DIR, "CLAUDE.md"), "utf8")).toContain(
+      "## Design System",
+    );
+  });
+
+  it("creates AGENTS.md when neither file exists and createIfMissing is true", async () => {
+    const result = await linkAgentsToDesignMd({
+      rootDir: TEST_DIR,
+      createIfMissing: true,
+    });
+    expect(result.changed).toBe(true);
+    expect(result.files.find((f) => f.action === "created")).toBeDefined();
+    expect(await fs.readFile(path.join(TEST_DIR, "AGENTS.md"), "utf8")).toContain(
+      "## Design System",
+    );
+  });
+
+  it("is a no-op when neither file exists and createIfMissing is false", async () => {
+    const result = await linkAgentsToDesignMd({ rootDir: TEST_DIR });
+    expect(result.changed).toBe(false);
+    await expect(fs.access(path.join(TEST_DIR, "AGENTS.md"))).rejects.toThrow();
+  });
+});

package/src/design/__tests__/extract-patch-diff.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Issue #245 M4 §3.5 — extract / patch / diff helper tests.
+ *
+ * Cover the three pure surfaces the MCP write-tools layer over:
+ *   - `extractDesignTokens()` — color/font/component proposals
+ *   - `patchDesignMd()` — section-safe add/update/remove
+ *   - `diffDesignSpecs()` — local ↔ upstream per-section diff
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { extractDesignTokens } from "../extract";
+import { patchDesignMd, patchDesignMdBatch } from "../patch";
+import { diffDesignSpecs } from "../diff";
+import { parseDesignMd } from "../parser";
+
+// ─── extract ──────────────────────────────────────────────────────────
+
+async function setupFixture(): Promise<{ root: string; cleanup: () => Promise<void> }> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-extract-"));
+  await fs.mkdir(path.join(root, "src"), { recursive: true });
+  await fs.mkdir(path.join(root, "app"), { recursive: true });
+  await fs.writeFile(
+    path.join(root, "src/a.tsx"),
+    `const a = "#FF8C42"; const b = "#FF8C42"; const c = "#FF8C42";
+const elem = <div className="rounded-lg bg-orange-500 px-4 py-2 text-white" />;`,
+  );
+  await fs.writeFile(
+    path.join(root, "src/b.tsx"),
+    `const a = "#FF8C42"; const card = "#FFF8F0";
+const elem = <div className="rounded-lg bg-orange-500 px-4 py-2 text-white" />;`,
+  );
+  await fs.writeFile(
+    path.join(root, "app/c.tsx"),
+    `const x = "rgb(99,91,255)"; const y = "rgb(99,91,255)"; const z = "rgb(99,91,255)";
+const cssIsh = \`font-family: "Inter", sans-serif;\`;
+const elem = <div className="rounded-lg bg-orange-500 px-4 py-2 text-white" />;`,
+  );
+  return { root, cleanup: () => fs.rm(root, { recursive: true, force: true }) };
+}
+
+describe("extractDesignTokens", () => {
+  let fix: { root: string; cleanup: () => Promise<void> };
+  beforeEach(async () => {
+    fix = await setupFixture();
+  });
+  afterEach(async () => {
+    await fix.cleanup();
+  });
+
+  it("flags colors that occur ≥ minOccurrences", async () => {
+    const result = await extractDesignTokens(fix.root);
+    const orange = result.proposals.find((p) => p.key === "#ff8c42");
+    expect(orange).toBeDefined();
+    expect(orange?.section).toBe("color-palette");
+    expect(orange?.occurrences).toBeGreaterThanOrEqual(3);
+    expect(orange?.confidence).toBeGreaterThan(0);
+  });
+
+  it("ignores colors below the threshold", async () => {
+    const result = await extractDesignTokens(fix.root, { minOccurrences: 4 });
+    expect(result.proposals.find((p) => p.key === "#fff8f0")).toBeUndefined();
+  });
+
+  it("flags font-family declarations", async () => {
+    const result = await extractDesignTokens(fix.root, { minOccurrences: 1 });
+    const inter = result.proposals.find(
+      (p) => p.section === "typography" && p.value.includes("Inter"),
+    );
+    expect(inter).toBeDefined();
+  });
+
+  it("flags repeating className combos", async () => {
+    const result = await extractDesignTokens(fix.root, { kinds: ["component"] });
+    const combo = result.proposals.find((p) => p.section === "components");
+    expect(combo).toBeDefined();
+    expect(combo?.occurrences).toBeGreaterThanOrEqual(3);
+  });
+
+  it("drops proposals already represented in the existing DesignSpec", async () => {
+    const existing = parseDesignMd(`# Test
+## Color Palette
+- Primary — #FF8C42 — brand
+`);
+    const result = await extractDesignTokens(fix.root, { existing });
+    expect(result.proposals.find((p) => p.key === "#ff8c42")).toBeUndefined();
+  });
+});
+
+// ─── patch ────────────────────────────────────────────────────────────
+
+const SAMPLE = `# Test
+## Color Palette
+- Primary — #FF8C42 — brand
+- Surface — #FFF8F0 — background
+
+## Typography
+- body: font-family: "Inter", sans-serif
+
+## Layout
+- sm: 0.5rem
+`;
+
+describe("patchDesignMd — color-palette", () => {
+  it("adds a new token in the right section", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "add",
+      key: "Accent",
+      value: "#1A1F36",
+      role: "text",
+    });
+    expect(r.applied).toBe(true);
+    expect(r.next).toContain("- Accent — #1A1F36 — text");
+    // Other sections untouched.
+    expect(r.next).toContain("## Typography");
+    expect(r.next).toContain("## Layout");
+  });
+
+  it("refuses to add a duplicate key (slug-insensitive)", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "add",
+      key: "primary",
+      value: "#000",
+    });
+    expect(r.applied).toBe(false);
+    expect(r.reason).toContain("already exists");
+  });
+
+  it("updates a matching key", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "update",
+      key: "Primary",
+      value: "#FF7733",
+    });
+    expect(r.applied).toBe(true);
+    expect(r.before).toContain("#FF8C42");
+    expect(r.after).toContain("#FF7733");
+    expect(r.next).toContain("#FF7733");
+    expect(r.next).not.toContain("#FF8C42");
+  });
+
+  it("removes a matching key", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "remove",
+      key: "Surface",
+    });
+    expect(r.applied).toBe(true);
+    expect(r.before).toContain("Surface");
+    expect(r.next).not.toContain("Surface");
+    // Primary still there.
+    expect(r.next).toContain("Primary");
+  });
+
+  it("returns no-op + reason when section is absent", () => {
+    const r = patchDesignMd("# Empty\n", {
+      section: "color-palette",
+      operation: "add",
+      key: "X",
+      value: "#000",
+    });
+    expect(r.applied).toBe(false);
+    expect(r.reason).toContain("not found");
+    expect(r.next).toBe("# Empty\n");
+  });
+
+  it("requires a value on add/update", () => {
+    const r = patchDesignMd(SAMPLE, {
+      section: "color-palette",
+      operation: "add",
+      key: "Foo",
+    });
+    expect(r.applied).toBe(false);
+    expect(r.reason).toContain("required");
+  });
+});
+
+describe("patchDesignMd — components (H3)", () => {
+  it("adds a new component as an H3 heading", () => {
+    const r = patchDesignMd(
+      `# Test
+## Components
+
+### Button
+A primary action.
+`,
+      { section: "components", operation: "add", key: "Card" },
+    );
+    expect(r.applied).toBe(true);
+    expect(r.next).toContain("### Card");
+  });
+});
+
+describe("patchDesignMdBatch", () => {
+  it("applies operations in order against the cumulative source", () => {
+    const r = patchDesignMdBatch(SAMPLE, [
+      { section: "color-palette", operation: "add", key: "Accent", value: "#000" },
+      { section: "color-palette", operation: "remove", key: "Surface" },
+      { section: "color-palette", operation: "update", key: "Primary", value: "#111" },
+    ]);
+    expect(r.appliedCount).toBe(3);
+    expect(r.next).toContain("#111");
+    expect(r.next).toContain("#000");
+    expect(r.next).not.toContain("Surface");
+  });
+
+  it("partial success — failed ops surface in results, others still apply", () => {
+    const r = patchDesignMdBatch(SAMPLE, [
+      { section: "color-palette", operation: "remove", key: "doesnotexist" },
+      { section: "color-palette", operation: "add", key: "Accent", value: "#000" },
+    ]);
+    expect(r.appliedCount).toBe(1);
+    expect(r.results[0]?.applied).toBe(false);
+    expect(r.results[1]?.applied).toBe(true);
+  });
+});
+
+// ─── diff ─────────────────────────────────────────────────────────────
+
+describe("diffDesignSpecs", () => {
+  it("flags added / removed / changed color tokens", () => {
+    const local = parseDesignMd(`# A
+## Color Palette
+- Primary — #FF8C42 — brand
+- Surface — #FFF8F0 — background
+`);
+    const upstream = parseDesignMd(`# B
+## Color Palette
+- Primary — #FF7733 — brand
+- Accent — #1A1F36 — text
+`);
+    const d = diffDesignSpecs(local, upstream);
+    expect(d.colorPalette.find((e) => e.kind === "changed" && e.name === "Primary")).toBeDefined();
+    expect(d.colorPalette.find((e) => e.kind === "added" && e.name === "Accent")).toBeDefined();
+    expect(d.colorPalette.find((e) => e.kind === "removed" && e.name === "Surface")).toBeDefined();
+    expect(d.totalChanges).toBe(3);
+  });
+
+  it("returns empty diff when specs are identical at the structured level", () => {
+    const a = parseDesignMd(`# T
+## Color Palette
+- Primary — #FF8C42 — brand
+`);
+    const b = parseDesignMd(`# Different prose, same tokens
+## Color Palette
+- Primary — #FF8C42 — brand
+`);
+    const d = diffDesignSpecs(a, b);
+    expect(d.totalChanges).toBe(0);
+  });
+
+  it("surfaces section presence changes", () => {
+    const local = parseDesignMd(`# A\n## Color Palette\n- Primary — #FF8C42 — brand\n`);
+    const upstream = parseDesignMd(
+      `# B\n## Color Palette\n- Primary — #FF8C42 — brand\n## Agent Prompts\n### Brand voice\nTone.\n`,
+    );
+    const d = diffDesignSpecs(local, upstream);
+    expect(d.sectionPresenceChanged).toContain("agent-prompts");
+  });
+});

package/src/design/__tests__/lint.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Issue #245 M5 — DESIGN.md lint tests.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { lintDesignSpec } from "../lint";
+import { parseDesignMd } from "../parser";
+
+describe("lintDesignSpec — color-palette", () => {
+  it("warns when parser couldn't extract a value (rule: color-missing-value)", () => {
+    // Parser drops non-hex/rgb values during extraction, so the
+    // resulting token has no `.value` — the linter flags that.
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Primary — #FF8C42 — brand
+- Bad — notahex — wrong
+`));
+    expect(
+      r.issues.find((i) => i.rule === "color-missing-value" && i.name === "Bad"),
+    ).toBeDefined();
+  });
+
+  it("warns on missing color value", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Primary — see docs
+`));
+    expect(r.issues.find((i) => i.rule === "color-missing-value")?.severity).toBe("warning");
+  });
+
+  it("warns on slug collision", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Primary — #FF0000
+- primary — #00FF00
+`));
+    expect(r.issues.find((i) => i.rule === "color-slug-collision")).toBeDefined();
+  });
+
+  it("notes duplicate values across distinct names (info)", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Brand — #FF8C42 — main
+- Accent — #FF8C42 — secondary
+`));
+    const dup = r.issues.find((i) => i.rule === "color-duplicate-value");
+    expect(dup?.severity).toBe("info");
+  });
+});
+
+describe("lintDesignSpec — typography / layout / shadows / components", () => {
+  it("warns on a typography token with neither family nor size", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Typography
+- body: weight: 400
+`));
+    expect(r.issues.find((i) => i.rule === "typography-empty-token")).toBeDefined();
+  });
+
+  it("warns on layout slug collision", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Layout
+- sm: 0.5rem
+- SM: 0.5rem
+`));
+    expect(r.issues.find((i) => i.rule === "spacing-slug-collision")).toBeDefined();
+  });
+
+  it("warns on shadow slug collision", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Depth & Elevation
+- card — 0 1px 2px rgba(0,0,0,0.1)
+- Card — 0 2px 4px rgba(0,0,0,0.2)
+`));
+    expect(r.issues.find((i) => i.rule === "shadow-slug-collision")).toBeDefined();
+  });
+
+  it("warns on duplicate component H3 names", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Components
+
+### Button
+
+### button
+`));
+    expect(r.issues.find((i) => i.rule === "component-duplicate")).toBeDefined();
+  });
+});
+
+describe("lintDesignSpec — clean DESIGN.md", () => {
+  it("returns ok with empty issues for a well-formed spec", () => {
+    const r = lintDesignSpec(parseDesignMd(`# T
+## Color Palette
+- Primary — #FF8C42 — brand
+- Accent — #1A1F36 — text
+
+## Typography
+- body: font-family: Inter, sans-serif; size: 16px
+
+## Layout
+- sm: 0.5rem
+- md: 1rem
+
+## Depth & Elevation
+- card — 0 1px 3px rgba(0,0,0,0.1)
+`));
+    expect(r.issues).toEqual([]);
+    expect(r.ok).toBe(true);
+  });
+});

package/src/design/agents-link.ts

@@ -0,0 +1,165 @@
+/**
+ * AGENTS.md / CLAUDE.md ↔ DESIGN.md linker (Issue #245 M5).
+ *
+ * Drops a markered `## Design System` section into the project's
+ * agent guide files so coding agents read DESIGN.md and use the
+ * Mandu MCP tools (M4) before touching UI. Idempotent — running it
+ * twice never duplicates the section.
+ *
+ * The linker writes the same payload to whichever of `AGENTS.md` /
+ * `CLAUDE.md` exists. When neither exists in `force: true` mode it
+ * creates `AGENTS.md` (the open standard) seeded with just the
+ * design block — agents that consume `CLAUDE.md` follow the
+ * cross-reference to `AGENTS.md` per Anthropic's convention.
+ *
+ * The injected section:
+ *
+ *   - Names DESIGN.md as the canonical design source.
+ *   - Lists the 8 MCP tools with one-line descriptions.
+ *   - Spells out the §3.5 incremental loop as a 5-step prompt agents
+ *     can follow verbatim.
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export const DESIGN_LINK_MARKER_START =
+  "<!-- @mandu-design-link:start — managed by `mandu design link` / `init --design`, do not edit -->";
+export const DESIGN_LINK_MARKER_END = "<!-- @mandu-design-link:end -->";
+
+export interface LinkAgentsOptions {
+  /** Project root. */
+  rootDir: string;
+  /** Filenames to update. Defaults to `["AGENTS.md", "CLAUDE.md"]`. */
+  filenames?: readonly string[];
+  /**
+   * When true, create a fresh `AGENTS.md` containing just the design
+   * link block when none of `filenames` exists. Default false — the
+   * linker only updates existing files unless explicitly asked.
+   */
+  createIfMissing?: boolean;
+  /** Override DESIGN.md filename. Defaults to `DESIGN.md`. */
+  designFilename?: string;
+}
+
+export interface LinkAgentsResult {
+  files: Array<{
+    path: string;
+    /** "created" | "inserted" (markered block added) | "updated" (markered block replaced) | "unchanged" */
+    action: "created" | "inserted" | "updated" | "unchanged";
+  }>;
+  /** True when at least one file was written. */
+  changed: boolean;
+}
+
+/** Generate the markered block payload. Pure — used by tests too. */
+export function buildAgentsDesignBlock(designFilename: string = "DESIGN.md"): string {
+  const lines = [
+    DESIGN_LINK_MARKER_START,
+    "",
+    "## Design System",
+    "",
+    `This project uses **${designFilename}** as the single source of truth for visual design (colors, typography, spacing, shadows, components, agent prompts).`,
+    "Mandu's MCP tools expose every part of it without grepping the codebase. Agents MUST read DESIGN.md *before* writing or editing UI.",
+    "",
+    "### Tools (call before / during UI work)",
+    "",
+    "| Phase | Tool | Use it for |",
+    "|---|---|---|",
+    "| Read | `mandu.design.get` | Section-by-section DESIGN.md (or `'all'` for full spec). |",
+    "| Read | `mandu.design.prompt` | §9 Agent Prompts — pre-warm context every session. |",
+    "| Read | `mandu.component.list` | Existing components in `src/client/shared/ui/` + `widgets/`. Don't re-implement. |",
+    "| Check | `mandu.design.check` | Lint a file BEFORE editing — surfaces forbidden inline classes. |",
+    "| Discover | `mandu.design.extract` | Find token candidates the project uses but DESIGN.md doesn't list. |",
+    "| Patch | `mandu.design.propose` | One-call: extract → dry-run patch → user reviews diff. |",
+    "| Patch | `mandu.design.patch` | Section-safe add/update/remove. Defaults to `dry_run: true`. |",
+    "| Sync | `mandu.design.diff_upstream` | Compare against awesome-design-md slugs (e.g. `'stripe'`). |",
+    "",
+    "### 5-step UI workflow",
+    "",
+    "1. **Pre-warm.** Call `mandu.design.prompt` (and `mandu.design.get` for the section you'll touch) so your edit honours existing tokens.",
+    "2. **Inventory.** Call `mandu.component.list` for the matching category. Re-use first; only add when nothing fits.",
+    "3. **Check.** Before editing a file, call `mandu.design.check { file }` to see if the file already violates DESIGN.md §7.",
+    "4. **Edit.** Write the change. Use existing tokens from §2 / components from §1.",
+    "5. **Propose tokens.** If you introduced a new color/font/spacing pattern, call `mandu.design.propose` and ask the user to apply the patch (default `dry_run: true`).",
+    "",
+    "### Hard rules",
+    "",
+    "- Never invent colors / fonts / spacing values without a `mandu.design.propose` round.",
+    "- Never bypass `mandu.design.check` on a file you're about to edit.",
+    "- DESIGN.md is the spec — when in doubt, update DESIGN.md *first*, then write code.",
+    "",
+    DESIGN_LINK_MARKER_END,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Update agent guide files to reference DESIGN.md and the MCP tools.
+ *
+ * Behaviour per file:
+ *   - Marker present → replace the markered region (idempotent).
+ *   - File exists, no marker → append the block at the end.
+ *   - File missing → skip unless `createIfMissing: true`.
+ */
+export async function linkAgentsToDesignMd(
+  options: LinkAgentsOptions,
+): Promise<LinkAgentsResult> {
+  const filenames = options.filenames ?? ["AGENTS.md", "CLAUDE.md"];
+  const block = buildAgentsDesignBlock(options.designFilename);
+  const files: LinkAgentsResult["files"] = [];
+
+  let anyExists = false;
+  for (const name of filenames) {
+    const full = path.join(options.rootDir, name);
+    let existing: string | null;
+    try {
+      existing = await fs.readFile(full, "utf8");
+      anyExists = true;
+    } catch {
+      existing = null;
+    }
+
+    if (existing === null) {
+      files.push({ path: full, action: "unchanged" });
+      continue;
+    }
+
+    const startIdx = existing.indexOf(DESIGN_LINK_MARKER_START);
+    const endIdx = existing.indexOf(DESIGN_LINK_MARKER_END);
+    let next: string;
+    let action: LinkAgentsResult["files"][number]["action"];
+    if (startIdx >= 0 && endIdx > startIdx) {
+      const before = existing.slice(0, startIdx);
+      const after = existing.slice(endIdx + DESIGN_LINK_MARKER_END.length);
+      const replacement = block.replace(/\n+$/, "");
+      next = `${before}${replacement}${after}`;
+      action = next === existing ? "unchanged" : "updated";
+    } else {
+      const sep = existing.endsWith("\n") ? "" : "\n";
+      next = `${existing}${sep}\n${block}`;
+      action = "inserted";
+    }
+
+    if (action !== "unchanged") {
+      await fs.writeFile(full, next, "utf8");
+    }
+    files.push({ path: full, action });
+  }
+
+  if (!anyExists && options.createIfMissing) {
+    const target = path.join(options.rootDir, filenames[0] ?? "AGENTS.md");
+    const seed = `# Project Agent Guide\n\n${block}`;
+    await fs.writeFile(target, seed, "utf8");
+    // Replace the placeholder "unchanged" entry with the real outcome.
+    const idx = files.findIndex((f) => f.path === target);
+    if (idx >= 0) files[idx] = { path: target, action: "created" };
+    else files.push({ path: target, action: "created" });
+  }
+
+  return {
+    files,
+    changed: files.some((f) => f.action !== "unchanged"),
+  };
+}