@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/clients/cli/commands/gap-report.mjs

@@ -7,7 +7,7 @@
 import {gapReport as gapReportApi} from '../../../api/gap-report/gap-report.mjs';
 import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, record, records, section} from '../formatters/index.mjs';
+import {emit, record, records, section, text} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as gapReportCommand} from './gap-report.doc.mjs';
@@ -19,7 +19,7 @@ export function registerGapReport(program) {
     fn: gapReportFn,
     action: async (
       /** @type {string|undefined} */ component,
-      /** @type {{category?: string, reason?: string, additionalContext?: string, package?: string, confirmPublic?: boolean, listCategories?: boolean}} */ options,
+      /** @type {{category?: string, reason?: string, additionalContext?: string, package?: string, confirmPublic?: boolean, listCategories?: boolean, to?: string}} */ options,
     ) => {
       /** @type {Awaited<ReturnType<typeof gapReportApi>>} */
       let result;
@@ -35,6 +35,7 @@ export function registerGapReport(program) {
           package: options.package,
           confirmPublic: options.confirmPublic,
           listCategories: options.listCategories,
+          to: options.to,
         });
       } catch (error) {
         const err =
@@ -78,6 +79,9 @@ export function registerGapReport(program) {
           section('Gap report categories'),
           records(result.data, {fields: ['value', 'label']}),
         );
+        if (result.meta) {
+          emit(...destinationBlocks(result.meta.destinations, result.meta.ask));
+        }
         return answered;
       }
 
@@ -119,8 +123,26 @@ export function registerGapReport(program) {
         );
       }
 
+      if (result.data.destinations && result.data.ask) {
+        emit(...destinationBlocks(result.data.destinations, result.data.ask));
+      }
+
       if (isFailure) process.exitCode = 1;
       return answered;
     },
   });
 }
+
+/**
+ * The destinations a report can go to, then the line telling an agent to ask
+ * the person (architecture:cli-surface INV36).
+ * @param {import('../../../api/gap-report/gap-report.type.mjs').GapReportDestination[]} destinations
+ * @param {string} ask
+ */
+function destinationBlocks(destinations, ask) {
+  return [
+    section('Destinations'),
+    records(destinations, {fields: ['to', 'default', 'issuesUrl']}),
+    text(ask),
+  ];
+}

package/clients/cli/commands/gap-report.test.mjs

@@ -331,3 +331,82 @@ describe('gap-report control docs', () => {
     ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
   });
 });
+
+describe('gap-report destinations in text', () => {
+  it('lists the destinations and tells the agent to ask the person', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-dest-'));
+    try {
+      fs.writeFileSync(
+        path.join(cwd, 'package.json'),
+        JSON.stringify({name: 'fixture-app'}),
+      );
+      const pkg = path.join(cwd, 'node_modules', '@test', 'widgets');
+      fs.mkdirSync(pkg, {recursive: true});
+      fs.writeFileSync(
+        path.join(pkg, 'package.json'),
+        JSON.stringify({name: '@test/widgets', version: '1.0.0'}),
+      );
+      fs.writeFileSync(
+        path.join(pkg, 'astryx.integration.mjs'),
+        "export default {issuesUrl: 'https://tracker.example/widgets'};\n",
+      );
+      fs.writeFileSync(
+        path.join(cwd, 'astryx.config.mjs'),
+        `export default {
+  integrations: ['@test/widgets'],
+  gapReport: {audience: 'internal', handle: () => ({status: 'filed', message: 'shared'})},
+};\n`,
+      );
+
+      const listed = await runCli(['gap-report', '--list-categories'], {cwd});
+      expect(listed.status).toBe(0);
+      expect(listed.stdout).toContain('Destinations');
+      expect(listed.stdout).toMatch(/^default:\s+true$/m);
+      expect(listed.stdout).toMatch(/^to:\s+@test\/widgets$/m);
+      expect(listed.stdout).toMatch(
+        /^issuesUrl:\s+https:\/\/tracker\.example\/widgets$/m,
+      );
+      expect(listed.stdout).toMatch(/ask the person/i);
+
+      const filed = await runCli(
+        [
+          'gap-report',
+          'Button',
+          '--category',
+          'docs_gap',
+          '--reason',
+          'Need a keyboard example',
+        ],
+        {cwd},
+      );
+      expect(filed.status).toBe(0);
+      expect(filed.stdout).toContain('Destinations');
+      expect(filed.stdout).toMatch(/ask the person/i);
+
+      const chosen = await runCli(
+        [
+          'gap-report',
+          'Button',
+          '--category',
+          'docs_gap',
+          '--reason',
+          'Need a keyboard example',
+          '--to',
+          '@test/widgets',
+          '--json',
+        ],
+        {cwd},
+      );
+      expect(chosen.status).toBe(0);
+      expect(JSON.parse(chosen.stdout).data.deliveries).toEqual([
+        expect.objectContaining({
+          handler: 'issuesUrl',
+          status: 'routed_only',
+          url: 'https://tracker.example/widgets',
+        }),
+      ]);
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
+});

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

@@ -40,6 +40,7 @@ export const doc = {
     {label: 'Browse the catalog', cli: 'astryx hook --list'},
     {label: 'One hook as JSON', cli: 'astryx hook useFocusTrap --json'},
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {

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

@@ -39,6 +39,11 @@ const exists = rel => fs.existsSync(path.join(tmpDir, rel));
 
 describe('astryx init — default (no flags)', () => {
   it('installs the tool-agnostic AGENTS.md cheat sheet and prints next steps', async () => {
+    // Inside a project; outside one the steps are left out (outside-project.test.mjs).
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}',
+    );
     const {status, stdout} = await runCli(['init'], {cwd: tmpDir});
     expect(status).toBe(0);
     expect(exists('AGENTS.md')).toBe(true);
@@ -65,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 () => {
@@ -121,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);

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

@@ -16,10 +16,29 @@ export const doc = {
   summary: 'Initialize the design system in your project',
   description:
     'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +
-    'agents, and CI). By default it installs the AGENTS.md/CLAUDE.md agent-docs, ' +
-    'including guidance from configured integrations, and prints getting-started ' +
-    "steps. --features and --all print only the chosen features' guidance (no " +
-    'getting-started steps); the theme feature also writes an annotated theme template.',
+    'agents, and CI). By default it writes the agent-docs block, including guidance ' +
+    'from configured integrations, to AGENTS.md and to the Claude Code file the project ' +
+    'has (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 a one-line import of AGENTS.md to GEMINI.md ' +
+    'unless GEMINI.md already imports it. It then prints getting-started steps. Agent ' +
+    'docs go to the project root: the nearest folder at or above this one whose ' +
+    'package.json declares an @astryxdesign package, else the nearest with any ' +
+    'package.json, else this folder. The search stops at a repository root and never ' +
+    'counts the home folder. In the home folder, or in a settings folder in it ' +
+    'such as ~/.gemini outside a project, no agent docs are written. 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 project inside one, ' +
+    'such as an agent worktree with its own package.json, works. The managed block is ' +
+    'written whatever ignore rules or generated markers say; the text around it is never changed. ' +
+    '--features and --all print only ' +
+    "the chosen features' " +
+    'guidance (no getting-started steps); the theme feature also writes an annotated theme template. ' +
+    'Outside a project it writes the same files but prints no step that sets up a project: ' +
+    'no getting-started steps, and no step that adds a theme to an app. ' +
+        '--user writes the computer-level agent text instead (see the flag), in any folder, and touches nothing in the folder. ' +
+    'The CLI installed for the computer also keeps that text current in the background, unless --user --remove-agents turned it off; ' +
+    'package install scripts, project setup, and upgrade never write it.',
   fn: 'init',
   options: [
     {
@@ -39,19 +58,35 @@ export const doc = {
       flag: '--remove-agents',
       param: 'options.removeAgents',
       description:
-        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules, .hermes.md and HERMES.md ' +
-        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left) and do nothing else. " +
+        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md and HERMES.md, ' +
+        'at the project root (where init writes them) and in this folder ' +
+        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left, and GEMINI.md when nothing is left) and do nothing else. " +
+        'Below the project root, a project-root agent file whose block resolves outside the project is left as it is, with a note. ' +
         '--features, --all, --agent and --agent-docs-path are refused; a file written with --agent-docs-path keeps its block',
     },
+    {
+      flag: '--user',
+      param: 'options.user',
+      description:
+        'Write or refresh the computer-level agent text instead of setting up the folder: one skill file, ~/.agents/skills/astryx/SKILL.md, which most coding agents read, ' +
+        '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): a folder symlink with a relative target, a junction on Windows, or a copy where neither can be made. Continue, whose scanner skips links, gets a managed copy, refreshed with the file. ' +
+        "It tells agents anywhere on the computer that Astryx is there, when it is relevant, and to start with `astryx search`. " +
+        'Records the links it made in astryx/settings.json in the per-user configuration folder, so removal removes exactly those; the CLI installed for the computer refreshes the file in the background after each upgrade. ' +
+        'Works in any folder. A file without the Astryx markers, one edited since Astryx wrote it, or a symlink, is kept as it is, and so is anything at a link target that Astryx did not create. ' +
+        'Warns, and still writes, when no `astryx` command on the computer runs the Astryx CLI. ' +
+        'With --remove-agents it removes the file, the links, and the copy instead and records that the text is turned off. --features, --all, --agent and --agent-docs-path are refused',
+    },
     {
       flag: '--agent <tool>',
       param: 'options.agent',
       choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
       description:
         'Target AI tool for agent docs: claude (CLAUDE.md or .claude/CLAUDE.md, else creates .claude/CLAUDE.md), cursor (.cursorrules if present, else AGENTS.md), ' +
-        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc, else AGENTS.md and .claude/CLAUDE.md). ' +
+        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc except GEMINI.md, which keeps its ' +
+        'one-line import of AGENTS.md, else AGENTS.md and .claude/CLAUDE.md). With claude and all, when CLAUDE.md gets the block, .claude/CLAUDE.md gets none and ' +
+        'a block already there is removed, unless the project ignores CLAUDE.md: then a .claude/CLAUDE.md the project commits gets a copy too, with claude and all alike. ' +
         'An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
-        'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence',
+                'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence.',
     },
     {
       flag: '--agent-docs-path <path...>',
@@ -59,6 +94,7 @@ export const doc = {
       description:
         'Explicit file path(s) for agent docs, inside the project; takes precedence over --agent. ' +
         'If any path is outside the project, no agent docs are written and the command exits 1. ' +
+        'A path in the home folder itself, or in a settings folder in it outside a project (such as ~/.claude or ~/.claude/hooks), is refused with a note (exit 0), and nothing is written. ' +
         'Used only when agent docs are installed',
     },
   ],
@@ -66,16 +102,25 @@ export const doc = {
     {label: 'Default setup', cli: 'astryx init'},
     {label: 'All features, no prompts', cli: 'astryx init --all'},
     {label: 'Machine-readable receipt', cli: 'astryx init --json'},
+    {label: 'Agent text for the whole computer', cli: 'astryx init --user'},
+    {label: 'Remove the computer-level agent text and turn it off', cli: 'astryx init --user --remove-agents'},
   ],
+  outsideProject: 'own',
   exitCodes: [
     {
       code: 0,
-      when: 'success, including agent docs that could not be written for a reason other than a path escape (reported as docsError)',
+      when: "success, including agent docs left unwritten in five soft cases, each reported as docsError with one note: running in the home folder, or in a settings folder in it outside a project; a GEMINI.md that resolves outside the project; when init runs below the project root, a project-root agent file that resolves outside the project; the project's Claude Code file (root CLAUDE.md, or .claude/CLAUDE.md when there is no root one) when it resolves outside the project and is a block-less import of an existing AGENTS.md, which 0.7.1 left alone; and a .claude/CLAUDE.md that resolves outside the project and that 0.7.1 did not write: beside a CLAUDE.md the project ignores, the one --agent claude adds or a block-less import of an existing AGENTS.md; with --agent claude beside a CLAUDE.md, one whose block it would remove",
     },
     {
       code: 1,
-      when: 'an unknown --agent or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, or --all with --features (ERR_INVALID_ARGUMENT)',
+      when: 'an unknown --agent (ERR_UNKNOWN_AGENT) or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, --user combined with --features, --all, --agent or --agent-docs-path, or --all with --features (ERR_INVALID_ARGUMENT); or, when init runs at the project root, an agent file 0.7.1 also wrote there that resolves outside the project (ERR_PATH_TRAVERSAL, docsError path-safety, nothing written)',
     },
   ],
   related: ['doctor', 'upgrade', 'build', 'theme'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a project, init writes the agent docs (AGENTS.md) into the folder and prints no getting-started steps. `init --user` writes the agent guide for your computer, in any folder, and is never handed to a project's own CLI. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:computer-agent-guide}.",
+    },
+  ],
 };

package/clients/cli/commands/init.flag-help.test.mjs

@@ -67,6 +67,7 @@ describe('astryx init flag interactions', () => {
       expect(help).toContain(file);
     }
     expect(help).toMatch(/--agent-docs-path are refused/);
+    expect(help).toMatch(/at the project root \(where init writes them\) and in this folder/);
 
     await initJson(['--agent-docs-path', 'docs/AI.md']);
     await initJson([]);