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

package/api/hook/_adapter.mjs

@@ -14,14 +14,14 @@
  * @position api/hook/_adapter.mjs — shared by ./list, ./detail, ./detail/params
  */
 
-import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {requireCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   findHookDoc,
   getAllHookNames,
 } from '../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
-import {AstryxError} from '../error.mjs';
+import {AstryxError, coreDirOrThrow} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
 /** The package that owns Core's components, hooks, and codemods. */
@@ -34,15 +34,7 @@ export {CORE_PROVIDER_ID as CORE_PACKAGE} from '../../foundation/identity/provid
  * @returns {string} Absolute path to the core package directory.
  */
 export function resolveCoreDir(cwd) {
-  const coreDir = findCoreDir(cwd);
-  if (!coreDir) {
-    throw new AstryxError(
-      'Could not find @astryxdesign/core package',
-      undefined,
-      ERROR_CODES.ERR_CORE_NOT_FOUND,
-    );
-  }
-  return coreDir;
+  return coreDirOrThrow(requireCoreDir, cwd);
 }
 
 /**

package/api/hook/hook.doc.mjs

@@ -90,6 +90,10 @@ export const doc = {
       code: 'ERR_CORE_NOT_FOUND',
       when: '@astryxdesign/core cannot be resolved from cwd',
     },
+    {
+      code: 'ERR_VERSIONS_UNAVAILABLE',
+      when: 'outside a project, or in a project with nothing installed, the Core of the release that answers is not beside it or cached, and cannot be installed into the per-user cache (offline, a registry without it, or an unwritable cache)',
+    },
     {
       code: 'ERR_UNKNOWN_CATEGORY',
       when: 'options.category is not a string or matches no known category',

package/api/hook/hook.mjs

@@ -43,7 +43,7 @@ export async function hook(name, options = {}) {
     zh = false,
   } = options;
 
-  // Default detail level mirrors the CLI (see commands/hook/index.mjs):
+  // Default detail level mirrors the CLI (see commands/hook.mjs):
   // single-hook views default to 'full', list-style views (--list,
   // --category, or no name) default to 'brief' (scannable name lists).
   // Keeping this in sync with the CLI is what the API↔CLI parity test checks.

package/api/hook/list/list.d.mts

@@ -13,7 +13,7 @@
 export function list({ cwd, category, detail, zh, lang, }?: {
     cwd?: string | undefined;
     category?: string | undefined;
-    detail?: "compact" | "full" | "brief" | "names" | undefined;
+    detail?: "names" | "compact" | "full" | "brief" | undefined;
     zh?: boolean | undefined;
     lang?: string | null | undefined;
 }): Promise<import("../hook.type.mjs").HookListResponse>;

package/api/index.d.mts

@@ -16,6 +16,7 @@ export { init } from "./init/init.mjs";
 export { doctor } from "./doctor/doctor.mjs";
 export { integrationAddTheme } from "./integration/add-theme.mjs";
 export { integrationPackCheck } from "./integration/pack-check.mjs";
+export { integrationCheck } from "./integration/check/check.mjs";
 export { AstryxError } from "./error.mjs";
 export { logger } from "./logger.mjs";
 export * from "../foundation/response/batch.type.mjs";
@@ -37,6 +38,7 @@ export * from "./integration/integration-authoring.type.mjs";
 export * from "./integration/pack-check.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export * from "./integration/authoring-checks.type.mjs";
+export * from "./integration/integration-check.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
 export { themeBuild, themeAdd, themeRemove, themeUse, themeEject, themeTemplate, themeList, themeListAvailable, themeListCopySources, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";

package/api/index.mjs

@@ -67,6 +67,7 @@ export {
   integrationComponentConflicts,
   integrationDocConflicts,
 } from './integration/authoring-checks.mjs';
+export {integrationCheck} from './integration/check/check.mjs';
 export {AstryxError} from './error.mjs';
 // The one shared logger: the `logger` instance side-effecting commands write
 // through, plus its generated `Logger` type. Part of the public surface so an
@@ -100,3 +101,4 @@ export * from './integration/integration-authoring.type.mjs';
 export * from './integration/pack-check.type.mjs';
 export * from './integration/validate-integration.type.mjs';
 export * from './integration/authoring-checks.type.mjs';
+export * from './integration/integration-check.type.mjs';

package/api/init/_adapter.d.mts

@@ -0,0 +1,22 @@
+// @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 refresh the computer-level agent text, or remove it, and record
+ * the setting and the links Astryx made; after a write, record the release
+ * that wrote it.
+ * @param {{remove: boolean}} options
+ * @returns {{home: string, command: string, files: import('./init.type.mjs').InitUserFile[], cliOnSearchPath: boolean}}
+ */
+export function applyComputerAgentText({ remove }: {
+    remove: boolean;
+}): {
+    home: string;
+    command: string;
+    files: import("./init.type.mjs").InitUserFile[];
+    cliOnSearchPath: boolean;
+};
+import { COMPUTER_COMMAND } from '../../foundation/agent-docs/computer-agent-text.mjs';
+import { COMPUTER_INSTALL_STEP } from '../../foundation/agent-docs/computer-agent-text.mjs';
+import { displayHomePath } from '../../foundation/agent-docs/computer-agent-text.mjs';
+export { COMPUTER_COMMAND, COMPUTER_INSTALL_STEP, displayHomePath };

package/api/init/_adapter.mjs

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Environment adapter for `init --user`: the home folder, the settings
+ * file, the per-user state, and the search path (spec AST-081 FR7, FR8;
+ * architecture:cli-surface INV21).
+ *
+ * @input  the home folder, the settings file, the search path
+ * @output the computer-level agent text written or removed, with the setting
+ *   and the links recorded
+ * @position packages/cli/api/init — imported by the user leaf only
+ */
+
+import * as os from 'node:os';
+import {
+  COMPUTER_COMMAND,
+  COMPUTER_INSTALL_STEP,
+  astryxOnSearchPath,
+  computerAgentCommand,
+  displayHomePath,
+  removeComputerAgentText,
+  writeComputerAgentText,
+} from '../../foundation/agent-docs/computer-agent-text.mjs';
+import {
+  computerAgentTextSettings,
+  recordComputerAgentTextSettings,
+} from '../../foundation/env/user-settings.mjs';
+import {recordAgentTextWritten} from '../../foundation/release/global-state.mjs';
+import {cliVersion} from '../../foundation/release/run-context.mjs';
+
+export {COMPUTER_COMMAND, COMPUTER_INSTALL_STEP, displayHomePath};
+
+/**
+ * Write or refresh the computer-level agent text, or remove it, and record
+ * the setting and the links Astryx made; after a write, record the release
+ * that wrote it.
+ * @param {{remove: boolean}} options
+ * @returns {{home: string, command: string, files: import('./init.type.mjs').InitUserFile[], cliOnSearchPath: boolean}}
+ */
+export function applyComputerAgentText({remove}) {
+  const home = os.homedir();
+  const command = computerAgentCommand();
+  const recorded = computerAgentTextSettings().links;
+  /** @type {import('./init.type.mjs').InitUserFile[]} */
+  let files;
+  if (remove) {
+    files = removeComputerAgentText({home, links: recorded});
+    recordComputerAgentTextSettings({install: false, links: []});
+  } else {
+    const written = writeComputerAgentText({home, command});
+    files = written.rows;
+    recordComputerAgentTextSettings({
+      install: true,
+      links: [...new Set([...recorded, ...written.links])],
+    });
+    recordAgentTextWritten(cliVersion());
+  }
+  return {home, command, files, cliOnSearchPath: astryxOnSearchPath()};
+}

package/api/init/init.d.mts

@@ -9,19 +9,21 @@
  * @typedef {import('./init.type.mjs').InitRunData} InitRunData
  */
 /**
- * Run the non-interactive init flow. Dispatches to the remove leaf when
- * `--remove-agents` is set, otherwise to the install (run) leaf, and returns
- * that leaf's receipt. Progress is emitted through `logger` (silent by
+ * Run the non-interactive init flow. Dispatches to the user leaf when
+ * `--user` is set (it writes, or with `--remove-agents` removes, the
+ * computer-level agent text and nothing in the folder), to the remove leaf
+ * when `--remove-agents` is set, otherwise to the install (run) leaf, and
+ * returns that leaf's receipt. Progress is emitted through `logger` (silent by
  * default); unknown feature or template names throw AstryxError with a stable
  * code.
  *
  * @param {InitOptions} [options]
  * @param {{cwd?: string}} [ctx]
- * @returns {Promise<import('./init.type.mjs').InitRunResponse | import('./init.type.mjs').InitRemoveResponse>}
+ * @returns {Promise<import('./init.type.mjs').InitRunResponse | import('./init.type.mjs').InitRemoveResponse | import('./init.type.mjs').InitUserResponse>}
  */
 export function init(options?: InitOptions, { cwd }?: {
     cwd?: string;
-}): Promise<import("./init.type.mjs").InitRunResponse | import("./init.type.mjs").InitRemoveResponse>;
+}): Promise<import("./init.type.mjs").InitRunResponse | import("./init.type.mjs").InitRemoveResponse | import("./init.type.mjs").InitUserResponse>;
 export { getNextSteps } from "./run/run.mjs";
 /**
  * Re-exported types so callers can keep referencing them off the init barrel

package/api/init/init.doc.mjs

@@ -17,14 +17,29 @@ export const doc = {
     'Non-interactive project setup: install agent docs and point at the theme + build workflows.',
   description:
     'Sets a project up with NO prompts, so it behaves identically for humans, ' +
-    'agents, CI, and piped I/O. By default it installs the AGENTS.md/CLAUDE.md ' +
-    'agent-docs cheat sheet, including guidance from configured integrations, and ' +
+    'agents, CI, and piped I/O. By default it writes the agent-docs cheat sheet, ' +
+    'including guidance from configured integrations, at the project root (the nearest ' +
+    'package.json that declares an @astryxdesign package, else the nearest package.json, ' +
+    'searching no higher than the repository root): to AGENTS.md, ' +
+    "to the project's Claude Code file (CLAUDE.md, else .claude/CLAUDE.md; when CLAUDE.md " +
+    'exists, a block in .claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a ' +
+    '.claude/CLAUDE.md the project commits keeps a copy), and as a ' +
+    'one-line import of AGENTS.md in GEMINI.md unless GEMINI.md already imports it. ' +
+    'In the home folder, or in a settings folder in it outside a project, it writes none: every ' +
+    'folder of the home folder whose name starts with a dot is a settings folder, and such a folder itself never ' +
+    'counts as a project, even with a package.json; a folder below it with a package.json does. ' +
+    'The managed block is Astryx-owned: it is written, refreshed, and removed whatever ignore rules ' +
+    'or generated markers say, and the text around it is never changed. It then ' +
     "prints getting-started guidance; `features` / `all` print only the chosen features' " +
     'guidance instead (the theme feature also writes the annotated theme template). ' +
-    'With `removeAgents` it removes the managed agent-docs block instead of installing.',
+    'With `removeAgents` it removes the managed agent-docs block, at the project root and in `ctx.cwd`, instead of installing. ' +
+    'Outside a project it writes the same files but prints no getting-started steps and no step that adds a theme to an app, since those set up a project the folder does not have. ' +
+        "With `user` it sets up the computer instead of the folder: it writes the computer-level agent text, one skill file at `~/.agents/skills/astryx/SKILL.md`, linked into the skill folders of agents that read only their own (`~/.claude/skills` always; Kiro, Windsurf, Letta, Xcode's coding assistant, and `~/.config/agents/skills` when that folder exists), with a managed copy for Continue, whose scanner skips links,, telling agents anywhere on the computer that Astryx is there and when to use it; with `user` and `removeAgents` it removes the file and the links it made and records that the text is turned off. " +
+    'The CLI installed for the computer refreshes the file in the background after each upgrade; package install scripts, project setup, and upgrade never write it.' +
+    " In global mode: with `cwd` outside a project, it writes the agent docs and prints no getting-started steps; `user` writes only the agent guide for the computer, in the home folder, and touches nothing in `cwd`. See {@link namespace:global} and {@link generic:computer-agent-guide}.",
   importPath: '@astryxdesign/cli/api',
   signature:
-    'init(options?: InitOptions, ctx?: {cwd?: string}): Promise<InitRunResponse | InitRemoveResponse>',
+    'init(options?: InitOptions, ctx?: {cwd?: string}): Promise<InitRunResponse | InitRemoveResponse | InitUserResponse>',
   keywords: ['init', 'setup', 'install', 'scaffold', 'agents', 'bootstrap'],
   params: [
     {
@@ -41,13 +56,27 @@ export const doc = {
     {
       name: 'options.removeAgents',
       type: 'boolean',
-      description: 'Remove the managed agent-docs block instead of installing.',
+      description:
+        'Remove the managed agent-docs block, at the project root and in `ctx.cwd`, instead of installing. With `user`, remove the computer-level agent text instead.',
+    },
+    {
+      name: 'options.user',
+      type: 'boolean',
+      description:
+        "Write or refresh the computer-level agent text instead of setting up `ctx.cwd`: one skill file at `~/.agents/skills/astryx/SKILL.md` in the current user's home folder, linked (a folder symlink with a relative target, a junction on Windows, or a copy where neither can be made) into `~/.claude/skills/astryx`, and into the skills folder of Kiro, Windsurf, Letta, Xcode's coding assistant, and `~/.config/agents/skills` when that folder exists; Continue, whose scanner skips links, gets a managed copy, refreshed with the file. " +
+        'The text uses the `astryx` command, or the command of the host that started the run; an integration\'s `cliCommand` never applies. ' +
+        'Records the links it made, or with `removeAgents` that the text is turned off, in `astryx/settings.json` in the per-user configuration 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. When no `astryx` command on the computer runs the Astryx CLI, the text is still written and the receipt carries a warning to install the CLI for the computer (`npm i -g @astryxdesign/cli`). ' +
+        'Cannot be combined with `features`, `all`, `agent`, or `agentDocsPath`.',
     },
     {
       name: 'options.agent',
       type: 'string',
       description:
-        'Agent preset: claude, cursor, codex, hermes, muse, all. Used only when the agents feature runs.',
+        'Agent preset: claude, cursor, codex, hermes, muse, all. `all` writes every existing agent doc except GEMINI.md, ' +
+        'which keeps its one-line import of AGENTS.md. With claude and all, when CLAUDE.md gets the block, a block in ' +
+        '.claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a .claude/CLAUDE.md the ' +
+        'project commits gets a copy too. Used only when the agents feature runs. Refused with `user`.',
     },
     {
       name: 'options.agentDocsPath',
@@ -71,22 +100,27 @@ export const doc = {
     {
       type: 'init.run',
       description:
-        'The install receipt: the `mode` (`default` | `features`), the features run, agent-doc files written, any soft docsError, the theme-template outcome (`created` | `skipped` | `failed`) plus its path, the page-template outcome (`workflow` | `created` | `skipped`) plus its path, and whether the next-steps were emitted.',
+        'The install receipt: the `mode` (`default` | `features`), the features run, agent-doc files written, any soft docsError, the theme-template outcome (`created` | `skipped` | `failed`) plus its path, the page-template outcome (`workflow` | `created` | `skipped`) plus its path, and whether the next-steps were emitted (never outside a project).',
     },
     {
       type: 'init.remove',
       description:
         'The removal receipt, returned when `removeAgents` is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove.',
     },
+    {
+      type: 'init.user',
+      description:
+        'The computer-level agent text receipt, returned when `user` is set: `data.files`, one `{path, action, reason?}` per path acted on (`~/.agents/skills/astryx/SKILL.md`, then each link to its folder, such as `~/.claude/skills/astryx`; action `written` | `linked` | `unchanged` | `removed` | `absent` | `kept`; `reason` on `kept`: `edited` | `not-astryx`), `data.command` (the command the text names), and `data.warnings`.',
+    },
   ],
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: '--remove-agents is combined with --features, --all, --agent, or --agent-docs-path; or --all is combined with --features',
+            when: '--remove-agents is combined with --features, --all, --agent, or --agent-docs-path; --user is combined with --features, --all, --agent, or --agent-docs-path; or --all is combined with --features',
     },
     {
       code: 'ERR_UNKNOWN_AGENT',
-      when: 'the agents feature runs (default mode, features includes agents, or all) and `agent` is not one of claude, cursor, codex, hermes, muse, all',
+            when: 'the agents feature runs (default mode, features includes agents, or all) and `agent` is not one of claude, cursor, codex, hermes, muse, all',
     },
     {
       code: 'ERR_UNKNOWN_FEATURE',
@@ -102,13 +136,14 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file resolves outside cwd through a symlink',
+      when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file in cwd, or at the project root when run there, resolves outside that folder through a symlink (run below the root, a project-root file is left as it is with a note)',
     },
   ],
   examples: [
     {label: 'Default setup', code: 'const r = await init();'},
     {label: 'All features', code: 'await init({all: true});'},
     {label: 'Remove agent docs', code: 'await init({removeAgents: true});'},
+        {label: 'Agent text for the whole computer', code: 'const r = await init({user: true});\nfor (const w of r.data.warnings) console.warn(w);'},
   ],
   command: 'init',
   related: ['doctor', 'upgrade', 'build', 'themeTemplate'],

package/api/init/init.mjs

@@ -10,6 +10,9 @@
  *                                         install path (agent-docs, theme +
  *                                         page-building guidance, template)
  *   - `init.remove` (remove/remove.mjs) — the `--remove-agents` path
+ *   - `init.user`   (user/user.mjs)     — the `--user` path: the
+ *                                         computer-level agent text, written
+ *                                         or (with `--remove-agents`) removed
  *
  * This module also re-exports the leaf symbols the CLI + tests import by name
  * (`getNextSteps`) so api/index.mjs, the command handler
@@ -18,6 +21,7 @@
 
 import {run} from './run/run.mjs';
 import {remove} from './remove/remove.mjs';
+import {user} from './user/user.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
@@ -32,17 +36,37 @@ export {getNextSteps} from './run/run.mjs';
  */
 
 /**
- * Run the non-interactive init flow. Dispatches to the remove leaf when
- * `--remove-agents` is set, otherwise to the install (run) leaf, and returns
- * that leaf's receipt. Progress is emitted through `logger` (silent by
+ * Run the non-interactive init flow. Dispatches to the user leaf when
+ * `--user` is set (it writes, or with `--remove-agents` removes, the
+ * computer-level agent text and nothing in the folder), to the remove leaf
+ * when `--remove-agents` is set, otherwise to the install (run) leaf, and
+ * returns that leaf's receipt. Progress is emitted through `logger` (silent by
  * default); unknown feature or template names throw AstryxError with a stable
  * code.
  *
  * @param {InitOptions} [options]
  * @param {{cwd?: string}} [ctx]
- * @returns {Promise<import('./init.type.mjs').InitRunResponse | import('./init.type.mjs').InitRemoveResponse>}
+ * @returns {Promise<import('./init.type.mjs').InitRunResponse | import('./init.type.mjs').InitRemoveResponse | import('./init.type.mjs').InitUserResponse>}
  */
 export async function init(options = {}, {cwd = process.cwd()} = {}) {
+  if (options.user) {
+    // Its own path: fixed files in the home folder, never the project
+    // agent-docs resolution, so it works the same in every folder.
+    const refused = [
+      options.features ? '--features' : null,
+      options.all ? '--all' : null,
+      options.agentDocsPath ? '--agent-docs-path' : null,
+      options.agent ? '--agent' : null,
+    ].filter(Boolean);
+    if (refused.length > 0) {
+      throw new AstryxError(
+        `\`--user\` cannot be combined with ${refused.join(', ')}: it writes one skill file for every agent on the computer, linked into the folders agents read, with no features, agents, or path to choose.`,
+        undefined,
+        ERROR_CODES.ERR_INVALID_ARGUMENT,
+      );
+    }
+    return user({remove: Boolean(options.removeAgents)});
+  }
   if (options.removeAgents) {
     const ignored = [
       options.features ? '--features' : null,

package/api/init/init.test.mjs

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

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

@@ -11,11 +11,11 @@ export type InitRunData = {
      */
     features: string[];
     /**
-     * Agent-doc files written (empty if agents weren't run or install failed).
+     * Agent-doc files written, relative to the directory init ran in (empty if agents weren't run or install failed). Without --agent-docs-path they sit at the project root: the nearest folder at or above it whose package.json declares an Astryx package, else the nearest with any package.json, within its repository and never the home folder; with none, the directory init ran in.
      */
     docsWritten: string[];
     /**
-     * Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
+     * Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit. `install-failed` carries a message when init wrote no agent docs (the home folder, or a settings folder in it outside a project) or skipped a file that resolves outside the project; docsWritten then lists what was written.
      */
     docsError: {
         kind: "path-safety" | "install-failed";
@@ -42,7 +42,7 @@ export type InitRunData = {
      */
     templatePath: string | null;
     /**
-     * Whether the getting-started "Next steps" were emitted (default mode).
+     * Whether the getting-started "Next steps" were emitted (default mode inside a project; false outside one).
      */
     nextSteps: boolean;
 };
@@ -59,6 +59,47 @@ export type InitRemoveResponse = {
         removed: boolean;
     };
 };
+/**
+ * What `init --user` did with one file of the computer-level agent text.
+ * `written`: created or refreshed. `unchanged`: already this release's text.
+ * `removed`: deleted (with `--remove-agents`). `absent`: nothing to remove.
+ * `kept`: a file left as it is, because a person edited it or Astryx did not
+ * write it (see `reason`).
+ */
+export type InitUserAction = "written" | "linked" | "unchanged" | "removed" | "absent" | "kept";
+export type InitUserFile = {
+    /**
+     * Absolute path in the home folder: the skill file,
+     * or a link to its folder.
+     */
+    path: string;
+    action: InitUserAction;
+    /**
+     * Only on `kept`: `edited`, the
+     * text no longer matches the hash Astryx recorded in it; `not-astryx`, it
+     * has no Astryx markers or is a symlink, or a link target holds something
+     * Astryx did not create.
+     */
+    reason?: "edited" | "not-astryx" | undefined;
+};
+export type InitUserData = {
+    /**
+     * One row per path acted on: `~/.agents/skills/astryx/SKILL.md` first, then each link to its folder: `~/.claude/skills/astryx` always, and another agent's skills folder when that agent's folder exists (`linked`, or `unchanged` when the link is already there). Removal removes the file and the links Astryx made.
+     */
+    files: InitUserFile[];
+    /**
+     * The command the text tells agents to run: `astryx`, or the host's command when a host started the run.
+     */
+    command: string;
+    /**
+     * Non-fatal notes, such as no `astryx` on the computer that runs the Astryx CLI.
+     */
+    warnings: string[];
+};
+export type InitUserResponse = {
+    type: "init.user";
+    data: InitUserData;
+};
 /**
  * Options for `init()`.
  */
@@ -72,11 +113,15 @@ export type InitOptions = {
      */
     all?: boolean | undefined;
     /**
-     * Remove the managed agent-docs block instead of installing.
+     * Remove the managed agent-docs block, at the project root and in the folder init runs in, instead of installing; with `user`, remove the computer-level agent text.
      */
     removeAgents?: boolean | undefined;
     /**
-     * Agent preset: claude, cursor, codex, hermes, muse, all.
+     * Write the computer-level agent text (`~/.agents/skills/astryx/SKILL.md`, linked into `~/.claude/skills` and the skill folders of other installed tools, with a copy for Continue) instead of setting up the folder.
+     */
+    user?: boolean | undefined;
+    /**
+     * Agent preset: claude, cursor, codex, hermes, muse, all. Refused with `user`.
      */
     agent?: string | undefined;
     /**

package/api/init/init.type.mjs

@@ -10,14 +10,14 @@
  * @typedef {object} InitRunData
  * @property {'default' | 'features'} mode `default` (no flags) or `features` (--features/--all).
  * @property {string[]} features Features that were run, in order.
- * @property {string[]} docsWritten Agent-doc files written (empty if agents weren't run or install failed).
- * @property {{kind: 'path-safety' | 'install-failed', message?: string} | null} docsError Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
+ * @property {string[]} docsWritten Agent-doc files written, relative to the directory init ran in (empty if agents weren't run or install failed). Without --agent-docs-path they sit at the project root: the nearest folder at or above it whose package.json declares an Astryx package, else the nearest with any package.json, within its repository and never the home folder; with none, the directory init ran in.
+ * @property {{kind: 'path-safety' | 'install-failed', message?: string} | null} docsError Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit. `install-failed` carries a message when init wrote no agent docs (the home folder, or a settings folder in it outside a project) or skipped a file that resolves outside the project; docsWritten then lists what was written.
  * @property {boolean} theme Whether the theme feature ran.
  * @property {'created' | 'skipped' | 'failed' | null} themeTemplate Outcome of writing the annotated theme template (`skipped` = a file was already there).
  * @property {string | null} themeTemplatePath Relative output path when `themeTemplate === 'created'`.
  * @property {'workflow' | 'created' | 'skipped' | null} template Template outcome (`workflow` is the CLI default; `created`/`skipped` are programmatic).
  * @property {string | null} templatePath Relative output path when `template === 'created'`.
- * @property {boolean} nextSteps Whether the getting-started "Next steps" were emitted (default mode).
+ * @property {boolean} nextSteps Whether the getting-started "Next steps" were emitted (default mode inside a project; false outside one).
  */
 
 /**
@@ -32,13 +32,47 @@
  * @property {{removed: boolean}} data False when no managed agent-docs block was found, so nothing was removed.
  */
 
+/**
+ * What `init --user` did with one file of the computer-level agent text.
+ * `written`: created or refreshed. `unchanged`: already this release's text.
+ * `removed`: deleted (with `--remove-agents`). `absent`: nothing to remove.
+ * `kept`: a file left as it is, because a person edited it or Astryx did not
+ * write it (see `reason`).
+ * @typedef {'written' | 'linked' | 'unchanged' | 'removed' | 'absent' | 'kept'} InitUserAction
+ */
+
+/**
+ * @typedef {object} InitUserFile
+ * @property {string} path Absolute path in the home folder: the skill file,
+ *   or a link to its folder.
+ * @property {InitUserAction} action
+ * @property {'edited' | 'not-astryx'} [reason] Only on `kept`: `edited`, the
+ *   text no longer matches the hash Astryx recorded in it; `not-astryx`, it
+ *   has no Astryx markers or is a symlink, or a link target holds something
+ *   Astryx did not create.
+ */
+
+/**
+ * @typedef {object} InitUserData
+ * @property {InitUserFile[]} files One row per path acted on: `~/.agents/skills/astryx/SKILL.md` first, then each link to its folder: `~/.claude/skills/astryx` always, and another agent's skills folder when that agent's folder exists (`linked`, or `unchanged` when the link is already there). Removal removes the file and the links Astryx made.
+ * @property {string} command The command the text tells agents to run: `astryx`, or the host's command when a host started the run.
+ * @property {string[]} warnings Non-fatal notes, such as no `astryx` on the computer that runs the Astryx CLI.
+ */
+
+/**
+ * @typedef {object} InitUserResponse
+ * @property {'init.user'} type
+ * @property {InitUserData} data
+ */
+
 /**
  * Options for `init()`.
  * @typedef {object} InitOptions
  * @property {string} [features] Comma-separated features to install (agents, theme, template).
  * @property {boolean} [all] Install all features.
- * @property {boolean} [removeAgents] Remove the managed agent-docs block instead of installing.
- * @property {string} [agent] Agent preset: claude, cursor, codex, hermes, muse, all.
+ * @property {boolean} [removeAgents] Remove the managed agent-docs block, at the project root and in the folder init runs in, instead of installing; with `user`, remove the computer-level agent text.
+ * @property {boolean} [user] Write the computer-level agent text (`~/.agents/skills/astryx/SKILL.md`, linked into `~/.claude/skills` and the skill folders of other installed tools, with a copy for Continue) instead of setting up the folder.
+ * @property {string} [agent] Agent preset: claude, cursor, codex, hermes, muse, all. Refused with `user`.
  * @property {string | string[]} [agentDocsPath] Explicit agent-docs file path(s).
  * @property {string} [templateName] Scaffold a named page template (programmatic only; the CLI never sets it).
  */

package/api/init/remove/remove.mjs

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