@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ee13359

package/clients/cli/lib/json-shim.test.mjs

@@ -20,7 +20,12 @@
  */
 
 import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {Command} from 'commander';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {installJsonShim} from './json-shim.mjs';
+import {setJsonMode} from '../../../foundation/response/json.mjs';
 
 function parseJson(stdout) {
   return JSON.parse(stdout);
@@ -207,3 +212,81 @@ describe('--json shim: stdout discipline under --json', () => {
     }
   });
 });
+
+describe('--json shim: help shown for a failed invocation is an error envelope', () => {
+  it('astryx help bogus --json emits ERR_UNKNOWN_COMMAND, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['help', 'bogus', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
+    expect(parsed.error).toMatch(/bogus/);
+  });
+
+  it('astryx layout --json (group, no subcommand) emits ERR_MISSING_ARGUMENT, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['layout', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
+    expect(parsed.suggestions.map((s) => s.name)).toContain('layout expand');
+  });
+
+  it('astryx layout (no --json) still prints help to stderr, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['layout']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/Usage: astryx layout/);
+  });
+
+  it('the real binary emits the same envelope for help bogus --json', () => {
+    // One program per process, so the root's own outputHelp patch is used here.
+    const bin = fileURLToPath(new URL('../bin/astryx.mjs', import.meta.url));
+    const res = spawnSync(process.execPath, [bin, 'help', 'bogus', '--json'], {
+      encoding: 'utf-8',
+      timeout: 20_000,
+    });
+    expect(res.status).toBe(1);
+    expect(res.stderr).toBe('');
+    const parsed = parseJson(res.stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
+  });
+
+  it('a group added after install gets the same error envelope', () => {
+    const program = new Command('astryx');
+    installJsonShim(program);
+    // Added later, so only the prototype-level patch covers its outputHelp.
+    const late = new Command('late');
+    late.command('child');
+    program.addCommand(late);
+    /** @type {string[]} */
+    const writes = [];
+    const origWrite = process.stdout.write;
+    // @ts-expect-error - test-only capture
+    process.stdout.write = (chunk) => writes.push(String(chunk)) > 0;
+    setJsonMode(true);
+    delete process.__xdsJsonHandled;
+    try {
+      late.outputHelp({error: true});
+    } finally {
+      process.stdout.write = origWrite;
+      setJsonMode(false);
+      delete process.__xdsJsonHandled;
+    }
+    const parsed = parseJson(writes.join(''));
+    expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
+    expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
+  });
+
+  it('astryx help layout --json still emits the help envelope, exit 0', async () => {
+    const {status, stdout} = await runCli(['help', 'layout', '--json']);
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('help');
+    expect(parsed.data.command).toBe('astryx layout');
+  });
+});

package/clients/cli/lib/manifest.d.ts

@@ -48,6 +48,8 @@ export interface ManifestCommand {
   responseTypes?: string[];
   /** Example invocations. */
   examples?: string[];
+  /** Documented exit codes: the process exit status and when it occurs. */
+  exitCodes?: {code: number; when: string}[];
   /** Nested subcommands (e.g. `theme build` under `theme`). */
   subcommands?: ManifestCommand[];
 }

package/clients/cli/lib/manifest.mjs

@@ -35,6 +35,8 @@
  */
 
 import {API_VERSION} from '../../../foundation/response/json.mjs';
+import {commandDocsOf} from './define-command.mjs';
+import {doc as manifestDoc} from '../commands/manifest.doc.mjs';
 
 /**
  * Response `type` discriminators each fully-qualified command can emit in
@@ -55,7 +57,13 @@ export const RESPONSE_TYPES = {
     'component.detail.showcase',
     'component.detail.blocks',
   ],
-  docs: ['docs.list', 'docs.detail', 'docs.detail.section'],
+  docs: [
+    'docs.list',
+    'docs.index',
+    'docs.detail',
+    'docs.detail.section',
+    'docs.node',
+  ],
   blog: ['blog.list', 'blog.detail'],
   discover: [
     'discover.list',
@@ -105,7 +113,13 @@ const EXAMPLES = {
     'astryx component XDSButton',
     'astryx component XDSButton --props --json',
   ],
-  docs: ['astryx docs', 'astryx docs spacing --json'],
+  docs: [
+    'astryx docs',
+    'astryx docs spacing --json',
+    'astryx docs theme',
+    'astryx docs theme quick-start',
+    'astryx docs cli/integrations --full',
+  ],
   discover: ['astryx discover --json'],
   search: [
     'astryx search modal --json',
@@ -232,6 +246,18 @@ function fullName(cmd, root) {
   return parts.join(' ');
 }
 
+/**
+ * The docs a command was built from. `manifest` is registered by hand in
+ * index.mjs, so its CommandDoc is read here.
+ * @param {import('commander').Command} cmd
+ * @param {string} name
+ */
+function docsOf(cmd, name) {
+  return (
+    commandDocsOf(cmd) ?? (name === 'manifest' ? {doc: manifestDoc} : undefined)
+  );
+}
+
 /**
  * Recursively describe a Commander command and its subcommands.
  *
@@ -247,6 +273,8 @@ function describeCommand(cmd, root, jsonSupported) {
   // `_hidden` is a Commander internal not present on its public types.
   if (!name || /** @type {any} */ (cmd)._hidden || name === 'help') return null;
 
+  const docs = docsOf(cmd, name);
+
   const subcommands = /** @type {object[]} */ (
     (cmd.commands || [])
       .map(sub => describeCommand(sub, root, jsonSupported))
@@ -279,6 +307,12 @@ function describeCommand(cmd, root, jsonSupported) {
 
   if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
 
+  const exitCodes = (docs?.doc.exitCodes ?? []).map(({code, when}) => ({
+    code,
+    when,
+  }));
+  if (exitCodes.length > 0) entry.exitCodes = exitCodes;
+
   // Sort subcommands by name for a stable, agent-facing contract — the same
   // guarantee the top-level command list makes. Otherwise Commander
   // registration order leaks into the manifest and a pure reorder of

package/clients/cli/lib/manifest.test.mjs

@@ -196,3 +196,20 @@ describe('manifest: e2e', () => {
       .toContain('component.list');
   });
 });
+
+describe('manifest: text projection', () => {
+  it('astryx manifest (text) uses the JSON entry keys as its field names', async () => {
+    const text = await runCli(['manifest']);
+    expect(text.status).toBe(0);
+    const json = JSON.parse((await runCli(['manifest', '--json'])).stdout);
+    const jsonKeys = new Set(json.data.commands.flatMap((c) => Object.keys(c)));
+    const textKeys = new Set(
+      text.stdout
+        .split('\n')
+        .map((line) => /^([A-Za-z]+):\s/.exec(line)?.[1])
+        .filter(Boolean),
+    );
+    expect(textKeys).toContain('name');
+    for (const key of textKeys) expect(jsonKeys).toContain(key);
+  });
+});

package/foundation/agent-docs/agent-docs.d.mts

@@ -182,6 +182,8 @@ export function removeXdsBlock(filePath: string, { deleteIfEmpty }?: {
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
+ *   resolves outside `targetDir`; nothing is changed.
  */
 export function removeAgentDocs(targetDir: string): void;
 /**
@@ -208,6 +210,8 @@ export function removeAgentDocs(targetDir: string): void;
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
  * @returns {string[]} List of files written
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
+ *   write resolves outside `targetDir`; nothing is written.
  */
 export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics, renderedBlock, }?: {
     zh?: boolean | undefined;

package/foundation/agent-docs/agent-docs.mjs

@@ -22,11 +22,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {findCoreDir, CLI_ROOT} from '../fs/paths.mjs';
-import {assertWithin} from '../fs/path-safety.mjs';
+import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
 import {getCliInvocation} from '../env/package-manager.mjs';
 import {discoverComponents} from '../discovery/component-discovery.mjs';
 import {Project} from '../config/project.mjs';
 import {humanLog} from '../response/json.mjs';
+import {ERROR_CODES} from '../response/error-codes.mjs';
 import {
   AGENTS_MD,
   CLAUDE_MD,
@@ -485,6 +486,7 @@ export function generateCompressedIndex(
   if (resolvedTopics.length > 0) {
     lines.push(`  docs <topic>       ${resolvedTopics.join(', ')}`);
   }
+  lines.push('  docs cli           commands, API reference, integration authoring (one level at a time)');
   lines.push('  swizzle <Name>     eject component source for deep customization');
   lines.push('  upgrade --apply    run after any Astryx or integration dependency bump');
   const appendCount = agentDocs.reduce(
@@ -705,12 +707,65 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
   return true;
 }
 
+/**
+ * Whether an agent-doc file already carries a managed-block marker.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function hasManagedMarker(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return content.includes(MARKER_START) || content.includes(LEGACY_MARKER_START);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `removeXdsBlock` would change `filePath`: it holds one well-formed
+ * managed block.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function hasRemovableBlock(filePath) {
+  try {
+    return findManagedBlock(fs.readFileSync(filePath, 'utf-8')) != null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every file a run writes must resolve inside `targetDir`, symlinks
+ * included. Checked for the whole write set before the first write, so an
+ * escape writes nothing.
+ * @param {string} targetDir
+ * @param {Iterable<string>} relPaths
+ */
+function assertTargetsWithin(targetDir, relPaths) {
+  for (const p of relPaths) {
+    assertWithin(p, targetDir, {label: 'agent docs path'});
+  }
+}
+
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
+ *   resolves outside `targetDir`; nothing is changed.
  */
 export function removeAgentDocs(targetDir) {
   const allPaths = discoverAgentDocs(targetDir);
+  try {
+    assertTargetsWithin(
+      targetDir,
+      allPaths.filter(p => hasRemovableBlock(path.join(targetDir, p))),
+    );
+  } catch (err) {
+    // The code reaches the error envelope as is, so it must be registered.
+    if (!(err instanceof PathSafetyError)) throw err;
+    throw new PathSafetyError(err.message, ERROR_CODES.ERR_PATH_TRAVERSAL);
+  }
 
   for (const p of allPaths) {
     const filePath = path.join(targetDir, p);
@@ -718,9 +773,9 @@ export function removeAgentDocs(targetDir) {
     const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;
     if (removeXdsBlock(filePath, {deleteIfEmpty})) {
       if (!fs.existsSync(filePath)) {
-        humanLog(`✓ Removed empty ${p}`);
+        humanLog(`[ok] Removed empty ${p}`);
       } else {
-        humanLog(`✓ Removed design system section from ${p}`);
+        humanLog(`[ok] Removed design system section from ${p}`);
       }
     }
   }
@@ -750,6 +805,8 @@ export function removeAgentDocs(targetDir) {
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
  * @returns {string[]} List of files written
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
+ *   write resolves outside `targetDir`; nothing is written.
  */
 export function installAgentDocs(
   targetDir,
@@ -806,6 +863,7 @@ export function installAgentDocs(
   // Agent preset
   if (agent) {
     const {inject, create} = resolveAgentPaths(targetDir, agent);
+    assertTargetsWithin(targetDir, [...inject, ...create]);
     for (const p of inject) {
       injectXdsBlock(path.join(targetDir, p), compressedIndex);
       written.push(p);
@@ -833,6 +891,14 @@ export function installAgentDocs(
   if (existing.length > 0) {
     const wrappers = discoverAgentDocWrappers(targetDir, existing);
     const targets = existing.filter(p => !wrappers.has(p));
+    // A refresh skips unmarked files and a wrapper is only written when it
+    // carries a block, so only the files this run writes are checked.
+    /** @param {string} p */
+    const marked = p => hasManagedMarker(path.join(targetDir, p));
+    assertTargetsWithin(targetDir, [
+      ...targets.filter(p => !onlyReplace || marked(p)),
+      ...[...wrappers].filter(marked),
+    ]);
 
     for (const p of targets) {
       const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});
@@ -860,6 +926,7 @@ export function installAgentDocs(
   if (onlyReplace) return written;
 
   const defaultPath = AGENTS_MD;
+  assertTargetsWithin(targetDir, [defaultPath]);
   injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
     createIfMissing: true,
     header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,

package/foundation/agent-docs/agent-docs.path-safety.test.mjs

@@ -1,22 +1,31 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Path-safety regression tests for `--agent-docs-path`.
+ * @file Path-safety regression tests for agent-doc writes.
  *
  * `installAgentDocs(targetDir, {paths})` previously joined each path
  * onto `targetDir` with no validation, so:
  *   - `../OUT.md` wrote outside `targetDir`
  *   - `/tmp/x.md` was silently re-rooted under `targetDir`
  *
- * Both cases now throw PathSafetyError before any file is touched.
+ * Auto-detected and preset files were never checked at all, so a `CLAUDE.md`
+ * or `.claude/` symlinked out of the project had the block written through
+ * it. Every case now throws PathSafetyError before any file is touched.
+ *
+ * `removeAgentDocs` (`init --remove-agents`) stripped or deleted a block
+ * through the same kind of link and reported success. It now refuses with
+ * `ERR_PATH_TRAVERSAL` before any file is touched.
  */
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {installAgentDocs} from './agent-docs.mjs';
+import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';
 import {PathSafetyError} from '../fs/path-safety.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const BLOCK = '<!-- ASTRYX:START -->\nmanaged\n<!-- ASTRYX:END -->';
 
 let tmpDir;
 beforeEach(() => {
@@ -26,6 +35,28 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
+/** A project dir plus a sibling dir outside it. */
+function layout() {
+  const project = path.join(tmpDir, 'project');
+  const outside = path.join(tmpDir, 'outside');
+  fs.mkdirSync(project, {recursive: true});
+  fs.mkdirSync(outside, {recursive: true});
+  return {project, outside};
+}
+
+/**
+ * @param {() => unknown} fn
+ * @returns {unknown} what `fn` threw
+ */
+function thrownBy(fn) {
+  try {
+    fn();
+  } catch (err) {
+    return err;
+  }
+  throw new Error('expected a throw');
+}
+
 describe('installAgentDocs path safety', () => {
   it('rejects --agent-docs-path that escapes the target directory', () => {
     const target = path.join(tmpDir, 'project');
@@ -64,3 +95,234 @@ describe('installAgentDocs path safety', () => {
     expect(fs.existsSync(path.join(tmpDir, 'escaped.md'))).toBe(false);
   });
 });
+
+describe('installAgentDocs never writes through a symlink out of the project', () => {
+  it('refuses an auto-detected file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      /outside the project root/,
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  });
+
+  it('refuses a preset file reached through a symlinked directory', () => {
+    const {project, outside} = layout();
+    fs.symlinkSync(outside, path.join(project, '.claude'));
+
+    expect(() =>
+      installAgentDocs(project, {agent: 'claude', renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('refuses an existing preset file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    expect(() =>
+      installAgentDocs(project, {agent: 'cursor', renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('writes nothing when any file of the set escapes', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      PathSafetyError,
+    );
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  });
+
+  it('refuses to refresh a managed block that lives outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK.replace('managed', 'old')}\n`);
+    const before = fs.readFileSync(shared, 'utf-8');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() =>
+      installAgentDocs(project, {onlyReplace: true, renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(before);
+  });
+
+  it('refuses to strip a duplicate block from a wrapper that links outside', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${BLOCK}\n`);
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `@AGENTS.md\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      PathSafetyError,
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`@AGENTS.md\n\n${BLOCK}\n`);
+  });
+
+  it('still refreshes in-project blocks beside an unmarked outside link it skips', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(
+      path.join(project, 'AGENTS.md'),
+      `# Agents\n\n${BLOCK.replace('managed', 'old')}\n`,
+    );
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    expect(
+      installAgentDocs(project, {onlyReplace: true, renderedBlock: BLOCK}),
+    ).toEqual(['AGENTS.md']);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toContain(
+      'managed',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('writes through a symlink that stays inside the project', () => {
+    const {project} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
+    fs.symlinkSync('AGENTS.md', path.join(project, 'CLAUDE.md'));
+
+    expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
+      'AGENTS.md',
+      'CLAUDE.md',
+    ]);
+    const content = fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8');
+    expect(content.split('<!-- ASTRYX:START -->')).toHaveLength(2);
+  });
+});
+
+describe('init --features agents with an agent doc linked outside the project', () => {
+  it('writes nothing outside, reports path-safety, and exits 1 in both modes', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(project, {recursive: true});
+    fs.mkdirSync(outside, {recursive: true});
+    fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const json = await runCli(['init', '--features', 'agents', '--json'], project);
+    expect(json.status).toBe(1);
+    const env = JSON.parse(json.stdout);
+    expect(env.type).toBe('init.run');
+    expect(env.data.docsError).toMatchObject({kind: 'path-safety'});
+
+    const text = await runCli(['init', '--features', 'agents'], project);
+    expect(text.status).toBe(1);
+
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  }, 30_000);
+});
+
+describe('removeAgentDocs never changes a file out of the project', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('refuses to strip a block from a file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const err = thrownBy(() => removeAgentDocs(project));
+    expect(err).toBeInstanceOf(PathSafetyError);
+    expect(err).toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`# Shared\n\n${BLOCK}\n`);
+  });
+
+  it('refuses to delete a file reached through a symlinked directory', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    const content = `# CLAUDE\n\nProject-specific guidance for AI coding agents.\n\n${BLOCK}\n`;
+    fs.writeFileSync(shared, content);
+    fs.symlinkSync(outside, path.join(project, '.claude'));
+
+    expect(thrownBy(() => removeAgentDocs(project))).toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(content);
+  });
+
+  it('changes nothing when any file of the set escapes', () => {
+    const {project, outside} = layout();
+    const agents = `# Agents\n\nkeep\n\n${BLOCK}\n`;
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), agents);
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(thrownBy(() => removeAgentDocs(project))).toBeInstanceOf(PathSafetyError);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(agents);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`# Shared\n\n${BLOCK}\n`);
+  });
+
+  it('still strips in-project blocks beside an unmarked outside link it skips', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\nkeep\n\n${BLOCK}\n`);
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    removeAgentDocs(project);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n\nkeep\n',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('strips through a symlink that stays inside the project', () => {
+    const {project} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\nkeep\n\n${BLOCK}\n`);
+    fs.symlinkSync('AGENTS.md', path.join(project, 'CLAUDE.md'));
+
+    removeAgentDocs(project);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n\nkeep\n',
+    );
+  });
+});
+
+describe('init --remove-agents with an agent doc linked outside the project', () => {
+  it('changes nothing outside, fails with ERR_PATH_TRAVERSAL, and exits 1 in both modes', async () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    const content = `# Shared\n\n${BLOCK}\n`;
+    fs.writeFileSync(shared, content);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const json = await runCli(['init', '--remove-agents', '--json'], project);
+    expect(json.status).toBe(1);
+    const env = JSON.parse(json.stdout);
+    expect(env).toMatchObject({apiVersion: 1, code: 'ERR_PATH_TRAVERSAL'});
+    expect(env.error).toMatch(/"CLAUDE\.md": resolves outside the project root/);
+    expect(env).not.toHaveProperty('data');
+
+    const text = await runCli(['init', '--remove-agents'], project);
+    expect(text.status).toBe(1);
+    expect(text.stderr).toMatch(/^Error: .*"CLAUDE\.md": resolves outside the project root/m);
+    expect(text.stdout).not.toMatch(/removed/i);
+
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(content);
+  }, 30_000);
+});

package/foundation/agent-docs/agent-docs.test.mjs

@@ -134,7 +134,6 @@ describe('generateCompressedIndex', () => {
     const line = topicLine(generateCompressedIndex('1.0.0'));
     for (const topic of [
       'getting-started',
-      'cli-integrations',
       'browser-support',
       'styling-libraries',
       'working-with-ai',
@@ -143,6 +142,16 @@ describe('generateCompressedIndex', () => {
     }
   });
 
+  it('points to the CLI docs tree on a line of its own', () => {
+    // The integration guide lives in the docs tree now (cli/integrations), so
+    // the topic line no longer names it; the tree's entry point does.
+    const block = generateCompressedIndex('1.0.0');
+    expect(block).toContain(
+      '  docs cli           commands, API reference, integration authoring (one level at a time)',
+    );
+    expect(topicLine(block)).not.toContain('cli-integrations');
+  });
+
   it('lists the topics it is given, so an integration’s reach the agent', () => {
     const line = topicLine(
       generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),