@bridge-ui/vue 0.0.7 → 0.0.8

package/ai/AGENTS.md

@@ -0,0 +1,31 @@
+# Bridge UI (Vue) — agent instructions
+
+Use **`@bridge-ui/vue`**. Prefer Bridge components over ad-hoc markup.
+
+## Quick start
+
+```bash
+npm install @bridge-ui/vue
+npx bridge-ui-vue-ai install
+```
+
+## Always follow
+
+- Guidelines: `.ai/guidelines/core.md`
+- Component docs: `.ai/docs/components/` (index: `.ai/docs/README.md`)
+- Adapter samples: `.ai/docs/examples/`
+- Skills (on demand) under `.cursor/skills/`:
+  - `bridge-ui-setup`
+  - `bridge-ui-components`
+  - `bridge-ui-forms`
+  - `bridge-ui-overlays`
+
+Skills point at the docs — **read `.ai/docs/components/{Component}.md` for copy-paste examples**.
+
+## Hard rules
+
+1. Import from `@bridge-ui/vue/Components/{Name}`.
+2. Tailwind v4 + `@bridge-ui/vue/theme.css`.
+3. `createBridgeUI` / `BridgeUIProvider` + `BridgeUIHosts` when using action hooks.
+4. Fields: `v-model`.
+5. Modal body: `Card` (no `ModalCard`).

package/ai/README.md

@@ -0,0 +1,35 @@
+# AI resources (Vue)
+
+Consumer guidelines and Agent Skills for `@bridge-ui/vue`.
+
+Component **examples live in** [`../docs/components/`](../docs/components/). Adapter samples: [`../docs/examples/`](../docs/examples/). Skills only route agents to those pages.
+
+```bash
+npx bridge-ui-vue-ai install
+```
+
+## What gets installed
+
+| Path                           | Role                                                           |
+| ------------------------------ | -------------------------------------------------------------- |
+| `AGENTS.md` (root)             | Short stub / inject block — auto-loaded by Cursor, Codex, etc. |
+| `CLAUDE.md`                    | Symlink (or copy) to root `AGENTS.md` for Claude Code          |
+| `llms.txt`                     | Short package index some tools/LLMs look for                   |
+| `.ai/AGENTS.md`                | Full agent guide                                               |
+| `.ai/guidelines/`, `.ai/docs/` | Guidelines and component/example docs                          |
+| `.cursor/skills/bridge-ui-*`   | On-demand Agent Skills                                         |
+
+## `npx` / bin link
+
+`npx bridge-ui-vue-ai` resolves the bin from `node_modules/.bin`. After upgrading Bridge (especially with local `file:` installs), run `npm install` again so the bin link exists.
+
+Fallbacks if `npx` hits the registry (404):
+
+```bash
+npx --package=@bridge-ui/vue bridge-ui-vue-ai install
+node node_modules/@bridge-ui/vue/bin/ai.mjs install
+```
+
+## Dual React + Vue
+
+Install destinations collide (`.ai/`, `llms.txt`, skills, root stub). In apps that use both packages, run the AI install for **one** framework only.

package/ai/guidelines/core.md

@@ -0,0 +1,44 @@
+# Bridge UI (Vue) — consumer guidelines
+
+Use these rules when writing application code with `@bridge-ui/vue`. Do **not** invent APIs; prefer examples from package docs (`.ai/docs/components/` after install, or `docs/components/` in this package).
+
+## Install
+
+```bash
+npm install @bridge-ui/vue
+npx bridge-ui-vue-ai install
+```
+
+`@bridge-ui/core` is transitive. Peer: Vue ^3.4.
+
+## Setup (required)
+
+1. Tailwind CSS **v4**.
+2. `@import "@bridge-ui/vue/theme.css"`.
+3. `createBridgeUI` and/or `BridgeUIProvider` — see `.ai/docs/components/BridgeUIProvider.md`.
+4. Mount `BridgeUIHosts` when using action hooks.
+
+## Imports
+
+```ts
+import { Button } from "@bridge-ui/vue/Components/Button";
+```
+
+## Vue patterns
+
+| Concern    | Pattern                                            |
+| ---------- | -------------------------------------------------- |
+| Fields     | `v-model` / `modelValue`                           |
+| Modal open | `v-model`                                          |
+| Events     | emits / `v-on:close`                               |
+| Slots      | `<template #start>`                                |
+| Templates  | kebab-case attrs (`error-message`, `custom-props`) |
+
+## Hard rules
+
+- Prefer Bridge tokens (`color`, `size`, `variant`, `density`) when they exist.
+- `custom-props` is for **inner** parts; root HTML attrs stay on the component.
+- Modal/Drawer content: **`Card`** — no `ModalCard`.
+- Do not destructure `useBreakpoint()` helpers — keep the reactive object.
+- Do not compare Bridge to other UI libraries in generated docs or comments.
+- Load skills under `.cursor/skills/` and read the linked `.ai/docs/` pages for examples.

package/ai/llms.txt

@@ -0,0 +1,38 @@
+# @bridge-ui/vue
+
+> Vue 3 component library. Design tokens and utils come from transitive `@bridge-ui/core`.
+
+## Setup
+
+```bash
+npm install @bridge-ui/vue
+npx bridge-ui-vue-ai install
+```
+
+## AI + docs (this package)
+
+- ai/AGENTS.md
+- ai/llms.txt
+- ai/guidelines/core.md
+- ai/skills/*/SKILL.md
+- docs/README.md
+- docs/components/*.md
+- docs/examples/*
+
+After install:
+
+- AGENTS.md (root stub) + CLAUDE.md → AGENTS.md
+- .ai/AGENTS.md (full guide)
+- llms.txt
+- .ai/guidelines/
+- .ai/docs/ (components + examples)
+- .cursor/skills/bridge-ui-*
+
+## Imports
+
+- `@bridge-ui/vue`
+- `@bridge-ui/vue/Components/{Name}`
+- `@bridge-ui/vue/Provider`
+- `@bridge-ui/vue/Actions`
+- `@bridge-ui/vue/theme.css`
+- `@bridge-ui/vue/docs/components/{Name}.md`

package/ai/skills/bridge-ui-components/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: bridge-ui-components
+description: >-
+  Use Bridge UI Vue presentational components — Button, Avatar, Card, Alert,
+  Badge, Icon, Link, List, Tabs, Spinner, Skeleton, Progress, classes,
+  customProps, slots. Use when building UI outside forms and overlays.
+---
+
+# Bridge UI (Vue) — components
+
+Do **not** invent APIs. Copy examples from `.ai/docs/components/{Component}.md` (package: `docs/components/{Component}.md`).
+
+In templates, use kebab-case attrs (`start-icon`, `custom-props`, `error-message`).
+
+## Start here
+
+| Need                          | Doc                                                            |
+| ----------------------------- | -------------------------------------------------------------- |
+| Actions                       | `.ai/docs/components/Button.md`                                |
+| Surfaces / modal body         | `.ai/docs/components/Card.md`                                  |
+| Avatar                        | `.ai/docs/components/Avatar.md`                                |
+| Badge                         | `.ai/docs/components/Badge.md`                                 |
+| Alert                         | `.ai/docs/components/Alert.md`                                 |
+| Icon                          | `.ai/docs/components/Icon.md`                                  |
+| Lists                         | `.ai/docs/components/List.md`                                  |
+| Tabs                          | `.ai/docs/components/Tabs.md`                                  |
+| Spinner / skeleton / progress | `.ai/docs/components/Spinner.md`, `Skeleton.md`, `Progress.md` |
+| Index                         | `.ai/docs/README.md`                                           |
+
+## Hard rules
+
+1. Import from `@bridge-ui/vue/Components/{Name}`.
+2. Prefer Bridge tokens (`color`, `size`, `variant`, `density`) when they exist.
+3. `:classes` / `:custom-props` / named slots follow each component doc.
+4. Root HTML attributes stay on the component; use `custom-props` for **inner** parts.
+5. Modal/Drawer content uses **`Card`** — there is no `ModalCard` export.
+6. Do not compare Bridge to other UI libraries in generated docs or comments.

package/ai/skills/bridge-ui-forms/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: bridge-ui-forms
+description: >-
+  Build forms with Bridge UI Vue — TextField, Textarea, PasswordField,
+  NumberField, OtpField, Select, Autocomplete, Slider, Checkbox, Radio,
+  Switch, FormField, FormControl, BaseField. Use when wiring inputs,
+  validation chrome, or select.
+---
+
+# Bridge UI (Vue) — forms
+
+Do **not** invent APIs. Copy examples from `.ai/docs/components/{Component}.md`.
+
+## Binding
+
+Controlled fields: **`v-model` / `modelValue`**. Never React `value`/`onChange`.
+
+## Start here
+
+| Need                      | Doc                                                                |
+| ------------------------- | ------------------------------------------------------------------ |
+| Text input                | `.ai/docs/components/TextField.md`                                 |
+| Password                  | `.ai/docs/components/PasswordField.md`                             |
+| Number / OTP / textarea   | `.ai/docs/components/NumberField.md`, `OtpField.md`, `Textarea.md` |
+| Slider                    | `.ai/docs/components/Slider.md`                                    |
+| Select                    | `.ai/docs/components/Select.md`                                    |
+| Autocomplete              | `.ai/docs/components/Autocomplete.md`                              |
+| Checkbox / radio / switch | `.ai/docs/components/Checkbox.md`, `Radio.md`, `Switch.md`         |
+| Input chrome              | `.ai/docs/components/FormField.md`                                 |
+| Toggle row chrome         | `.ai/docs/components/FormControl.md`                               |
+| Custom control chrome     | `.ai/docs/components/BaseField.md`                                 |
+
+## Hard rules
+
+1. Map validation to `error`, `error-message`, `description`, `disabled`, `readOnly`.
+2. Native input attrs often go through `:custom-props` → `input` — see TextField docs.
+3. Use only documented option shapes for Select/Autocomplete.
+4. Prefer public fields/controls in apps. `FormField`, `FormControl`, `BaseField`, and `Listbox` are exported building blocks for advanced composition — they are **not** registry keys. Theme via the public parent (`components.TextField`, `tokens.baseField`, `tokens.formControl`, `tokens.listbox` on Select/Autocomplete). Shared form density: `global.formDefaults: { size, rounded }` (Radio/Switch ignore `rounded`).

package/ai/skills/bridge-ui-overlays/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: bridge-ui-overlays
+description: >-
+  Bridge UI Vue overlays and imperative actions — Modal, Drawer, Menu, Tooltip,
+  Snackbar, useModalAction, useDialogAction, useDrawerAction, useSnackbarAction,
+  BridgeUIHosts. Use when opening layers or toast/dialog flows.
+---
+
+# Bridge UI (Vue) — overlays & actions
+
+Do **not** invent APIs. Copy examples from `.ai/docs/components/{Component}.md`.
+
+## Binding
+
+Overlays: **`v-model`**. Modal/Drawer body: **`Card`** (no `ModalCard`).
+
+## Start here
+
+| Need              | Doc                                        |
+| ----------------- | ------------------------------------------ |
+| Modal             | `.ai/docs/components/Modal.md`             |
+| Drawer            | `.ai/docs/components/Drawer.md`            |
+| Menu              | `.ai/docs/components/Menu.md`              |
+| Tooltip           | `.ai/docs/components/Tooltip.md`           |
+| Snackbar          | `.ai/docs/components/Snackbar.md`          |
+| useModalAction    | `.ai/docs/components/useModalAction.md`    |
+| useDialogAction   | `.ai/docs/components/useDialogAction.md`   |
+| useDrawerAction   | `.ai/docs/components/useDrawerAction.md`   |
+| useSnackbarAction | `.ai/docs/components/useSnackbarAction.md` |
+| Breakpoints       | `.ai/docs/components/useBreakpoint.md`     |
+
+## Hard rules
+
+1. Mount `BridgeUIHosts` before using action hooks.
+2. `align` on Modal applies on all breakpoints — use `useBreakpoint` for mobile bottom sheets (keep the reactive object; do not destructure helpers).
+3. Menu panel children are real components (`List` / `ListItem`, etc.). Docs may show a local `MenuContent` helper — that is **not** a Bridge export.
+4. Match action `open` option shapes to the `use*Action` docs. Escape closes the top nested layer only.

package/ai/skills/bridge-ui-setup/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: bridge-ui-setup
+description: >-
+  Install and configure Bridge UI Vue — Tailwind v4 theme CSS, createBridgeUI /
+  BridgeUIProvider, component defaults, icon and i18n adapters, BridgeUIHosts,
+  useBridgeUI. Use when scaffolding Bridge, wiring the provider, or fixing
+  missing theme / hosts / adapters.
+---
+
+# Bridge UI (Vue) — setup
+
+Do **not** invent APIs. Read the package docs (after install: `.ai/docs/`; in this package: `docs/`).
+
+## Install
+
+```bash
+npm install @bridge-ui/vue
+npx bridge-ui-vue-ai install
+```
+
+## Required reading
+
+| Topic                                                  | Doc                                       |
+| ------------------------------------------------------ | ----------------------------------------- |
+| Provider / plugin, `global`, `components`, icons, i18n | `.ai/docs/components/BridgeUIProvider.md` |
+| Icon adapter usage                                     | `.ai/docs/components/Icon.md`             |
+| i18n adapter                                           | `.ai/docs/components/I18n.md`             |
+| Breakpoints                                            | `.ai/docs/components/useBreakpoint.md`    |
+| Adapter sample code                                    | `.ai/docs/examples/`                      |
+
+## Hard rules
+
+1. Tailwind CSS **v4** + `@import "@bridge-ui/vue/theme.css"`.
+2. Use `app.use(createBridgeUI({ ... }))` and/or `<BridgeUIProvider>`.
+3. Mount `BridgeUIHosts` when using action hooks (`useDialogAction`, `useModalAction`, `useDrawerAction`, `useSnackbarAction`).
+4. Semantic icon names and chrome strings need `global.icons` / `global.i18n` — copy samples from `.ai/docs/examples/`.
+5. Prefer deep imports: `@bridge-ui/vue/Components/{Name}`.
+6. Do not destructure `useBreakpoint()` helpers — keep the reactive object.

package/bin/__tests__/ai.test.ts

@@ -0,0 +1,319 @@
+// @vitest-environment node
+
+// ** External Imports
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, test } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const packageRoot = resolve(__dirname, "../..");
+const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+
+const aiRoot = join(packageRoot, "ai");
+const packageName = pkg.name as string;
+const binPath = join(packageRoot, "bin", "ai.mjs");
+const binName = Object.keys(pkg.bin ?? {})[0] as string;
+
+const MARK_END = "<!-- bridge-ui-ai:end -->";
+const MARK_START = "<!-- bridge-ui-ai:start -->";
+
+const skillNames = [
+  "bridge-ui-forms",
+  "bridge-ui-setup",
+  "bridge-ui-overlays",
+  "bridge-ui-components",
+] as const;
+
+const installedRels = [
+  ".ai/docs",
+  "llms.txt",
+  ".ai/AGENTS.md",
+  ".ai/guidelines",
+  ...skillNames.map((name) => join(".cursor", "skills", name)),
+] as const;
+
+let appRoot: string;
+
+function createAppRoot() {
+  appRoot = mkdtempSync(join(tmpdir(), "bridge-ui-ai-"));
+  return appRoot;
+}
+
+function run(args: string[]) {
+  return spawnSync(process.execPath, [binPath, ...args], {
+    encoding: "utf8",
+    env: process.env,
+  });
+}
+
+function isSymlink(path: string) {
+  return lstatSync(path).isSymbolicLink();
+}
+
+afterEach(() => {
+  if (appRoot && existsSync(appRoot)) {
+    rmSync(appRoot, { recursive: true, force: true });
+  }
+});
+
+describe("bridge-ui-ai CLI", () => {
+  test("it should print help for help and --help", () => {
+    for (const args of [["help"], ["--help"], ["-h"], []]) {
+      const result = run(args);
+
+      expect(result.status).toBe(0);
+      expect(result.stdout).toContain("install");
+      expect(result.stdout).toContain("remove");
+      expect(result.stdout).toContain(`Usage: ${binName}`);
+    }
+  });
+
+  test("it should exit with code 1 for unknown commands", () => {
+    const result = run(["nope"]);
+
+    expect(result.status).toBe(1);
+    expect(result.stdout).toContain(`Usage: ${binName}`);
+  });
+
+  test("it should symlink AI resources and write a root AGENTS.md stub", () => {
+    const cwd = createAppRoot();
+    const result = run(["install", "--cwd", cwd]);
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain(
+      `Installed Bridge UI AI resources from ${packageName}`,
+    );
+
+    for (const rel of installedRels) {
+      const dest = join(cwd, rel);
+
+      expect(isSymlink(dest), rel).toBe(true);
+      expect(existsSync(dest), rel).toBe(true);
+    }
+
+    const agents = join(cwd, "AGENTS.md");
+    const content = readFileSync(agents, "utf8");
+
+    expect(isSymlink(agents)).toBe(false);
+    expect(content).toContain(MARK_START);
+    expect(content).toContain(MARK_END);
+    expect(content).toContain(packageName);
+    expect(content).toContain(".ai/AGENTS.md");
+    expect(content).not.toBe(readFileSync(join(aiRoot, "AGENTS.md"), "utf8"));
+    expect(realpathSync(join(cwd, ".ai", "AGENTS.md"))).toBe(
+      realpathSync(join(aiRoot, "AGENTS.md")),
+    );
+  });
+
+  test("it should copy AI resources when --copy is set", () => {
+    const cwd = createAppRoot();
+
+    const result = run(["install", "--copy", "--cwd", cwd]);
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toMatch(/copied\s+\.ai\/AGENTS\.md/);
+
+    for (const rel of installedRels) {
+      const dest = join(cwd, rel);
+
+      expect(isSymlink(dest), rel).toBe(false);
+      expect(existsSync(dest), rel).toBe(true);
+    }
+
+    const agents = join(cwd, "AGENTS.md");
+
+    expect(isSymlink(agents)).toBe(false);
+    expect(readFileSync(agents, "utf8")).toContain(MARK_START);
+    expect(readFileSync(agents, "utf8")).not.toBe(
+      readFileSync(join(aiRoot, "AGENTS.md"), "utf8"),
+    );
+  });
+
+  test("it should inject a Bridge block when AGENTS.md already exists", () => {
+    const cwd = createAppRoot();
+
+    const agentsPath = join(cwd, "AGENTS.md");
+
+    writeFileSync(agentsPath, "# My app agents\n\nKeep me.\n");
+
+    const result = run(["install", "--cwd", cwd]);
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toMatch(/updated\s+AGENTS\.md/);
+
+    const content = readFileSync(agentsPath, "utf8");
+
+    expect(content).toContain(MARK_END);
+    expect(content).toContain("Keep me.");
+    expect(content).toContain(MARK_START);
+    expect(content).toContain(packageName);
+    expect(isSymlink(agentsPath)).toBe(false);
+    expect(content).toContain("# My app agents");
+    expect(content).toContain(`npx ${binName} install`);
+  });
+
+  test("it should replace an existing Bridge block on reinstall", () => {
+    const cwd = createAppRoot();
+
+    const agentsPath = join(cwd, "AGENTS.md");
+
+    writeFileSync(
+      agentsPath,
+      [
+        "# My app agents",
+        "",
+        MARK_START,
+        "stale block",
+        MARK_END,
+        "",
+        "After block.",
+        "",
+      ].join("\n"),
+    );
+
+    const result = run(["install", "--cwd", cwd]);
+
+    expect(result.status).toBe(0);
+
+    const content = readFileSync(agentsPath, "utf8");
+
+    expect(content).toContain("After block.");
+    expect(content).toContain("## Bridge UI");
+    expect(content).toContain("# My app agents");
+    expect(content).not.toContain("stale block");
+  });
+
+  test("it should remove linked resources, root stub, and empty dirs", () => {
+    const cwd = createAppRoot();
+
+    expect(run(["install", "--cwd", cwd]).status).toBe(0);
+
+    const result = run(["remove", "--cwd", cwd]);
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toContain(
+      `Removed Bridge UI AI resources for ${packageName}`,
+    );
+
+    for (const rel of installedRels) {
+      expect(existsSync(join(cwd, rel)), rel).toBe(false);
+    }
+
+    expect(existsSync(join(cwd, "AGENTS.md"))).toBe(false);
+    expect(existsSync(join(cwd, "CLAUDE.md"))).toBe(false);
+    expect(existsSync(join(cwd, ".ai"))).toBe(false);
+    expect(existsSync(join(cwd, ".cursor"))).toBe(false);
+  });
+
+  test("it should strip the Bridge block and keep custom AGENTS.md content", () => {
+    const cwd = createAppRoot();
+
+    const agentsPath = join(cwd, "AGENTS.md");
+
+    writeFileSync(agentsPath, "# My app agents\n\nKeep me.\n");
+
+    expect(run(["install", "--cwd", cwd]).status).toBe(0);
+    expect(run(["remove", "--cwd", cwd]).status).toBe(0);
+
+    expect(existsSync(agentsPath)).toBe(true);
+
+    const content = readFileSync(agentsPath, "utf8");
+
+    expect(content).toContain("Keep me.");
+    expect(content).toContain("# My app agents");
+    expect(content).not.toContain(MARK_END);
+    expect(content).not.toContain(MARK_START);
+  });
+
+  test("it should recreate parent dirs when installing over a previous install", () => {
+    const cwd = createAppRoot();
+
+    expect(run(["install", "--cwd", cwd]).status).toBe(0);
+    expect(run(["remove", "--cwd", cwd]).status).toBe(0);
+
+    mkdirSync(join(cwd, ".ai"), { recursive: true });
+    mkdirSync(join(cwd, ".cursor", "skills"), { recursive: true });
+
+    const result = run(["install", "--copy", "--cwd", cwd]);
+
+    expect(result.status).toBe(0);
+    expect(existsSync(join(cwd, ".ai", "guidelines", "core.md"))).toBe(true);
+    expect(
+      existsSync(join(cwd, ".cursor", "skills", "bridge-ui-setup", "SKILL.md")),
+    ).toBe(true);
+  });
+
+  test("it should remove AGENTS.md after install --copy", () => {
+    const cwd = createAppRoot();
+
+    expect(run(["install", "--copy", "--cwd", cwd]).status).toBe(0);
+    expect(existsSync(join(cwd, "AGENTS.md"))).toBe(true);
+
+    expect(run(["remove", "--cwd", cwd]).status).toBe(0);
+    expect(existsSync(join(cwd, "AGENTS.md"))).toBe(false);
+  });
+
+  test("it should link CLAUDE.md to the root stub and remove it on uninstall", () => {
+    const cwd = createAppRoot();
+
+    expect(run(["install", "--cwd", cwd]).status).toBe(0);
+
+    const claude = join(cwd, "CLAUDE.md");
+    const agents = join(cwd, "AGENTS.md");
+
+    expect(isSymlink(claude)).toBe(true);
+    expect(realpathSync(claude)).toBe(realpathSync(agents));
+
+    expect(run(["remove", "--cwd", cwd]).status).toBe(0);
+    expect(existsSync(claude)).toBe(false);
+  });
+
+  test("it should not overwrite a custom CLAUDE.md", () => {
+    const cwd = createAppRoot();
+    const claude = join(cwd, "CLAUDE.md");
+
+    writeFileSync(claude, "# My Claude rules\n");
+
+    expect(run(["install", "--cwd", cwd]).status).toBe(0);
+    expect(isSymlink(claude)).toBe(false);
+    expect(readFileSync(claude, "utf8")).toBe("# My Claude rules\n");
+
+    expect(run(["remove", "--cwd", cwd]).status).toBe(0);
+    expect(existsSync(claude)).toBe(true);
+    expect(readFileSync(claude, "utf8")).toBe("# My Claude rules\n");
+  });
+
+  test("it should not mutate another package AGENTS.md when replacing a foreign symlink", () => {
+    const cwd = createAppRoot();
+
+    const otherRoot = resolve(packageRoot, "../react");
+    const otherAgents = join(otherRoot, "ai", "AGENTS.md");
+    const before = readFileSync(otherAgents, "utf8");
+
+    symlinkSync(otherAgents, join(cwd, "AGENTS.md"));
+
+    const result = run(["install", "--cwd", cwd]);
+
+    expect(result.status).toBe(0);
+    expect(isSymlink(join(cwd, "AGENTS.md"))).toBe(false);
+    expect(readFileSync(join(cwd, "AGENTS.md"), "utf8")).toContain(MARK_START);
+
+    expect(readFileSync(otherAgents, "utf8")).toBe(before);
+    expect(readFileSync(otherAgents, "utf8")).not.toContain(MARK_START);
+    expect(readFileSync(otherAgents, "utf8")).not.toContain(packageName);
+  });
+});