@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

package/clients/cli/commands/docs.mjs

@@ -10,6 +10,9 @@
  * contract: a topic returns its whole doc, and `--index` its sections.
  * Supports --detail (full|compact|brief) and --lang (en|zh|dense). A code
  * block's label prints above its fence, and table cells escape their pipes.
+ * Docs write commands as bare `astryx ...`; text output prefixes them with the
+ * project's invocation (prefixCliCommands, in formatBlock and the summaries),
+ * and JSON keeps them bare.
  *
  * Usage:
  *   astryx docs                          List available topics
@@ -25,6 +28,7 @@
 import {
   formatCliCommand,
   getCliInvocation,
+  prefixCliCommands,
 } from '../../../foundation/env/package-manager.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {
@@ -96,12 +100,17 @@ function formatTableCompact(headers, rows) {
  * @returns {string | null}
  */
 export function formatBlock(block, detail) {
+  // Docs write commands as bare `astryx ...`; show them the way this project
+  // runs the CLI.
+  const stem = getCliInvocation();
+  /** @param {string} value */
+  const shown = value => prefixCliCommands(value, stem);
   switch (block.type) {
     case 'prose':
-      return block.text;
+      return shown(block.text);
 
     case 'heading':
-      return `${'#'.repeat(block.level || 3)} ${block.text}`;
+      return `${'#'.repeat(block.level || 3)} ${shown(block.text)}`;
 
     case 'code':
       if (detail === 'compact' || detail === 'brief') return null;
@@ -112,19 +121,29 @@ export function formatBlock(block, detail) {
         const label = block.label
           ? `${block.label.replace(/:\s*$/, '')}:\n`
           : '';
-        return `${label}\`\`\`${block.lang}\n${block.code}\n\`\`\``;
+        const body = prefixCliCommands(block.code, stem, block.lang);
+        return `${label}\`\`\`${block.lang}\n${body}\n\`\`\``;
       }
 
-    case 'table':
+    case 'table': {
+      // A cell that is a whole command, such as `astryx theme add neutral`
+      // written without backticks, is prefixed too.
+      /** @param {string} cell */
+      const shownCell = cell =>
+        /^astryx(\s|$)/.test(cell ?? '')
+          ? `${stem}${cell.slice('astryx'.length)}`
+          : shown(cell ?? '');
+      const rows = block.rows.map(row => row.map(shownCell));
       if (detail === 'brief') {
-        return block.rows
+        return rows
           .map(r => r.slice(0, 2).map(tableCell).join('='))
           .join(' | ');
       }
       if (detail === 'compact') {
-        return formatTableCompact(block.headers, block.rows);
+        return formatTableCompact(block.headers, rows);
       }
-      return formatTable(block.headers, block.rows);
+      return formatTable(block.headers, rows);
+    }
 
     case 'list': {
       const prefix =
@@ -135,7 +154,9 @@ export function formatBlock(block, detail) {
             : block.style === 'do'
               ? () => '+ '
               : () => '- ';
-      return block.items.map((item, i) => `${prefix(i)}${item}`).join('\n');
+      return block.items
+        .map((item, i) => `${prefix(i)}${shown(item)}`)
+        .join('\n');
     }
 
     default:
@@ -289,7 +310,7 @@ function formatTreeChild(child, detail, level, root, run, owner) {
     child.summary &&
     (child.kind === 'namespace' || child.kind === 'generic')
   ) {
-    parts.push(child.summary);
+    parts.push(prefixCliCommands(child.summary, run));
   }
   const content = formatTreeBlocks(child.content ?? [], detail, level - 2);
   if (content.length > 0) parts.push(content.join('\n\n'));
@@ -341,7 +362,7 @@ function emitTree(node, detail, childDetail, run) {
     .every(route => route.startsWith(`${node.route}/`));
   const root = allBelow ? node.route : '';
   emit(
-    section(node.title, wrapText(node.summary)),
+    section(node.title, wrapText(prefixCliCommands(node.summary, run))),
     record({package: node.package}),
     ...(node.content?.length
       ? [
@@ -427,9 +448,12 @@ function emitIndex(index, owner, run) {
     // Summaries wrap rather than being cut: the summary is how a reader picks
     // the one section to open. A section another package wrote says which one.
     records(
-      index.sections.map(s =>
-        s.package === owner ? s : {...s, title: `${s.title} (${s.package})`},
-      ),
+      index.sections.map(s => {
+        const shown = {...s, summary: prefixCliCommands(s.summary ?? '', run)};
+        return s.package === owner
+          ? shown
+          : {...shown, title: `${s.title} (${s.package})`};
+      }),
       {
         fields: ['id', 'title', 'summary'],
         layout: 'inline',
@@ -462,9 +486,10 @@ function childRow(child, owner) {
   return {
     // A child another package owns says which one.
     name: child.package === owner ? child.name : `${child.name} (${child.package})`,
-    summary: titleAddsIdentity
-      ? `${child.title}: ${child.summary}`
-      : child.summary,
+    summary: prefixCliCommands(
+      titleAddsIdentity ? `${child.title}: ${child.summary}` : child.summary,
+      getCliInvocation(),
+    ),
   };
 }
 
@@ -479,14 +504,19 @@ function childRow(child, owner) {
 function emitNode(node, detail, run) {
   if (node.kind === 'namespace') {
     emit(
-      section(node.title, wrapText(node.summary)),
+      section(node.title, wrapText(prefixCliCommands(node.summary, run))),
       record({package: node.package}),
-      // A namespace may author intro `blocks`; they render above its children.
+      // A namespace may author intro `blocks`; they render above its children,
+      // prose wrapped like the summary.
       ...(node.content?.length
         ? [
             text(
               node.content
-                .map(b => formatBlock(b, detail))
+                .map(b =>
+                  b.type === 'prose'
+                    ? wrapText(formatBlock(b, detail) ?? '')
+                    : formatBlock(b, detail),
+                )
                 .filter(Boolean)
                 .join('\n\n'),
             ),

package/clients/cli/commands/docs.test.mjs

@@ -113,7 +113,7 @@ describe('progressive reads', () => {
     expect(stdout).toMatch(/^principles +\S/m);
     expect(widest(stdout)).toBeLessThanOrEqual(120);
     // The repo root has no `astryx` bin, so the CLI names the scoped package.
-    expect(stdout).toMatch(/Usage: \S+(?: dlx)? (?:astryx|@astryxdesign\/cli) docs <topic>/);
+    expect(stdout).toMatch(/Usage: \S+(?: dlx)? (?:astryx|@astryxdesign\/cli(?:@\S+)?) docs <topic>/);
   }, SLOW);
 
   it("prints a topic's section index with the keys to read by", async () => {
@@ -255,7 +255,7 @@ describe('the docs tree, one level at a time', () => {
     const {status, stdout} = await runCli(['docs', 'cli/api/functions/search']);
     expect(status).toBe(0);
     expect(stdout).toMatch(/^## search\(\)/m);
-    expect(stdout).toContain('Read it with `astryx docs cli/commands/search`.');
+    expect(stdout).toMatch(/Read it with `.+ docs cli\/commands\/search`\./);
     expect(stdout).toMatch(/Up: .*docs cli\/api\/functions$/m);
   }, SLOW);
 

package/clients/cli/commands/doctor-integration-components.doc.mjs

@@ -20,12 +20,15 @@ export const doc = {
     'Core component is an error. In a package without that range they are warnings, ' +
     'with a warning for each such component, naming the range to declare. ' +
     "Then it compares each component doc's props with the component's TypeScript " +
-    "props, using the project's own `typescript`, and warns about a documented prop " +
+    "props, using the project's own `typescript` (or, where `typescript` is missing or " +
+    'has no JavaScript compiler API, as TypeScript 7 does, the `@typescript/typescript6` ' +
+    'it installs), and warns about a documented prop ' +
     'the code lacks, a prop the package declares that the doc omits, a wrong ' +
     '`required`, and a type that does not match where both sides read exactly ' +
     '(it lists every other documented type as not compared, with the reason). ' +
     'Without TypeScript it prints one ' +
-    'line saying the comparison was skipped.',
+    'line saying the comparison was skipped. It also warns on each `{@link}` in ' +
+    "a component doc's text that names no doc.",
   fn: 'integrationComponentConflicts',
   args: [
     {
@@ -46,10 +49,11 @@ export const doc = {
       cli: 'astryx doctor integration components @acme/widgets --json',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,
-      when: 'the check completed; component name conflicts, replaces findings for a package without the CLI range, and props that differ from the code are warnings',
+      when: 'the check completed; component name conflicts, replaces findings for a package without the CLI range, props that differ from the code, and links that name no doc are warnings',
     },
     {
       code: 1,

package/clients/cli/commands/doctor-integration-docs.doc.mjs

@@ -8,12 +8,17 @@ export const doc = {
   name: 'doctor integration docs',
   displayName: 'astryx doctor integration docs',
   namespace: 'cli/commands',
-  summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
+  summary:
+    "Check an integration's docs: the docs tree they add, every link, and overlaps with Core topics",
   description:
     'Checks the docs tree the package adds, every link in its docs, and overlaps with Core topics. ' +
     'Intentional replacements and extensions are information. ' +
     'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
-    'and fails until the author declares the relationship or renames it. See {@link generic:check-your-docs}.',
+    'and fails until the author declares the relationship or renames it. ' +
+    'It also lists each pair of topics (two of the package, or one of them and a Core topic other than the one it replaces) ' +
+    'that repeat 10 or more words of prose word for word, each padding phrase and low-density topic, ' +
+    'and each written `astryx docs <name>` that should be a link, ' +
+    'each as a warning (`copied_passage`, `doc_fluff`, `stray_doc_pointer`; exit 0, and `integration check --strict` fails on it). See {@link generic:check-your-docs}.',
   fn: 'integrationDocConflicts',
   args: [
     {
@@ -25,15 +30,25 @@ export const doc = {
     },
   ],
   examples: [
-    {label: 'Check the local integration', cli: 'astryx doctor integration docs'},
+    {
+      label: 'Check the local integration',
+      cli: 'astryx doctor integration docs',
+    },
     {
       label: 'Check an installed integration',
       cli: 'astryx doctor integration docs @acme/widgets --json',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
-    {code: 0, when: 'all Core overlaps are explicitly declared or no overlap exists'},
-    {code: 1, when: 'an overlap is accidental, a doc is invalid, a namespace or placement fails, or a reference block cannot include what it names. A link that names no doc is a warning, and does not change the exit code'},
+    {
+      code: 0,
+      when: 'all Core overlaps are explicitly declared or no overlap exists',
+    },
+    {
+      code: 1,
+      when: 'an overlap is accidental, a doc is invalid, a namespace or placement fails, or a reference block cannot include what it names. A link that names no doc is a warning, and does not change the exit code',
+    },
   ],
   related: ['doctor integration validate', 'docs'],
 };

package/clients/cli/commands/doctor-integration-templates.doc.mjs

@@ -37,6 +37,7 @@ export const doc = {
       cli: 'astryx doctor integration templates @acme/widgets --json',
     },
   ],
+  outsideProject: 'same',
   exitCodes: [
     {
       code: 0,

package/clients/cli/commands/doctor-integration-validate.doc.mjs

@@ -16,11 +16,15 @@ export const doc = {
     'installed package resolved by name. It schema-checks the manifest, verifies ' +
     'every declared contribution root, and reports every finding. Safe as a CI gate. ' +
     'It then checks every doc the package ships under its roots against the ' +
-    "published authoring type for its kind, with the project's own `typescript`, and " +
+    "published authoring type for its kind, with the project's own `typescript` (or, " +
+    'where `typescript` is missing or has no JavaScript compiler API, as TypeScript 7 ' +
+    'does, the `@typescript/typescript6` it installs), and ' +
     'warns about each field that does not match, naming the field and a fix. A doc ' +
     'it cannot fully check is listed with the reason, and test fixtures under ' +
     '`__tests__` in the components or docs root are counted, not checked. Without ' +
-    'TypeScript it prints one line saying the docs were not type-checked.',
+    'TypeScript it prints one line saying the docs were not type-checked. ' +
+    'Outside a package, with no package name it writes nothing and reports one no_package issue (exit 1); ' +
+    'a package name is looked up as it is in a project.',
   fn: 'validateIntegration',
   args: [
     {
@@ -41,6 +45,7 @@ export const doc = {
       cli: 'astryx doctor integration validate @acme/widgets --json',
     },
   ],
+  outsideProject: 'own',
   exitCodes: [
     {
       code: 0,
@@ -49,4 +54,10 @@ export const doc = {
     {code: 1, when: 'one or more error-severity issues'},
   ],
   related: ['doctor integration templates', 'template'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a package, with no package named, it writes nothing, reports one `no_package` issue, and exits 1; a package name is looked up as it is in a project. 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/doctor-integration.test.mjs

@@ -19,7 +19,7 @@ import {Command} from 'commander';
 import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
 import {discoverOwnedComponents} from '../../../foundation/discovery/component-discovery.mjs';
 import {discoverBuiltinTopics} from '../../../foundation/discovery/docs-discovery.mjs';
-import {findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {findCoreDir, findProjectCoreDir} from '../../../foundation/fs/paths.mjs';
 import {registerDoctor} from './doctor.mjs';
 import {expectRecordsCarry} from '../../../test-utils/text-projection.mjs';
 
@@ -185,7 +185,7 @@ describe('doctor integration — command', () => {
     ]);
 
     expect(logCalls.join('\n')).toContain(
-      'astryx doctor integration templates <package>',
+      ' doctor integration templates <package>',
     );
     expect(process.exitCode).toBeUndefined();
   });
@@ -210,6 +210,51 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('validate prints the fix and the file an issue carries, and JSON carries the same issue', async () => {
+    writeDocIntegration({name: 'deploying'});
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'ghost.doc.zh.mjs'),
+      "export default {title: 'ghost'};\n",
+    );
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+      'validate',
+    ]);
+    const output = logCalls.join('\n');
+    expect(output).toContain('orphan_doc_overlay');
+    expect(output).toMatch(
+      /fix:\s+Delete docs\/ghost\.doc\.zh\.mjs, or add the topic it translates/,
+    );
+    expect(output).toMatch(/file:\s+docs\/ghost\.doc\.zh\.mjs/);
+    expect(output).toMatch(/line:\s+1\b/);
+
+    logCalls = [];
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'validate',
+    ]);
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual([
+      {
+        code: 'orphan_doc_overlay',
+        severity: 'warning',
+        message: expect.stringContaining('docs/ghost.doc.zh.mjs'),
+        fix: expect.stringContaining('Delete docs/ghost.doc.zh.mjs'),
+        file: 'docs/ghost.doc.zh.mjs',
+        line: 1,
+      },
+    ]);
+  });
+
   it('validate warns about each doc field that does not match its authoring type, and still exits 0', async () => {
     writeIntegration({id: 'hero', name: 'Hero', type: 'block'});
     process.chdir(tmpDir);
@@ -772,7 +817,8 @@ describe('doctor integration — command', () => {
     tmpDir = outside;
     try {
       writeComponentIntegration('AcmeCarousel');
-      expect(findCoreDir(outside)).toBeNull();
+      // Doctor judges the project's own Core, never the one a copy carries.
+      expect(findProjectCoreDir(outside)).toBeNull();
       process.chdir(outside);
 
       await createProgram().parseAsync([
@@ -1060,12 +1106,13 @@ describe('doctor integration — command', () => {
         "{name: 'elevation', type: 'number', description: 'Shadow.'}",
         "{name: 'size', type: 'string', description: 'Size.'}",
         "{name: 'meta', type: '{id: string; extra?: number}', description: 'Data.'}",
+        "{name: 'gap', type: 'number', description: 'Gap.', default: '8'}",
       ].join(', ')}]};\n`,
     );
     // `key` is a prop a doc never needs, though the component declares it.
     fs.writeFileSync(
       path.join(tmpDir, 'components', 'AcmeBadge.tsx'),
-      "export function AcmeBadge(props: {label: string; tone?: 'neutral' | 'info'; size?: number; meta?: {id: string}; key?: string}) { return null; }\n",
+      "export function AcmeBadge({gap = 4}: {label: string; tone?: 'neutral' | 'info'; size?: number; meta?: {id: string}; gap?: number; key?: string}) { return null; }\n",
     );
     fs.writeFileSync(
       path.join(tmpDir, 'components', 'AcmeLonely.doc.mjs'),
@@ -1094,6 +1141,7 @@ describe('doctor integration — command', () => {
 
     expect(report.findings.map(f => `${f.prop} ${f.kind}`)).toEqual([
       'elevation not_in_code',
+      'gap default_mismatch',
       'label required_mismatch',
       'size type_mismatch',
       'tone not_in_doc',

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

@@ -18,8 +18,11 @@ export const doc = {
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +
     'install and version alignment, theme packages, generated app themes when present, earlier copied-theme migration, config, integrations (every one astryx.config names must load, linked without a config entry, ' +
     'provider identity, contribution issues), agent docs, core peer dependencies, package manager, ' +
-    "and the docs the CLI reads. It writes nothing, but loading astryx.config runs that file's code. " +
-    'The `integration` subcommands provide authoring checks for one integration package.',
+    "the docs the CLI reads, the newest release the computer knows of, with the install and upgrade commands when the project's release is older, and every `astryx` command on the search path, warning when the first one is not the Astryx CLI or predates the hand-off. It writes nothing, but loading astryx.config runs that file's code. " +
+    'The `integration` subcommands provide authoring checks for one integration package. ' +
+    'Outside a project it checks the computer instead: the Node version, the release that answered, ' +
+    'the newest release this computer knows of, with the command that upgrades the CLI installed for the computer when it is older, the astryx commands on the search path, the integrations installed for the computer (warning about one it skips), and whether the computer-level agent text (`astryx init --user`) is present, matches this release, was edited, or is turned off (info only). ' +
+    'It never fails a check because the folder has no project.',
   fn: 'doctor',
   subcommands: ['integration'],
   examples: [
@@ -42,9 +45,16 @@ export const doc = {
       cli: 'astryx doctor integration docs @acme/widgets',
     },
   ],
+  outsideProject: 'own',
   exitCodes: [
     {code: 0, when: 'no checks failed (warnings are allowed)'},
     {code: 1, when: 'one or more checks failed'},
   ],
   related: ['init', 'upgrade'],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: outside a project, doctor checks your computer instead of a folder: `node-version`, `answering-release` (the version that answered), `newest-release`, `cli-on-path` (every astryx command on your PATH), `computer-integrations` (integrations installed globally), and `computer-agent-text` (the agent guide). It never fails a check because the folder has no project. In a project, the project's version of Astryx runs it, whichever astryx command you start. See {@link namespace:global} and {@link generic:who-answers}.",
+    },
+  ],
 };

package/clients/cli/commands/doctor.mjs

@@ -38,6 +38,8 @@ import {doc as integrationDocConflictsFn} from '../../../api/integration/integra
 import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
+import {isOutsideProject} from '../../../foundation/env/project-scope.mjs';
 
 const STATUS = {
   pass: '[ok]',
@@ -92,7 +94,7 @@ function issueBlocks(issues) {
   return [
     section('Integration issues'),
     records(issues, {
-      fields: ['severity', 'code', 'message'],
+      fields: ['severity', 'code', 'message', 'fix', 'file', 'line'],
       format: {severity: statusToken},
     }),
   ];
@@ -189,11 +191,14 @@ function printIntegrationValidation(data) {
     ...(data.issues.length > 0
       ? [
           records(data.issues, {
-            fields: ['severity', 'code', 'message'],
+            fields: ['severity', 'code', 'message', 'fix', 'file', 'line'],
             format: {severity: statusToken},
           }),
         ]
       : [text('[ok] No integration issues found.')]),
+    ...(data.notes ?? []).map(note =>
+      text(`note (${note.code}): ${note.message}`),
+    ),
     text(
       `Summary: ${errors} error${errors === 1 ? '' : 's'}, ` +
         `${warnings} warning${warnings === 1 ? '' : 's'}`,
@@ -287,6 +292,9 @@ function propDriftBlocks(report, failed) {
           'codeType',
           'docRequired',
           'codeRequired',
+          'docDefault',
+          'codeDefault',
+          'fix',
         ],
         format: {severity: statusToken},
       }),
@@ -358,7 +366,8 @@ function printComponentConflicts(data) {
   // An [ok] after a failed check reads as a pass: say nothing it could not check.
   const failed = data.issues.some(issue => issue.severity === 'error');
   if (data.conflicts.length === 0) {
-    if (!failed) output.push(text('[ok] No component names conflict with Core.'));
+    if (!failed)
+      output.push(text('[ok] No component names conflict with Core.'));
   } else {
     output.push(
       records(data.conflicts, {
@@ -389,7 +398,16 @@ function printDocConflicts(data) {
     section(
       `Checking integration docs: ${integrationLabel(data) ?? '(local package)'}`,
     ),
-    ...issueBlocks(data.issues),
+    // A copied passage or fluff is listed below with its detail, so its
+    // issue is not printed twice.
+    ...issueBlocks(
+      data.issues.filter(
+        issue =>
+          issue.code !== 'copied_passage' &&
+          issue.code !== 'doc_fluff' &&
+          issue.code !== 'stray_doc_pointer',
+      ),
+    ),
   ];
   if (
     !data.issues.some(
@@ -412,6 +430,79 @@ function printDocConflicts(data) {
       }),
     );
   }
+  const copied = data.copiedPassages ?? [];
+  if (copied.length === 0) {
+    if (!data.issues.some(issue => issue.severity === 'error')) {
+      output.push(text('[ok] No topic copies a passage from another.'));
+    }
+  } else {
+    output.push(
+      text(
+        `[warn] ${copied.length} copied passage(s) (copied_passage): two topics say the same thing word for word. Keep the text in one and link to it from the other.`,
+      ),
+      records(copied, {
+        fields: [
+          'topic',
+          'section',
+          'line',
+          'otherTopic',
+          'otherOwner',
+          'owner',
+          'text',
+          'words',
+          'passages',
+          'message',
+        ],
+      }),
+    );
+  }
+  const fluff = data.fluff ?? [];
+  if (fluff.length === 0) {
+    if (!data.issues.some(issue => issue.severity === 'error')) {
+      output.push(text('[ok] No filler phrases or low-density topics.'));
+    }
+  } else {
+    output.push(
+      text(
+        `[warn] ${fluff.length} fluff finding(s) (doc_fluff): words that add length, not meaning. Cut each one.`,
+      ),
+      records(fluff, {
+        fields: [
+          'topic',
+          'kind',
+          'phrase',
+          'section',
+          'file',
+          'line',
+          'density',
+          'message',
+        ],
+      }),
+    );
+  }
+  const stray = data.strayPointers ?? [];
+  if (stray.length === 0) {
+    if (!data.issues.some(issue => issue.severity === 'error')) {
+      output.push(text('[ok] Every pointer to a doc is a link.'));
+    }
+  } else {
+    output.push(
+      text(
+        `[warn] ${stray.length} stray doc pointer(s) (stray_doc_pointer): a written \`astryx docs <name>\` where a link would be checked. Replace each with the link shown.`,
+      ),
+      records(stray, {
+        fields: [
+          'topic',
+          'section',
+          'file',
+          'line',
+          'pointer',
+          'link',
+          'message',
+        ],
+      }),
+    );
+  }
   emit(...output);
 }
 
@@ -455,7 +546,7 @@ async function runIntegrationValidation(program, pkg) {
         noPackage
           ? 'Nothing was validated: no package.json found. Run this command inside a package directory.'
           : 'Nothing was validated: no astryx.integration.* found next to package.json. ' +
-            'To validate an installed integration: astryx doctor integration validate <package>',
+              `To validate an installed integration: ${formatCliCommand('doctor integration validate <package>')}`,
       ),
     );
   } else printIntegrationValidation(result.data);
@@ -478,10 +569,14 @@ async function runAuthoringCheck(program, pkg, kind) {
 
   if (program.opts().json) jsonOut(result);
   else if (!result.data.validated) {
+    // Outside a project no integration is installed to check by name
+    // (spec AST-081 FR3).
     emit(
       text(
-        'Nothing was checked: no astryx.integration.* found next to package.json. ' +
-          `To check an installed integration: astryx doctor integration ${kind} <package>`,
+        isOutsideProject()
+          ? 'Nothing was checked: no astryx.integration.* found next to package.json, and this folder is outside a project.'
+          : 'Nothing was checked: no astryx.integration.* found next to package.json. ' +
+              `To check an installed integration: ${formatCliCommand(`doctor integration ${kind} <package>`)}`,
       ),
     );
   } else if (kind === 'templates') {

package/clients/cli/commands/doctor.test.mjs

@@ -20,6 +20,7 @@ import {
   checkPackageManager,
 } from '../../../api/doctor/doctor.mjs';
 import {MIN_NODE_VERSION} from '../../../foundation/env/node-version.mjs';
+import {CLI_VERSION, linkThisCliAsProjectCli} from '../../../test-utils/release-fixtures.mjs';
 
 let tmpDir;
 let logCalls;
@@ -101,7 +102,7 @@ describe('doctor — individual checks', () => {
   });
 
   it('app themes: reports unmanaged state as one INFO check', async () => {
-    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"app"}\n');
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}\n');
     const result = await runChecks({cwd: tmpDir});
     const themeChecks = result.checks.filter(check =>
       check.id.startsWith('theme-'),
@@ -176,13 +177,16 @@ describe('doctor — individual checks', () => {
   it('agent-docs: the fix names the scoped package when the project has no local CLI', () => {
     fs.writeFileSync(path.join(tmpDir, 'package-lock.json'), '{}');
     const res = checkAgentDocs({cwd: tmpDir});
-    expect(res.fix).toContain('`npx @astryxdesign/cli init --features agents`');
+    expect(res.fix).toContain(
+      `\`npx @astryxdesign/cli@${CLI_VERSION} init --features agents\``,
+    );
   });
 
   it('agent-docs: the fix keeps `npx astryx` when the project has a local CLI', () => {
     fs.writeFileSync(path.join(tmpDir, 'package-lock.json'), '{}');
     fs.mkdirSync(path.join(tmpDir, 'node_modules', '.bin'), {recursive: true});
     fs.writeFileSync(path.join(tmpDir, 'node_modules', '.bin', 'astryx'), '');
+    linkThisCliAsProjectCli(tmpDir);
     const res = checkAgentDocs({cwd: tmpDir});
     expect(res.fix).toContain('`npx astryx init --features agents`');
   });
@@ -301,7 +305,8 @@ describe('doctor — runChecks / report', () => {
     expect(total).toBe(report.checks.length);
   });
 
-  it('reports a FAIL for core when run in a bare directory', async () => {
+  it('reports a FAIL for core in a project that declares Core but installs none', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}\n');
     const report = await runChecks({cwd: tmpDir});
     expect(find(report.checks, 'core-installed').status).toBe('fail');
     expect(report.summary.fail).toBeGreaterThan(0);
@@ -346,7 +351,8 @@ describe('doctor — command', () => {
     process.exitCode = prevExit;
   });
 
-  it('sets exit code 1 when a check FAILs (bare dir, no @astryxdesign/core)', async () => {
+  it('sets exit code 1 when a check FAILs (Core declared, not installed)', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"app","dependencies":{"@astryxdesign/core":"*"}}\n');
     const prevCwd = process.cwd();
     const prevExit = process.exitCode;
     process.exitCode = undefined;