@astryxdesign/cli 0.7.2-canary.f16dc9f → 0.7.2-canary.f2b60a0

package/clients/cli/commands/integration.mjs

@@ -3,18 +3,22 @@
 /** @file CLI bindings for integration authoring and package verification. */
 
 import {integrationAdd} from '../../../api/integration/add-contribution.mjs';
+import {integrationCheck} from '../../../api/integration/check/check.mjs';
 import {integrationPackCheck} from '../../../api/integration/pack-check.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
-import {emit, list, section, text} from '../formatters/index.mjs';
+import {emit, list, records, section, text} from '../formatters/index.mjs';
 import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as integrationGroup} from './integration.doc.mjs';
 import {doc as integrationAddCommand} from './integration-add.doc.mjs';
+import {doc as integrationCheckCommand} from './integration-check.doc.mjs';
 import {doc as integrationVerifyCommand} from './integration-verify.doc.mjs';
 import {doc as integrationPackCommand} from './integration-pack.doc.mjs';
 import {doc as integrationAddFn} from '../../../api/integration/integrationAdd.doc.mjs';
+import {doc as integrationCheckFn} from '../../../api/integration/integrationCheck.doc.mjs';
+import {printIntegrationCheckResponse} from './doctor.mjs';
 import {doc as integrationPackCheckFn} from '../../../api/integration/integrationPackCheck.doc.mjs';
 
 /**
@@ -88,6 +92,102 @@ async function verifyPackage(program) {
   return NO_RESULT_SET;
 }
 
+/**
+ * Run `integration check` and print each check as its own subcommand prints
+ * it, then one summary: each check's errors, warnings and skipped work, and
+ * what decided the exit code.
+ * @param {import('commander').Command} program
+ * @param {{strict?: boolean}} options
+ */
+async function checkPackage(program, options) {
+  const result = await integrationCheck({strict: options.strict === true});
+  if (program.opts().json) {
+    jsonOut(result);
+  } else {
+    const {data} = result;
+    const noPackage = data.checks[0]?.response.data.issues.some(
+      issue => issue.code === 'no_package',
+    );
+    if (noPackage) {
+      emit(
+        text(
+          'Nothing was checked: no package.json found. Run this command inside a package directory.',
+        ),
+      );
+    } else if (!data.validated) {
+      emit(
+        text(
+          'Nothing was checked: no astryx.integration.* found next to package.json. ' +
+            "Run this command in an integration package's folder.",
+        ),
+      );
+    } else {
+      data.checks.forEach((check, index) => {
+        // A blank line keeps each check's output apart from the next.
+        if (index > 0) emit(text(''));
+        printIntegrationCheckResponse(check.response);
+      });
+    }
+    const plural = (/** @type {number} */ n, /** @type {string} */ word) =>
+      `${n} ${word}${n === 1 ? '' : 's'}`;
+    const counts =
+      `${plural(data.errors, 'error')}, ${plural(data.warnings, 'warning')}, ` +
+      `${data.skipped.length} skipped`;
+    const notCompared =
+      data.unchecked > 0
+        ? ` ${plural(data.unchecked, 'item')} could not be compared; the checks above list them.`
+        : '';
+    const closing = noPackage
+      ? `[fail] ${counts}. No package.json was found here, so nothing was checked.`
+      : data.checks.some(check => check.failed)
+        ? `[fail] ${counts}. Address the items marked [fail] above.`
+        : data.failed
+          ? `[fail] ${counts}. --strict fails on every warning and on skipped work; fix them, or drop --strict to fail only on errors.`
+          : data.warnings > 0 || data.skipped.length > 0
+            ? `[ok] ${counts}. No check failed; review the warnings and skipped work above (--strict fails on them).${notCompared}`
+            : notCompared
+              ? `[ok] ${counts}. No check failed.${notCompared}`
+              : `[ok] ${counts}. Every check passed.`;
+    const identity = noPackage
+      ? '(no package.json)'
+      : data.version != null
+        ? `${data.name}@${data.version}`
+        : data.name;
+    emit(
+      // --strict lists each warning and each skipped check again, as the
+      // error it now is, in the issue format the checks use.
+      ...(data.failures.length > 0
+        ? [
+            section('Failing under --strict'),
+            records(data.failures, {
+              fields: [
+                'severity',
+                'check',
+                'code',
+                'component',
+                'prop',
+                'message',
+                'fix',
+                'file',
+                'line',
+              ],
+              format: {severity: () => '[fail]'},
+            }),
+          ]
+        : []),
+      section(
+        `Integration check: ${identity ?? '(local package)'}${data.strict ? ' (strict)' : ''}`,
+      ),
+      records(data.checks, {
+        fields: ['check', 'failed', 'errors', 'warnings', 'skipped'],
+      }),
+      text(closing),
+    );
+  }
+  if (result.data.failed) process.exitCode = 1;
+  return NO_RESULT_SET;
+}
+
 /** @param {import('commander').Command} program */
 export function registerIntegration(program) {
   /** @type {import('commander').Command} */
@@ -159,6 +259,12 @@ export function registerIntegration(program) {
   });
   addCmd.allowExcessArguments(false);
 
+  // It takes no package name, so a name passed by mistake is an error, not a
+  // silent check of the current folder.
+  defineCommand(integration, integrationCheckCommand, {
+    fn: integrationCheckFn,
+    action: async options => checkPackage(program, options),
+  }).allowExcessArguments(false);
   defineCommand(integration, integrationVerifyCommand, {
     fn: integrationPackCheckFn,
     action: async () => verifyPackage(program),

package/clients/cli/commands/setup-nudge.test.mjs

@@ -16,9 +16,24 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {isAstryxInitialized} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {fileURLToPath} from 'node:url';
+import {
+  isAstryxInitialized,
+  isAstryxPromptInReach,
+} from '../../../foundation/agent-docs/agent-docs.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 
+/** This source checkout: the tests run the CLI from it. */
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+
+/** Is `dir` inside a git repository? The temp folder normally is not. */
+function insideRepository(dir) {
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, '.git'))) return true;
+    if (path.dirname(d) === d) return false;
+  }
+}
+
 const MARKER = '<!-- ASTRYX:START -->';
 const NUDGE = /finish setup and install the Astryx agent prompt/;
 
@@ -61,6 +76,41 @@ describe('isAstryxInitialized — centralized setup check (one place)', () => {
   });
 });
 
+// Agents read the agent docs between the repository root and the folder they
+// work in, so a monorepo initialized at its root is set up in every package.
+describe('isAstryxPromptInReach — up to the repository root', () => {
+  it('finds init\'s block at the repository root from a workspace package', () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('AGENTS.md', MARKER);
+    write('packages/app/package.json', '{"name":"app"}');
+    expect(isAstryxPromptInReach(path.join(tmp, 'packages/app'))).toBe(true);
+  });
+
+  it('treats a worktree .git file as the repository root', () => {
+    write('.git', 'gitdir: /elsewhere\n');
+    write('CLAUDE.md', MARKER);
+    write('packages/app/package.json', '{"name":"app"}');
+    expect(isAstryxPromptInReach(path.join(tmp, 'packages/app'))).toBe(true);
+  });
+
+  it('does not look above the repository root', () => {
+    write('AGENTS.md', MARKER);
+    fs.mkdirSync(path.join(tmp, 'repo/.git'), {recursive: true});
+    write('repo/pkg/package.json', '{"name":"pkg"}');
+    expect(isAstryxPromptInReach(path.join(tmp, 'repo/pkg'))).toBe(false);
+  });
+
+  it.skipIf(insideRepository(os.tmpdir()))(
+    'checks only the folder itself outside a repository',
+    () => {
+      write('AGENTS.md', MARKER);
+      write('pkg/package.json', '{"name":"pkg"}');
+      expect(isAstryxPromptInReach(tmp)).toBe(true);
+      expect(isAstryxPromptInReach(path.join(tmp, 'pkg'))).toBe(false);
+    },
+  );
+});
+
 describe('enforcement layer 3 — per-command setup nudge', () => {
   const asProject = () => write('package.json', '{"name":"t"}');
 
@@ -99,4 +149,32 @@ describe('enforcement layer 3 — per-command setup nudge', () => {
     asProject();
     expect((await runCli(['init'], tmp)).stderr).not.toMatch(NUDGE);
   });
+
+  it('is quiet in a workspace package when init\'s block is at the repository root', async () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('AGENTS.md', MARKER);
+    write('packages/app/package.json', '{"name":"app"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'packages/app'));
+    expect(r.stderr).not.toMatch(NUDGE);
+  });
+
+  it('still nudges in a workspace package with no block up to the repository root', async () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('AGENTS.md', 'project notes, no astryx block');
+    write('packages/app/package.json', '{"name":"app"}');
+    const r = await runCli(['docs', 'tokens'], path.join(tmp, 'packages/app'));
+    expect(r.stderr).toMatch(NUDGE);
+  });
+
+  // The tests run the CLI from this checkout, so a project inside it is the
+  // contributor flow. The same project in the temp folder nudges (above).
+  it('is quiet inside the source checkout the CLI runs from', async () => {
+    const inside = fs.mkdtempSync(path.join(REPO, '.astryx-setup-nudge-'));
+    try {
+      fs.writeFileSync(path.join(inside, 'package.json'), '{"name":"t"}');
+      expect((await runCli(['docs', 'tokens'], inside)).stderr).not.toMatch(NUDGE);
+    } finally {
+      fs.rmSync(inside, {recursive: true, force: true});
+    }
+  });
 });

package/clients/cli/commands/swizzle.mjs

@@ -91,14 +91,16 @@ export function registerSwizzle(program) {
         ),
       ];
 
-      // StyleX build requirement — swizzled StyleX source renders unstyled with
-      // no error unless the consumer's build runs a StyleX compiler.
+      // StyleX build requirement — swizzled StyleX source throws on import
+      // ("Unexpected 'stylex.create' call at runtime") unless the consumer's
+      // build runs a StyleX compiler, so the page does not render at all.
       if (usesStyleX) {
         out.push(
           text(
             [
               `${WARN} These components use StyleX and require a StyleX compiler in your build.`,
-              '  Without one they render unstyled (no error). See setup per framework:',
+              `  Without one, importing them throws "Unexpected 'stylex.create' call at runtime"`,
+              '  and the page does not render. See setup per framework:',
               `  ${run} docs styling`,
               '  Next.js note: the StyleX Babel plugin disables SWC and breaks next/font -',
               '  use an SWC-based StyleX transform instead (covered in the guide).',

package/clients/cli/commands/swizzle.routing.test.mjs

@@ -15,8 +15,16 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import {createRequire} from 'node:module';
+import {fileURLToPath} from 'node:url';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 
+/** The StyleX runtime that Core ships with, resolved the way Core resolves it. */
+const CORE_PACKAGE = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../core/package.json',
+);
+
 /**
  * Build a fake @astryxdesign/core under <project>/node_modules with a single
  * swizzleable Button component (bare `Button.tsx`, no doc).
@@ -303,12 +311,21 @@ describe('swizzle — StyleX build setup note (#3373)', () => {
     const humanResult = await runCli(['swizzle', 'Styled', '-f'], project);
     expect(humanResult.code).toBe(0);
     expect(humanResult.stdout).toMatch(/StyleX compiler/i);
-    expect(humanResult.stdout).toMatch(/unstyled/i);
+    expect(humanResult.stdout).toMatch(/importing them throws "Unexpected 'stylex\.create' call at runtime"/);
+    expect(humanResult.stdout).not.toMatch(/unstyled/i);
     expect(humanResult.stdout).toMatch(/next\/font/i);
     // The fixture has no `astryx` bin installed, so the note names the scoped package.
     expect(humanResult.stdout).toMatch(/@astryxdesign\/cli docs styling/);
   });
 
+  // The note quotes what StyleX does without a compiler; this keeps it true.
+  it('matches what the StyleX runtime does when styles are not compiled', () => {
+    const stylex = createRequire(CORE_PACKAGE)('@stylexjs/stylex');
+    expect(() => stylex.create({root: {color: 'red'}})).toThrow(
+      /Unexpected 'stylex\.create' call at runtime/,
+    );
+  });
+
   it('does not print the StyleX note for components without StyleX', async () => {
     buildStyleXCore(project);
     writeProjectPackageJson(project);

package/clients/cli/commands/text-json-parity.test.mjs

@@ -341,6 +341,11 @@ const CASES = [
     args: ['doctor', 'integration', 'validate'],
     skipFieldChecks: true,
   },
+  {
+    name: 'integration check',
+    args: ['integration', 'check'],
+    skipFieldChecks: true,
+  },
   {
     name: 'doctor integration components',
     args: ['doctor', 'integration', 'components'],

package/clients/cli/commands/theme-build.doc.mjs

@@ -30,7 +30,7 @@ export const doc = {
     {
       flag: '--family',
       description:
-        'Build the selected extension family into one keyed CSS, JS, and declaration set. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
+        'Build the selected extension family into one keyed CSS, JS, and declaration set, written beside the family root theme file, which must be inside the working directory to build (ERR_PATH_TRAVERSAL); --check only reads, so it compares outputs anywhere. Requires --family-key; refused with --out or --watch (ERR_THEME_INVALID)',
     },
     {
       flag: '--family-key <key>',
@@ -41,7 +41,7 @@ export const doc = {
       flag: '-o, --out <path>',
       param: 'options.out',
       description:
-        'Output CSS file path; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A relative path must stay inside the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
+        'Output CSS file path, relative or absolute; the .js and .d.ts are written beside it (default: <theme name>.css next to the source). A build writes only inside the working directory, the defaults beside the source too (ERR_PATH_TRAVERSAL); --check writes nothing, so it compares outputs anywhere and refuses only a relative path that escapes the working directory. Single theme only: refused with more than one file or with --family (ERR_THEME_INVALID)',
     },
     {
       flag: '--icons-specifier <specifier>',

package/clients/cli/index.mjs

@@ -26,7 +26,8 @@ import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
 import {addDocHelp, markReportsResult} from './lib/define-command.mjs';
 import {doc as manifestDoc} from './commands/manifest.doc.mjs';
-import {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.mjs';
+import {isAstryxInitialized, isAstryxPromptInReach} from '../../foundation/agent-docs/agent-docs.mjs';
+import {CLI_ROOT} from '../../foundation/fs/paths.mjs';
 import * as debug from '../../foundation/debug/index.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -98,6 +99,7 @@ export const JSON_SUPPORTED = new Set([
   'theme targets',
   'theme palette generate',
   'integration add',
+  'integration check',
   'integration verify',
   'integration pack',
   'upgrade',
@@ -276,6 +278,26 @@ const commands = [
 ];
 
 const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+
+/**
+ * Is `cwd` inside the CLI's own source checkout while the CLI runs from it?
+ * An installed CLI always lives under `node_modules`; a CLI running from source
+ * does not, and its checkout is the pnpm workspace that holds it. Developing
+ * Astryx is not an app to set up, so the setup nudge stays quiet there.
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function inOwnSourceCheckout(cwd) {
+  if (CLI_ROOT.split(path.sep).includes('node_modules')) return false;
+  let checkout = CLI_ROOT;
+  while (!fs.existsSync(path.join(checkout, 'pnpm-workspace.yaml'))) {
+    const parent = path.dirname(checkout);
+    if (parent === checkout) return false;
+    checkout = parent;
+  }
+  const rel = path.relative(checkout, path.resolve(cwd));
+  return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
 /** An integration package's manifest: the package is not an app to set up. */
 const INTEGRATION_MANIFEST_FILES = [
   'astryx.integration.ts',
@@ -527,8 +549,9 @@ export async function createProgram() {
 
   /**
    * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
-   * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
-   * the user/agent that setup is missing.
+   * yet (no Astryx marker in any agent-doc file between the project and its
+   * repository root — see isAstryxPromptInReach), remind the user/agent that
+   * setup is missing.
    *
    * Uses `preAction` (not postAction) so it fires for EVERY valid command — even
    * ones whose action errors or calls process.exit (postAction is skipped then).
@@ -538,7 +561,8 @@ export async function createProgram() {
    * consumers parse stdout, not stderr — a stderr nudge would not reach them anyway.
    * The core/cli postinstall layers already nudge at install time regardless of
    * --json; a machine-readable nudge could later be an envelope field. Also skipped
-   * for the installer commands themselves and outside a project (no package.json).
+   * for the installer commands themselves, outside a project (no package.json),
+   * and inside the CLI's own source checkout when it runs from there.
    */
   program.hook('preAction', (thisCommand, actionCommand) => {
     try {
@@ -548,7 +572,8 @@ export async function createProgram() {
       if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
       // An integration package is not an app: `init` is not its next step.
       if (INTEGRATION_MANIFEST_FILES.some(file => fs.existsSync(path.join(cwd, file)))) return;
-      if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
+      if (inOwnSourceCheckout(cwd)) return; // developing Astryx itself, not an app
+      if (isAstryxPromptInReach(cwd)) return; // already set up — stay quiet
       // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
       // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
       // one-off, or `<pm> astryx` when installed — never the bare `npx astryx` footgun.

package/clients/cli/lib/component-format.mjs

@@ -68,8 +68,12 @@ function formatPropsTable(props) {
   for (const p of props) {
     const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
+    // The text projection of the prop doc's `stability` field: an
+    // experimental prop is outside the stable compatibility promise.
+    const stability =
+      p.stability === 'experimental' ? ' **(experimental)**' : '';
     lines.push(
-      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
+      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req}${stability} |`,
     );
   }
   return lines.join('\n');

package/foundation/agent-docs/agent-doc-state.d.mts

@@ -20,6 +20,20 @@ export function discoverAgentDocs(targetDir: string): string[];
  * @returns {boolean}
  */
 export function isAstryxInitialized(targetDir?: string): boolean;
+/**
+ * Does an agent working in `startDir` already have the Astryx prompt in reach?
+ *
+ * Coding agents read the agent docs between the repository root and the folder
+ * they work in. So inside a git repository, init's block in any folder from
+ * `startDir` up to the repository root counts: a workspace package of a
+ * monorepo initialized at its root is set up. Outside a repository only
+ * `startDir` itself is checked, as {@link isAstryxInitialized} does. Both the
+ * per-command nudge and the postinstall nudges ask this.
+ *
+ * @param {string} [startDir=process.cwd()]
+ * @returns {boolean}
+ */
+export function isAstryxPromptInReach(startDir?: string): boolean;
 /**
  * Pure decision: should a postinstall print the setup nudge? Shared by BOTH
  * postinstall layers, so the matrix cannot drift between them, and unit-testable

package/foundation/agent-docs/agent-doc-state.mjs

@@ -96,6 +96,44 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
   return false;
 }
 
+/**
+ * Does an agent working in `startDir` already have the Astryx prompt in reach?
+ *
+ * Coding agents read the agent docs between the repository root and the folder
+ * they work in. So inside a git repository, init's block in any folder from
+ * `startDir` up to the repository root counts: a workspace package of a
+ * monorepo initialized at its root is set up. Outside a repository only
+ * `startDir` itself is checked, as {@link isAstryxInitialized} does. Both the
+ * per-command nudge and the postinstall nudges ask this.
+ *
+ * @param {string} [startDir=process.cwd()]
+ * @returns {boolean}
+ */
+export function isAstryxPromptInReach(startDir = process.cwd()) {
+  const start = path.resolve(startDir);
+  const repositoryRoot = findRepositoryRoot(start);
+  if (!repositoryRoot) return isAstryxInitialized(start);
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (isAstryxInitialized(dir)) return true;
+    if (dir === repositoryRoot) return false;
+  }
+}
+
+/**
+ * The nearest folder at or above `start` that holds `.git` (a folder, or the
+ * file a worktree uses), or null outside a repository.
+ * @param {string} start
+ * @returns {string | null}
+ */
+function findRepositoryRoot(start) {
+  for (let dir = start; ; ) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 /**
  * The one-line next-step both postinstall nudges print. Kept here so layer 1
  * (core) and layer 2 (cli) can never word it differently.

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

@@ -226,4 +226,5 @@ export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, on
 }): string[];
 import { discoverAgentDocs } from './agent-doc-state.mjs';
 import { isAstryxInitialized } from './agent-doc-state.mjs';
-export { discoverAgentDocs, isAstryxInitialized };
+import { isAstryxPromptInReach } from './agent-doc-state.mjs';
+export { discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach };

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

@@ -42,15 +42,17 @@ import {
   LEGACY_MARKER_END,
   discoverAgentDocs,
   isAstryxInitialized,
+  isAstryxPromptInReach,
 } from './agent-doc-state.mjs';
 
 // The agent-doc locations, markers, and the setup-state predicates
-// (discoverAgentDocs, isAstryxInitialized) are the ONE canonical contract. They
-// live in the dependency-free leaf ./agent-doc-state.mjs so the postinstall
-// nudge (enforcement layer 2) can load them safely at install time. Re-exported
-// here so existing importers (init/upgrade commands, the layer-3 nudge in
-// clients/cli/index.mjs, tests) keep their `from './agent-docs.mjs'` paths.
-export {discoverAgentDocs, isAstryxInitialized};
+// (discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach) are the ONE
+// canonical contract. They live in the dependency-free leaf
+// ./agent-doc-state.mjs so the postinstall nudge (enforcement layer 2) can load
+// them safely at install time. Re-exported here so existing importers
+// (init/upgrade commands, the layer-3 nudge in clients/cli/index.mjs, tests)
+// keep their `from './agent-docs.mjs'` paths.
+export {discoverAgentDocs, isAstryxInitialized, isAstryxPromptInReach};
 
 const MAX_PROJECT_AGENT_DOC_LINES = 32;
 const MANAGED_MARKER_TEXT = /(?:ASTRYX|XDS):(START|END)/u;

package/foundation/config/project.mjs

@@ -60,6 +60,7 @@ import {
   applyTemplateReplacements,
   effectiveTemplateDiscovery,
   discoverAllUnresolved as discoverTemplates,
+  discoverCoreTemplates,
   discoverIntegrationTemplatesForOne,
 } from '../discovery/template-adapter.mjs';
 import {
@@ -821,6 +822,85 @@ export class Project {
     });
   }
 
+  /**
+   * The components and templates this project reads, as links name them: by
+   * owner provider id, kind, and name (a template by its id).
+   * @returns {Promise<import('../discovery/docs-discovery.mjs').LinkableContributions>}
+   */
+  async #linkableContributions() {
+    /** @type {Map<string, string>} */
+    const providers = new Map([[CORE_PACKAGE, CORE_PACKAGE]]);
+    for (const integration of this.#loadedIntegrations) {
+      if (integration?.name) {
+        providers.set(
+          integration.name,
+          integration.providerId ?? integration.name,
+        );
+      }
+    }
+    const providerOf = (/** @type {string | undefined} */ pkg) =>
+      providers.get(pkg ?? CORE_PACKAGE) ?? pkg ?? CORE_PACKAGE;
+    // An active replacement answers to the Core name it replaces, so a link
+    // to that Core component has to select Core (spec:AST-035 FR11).
+    /** @type {Map<string, string>} */
+    const replacing = new Map();
+    if (this.#loadedIntegrations.length > 0) {
+      const {active} = await resolveComponentReplacements(
+        findCoreDir(this.#cwd),
+        this.#loadedIntegrations,
+      );
+      for (const each of active) {
+        replacing.set(`${each.package}\0${each.name}`, each.target);
+      }
+    }
+    const components = (await this.components()).map(record => {
+      const replaces = replacing.get(`${record.package}\0${record.name}`);
+      return {
+        providerId: providerOf(record.package),
+        package: record.package,
+        name: record.name,
+        docPath: record.docPath,
+        ...(replaces == null ? {} : {replaces}),
+      };
+    });
+    /** @param {any} template @param {string} pkg */
+    const linkable = (template, pkg) => ({
+      providerId: providerOf(pkg),
+      package: pkg,
+      type: template.type,
+      id: template.dirName,
+      name: template.name,
+      ...(template.displayName == null
+        ? {}
+        : {displayName: template.displayName}),
+      ...(template.description == null
+        ? {}
+        : {description: template.description}),
+      ...(typeof template.replaces === 'string'
+        ? {replaces: template.replaces}
+        : {}),
+    });
+    /** @param {any} template */
+    const isPageOrBlock = template =>
+      template.type === 'page' || template.type === 'block';
+    // Every Core template, a replaced one too, since `--package
+    // @astryxdesign/core` still opens it; everyone else's as unqualified
+    // lookups see them, an active replacement with the id it takes over.
+    const templates = [
+      ...(await discoverCoreTemplates())
+        .filter(isPageOrBlock)
+        .map(template => linkable(template, CORE_PACKAGE)),
+      .../** @type {any[]} */ (await this.templates())
+        .filter(
+          template =>
+            isPageOrBlock(template) &&
+            (template.package ?? CORE_PACKAGE) !== CORE_PACKAGE,
+        )
+        .map(template => linkable(template, template.package)),
+    ];
+    return {components, templates};
+  }
+
   /**
    * The CLI's own doc topics plus the ones the configured integrations
    * contribute, resolved into one catalog: additions, replacements (with the
@@ -838,6 +918,8 @@ export class Project {
   async docs() {
     return this.#memo('docs', async () => {
       const catalog = DocsCatalog.fromBuiltins();
+      // Links name component, page, and block docs too (spec:AST-047 FR9).
+      catalog.setContributions(() => this.#linkableContributions());
       let rank = 0;
 
       for (const integration of this.#loadedIntegrations) {

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

@@ -46,6 +46,7 @@ export const AUTHORING_SELF_DOCS = [
   'doctypes/reference/reference.doc.mjs',
   'doctypes/schema/schema.doc.mjs',
   'doctypes/template/template.doc.mjs',
+  'doctypes/template/integration-template.doc.mjs',
   'doctypes/theme/theme.doc.mjs',
 ];
 
@@ -192,7 +193,7 @@ export function buildAuthoringReferenceDoc(docs) {
     title: 'Authoring Reference',
     category: 'guide',
     description:
-      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
+      '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`.',
     sections: docs.map(selfDocSection),
   });
 }