@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/clients/cli/commands/gap-report.doc.mjs

@@ -16,6 +16,8 @@ export const doc = {
     'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability to the package that owns it: the --package you name, else the integration whose component replaces it, else the one package that provides the component, else Core. ' +
     'Every configured handler receives the report: the project config handler first, then each integration handler in config order. Public handlers run only with --confirm-public; internal handlers always run. A failing handler does not stop the others. ' +
     "With no handler it files a GitHub issue for the owning package, only with --confirm-public (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +
+    "With --to <package>, the report goes only to that integration's issues URL instead, under the same --confirm-public rule. " +
+    'When loaded integrations name their own issues URLs, the output lists every destination: an agent asks the person where to file and passes their choice with --to; it never picks a package itself, and without a choice the default is used. ' +
     'The report records whether an agent or a person ran it.',
   fn: 'gapReport',
   args: [
@@ -55,13 +57,19 @@ export const doc = {
       flag: '--confirm-public',
       param: 'options.confirmPublic',
       description:
-        'Allow public delivery: public handlers run, and with no handler it files a GitHub issue with your gh login',
+        'Allow public delivery: public handlers run, and a GitHub issues URL gets an issue filed with your gh login',
+    },
+    {
+      flag: '--to <package>',
+      param: 'options.to',
+      description:
+        "Send the report only to this loaded integration's issues URL, as the person chose; the destinations the output lists are the choices",
     },
     {
       flag: '--list-categories',
       param: 'options.listCategories',
       description:
-        'List valid report categories without filing; the component and the other gap-report options are refused with ERR_INVALID_ARGUMENT',
+        'List valid report categories, and the destinations when there is more than one, without filing; the component and the other gap-report options are refused with ERR_INVALID_ARGUMENT',
     },
   ],
   examples: [
@@ -70,7 +78,12 @@ export const doc = {
       label: 'Prepare a report (nothing public happens without --confirm-public)',
       cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size'",
     },
+    {
+      label: 'File where the person chose',
+      cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size' --to @acme/widgets",
+    },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,

package/clients/cli/commands/gap-report.mjs

@@ -7,7 +7,7 @@
 import {gapReport as gapReportApi} from '../../../api/gap-report/gap-report.mjs';
 import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, record, records, section} from '../formatters/index.mjs';
+import {emit, record, records, section, text} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as gapReportCommand} from './gap-report.doc.mjs';
@@ -19,7 +19,7 @@ export function registerGapReport(program) {
     fn: gapReportFn,
     action: async (
       /** @type {string|undefined} */ component,
-      /** @type {{category?: string, reason?: string, additionalContext?: string, package?: string, confirmPublic?: boolean, listCategories?: boolean}} */ options,
+      /** @type {{category?: string, reason?: string, additionalContext?: string, package?: string, confirmPublic?: boolean, listCategories?: boolean, to?: string}} */ options,
     ) => {
       /** @type {Awaited<ReturnType<typeof gapReportApi>>} */
       let result;
@@ -35,6 +35,7 @@ export function registerGapReport(program) {
           package: options.package,
           confirmPublic: options.confirmPublic,
           listCategories: options.listCategories,
+          to: options.to,
         });
       } catch (error) {
         const err =
@@ -78,6 +79,9 @@ export function registerGapReport(program) {
           section('Gap report categories'),
           records(result.data, {fields: ['value', 'label']}),
         );
+        if (result.meta) {
+          emit(...destinationBlocks(result.meta.destinations, result.meta.ask));
+        }
         return answered;
       }
 
@@ -119,8 +123,26 @@ export function registerGapReport(program) {
         );
       }
 
+      if (result.data.destinations && result.data.ask) {
+        emit(...destinationBlocks(result.data.destinations, result.data.ask));
+      }
+
       if (isFailure) process.exitCode = 1;
       return answered;
     },
   });
 }
+
+/**
+ * The destinations a report can go to, then the line telling an agent to ask
+ * the person (architecture:cli-surface INV36).
+ * @param {import('../../../api/gap-report/gap-report.type.mjs').GapReportDestination[]} destinations
+ * @param {string} ask
+ */
+function destinationBlocks(destinations, ask) {
+  return [
+    section('Destinations'),
+    records(destinations, {fields: ['to', 'default', 'issuesUrl']}),
+    text(ask),
+  ];
+}

package/clients/cli/commands/gap-report.test.mjs

@@ -331,3 +331,82 @@ describe('gap-report control docs', () => {
     ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
   });
 });
+
+describe('gap-report destinations in text', () => {
+  it('lists the destinations and tells the agent to ask the person', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-dest-'));
+    try {
+      fs.writeFileSync(
+        path.join(cwd, 'package.json'),
+        JSON.stringify({name: 'fixture-app'}),
+      );
+      const pkg = path.join(cwd, 'node_modules', '@test', 'widgets');
+      fs.mkdirSync(pkg, {recursive: true});
+      fs.writeFileSync(
+        path.join(pkg, 'package.json'),
+        JSON.stringify({name: '@test/widgets', version: '1.0.0'}),
+      );
+      fs.writeFileSync(
+        path.join(pkg, 'astryx.integration.mjs'),
+        "export default {issuesUrl: 'https://tracker.example/widgets'};\n",
+      );
+      fs.writeFileSync(
+        path.join(cwd, 'astryx.config.mjs'),
+        `export default {
+  integrations: ['@test/widgets'],
+  gapReport: {audience: 'internal', handle: () => ({status: 'filed', message: 'shared'})},
+};\n`,
+      );
+
+      const listed = await runCli(['gap-report', '--list-categories'], {cwd});
+      expect(listed.status).toBe(0);
+      expect(listed.stdout).toContain('Destinations');
+      expect(listed.stdout).toMatch(/^default:\s+true$/m);
+      expect(listed.stdout).toMatch(/^to:\s+@test\/widgets$/m);
+      expect(listed.stdout).toMatch(
+        /^issuesUrl:\s+https:\/\/tracker\.example\/widgets$/m,
+      );
+      expect(listed.stdout).toMatch(/ask the person/i);
+
+      const filed = await runCli(
+        [
+          'gap-report',
+          'Button',
+          '--category',
+          'docs_gap',
+          '--reason',
+          'Need a keyboard example',
+        ],
+        {cwd},
+      );
+      expect(filed.status).toBe(0);
+      expect(filed.stdout).toContain('Destinations');
+      expect(filed.stdout).toMatch(/ask the person/i);
+
+      const chosen = await runCli(
+        [
+          'gap-report',
+          'Button',
+          '--category',
+          'docs_gap',
+          '--reason',
+          'Need a keyboard example',
+          '--to',
+          '@test/widgets',
+          '--json',
+        ],
+        {cwd},
+      );
+      expect(chosen.status).toBe(0);
+      expect(JSON.parse(chosen.stdout).data.deliveries).toEqual([
+        expect.objectContaining({
+          handler: 'issuesUrl',
+          status: 'routed_only',
+          url: 'https://tracker.example/widgets',
+        }),
+      ]);
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
+});

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

@@ -40,6 +40,7 @@ export const doc = {
     {label: 'Browse the catalog', cli: 'astryx hook --list'},
     {label: 'One hook as JSON', cli: 'astryx hook useFocusTrap --json'},
   ],
+  outsideProject: 'same',
   exitCodes: [
     {code: 0, when: 'success'},
     {

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

@@ -39,6 +39,11 @@ const exists = rel => fs.existsSync(path.join(tmpDir, rel));
 
 describe('astryx init — default (no flags)', () => {
   it('installs the tool-agnostic AGENTS.md cheat sheet and prints next steps', async () => {
+    // Inside a project; outside one the steps are left out (outside-project.test.mjs).
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}',
+    );
     const {status, stdout} = await runCli(['init'], {cwd: tmpDir});
     expect(status).toBe(0);
     expect(exists('AGENTS.md')).toBe(true);

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

@@ -19,7 +19,12 @@ export const doc = {
     '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.',
+    '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. ' +
+    'The CLI installed for the computer also keeps that text current in the background, unless --user --remove-agents turned it off; ' +
+    'package install scripts, project setup, and upgrade never write it.',
   fn: 'init',
   options: [
     {
@@ -43,6 +48,18 @@ export const doc = {
         "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left) and do nothing else. " +
         '--features, --all, --agent and --agent-docs-path are refused; a file written with --agent-docs-path keeps its block',
     },
+    {
+      flag: '--user',
+      param: 'options.user',
+      description:
+        'Write or refresh the computer-level agent text instead of setting up the folder: one skill file, ~/.agents/skills/astryx/SKILL.md, which most coding agents read, ' +
+        '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): a folder symlink with a relative target, a junction on Windows, or a copy where neither can be made. Continue, whose scanner skips links, gets a managed copy, refreshed with the file. ' +
+        "It tells agents anywhere on the computer that Astryx is there, when it is relevant, and to start with `astryx search`. " +
+        'Records the links it made in astryx/settings.json in the per-user configuration folder, so removal removes exactly those; the CLI installed for the computer refreshes the file in the background after each upgrade. ' +
+        'Works in any 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. ' +
+        'Warns, and still writes, when no `astryx` command on the computer runs the Astryx CLI. ' +
+        'With --remove-agents it removes the file, the links, and the copy instead and records that the text is turned off. --features, --all, --agent and --agent-docs-path are refused',
+    },
     {
       flag: '--agent <tool>',
       param: 'options.agent',
@@ -51,7 +68,7 @@ export const doc = {
         '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). ' +
         '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',
+                'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence.',
     },
     {
       flag: '--agent-docs-path <path...>',
@@ -66,7 +83,10 @@ export const doc = {
     {label: 'Default setup', cli: 'astryx init'},
     {label: 'All features, no prompts', cli: 'astryx init --all'},
     {label: 'Machine-readable receipt', cli: 'astryx init --json'},
+    {label: 'Agent text for the whole computer', cli: 'astryx init --user'},
+    {label: 'Remove the computer-level agent text and turn it off', cli: 'astryx init --user --remove-agents'},
   ],
+  outsideProject: 'own',
   exitCodes: [
     {
       code: 0,
@@ -74,8 +94,14 @@ export const doc = {
     },
     {
       code: 1,
-      when: 'an unknown --agent or feature, an --agent-docs-path outside the project, --remove-agents combined with install options, 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)',
     },
   ],
   related: ['doctor', 'upgrade', 'build', 'theme'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a project, init writes the agent docs (AGENTS.md) into the folder and prints no getting-started steps. `init --user` writes the agent guide for your computer, in any folder, and is never handed to a project's own CLI. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:computer-agent-guide}.",
+    },
+  ],
 };

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

@@ -113,6 +113,7 @@ export const doc = {
       cli: 'astryx integration add theme ocean --from neutral',
     },
   ],
+  outsideProject: 'refuse',
   exitCodes: [
     {code: 0, when: 'the contribution is written or the dry run succeeds'},
     {
@@ -121,4 +122,10 @@ export const doc = {
     },
   ],
   related: ['integration verify', 'doctor integration validate', 'theme add'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, integration add writes nothing and stops with `ERR_FILE_NOT_FOUND`: \"No package.json found. Run this command inside an integration package.\" In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };

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

@@ -147,6 +147,52 @@ describe('integration authoring CLI', () => {
     );
   });
 
+  it("verify carries each issue's fix, file, and line in JSON and prints them in text", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs', 'docs'],
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      "export default {docs: './docs'};\n",
+    );
+    fs.mkdirSync(path.join(tmpDir, 'docs'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'deploying.doc.mjs'),
+      "export const docs = {type: 'generic', name: 'deploying', title: 'Deploying', description: 'How to deploy.', sections: [{title: 'Overview', content: [{type: 'prose', text: 'Ship it.'}]}]};\n",
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'ghost.doc.zh.mjs'),
+      "export default {title: 'ghost'};\n",
+    );
+
+    const json = parseEnvelope(
+      (await runCli(['integration', 'verify', '--json'], tmpDir)).stdout,
+    );
+    const orphans = json.data.issues.filter(issue =>
+      issue.code.endsWith('orphan_doc_overlay'),
+    );
+    expect(orphans.map(issue => issue.code).sort()).toEqual([
+      'orphan_doc_overlay',
+      'packed_orphan_doc_overlay',
+    ]);
+    for (const issue of orphans) {
+      expect(issue).toMatchObject({
+        file: 'docs/ghost.doc.zh.mjs',
+        line: 1,
+        fix: expect.stringContaining('Delete docs/ghost.doc.zh.mjs'),
+      });
+    }
+
+    const text = (await runCli(['integration', 'verify'], tmpDir)).stdout;
+    expect(text).toContain('file: docs/ghost.doc.zh.mjs:1');
+    expect(text).toContain(`fix: ${orphans[0].fix}`);
+  });
+
   it('keeps `integration pack --check` as a deprecated alias of `integration verify`', async () => {
     // The old spelling runs the same check: the same JSON, the same exit code.
     const verify = await runCli(['integration', 'verify', '--json'], tmpDir);
@@ -173,7 +219,7 @@ describe('integration authoring CLI', () => {
     expect(text.status).toBe(verifyText.status);
     expect(text.stdout).toBe(verifyText.stdout);
     expect(text.stderr).toContain('`integration pack --check` is deprecated');
-    expect(text.stderr).toContain('astryx integration verify');
+    expect(text.stderr).toContain(' integration verify`');
     // Without --check it fails, as it did, and points only at the new name:
     // suggesting `--check` would send people to the deprecated spelling.
     const bare = await runCli(['integration', 'pack'], tmpDir);
@@ -181,13 +227,13 @@ describe('integration authoring CLI', () => {
     expect(bare.stderr).toContain(
       '`integration pack` is now `integration verify`',
     );
-    expect(bare.stderr).toContain('astryx integration verify');
+    expect(bare.stderr).toContain(' integration verify`');
     expect(bare.stderr).toContain('npm pack');
     expect(bare.stderr).not.toContain('--check');
     const bareJson = await runCli(['--json', 'integration', 'pack'], tmpDir);
     expect(parseEnvelope(bareJson.stdout)).toMatchObject({
       code: 'ERR_INVALID_ARGUMENT',
-      error: expect.stringContaining('astryx integration verify'),
+      error: expect.stringContaining(' integration verify`'),
     });
     // Help lists it, marked deprecated: nothing is hidden.
     const help = await runCli(['integration', '--help'], tmpDir);

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

@@ -35,14 +35,15 @@ export const doc = {
     '`integration check` on every build; run ' +
     '`integration verify` before you publish, to check that the packed package ' +
     'works in an app. To check an installed integration by name, run the ' +
-    '`doctor integration` subcommands with its package name.',
+    '`doctor integration` subcommands with its package name. Outside a package, ' +
+    'it writes nothing, `validate` reports one `no_package` issue, and it exits 1.',
   fn: 'integrationCheck',
   options: [
     {
       flag: '--strict',
       param: 'options.strict',
       description:
-        'Also exit 1 on any warning and on any check that did not run. A new check or failure code joins only in a minor release, named in the release notes.',
+        'Also exit 1 on any warning and on any check that did not run. A new check or failure code joins only in a minor release, named in the release notes; until then, a malformed `cliCommand` is reported as a note (`invalid_cli_command`) that fails nothing.',
     },
   ],
   examples: [
@@ -65,6 +66,7 @@ export const doc = {
       cli: 'integration verify',
     },
   ],
+  outsideProject: 'own',
   exitCodes: [
     {
       code: 0,
@@ -82,4 +84,10 @@ export const doc = {
     'doctor integration templates',
     'doctor integration docs',
   ],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, it writes nothing, its `validate` check reports one `no_package` issue, and it exits 1. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };

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

@@ -117,6 +117,23 @@ describe('astryx integration check', () => {
     expect(run.status).toBe(1);
   });
 
+  it('--strict prints each finding once: its message above, its code in the failing list', async () => {
+    const id = await coreTemplateId();
+    writePackage({id});
+
+    const run = await runCli(['integration', 'check', '--strict'], tmpDir);
+    const json = await runCli(
+      ['integration', 'check', '--strict', '--json'],
+      tmpDir,
+    );
+    const [failure] = JSON.parse(json.stdout.trim()).data.failures;
+
+    expect(run.stdout.split(failure.message).length - 1).toBe(1);
+    expect(
+      run.stdout.slice(run.stdout.indexOf('Failing under --strict')),
+    ).toContain('template_id_conflict');
+  });
+
   it('--json carries each check with its own envelope, the --strict failures, and exits as the text does', async () => {
     const id = await coreTemplateId();
     writePackage({id});
@@ -248,13 +265,43 @@ describe('astryx integration check', () => {
       '"typecheck": "tsc --noEmit && astryx integration check --strict"',
     );
     expect(run.stdout).toContain(
-      'A new check or failure code joins only in a minor release, named in the release notes.',
+      'A new check or failure code joins only in a minor release, named in the release notes; until then, a malformed `cliCommand` is reported as a note (`invalid_cli_command`) that fails nothing.',
     );
     expect(run.stdout).toContain('integration verify');
     expect(run.stdout).toContain('against the package in the current folder');
     expect(run.stdout).not.toContain('[package]');
   });
 
+  it('reports a malformed cliCommand as a note beside the issues, which --strict does not fail', async () => {
+    // A unique template id, so nothing else warns.
+    writePackage({
+      id: 'acme-notes-only-fixture',
+      extraManifest: ", cliCommand: ' acme astryx\\n'",
+    });
+
+    const json = await runCli(
+      ['--json', 'integration', 'check', '--strict'],
+      tmpDir,
+    );
+    const envelope = JSON.parse(json.stdout);
+    const validate = envelope.data.checks[0].response.data;
+    expect(validate.issues.map((/** @type {any} */ i) => i.code)).not.toContain(
+      'invalid_cli_command',
+    );
+    expect(validate.notes).toEqual([
+      {code: 'invalid_cli_command', message: expect.any(String)},
+    ]);
+    expect(envelope.data.failed).toBe(false);
+    expect(json.status).toBe(0);
+
+    const text = await runCli(['integration', 'check'], tmpDir);
+    expect(
+      text.stdout
+        .split('\n')
+        .filter(line => line.startsWith('note (invalid_cli_command): ')),
+    ).toHaveLength(1);
+  });
+
   it('takes no package name: one passed is an error, not a check of the current folder', async () => {
     writePackage({id: 'acme-page'});
 
@@ -265,3 +312,130 @@ describe('astryx integration check', () => {
     expect(run.status).toBe(1);
   });
 });
+
+describe('a copied passage', () => {
+  const passage =
+    'Themes cannot style the layer that holds a menu or a popover, so a menu ' +
+    'keeps the default surface color until the next release adds a token for it.';
+
+  function writeCopiedDocs() {
+    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'));
+    for (const name of ['acme-setup', 'acme-menus']) {
+      const doc = {
+        type: 'generic',
+        name,
+        title: 'Fixture',
+        description: 'Fixture topic.',
+        sections: [
+          {title: 'Overview', content: [{type: 'prose', text: passage}]},
+        ],
+      };
+      fs.writeFileSync(
+        path.join(tmpDir, 'docs', `${name}.doc.mjs`),
+        `export default ${JSON.stringify(doc)};\n`,
+      );
+    }
+  }
+
+  it('keeps doctor integration docs at exit 0, and fails integration check --strict', async () => {
+    writeCopiedDocs();
+
+    const doctor = await runCli(['doctor', 'integration', 'docs'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain('1 copied passage(s)');
+
+    const loose = await runCli(['integration', 'check'], tmpDir);
+    expect(loose.status).toBe(0);
+
+    const strict = await runCli(['integration', 'check', '--strict'], tmpDir);
+    expect(strict.status).toBe(1);
+    expect(strict.stdout).toContain('copied_passage');
+  });
+});
+
+describe('a padding phrase', () => {
+  it('keeps doctor integration docs at exit 0, and fails integration check --strict', 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: 'prose', text: 'In order to start, run the setup.'}],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+
+    const doctor = await runCli(['doctor', 'integration', 'docs'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain('1 fluff finding(s)');
+
+    const strict = await runCli(['integration', 'check', '--strict'], tmpDir);
+    expect(strict.status).toBe(1);
+    expect(strict.stdout).toContain('doc_fluff');
+  });
+});
+
+describe('a stray doc pointer', () => {
+  it('keeps doctor integration docs at exit 0, and fails integration check --strict', 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: 'prose', text: 'The theme is in `astryx docs theme`.'},
+          ],
+        },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'acme-setup.doc.mjs'),
+      `export default ${JSON.stringify(doc)};\n`,
+    );
+
+    const doctor = await runCli(['doctor', 'integration', 'docs'], tmpDir);
+    expect(doctor.status).toBe(0);
+    expect(doctor.stdout).toContain('1 stray doc pointer(s)');
+    expect(doctor.stdout).toContain('{@link @astryxdesign/cli:generic:theme}');
+
+    const strict = await runCli(['integration', 'check', '--strict'], tmpDir);
+    expect(strict.status).toBe(1);
+    expect(strict.stdout).toContain('stray_doc_pointer');
+  });
+});

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

@@ -8,7 +8,7 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Deprecated: the old name of `integration verify`',
   description:
-    '`astryx integration pack --check` is the name this check had before {@link command:integration verify}. It still runs the same check, with the same output, JSON, and exit codes, and prints a note that names `integration verify`. It will be removed in a later release.',
+    '`astryx integration pack --check` is the name this check had before {@link command:integration verify}. It still runs the same check, with the same output, JSON, and exit codes, and prints a note that names `integration verify`. It will be removed in a later release. Outside a package it writes nothing and reports one failed check, no_package, naming the integration package it needs (exit 1).',
   fn: 'integrationPackCheck',
   options: [
     {
@@ -19,6 +19,7 @@ export const doc = {
   examples: [
     {label: 'The old spelling', cli: 'astryx integration pack --check'},
   ],
+  outsideProject: 'own',
   exitCodes: [
     {code: 0, when: 'the packed package exposes the same valid contributions'},
     {
@@ -27,4 +28,10 @@ export const doc = {
     },
   ],
   related: ['integration verify'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, `integration pack --check` writes nothing, reports one failed check, `no_package`, and exits 1. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };

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

@@ -8,15 +8,22 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Check the package the way npm will publish it, before you publish',
   description:
-    'Packs the package with npm, unpacks the tarball into a temporary app without installing its dependencies, and checks that the app sees the same components, templates, themes, docs, and codemods as the package, that every public import resolves, and that the package declares a CLI new enough to read it. It publishes nothing and leaves no tarball behind. It runs the package\'s own pack lifecycle scripts, as `npm pack` does.',
+    'Packs the package with npm, unpacks the tarball into a temporary app without installing its dependencies, and checks that the app sees the same components, templates, themes, docs, and codemods as the package, that every public import resolves, and that the package declares a CLI new enough to read it. It publishes nothing and leaves no tarball behind. It runs the package\'s own pack lifecycle scripts, as `npm pack` does. Outside a package it writes nothing and reports one failed check, no_package, naming the integration package it needs (exit 1).',
   fn: 'integrationPackCheck',
   examples: [
     {label: 'Check before publishing', cli: 'astryx integration verify'},
     {label: 'Machine-readable result', cli: 'astryx integration verify --json'},
   ],
+  outsideProject: 'own',
   exitCodes: [
     {code: 0, when: 'the packed package exposes the same valid contributions'},
     {code: 1, when: 'the tarball is incomplete or invalid'},
   ],
   related: ['integration add', 'doctor integration validate'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, it writes nothing, reports one failed check, `no_package`, and exits 1. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };