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

package/foundation/agent-docs/computer-agent-text.d.mts

@@ -1,6 +1,35 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * What to do when the `astryx` command the text names is not found, as on a
+ * machine whose home folder outlives its system folders: the skill file
+ * survives a restart while the CLI installed for the computer does not.
+ * @param {string} install the install step
+ * @returns {string}
+ */
+export function computerRestoreLine(install: string): string;
+/**
+ * The install step the text names. `judge`: the step a file is judged by, the
+ * one it records first, so every copy of one release, two global installs
+ * included, finds the same text current. `write`: the step a write records,
+ * the global copy's own first, since only the CLI installed for the computer
+ * chooses it. Either way npm's when there is no other.
+ * @param {{cliRoot?: string, home?: string, for?: 'judge' | 'write'}} [options]
+ * @returns {string}
+ */
+export function computerInstallStep({ cliRoot, home, for: use, }?: {
+    cliRoot?: string;
+    home?: string;
+    for?: "judge" | "write";
+}): string;
+/**
+ * The install step a skill file's text records, or null when it records
+ * none.
+ * @param {string} content
+ * @returns {string | null}
+ */
+export function skillInstallStepOf(content: string): string | null;
 /**
  * A home-folder path as a person reads it: `~/.claude/skills/astryx`.
  * @param {string} file
@@ -32,13 +61,21 @@ export function computerSkillLinks(home?: string): Array<{
  * @returns {string}
  */
 export function computerAgentCommand(): string;
+/**
+ * The command a skill file's text names: the one in its "Start with" line,
+ * or null when the text has none.
+ * @param {string} content
+ * @returns {string | null}
+ */
+export function skillCommandOf(content: string): string | null;
 /**
  * The full skill file.
- * @param {{command?: string}} [options]
+ * @param {{command?: string, install?: string}} [options]
  * @returns {string}
  */
-export function renderComputerAgentText({ command, }?: {
+export function renderComputerAgentText({ command, install, }?: {
     command?: string;
+    install?: string;
 }): string;
 /**
  * Read-only: the state of the skill file against this release's rendering,

package/foundation/agent-docs/computer-agent-text.mjs

@@ -43,7 +43,17 @@ import {createHash} from 'node:crypto';
 import {cliDoor} from '../env/cli-command.mjs';
 import {astryxCommandsOnSearchPath} from '../env/search-path.mjs';
 import {samePath} from '../fs/path-compare.mjs';
-import {MARKER_START, MARKER_END} from './agent-doc-state.mjs';
+import {CLI_ROOT} from '../fs/paths.mjs';
+import {CLI_PACKAGE} from '../env/package-manager.mjs';
+import {isGlobalCopy} from '../release/choose.mjs';
+import {globalUpgradeCommand} from '../release/notices.mjs';
+import {
+  MARKER_START,
+  MARKER_END,
+  SELF_CHECK_CSS,
+  WORKFLOW_STEPS,
+  WORKFLOW_TITLE,
+} from './agent-doc-state.mjs';
 
 /** The command the computer-level text uses when no host door is set. */
 export const COMPUTER_COMMAND = 'astryx';
@@ -51,6 +61,83 @@ export const COMPUTER_COMMAND = 'astryx';
 /** The install step for the CLI copy the computer-level text relies on. */
 export const COMPUTER_INSTALL_STEP = 'npm i -g @astryxdesign/cli';
 
+/**
+ * What to do when the `astryx` command the text names is not found, as on a
+ * machine whose home folder outlives its system folders: the skill file
+ * survives a restart while the CLI installed for the computer does not.
+ * @param {string} install the install step
+ * @returns {string}
+ */
+export function computerRestoreLine(install) {
+  return `If \`${COMPUTER_COMMAND}\` is not found, run \`${install}\` first.`;
+}
+
+/**
+ * The step the CLI installed for the computer names for itself: the command
+ * that installs it again with the same package manager into the same folder,
+ * as the update notice names it but with no version. Null for any other copy.
+ * @param {string} [cliRoot]
+ * @returns {string | null}
+ */
+function ownInstallStep(cliRoot = CLI_ROOT) {
+  try {
+    if (isGlobalCopy(cliRoot)) {
+      return globalUpgradeCommand(cliRoot).replace(
+        `${CLI_PACKAGE}@latest`,
+        CLI_PACKAGE,
+      );
+    }
+  } catch {
+    // A copy whose install cannot be read names none of its own.
+  }
+  return null;
+}
+
+/**
+ * The step the skill file in `home` records, or null.
+ * @param {string} home
+ * @returns {string | null}
+ */
+function recordedInstallStep(home) {
+  try {
+    return skillInstallStepOf(fs.readFileSync(computerSkillFile(home), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The install step the text names. `judge`: the step a file is judged by, the
+ * one it records first, so every copy of one release, two global installs
+ * included, finds the same text current. `write`: the step a write records,
+ * the global copy's own first, since only the CLI installed for the computer
+ * chooses it. Either way npm's when there is no other.
+ * @param {{cliRoot?: string, home?: string, for?: 'judge' | 'write'}} [options]
+ * @returns {string}
+ */
+export function computerInstallStep({
+  cliRoot = CLI_ROOT,
+  home = os.homedir(),
+  for: use = 'write',
+} = {}) {
+  const own = ownInstallStep(cliRoot);
+  const recorded = recordedInstallStep(home);
+  return (
+    (use === 'judge' ? (recorded ?? own) : (own ?? recorded)) ??
+    COMPUTER_INSTALL_STEP
+  );
+}
+
+/**
+ * The install step a skill file's text records, or null when it records
+ * none.
+ * @param {string} content
+ * @returns {string | null}
+ */
+export function skillInstallStepOf(content) {
+  return /is not found, run `(.+?)` first\./u.exec(content)?.[1] ?? null;
+}
+
 /** The skill folder, relative to the home folder, that holds the one file. */
 const SKILL_FOLDER = path.join('.agents', 'skills', 'astryx');
 
@@ -164,27 +251,52 @@ export function computerAgentCommand() {
 }
 
 /**
- * The body lines, with `run` as the command.
+ * The body lines, with `run` as the command and `install` as the step that
+ * installs it.
  * @param {string} run
+ * @param {string} install
  * @returns {string[]}
  */
-function bodyLines(run) {
+function bodyLines(run, install) {
   return [
     'Astryx, a design system and UI library, is available on this computer.',
     'Use it when you build or change UI, pick components, or style or theme an app.',
     `Its docs, components, templates, and themes are all reachable through \`${run}\`. Start with \`${run} search '<what you need>'\`.`,
     `Then read \`${run} component <Name>\` or \`${run} docs <topic>\`, not the package's files.`,
     "In a project, the project's version of Astryx answers automatically.",
+    // How to build, which discovery alone leaves to the agent's own page
+    // route: in a project, from the template, with the project agent docs'
+    // own workflow lines.
+    // A project that already installs Core gets the CLI at that version, as
+    // the CLI's own hint for that state says, never a newer CLI beside it.
+    `To build UI, work in a project folder (create one if there is none). Add \`@astryxdesign/core\` and \`@astryxdesign/cli\` to a new project or one without \`@astryxdesign/core\`; to a project that already has \`@astryxdesign/core\`, add \`@astryxdesign/cli\` at the same version. Run \`${run} init\` there and follow the agent docs it writes.`,
+    WORKFLOW_TITLE,
+    ...WORKFLOW_STEPS.map(step => step.replaceAll('`astryx ', `\`${run} `)),
+    `Before you deliver, re-read each file; ${SELF_CHECK_CSS}. Then build the project and deliver that build, not a description of it.`,
+    // A host's door is the host's to restore; only the global command has an
+    // install step to name.
+    ...(run === COMPUTER_COMMAND ? [computerRestoreLine(install)] : []),
   ];
 }
 
+/**
+ * The command a skill file's text names: the one in its "Start with" line,
+ * or null when the text has none.
+ * @param {string} content
+ * @returns {string | null}
+ */
+export function skillCommandOf(content) {
+  return /Start with `(.+?) search '/u.exec(content)?.[1] ?? null;
+}
+
 /**
  * The full skill file.
- * @param {{command?: string}} [options]
+ * @param {{command?: string, install?: string}} [options]
  * @returns {string}
  */
 export function renderComputerAgentText({
   command = computerAgentCommand(),
+  install = COMPUTER_INSTALL_STEP,
 } = {}) {
   return withHash(
     [
@@ -196,7 +308,7 @@ export function renderComputerAgentText({
       '---',
       '',
       MARKER_START,
-      ...bodyLines(command),
+      ...bodyLines(command, install),
       MARKER_END,
       '',
     ].join('\n'),
@@ -404,7 +516,10 @@ export function inspectComputerAgentText({
   command,
   links = [],
 } = {}) {
-  const expected = renderComputerAgentText({command});
+  const expected = renderComputerAgentText({
+    command,
+    install: computerInstallStep({home, for: 'judge'}),
+  });
   const folder = path.join(home, SKILL_FOLDER);
   const made = new Set(links);
   return [
@@ -517,12 +632,24 @@ function writeCopy(at, expected) {
  * @returns {{rows: import('../../api/init/init.type.mjs').InitUserFile[], links: string[]}}
  */
 export function writeComputerAgentText({home = os.homedir(), command} = {}) {
-  const expected = renderComputerAgentText({command});
+  // Judged by the step the file records, so a file another copy of this
+  // release wrote stays as it is; a write records this copy's own step.
+  const judged = renderComputerAgentText({
+    command,
+    install: computerInstallStep({home, for: 'judge'}),
+  });
   const file = computerSkillFile(home);
   const folder = path.dirname(file);
   /** @type {import('../../api/init/init.type.mjs').InitUserFile[]} */
   const rows = [];
-  const state = stateOf(file, expected);
+  const state = stateOf(file, judged);
+  const expected =
+    state === 'current'
+      ? judged
+      : renderComputerAgentText({
+          command,
+          install: computerInstallStep({home, for: 'write'}),
+        });
   if (state === 'foreign' || state === 'edited') {
     rows.push({path: file, action: 'kept', reason: keptReason(state)});
   } else if (state === 'current') {

package/foundation/agent-docs/computer-agent-text.test.mjs

@@ -24,10 +24,18 @@ import {
   computerSkillLinks,
   inspectComputerAgentText,
   removeComputerAgentText,
+  computerInstallStep,
   renderComputerAgentText,
+  skillInstallStepOf,
   writeComputerAgentText,
 } from './computer-agent-text.mjs';
-import {MARKER_END, MARKER_START} from './agent-doc-state.mjs';
+import {
+  MARKER_END,
+  MARKER_START,
+  SELF_CHECK_CSS,
+  WORKFLOW_STEPS,
+  WORKFLOW_TITLE,
+} from './agent-doc-state.mjs';
 import {runWithCliDoor} from '../env/cli-command.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
 import {parse as parseYaml} from 'yaml';
@@ -123,17 +131,106 @@ describe('renderComputerAgentText', () => {
 
   it('stays short, and tells agents to read docs through the CLI', () => {
     const text = renderComputerAgentText({command: 'astryx'});
-    expect(text.split('\n').length).toBeLessThanOrEqual(15);
+    expect(text.split('\n').length).toBeLessThanOrEqual(22);
     expect(text).toContain(
       "Then read `astryx component <Name>` or `astryx docs <topic>`, not the package's files.",
     );
   });
 
+  // Discovery alone leaves the build to the agent's own page route, which
+  // may not install packages; the skill names the route and the project
+  // agent docs' own workflow lines.
+  it('gives the build workflow: a project with Astryx installed and init run, the shared template steps, then check and deliver the build', () => {
+    const text = renderComputerAgentText({command: 'astryx'});
+    expect(text).toContain(
+      'To build UI, work in a project folder (create one if there is none). Add `@astryxdesign/core` and `@astryxdesign/cli` to a new project or one without `@astryxdesign/core`; to a project that already has `@astryxdesign/core`, add `@astryxdesign/cli` at the same version. Run `astryx init` there and follow the agent docs it writes.',
+    );
+    for (const line of [WORKFLOW_TITLE, ...WORKFLOW_STEPS]) {
+      expect(text).toContain(line);
+    }
+    expect(text).toContain(`re-read each file; ${SELF_CHECK_CSS}.`);
+    expect(text).toContain('deliver that build');
+  });
+
   it("uses the host's door when one is set", () => {
     const text = runWithCliDoor('acme astryx', () => renderComputerAgentText());
     expect(text).toContain("`acme astryx search '<what you need>'`");
     expect(text).not.toMatch(/`astryx /u);
   });
+
+  // A machine can keep the home folder and lose the CLI installed for the
+  // computer, so the skill says how to get it back, with no version.
+  it('names the install step for when `astryx` is not found, and only for the global command', () => {
+    expect(
+      renderComputerAgentText({
+        command: 'astryx',
+        install: 'npm i -g @astryxdesign/cli',
+      }),
+    ).toContain(
+      'If `astryx` is not found, run `npm i -g @astryxdesign/cli` first.',
+    );
+    // It repeats the step that installed the copy writing it, which doctor
+    // reads back.
+    const bun = renderComputerAgentText({
+      command: 'astryx',
+      install: 'bun add -g @astryxdesign/cli',
+    });
+    expect(bun).toContain(
+      'If `astryx` is not found, run `bun add -g @astryxdesign/cli` first.',
+    );
+    expect(skillInstallStepOf(bun)).toBe('bun add -g @astryxdesign/cli');
+  });
+
+  // Rendering is pure: its default step never depends on the skill in the
+  // home folder of the computer the test runs on.
+  it("renders npm's step by default, whatever skill the caller's home folder holds", () => {
+    const home = tmp('caller-home');
+    const file = computerSkillFile(home);
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    fs.writeFileSync(
+      file,
+      renderComputerAgentText({
+        command: 'astryx',
+        install: 'pnpm add -g @astryxdesign/cli',
+      }),
+    );
+    const saved = process.env.HOME;
+    process.env.HOME = home;
+    try {
+      expect(renderComputerAgentText({command: 'astryx'})).toContain(
+        'run `npm i -g @astryxdesign/cli` first.',
+      );
+    } finally {
+      process.env.HOME = saved;
+    }
+  });
+
+  // Only the CLI installed for the computer chooses the step; every other
+  // copy of the release, such as a project's own CLI, keeps the one the file
+  // records, so it neither reports the file as different nor rewrites it.
+  it('keeps the step the file records for a copy that is not installed for the computer', () => {
+    const home = tmp('home');
+    const file = computerSkillFile(home);
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    const pnpm = renderComputerAgentText({
+      command: 'astryx',
+      install: 'pnpm add -g @astryxdesign/cli',
+    });
+    fs.writeFileSync(file, pnpm);
+    expect(computerInstallStep({home})).toBe('pnpm add -g @astryxdesign/cli');
+    expect(inspectComputerAgentText({home, command: 'astryx'})[0].state).toBe(
+      'current',
+    );
+    writeComputerAgentText({home, command: 'astryx'});
+    expect(fs.readFileSync(file, 'utf8')).toBe(pnpm);
+    // No file yet: npm's step.
+    expect(computerInstallStep({home: tmp('empty-home')})).toBe(
+      'npm i -g @astryxdesign/cli',
+    );
+    expect(renderComputerAgentText({command: 'acme astryx'})).not.toContain(
+      'npm i -g',
+    );
+  });
 });
 
 describe('the link table', () => {

package/foundation/config/project.mjs

@@ -40,7 +40,7 @@ import {parseConfig} from '../../authoring/config/parse.mjs';
 import {
   loadIntegrations,
   loadLocalIntegration,
-  resolvePackageDir,
+  resolveInstalledIntegrationDir,
 } from '../integrations/integrations.mjs';
 import {loadAutolinkCandidates} from '../integrations/autolink.mjs';
 import {
@@ -65,7 +65,7 @@ import {
   discoverValidIntegrationComponents,
 } from '../discovery/component-discovery.mjs';
 import {resolveComponentReplacements} from '../discovery/component-replacement.mjs';
-import {CLI_ROOT, findCoreDir, findProjectCoreDir} from '../fs/paths.mjs';
+import {CLI_ROOT, findCoreDir, findPackageRoot, findProjectCoreDir} from '../fs/paths.mjs';
 import {
   applyTemplateReplacements,
   effectiveTemplateDiscovery,
@@ -89,6 +89,10 @@ import {
 } from '../../assets/codemods/integration-discovery.mjs';
 import {validateLoadedIntegration} from '../integrations/validate-contributions.mjs';
 import {recordDeclaredCliCommands} from '../env/cli-command.mjs';
+import {
+  hostedRun,
+  recordResolvedIntegrations,
+} from '../runtime/package-root.mjs';
 import {
   InMemoryConfigCache,
   cacheKey,
@@ -121,9 +125,16 @@ function errorMessage(err) {
  */
 export function computerIntegrationCandidates(cwd = process.cwd()) {
   try {
-    const cliRoot = isOutsideProject(cwd) ? CLI_ROOT : globalCliRoot(cwd);
+    const outside = isOutsideProject(cwd);
+    const cliRoot = outside ? CLI_ROOT : globalCliRoot(cwd);
     return cliRoot
-      ? scanComputerIntegrations({cliRoot, release: cliVersion()})
+      ? scanComputerIntegrations({
+          cliRoot,
+          release: cliVersion(),
+          // Outside a project, the integrations a host approves load from the
+          // package set that serves the run too (cli-surface INV30).
+          approved: outside ? (hostedRun()?.integrations ?? []) : [],
+        })
       : [];
   } catch {
     return [];
@@ -212,7 +223,7 @@ async function loadConfiguredIntegrations(specs, {cwd, fresh}) {
       /** @type {string|undefined} */
       let packageDir;
       try {
-        packageDir = resolvePackageDir(spec, cwd);
+        packageDir = resolveInstalledIntegrationDir(spec, cwd);
       } catch {
         // Not a bare package name: there is no install location to record.
       }
@@ -315,22 +326,6 @@ export const CONFIG_BASENAMES = [
 export const DEFAULT_ISSUES_URL =
   'https://github.com/facebook/astryx/issues/new';
 
-/**
- * Find the directory of the nearest package.json walking up from startDir.
- * @param {string} startDir
- * @returns {string|null}
- */
-function findPackageRoot(startDir) {
-  let dir = startDir;
-  for (let i = 0; i < 50; i++) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
-
 /**
  * Whether this project accepts `debug` handlers contributed by the
  * integrations it loads.
@@ -495,7 +490,8 @@ export class Project {
     // The project root: the config's directory when there is one (findConfigPath
     // resolves the config as a sibling of the nearest package.json, so the two
     // agree), otherwise that package.json's directory. Dependencies are declared
-    // there, and node_modules sits there.
+    // there, and installed packages resolve from there up the node_modules
+    // chain.
     const projectDir = configPath
       ? path.dirname(configPath)
       : (findPackageRoot(cwd) ?? cwd);
@@ -580,6 +576,8 @@ export class Project {
         : []),
     ]);
     loadedIntegrations = resolution.integrations;
+    // A hosted run returns each package it resolved (cli-surface INV30).
+    recordResolvedIntegrations(loadedIntegrations);
     // The picker (getCliInvocation) is synchronous, so the commands these
     // integrations declare are recorded here, where they become known.
     recordDeclaredCliCommands(projectDir, loadedIntegrations);

package/foundation/config/project.test.mjs

@@ -291,6 +291,32 @@ describe('Project.load', () => {
   });
 });
 
+describe('Project.issues and a near-miss manifest key', () => {
+  it.each([
+    [
+      'alone, while the loaded integration fills providerId from the package name',
+      {providerID: '@acme/widgets'},
+      'Fix: rename "providerID" to "providerId" in astryx.integration.mjs.',
+    ],
+    [
+      'beside the key it suggests',
+      {providerID: '@acme/widgets', providerId: '@acme/widgets'},
+      'Fix: remove "providerID" from astryx.integration.mjs; it already sets "providerId".',
+    ],
+  ])(
+    'reads the keys the manifest declares: providerID %s',
+    async (_label, unknownKeys, fix) => {
+      scaffold({unknownKeys});
+      const project = await Project.load(tmpDir);
+      const keys = (await project.issues()).filter(
+        issue => issue.code === 'unknown_manifest_key',
+      );
+      expect(keys).toHaveLength(1);
+      expect(keys[0].message).toContain(fix);
+    },
+  );
+});
+
 describe('Project.load and the cliCommand an integration declares', () => {
   it('records it, so the picker prints commands with it', async () => {
     scaffold({cliCommand: 'acme astryx'});
@@ -830,6 +856,36 @@ describe('Project loads each integration in isolation', () => {
   });
 });
 
+describe('Project finds configured integrations a workspace hoists', () => {
+  // npm, Yarn and Bun workspaces install a member's dependencies at the
+  // workspace root, so the member's own node_modules does not hold them.
+  it('loads an integration named in a member config from the workspace root', async () => {
+    scaffold();
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'root', private: true, workspaces: ['apps/*']}),
+    );
+    fs.rmSync(path.join(tmpDir, 'astryx.config.mjs'));
+    const member = path.join(tmpDir, 'apps', 'web');
+    fs.mkdirSync(member, {recursive: true});
+    fs.writeFileSync(path.join(member, 'package.json'), JSON.stringify({name: 'web'}));
+    fs.writeFileSync(
+      path.join(member, 'astryx.config.mjs'),
+      `export default ${JSON.stringify({integrations: ['@acme/widgets']})};\n`,
+    );
+
+    const project = await Project.load(member);
+
+    const widgets = (await project.components()).filter(
+      component => component.package === '@acme/widgets',
+    );
+    expect(widgets.map(component => component.name)).toEqual(['Widget']);
+    expect(await project.issues()).not.toContainEqual(
+      expect.objectContaining({package: '@acme/widgets', code: 'integration_error'}),
+    );
+  });
+});
+
 describe('Project.issuesUrl routing', () => {
   it('routes core to config.issuesUrl, falling back to the default', async () => {
     scaffold({issuesUrl: 'https://example.com/core'});

package/foundation/discovery/authoring-self-docs.d.mts

@@ -83,5 +83,12 @@ export function auditAuthoringSelfDocs({ root, sources, budget, }?: {
 }>;
 /** The directory the self-docs live under. */
 export const AUTHORING_ROOT: string;
+/** The guide that holds every authoring schema, one section each. */
+export const AUTHORING_REFERENCE_NAME: "field-reference";
+/**
+ * Its route. `astryx docs authoring <name>` reads one of its sections through
+ * the authoring namespace (spec:AST-046 FR6).
+ */
+export const AUTHORING_REFERENCE_ROUTE: "authoring/field-reference";
 /** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
 export const AUTHORING_SELF_DOCS: string[];

package/foundation/discovery/authoring-self-docs.mjs

@@ -9,7 +9,7 @@
  *   `authoring` reference topic with one section per self-doc, and an audit
  *   naming any self-doc the topic cannot reach, any that fails to load, and any
  *   section over the docs output budget.
- * @position Read by assets/docs/authoring.doc.mjs (the topic) and by Doctor
+ * @position Read by assets/docs/tree/field-reference.doc.mjs (the guide) and by Doctor
  *   (the audit). Lives in foundation because authoring/ holds only contracts.
  *   A new `*.doc.mjs` under authoring/ must be added to the list, or Doctor and
  *   the self-doc tests fail.
@@ -27,6 +27,15 @@ import {
 /** The directory the self-docs live under. */
 export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
 
+/** The guide that holds every authoring schema, one section each. */
+export const AUTHORING_REFERENCE_NAME = 'field-reference';
+
+/**
+ * Its route. `astryx docs authoring <name>` reads one of its sections through
+ * the authoring namespace (spec:AST-046 FR6).
+ */
+export const AUTHORING_REFERENCE_ROUTE = `authoring/${AUTHORING_REFERENCE_NAME}`;
+
 /** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
 export const AUTHORING_SELF_DOCS = [
   'integration/integration.doc.mjs',
@@ -189,11 +198,14 @@ export function selfDocSection(doc) {
  */
 export function buildAuthoringReferenceDoc(docs) {
   return /** @type {any} */ ({
-    name: 'authoring',
-    title: 'Authoring Reference',
+    type: 'generic',
+    name: AUTHORING_REFERENCE_NAME,
+    placement: {parent: 'namespace:authoring', slot: 'reference', order: 10},
+    title: 'Field reference',
     category: 'guide',
+    keywords: ['authoring reference', 'field reference', 'every field'],
     description:
-      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The step-by-step guides are under `astryx docs cli/integrations`.',
+      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type. The guides that use them are the rest of {@link namespace:authoring}.',
     sections: docs.map(selfDocSection),
   });
 }

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -38,20 +38,32 @@ describe('authoring self-docs', () => {
     });
   });
 
-  it('builds a valid topic with one section per self-doc', async () => {
-    const topic = await buildAuthoringTopic();
+  it('builds a valid guide with one section per self-doc, placed under authoring', async () => {
+    const {placement, ...topic} = await buildAuthoringTopic();
     expect(problemsInTopic(topic)).toEqual([]);
     expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
+    expect(placement).toEqual({
+      parent: 'namespace:authoring',
+      slot: 'reference',
+      order: 10,
+    });
   });
 
   it(
     'is readable progressively through the docs API',
     async () => {
-      const index = await docs('authoring', undefined, {index: true});
+      const index = await docs('authoring/field-reference', undefined, {
+        index: true,
+      });
       expect(index.type).toBe('docs.index');
       expect(index.data.sections.map(s => s.id)).toContain('integration');
+      // The namespace answers a section read from the field reference, as
+      // `astryx docs authoring <name>` always has.
       const section = await docs('authoring', 'integration');
       expect(section.data.title).toBe('Astryx Integration');
+      expect(
+        (await docs('authoring/field-reference', 'integration')).data,
+      ).toEqual(section.data);
       expect(section.data.content.some(block => block.type === 'table')).toBe(
         true,
       );

package/foundation/discovery/authoring-surface.d.mts

@@ -30,7 +30,7 @@ export function tracePublicAuthoringTypes(root?: string): {
  * document something public: a public type declared beside it, and, when its
  * title is the name of a type declared beside it, that type.
  * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
- *   `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ *   `topicKeys` are the keys `astryx docs authoring/field-reference --index` lists; null skips
  *   that comparison.
  * @returns {Promise<{
  *   types: number,