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

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

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

package/api/init/run/run.d.mts

@@ -8,7 +8,7 @@
  * installed built themes and imports their production and font stylesheets. The
  * app imports that module once and passes its default to <Theme>.
  *
- * @param {string} invocation install-aware CLI invocation stem (e.g. `npx astryx`, `pnpm exec astryx`, or `npx @astryxdesign/cli` for one-off runs)
+ * @param {string} invocation install-aware CLI invocation stem (e.g. `pnpm exec astryx`, `yarn astryx`, or `npx @astryxdesign/cli` for one-off runs)
  * @returns {string[]} ordered list of human-facing lines
  */
 export function getNextSteps(invocation: string): string[];

package/api/init/run/run.mjs

@@ -4,10 +4,12 @@
  * @file init.run leaf — non-interactive project setup + feature installer.
  *
  * `run(options, ctx)` is the default / `--features` / `--all` path behind
- * `astryx init`. It installs the AGENTS.md/CLAUDE.md agent-docs cheat sheet,
- * points at the theme + page-building workflows, and (optionally) scaffolds a
- * starter template — with NO prompts, so it behaves identically for humans,
- * agents, CI, and piped I/O. It performs the side effects and returns an
+ * `astryx init`. It installs the agent-docs cheat sheet at the project root so
+ * every agent reads it (AGENTS.md, a copy in the project's Claude Code file, and
+ * a GEMINI.md import), points at the theme + page-building workflows, and
+ * (optionally) scaffolds a starter template — with NO prompts, so it behaves
+ * identically for humans, agents, CI, and piped I/O. It performs the side
+ * effects and returns an
  * `init.run` receipt. Hard errors (unknown feature/template) throw AstryxError
  * with a stable code. Human output is emitted through the shared `logger`
  * (silent by default) so the CLI keeps its exact plain output and a
@@ -19,9 +21,13 @@ import * as fs from 'node:fs';
 import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
 import {PathSafetyError, assertWithin} from '../../../foundation/fs/path-safety.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 import {
+  AgentDocsHomeError,
+  assertAgentDocsTarget,
   installAgentDocs,
   renderAgentDocsBlock,
+  agentDocsTargetDir,
 } from '../../../foundation/agent-docs/agent-docs.mjs';
 import {themeTemplate} from '../../theme/template/template.mjs';
 import {listTemplates} from '../../template/template.mjs';
@@ -39,7 +45,7 @@ const VALID_AGENTS = ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'];
  * installed built themes and imports their production and font stylesheets. The
  * app imports that module once and passes its default to <Theme>.
  *
- * @param {string} invocation install-aware CLI invocation stem (e.g. `npx astryx`, `pnpm exec astryx`, or `npx @astryxdesign/cli` for one-off runs)
+ * @param {string} invocation install-aware CLI invocation stem (e.g. `pnpm exec astryx`, `yarn astryx`, or `npx @astryxdesign/cli` for one-off runs)
  * @returns {string[]} ordered list of human-facing lines
  */
 export function getNextSteps(invocation) {
@@ -50,11 +56,11 @@ export function getNextSteps(invocation) {
     `       (run \`${invocation} doctor\` to verify)`,
     "    2. Import base styles: import '@astryxdesign/core/reset.css'",
     "       and import '@astryxdesign/core/astryx.css'",
-    "    3. Import components: import { Button } from '@astryxdesign/core'",
+    "    3. Import components: import { Button } from '@astryxdesign/core/Button'",
     '    4. Add and wire a theme:',
     '       npm install @astryxdesign/theme-neutral',
     `       ${invocation} theme add neutral`,
-    "       import { Theme } from '@astryxdesign/core'",
+    "       import { Theme } from '@astryxdesign/core/theme'",
     "       import { themes, defaultThemeSlug } from './astryx-themes'",
     '       <Theme theme={themes[defaultThemeSlug]}>...</Theme>',
     `       Extend an imported theme to customize it. Run \`${invocation} theme eject <slug>\` only to fork source.`,
@@ -63,6 +69,24 @@ export function getNextSteps(invocation) {
   ];
 }
 
+/**
+ * Whether two paths name one folder, links resolved.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function sameFolder(a, b) {
+  /** @param {string} p */
+  const real = p => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  return real(a) === real(b);
+}
+
 /**
  * Install the agent-docs block; records the outcome (or soft error) on `data`.
  * Mirrors the CLI's historical soft-error policy: a PathSafetyError surfaces its
@@ -91,14 +115,46 @@ async function applyAgents(cwd, options, invocation, data) {
         ? options.agentDocsPath
         : [options.agentDocsPath]
       : undefined;
-    const renderedBlock = await renderAgentDocsBlock(cwd);
-    const written = installAgentDocs(cwd, {
+    // The docs belong at the project root, not in the subfolder init ran in;
+    // with no project above, they go where init ran, as before. Explicit
+    // --agent-docs-path entries stay relative to where init ran.
+    const root = agentDocsTargetDir(cwd);
+    const targetDir = paths ? cwd : root;
+    // With explicit paths, installAgentDocs checks each file's own folder.
+    if (!paths) assertAgentDocsTarget(targetDir);
+    const renderedBlock = await renderAgentDocsBlock(root);
+    /** @type {string[]} */
+    const skipped = [];
+    const files = installAgentDocs(targetDir, {
       agent: options.agent,
       paths,
       renderedBlock,
+      onSkipped: (rel, reason) => skipped.push(`${rel} (${reason})`),
+      // Below the project root, 0.7.1 wrote in the folder init ran in, so a
+      // project-root file that escapes the project is skipped and reported,
+      // not refused.
+      refuseEscapes: sameFolder(targetDir, cwd),
     });
+    // Each file is reported from where init ran, as before.
+    const written =
+      path.resolve(targetDir) === path.resolve(cwd)
+        ? files
+        : files.map(rel =>
+            path.relative(cwd, path.join(targetDir, rel)).split(path.sep).join('/'),
+          );
     data.docsWritten = written;
     logger.log(`[ok] AI agent docs installed -> ${written.join(', ')}`);
+    // A file 0.7.1 did not write (GEMINI.md, or a project-root file when init
+    // runs below the root) that resolves outside the project is left as it
+    // is, reported in docsError with one note; the exit code stays 0. A file
+    // 0.7.1 wrote whose path escapes the project still fails the run (below).
+    if (skipped.length > 0) {
+      const message =
+        `Left as ${skipped.length === 1 ? 'it is' : 'they are'}: ${skipped.join('; ')}. ` +
+        'To have init write the Astryx block there, make it a regular file inside the project, or copy the block from AGENTS.md by hand.';
+      logger.warn(`Note: ${message}`);
+      data.docsError = {kind: 'install-failed', message};
+    }
   } catch (err) {
     // PathSafetyError carries a precise, user-actionable message — surface it
     // (and flag exit 1) instead of the generic "could not install" warning so
@@ -108,6 +164,14 @@ async function applyAgents(cwd, options, invocation, data) {
       data.docsError = {kind: 'path-safety', message: err.message};
       return;
     }
+    // The home folder, and a settings folder in it outside a project, are
+    // refused: nothing is written, the reason is printed as a note, and the
+    // exit code stays 0.
+    if (err instanceof AgentDocsHomeError) {
+      logger.warn(`Note: ${err.message}`);
+      data.docsError = {kind: 'install-failed', message: err.message};
+      return;
+    }
     logger.error(
       `Could not install agent docs. Try again with \`${invocation} init --features agents\`.`,
     );
@@ -140,8 +204,11 @@ function applyTheme(cwd, invocation, data) {
     data.themeTemplate = 'failed';
     logger.error('Could not write the theme template.');
   }
+  // Outside a project there is no app to add a theme to (spec AST-081 FR3).
   logger.log(
-    `  Edit the blank template for a new theme, or run \`${invocation} theme add <slug>\` to import an installed built theme (\`${invocation} theme list\` to browse). Extend an imported theme for ordinary customization; use \`${invocation} theme eject <slug>\` only to fork source.`,
+    isOutsideProject(cwd)
+      ? `  Edit the blank template for a new theme, or run \`${invocation} theme eject <slug>\` to start from the source of a built theme (\`${invocation} theme list\` to browse).`
+      : `  Edit the blank template for a new theme, or run \`${invocation} theme add <slug>\` to import an installed built theme (\`${invocation} theme list\` to browse). Extend an imported theme for ordinary customization; use \`${invocation} theme eject <slug>\` only to fork source.`,
   );
 }
 
@@ -276,7 +343,10 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
   }
 
   // No flags: TTY-free default — install the AI agent cheat sheet with NO
-  // prompts, then print the getting-started guidance.
+  // prompts, then print the getting-started guidance. Outside a project the
+  // steps would set up a project the folder does not have, so they are left
+  // out (spec AST-081 FR3).
+  const outside = isOutsideProject(cwd);
   /** @type {import('../init.type.mjs').InitRunData} */
   const data = {
     mode: 'default',
@@ -288,13 +358,17 @@ export async function run(options = {}, {cwd = process.cwd()} = {}) {
     themeTemplatePath: null,
     template: null,
     templatePath: null,
-    nextSteps: true,
+    nextSteps: !outside,
   };
   await applyAgents(cwd, options, invocation, data);
   logger.log('');
   logger.log(
     `  Tip: \`${invocation} init --all\` also points you to the theme and page-building workflows.`,
   );
+  if (outside) {
+    logger.log('');
+    return {type: 'init.run', data};
+  }
   for (const line of getNextSteps(invocation)) logger.log(line);
   return {type: 'init.run', data};
 }

package/api/init/user/user.d.mts

@@ -0,0 +1,14 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Write or remove the computer-level agent text and return an `init.user`
+ * receipt. Progress is emitted through the shared `logger` (silent by
+ * default); warnings go to its warn channel.
+ *
+ * @param {{remove?: boolean}} [options]
+ * @returns {Promise<import('../init.type.mjs').InitUserResponse>}
+ */
+export function user({ remove }?: {
+    remove?: boolean;
+}): Promise<import("../init.type.mjs").InitUserResponse>;

package/api/init/user/user.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file init.user leaf — the `--user` path behind `astryx init`.
+ *
+ * `user(options)` writes, refreshes, or (with `remove`) removes the
+ * computer-level agent text: one skill file in the home folder, linked into
+ * the skill folders agents read (spec AST-081 FR7, FR8). It records the
+ * setting and the links it made in the settings file, so the global copy,
+ * which keeps the text current in the background, does the same, or, after
+ * `remove`, writes nothing. The adapter does every file access. It works in any
+ * folder and never touches a project's agent docs. A file without the Astryx
+ * markers, one a person edited, or a symlinked one is kept as it is. When no
+ * `astryx` on the computer's search path runs the Astryx CLI, the text is
+ * still written and the receipt warns that the CLI should be installed for
+ * the computer.
+ *
+ * @input  `remove`; the home folder, search path, and settings of
+ *   the computer
+ * @output an `init.user` receipt
+ * @position packages/cli/api/init — dispatched by init.mjs
+ */
+
+import {
+  COMPUTER_COMMAND,
+  COMPUTER_INSTALL_STEP,
+  applyComputerAgentText,
+  displayHomePath,
+} from '../_adapter.mjs';
+import {logger} from '../../logger.mjs';
+
+/**
+ * @param {string} file
+ * @param {string} home
+ * @returns {string}
+ */
+const display = (file, home) => displayHomePath(file, home);
+
+/** @type {Record<import('../init.type.mjs').InitUserAction, string>} */
+const ACTION_LINES = {
+  written: '[ok] Wrote',
+  linked: '[ok] Linked',
+  unchanged: '[ok] Already current:',
+  removed: '[ok] Removed',
+  absent: '[ok] Nothing to remove:',
+  kept: '[skip] Kept',
+};
+
+/** @type {Record<'edited' | 'not-astryx', string>} */
+const KEPT_REASONS = {
+  edited: '(edited since Astryx wrote it; delete it to get the current text):',
+  'not-astryx': '(not created by Astryx):',
+};
+
+/**
+ * Write or remove the computer-level agent text and return an `init.user`
+ * receipt. Progress is emitted through the shared `logger` (silent by
+ * default); warnings go to its warn channel.
+ *
+ * @param {{remove?: boolean}} [options]
+ * @returns {Promise<import('../init.type.mjs').InitUserResponse>}
+ */
+export async function user({remove = false} = {}) {
+  const {home, command, files, cliOnSearchPath} = applyComputerAgentText({
+    remove,
+  });
+  /** @type {string[]} */
+  const warnings = [];
+  // A host's door is its own command; only the plain `astryx` needs a copy of
+  // the CLI installed for the computer.
+  if (!remove && command === COMPUTER_COMMAND && !cliOnSearchPath) {
+    warnings.push(
+      `No \`${COMPUTER_COMMAND}\` command on this computer runs the Astryx CLI, so agents cannot run the commands this text names. Install the CLI for the computer: ${COMPUTER_INSTALL_STEP}`,
+    );
+  }
+  for (const file of files) {
+    const reason = file.reason ? ` ${KEPT_REASONS[file.reason]}` : '';
+    logger.log(
+      `${ACTION_LINES[file.action]}${reason || (file.action === 'kept' ? ':' : '')} ${display(file.path, home)}`,
+    );
+  }
+  for (const warning of warnings) logger.warn(`[warn] ${warning}`);
+  return {
+    type: 'init.user',
+    data: {files, command, warnings},
+  };
+}

package/api/init/user/user.test.mjs

@@ -0,0 +1,232 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `init({user})` and `astryx init --user`: the `init.user` receipt, the
+ * install warning, the refused combinations, and that it touches nothing in
+ * the folder it runs in. Every test uses a temporary home folder and search
+ * path.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {init} from '../init.mjs';
+import {user} from './user.mjs';
+import {runWithCliDoor} from '../../../foundation/env/cli-command.mjs';
+import {renderComputerAgentText} from '../../../foundation/agent-docs/computer-agent-text.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {settingsFile} from '../../../foundation/env/user-settings.mjs';
+import {readGlobalState} from '../../../foundation/release/global-state.mjs';
+import {cliVersion} from '../../../foundation/release/run-context.mjs';
+
+/** @type {string[]} */
+const dirs = [];
+/** @param {string} label */
+function tmp(label) {
+  const dir = fs.mkdtempSync(
+    path.join(os.tmpdir(), `astryx-init-user-${label}-`),
+  );
+  dirs.push(dir);
+  return dir;
+}
+
+let home = '';
+let emptyPath = '';
+beforeEach(() => {
+  home = tmp('home');
+  emptyPath = tmp('path');
+  vi.stubEnv('HOME', home);
+  vi.stubEnv('USERPROFILE', home);
+  vi.stubEnv('PATH', emptyPath);
+  // The settings file and the cache live under this home folder too.
+  vi.stubEnv('XDG_CONFIG_HOME', path.join(home, '.config'));
+  vi.stubEnv('XDG_CACHE_HOME', path.join(home, '.cache'));
+  vi.stubEnv('APPDATA', path.join(home, 'AppData', 'Roaming'));
+  vi.stubEnv('LOCALAPPDATA', path.join(home, 'AppData', 'Local'));
+});
+
+/** The settings file under the temporary home folder. */
+const settings = () => {
+  try {
+    return JSON.parse(fs.readFileSync(settingsFile(), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+afterEach(() => {
+  vi.unstubAllEnvs();
+  while (dirs.length) {
+    fs.rmSync(/** @type {string} */ (dirs.pop()), {
+      recursive: true,
+      force: true,
+    });
+  }
+});
+
+const FILE = path.join('.agents', 'skills', 'astryx', 'SKILL.md');
+const CLAUDE = path.join('.claude', 'skills', 'astryx');
+
+/** Put a linked Astryx CLI first on the search path. */
+function installCliOnPath() {
+  const prefix = tmp('prefix');
+  const pkg = path.join(prefix, 'lib', 'node_modules', '@astryxdesign', 'cli');
+  fs.mkdirSync(pkg, {recursive: true});
+  fs.writeFileSync(
+    path.join(pkg, 'package.json'),
+    '{"name":"@astryxdesign/cli"}',
+  );
+  fs.writeFileSync(path.join(pkg, 'bin.mjs'), '#!/usr/bin/env node\n');
+  fs.chmodSync(path.join(pkg, 'bin.mjs'), 0o755);
+  fs.mkdirSync(path.join(prefix, 'bin'));
+  fs.symlinkSync(path.join(pkg, 'bin.mjs'), path.join(prefix, 'bin', 'astryx'));
+  vi.stubEnv('PATH', path.join(prefix, 'bin'));
+}
+
+describe('init({user: true})', () => {
+  it('writes the file, links Claude Code to it, and returns the init.user receipt, warning when no astryx runs the CLI', async () => {
+    const r = await init({user: true}, {cwd: tmp('cwd')});
+    expect(r.type).toBe('init.user');
+    if (r.type !== 'init.user') return;
+    expect(r.data.files).toEqual([
+      {path: path.join(home, FILE), action: 'written'},
+      {path: path.join(home, CLAUDE), action: 'linked'},
+    ]);
+    expect(r.data.command).toBe('astryx');
+    expect(r.data.warnings).toHaveLength(1);
+    expect(r.data.warnings[0]).toContain('npm i -g @astryxdesign/cli');
+    expect(fs.readFileSync(path.join(home, FILE), 'utf8')).toBe(
+      renderComputerAgentText({command: 'astryx'}),
+    );
+    expect(fs.readFileSync(path.join(home, CLAUDE, 'SKILL.md'), 'utf8')).toBe(
+      renderComputerAgentText({command: 'astryx'}),
+    );
+  });
+
+  it.skipIf(process.platform === 'win32')(
+    'does not warn when the astryx on the search path is the Astryx CLI',
+    async () => {
+      installCliOnPath();
+      const r = await user();
+      expect(r.data.warnings).toEqual([]);
+    },
+  );
+
+  it("names the host's door and does not ask for a global install", async () => {
+    const r = await runWithCliDoor('acme astryx', () => user());
+    expect(r.data.command).toBe('acme astryx');
+    expect(r.data.warnings).toEqual([]);
+    expect(fs.readFileSync(path.join(home, FILE), 'utf8')).toContain(
+      "`acme astryx search '<what you need>'`",
+    );
+  });
+
+  it('works inside a project and writes nothing in it', async () => {
+    const dir = tmp('project');
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}',
+    );
+    const before = fs.readdirSync(dir).sort();
+    const r = await init({user: true}, {cwd: dir});
+    expect(r.type).toBe('init.user');
+    expect(fs.readdirSync(dir).sort()).toEqual(before);
+  });
+
+  it('records the links it made, and the release that wrote the text', async () => {
+    await init({user: true});
+    expect(settings()).toEqual({
+      computerAgentText: {install: true, links: [path.join(home, CLAUDE)]},
+    });
+    expect(readGlobalState().agentText).toEqual({writtenBy: cliVersion()});
+  });
+
+  it('keeps every other setting when it records the choice', async () => {
+    fs.mkdirSync(path.dirname(settingsFile()), {recursive: true});
+    fs.writeFileSync(settingsFile(), '{"other": 1}');
+    await init({user: true, removeAgents: true});
+    expect(settings()).toEqual({
+      other: 1,
+      computerAgentText: {install: false, links: []},
+    });
+  });
+
+  it('with removeAgents removes the file and the links it made, and records that the text is not wanted', async () => {
+    await init({user: true});
+    const r = await init({user: true, removeAgents: true});
+    expect(r.type).toBe('init.user');
+    if (r.type !== 'init.user') return;
+    expect(r.data.files).toEqual([
+      {path: path.join(home, FILE), action: 'removed'},
+      {path: path.join(home, CLAUDE), action: 'removed'},
+    ]);
+    expect(r.data.warnings).toEqual([]);
+    expect(fs.existsSync(path.join(home, FILE))).toBe(false);
+    expect(fs.existsSync(path.join(home, CLAUDE))).toBe(false);
+    expect(settings()).toEqual({
+      computerAgentText: {install: false, links: []},
+    });
+  });
+
+  it.each([
+    [{features: 'agents'}, '--features'],
+    [{all: true}, '--all'],
+    [{agentDocsPath: 'X.md'}, '--agent-docs-path'],
+    [{agent: 'claude'}, '--agent'],
+    [{removeAgents: true, agent: 'claude'}, '--agent'],
+  ])(
+    'refuses %o with ERR_INVALID_ARGUMENT and writes nothing',
+    async (extra, flag) => {
+      await expect(init({user: true, ...extra})).rejects.toMatchObject({
+        code: 'ERR_INVALID_ARGUMENT',
+        message: expect.stringContaining(flag),
+      });
+      expect(fs.existsSync(path.join(home, '.agents'))).toBe(false);
+      expect(fs.existsSync(path.join(home, '.claude'))).toBe(false);
+    },
+  );
+});
+
+describe('astryx init --user', () => {
+  it('prints the file, the link, and the install warning in text mode', async () => {
+    const r = await runCli(['init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain(`Wrote ~${path.sep}${FILE}`);
+    expect(r.stdout).toContain(`Linked ~${path.sep}${CLAUDE}`);
+    expect(r.stderr).toContain('npm i -g @astryxdesign/cli');
+  });
+
+  it('emits the init.user envelope under --json', async () => {
+    const r = await runCli(['--json', 'init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    const env = JSON.parse(r.stdout);
+    expect(env.type).toBe('init.user');
+    expect(
+      env.data.files.map((/** @type {{action: string}} */ f) => f.action),
+    ).toEqual(['written', 'linked']);
+    expect(env.data.command).toBe('astryx');
+  });
+
+  it('names a file a person edited as kept, and why', async () => {
+    await runCli(['init', '--user'], tmp('cwd'));
+    const file = path.join(home, FILE);
+    fs.appendFileSync(file, 'my note\n');
+    const r = await runCli(['init', '--user'], tmp('cwd'));
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain(
+      `Kept (edited since Astryx wrote it; delete it to get the current text): ~${path.sep}${FILE}`,
+    );
+    expect(fs.readFileSync(file, 'utf8')).toMatch(/my note\n$/u);
+  });
+
+  it('exits 1 with ERR_INVALID_ARGUMENT when combined with --all or --agent', async () => {
+    for (const extra of [['--all'], ['--agent', 'claude']]) {
+      const r = await runCli(
+        ['--json', 'init', '--user', ...extra],
+        tmp('cwd'),
+      );
+      expect(r.status).toBe(1);
+      expect(JSON.parse(r.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    }
+  });
+});