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

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

@@ -20,10 +20,64 @@ import {
   renderAgentDocsBlock,
   inspectAgentDocs,
   isAstryxInitialized,
+  AgentDocsHomeError,
+  resolveAgentDocsRoot,
 } from './agent-docs.mjs';
 
 let tmpDir;
 
+/** The managed import of AGENTS.md the default writes to GEMINI.md. */
+const GEMINI_IMPORT = '<!-- ASTRYX:START -->\n@./AGENTS.md\n<!-- ASTRYX:END -->\n';
+/** The heading of a .claude/CLAUDE.md the default creates. */
+const CLAUDE_HEADING = '# CLAUDE\n\nProject-specific guidance for AI coding agents.\n\n';
+
+/** Every file the default layout can write. */
+const LAYOUT_FILES = ['AGENTS.md', 'CLAUDE.md', '.claude/CLAUDE.md', 'GEMINI.md'];
+
+/**
+ * How many full managed blocks the files hold, by the header every block
+ * starts with. An import of AGENTS.md carries no header.
+ * @param {string} dir
+ * @param {string[]} files
+ */
+function countBlocks(dir, files) {
+  return files
+    .filter(f => fs.existsSync(path.join(dir, f)))
+    .map(f => fs.readFileSync(path.join(dir, f), 'utf-8').split(/Astryx v\d/).length - 1)
+    .reduce((a, b) => a + b, 0);
+}
+
+/**
+ * Full blocks in the files each agent reads at the project root, as measured:
+ * Codex reads AGENTS.md; Copilot CLI reads AGENTS.md, CLAUDE.md and GEMINI.md
+ * and does not expand an import in GEMINI.md; Claude Code reads CLAUDE.md and
+ * .claude/CLAUDE.md, or AGENTS.md when neither exists; Gemini CLI reads
+ * GEMINI.md and expands its import of AGENTS.md.
+ * @param {string} dir
+ */
+function blocksSeen(dir) {
+  const claudeFiles = ['CLAUDE.md', '.claude/CLAUDE.md'].filter(f =>
+    fs.existsSync(path.join(dir, f)),
+  );
+  const gemini = fs.existsSync(path.join(dir, 'GEMINI.md'))
+    ? fs.readFileSync(path.join(dir, 'GEMINI.md'), 'utf-8')
+    : null;
+  return {
+    claude: countBlocks(dir, claudeFiles.length > 0 ? claudeFiles : ['AGENTS.md']),
+    codex: countBlocks(dir, ['AGENTS.md']),
+    gemini:
+      gemini == null
+        ? 0
+        : countBlocks(dir, ['GEMINI.md']) +
+          (/(^|\s)@(\.\/)?AGENTS\.md(\s|$)/.test(gemini) ? countBlocks(dir, ['AGENTS.md']) : 0),
+    copilot: countBlocks(dir, ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']),
+  };
+}
+/** Every agent reads one copy. */
+const ONCE_EACH = {claude: 1, codex: 1, gemini: 1, copilot: 1};
+/** Copilot CLI reads AGENTS.md and a root CLAUDE.md together: the accepted duplicate. */
+const COPILOT_TWICE = {claude: 1, codex: 1, gemini: 1, copilot: 2};
+
 beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-test-'));
 });
@@ -301,7 +355,8 @@ describe('renderAgentDocsBlock', () => {
         'utf-8',
       );
       expect(firstAgents).toContain(renderedBlock);
-      expect(firstClaude).toContain(renderedBlock);
+      expect(firstClaude).toBe(`# Claude\n\n${renderedBlock}\n`);
+      expect(fs.existsSync(path.join(projectDir, '.claude'))).toBe(false);
 
       installAgentDocs(projectDir, {renderedBlock});
       expect(fs.readFileSync(path.join(projectDir, 'AGENTS.md'), 'utf-8')).toBe(
@@ -655,24 +710,27 @@ describe('installAgentDocs', () => {
     );
   }
 
-  it('creates AGENTS.md when no agent docs exist (tool-agnostic default)', () => {
+  it('creates AGENTS.md, plus the GEMINI.md import, when no agent docs exist', () => {
     setupCorePackage(tmpDir);
 
     const written = installAgentDocs(tmpDir);
 
-    expect(written).toEqual(['AGENTS.md']);
+    expect(written).toEqual(['AGENTS.md', 'GEMINI.md']);
     expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
-    // Must NOT create the Claude-specific file by default.
+    // Claude Code reads AGENTS.md when the project has no CLAUDE.md, so no
+    // Claude file is created.
     expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'CLAUDE.md'))).toBe(false);
     const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
     expect(content).toContain('# AGENTS.md');
     expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(GEMINI_IMPORT);
   });
 
   it('defaults to AGENTS.md but writes .claude/CLAUDE.md only when --agent claude is explicit', () => {
     // Default (no agent): tool-agnostic AGENTS.md, never the Claude file.
     setupCorePackage(tmpDir);
-    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md']);
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'GEMINI.md']);
     expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
 
     // Explicit Claude: the Claude-specific file, in a fresh project.
@@ -686,46 +744,193 @@ describe('installAgentDocs', () => {
     }
   });
 
-  it('injects into CLAUDE.md at root when it exists', () => {
+  it('writes the block to AGENTS.md and to root CLAUDE.md when the project has only CLAUDE.md', () => {
+    // Codex reads only AGENTS.md, and Claude Code skips AGENTS.md beside a
+    // CLAUDE.md. The copy goes in the committed root CLAUDE.md; init creates
+    // no .claude/ folder.
     setupCorePackage(tmpDir);
     fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');
 
     const written = installAgentDocs(tmpDir);
 
-    expect(written).toEqual(['CLAUDE.md']);
-    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
-    const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
-    expect(claudeContent).toContain('<!-- ASTRYX:START -->');
-    expect(claudeContent).toContain('Project rules.');
+    expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8').startsWith(
+        '# Claude\n\nProject rules.\n\n<!-- ASTRYX:START -->',
+      ),
+    ).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, '.claude'))).toBe(false);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(GEMINI_IMPORT);
+    expect(blocksSeen(tmpDir)).toEqual(COPILOT_TWICE);
   });
 
-  it('injects into all existing agent doc files', () => {
+  it('keeps the block in root CLAUDE.md when AGENTS.md and CLAUDE.md both exist', () => {
     setupCorePackage(tmpDir);
     fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nAgent rules.\n');
     fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nClaude rules.\n');
 
     const written = installAgentDocs(tmpDir);
 
-    expect(written).toContain('AGENTS.md');
-    expect(written).toContain('CLAUDE.md');
+    expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
     const agentsContent = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
-    const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(agentsContent).toContain('Agent rules.');
     expect(agentsContent).toContain('<!-- ASTRYX:START -->');
-    expect(claudeContent).toContain('<!-- ASTRYX:START -->');
+    expect(fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')).toContain(
+      'Claude rules.',
+    );
+    expect(blocksSeen(tmpDir)).toEqual(COPILOT_TWICE);
+  });
+
+  it('refreshes a block an older run wrote into CLAUDE.md and adds one to AGENTS.md', () => {
+    setupCorePackage(tmpDir, '2.0.0');
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '# Claude\n\nRules.\n\n<!-- ASTRYX:START -->\nAstryx v1.0.0 · old\n<!-- ASTRYX:END -->\n\nMore rules.\n',
+    );
+
+    const written = installAgentDocs(tmpDir);
+
+    expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+    const claude = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(claude).toContain('Astryx v2.0.0');
+    expect(claude).not.toContain('Astryx v1.0.0');
+    expect(claude).toContain('More rules.');
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toContain(
+      'Astryx v2.0.0',
+    );
+    expect(blocksSeen(tmpDir)).toEqual(COPILOT_TWICE);
+  });
+
+  it('gives Claude Code one copy when CLAUDE.md and .claude/CLAUDE.md both exist', () => {
+    // The copy goes in root CLAUDE.md, which projects commit even when they
+    // ignore .claude/; a block an older run left in .claude/CLAUDE.md goes.
+    setupCorePackage(tmpDir, '2.0.0');
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n');
+    fs.mkdirSync(path.join(tmpDir, '.claude'));
+    fs.writeFileSync(
+      path.join(tmpDir, '.claude', 'CLAUDE.md'),
+      '# Local\n\n<!-- ASTRYX:START -->\nAstryx v1.0.0 · old\n<!-- ASTRYX:END -->\n',
+    );
+
+    const written = installAgentDocs(tmpDir);
+
+    expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', '.claude/CLAUDE.md', 'GEMINI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      '# Local\n',
+    );
+    expect(blocksSeen(tmpDir)).toEqual(COPILOT_TWICE);
+  });
+
+  it('writes the same bytes when run again', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n');
+    installAgentDocs(tmpDir);
+    const files = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+    const first = files.map(f => fs.readFileSync(path.join(tmpDir, f), 'utf-8'));
+
+    expect(installAgentDocs(tmpDir)).toEqual(files);
+    expect(files.map(f => fs.readFileSync(path.join(tmpDir, f), 'utf-8'))).toEqual(first);
+  });
+
+  it('adds no import when GEMINI.md already imports AGENTS.md inline', () => {
+    setupCorePackage(tmpDir);
+    const gemini = '# Gemini\n\nFollow @./AGENTS.md always.\n';
+    fs.writeFileSync(path.join(tmpDir, 'GEMINI.md'), gemini);
+
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(gemini);
+    expect(blocksSeen(tmpDir)).toEqual(ONCE_EACH);
+  });
+
+  it('removes its own import when GEMINI.md also imports AGENTS.md', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(
+      path.join(tmpDir, 'GEMINI.md'),
+      `# Gemini\n\nSee @AGENTS.md first.\n\n${GEMINI_IMPORT}`,
+    );
+
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(
+      '# Gemini\n\nSee @AGENTS.md first.\n',
+    );
+  });
+
+  it('adds the import when GEMINI.md mentions AGENTS.md only in code or not as an import', () => {
+    setupCorePackage(tmpDir);
+    // Gemini CLI follows no `@` inside backticks, none glued to a word, and
+    // none whose path does not name AGENTS.md exactly.
+    const gemini = 'Write `@./AGENTS.md` to import.\nmail@AGENTS.md\nRead @./AGENTS.md.\n';
+    fs.writeFileSync(path.join(tmpDir, 'GEMINI.md'), gemini);
+
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(
+      `${gemini}\n${GEMINI_IMPORT}`,
+    );
+  });
+
+  it.each([
+    ['a list', '{"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}}'],
+    ['a name', '{"context": {"fileName": "AGENTS.md"}}'],
+    ['comments', '{\n  // Gemini reads AGENTS.md\n  "context": {/* both */ "fileName": ["AGENTS.md", "GEMINI.md"]}\n}\n'],
+    ['another file', '{"context": {"fileName": "GEMINI.md"}}'],
+  ])('writes the GEMINI.md import whatever the project Gemini settings read (%s)', (_label, settings) => {
+    // Gemini loads project settings only when it starts at the project root;
+    // started in a subfolder, the import is its only copy.
+    setupCorePackage(tmpDir);
+    fs.mkdirSync(path.join(tmpDir, '.gemini'));
+    fs.writeFileSync(path.join(tmpDir, '.gemini', 'settings.json'), settings);
+
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(GEMINI_IMPORT);
+  });
+
+  it('keeps its GEMINI.md import when the project Gemini settings read AGENTS.md', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'GEMINI.md'), `# Gemini\n\n${GEMINI_IMPORT}`);
+    fs.mkdirSync(path.join(tmpDir, '.gemini'));
+    fs.writeFileSync(
+      path.join(tmpDir, '.gemini', 'settings.json'),
+      '{"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}}',
+    );
+
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(
+      `# Gemini\n\n${GEMINI_IMPORT}`,
+    );
+  });
+
+  it('leaves a file that is AGENTS.md under another name alone', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');
+    fs.symlinkSync('AGENTS.md', path.join(tmpDir, 'CLAUDE.md'));
+
+    // Claude Code reads the block through CLAUDE.md, so no copy is added.
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+    expect(countBlocks(tmpDir, ['AGENTS.md'])).toBe(1);
+  });
+
+  it('keeps an existing GEMINI.md and adds the import to it', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'GEMINI.md'), '# Gemini\n\nUse tabs.\n');
+
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(
+      `# Gemini\n\nUse tabs.\n\n${GEMINI_IMPORT}`,
+    );
   });
 
   it('preserves import wrappers while initializing standalone files', () => {
     setupCorePackage(tmpDir);
     fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');
-    fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
-    const wrapperPath = path.join(tmpDir, '.claude', 'CLAUDE.md');
-    const wrapper = '@../AGENTS.md\n';
+    const wrapperPath = path.join(tmpDir, '.hermes.md');
+    const wrapper = '@AGENTS.md\n';
     fs.writeFileSync(wrapperPath, wrapper);
     fs.writeFileSync(path.join(tmpDir, '.cursorrules'), 'Cursor rules.\n');
 
     const written = installAgentDocs(tmpDir);
 
-    expect(written).toEqual(['AGENTS.md', '.cursorrules']);
+    expect(written).toEqual(['AGENTS.md', 'GEMINI.md', '.cursorrules']);
     expect(fs.readFileSync(wrapperPath, 'utf-8')).toBe(wrapper);
     expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toContain(
       '<!-- ASTRYX:START -->',
@@ -735,7 +940,7 @@ describe('installAgentDocs', () => {
     );
   });
 
-  it('keeps cyclic imports standalone when another file exists', () => {
+  it('treats cyclic imports as standalone files', () => {
     setupCorePackage(tmpDir);
     fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '@CLAUDE.md\n');
     fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '@AGENTS.md\n');
@@ -743,22 +948,30 @@ describe('installAgentDocs', () => {
 
     const written = installAgentDocs(tmpDir);
 
-    expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', '.cursorrules']);
-    for (const rel of written) {
-      expect(fs.readFileSync(path.join(tmpDir, rel), 'utf-8')).toContain(
-        '<!-- ASTRYX:START -->',
-      );
+    expect(written).toEqual(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.cursorrules']);
+    for (const rel of ['AGENTS.md', 'CLAUDE.md', '.cursorrules']) {
+      expect(countBlocks(tmpDir, [rel])).toBe(1);
     }
   });
 
+  it('keeps the per-file layout when a wrapper imports a file other than AGENTS.md', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n');
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '@CLAUDE.md\n');
+
+    expect(installAgentDocs(tmpDir)).toEqual(['CLAUDE.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')).toBe('@CLAUDE.md\n');
+    expect(countBlocks(tmpDir, ['CLAUDE.md'])).toBe(1);
+    expect(fs.existsSync(path.join(tmpDir, 'GEMINI.md'))).toBe(false);
+  });
+
   it('removes a managed block previously expanded into an import wrapper', () => {
     setupCorePackage(tmpDir);
     installAgentDocs(tmpDir, {agent: 'codex'});
-    fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
-    const wrapperPath = path.join(tmpDir, '.claude', 'CLAUDE.md');
-    const wrapper = '@../AGENTS.md\n';
+    const wrapperPath = path.join(tmpDir, '.hermes.md');
+    const wrapper = '@AGENTS.md\n';
     fs.writeFileSync(wrapperPath, wrapper);
-    installAgentDocs(tmpDir, {agent: 'claude'});
+    installAgentDocs(tmpDir, {agent: 'hermes'});
     expect(fs.readFileSync(wrapperPath, 'utf-8')).toContain(
       '<!-- ASTRYX:START -->',
     );
@@ -766,7 +979,7 @@ describe('installAgentDocs', () => {
     const written = installAgentDocs(tmpDir, {onlyReplace: true});
 
     expect(written).toContain('AGENTS.md');
-    expect(written).toContain('.claude/CLAUDE.md');
+    expect(written).toContain('.hermes.md');
     expect(fs.readFileSync(wrapperPath, 'utf-8')).toBe(wrapper);
   });
 
@@ -782,17 +995,123 @@ describe('installAgentDocs', () => {
     expect(() => installAgentDocs(tmpDir)).toThrow(/malformed|no matching/i);
   });
 
-  it('updates existing .claude/CLAUDE.md', () => {
+  it('adds the block to an existing .claude/CLAUDE.md and to AGENTS.md', () => {
     setupCorePackage(tmpDir);
     fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
     fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '# Project\n\nExisting content.\n');
 
     const written = installAgentDocs(tmpDir);
 
-    expect(written).toEqual(['.claude/CLAUDE.md']);
+    expect(written).toEqual(['AGENTS.md', '.claude/CLAUDE.md', 'GEMINI.md']);
     const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
-    expect(content).toContain('Existing content.');
-    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(content.startsWith('# Project\n\nExisting content.\n\n<!-- ASTRYX:START -->')).toBe(
+      true,
+    );
+    expect(blocksSeen(tmpDir)).toEqual(ONCE_EACH);
+  });
+
+  it('gives a root CLAUDE.md that imports AGENTS.md a copy too', () => {
+    // Claude Code does not follow an import of a file above the folder it
+    // starts in, so a session in a subfolder reads only the copy.
+    setupCorePackage(tmpDir);
+    const claude = '# Claude\n\n@AGENTS.md\n';
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), claude);
+
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content.startsWith(`${claude}\n<!-- ASTRYX:START -->`)).toBe(true);
+    expect(countBlocks(tmpDir, ['AGENTS.md', 'CLAUDE.md'])).toBe(2);
+    expect(fs.existsSync(path.join(tmpDir, '.claude'))).toBe(false);
+
+    // Running again keeps the copy where it is.
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')).toBe(content);
+  });
+
+  it('keeps the copy in root CLAUDE.md, not .claude/CLAUDE.md, when root CLAUDE.md imports AGENTS.md', () => {
+    // Root CLAUDE.md is committed even where .claude/ is ignored, so a fresh
+    // clone still gives a session in a subfolder its copy.
+    setupCorePackage(tmpDir, '2.0.0');
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\n@AGENTS.md\n');
+    fs.mkdirSync(path.join(tmpDir, '.claude'));
+    fs.writeFileSync(
+      path.join(tmpDir, '.claude', 'CLAUDE.md'),
+      '# Local\n\n<!-- ASTRYX:START -->\nAstryx v1.0.0 · old\n<!-- ASTRYX:END -->\n',
+    );
+
+    expect(installAgentDocs(tmpDir)).toEqual([
+      'AGENTS.md',
+      'CLAUDE.md',
+      '.claude/CLAUDE.md',
+      'GEMINI.md',
+    ]);
+    expect(countBlocks(tmpDir, ['CLAUDE.md'])).toBe(1);
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      '# Local\n',
+    );
+  });
+
+  it('gives a .claude/CLAUDE.md that imports AGENTS.md a copy when there is no root CLAUDE.md', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');
+    fs.mkdirSync(path.join(tmpDir, '.claude'));
+    fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '@../AGENTS.md\n');
+
+    expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md', '.claude/CLAUDE.md', 'GEMINI.md']);
+    const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
+    expect(content.startsWith('@../AGENTS.md\n\n<!-- ASTRYX:START -->')).toBe(true);
+  });
+
+  it('onlyReplace: refreshes the copy in a Claude file that imports AGENTS.md instead of removing it', () => {
+    setupCorePackage(tmpDir, '1.0.0');
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\n@AGENTS.md\n');
+    installAgentDocs(tmpDir);
+    setupCorePackage(tmpDir, '2.0.0');
+
+    expect(installAgentDocs(tmpDir, {onlyReplace: true})).toEqual(['AGENTS.md', 'CLAUDE.md']);
+    const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    expect(content).toContain('@AGENTS.md');
+    expect(content).toContain('Astryx v2.0.0');
+    expect(content).not.toContain('Astryx v1.0.0');
+  });
+
+  it('--agent all after the default keeps the GEMINI.md import and one Claude copy', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n');
+    fs.mkdirSync(path.join(tmpDir, '.claude'));
+    fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), '# Local\n');
+    installAgentDocs(tmpDir);
+
+    expect(installAgentDocs(tmpDir, {agent: 'all'})).toEqual(['AGENTS.md', 'CLAUDE.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(GEMINI_IMPORT);
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      '# Local\n',
+    );
+    expect(blocksSeen(tmpDir)).toEqual(COPILOT_TWICE);
+  });
+
+  it('--agent claude writes CLAUDE.md and removes a block from .claude/CLAUDE.md', () => {
+    setupCorePackage(tmpDir);
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n');
+    fs.mkdirSync(path.join(tmpDir, '.claude'));
+    fs.writeFileSync(
+      path.join(tmpDir, '.claude', 'CLAUDE.md'),
+      '# Local\n\n<!-- ASTRYX:START -->\nAstryx v1.0.0 · old\n<!-- ASTRYX:END -->\n',
+    );
+    installAgentDocs(tmpDir);
+
+    expect(installAgentDocs(tmpDir, {agent: 'claude'})).toEqual(['CLAUDE.md']);
+    expect(installAgentDocs(tmpDir, {agent: 'all'})).toEqual(['AGENTS.md', 'CLAUDE.md']);
+    fs.writeFileSync(
+      path.join(tmpDir, '.claude', 'CLAUDE.md'),
+      '# Local\n\n<!-- ASTRYX:START -->\nAstryx v1.0.0 · old\n<!-- ASTRYX:END -->\n',
+    );
+    expect(installAgentDocs(tmpDir, {agent: 'claude'})).toEqual(['CLAUDE.md', '.claude/CLAUDE.md']);
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      '# Local\n',
+    );
+    expect(blocksSeen(tmpDir).claude).toBe(1);
   });
 
   it('respects --agent claude preset: finds existing CLAUDE.md', () => {
@@ -879,6 +1198,39 @@ describe('installAgentDocs', () => {
     expect(content).toContain('Other rules.');
   });
 
+  it('onlyReplace: refreshes both copies of the block and leaves the GEMINI.md import alone', () => {
+    setupCorePackage(tmpDir, '1.0.0');
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n');
+    installAgentDocs(tmpDir);
+    setupCorePackage(tmpDir, '2.0.0');
+
+    expect(installAgentDocs(tmpDir, {onlyReplace: true})).toEqual([
+      'AGENTS.md',
+      'CLAUDE.md',
+    ]);
+    for (const rel of ['AGENTS.md', 'CLAUDE.md']) {
+      const content = fs.readFileSync(path.join(tmpDir, rel), 'utf-8');
+      expect(content).toContain('Astryx v2.0.0');
+      expect(content).not.toContain('Astryx v1.0.0');
+    }
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(GEMINI_IMPORT);
+    expect(blocksSeen(tmpDir)).toEqual(COPILOT_TWICE);
+  });
+
+  it('onlyReplace: refreshes a block beside an import of a missing AGENTS.md', () => {
+    setupCorePackage(tmpDir, '2.0.0');
+    fs.writeFileSync(
+      path.join(tmpDir, 'CLAUDE.md'),
+      '@AGENTS.md\n\n<!-- ASTRYX:START -->\nAstryx v1.0.0\n<!-- ASTRYX:END -->\n',
+    );
+
+    expect(installAgentDocs(tmpDir, {onlyReplace: true})).toEqual(['CLAUDE.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')).toContain(
+      'Astryx v2.0.0',
+    );
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+  });
+
   it('onlyReplace: does not create the default AGENTS.md when nothing exists', () => {
     setupCorePackage(tmpDir);
 
@@ -1084,6 +1436,25 @@ describe('inspectAgentDocs', () => {
     expect(res.staleFiles).toEqual(['CLAUDE.md']);
   });
 
+  it('checks both copies of the block and does not count the GEMINI.md import', () => {
+    const core = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(core, {recursive: true});
+    fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({version: '3.0.0'}));
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n');
+    installAgentDocs(tmpDir);
+
+    const current = inspectAgentDocs(tmpDir, '3.0.0');
+    expect(current.status).toBe('current');
+    expect(current.files.map(f => f.path)).toEqual(['AGENTS.md', 'CLAUDE.md']);
+    expect(inspectAgentDocs(tmpDir, '4.0.0').staleFiles).toEqual(['AGENTS.md', 'CLAUDE.md']);
+
+    // Without the blocks, the import alone reads as not set up.
+    fs.rmSync(path.join(tmpDir, 'AGENTS.md'));
+    fs.rmSync(path.join(tmpDir, 'CLAUDE.md'));
+    expect(inspectAgentDocs(tmpDir, '3.0.0').status).toBe('missing');
+    expect(isAstryxInitialized(tmpDir)).toBe(false);
+  });
+
   it('defaults the installed version to the core package when omitted', () => {
     const coreDir = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
     fs.mkdirSync(coreDir, {recursive: true});
@@ -1179,3 +1550,275 @@ describe('isAstryxInitialized — resilient to malformed markers (postinstall ho
     expect(isAstryxInitialized(path.join(tmpDir, 'does-not-exist'))).toBe(false);
   });
 });
+
+describe('removeAgentDocs after the default layout', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('deletes the files the default created and keeps the project files', () => {
+    const core = path.join(tmpDir, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(core, {recursive: true});
+    fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({version: '1.0.0'}));
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n');
+    installAgentDocs(tmpDir);
+
+    expect(removeAgentDocs(tmpDir)).toEqual(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
+    expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'GEMINI.md'))).toBe(false);
+    expect(fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')).toBe('# Claude\n');
+  });
+
+  it('keeps a GEMINI.md that has the project\'s own content', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'GEMINI.md'),
+      `# Gemini\n\nUse tabs.\n\n${GEMINI_IMPORT}`,
+    );
+
+    expect(removeAgentDocs(tmpDir)).toEqual(['GEMINI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'GEMINI.md'), 'utf-8')).toBe(
+      '# Gemini\n\nUse tabs.\n',
+    );
+  });
+});
+
+describe('agent docs never go into the home folder', () => {
+  const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+  const personal = '# My notes\n\nAlways use tabs.\n';
+
+  beforeEach(() => {
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), personal);
+  });
+  afterEach(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+
+  it.each([
+    ['the default', {}],
+    ['a preset', {agent: 'claude'}],
+    ['an explicit path', {paths: ['AGENTS.md']}],
+    ['a refresh', {onlyReplace: true}],
+  ])('refuses %s and writes nothing', (_label, options) => {
+    expect(() => installAgentDocs(tmpDir, options)).toThrow(AgentDocsHomeError);
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      personal,
+    );
+    expect(fs.readdirSync(tmpDir).sort()).toEqual(['.claude']);
+  });
+
+  it('writes an explicit path into a plain folder of the home folder, as 0.7.x did', () => {
+    expect(installAgentDocs(tmpDir, {paths: ['notes/AI.md']})).toEqual(['notes/AI.md']);
+    expect(fs.readFileSync(path.join(tmpDir, 'notes', 'AI.md'), 'utf-8')).toContain(
+      '<!-- ASTRYX:START -->',
+    );
+  });
+
+  it.each([
+    ['a file in the home folder', ['AI.md']],
+    ['a file at the top of a settings folder', ['.claude/CLAUDE.md']],
+    ['one of several paths', ['notes/AI.md', 'AI.md']],
+  ])('refuses an explicit path to %s, and writes nothing', (_label, paths) => {
+    expect(() => installAgentDocs(tmpDir, {paths})).toThrow(AgentDocsHomeError);
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      personal,
+    );
+    expect(fs.readdirSync(tmpDir).sort()).toEqual(['.claude']);
+  });
+
+  it('init with an explicit path from the home folder writes it, and refuses one in the home folder', async () => {
+    const {init} = await import('../../api/init/init.mjs');
+    const written = await init(
+      {features: ['agents'], agentDocsPath: 'notes/AI.md'},
+      {cwd: tmpDir},
+    );
+    expect(written.data.docsWritten).toEqual(['notes/AI.md']);
+    expect(written.data.docsError ?? null).toBeNull();
+    const refused = await init(
+      {features: ['agents'], agentDocsPath: 'AI.md'},
+      {cwd: tmpDir},
+    );
+    expect(refused.data.docsError).toMatchObject({kind: 'install-failed'});
+    expect(fs.existsSync(path.join(tmpDir, 'AI.md'))).toBe(false);
+  });
+
+  it('refuses through a symlink to the home folder', () => {
+    const link = `${tmpDir}-link`;
+    fs.symlinkSync(tmpDir, link);
+    try {
+      expect(() => installAgentDocs(link)).toThrow(AgentDocsHomeError);
+    } finally {
+      fs.rmSync(link);
+    }
+  });
+
+  it('still removes a block an older run wrote there', () => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    fs.writeFileSync(
+      path.join(tmpDir, '.claude', 'CLAUDE.md'),
+      `${personal}\n<!-- ASTRYX:START -->\nAstryx v1.0.0\n<!-- ASTRYX:END -->\n`,
+    );
+
+    expect(removeAgentDocs(tmpDir)).toEqual(['.claude/CLAUDE.md']);
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      personal,
+    );
+  });
+
+  it.each(['.gemini', '.claude', '.codex', path.join('.gemini', 'extensions', 'x')])(
+    'refuses the settings folder ~/%s',
+    folder => {
+      const dir = path.join(tmpDir, folder);
+      fs.mkdirSync(dir, {recursive: true});
+      const before = fs.readdirSync(dir);
+      expect(() => installAgentDocs(dir)).toThrow(AgentDocsHomeError);
+      expect(fs.readdirSync(dir)).toEqual(before);
+      expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+        personal,
+      );
+    },
+  );
+
+  it('writes in a project folder inside the home folder', () => {
+    const project = path.join(tmpDir, 'app');
+    fs.mkdirSync(project);
+    expect(installAgentDocs(project)).toEqual(['AGENTS.md', 'GEMINI.md']);
+  });
+
+  /**
+   * A git project that declares Astryx, at `rel` under the home folder, with
+   * Core installed at `version`.
+   * @param {string} rel
+   * @param {string} version
+   */
+  function writeProject(rel, version) {
+    const project = path.join(tmpDir, rel);
+    fs.mkdirSync(path.join(project, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(project, '.git'), 'gitdir: /elsewhere/.git/worktrees/web\n');
+    fs.writeFileSync(
+      path.join(project, 'package.json'),
+      JSON.stringify({name: 'web', dependencies: {'@astryxdesign/core': version}}),
+    );
+    const core = path.join(project, 'node_modules', '@astryxdesign', 'core');
+    fs.mkdirSync(core, {recursive: true});
+    fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({version}));
+    return project;
+  }
+
+  it.each([
+    ['a Codex worktree', path.join('.codex', 'worktrees', 'a1b2c3', 'web')],
+    ['a Cursor worktree', path.join('.cursor', 'worktrees', 'web', 'x9y8')],
+    ['a project with its package.json one level in', path.join('.config', 'web')],
+  ])('writes and refreshes the docs of a project inside a settings folder (%s)', (_label, rel) => {
+    const project = writeProject(rel, '1.0.0');
+
+    expect(resolveAgentDocsRoot(path.join(project, 'src'))).toBe(project);
+    expect(installAgentDocs(project)).toEqual(['AGENTS.md', 'GEMINI.md']);
+
+    // upgrade refreshes the block in place.
+    writeProject(rel, '2.0.0');
+    expect(installAgentDocs(project, {onlyReplace: true})).toEqual(['AGENTS.md']);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toContain(
+      'Astryx v2.0.0',
+    );
+
+    // Nothing reaches the settings folder or the home folder.
+    const settings = path.join(tmpDir, rel.split(path.sep)[0]);
+    expect(fs.readdirSync(settings)).toEqual([rel.split(path.sep)[1]]);
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      personal,
+    );
+  });
+
+  it('refuses the top of a settings folder even with a package.json, and the folders in it outside a project', () => {
+    // A package.json in ~/.claude (for hook scripts, say) would otherwise put the
+    // block in ~/.claude/CLAUDE.md, which Claude Code reads in every project.
+    fs.writeFileSync(path.join(tmpDir, '.claude', 'package.json'), '{"name":"hooks"}\n');
+    fs.mkdirSync(path.join(tmpDir, '.claude', 'hooks'));
+
+    expect(() => installAgentDocs(path.join(tmpDir, '.claude'))).toThrow(AgentDocsHomeError);
+    expect(() => installAgentDocs(path.join(tmpDir, '.claude', 'hooks'))).toThrow(
+      AgentDocsHomeError,
+    );
+    expect(resolveAgentDocsRoot(path.join(tmpDir, '.claude', 'hooks'))).toBe(
+      path.join(tmpDir, '.claude'),
+    );
+    expect(fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8')).toBe(
+      personal,
+    );
+
+    // A worktree folder whose project has no package.json is not a project.
+    const bare = path.join(tmpDir, '.codex', 'worktrees', 'a1b2c3', 'notes');
+    fs.mkdirSync(bare, {recursive: true});
+    expect(() => installAgentDocs(bare)).toThrow(AgentDocsHomeError);
+    expect(fs.readdirSync(bare)).toEqual([]);
+  });
+});
+
+describe('resolveAgentDocsRoot', () => {
+  /** @param {string} dir @param {object} pkg */
+  const writePkg = (dir, pkg) => {
+    fs.mkdirSync(dir, {recursive: true});
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(pkg));
+  };
+  const astryx = {devDependencies: {'@astryxdesign/cli': '0.7.0'}};
+
+  it('finds the nearest folder whose package.json declares Astryx', () => {
+    writePkg(tmpDir, astryx);
+    const sub = path.join(tmpDir, 'src', 'app');
+    fs.mkdirSync(sub, {recursive: true});
+    expect(resolveAgentDocsRoot(sub)).toBe(tmpDir);
+    expect(resolveAgentDocsRoot(tmpDir)).toBe(tmpDir);
+
+    // A nested package that does not declare Astryx is passed over.
+    const functions = path.join(tmpDir, 'functions');
+    writePkg(functions, {name: 'functions'});
+    fs.mkdirSync(path.join(functions, 'src'));
+    expect(resolveAgentDocsRoot(path.join(functions, 'src'))).toBe(tmpDir);
+
+    // A nested package that declares Astryx is its own project.
+    const web = path.join(tmpDir, 'apps', 'web');
+    writePkg(web, {dependencies: {'@astryxdesign/core': '0.7.0'}});
+    expect(resolveAgentDocsRoot(web)).toBe(web);
+  });
+
+  it('falls back to the nearest package.json when none declares Astryx', () => {
+    writePkg(tmpDir, {name: 'app'});
+    const pkg = path.join(tmpDir, 'packages', 'web');
+    writePkg(pkg, {name: 'web'});
+    fs.mkdirSync(path.join(pkg, 'src'));
+    expect(resolveAgentDocsRoot(path.join(pkg, 'src'))).toBe(pkg);
+  });
+
+  it('stops at a repository root, and finds no project without a package.json', () => {
+    writePkg(tmpDir, astryx);
+    const repo = path.join(tmpDir, 'repo');
+    fs.mkdirSync(path.join(repo, '.git'), {recursive: true});
+    const sub = path.join(repo, 'docs');
+    fs.mkdirSync(sub);
+    expect(resolveAgentDocsRoot(sub)).toBeNull();
+  });
+
+  it('never returns the home folder', () => {
+    const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    try {
+      writePkg(tmpDir, astryx);
+      const scratch = path.join(tmpDir, 'scratch');
+      fs.mkdirSync(scratch);
+      expect(resolveAgentDocsRoot(scratch)).toBeNull();
+      expect(resolveAgentDocsRoot(tmpDir)).toBeNull();
+    } finally {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+});