@astryxdesign/cli 0.7.2 → 0.7.3-canary.02f5fe4

package/api/docs/docs.test.mjs

@@ -93,7 +93,7 @@ describe('docs() dispatcher routing', () => {
 
   it("lists the docs tree's namespaces in meta, so every data entry reads as a topic", async () => {
     const res = await docs();
-    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['cli', 'global', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography', 'unorganized']);
+    expect(res.meta.namespaces.map(entry => entry.topic)).toEqual(['authoring', 'cli', 'foundations', 'global', 'guides', 'internationalization', 'layout', 'migration', 'styling', 'styling-libraries', 'tokens', 'typography']);
     for (const entry of res.data) {
       expect((await docs(entry.topic)).type).toBe('docs.detail');
     }
@@ -123,7 +123,13 @@ describe('docs() dispatcher routing', () => {
       kind: 'namespace',
       package: '@astryxdesign/cli',
       breadcrumb: [{route: 'cli', title: 'Astryx CLI'}],
-      content: [],
+      // Its one block points to the host entry's guide.
+      content: [
+        {
+          type: 'prose',
+          text: expect.stringContaining('`astryx docs cli/host-entry`'),
+        },
+      ],
     });
     expect(r.data.slots.flatMap(slot => slot.children.map(c => c.route))).toEqual([
       'cli/api/functions',
@@ -152,8 +158,8 @@ describe('docs() dispatcher routing', () => {
   }, SLOW);
 
   it('a guide the tree places reads like a topic: the whole doc, its index, a section', async () => {
-    // cli/integrations is a namespace of short guides; each guide reads like a topic.
-    const integrations = await docs('cli/integrations');
+    // authoring is a namespace of short guides; each guide reads like a topic.
+    const integrations = await docs('authoring');
     expect(integrations.type).toBe('docs.node');
     const guide = placedGuide(integrations.data);
     expect((await docs(guide)).type).toBe('docs.detail');
@@ -172,7 +178,7 @@ describe('docs() dispatcher routing', () => {
     expect(leaf.links.up).toBe('astryx docs cli/api/functions');
     expect(leaf.links.previous).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
     expect(leaf.links.next).toMatch(/^astryx docs cli\/api\/functions\/[a-z-]+$/);
-    const integrations = (await docs('cli/integrations')).data;
+    const integrations = (await docs('authoring')).data;
     const guide = placedGuide(integrations);
     const siblings = integrations.slots
       .find(slot => slot.children.some(child => child.route === guide))
@@ -181,7 +187,7 @@ describe('docs() dispatcher routing', () => {
     const index = await docs(guide, undefined, {index: true});
     // A guide moves across its namespace's slot, as any tree node does.
     expect(index.data.links).toEqual({
-      up: 'astryx docs cli/integrations',
+      up: 'astryx docs authoring',
       ...(at > 0 ? {previous: `astryx docs ${siblings[at - 1]}`} : {}),
       ...(at < siblings.length - 1
         ? {next: `astryx docs ${siblings[at + 1]}`}
@@ -198,16 +204,22 @@ describe('docs() dispatcher routing', () => {
     expect(end.links.previous).toBe(
       `astryx docs ${guide} ${index.data.sections.at(-2).id}`,
     );
-    // A flat topic's home is the Unorganized level, and it moves across it.
+    // A flat topic's home is the level for its category, and it moves across it.
     const flat = (await docs('principles')).data.links;
-    expect(flat.up).toBe('astryx docs unorganized');
+    expect(flat.up).toBe('astryx docs guides');
     expect(flat.previous).toMatch(/^astryx docs [a-z-]+$/);
     expect(flat.next).toMatch(/^astryx docs [a-z-]+$/);
-    const home = (await docs('unorganized')).data;
-    expect(home).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
-    expect(home.slots[0].children.map(child => child.route)).toEqual(
-      (await docs()).data.map(entry => entry.topic),
-    );
+    const guides = (await docs('guides')).data;
+    expect(guides).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+    const foundations = (await docs('foundations')).data;
+    expect(foundations).toMatchObject({id: null, kind: 'namespace', links: {up: 'astryx docs'}});
+    // Between them the two levels hold every flat topic, each in list order.
+    const topics = (await docs()).data.map(entry => entry.topic);
+    const held = [guides, foundations].map(level => level.slots[0].children.map(child => child.route));
+    for (const routes of held) {
+      expect(routes).toEqual(topics.filter(topic => routes.includes(topic)));
+    }
+    expect(held.flat().sort()).toEqual([...topics].sort());
   }, SLOW);
 
   it('names a node by its doc identity; a generated level has id null', async () => {
@@ -234,10 +246,9 @@ describe('docs() dispatcher routing', () => {
   }, SLOW);
 
   it("the guide's old flat name is gone, and its error names the new route", async () => {
-    await expect(docs('cli-integrations')).rejects.toMatchObject({
-      code: 'ERR_UNKNOWN_TOPIC',
-      suggestions: [expect.objectContaining({name: 'cli/integrations'})],
-    });
+    const error = await docs('cli-integrations').catch(e => e);
+    expect(error.code).toBe('ERR_UNKNOWN_TOPIC');
+    expect(error.suggestions[0]).toMatchObject({name: 'authoring'});
     expect((await docs()).data.map(entry => entry.topic)).not.toContain(
       'cli-integrations',
     );
@@ -247,11 +258,16 @@ describe('docs() dispatcher routing', () => {
     const err = await docs('cli', 'zzzz-nope').catch(e => e);
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    // It names every guide below the namespace, at any depth.
     const names = err.suggestions.map(s => s.name);
     expect(names).toContain('cli/component-lookups');
-    expect(names).toContain('cli/integrations/quick-start');
     expect(names.every(name => name.startsWith('cli/'))).toBe(true);
+    // It names every guide below the namespace, at any depth.
+    const deep = await docs('authoring', 'zzzz-nope').catch(e => e);
+    expect(deep.code).toBe('ERR_UNKNOWN_SECTION');
+    const below = deep.suggestions.map(s => s.name);
+    expect(below).toContain('authoring/quick-start');
+    expect(below).toContain('authoring/building-blocks/components/add-a-component');
+    expect(below.every(name => name.startsWith('authoring/'))).toBe(true);
   }, SLOW);
 
   it('an unknown route suggests the children of the deepest namespace it reaches', async () => {

package/api/docs/integration-tree.test.mjs

@@ -246,7 +246,7 @@ describe('integration docs in the docs tree', () => {
     });
     scaffold({
       ...kit(),
-      'unorganized.doc.mjs': {...NAMESPACE, name: 'unorganized', title: 'Mine', summary: 'Mine.'},
+      'guides.doc.mjs': {...NAMESPACE, name: 'guides', title: 'Mine', summary: 'Mine.'},
       'use-a-theme.doc.mjs': {...NAMESPACE, name: 'use-a-theme', title: 'Acme use-a-theme', summary: 'Acme use-a-theme.'},
       'cli.doc.mjs': flat('cli'),
     });
@@ -254,26 +254,26 @@ describe('integration docs in the docs tree', () => {
     expect(listed.meta.namespaces).toEqual(
       expect.arrayContaining([
         expect.objectContaining({topic: 'cli', package: '@astryxdesign/cli'}),
-        expect.objectContaining({topic: 'unorganized', package: '@astryxdesign/cli'}),
+        expect.objectContaining({topic: 'guides', package: '@astryxdesign/cli'}),
       ]),
     );
-    expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'unorganized'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
+    expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'guides'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
     expect(listed.data.map(entry => entry.topic)).not.toContain('cli');
     // Each name opens the CLI's doc, and a CLI topic keeps its home.
     expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
-    expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
+    expect((await docs('guides', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
     const tokens = await docs('use-a-theme', undefined, {cwd: tmpDir});
     expect(tokens.type).toBe('docs.detail');
-    expect(tokens.data.links.up).toBe('astryx docs unorganized');
+    expect(tokens.data.links.up).toBe('astryx docs guides');
     // The project doctor and the package doctor both name the claims.
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
-    expect(check.message).toContain('takes the route "unorganized", which the CLI\'s own docs keep');
+    expect(check.message).toContain('takes the route "guides", which the CLI\'s own docs keep');
     expect(check.message).toContain('takes the route "use-a-theme"');
     expect(check.message).toContain('both have the route "cli"');
     const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message).join('\n');
-    expect(graph).toContain('takes the route "unorganized"');
+    expect(graph).toContain('takes the route "guides"');
     expect(graph).toContain('takes the route "use-a-theme"');
     expect(graph).toContain('route "cli"');
   }, SLOW);
@@ -294,16 +294,16 @@ describe('integration docs in the docs tree', () => {
     const nested = path.join(tmpDir, 'node_modules', '@acme', 'kit', 'docs', 'nested');
     fs.mkdirSync(nested, {recursive: true});
     fs.writeFileSync(
-      path.join(nested, 'caps-unorganized.doc.mjs'),
-      `export const docs = ${JSON.stringify(flat('Unorganized'), null, 2)};\n`,
+      path.join(nested, 'caps-guides.doc.mjs'),
+      `export const docs = ${JSON.stringify(flat('Guides'), null, 2)};\n`,
     );
     fs.writeFileSync(
       path.join(nested, 'caps-use-a-theme.doc.mjs'),
       `export const docs = ${JSON.stringify(flat('USE-A-THEME'), null, 2)};\n`,
     );
     expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
-    expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
-    expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs unorganized');
+    expect((await docs('guides', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
+    expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs guides');
     const listed = await docs(undefined, undefined, {cwd: tmpDir});
     expect(listed.data.map(entry => entry.topic.toLowerCase())).not.toContain('cli');
     // Search does not offer a topic whose route another doc owns.
@@ -314,10 +314,10 @@ describe('integration docs in the docs tree', () => {
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
     expect(check.message).toContain('route "CLI"');
-    expect(check.message).toContain('takes the route "Unorganized"');
+    expect(check.message).toContain('takes the route "Guides"');
     // `USE-A-THEME` is the CLI's topic `use-a-theme` in another spelling: the CLI's wins.
     const tokens = await docs('USE-A-THEME', undefined, {cwd: tmpDir, index: true});
-    expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs unorganized'}});
+    expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs guides'}});
     expect(tokens.data.title).not.toBe('Acme USE-A-THEME');
     const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = result.data.issues
@@ -325,7 +325,7 @@ describe('integration docs in the docs tree', () => {
       .map(issue => issue.message)
       .join('\n');
     expect(graph).toContain('route "CLI"');
-    expect(graph).toContain('takes the route "Unorganized"');
+    expect(graph).toContain('takes the route "Guides"');
   }, SLOW);
 
   it("keeps a replaced name for the topic that replaces it, over another integration's namespace", async () => {
@@ -420,9 +420,9 @@ describe('integration docs in the docs tree', () => {
     scaffold({
       ...kit(),
       'a-cli.doc.mjs': flat('cli'),
-      'a-unorganized.doc.mjs': flat('Unorganized'),
+      'a-guides.doc.mjs': flat('Guides'),
       'z-b2.doc.mjs': flat('b2', {replaces: 'cli'}),
-      'z-u2.doc.mjs': flat('u2', {replaces: 'Unorganized'}),
+      'z-u2.doc.mjs': flat('u2', {replaces: 'Guides'}),
     });
     // Another package carries the chain on: c3 replaces b2, which replaced cli.
     const three = path.join(tmpDir, 'node_modules', '@acme', 'three');
@@ -440,8 +440,8 @@ describe('integration docs in the docs tree', () => {
     for (const name of ['cli', 'CLI']) {
       expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
     }
-    for (const name of ['unorganized', 'UNORGANIZED']) {
-      expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
+    for (const name of ['guides', 'GUIDES']) {
+      expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
     }
     // The replacement still answers to its own names.
     for (const name of ['b2', 'c3']) {
@@ -456,7 +456,7 @@ describe('integration docs in the docs tree', () => {
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
     expect(check.message).toContain('The topic "c3" answers to "cli" through replaces');
-    expect(check.message).toContain('The topic "u2" answers to "unorganized" through replaces');
+    expect(check.message).toContain('The topic "u2" answers to "guides" through replaces');
     const inPackage = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = inPackage.data.issues
       .filter(issue => issue.code === 'invalid_doc_graph')
@@ -519,7 +519,7 @@ describe('integration docs in the docs tree', () => {
     });
     const {data} = await docs('theme', 'acme-theming-notes', {cwd: tmpDir});
     // `generic:integrations` is the extension's own guide, never the CLI's
-    // `cli/integrations`; a provider-qualified link reaches the CLI's topic.
+    // `authoring`; a provider-qualified link reaches the CLI's topic.
     expect(data.content[0].text).toBe(
       'See `astryx docs acme/integrations`, and `astryx docs tokens` for the tokens.',
     );

package/api/docs/integrationDocs.test.mjs

@@ -447,7 +447,7 @@ describe('integration-contributed topics', () => {
     // places it.
     expect(top).toContain('troubleshooting');
     expect(
-      top.some(name => /^cli\/integrations\/(?:.+\/)?troubleshooting$/.test(name)),
+      top.some(name => /^authoring\/(?:.+\/)?troubleshooting$/.test(name)),
       top.join(', '),
     ).toBe(true);
   }, SLOW);

package/api/docs/namespace-section.test.mjs

@@ -157,13 +157,13 @@ describe('a section read on a namespace', () => {
       expect(names).toContain('layout/side-panels');
       expect(names.every(name => name.startsWith('layout/'))).toBe(true);
       // At any depth: guides under nested namespaces are named, namespaces are not.
-      const cli = await docs('cli', 'zzzz-nope').catch(e => e);
-      expect(cli.code).toBe('ERR_UNKNOWN_SECTION');
-      expect(cli.suggestions.map(s => s.name)).toContain(
-        'cli/integrations/quick-start',
+      const authoring = await docs('authoring', 'zzzz-nope').catch(e => e);
+      expect(authoring.code).toBe('ERR_UNKNOWN_SECTION');
+      expect(authoring.suggestions.map(s => s.name)).toContain(
+        'authoring/building-blocks/components/add-a-component',
       );
-      expect(cli.suggestions.map(s => s.name)).not.toContain(
-        'cli/integrations',
+      expect(authoring.suggestions.map(s => s.name)).not.toContain(
+        'authoring/building-blocks',
       );
     },
     SLOW,

package/api/docs/reference-blocks.test.mjs

@@ -300,11 +300,11 @@ describe('a reference block that includes what it names', () => {
 });
 
 describe('what a reference block names', () => {
-  it('resolves a CLI authoring schema by identity, to its section of `astryx docs authoring`', async () => {
+  it('resolves a CLI authoring schema by identity, to its section of the field reference', async () => {
     const resolve = await linkResolver(builtinCatalog(), CLI_PROVIDER_ID);
     expect(await resolve('schema:integration')).toMatchObject({
       id: createDocId(CLI_PROVIDER_ID, 'schema', 'integration'),
-      route: 'authoring',
+      route: 'authoring/field-reference',
       title: 'Astryx Integration',
       command: 'astryx docs authoring integration',
     });

package/api/doctor/_adapter.d.mts

@@ -64,8 +64,11 @@ export function computerIntegrationsOutside(cwd: string): Promise<{
  */
 export function computerIntegrationsToAdd(cwd: string, loadedNames: string[]): Promise<import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[]>;
 /**
- * The computer-level agent text's setting and its state on disk.
- * @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>}}
+ * The computer-level agent text's setting, its state on disk, and the command
+ * the skill file tells agents to run and the install step it records for when
+ * that command is not found (each null when there is no file, or it names
+ * none).
+ * @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>, command: string | null, install: string | null}}
  */
 export function computerAgentTextState(): {
     settings: import("../../foundation/env/user-settings.mjs").ComputerAgentTextSettings;
@@ -74,6 +77,8 @@ export function computerAgentTextState(): {
         state: import("../../foundation/agent-docs/computer-agent-text.mjs").ComputerAgentTextState;
         link?: true;
     }>;
+    command: string | null;
+    install: string | null;
 };
 /**
  * The release facts doctor reports, read here so the checks stay pure
@@ -83,7 +88,7 @@ export function computerAgentTextState(): {
  * command that upgrades it.
  * @param {string} cwd
  * @param {{project: boolean}} options
- * @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null}>}}
+ * @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null, runner: boolean}>}}
  */
 export function releaseFacts(cwd: string, { project }: {
     project: boolean;
@@ -101,6 +106,7 @@ export function releaseFacts(cwd: string, { project }: {
     stateLock: ReturnType<typeof stateLockHolder>;
     searchPathCommands: Array<import("../../foundation/env/search-path.mjs").SearchPathCommand & {
         upgrade: string | null;
+        runner: boolean;
     }>;
 };
 /** Whether `cwd` is outside every project. */
@@ -108,13 +114,14 @@ export function outsideProject(cwd: string): boolean;
 /**
  * The commands that bring a project's own CLI and Core to one release, with
  * the project's package manager: Core up to the CLI, then its codemods, when
- * the CLI is newer; else the CLI to the Core's release.
+ * the CLI is newer; else the CLI to the Core's release. Null when no
+ * command fits (see `alignCliAndCore`).
  * @param {string} cwd
  * @param {string} cli
  * @param {string} core
- * @returns {string}
+ * @returns {string | null}
  */
-export function alignCommand(cwd: string, cli: string, core: string): string;
+export function alignCommand(cwd: string, cli: string, core: string): string | null;
 /**
  * The Core release the project at `cwd` names: installed, else locked, else
  * declared; the version the daily hint and notice compare against (spec
@@ -131,19 +138,32 @@ export function projectCoreVersion(cwd: string): string | null;
 export function projectHasOwnCli(cwd: string): boolean;
 /**
  * The command that adds the CLI at `version` with the project's package
- * manager.
+ * manager, and the Core it matches: from a folder whose package.json declares
+ * no Astryx package, in the Astryx project above at that project's Core; null
+ * when there is none (see `cliInstallAdvice`).
  * @param {string} cwd
  * @param {string} version
- * @returns {string}
+ * @returns {{command: string, core: string} | null}
  */
-export function addCliCommandFor(cwd: string, version: string): string;
+export function addCliCommandFor(cwd: string, version: string): {
+    command: string;
+    core: string;
+} | null;
 /**
- * The command that adds a package with the folder's package manager, read
- * from its lockfiles and `packageManager` field.
+ * The command that adds a package to the project of `cwd`; null in a folder
+ * that belongs to no project or whose package.json is not the project's (see
+ * `projectAddCommand`).
  * @param {string} cwd
- * @returns {(name: string) => string}
+ * @returns {((name: string) => string) | null}
+ */
+export function installCommandFor(cwd: string): ((name: string) => string) | null;
+/**
+ * Whether `cwd` is inside a project whose package.json is not the project's,
+ * so advice points at the project's folder (see `installFolder`).
+ * @param {string} cwd
+ * @returns {boolean}
  */
-export function installCommandFor(cwd: string): (name: string) => string;
+export function insideProjectElsewhere(cwd: string): boolean;
 export { resolveRecordedTheme } from "../theme/theme.mjs";
 export { collectUnloadedFonts } from "../theme/build/font-warning.mjs";
 export const SOURCE_EXTENSIONS: Set<string>;

package/api/doctor/_adapter.mjs

@@ -10,8 +10,10 @@ import {
   stateLockHolder,
 } from '../../foundation/release/global-state.mjs';
 import {
-  addCliCommand,
   alignCliAndCore,
+  cliInstallAdvice,
+  installFolder,
+  projectAddCommand,
   globalBehind,
   globalUpgradeCommand,
   lastNoticeSkip,
@@ -19,16 +21,18 @@ import {
 } from '../../foundation/release/notices.mjs';
 import {
   coreVersionOf,
+  installPlaceOf,
   isGlobalCopy,
-  projectRootOf,
 } from '../../foundation/release/choose.mjs';
 import {readReleaseFacts} from '../../foundation/release/project.mjs';
-import {detectPackageManager} from '../../foundation/env/package-manager.mjs';
 import {astryxCommandsOnSearchPath} from '../../foundation/env/search-path.mjs';
 import {readDeclaredDependencies} from '../../foundation/integrations/autolink.mjs';
 import {
+  computerSkillFile,
   displayHomePath,
   inspectComputerAgentText,
+  skillCommandOf,
+  skillInstallStepOf,
 } from '../../foundation/agent-docs/computer-agent-text.mjs';
 import {computerAgentTextSettings} from '../../foundation/env/user-settings.mjs';
 import * as fs from 'node:fs';
@@ -291,12 +295,29 @@ function declaredPackageNames(cwd) {
 }
 
 /**
- * The computer-level agent text's setting and its state on disk.
- * @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>}}
+ * The computer-level agent text's setting, its state on disk, and the command
+ * the skill file tells agents to run and the install step it records for when
+ * that command is not found (each null when there is no file, or it names
+ * none).
+ * @returns {{settings: import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings, entries: Array<{path: string, state: import('../../foundation/agent-docs/computer-agent-text.mjs').ComputerAgentTextState, link?: true}>, command: string | null, install: string | null}}
  */
 export function computerAgentTextState() {
   const settings = computerAgentTextSettings();
-  return {settings, entries: inspectComputerAgentText({links: settings.links})};
+  let command = null;
+  let install = null;
+  try {
+    const text = fs.readFileSync(computerSkillFile(), 'utf8');
+    command = skillCommandOf(text);
+    install = skillInstallStepOf(text);
+  } catch {
+    // No skill file, or one that cannot be read: no command to check.
+  }
+  return {
+    settings,
+    entries: inspectComputerAgentText({links: settings.links}),
+    command,
+    install,
+  };
 }
 
 export {displayHomePath};
@@ -309,7 +330,7 @@ export {displayHomePath};
  * command that upgrades it.
  * @param {string} cwd
  * @param {{project: boolean}} options
- * @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null}>}}
+ * @returns {{answeredBy: {cli: string, core: string | null, copy: string}, latest: string | null, globalBehind: ReturnType<typeof globalBehind> | null, projectLag: ReturnType<typeof projectLag> | null, lastNoticeSkip: ReturnType<typeof lastNoticeSkip>, lastCheckFailure: ReturnType<typeof lastCheckFailure>, stateLock: ReturnType<typeof stateLockHolder>, searchPathCommands: Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade: string | null, runner: boolean}>}}
  */
 export function releaseFacts(cwd, {project}) {
   const answered = answeredBy(cwd);
@@ -336,6 +357,9 @@ export function releaseFacts(cwd, {project}) {
     searchPathCommands: astryxCommandsOnSearchPath().map(row => ({
       ...row,
       upgrade: row.cliRoot ? globalUpgradeCommand(row.cliRoot) : null,
+      // A package runner's temporary install, which it puts first on the
+      // search path only for the run it starts.
+      runner: row.cliRoot ? installPlaceOf(row.cliRoot).runner : false,
     })),
   };
 }
@@ -348,11 +372,12 @@ export function outsideProject(/** @type {string} */ cwd) {
 /**
  * The commands that bring a project's own CLI and Core to one release, with
  * the project's package manager: Core up to the CLI, then its codemods, when
- * the CLI is newer; else the CLI to the Core's release.
+ * the CLI is newer; else the CLI to the Core's release. Null when no
+ * command fits (see `alignCliAndCore`).
  * @param {string} cwd
  * @param {string} cli
  * @param {string} core
- * @returns {string}
+ * @returns {string | null}
  */
 export function alignCommand(cwd, cli, core) {
   return alignCliAndCore({cwd, cli, core});
@@ -380,30 +405,35 @@ export function projectHasOwnCli(cwd) {
 
 /**
  * The command that adds the CLI at `version` with the project's package
- * manager.
+ * manager, and the Core it matches: from a folder whose package.json declares
+ * no Astryx package, in the Astryx project above at that project's Core; null
+ * when there is none (see `cliInstallAdvice`).
  * @param {string} cwd
  * @param {string} version
- * @returns {string}
+ * @returns {{command: string, core: string} | null}
  */
 export function addCliCommandFor(cwd, version) {
-  return addCliCommand(projectRootOf(readReleaseFacts(cwd)) ?? cwd, version);
+  const advice = cliInstallAdvice({cwd, core: version});
+  return advice?.command ? {command: advice.command, core: advice.core} : null;
 }
 
 /**
- * The command that adds a package with the folder's package manager, read
- * from its lockfiles and `packageManager` field.
+ * The command that adds a package to the project of `cwd`; null in a folder
+ * that belongs to no project or whose package.json is not the project's (see
+ * `projectAddCommand`).
  * @param {string} cwd
- * @returns {(name: string) => string}
+ * @returns {((name: string) => string) | null}
  */
 export function installCommandFor(cwd) {
-  const pm = detectPackageManager(cwd);
-  const verb =
-    pm === 'pnpm'
-      ? 'pnpm add'
-      : pm === 'yarn'
-        ? 'yarn add'
-        : pm === 'bun'
-          ? 'bun add'
-          : 'npm install';
-  return name => `${verb} ${name}`;
+  return projectAddCommand(cwd);
+}
+
+/**
+ * Whether `cwd` is inside a project whose package.json is not the project's,
+ * so advice points at the project's folder (see `installFolder`).
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function insideProjectElsewhere(cwd) {
+  return installFolder(cwd)?.moved === true;
 }

package/api/doctor/doctor.d.mts

@@ -188,6 +188,10 @@ export function checkCliCommand(ctx: DoctorContext): DoctorCheck;
   *   each file of the computer-level agent text against this release's rendering
  * @property {import('../../foundation/env/user-settings.mjs').ComputerAgentTextSettings} [agentTextSettings]
  *   the person's choices about the computer-level agent text
+ * @property {string | null} [agentTextCommand] the command the skill file
+ *   tells agents to run, or null
+ * @property {string | null} [agentTextInstall] the install step the skill
+ *   file records for when that command is not found, or null
   * @property {string} [cwd] the folder doctor runs in, for the printed fix
  * @property {import('../../foundation/release/notices.mjs').GlobalBehind | null} [globalBehind]
  *   the CLI installed for the computer, when it is older than the newest
@@ -200,7 +204,7 @@ export function checkCliCommand(ctx: DoctorContext): DoctorCheck;
  *   the newest update notice that did not print, and why (diagnostic only)
  * @property {{pid: number | null, host: string | null, since: number} | null} [stateLock]
  *   who holds the state file's lock now (diagnostic only)
-  * @property {Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade?: string | null}>} [searchPathCommands]
+  * @property {Array<import('../../foundation/env/search-path.mjs').SearchPathCommand & {upgrade?: string | null, runner?: boolean}>} [searchPathCommands]
  *   every `astryx` on the search path, with the command that upgrades it
  *   the `astryx` commands on the search path, in order
  * @property {import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[]} [computerIntegrations]
@@ -259,15 +263,18 @@ export function checkComputerIntegrations(ctx: ComputerContext): DoctorCheck;
  * Inside a project, the integrations installed for the computer that the
  * project does not install: available, never used (spec AST-081 FR12).
  * Always info.
- * @param {{installed: Set<string>, candidates: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], install: (name: string) => string}} input
+ * @param {{installed: Set<string>, candidates: import('../../foundation/integrations/computer-integrations.mjs').ComputerIntegrationCandidate[], install: ((name: string) => string) | null, elsewhere?: boolean}} input
  *   `install`: the command that adds a package with the project's package
- *   manager (read by the adapter)
+ *   manager (read by the adapter); null when the folder belongs to no
+ *   project, or `elsewhere`: its package.json is not the project's, where the
+ *   fix points at the project's folder
  * @returns {DoctorCheck}
  */
-export function checkComputerIntegrationsAvailable({ installed, candidates, install }: {
+export function checkComputerIntegrationsAvailable({ installed, candidates, install, elsewhere }: {
     installed: Set<string>;
     candidates: import("../../foundation/integrations/computer-integrations.mjs").ComputerIntegrationCandidate[];
-    install: (name: string) => string;
+    install: ((name: string) => string) | null;
+    elsewhere?: boolean;
 }): DoctorCheck;
 /**
  * Run all diagnostic checks and return a structured report.
@@ -443,6 +450,16 @@ export type ComputerContext = {
      * the person's choices about the computer-level agent text
      */
     agentTextSettings?: import("../../foundation/env/user-settings.mjs").ComputerAgentTextSettings | undefined;
+    /**
+     * the command the skill file
+     * tells agents to run, or null
+     */
+    agentTextCommand?: string | null | undefined;
+    /**
+     * the install step the skill
+     * file records for when that command is not found, or null
+     */
+    agentTextInstall?: string | null | undefined;
     /**
      * the folder doctor runs in, for the printed fix
      */
@@ -484,6 +501,7 @@ export type ComputerContext = {
      */
     searchPathCommands?: (import("../../foundation/env/search-path.mjs").SearchPathCommand & {
         upgrade?: string | null;
+        runner?: boolean;
     })[] | undefined;
     /**
      * the integrations installed beside the running CLI