@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/api/gap-report/gap-report.test.mjs

@@ -7,6 +7,7 @@ import * as path from 'node:path';
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
 import {Project} from '../../foundation/config/project.mjs';
 import {
+  ASK_DESTINATION_MESSAGE,
   GAP_REPORT_CATEGORIES,
   PUBLIC_CONFIRMATION_MESSAGE,
   collectGapReportHandlers,
@@ -1022,6 +1023,238 @@ console.log('https://github.com/acme/widgets/issues/42');
   });
 });
 
+describe('gapReport destinations and --to', () => {
+  /** A shared internal handler that records each call in a marker file. */
+  function addSharedHandler() {
+    const marker = path.join(projectDir, 'shared-called');
+    addIntegration({
+      name: '@test/shared',
+      audience: 'internal',
+      handleBody: `(await import('node:fs')).writeFileSync(${JSON.stringify(marker)}, 'x'); return {status: 'filed', message: 'shared'};`,
+    });
+    return marker;
+  }
+
+  function addWidgets(issuesUrl = 'https://github.com/acme/widgets/issues') {
+    addIntegration({name: '@test/widgets', handler: false, issuesUrl});
+  }
+
+  it('keeps the default route and lists the destinations with the ask line', async () => {
+    const marker = addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+    const argsFile = stubGh();
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      confirmPublic: true,
+      cwd: projectDir,
+    });
+
+    expect(result.data.deliveries).toEqual([
+      expect.objectContaining({handler: '@test/shared', status: 'filed'}),
+    ]);
+    expect(fs.existsSync(marker)).toBe(true);
+    expect(fs.existsSync(argsFile)).toBe(false);
+    expect(result.data.destinations).toEqual([
+      {to: null, default: true, issuesUrl: null},
+      {
+        to: '@test/widgets',
+        default: false,
+        issuesUrl: 'https://github.com/acme/widgets/issues',
+      },
+    ]);
+    expect(result.data.ask).toBe(ASK_DESTINATION_MESSAGE);
+    expect(ASK_DESTINATION_MESSAGE).toMatch(/ask the person/i);
+  });
+
+  it('lists no destinations when no integration names an issuesUrl', async () => {
+    addSharedHandler();
+    configure(['@test/shared']);
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      cwd: projectDir,
+    });
+
+    expect(result.data).not.toHaveProperty('destinations');
+    expect(result.data).not.toHaveProperty('ask');
+  });
+
+  it('files with the chosen integration GitHub issuesUrl only with consent, and runs no handler', async () => {
+    const marker = addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+    const argsFile = stubGh();
+
+    const pending = await gapReport('General', {
+      ...reportOptions,
+      to: '@test/widgets',
+      cwd: projectDir,
+    });
+    expect(pending.data.deliveries).toEqual([
+      {
+        handlerType: 'fallback',
+        handler: 'github',
+        audience: 'public',
+        status: 'consent_required',
+        url: null,
+        message: PUBLIC_CONFIRMATION_MESSAGE,
+      },
+    ]);
+    expect(pending.data.issuesUrl).toBe(
+      'https://github.com/acme/widgets/issues',
+    );
+    expect(pending.data).not.toHaveProperty('destinations');
+    expect(fs.existsSync(argsFile)).toBe(false);
+
+    const filed = await gapReport('General', {
+      ...reportOptions,
+      to: '@test/widgets',
+      confirmPublic: true,
+      cwd: projectDir,
+    });
+    expect(filed.data.deliveries).toHaveLength(1);
+    expect(filed.data.deliveries[0]).toMatchObject({
+      handlerType: 'fallback',
+      handler: 'github',
+      status: 'filed',
+    });
+    const args = JSON.parse(fs.readFileSync(argsFile, 'utf8'));
+    expect(args.slice(0, 4)).toEqual([
+      'issue',
+      'create',
+      '--repo',
+      'acme/widgets',
+    ]);
+    expect(fs.existsSync(marker)).toBe(false);
+  });
+
+  it('routes a chosen non-GitHub issuesUrl as routed_only', async () => {
+    addSharedHandler();
+    addWidgets('https://tracker.example/widgets');
+    configure(['@test/shared', '@test/widgets']);
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      to: '@test/widgets',
+      cwd: projectDir,
+    });
+
+    expect(result.data.deliveries).toEqual([
+      expect.objectContaining({
+        handlerType: 'fallback',
+        handler: 'issuesUrl',
+        status: 'routed_only',
+        url: 'https://tracker.example/widgets',
+      }),
+    ]);
+    expect(result.data.status).toBe('routed_only');
+  });
+
+  it.each([
+    ['a package that is not loaded', '@test/nope'],
+    ['a loaded integration without an issuesUrl', '@test/shared'],
+  ])(
+    'refuses --to naming %s, lists the choices, and sends nothing',
+    async (_label, to) => {
+      const marker = addSharedHandler();
+      addWidgets();
+      configure(['@test/shared', '@test/widgets']);
+
+      await expect(
+        gapReport('General', {...reportOptions, to, cwd: projectDir}),
+      ).rejects.toMatchObject({
+        code: 'ERR_UNKNOWN_PACKAGE',
+        suggestions: [
+          {
+            name: '@test/widgets',
+            reason: 'https://github.com/acme/widgets/issues',
+          },
+        ],
+      });
+      expect(fs.existsSync(marker)).toBe(false);
+    },
+  );
+
+  it.each([
+    ['an empty value', ''],
+    ['a blank value', '   '],
+    ['an over-long value', `@test/${'a'.repeat(300)}`],
+  ])('refuses %s for --to with the destination list', async (_label, to) => {
+    const marker = addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+
+    await expect(
+      gapReport('General', {...reportOptions, to, cwd: projectDir}),
+    ).rejects.toMatchObject({
+      code: 'ERR_UNKNOWN_PACKAGE',
+      suggestions: [{name: '@test/widgets'}],
+    });
+    expect(fs.existsSync(marker)).toBe(false);
+  });
+
+  it('treats to: null as absent', async () => {
+    const marker = addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+
+    const result = await gapReport('General', {
+      ...reportOptions,
+      to: /** @type {any} */ (null),
+      cwd: projectDir,
+    });
+
+    expect(result.data.deliveries).toHaveLength(1);
+    expect(fs.existsSync(marker)).toBe(true);
+    expect(result.data.destinations).toHaveLength(2);
+  });
+
+  it('lists the destinations with the categories', async () => {
+    addSharedHandler();
+    addWidgets();
+    configure(['@test/shared', '@test/widgets']);
+
+    const listed = await gapReport(undefined, {
+      listCategories: true,
+      cwd: projectDir,
+    });
+
+    expect(listed.data).toEqual(GAP_REPORT_CATEGORIES);
+    expect(listed.meta).toEqual({
+      destinations: [
+        {to: null, default: true, issuesUrl: null},
+        {
+          to: '@test/widgets',
+          default: false,
+          issuesUrl: 'https://github.com/acme/widgets/issues',
+        },
+      ],
+      ask: ASK_DESTINATION_MESSAGE,
+    });
+  });
+
+  it('adds no meta to the categories when there is only the default', async () => {
+    configure([]);
+    const listed = await gapReport(undefined, {
+      listCategories: true,
+      cwd: projectDir,
+    });
+    expect(listed).not.toHaveProperty('meta');
+  });
+
+  it('refuses --to with --list-categories', async () => {
+    await expect(
+      gapReport(undefined, {
+        listCategories: true,
+        to: '@test/widgets',
+        cwd: projectDir,
+      }),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+  });
+});
+
 describe('gapReport target selection', () => {
   it('routes to the unique component owner', async () => {
     addIntegration({

package/api/gap-report/gap-report.type.d.mts

@@ -35,10 +35,42 @@ export type GapReportOptions = {
      * Return the category vocabulary without routing or writing.
      */
     listCategories?: boolean | undefined;
+    /**
+     * A destination the person chose: a loaded integration
+     * whose manifest names an issues URL. The report goes only there.
+     */
+    to?: string | undefined;
+};
+/**
+ * Where a report can go. The default entry (`to: null`) is the configured
+ * handlers, or with none the owning package's issues URL.
+ */
+export type GapReportDestination = {
+    /**
+     * The value to pass as `to`; null for the default.
+     */
+    to: string | null;
+    /**
+     * Whether this is the default destination.
+     */
+    default: boolean;
+    /**
+     * The integration's issues URL; null for the
+     * default.
+     */
+    issuesUrl: string | null;
 };
 export type GapReportCategoriesResponse = {
     type: "gap-report.categories";
     data: GapReportCategoryEntry[];
+    /**
+     * Present when a destination besides the default exists: every destination,
+     * and the line telling an agent to ask the person.
+     */
+    meta?: {
+        destinations: GapReportDestination[];
+        ask: string;
+    } | undefined;
 };
 export type GapReportAggregateStatus = "filed" | "partial" | "failed" | "routed_only" | "consent_required" | "skipped";
 export type GapReportDeliveryStatus = "filed" | "routed_only" | "skipped" | "failed" | "consent_required";
@@ -81,6 +113,15 @@ export type GapReportReceipt = {
      * Count of handlers that routed only.
      */
     routedOnlyCount: number;
+    /**
+     * For a run without `to`,
+     * when a destination besides the default exists: every destination.
+     */
+    destinations?: GapReportDestination[] | undefined;
+    /**
+     * With `destinations`: ask the person where to file.
+     */
+    ask?: string | undefined;
 };
 export type GapReportReceiptResponse = {
     type: "gap-report.file";

package/api/gap-report/gap-report.type.mjs

@@ -23,12 +23,27 @@
  * @property {string} [package] Explicit owner package for ambiguous routes.
  * @property {boolean} [confirmPublic] Explicit consent for public handlers or GitHub issue creation.
  * @property {boolean} [listCategories] Return the category vocabulary without routing or writing.
+ * @property {string} [to] A destination the person chose: a loaded integration
+ *   whose manifest names an issues URL. The report goes only there.
+ */
+
+/**
+ * Where a report can go. The default entry (`to: null`) is the configured
+ * handlers, or with none the owning package's issues URL.
+ * @typedef {object} GapReportDestination
+ * @property {string|null} to The value to pass as `to`; null for the default.
+ * @property {boolean} default Whether this is the default destination.
+ * @property {string|null} issuesUrl The integration's issues URL; null for the
+ *   default.
  */
 
 /**
  * @typedef {object} GapReportCategoriesResponse
  * @property {'gap-report.categories'} type
  * @property {GapReportCategoryEntry[]} data
+ * @property {{destinations: GapReportDestination[], ask: string}} [meta]
+ *   Present when a destination besides the default exists: every destination,
+ *   and the line telling an agent to ask the person.
  */
 
 /**
@@ -58,6 +73,9 @@
  * @property {GapReportDelivery[]} deliveries Ordered handler outcomes.
  * @property {number} filedCount Count of handlers that filed the report.
  * @property {number} routedOnlyCount Count of handlers that routed only.
+ * @property {GapReportDestination[]} [destinations] For a run without `to`,
+ *   when a destination besides the default exists: every destination.
+ * @property {string} [ask] With `destinations`: ask the person where to file.
  */
 
 /**

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/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/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

@@ -21,10 +21,14 @@ export const doc = {
     'agent-docs cheat sheet, including guidance from configured integrations, and ' +
     "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 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 +45,24 @@ 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 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. Used only when the agents feature runs. Refused with `user`.',
     },
     {
       name: 'options.agentDocsPath',
@@ -71,22 +86,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',
@@ -109,6 +129,7 @@ export const doc = {
     {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,