@astryxdesign/cli 0.7.2 → 0.7.3-canary.04c7468

package/clients/cli/commands/import-hint-correctness.test.mjs

@@ -21,7 +21,7 @@ import {
   resolveImportPath,
   discoverComponents,
   findComponentSource,
-} from './component/index.mjs';
+} from './component.mjs';
 import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 

package/clients/cli/commands/init.behavior.test.mjs

@@ -70,10 +70,12 @@ describe('astryx init — default (no flags)', () => {
 });
 
 describe('astryx init --features', () => {
-  it('--features agents writes AGENTS.md only', async () => {
+  it('--features agents writes AGENTS.md and the GEMINI.md import of it', async () => {
     const {status} = await runCli(['init', '--features', 'agents'], {cwd: tmpDir});
     expect(status).toBe(0);
     expect(exists('AGENTS.md')).toBe(true);
+    expect(read('GEMINI.md')).toBe(`${MARKER_START}\n@./AGENTS.md\n<!-- ASTRYX:END -->\n`);
+    expect(exists('theme.template.ts')).toBe(false);
   });
 
   it('--features theme writes the annotated theme template', async () => {
@@ -126,7 +128,234 @@ describe('astryx init --agent <preset>', () => {
   });
 });
 
+describe('astryx init from a subfolder', () => {
+  /** @param {string} dir */
+  const astryxProject = dir =>
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+
+  it('writes the agent docs at the project root and reports them from where it ran', async () => {
+    astryxProject(tmpDir);
+    const sub = path.join(tmpDir, 'src', 'app');
+    fs.mkdirSync(sub, {recursive: true});
+
+    const json = await runCli(['init', '--json'], {cwd: sub});
+    expect(json.status).toBe(0);
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual([
+      '../../AGENTS.md',
+      '../../GEMINI.md',
+    ]);
+    expect(read('AGENTS.md')).toContain(MARKER_START);
+    expect(fs.readdirSync(sub)).toEqual([]);
+  });
+
+  it('keeps --agent-docs-path relative to where it ran', async () => {
+    astryxProject(tmpDir);
+    const sub = path.join(tmpDir, 'docs');
+    fs.mkdirSync(sub);
+
+    const json = await runCli(['init', '--agent-docs-path', 'AI.md', '--json'], {cwd: sub});
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual(['AI.md']);
+    expect(fs.readFileSync(path.join(sub, 'AI.md'), 'utf8')).toContain(MARKER_START);
+    expect(exists('AGENTS.md')).toBe(false);
+  });
+});
+
+describe('astryx init in the home folder', () => {
+  const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+  const personal = '# My notes\n\nAlways use tabs.\n';
+
+  beforeEach(() => {
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    fs.mkdirSync(path.join(tmpDir, '.claude'), {recursive: true});
+    fs.writeFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), personal);
+  });
+  afterEach(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+
+  it('writes no agent docs, says why, and keeps the soft-failure exit code', async () => {
+    const json = await runCli(['init', '--json'], {cwd: tmpDir});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual([]);
+    expect(env.data.docsError).toEqual({
+      kind: 'install-failed',
+      message: expect.stringMatching(/not written into the home folder/),
+    });
+
+    const text = await runCli(['init'], {cwd: tmpDir});
+    expect(text.status).toBe(0);
+    expect(text.stderr).toMatch(/not written into the home folder/);
+    expect(text.stderr).not.toMatch(/Error:/);
+
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+    expect(fs.readdirSync(tmpDir)).toEqual(['.claude']);
+  });
+
+  it('does not let a package.json in the home folder pull the docs there', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const scratch = path.join(tmpDir, 'scratch');
+    fs.mkdirSync(scratch);
+
+    const json = await runCli(['init', '--json'], {cwd: scratch});
+    expect(json.status).toBe(0);
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.existsSync(path.join(scratch, 'AGENTS.md'))).toBe(true);
+    expect(exists('AGENTS.md')).toBe(false);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+
+  it('--remove-agents in a folder in home never reaches the home folder', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, '.claude', 'CLAUDE.md'),
+      `${personal}\n<!-- ASTRYX:START -->\nAstryx v0.7.0\n<!-- ASTRYX:END -->\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const scratch = path.join(tmpDir, 'scratch');
+    fs.mkdirSync(scratch);
+
+    const json = await runCli(['init', '--remove-agents', '--json'], {cwd: scratch});
+    expect(JSON.parse(json.stdout).data.removed).toBe(false);
+    expect(read('.claude/CLAUDE.md')).toContain('<!-- ASTRYX:START -->');
+
+    // Run in the home folder itself, it still removes the block there.
+    const home = await runCli(['init', '--remove-agents', '--json'], {cwd: tmpDir});
+    expect(JSON.parse(home.stdout).data.removed).toBe(true);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+
+  it.each(['.gemini', '.claude'])('refuses the settings folder ~/%s', async folder => {
+    const dir = path.join(tmpDir, folder);
+    fs.mkdirSync(dir, {recursive: true});
+    const before = fs.readdirSync(dir);
+
+    const json = await runCli(['init', '--json'], {cwd: dir});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual([]);
+    expect(env.data.docsError.message).toMatch(/settings folder in it outside a project/);
+    expect(fs.readdirSync(dir)).toEqual(before);
+    expect(read('.claude/CLAUDE.md')).toBe(personal);
+  });
+});
+
+describe('astryx init in an agent worktree inside a home settings folder', () => {
+  const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+
+  beforeEach(() => {
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+  });
+  afterEach(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+
+  it.each([
+    ['Codex', path.join('.codex', 'worktrees', 'a1b2c3', 'web')],
+    ['Cursor', path.join('.cursor', 'worktrees', 'web', 'x9y8')],
+  ])('writes at the project root of a %s worktree', async (_tool, rel) => {
+    const project = path.join(tmpDir, rel);
+    fs.mkdirSync(path.join(project, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(project, '.git'), 'gitdir: /elsewhere/.git/worktrees/web\n');
+    fs.writeFileSync(
+      path.join(project, 'package.json'),
+      JSON.stringify({name: 'web', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+
+    const json = await runCli(['init', '--json'], {cwd: path.join(project, 'src')});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual(['../AGENTS.md', '../GEMINI.md']);
+    expect(env.data.docsError).toBeNull();
+
+    const explicit = await runCli(['init', '--agent-docs-path', 'AI.md', '--json'], {
+      cwd: path.join(project, 'src'),
+    });
+    expect(JSON.parse(explicit.stdout).data.docsWritten).toEqual(['AI.md']);
+
+    // Nothing reaches the settings folder itself.
+    const settings = path.join(tmpDir, rel.split(path.sep)[0]);
+    expect(fs.readdirSync(settings)).toEqual(['worktrees']);
+  });
+});
+
+describe('astryx init and the project root', () => {
+  it('writes where it runs when no folder above has a package.json, as before', async () => {
+    const notes = path.join(tmpDir, 'notes');
+    fs.mkdirSync(notes);
+
+    const json = await runCli(['init', '--json'], {cwd: notes});
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.docsWritten).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(env.data.docsError).toBeNull();
+    expect(fs.readdirSync(notes).sort()).toEqual(['AGENTS.md', 'GEMINI.md']);
+    expect(fs.readdirSync(tmpDir)).toEqual(['notes']);
+  });
+
+  it('writes at the project root that declares Astryx, past a nested package that does not', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const functions = path.join(tmpDir, 'functions');
+    fs.mkdirSync(path.join(functions, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(functions, 'package.json'), '{"name":"functions"}\n');
+
+    const json = await runCli(['init', '--json'], {cwd: path.join(functions, 'src')});
+    expect(JSON.parse(json.stdout).data.docsWritten).toEqual([
+      '../../AGENTS.md',
+      '../../GEMINI.md',
+    ]);
+    expect(fs.readdirSync(functions).sort()).toEqual(['package.json', 'src']);
+  });
+});
+
 describe('astryx init --remove-agents', () => {
+  it('run in a subfolder, removes what init wrote at the project root, with the same JSON shape', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'app', dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    const sub = path.join(tmpDir, 'src', 'app');
+    fs.mkdirSync(sub, {recursive: true});
+    await runCli(['init'], {cwd: sub});
+    expect(exists('AGENTS.md')).toBe(true);
+
+    const text = await runCli(['init', '--remove-agents'], {cwd: sub});
+    expect(text.status).toBe(0);
+    expect(text.stdout).toMatch(/Removed empty \.\.\/\.\.\/AGENTS\.md/);
+    expect(exists('AGENTS.md')).toBe(false);
+    expect(exists('GEMINI.md')).toBe(false);
+
+    await runCli(['init'], {cwd: sub});
+    const json = await runCli(['init', '--remove-agents', '--json'], {cwd: sub});
+    expect(json.status).toBe(0);
+    // meta.answeredBy names the release that answered (spec AST-081).
+    expect(JSON.parse(json.stdout)).toEqual({
+      apiVersion: 1,
+      type: 'init.remove',
+      data: {removed: true},
+      meta: {answeredBy: expect.any(Object)},
+    });
+  });
+
   it('removes the Astryx section it previously installed', async () => {
     await runCli(['init', '--features', 'agents'], {cwd: tmpDir});
     expect(exists('AGENTS.md')).toBe(true);

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

@@ -16,10 +16,24 @@ export const doc = {
   summary: 'Initialize the design system in your project',
   description:
     'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +
-    'agents, and CI). By default it installs the AGENTS.md/CLAUDE.md agent-docs, ' +
-    'including guidance from configured integrations, and prints getting-started ' +
-    "steps. --features and --all print only the chosen features' guidance (no " +
-    'getting-started steps); the theme feature also writes an annotated theme template. ' +
+    'agents, and CI). By default it writes the agent-docs block, including guidance ' +
+    'from configured integrations, to AGENTS.md and to the Claude Code file the project ' +
+    'has (CLAUDE.md, else .claude/CLAUDE.md; when CLAUDE.md exists, a block in ' +
+    '.claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a .claude/CLAUDE.md the ' +
+    'project commits keeps a copy), and a one-line import of AGENTS.md to GEMINI.md ' +
+    'unless GEMINI.md already imports it. It then prints getting-started steps. Agent ' +
+    'docs go to the project root: the nearest folder at or above this one whose ' +
+    'package.json declares an @astryxdesign package, else the nearest with any ' +
+    'package.json, else this folder. The search stops at a repository root and never ' +
+    'counts the home folder. In the home folder, or in a settings folder in it ' +
+    'such as ~/.gemini outside a project, no agent docs are written. Every folder of the ' +
+    'home folder whose name starts with a dot is a settings folder, and such a folder ' +
+    'itself never counts as a project, even with a package.json; a project inside one, ' +
+    'such as an agent worktree with its own package.json, works. The managed block is ' +
+    'written whatever ignore rules or generated markers say; the text around it is never changed. ' +
+    '--features and --all print only ' +
+    "the chosen features' " +
+    'guidance (no getting-started steps); the theme feature also writes an annotated theme template. ' +
     'Outside a project it writes the same files but prints no step that sets up a project: ' +
     'no getting-started steps, and no step that adds a theme to an app. ' +
         '--user writes the computer-level agent text instead (see the flag), in any folder, and touches nothing in the folder. ' +
@@ -44,8 +58,10 @@ export const doc = {
       flag: '--remove-agents',
       param: 'options.removeAgents',
       description:
-        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules, .hermes.md and HERMES.md ' +
-        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left) and do nothing else. " +
+        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md and HERMES.md, ' +
+        'at the project root (where init writes them) and in this folder ' +
+        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left, and GEMINI.md when nothing is left) and do nothing else. " +
+        'Below the project root, a project-root agent file whose block resolves outside the project is left as it is, with a note. ' +
         '--features, --all, --agent and --agent-docs-path are refused; a file written with --agent-docs-path keeps its block',
     },
     {
@@ -66,7 +82,9 @@ export const doc = {
       choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
       description:
         'Target AI tool for agent docs: claude (CLAUDE.md or .claude/CLAUDE.md, else creates .claude/CLAUDE.md), cursor (.cursorrules if present, else AGENTS.md), ' +
-        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc, else AGENTS.md and .claude/CLAUDE.md). ' +
+        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc except GEMINI.md, which keeps its ' +
+        'one-line import of AGENTS.md, else AGENTS.md and .claude/CLAUDE.md). With claude and all, when CLAUDE.md gets the block, .claude/CLAUDE.md gets none and ' +
+        'a block already there is removed, unless the project ignores CLAUDE.md: then a .claude/CLAUDE.md the project commits gets a copy too, with claude and all alike. ' +
         'An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
                 'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence.',
     },
@@ -76,6 +94,7 @@ export const doc = {
       description:
         'Explicit file path(s) for agent docs, inside the project; takes precedence over --agent. ' +
         'If any path is outside the project, no agent docs are written and the command exits 1. ' +
+        'A path in the home folder itself, or in a settings folder in it outside a project (such as ~/.claude or ~/.claude/hooks), is refused with a note (exit 0), and nothing is written. ' +
         'Used only when agent docs are installed',
     },
   ],
@@ -90,11 +109,11 @@ export const doc = {
   exitCodes: [
     {
       code: 0,
-      when: 'success, including agent docs that could not be written for a reason other than a path escape (reported as docsError)',
+      when: "success, including agent docs left unwritten in five soft cases, each reported as docsError with one note: running in the home folder, or in a settings folder in it outside a project; a GEMINI.md that resolves outside the project; when init runs below the project root, a project-root agent file that resolves outside the project; the project's Claude Code file (root CLAUDE.md, or .claude/CLAUDE.md when there is no root one) when it resolves outside the project and is a block-less import of an existing AGENTS.md, which 0.7.1 left alone; and a .claude/CLAUDE.md that resolves outside the project and that 0.7.1 did not write: beside a CLAUDE.md the project ignores, the one --agent claude adds or a block-less import of an existing AGENTS.md; with --agent claude beside a CLAUDE.md, one whose block it would remove",
     },
     {
       code: 1,
-            when: 'an unknown --agent (ERR_UNKNOWN_AGENT) or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, --user combined with --features, --all, --agent or --agent-docs-path, or --all with --features (ERR_INVALID_ARGUMENT)',
+      when: 'an unknown --agent (ERR_UNKNOWN_AGENT) or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, --user combined with --features, --all, --agent or --agent-docs-path, or --all with --features (ERR_INVALID_ARGUMENT); or, when init runs at the project root, an agent file 0.7.1 also wrote there that resolves outside the project (ERR_PATH_TRAVERSAL, docsError path-safety, nothing written)',
     },
   ],
   related: ['doctor', 'upgrade', 'build', 'theme'],

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

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

package/clients/cli/commands/init.mjs

@@ -3,8 +3,8 @@
 /**
  * @file init command — thin wrapper around the init API.
  *
- * `astryx init` is non-interactive by default: it installs the AGENTS.md/
- * CLAUDE.md cheat sheet with NO prompts, so it behaves identically for humans,
+ * `astryx init` is non-interactive by default: it installs the agent-docs
+ * cheat sheet with NO prompts, so it behaves identically for humans,
  * AI agents, CI, and piped I/O — it never hangs or errors on a missing TTY.
  * Non-interactive feature install: `astryx init --features agents,theme,template`
  * Re-runnable: safe to run multiple times, idempotent.

package/clients/cli/commands/integration-check.test.mjs

@@ -439,3 +439,51 @@ describe('a stray doc pointer', () => {
     expect(strict.stdout).toContain('stray_doc_pointer');
   });
 });
+describe('a command written with a runner', () => {
+  it('is a note in doctor integration validate, and integration check --strict still passes', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3'}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      `export default {docs: './docs'};\n`,
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    const doc = {
+      type: 'generic',
+      name: 'acme-setup',
+      title: 'Fixture',
+      description: 'Fixture topic.',
+      sections: [
+        {
+          title: 'Overview',
+          content: [{type: 'code', lang: 'bash', code: 'npx astryx doctor'}],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+
+    const doctor = await runCli(['doctor', 'integration', 'validate'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain(
+      'note (runner_command): docs/acme-setup.doc.mjs:',
+    );
+    expect(doctor.stdout).toContain('Write `astryx doctor`');
+
+    const strict = await runCli(
+      ['--json', 'integration', 'check', '--strict'],
+      tmpDir,
+    );
+    expect(strict.status).toBe(0);
+    const validate = JSON.parse(strict.stdout).data.checks.find(
+      (/** @type {any} */ each) => each.check === 'validate',
+    ).response.data;
+    expect(validate.notes.map((/** @type {any} */ note) => note.code)).toEqual([
+      'runner_command',
+    ]);
+  });
+});

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

@@ -8,7 +8,7 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Author and verify an Astryx integration package',
   description:
-    'Add contributions to your package, check them on every build with `integration check --strict`, then check the packed package the way an app receives it. The guides start at {@link namespace:integrations}.',
+    'Add contributions to your package, check them on every build with `integration check --strict`, then check the packed package the way an app receives it. The guides start at {@link namespace:authoring}.',
   subcommands: ['add', 'check', 'verify', 'pack'],
   examples: [
     {

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

@@ -13,7 +13,7 @@ export const doc = {
   name: 'manifest',
   displayName: 'astryx manifest',
   namespace: 'cli/commands',
-  summary: 'Print the full CLI capability manifest (use with --json).',
+  summary: 'Print the full CLI capability manifest (use with --json)',
   description:
     'Emits the complete CLI surface: every command with its arguments, options, ' +
     'subcommands, and JSON response types, as a single typed envelope for agents and ' +

package/clients/cli/commands/manifest.mjs

@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file manifest command — `astryx manifest`, the CLI capability manifest.
+ *
+ * A single, self-describing view of the whole CLI so agents can discover every
+ * command, argument, flag, and response type without scraping `--help`.
+ * `astryx manifest --json` is the dedicated surface; the bare `astryx --json`
+ * embeds the same payload under data.manifest for convenience.
+ *
+ * Intentionally CLI-special — no `api/manifest`. It introspects the live
+ * Commander `program`, so extracting it to `api/` would create an `api → cli`
+ * cycle. `buildManifest(program)` lives in lib/; see its header. Register it
+ * after every other command: the manifest lists commands in registration order.
+ *
+ * The command surface comes from the colocated CommandDoc via `defineCommand`.
+ */
+
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, records} from '../formatters/index.mjs';
+import {buildManifest} from '../lib/manifest.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
+import {doc as manifestCommand} from './manifest.doc.mjs';
+
+/**
+ * @param {import('commander').Command} program the root program
+ * @param {{jsonSupported: Set<string>, version: string}} context the commands
+ *   that accept --json, and the CLI's version
+ */
+export function registerManifest(program, {jsonSupported, version}) {
+  defineCommand(program, manifestCommand, {
+    action: () => {
+      const manifest = buildManifest(program, {jsonSupported, version});
+      // The manifest IS a result set: one entry per command the CLI ships.
+      const answered = resultSet({
+        count: manifest.commands.length,
+        resultKind: 'command',
+      });
+      if (program.opts().json) {
+        jsonOut({type: 'manifest', data: manifest});
+        return answered;
+      }
+      // Human-readable summary as greppable records (agents should use --json).
+      // One record per command: name, whether it supports --json, and the
+      // description. Field names are the manifest entry's own keys.
+      emit(
+        section(
+          `${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`,
+        ),
+        records(
+          manifest.commands.map(c => ({
+            name: c.name,
+            json: c.json ? 'yes' : '',
+            description: c.description || '',
+          })),
+          {fields: ['name', 'json', 'description']},
+        ),
+        text(
+          `Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`,
+        ),
+      );
+      return answered;
+    },
+  });
+}

package/clients/cli/commands/outside-project.test.mjs

@@ -392,6 +392,97 @@ describe('doctor: the computer-level agent text', () => {
   const A = '/home/me/.agents/skills/astryx/SKILL.md';
   const C = '/home/me/.claude/skills/astryx';
 
+  it('a skill naming `astryx` with no Astryx CLI on the search path: says whether it is current, and names the step it records', () => {
+    const check = (/** @type {Record<string, any>} */ over) =>
+      checkComputerAgentText({
+        nodeVersion: '22.13.0',
+        answeredBy: {cli: '1.2.0', core: '1.2.0', copy: 'carried'},
+        latest: null,
+        agentText: [{path: A, state: 'current'}],
+        agentTextCommand: 'astryx',
+        searchPathCommands: [],
+        cwd: os.tmpdir(),
+        ...over,
+      });
+    const recorded = check({agentTextInstall: 'pnpm add -g @astryxdesign/cli'});
+    // A package runner's own copy first on the search path does not count.
+    expect(
+      check({
+        agentTextInstall: 'pnpm add -g @astryxdesign/cli',
+        searchPathCommands: [
+          /** @type {any} */ ({
+            file: '/tmp/_npx/r/node_modules/.bin/astryx',
+            astryx: true,
+            runner: true,
+          }),
+        ],
+      }).fix,
+    ).toBe(
+      'Run `pnpm add -g @astryxdesign/cli`, the step the skill names for when `astryx` is not found.',
+    );
+    expect(recorded.status).toBe('info');
+    expect(recorded.message).toContain(
+      `The computer-level agent text matches this release: ${A}. It tells agents to run \`astryx\`, but no \`astryx\` command is on the search path`,
+    );
+    expect(recorded.fix).toBe(
+      'Run `pnpm add -g @astryxdesign/cli`, the step the skill names for when `astryx` is not found.',
+    );
+    // A skill from an earlier release records no step: npm's, worded as
+    // cli-on-path words it.
+    const older = check({
+      agentText: [{path: A, state: 'differs'}],
+      agentTextInstall: null,
+    });
+    expect(older.message).toContain(
+      "The computer-level agent text differs from this release's",
+    );
+    expect(older.fix).toBe(
+      'Install it for the computer: `npm i -g @astryxdesign/cli`.',
+    );
+    // With the Astryx CLI anywhere on the search path, even behind another
+    // program (cli-on-path's to report), or a skill naming a host's command,
+    // there is nothing to restore.
+    for (const over of [
+      {
+        searchPathCommands: [
+          /** @type {any} */ ({
+            file: '/usr/bin/astryx',
+            astryx: true,
+            version: '1.2.0',
+          }),
+        ],
+      },
+      {
+        searchPathCommands: [
+          /** @type {any} */ ({file: '/opt/other/astryx', astryx: false}),
+          /** @type {any} */ ({
+            file: '/usr/bin/astryx',
+            astryx: true,
+            version: '1.2.0',
+          }),
+        ],
+      },
+      {agentTextCommand: 'acme astryx'},
+      // An `astryx` the scan cannot trace (a Volta, asdf or mise shim, or
+      // another program): it may run the CLI, so no report here.
+      {
+        searchPathCommands: [
+          /** @type {any} */ ({
+            file: '/home/me/.volta/bin/astryx',
+            astryx: false,
+            runner: false,
+          }),
+        ],
+      },
+      // Only a package runner's own copy: the CLI is still gone.
+    ]) {
+      const other = check(over);
+      expect(other.message).toBe(
+        `The computer-level agent text matches this release: ${A}.`,
+      );
+    }
+  });
+
   it('present and current, linked: no fix', () => {
     const check = at([
       {path: A, state: 'current'},
@@ -460,6 +551,14 @@ describe('doctor: the computer-level agent text', () => {
       const home = tmpDir('home');
       vi.stubEnv('HOME', home);
       vi.stubEnv('USERPROFILE', home);
+      // The CLI installed for the computer, first on the search path, as the
+      // skill expects.
+      const bin = tmpDir('bin');
+      fs.symlinkSync(
+        path.join(CLI_ROOT, 'clients', 'cli', 'bin', 'astryx.mjs'),
+        path.join(bin, 'astryx'),
+      );
+      vi.stubEnv('PATH', `${bin}${path.delimiter}${process.env.PATH ?? ''}`);
       try {
         const find = r =>
           r.envelope.data.checks.find(c => c.id === 'computer-agent-text');
@@ -541,7 +640,8 @@ describe('init outside a project (own)', () => {
       const dir = tmpDir('init');
       const json = await answer(['--json', 'init'], dir);
       expect(json.status).toBe(0);
-      expect(json.written).toEqual(['AGENTS.md']);
+      // GEMINI.md gets its one-line import of AGENTS.md (spec cli-surface INV31).
+      expect(json.written).toEqual(['AGENTS.md', 'GEMINI.md']);
       expect(json.envelope.data.nextSteps).toBe(false);
       const text = await runCli(['init'], tmpDir('init-text'));
       expect(text.stdout).not.toContain('Next steps');

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

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx postinstall`. A hidden, CLI-only hook with no
+ * wrapped API function (so no `fn`): it prints the welcome box.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'postinstall',
+  displayName: 'astryx postinstall',
+  namespace: 'cli/commands',
+  summary: 'Print the welcome message shown after install',
+  description:
+    'Prints a short welcome box that names the first commands to run. It is hidden ' +
+    'from help and the manifest, looks nothing up, and does not support --json.',
+  examples: [{label: 'Print the welcome box', cli: 'astryx postinstall'}],
+  outsideProject: 'same',
+  exitCodes: [{code: 0, when: 'success'}],
+  related: ['init'],
+};