@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

package/clients/cli/commands/component.test.mjs

@@ -12,7 +12,7 @@ import {
   findComponentSource,
   levenshteinDistance,
   findClosestComponents,
-} from './component/index.mjs';
+} from './component.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 
 const REPO_ROOT = path.resolve(import.meta.dirname, '../../../../..');
@@ -528,7 +528,7 @@ describe('findExternalComponentDoc', () => {
 describe('searchComponents', () => {
   it('finds Collapsible when searching "accordion"', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'accordion',
@@ -542,7 +542,7 @@ describe('searchComponents', () => {
 
   it('finds Dialog when searching "modal"', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'modal',
@@ -556,7 +556,7 @@ describe('searchComponents', () => {
 
   it('returns multiple matches for ambiguous terms like "select"', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'select',
@@ -571,7 +571,7 @@ describe('searchComponents', () => {
 
   it('finds exact name matches with score 100', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'Button',
@@ -584,7 +584,7 @@ describe('searchComponents', () => {
 
   it('returns empty array for complete gibberish', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'zzzzzzzzzzz',

package/clients/cli/commands/docs.doc.mjs

@@ -58,10 +58,10 @@ export const doc = {
     {label: 'Every CLI doc, one line each', cli: 'astryx docs cli --depth all'},
     {
       label: 'The integration guides as one read',
-      cli: 'astryx docs cli/integrations --depth all --detail full',
+      cli: 'astryx docs authoring --depth all --detail full',
     },
     {label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
-    {label: 'A whole guide', cli: 'astryx docs cli/integrations/quick-start --full'},
+    {label: 'A whole guide', cli: 'astryx docs authoring/quick-start --full'},
   ],
   outsideProject: 'same',
   exitCodes: [

package/clients/cli/commands/docs.mjs

@@ -535,7 +535,7 @@ function emitNode(node, detail, run) {
       text(
         [
           // A child's route is its parent's route and its name, except a flat
-          // topic in the Unorganized level, which keeps its own name.
+          // topic in a topic level, which keeps its own name.
           node.slots.every(slot =>
             slot.children.every(child => child.route.startsWith(`${node.route}/`)),
           )

package/clients/cli/commands/docs.test.mjs

@@ -227,7 +227,7 @@ describe('the docs tree, one level at a time', () => {
   it('wraps namespace summaries without discarding searchable words', async () => {
     const {status, stdout} = await runCli([
       'docs',
-      'cli/integrations/building-blocks/templates',
+      'authoring/building-blocks/templates',
     ]);
     expect(status).toBe(0);
     expect(stdout).toMatch(/^start-a-template +Help others build apps faster/m);
@@ -274,8 +274,8 @@ describe('the docs tree, one level at a time', () => {
   }, SLOW);
 
   it('reads the integration guides by their routes, and not by the old name', async () => {
-    // cli/integrations is a namespace: one level, its guides by slot.
-    const level = await runCli(['docs', 'cli/integrations']);
+    // authoring is a namespace: one level, its guides by slot.
+    const level = await runCli(['docs', 'authoring']);
     expect(level.status).toBe(0);
     expect(level.stdout).toMatch(
       /^quick-start +Create a new integration package/m,
@@ -283,42 +283,42 @@ describe('the docs tree, one level at a time', () => {
     expect(level.stdout).toMatch(/^building-blocks +/m);
     const guide = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       '--index',
     ]);
     expect(guide.status).toBe(0);
     expect(guide.stdout).toMatch(
-      /Read one section: .*docs cli\/integrations\/building-blocks\/codemods <section>/,
+      /Read one section: .*docs authoring\/building-blocks\/codemods <section>/,
     );
     // A bare read is one level too: the sections, and how to read it all.
     const bare = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
     ]);
     expect(bare.status).toBe(0);
     expect(bare.stdout).toBe(guide.stdout);
     expect(bare.stdout).toMatch(
-      /Read everything: +.*docs cli\/integrations\/building-blocks\/codemods --full$/m,
+      /Read everything: +.*docs authoring\/building-blocks\/codemods --full$/m,
     );
     const one = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       'which-codemods-run',
     ]);
     expect(one.status).toBe(0);
     expect(one.stdout).toMatch(/^## Choose when a codemod runs$/m);
     expect(one.stdout).toMatch(
-      /^Up: .*docs cli\/integrations\/building-blocks\/codemods --index$/m,
+      /^Up: .*docs authoring\/building-blocks\/codemods --index$/m,
     );
     expect(one.stdout).toMatch(
-      /^Previous: .*docs cli\/integrations\/building-blocks\/codemods write-the-transform$/m,
+      /^Previous: .*docs authoring\/building-blocks\/codemods write-the-transform$/m,
     );
     expect(one.stdout).toMatch(
-      /^Next: .*docs cli\/integrations\/building-blocks\/codemods run-codemods-in-an-app$/m,
+      /^Next: .*docs authoring\/building-blocks\/codemods run-codemods-in-an-app$/m,
     );
     const full = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       '--full',
     ]);
     expect(full.status).toBe(0);
@@ -343,11 +343,11 @@ describe('the docs tree, one level at a time', () => {
       type: 'docs.detail.section',
       data: {id: 'side-panels', title: 'Side panels'},
     });
-    const missing = await runCli(['docs', 'cli', 'zzzz-nope', '--json']);
+    const missing = await runCli(['docs', 'authoring', 'zzzz-nope', '--json']);
     expect(missing.status).toBe(1);
     const error = JSON.parse(missing.stdout);
     expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
-    expect(error.suggestions.map(s => s.name)).toContain('cli/integrations/quick-start');
+    expect(error.suggestions.map(s => s.name)).toContain('authoring/quick-start');
   }, SLOW);
 });
 

package/clients/cli/commands/doctor.mjs

@@ -179,6 +179,34 @@ function docTypesBlocks(report, failed) {
   return blocks;
 }
 
+/**
+ * The component doc names that could not be judged against their sources.
+ * @param {import('../../../api/integration/validate-integration.type.mjs').DocNamesReport | undefined} report
+ */
+function docNamesBlocks(report) {
+  if (!report || report.unchecked.length === 0) return [];
+  return [
+    text(
+      `[info] Component names not checked: ${report.unchecked.length} doc(s) whose source exports this check cannot read:`,
+    ),
+    records(report.unchecked, {fields: ['file', 'name', 'reason']}),
+  ];
+}
+
+/**
+ * The block component names this check could not judge.
+ * @param {import('../../../api/integration/validate-integration.type.mjs').BlockComponentsReport | undefined} report
+ */
+function blockComponentsBlocks(report) {
+  if (!report || report.unchecked.length === 0) return [];
+  return [
+    text(
+      `[info] Block component names not checked: ${report.unchecked.length} name(s) this check could not judge:`,
+    ),
+    records(report.unchecked, {fields: ['file', 'name', 'reason']}),
+  ];
+}
+
 /**
  * @param {import('../../../api/integration/validate-integration.type.mjs').ValidateIntegrationResponse['data']} data
  */
@@ -204,6 +232,8 @@ function printIntegrationValidation(data) {
         `${warnings} warning${warnings === 1 ? '' : 's'}`,
     ),
     ...docTypesBlocks(data.docTypes, errors > 0),
+    ...docNamesBlocks(data.docNames),
+    ...blockComponentsBlocks(data.blockComponents),
   );
 }
 

package/clients/cli/commands/doctor.test.mjs

@@ -191,6 +191,31 @@ describe('doctor — individual checks', () => {
     expect(res.fix).toContain('`npx astryx init --features agents`');
   });
 
+  it('agent-docs: at the top of a home settings folder, the fix moves the project or edits by hand, never init', () => {
+    const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    try {
+      const project = path.join(tmpDir, '.dotfiles');
+      fs.mkdirSync(project);
+      fs.writeFileSync(path.join(project, 'package.json'), '{"name":"dots"}');
+      for (const content of [null, '# Agents\nno markers here\n']) {
+        if (content != null) fs.writeFileSync(path.join(project, 'AGENTS.md'), content);
+        const res = checkAgentDocs({cwd: project});
+        expect(res.fix).toContain('Agent docs are not written into the home folder');
+        expect(res.fix).toContain(
+          'Move the project into a folder of its own, or edit the Astryx block in its agent file by hand.',
+        );
+        expect(res.fix).not.toContain('init --features agents');
+      }
+    } finally {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
   it('agent-docs: WARN when docs exist without XDS markers', () => {
     fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# AGENTS\nno markers here');
     const res = checkAgentDocs({cwd: tmpDir});
@@ -221,6 +246,25 @@ describe('doctor — individual checks', () => {
     );
   });
 
+  it('agent-docs: PASS from a nested package, reading the root that declares Astryx', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'AGENTS.md'),
+      '<!-- ASTRYX:START -->\nstuff\n<!-- ASTRYX:END -->\n',
+    );
+    const functions = path.join(tmpDir, 'functions');
+    fs.mkdirSync(path.join(functions, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(functions, 'package.json'), '{"name":"functions"}');
+
+    expect(checkAgentDocs({cwd: path.join(functions, 'src')})).toMatchObject({
+      status: 'pass',
+      message: `Astryx agent docs section present in ${path.join('..', '..', 'AGENTS.md')}.`,
+    });
+  });
+
   it('agent-docs: reads every file init can write, Hermes included', () => {
     fs.writeFileSync(
       path.join(tmpDir, 'HERMES.md'),
@@ -232,6 +276,27 @@ describe('doctor — individual checks', () => {
     });
   });
 
+  it('agent-docs: FAIL when GEMINI.md imports an AGENTS.md that holds no block', () => {
+    const geminiImport = '<!-- ASTRYX:START -->\n@./AGENTS.md\n<!-- ASTRYX:END -->\n';
+    fs.writeFileSync(path.join(tmpDir, 'GEMINI.md'), geminiImport);
+    expect(checkAgentDocs({cwd: tmpDir})).toMatchObject({
+      status: 'fail',
+      message: expect.stringMatching(/^GEMINI\.md imports AGENTS\.md, which holds no Astryx block/),
+      fix: expect.stringMatching(/init --features agents/),
+    });
+
+    // A copy elsewhere does not mend it: Codex and Gemini CLI still get none.
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '<!-- ASTRYX:START -->\nstuff\n<!-- ASTRYX:END -->\n');
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');
+    expect(checkAgentDocs({cwd: tmpDir}).status).toBe('fail');
+
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '<!-- ASTRYX:START -->\nstuff\n<!-- ASTRYX:END -->\n');
+    expect(checkAgentDocs({cwd: tmpDir})).toMatchObject({
+      status: 'pass',
+      message: 'Astryx agent docs section present in AGENTS.md, CLAUDE.md.',
+    });
+  });
+
   it('agent-docs: INFO names what it looked for and where', () => {
     const res = checkAgentDocs({cwd: tmpDir});
     expect(res.status).toBe('info');

package/clients/cli/commands/{hook/index.mjs → hook.mjs}

@@ -11,17 +11,17 @@ import {
   formatHookCompact,
   formatHookBrief,
   formatHookParams,
-} from '../../lib/hook-format.mjs';
-import {getCliInvocation} from '../../../../foundation/env/package-manager.mjs';
-import {jsonOut} from '../../../../foundation/response/json.mjs';
-import {emit, section, text, list, records, code, record} from '../../formatters/index.mjs';
-import {cliError} from '../../lib/cli-error.mjs';
-import {defineCommand} from '../../lib/define-command.mjs';
-import {resultSet} from '../../../../foundation/debug/index.mjs';
-import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {hook as hookApi} from '../../../../api/hook/hook.mjs';
-import {doc as hookCommand} from '../hook.doc.mjs';
-import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
+} from '../lib/hook-format.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, records, code, record} from '../formatters/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {hook as hookApi} from '../../../api/hook/hook.mjs';
+import {doc as hookCommand} from './hook.doc.mjs';
+import {doc as hookFn} from '../../../api/hook/hook.doc.mjs';
 
 /**
  * The api layer's hook() widens its return to `{type: string, data: unknown}`,
@@ -29,9 +29,9 @@ import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
  * the colocated api/hook/hook.type.mjs to get narrowing + typed data.
  *
  * @typedef {(
- *   | import('../../../../api/hook/hook.type.mjs').HookListResponse
- *   | import('../../../../api/hook/hook.type.mjs').HookDetailResponse
- *   | import('../../../../api/hook/hook.type.mjs').HookDetailParamsResponse
+ *   | import('../../../api/hook/hook.type.mjs').HookListResponse
+ *   | import('../../../api/hook/hook.type.mjs').HookDetailResponse
+ *   | import('../../../api/hook/hook.type.mjs').HookDetailParamsResponse
  * )} HookResult
  */
 
@@ -40,7 +40,7 @@ import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
  * count is every hook across the groups — names or docs, depending on detail.
  *
  * @param {HookResult} result
- * @returns {import('../../../../foundation/debug/command-result.mjs').CommandResult}
+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
  */
 function summarize(result) {
   if (result.type === 'hook.list') {
@@ -90,7 +90,7 @@ export function registerHook(program) {
           lang, zh,
         }));
       } catch (e) {
-        const err = /** @type {import('../../../../api/error.mjs').AstryxError} */ (e);
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
         return cliError(err.message, {suggestions: err.suggestions, code: err.code});
       }
 
@@ -112,7 +112,7 @@ export function registerHook(program) {
             // The whole view is one markdown document: a `## <category>` heading
             // over each category's concatenated hook docs.
             const groups = result.data.components;
-            /** @type {import('../../formatters/index.mjs').Block[]} */
+            /** @type {import('../formatters/index.mjs').Block[]} */
             const out = [];
             for (const [cat, items] of Object.entries(groups)) {
               const body = items
@@ -130,7 +130,7 @@ export function registerHook(program) {
             // --detail compact — one record (name + description) per hook,
             // grouped by category.
             const groups = result.data.components;
-            /** @type {import('../../formatters/index.mjs').Block[]} */
+            /** @type {import('../formatters/index.mjs').Block[]} */
             const out = [];
             for (const [cat, items] of Object.entries(groups)) {
               out.push(section(cat), records(items, {fields: ['name', 'description']}));
@@ -147,7 +147,7 @@ export function registerHook(program) {
             const [cat, hookNames] = Object.entries(groups)[0];
             emit(section(`${cat}:`), list(hookNames));
           } else {
-            /** @type {import('../../formatters/index.mjs').Block[]} */
+            /** @type {import('../formatters/index.mjs').Block[]} */
             const out = [];
             for (const [category, hookNames] of Object.entries(groups)) {
               out.push(section(category), list(hookNames));
@@ -197,12 +197,12 @@ export function registerHook(program) {
 }
 
 // Re-export lib functions for external consumers
-export {discoverHooks, findHookDoc, getAllHookNames} from '../../../../foundation/discovery/hook-discovery.mjs';
-export {loadDocs} from '../../../../foundation/discovery/component-loader.mjs';
+export {discoverHooks, findHookDoc, getAllHookNames} from '../../../foundation/discovery/hook-discovery.mjs';
+export {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 export {
   formatHookFull,
   formatHookCompact,
   formatHookBrief,
   formatHookBriefAll,
   formatHookParams,
-} from '../../lib/hook-format.mjs';
+} from '../lib/hook-format.mjs';

package/clients/cli/commands/import-hint-correctness.test.mjs

@@ -21,7 +21,7 @@ import {
   resolveImportPath,
   discoverComponents,
   findComponentSource,
-} from './component/index.mjs';
+} from './component.mjs';
 import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 

package/clients/cli/commands/init.behavior.test.mjs

@@ -70,10 +70,12 @@ describe('astryx init — default (no flags)', () => {
 });
 
 describe('astryx init --features', () => {
-  it('--features agents writes AGENTS.md only', async () => {
+  it('--features agents writes AGENTS.md and the GEMINI.md import of it', async () => {
     const {status} = await runCli(['init', '--features', 'agents'], {cwd: tmpDir});
     expect(status).toBe(0);
     expect(exists('AGENTS.md')).toBe(true);
+    expect(read('GEMINI.md')).toBe(`${MARKER_START}\n@./AGENTS.md\n<!-- ASTRYX:END -->\n`);
+    expect(exists('theme.template.ts')).toBe(false);
   });
 
   it('--features theme writes the annotated theme template', async () => {
@@ -126,7 +128,234 @@ describe('astryx init --agent <preset>', () => {
   });
 });
 
+describe('astryx init from a subfolder', () => {
+  /** @param {string} dir */
+  const astryxProject = dir =>
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+
+  it('writes the agent docs at the project root and reports them from where it ran', async () => {
+    astryxProject(tmpDir);
+    const sub = path.join(tmpDir, 'src', 'app');
+    fs.mkdirSync(sub, {recursive: true});
+
+    const json = await runCli(['init', '--json'], {cwd: sub});
+    expect(json.status).toBe(0);
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual([
+      '../../AGENTS.md',
+      '../../GEMINI.md',
+    ]);
+    expect(read('AGENTS.md')).toContain(MARKER_START);
+    expect(fs.readdirSync(sub)).toEqual([]);
+  });
+
+  it('keeps --agent-docs-path relative to where it ran', async () => {
+    astryxProject(tmpDir);
+    const sub = path.join(tmpDir, 'docs');
+    fs.mkdirSync(sub);
+
+    const json = await runCli(['init', '--agent-docs-path', 'AI.md', '--json'], {cwd: sub});
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual(['AI.md']);
+    expect(fs.readFileSync(path.join(sub, 'AI.md'), 'utf8')).toContain(MARKER_START);
+    expect(exists('AGENTS.md')).toBe(false);
+  });
+});
+
+describe('astryx init in 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('writes no agent docs, says why, and keeps the soft-failure exit code', async () => {
+    const json = await runCli(['init', '--json'], {cwd: tmpDir});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual([]);
+    expect(env.data.docsError).toEqual({
+      kind: 'install-failed',
+      message: expect.stringMatching(/not written into the home folder/),
+    });
+
+    const text = await runCli(['init'], {cwd: tmpDir});
+    expect(text.status).toBe(0);
+    expect(text.stderr).toMatch(/not written into the home folder/);
+    expect(text.stderr).not.toMatch(/Error:/);
+
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+    expect(fs.readdirSync(tmpDir)).toEqual(['.claude']);
+  });
+
+  it('does not let a package.json in the home folder pull the docs there', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const scratch = path.join(tmpDir, 'scratch');
+    fs.mkdirSync(scratch);
+
+    const json = await runCli(['init', '--json'], {cwd: scratch});
+    expect(json.status).toBe(0);
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.existsSync(path.join(scratch, 'AGENTS.md'))).toBe(true);
+    expect(exists('AGENTS.md')).toBe(false);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+
+  it('--remove-agents in a folder in home never reaches the home folder', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, '.claude', 'CLAUDE.md'),
+      `${personal}\n<!-- ASTRYX:START -->\nAstryx v0.7.0\n<!-- ASTRYX:END -->\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const scratch = path.join(tmpDir, 'scratch');
+    fs.mkdirSync(scratch);
+
+    const json = await runCli(['init', '--remove-agents', '--json'], {cwd: scratch});
+    expect(JSON.parse(json.stdout).data.removed).toBe(false);
+    expect(read('.claude/CLAUDE.md')).toContain('<!-- ASTRYX:START -->');
+
+    // Run in the home folder itself, it still removes the block there.
+    const home = await runCli(['init', '--remove-agents', '--json'], {cwd: tmpDir});
+    expect(JSON.parse(home.stdout).data.removed).toBe(true);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+
+  it.each(['.gemini', '.claude'])('refuses the settings folder ~/%s', async folder => {
+    const dir = path.join(tmpDir, folder);
+    fs.mkdirSync(dir, {recursive: true});
+    const before = fs.readdirSync(dir);
+
+    const json = await runCli(['init', '--json'], {cwd: dir});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual([]);
+    expect(env.data.docsError.message).toMatch(/settings folder in it outside a project/);
+    expect(fs.readdirSync(dir)).toEqual(before);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+});
+
+describe('astryx init in an agent worktree inside a home settings folder', () => {
+  const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+
+  beforeEach(() => {
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+  });
+  afterEach(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+
+  it.each([
+    ['Codex', path.join('.codex', 'worktrees', 'a1b2c3', 'web')],
+    ['Cursor', path.join('.cursor', 'worktrees', 'web', 'x9y8')],
+  ])('writes at the project root of a %s worktree', async (_tool, rel) => {
+    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': '0.7.0'}}),
+    );
+
+    const json = await runCli(['init', '--json'], {cwd: path.join(project, 'src')});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual(['../AGENTS.md', '../GEMINI.md']);
+    expect(env.data.docsError).toBeNull();
+
+    const explicit = await runCli(['init', '--agent-docs-path', 'AI.md', '--json'], {
+      cwd: path.join(project, 'src'),
+    });
+    expect(JSON.parse(explicit.stdout).data.docsWritten).toEqual(['AI.md']);
+
+    // Nothing reaches the settings folder itself.
+    const settings = path.join(tmpDir, rel.split(path.sep)[0]);
+    expect(fs.readdirSync(settings)).toEqual(['worktrees']);
+  });
+});
+
+describe('astryx init and the project root', () => {
+  it('writes where it runs when no folder above has a package.json, as before', async () => {
+    const notes = path.join(tmpDir, 'notes');
+    fs.mkdirSync(notes);
+
+    const json = await runCli(['init', '--json'], {cwd: notes});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(env.data.docsError).toBeNull();
+    expect(fs.readdirSync(notes).sort()).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.readdirSync(tmpDir)).toEqual(['notes']);
+  });
+
+  it('writes at the project root that declares Astryx, past a nested package that does not', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const functions = path.join(tmpDir, 'functions');
+    fs.mkdirSync(path.join(functions, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(functions, 'package.json'), '{"name":"functions"}\n');
+
+    const json = await runCli(['init', '--json'], {cwd: path.join(functions, 'src')});
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual([
+      '../../AGENTS.md',
+      '../../GEMINI.md',
+    ]);
+    expect(fs.readdirSync(functions).sort()).toEqual(['package.json', 'src']);
+  });
+});
+
 describe('astryx init --remove-agents', () => {
+  it('run in a subfolder, removes what init wrote at the project root, with the same JSON shape', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const sub = path.join(tmpDir, 'src', 'app');
+    fs.mkdirSync(sub, {recursive: true});
+    await runCli(['init'], {cwd: sub});
+    expect(exists('AGENTS.md')).toBe(true);
+
+    const text = await runCli(['init', '--remove-agents'], {cwd: sub});
+    expect(text.status).toBe(0);
+    expect(text.stdout).toMatch(/Removed empty \.\.\/\.\.\/AGENTS\.md/);
+    expect(exists('AGENTS.md')).toBe(false);
+    expect(exists('GEMINI.md')).toBe(false);
+
+    await runCli(['init'], {cwd: sub});
+    const json = await runCli(['init', '--remove-agents', '--json'], {cwd: sub});
+    expect(json.status).toBe(0);
+    // meta.answeredBy names the release that answered (spec AST-081).
+    expect(JSON.parse(json.stdout)).toEqual({
+      apiVersion: 1,
+      type: 'init.remove',
+      data: {removed: true},
+      meta: {answeredBy: expect.any(Object)},
+    });
+  });
+
   it('removes the Astryx section it previously installed', async () => {
     await runCli(['init', '--features', 'agents'], {cwd: tmpDir});
     expect(exists('AGENTS.md')).toBe(true);