@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

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

@@ -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,

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

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

@@ -17,7 +17,7 @@
  * @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 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/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

@@ -19,6 +19,7 @@ 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 {
   installAgentDocs,
   renderAgentDocsBlock,
@@ -39,7 +40,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 +51,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.`,
@@ -140,8 +141,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 +280,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 +295,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>;