@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/api/docs/_adapter.mjs

@@ -1146,6 +1146,14 @@ function packageCatalog(integration, discovered) {
  * @returns {Promise<Array<{severity: 'warning', message: string}>>}
  */
 export async function packageComponentLinkProblems(integration, discovered) {
+  // A package with no provider id (its manifest's, else its name) links
+  // nothing, as on the read path: its text reads as written, so there is
+  // nothing to report.
+  try {
+    normalizeProviderId(integration.providerId ?? integration.name);
+  } catch {
+    return [];
+  }
   const catalog = packageCatalog(integration, discovered);
   return (await componentLinkProblems(catalog, integration.name)).map(
     message => ({severity: /** @type {const} */ ('warning'), message}),
@@ -1176,11 +1184,15 @@ async function componentLinkProblems(catalog, owner) {
       // The components check reports a doc that does not load.
       continue;
     }
-    const linked = await linkComponentDoc(
-      catalog,
-      componentLinkProvider(record.package, record.providerId),
-      doc,
-    );
+    let provider;
+    try {
+      provider = componentLinkProvider(record.package, record.providerId);
+    } catch {
+      // An owner that is not a provider id links nothing (as on the read
+      // path); its text reads as written.
+      continue;
+    }
+    const linked = await linkComponentDoc(catalog, provider, doc);
     const name = typeof doc?.name === 'string' ? doc.name : record.name;
     for (const problem of linked.problems) {
       problems.push(

package/api/docs/docs.test.mjs

@@ -123,7 +123,13 @@ describe('docs() dispatcher routing', () => {
       kind: 'namespace',
       package: '@astryxdesign/cli',
       breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],
-      content: [],
+      // Its one block points to the host entry's guide.
+      content: [
+        {
+          type: 'prose',
+          text: expect.stringContaining('`astryx docs cli/host-entry`'),
+        },
+      ],
     });
     expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([
       'cli/api/functions',

package/api/doctor/doctor.mjs

@@ -28,7 +28,15 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/node-version.mjs';
-import {AGENT_DOC_PATHS} from '../../foundation/agent-docs/agent-doc-state.mjs';
+import {
+  AGENT_DOC_PATHS,
+  holdsAstryxBlock,
+} from '../../foundation/agent-docs/agent-doc-state.mjs';
+import {
+  agentDocsTargetDir,
+  assertAgentDocsTarget,
+  resolveAgentDocsRoot,
+} from '../../foundation/agent-docs/agent-docs.mjs';
 import {CLI_ROOT, findProjectCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
 import {explainPackageManager, formatCliCommand, getCliInvocation, guessCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {chooseDeclaredCliCommand, declaredCliCommandsOf} from '../../foundation/env/cli-command.mjs';
@@ -610,6 +618,21 @@ export function checkConfiguredIntegrations(ctx) {
   };
 }
 
+/**
+ * Why init writes no agent docs for `cwd`, or null when it does: the folder
+ * it would write to is the home folder or the top of a settings folder in it.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+function agentDocsRefusal(cwd) {
+  try {
+    assertAgentDocsTarget(agentDocsTargetDir(cwd));
+    return null;
+  } catch (err) {
+    return err instanceof Error && err.name === 'AgentDocsHomeError' ? err.message : null;
+  }
+}
+
 /**
  * Check 7 — agent docs exist and contain the Astryx section markers.
  * @param {DoctorContext} ctx
@@ -617,8 +640,15 @@ export function checkConfiguredIntegrations(ctx) {
  */
 export function checkAgentDocs(ctx) {
   // Every file init can write (one shared list), looked for in the working
-  // directory and in the project root: run from src/, the docs sit at the root.
-  const dirs = [...new Set([ctx.cwd, projectRootOf(ctx)])];
+  // directory, the project root, and the folder init writes them to: run from
+  // src/ or a nested package, the docs sit at the root.
+  const dirs = [
+    ...new Set(
+      [ctx.cwd, projectRootOf(ctx), resolveAgentDocsRoot(ctx.cwd) ?? ctx.cwd].map(dir =>
+        path.resolve(dir),
+      ),
+    ),
+  ];
   const present = dirs.flatMap(dir =>
     AGENT_DOC_PATHS.map(rel => path.join(dir, rel)).filter(abs =>
       fs.existsSync(abs),
@@ -626,6 +656,15 @@ export function checkAgentDocs(ctx) {
   );
   /** @param {string} abs */
   const shown = abs => path.relative(ctx.cwd, abs) || path.basename(abs);
+  // In the home folder, or at the top of a settings folder in it, init
+  // writes no agent docs (INV31), so the fix is moving the project or a hand
+  // edit, never init.
+  const refusal = agentDocsRefusal(ctx.cwd);
+  /** @param {string} initFix */
+  const fixFor = initFix =>
+    refusal
+      ? `${refusal} Move the project into a folder of its own, or edit the Astryx block in its agent file by hand.`
+      : initFix;
 
   if (present.length === 0) {
     return {
@@ -633,29 +672,64 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'info',
       message: `No agent docs found: looked for ${AGENT_DOC_PATHS.join(', ')} in ${dirs.map(dir => path.relative(ctx.cwd, dir) || '.').join(' and ')}.`,
-      fix: `Generate agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      fix: fixFor(
+        `Generate agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      ),
     };
   }
 
-  const withMarkers = present.filter(abs => {
+  /** @param {string} abs */
+  const read = abs => {
     try {
-      const content = fs.readFileSync(abs, 'utf-8');
-      return (
-        (content.includes('<!-- ASTRYX:START -->') || content.includes('<!-- XDS:START -->')) &&
-        (content.includes('<!-- ASTRYX:END -->') || content.includes('<!-- XDS:END -->'))
-      );
+      return fs.readFileSync(abs, 'utf-8');
     } catch {
-      return false;
+      return '';
     }
+  };
+  const withMarkers = present.filter(abs => {
+    const content = read(abs);
+    return (
+      (content.includes('<!-- ASTRYX:START -->') || content.includes('<!-- XDS:START -->')) &&
+      (content.includes('<!-- ASTRYX:END -->') || content.includes('<!-- XDS:END -->')) &&
+      holdsAstryxBlock(content)
+    );
   });
 
+  // A managed block that only imports another file (init's GEMINI.md import
+  // of AGENTS.md) is broken when that file holds no block: the agents that
+  // read either file get no Astryx docs.
+  const dangling = present.flatMap(abs => {
+    const match = /<!-- ASTRYX:START -->\s*@(\S+)\s*<!-- ASTRYX:END -->/.exec(read(abs));
+    if (match == null) return [];
+    const target = path.resolve(path.dirname(abs), match[1]);
+    return holdsAstryxBlock(read(target)) ? [] : [{abs, target}];
+  });
+  if (dangling.length > 0) {
+    return {
+      id: 'agent-docs',
+      label: 'AI agent docs',
+      status: 'fail',
+      message: dangling
+        .map(
+          ({abs, target}) =>
+            `${shown(abs)} imports ${shown(target)}, which holds no Astryx block, so agents that read them get no Astryx docs.`,
+        )
+        .join(' '),
+      fix: fixFor(
+        `Write the block again with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      ),
+    };
+  }
+
   if (withMarkers.length === 0) {
     return {
       id: 'agent-docs',
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.map(shown).join(', ')}) but no Astryx section markers found.`,
-      fix: `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      fix: fixFor(
+        `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      ),
     };
   }
 

package/api/doctor/doctor.test.mjs

@@ -1317,8 +1317,12 @@ describe('a configured integration that cannot load fails the gate', () => {
     'astryx.config.mjs': "export default { integrations: ['@acme/widgets'] };\n",
   };
 
-  /** Run doctor on a project under the working directory. */
-  async function report(files) {
+  /**
+   * Run doctor on a project under the working directory, in its folder `at`.
+   * @param {Record<string, string>} files
+   * @param {string} [at]
+   */
+  async function report(files, at = '.') {
     const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-gate-'));
     tmpDirs.push(dir);
     for (const [rel, content] of Object.entries(files)) {
@@ -1326,7 +1330,7 @@ describe('a configured integration that cannot load fails the gate', () => {
       fs.mkdirSync(path.dirname(abs), {recursive: true});
       fs.writeFileSync(abs, content);
     }
-    const {checks, summary} = (await doctor({cwd: dir})).data;
+    const {checks, summary} = (await doctor({cwd: path.join(dir, at)})).data;
     return {by: Object.fromEntries(checks.map(c => [c.id, c])), summary};
   }
 
@@ -1354,6 +1358,27 @@ describe('a configured integration that cannot load fails the gate', () => {
     SLOW,
   );
 
+  it(
+    'passes in a workspace member whose configured integration is hoisted to the root',
+    async () => {
+      const {by} = await report(
+        {
+          'package.json': JSON.stringify({name: 'root', private: true, workspaces: ['apps/*']}),
+          ...CORE_STUB,
+          ...widgets(),
+          'apps/web/package.json': '{"name":"web"}',
+          'apps/web/astryx.config.mjs': "export default { integrations: ['@acme/widgets'] };\n",
+        },
+        'apps/web',
+      );
+      expect(by['configured-integrations'].status).toBe('pass');
+      expect(by['configured-integrations'].message).toBe(
+        '1 integration named in astryx.config loaded: @acme/widgets.',
+      );
+    },
+    SLOW,
+  );
+
   it(
     'counts the package being authored when its own config names it',
     async () => {

package/api/init/init.doc.mjs

@@ -17,11 +17,22 @@ export const doc = {
     'Non-interactive project setup: install agent docs and point at the theme + build workflows.',
   description:
     'Sets a project up with NO prompts, so it behaves identically for humans, ' +
-    'agents, CI, and piped I/O. By default it installs the AGENTS.md/CLAUDE.md ' +
-    'agent-docs cheat sheet, including guidance from configured integrations, and ' +
+    'agents, CI, and piped I/O. By default it writes the agent-docs cheat sheet, ' +
+    'including guidance from configured integrations, at the project root (the nearest ' +
+    'package.json that declares an @astryxdesign package, else the nearest package.json, ' +
+    'searching no higher than the repository root): to AGENTS.md, ' +
+    "to the project's Claude Code file (CLAUDE.md, else .claude/CLAUDE.md; when CLAUDE.md " +
+    'exists, a block in .claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a ' +
+    '.claude/CLAUDE.md the project commits keeps a copy), and as a ' +
+    'one-line import of AGENTS.md in GEMINI.md unless GEMINI.md already imports it. ' +
+    'In the home folder, or in a settings folder in it outside a project, it writes none: every ' +
+    'folder of the home folder whose name starts with a dot is a settings folder, and such a folder itself never ' +
+    'counts as a project, even with a package.json; a folder below it with a package.json does. ' +
+    'The managed block is Astryx-owned: it is written, refreshed, and removed whatever ignore rules ' +
+    'or generated markers say, and the text around it is never changed. It then ' +
     "prints getting-started guidance; `features` / `all` print only the chosen features' " +
     'guidance instead (the theme feature also writes the annotated theme template). ' +
-    'With `removeAgents` it removes the managed agent-docs block instead of installing. ' +
+    'With `removeAgents` it removes the managed agent-docs block, at the project root and in `ctx.cwd`, instead of installing. ' +
     'Outside a project it writes the same files but prints no getting-started steps and no step that adds a theme to an app, since those set up a project the folder does not have. ' +
         "With `user` it sets up the computer instead of the folder: it writes the computer-level agent text, one skill file at `~/.agents/skills/astryx/SKILL.md`, linked into the skill folders of agents that read only their own (`~/.claude/skills` always; Kiro, Windsurf, Letta, Xcode's coding assistant, and `~/.config/agents/skills` when that folder exists), with a managed copy for Continue, whose scanner skips links,, telling agents anywhere on the computer that Astryx is there and when to use it; with `user` and `removeAgents` it removes the file and the links it made and records that the text is turned off. " +
     'The CLI installed for the computer refreshes the file in the background after each upgrade; package install scripts, project setup, and upgrade never write it.' +
@@ -46,7 +57,7 @@ export const doc = {
       name: 'options.removeAgents',
       type: 'boolean',
       description:
-        'Remove the managed agent-docs block instead of installing. With `user`, remove the computer-level agent text instead.',
+        'Remove the managed agent-docs block, at the project root and in `ctx.cwd`, instead of installing. With `user`, remove the computer-level agent text instead.',
     },
     {
       name: 'options.user',
@@ -62,7 +73,10 @@ export const doc = {
       name: 'options.agent',
       type: 'string',
       description:
-        'Agent preset: claude, cursor, codex, hermes, muse, all. Used only when the agents feature runs. Refused with `user`.',
+        'Agent preset: claude, cursor, codex, hermes, muse, all. `all` writes every existing agent doc except GEMINI.md, ' +
+        'which keeps its one-line import of AGENTS.md. With claude and all, when CLAUDE.md gets the block, a block in ' +
+        '.claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a .claude/CLAUDE.md the ' +
+        'project commits gets a copy too. Used only when the agents feature runs. Refused with `user`.',
     },
     {
       name: 'options.agentDocsPath',
@@ -122,7 +136,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file resolves outside cwd through a symlink',
+      when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file in cwd, or at the project root when run there, resolves outside that folder through a symlink (run below the root, a project-root file is left as it is with a note)',
     },
   ],
   examples: [

package/api/init/init.test.mjs

@@ -10,6 +10,7 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import {init, getNextSteps} from './init.mjs';
 import {logger} from '../logger.mjs';
@@ -21,7 +22,8 @@ const MARKER_START = '<!-- ASTRYX:START -->';
 let tmpDir;
 
 beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-api-'));
+  // Outside any package: init writes agent docs at the nearest package.json.
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-init-api-'));
 });
 
 afterEach(() => {
@@ -30,6 +32,18 @@ afterEach(() => {
 
 /** @param {string} rel */
 const read = rel => fs.readFileSync(path.join(tmpDir, rel), 'utf8');
+
+/**
+ * Make tmpDir a project that declares Astryx: a folder that declares nothing
+ * is outside a project, where init prints no getting-started steps (spec
+ * AST-081 FR3).
+ */
+function asProject() {
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '*'}}),
+  );
+}
 /** @param {string} rel */
 const exists = rel => fs.existsSync(path.join(tmpDir, rel));
 
@@ -58,6 +72,7 @@ function writeIntegration() {
 
 describe('init() — receipts + side effects', () => {
   it('default mode installs AGENTS.md and returns an init.run receipt', async () => {
+    asProject();
     const res = await init({}, {cwd: tmpDir});
     expect(res.type).toBe('init.run');
     if (res.type !== 'init.run') return;
@@ -217,6 +232,7 @@ describe('init() — logger', () => {
   });
 
   it('emits the install line + full next-steps through the shared logger', async () => {
+    asProject();
     /** @type {string[]} */
     const lines = [];
     const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
@@ -243,7 +259,7 @@ describe('init() — ASCII output', () => {
     const lines = [];
     const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
     const errSpy = vi.spyOn(console, 'error').mockImplementation((...a) => lines.push(a.join(' ')));
-    const empty = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-remove-'));
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-init-remove-'));
     logger.setSilent(false);
     try {
       await init({}, {cwd: tmpDir});

package/api/init/init.type.d.mts

@@ -11,11 +11,11 @@ export type InitRunData = {
      */
     features: string[];
     /**
-     * Agent-doc files written (empty if agents weren't run or install failed).
+     * Agent-doc files written, relative to the directory init ran in (empty if agents weren't run or install failed). Without --agent-docs-path they sit at the project root: the nearest folder at or above it whose package.json declares an Astryx package, else the nearest with any package.json, within its repository and never the home folder; with none, the directory init ran in.
      */
     docsWritten: string[];
     /**
-     * Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
+     * Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit. `install-failed` carries a message when init wrote no agent docs (the home folder, or a settings folder in it outside a project) or skipped a file that resolves outside the project; docsWritten then lists what was written.
      */
     docsError: {
         kind: "path-safety" | "install-failed";
@@ -113,7 +113,7 @@ export type InitOptions = {
      */
     all?: boolean | undefined;
     /**
-     * Remove the managed agent-docs block instead of installing; with `user`, remove the computer-level agent text.
+     * Remove the managed agent-docs block, at the project root and in the folder init runs in, instead of installing; with `user`, remove the computer-level agent text.
      */
     removeAgents?: boolean | undefined;
     /**

package/api/init/init.type.mjs

@@ -10,8 +10,8 @@
  * @typedef {object} InitRunData
  * @property {'default' | 'features'} mode `default` (no flags) or `features` (--features/--all).
  * @property {string[]} features Features that were run, in order.
- * @property {string[]} docsWritten Agent-doc files written (empty if agents weren't run or install failed).
- * @property {{kind: 'path-safety' | 'install-failed', message?: string} | null} docsError Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
+ * @property {string[]} docsWritten Agent-doc files written, relative to the directory init ran in (empty if agents weren't run or install failed). Without --agent-docs-path they sit at the project root: the nearest folder at or above it whose package.json declares an Astryx package, else the nearest with any package.json, within its repository and never the home folder; with none, the directory init ran in.
+ * @property {{kind: 'path-safety' | 'install-failed', message?: string} | null} docsError Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit. `install-failed` carries a message when init wrote no agent docs (the home folder, or a settings folder in it outside a project) or skipped a file that resolves outside the project; docsWritten then lists what was written.
  * @property {boolean} theme Whether the theme feature ran.
  * @property {'created' | 'skipped' | 'failed' | null} themeTemplate Outcome of writing the annotated theme template (`skipped` = a file was already there).
  * @property {string | null} themeTemplatePath Relative output path when `themeTemplate === 'created'`.
@@ -70,7 +70,7 @@
  * @typedef {object} InitOptions
  * @property {string} [features] Comma-separated features to install (agents, theme, template).
  * @property {boolean} [all] Install all features.
- * @property {boolean} [removeAgents] Remove the managed agent-docs block instead of installing; with `user`, remove the computer-level agent text.
+ * @property {boolean} [removeAgents] Remove the managed agent-docs block, at the project root and in the folder init runs in, instead of installing; with `user`, remove the computer-level agent text.
  * @property {boolean} [user] Write the computer-level agent text (`~/.agents/skills/astryx/SKILL.md`, linked into `~/.claude/skills` and the skill folders of other installed tools, with a copy for Continue) instead of setting up the folder.
  * @property {string} [agent] Agent preset: claude, cursor, codex, hermes, muse, all. Refused with `user`.
  * @property {string | string[]} [agentDocsPath] Explicit agent-docs file path(s).

package/api/init/remove/remove.mjs

@@ -4,15 +4,16 @@
  * @file init.remove leaf — the `--remove-agents` path behind `astryx init`.
  *
  * `remove(ctx)` deletes the managed agent-docs block from every agent-doc file
- * and returns an `init.remove` receipt. The removal engine lives in
- * lib/agent-docs; this leaf only wires the cwd.
+ * at the project root, where init writes it, and in the working folder, and
+ * returns an `init.remove` receipt. The removal engine lives in
+ * foundation/agent-docs; this leaf only wires the cwd.
  *
  * Note: removeAgentDocs() still logs its own per-file lines via humanLog
  * (shared lib behavior) — so a programmatic remove is not perfectly silent yet.
  * Threading a logger through agent-docs is a separate cleanup.
  */
 
-import {removeAgentDocs} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {removeProjectAgentDocs} from '../../../foundation/agent-docs/agent-docs.mjs';
 import {logger} from '../../logger.mjs';
 
 /**
@@ -23,7 +24,19 @@ import {logger} from '../../logger.mjs';
  * @returns {Promise<import('../init.type.mjs').InitRemoveResponse>}
  */
 export async function remove({cwd = process.cwd()} = {}) {
-  const removedFrom = removeAgentDocs(cwd);
+  /** @type {string[]} */
+  const skipped = [];
+  const removedFrom = removeProjectAgentDocs(cwd, {
+    onSkipped: (rel, reason) => skipped.push(`${rel} (${reason})`),
+  });
+  if (skipped.length > 0) {
+    // Below the project root, as install does there (0.7.x touched only the
+    // working folder): a root agent file outside the project is left alone.
+    logger.warn(
+      `Note: Left as ${skipped.length === 1 ? 'it is' : 'they are'}: ${skipped.join('; ')}. ` +
+        'To remove the Astryx block there, delete it by hand.',
+    );
+  }
   const removed = removedFrom.length > 0;
   logger.log(
     removed

package/api/init/remove/remove.test.mjs

@@ -1,12 +1,124 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
-import * as fs from 'node:fs'; import * as path from 'node:path';
+import * as fs from 'node:fs'; import * as path from 'node:path'; import * as os from 'node:os';
 import {init} from '../init.mjs'; import {remove} from './remove.mjs'; import {logger} from '../../logger.mjs';
 let dir;
-beforeEach(() => { dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-rm-')); fs.writeFileSync(path.join(dir,'package.json'),JSON.stringify({name:'c',version:'1.0.0'})); });
+beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-')); fs.writeFileSync(path.join(dir,'package.json'),JSON.stringify({name:'c',version:'1.0.0'})); });
 afterEach(() => { fs.rmSync(dir,{recursive:true,force:true}); logger.setSilent(true); });
 describe('init.remove says whether anything was removed', () => {
   it('false on clean', async () => { const r=await remove({cwd:dir}); expect(r.type).toBe('init.remove'); expect(r.data.removed).toBe(false); });
   it('true then false', async () => { await init({features:['agents']},{cwd:dir}); expect(fs.readFileSync(path.join(dir,'AGENTS.md'),'utf8')).toContain('<!-- ASTRYX:START -->'); const a=await remove({cwd:dir}); expect(a.data.removed).toBe(true); const b=await remove({cwd:dir}); expect(b.data.removed).toBe(false); });
   it('human line', async () => { const l=[]; const s=vi.spyOn(console,'log').mockImplementation((...a)=>l.push(a.join(' '))); logger.setSilent(false); try{await remove({cwd:dir});}finally{logger.setSilent(true);s.mockRestore();} expect(l.join('\n')).toContain('Nothing to remove'); });
 });
+
+describe('init.remove acts where init writes, the project root, and in the folder it runs in', () => {
+  /** @type {string} */
+  let project;
+  beforeEach(() => {
+    project = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-root-'));
+    fs.writeFileSync(
+      path.join(project, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '1.0.0'}}),
+    );
+    fs.mkdirSync(path.join(project, 'src', 'app'), {recursive: true});
+  });
+  afterEach(() => { fs.rmSync(project, {recursive: true, force: true}); });
+  const block = '<!-- ASTRYX:START -->\nAstryx v0.7.0 · old\n<!-- ASTRYX:END -->\n';
+
+  it('removes from a subfolder what init wrote at the project root', async () => {
+    const sub = path.join(project, 'src', 'app');
+    const written = await init({features: ['agents']}, {cwd: sub});
+    expect(written.data.docsWritten).toEqual(['../../AGENTS.md', '../../GEMINI.md']);
+
+    const r = await remove({cwd: sub});
+    expect(r).toEqual({type: 'init.remove', data: {removed: true}});
+    // Both files held only what init wrote, so they are deleted.
+    expect(fs.existsSync(path.join(project, 'AGENTS.md'))).toBe(false);
+    expect(fs.existsSync(path.join(project, 'GEMINI.md'))).toBe(false);
+    expect((await remove({cwd: sub})).data.removed).toBe(false);
+  });
+
+  it('removes a block an earlier version left in the subfolder, and keeps the files\' own text', async () => {
+    const sub = path.join(project, 'src', 'app');
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\nRoot rules.\n\n${block}`);
+    fs.writeFileSync(path.join(sub, 'AGENTS.md'), `# App\n\nApp rules.\n\n${block}`);
+
+    expect((await remove({cwd: sub})).data.removed).toBe(true);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf8').trimEnd()).toBe('# Agents\n\nRoot rules.');
+    expect(fs.readFileSync(path.join(sub, 'AGENTS.md'), 'utf8').trimEnd()).toBe('# App\n\nApp rules.');
+  });
+
+  it('run at the project root, leaves a subfolder alone', async () => {
+    const sub = path.join(project, 'src', 'app');
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${block}`);
+    fs.writeFileSync(path.join(sub, 'AGENTS.md'), `# App\n\n${block}`);
+
+    expect((await remove({cwd: project})).data.removed).toBe(true);
+    expect(fs.readFileSync(path.join(sub, 'AGENTS.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+  });
+
+  it('below the root, leaves a root agent file linked outside the project with a note, and removes the rest (0.7.x exited 0)', async () => {
+    // A workspace member whose CLAUDE.md links to the monorepo's.
+    const monorepo = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-mono-'));
+    try {
+      const web = path.join(monorepo, 'apps', 'web');
+      const sub = path.join(web, 'src');
+      fs.mkdirSync(sub, {recursive: true});
+      fs.writeFileSync(
+        path.join(web, 'package.json'),
+        JSON.stringify({name: 'web', dependencies: {'@astryxdesign/core': '1.0.0'}}),
+      );
+      fs.writeFileSync(path.join(monorepo, 'CLAUDE.md'), `# Shared\n\n${block}`);
+      fs.symlinkSync('../../CLAUDE.md', path.join(web, 'CLAUDE.md'));
+      fs.writeFileSync(path.join(web, 'AGENTS.md'), `# Web\n\n${block}`);
+      fs.writeFileSync(path.join(sub, 'AGENTS.md'), `# Src\n\n${block}`);
+      const warned = [];
+      const warn = vi.spyOn(console, 'error').mockImplementation((...a) => warned.push(a.join(' ')));
+      logger.setSilent(false);
+      let r;
+      try {
+        r = await remove({cwd: sub});
+      } finally {
+        logger.setSilent(true);
+        warn.mockRestore();
+      }
+      expect(r).toEqual({type: 'init.remove', data: {removed: true}});
+      expect(fs.readFileSync(path.join(web, 'AGENTS.md'), 'utf8').trimEnd()).toBe('# Web');
+      expect(fs.readFileSync(path.join(sub, 'AGENTS.md'), 'utf8').trimEnd()).toBe('# Src');
+      // The file outside the project keeps its block.
+      expect(fs.readFileSync(path.join(monorepo, 'CLAUDE.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+      expect(warned.join('\n')).toMatch(/Note: Left as it is: \.\.\/CLAUDE\.md \(/u);
+    } finally {
+      fs.rmSync(monorepo, {recursive: true, force: true});
+    }
+  });
+
+  it('at the root, a root agent file linked outside the project still refuses the run', async () => {
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-outside-'));
+    try {
+      fs.writeFileSync(path.join(outside, 'CLAUDE.md'), `# Shared\n\n${block}`);
+      fs.symlinkSync(path.join(outside, 'CLAUDE.md'), path.join(project, 'CLAUDE.md'));
+      fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${block}`);
+      await expect(remove({cwd: project})).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+    } finally {
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
+
+  it('a link in the subfolder that escapes it refuses the run before anything is written', async () => {
+    const sub = path.join(project, 'src', 'app');
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-rm-outside-'));
+    try {
+      fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${block}`);
+      fs.writeFileSync(path.join(outside, 'CLAUDE.md'), `# Shared\n\n${block}`);
+      fs.symlinkSync(path.join(outside, 'CLAUDE.md'), path.join(sub, 'CLAUDE.md'));
+
+      await expect(remove({cwd: sub})).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+      expect(fs.readFileSync(path.join(outside, 'CLAUDE.md'), 'utf8')).toContain('<!-- ASTRYX:START -->');
+    } finally {
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
+});