@astryxdesign/cli 0.6.3-canary.e78c3ce → 0.6.3-canary.e86aa19

package/README.md

@@ -21,16 +21,16 @@ The CLI documents itself, so these commands print what the installed version doe
 
 - `astryx <command> --help`: one command's arguments and options.
 - `astryx manifest --json`: every command, option, and response type, as JSON.
-- `astryx docs cli --index`: one section for each command (`commands-<name>`)
-  and each API function, plus the JSON output envelope, error codes, and
-  response types (`api-<name>`). Read one with `astryx docs cli <key>`, for
-  example `astryx docs cli api-search`.
+- `astryx docs cli`: the CLI's docs tree, one level at a time.
+  `astryx docs cli/commands` lists every command, `astryx docs cli/api` lists
+  the API's functions, schemas, and enums, and a route such as
+  `astryx docs cli/api/functions/search` prints one.
 - `astryx docs authoring --index`: the authoring reference, with one section for
   each file an author writes: the `astryx.config.*` file, the
   `astryx.integration.*` manifest, codemods, and every doc type (`ComponentDoc`,
   `TemplateDoc`, `ThemeDoc`, and the rest). Read one section with
   `astryx docs authoring <section>`, for example `astryx docs authoring config`.
-- `astryx docs cli-integrations`: the guide to building an integration package.
+- `astryx docs cli/integrations`: the guide to building an integration package.
 - `astryx docs`: every docs topic, including the design-system guides (for
   example `tokens`, `theme`, and `layout`).
 
@@ -428,24 +428,25 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `component.detail.source`         | One component's source file, as {component, source}.                                                                                                                                                                                                                                                                                                                                                                                       |
 | `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                                                                                                                                                                                                                     |
 | `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                                                                                                                                                                 |
-| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                                                                                                                                                                                                                    |
-| `docs.detail`                     | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                                                                                                                                                                                                              |
-| `docs.index`                      | One topic's section index (--index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary).                                                                                                                                                                                                                                  |
-| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined.                                                                                                                                                                                                                                                                                                                                                     |
+| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load.                                                                                                                                                                                                                |
+| `docs.detail`                     | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                                                                                                                                             |
+| `docs.index`                      | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                  |
+| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it).                                                                                                                                                                                                                                     |
+| `docs.node`                       | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).                                                                                                                           |
 | `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                                                                                                                                                                   |
 | `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                                                                                                                                                                  |
 | `discover.list`                   | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                                                                                         |
 | `discover.detail`                 | A single external package entry, for an @scope/name query.                                                                                                                                                                                                                                                                                                                                                                                 |
 | `discover.detail.doc`             | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                                                                                                                                                                                                             |
 | `discover.search`                 | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                                                                                                                                                                                                           |
-| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title (docs), or displayName and kind (templates).                                                                                                                                                                |
+| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).                                        |
 | `build.help`                      | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.                                                                                                                                                              |
 | `build.kit`                       | The composition kit: echoed query, hasResults, matchCount (total matched, never a cap), directMatch, pages (closest templates), blocks (drop-in patterns) and domain (idea components/hooks) as SearchResultEntry[], frame and foundation name arrays, and hint {reason, commands} when thin.                                                                                                                                              |
 | `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                             |
 | `swizzle.copy`                    | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                                                                                                                                                                                                                             |
 | `gap-report.categories`           | The fixed gap category values and human-readable labels.                                                                                                                                                                                                                                                                                                                                                                                   |
 | `gap-report.file`                 | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.                                                                                                                                                                                      |
-| `template.list`                   | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                                                                                                                                                                                                                       |
+| `template.list`                   | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.                                                                                                                                                                                                                                                             |
 | `template.show`                   | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                                                                                                                                                                                                        |
 | `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                                                                                                                                                                                                               |
 | `template.copy`                   | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                                                                                                                                                                                                                      |
@@ -469,9 +470,9 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `integration.add`                 | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun.                                                                                                                                                                                                                                                                            |
 | `integration.pack-check`          | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}]. |
 | `integration.validate`            | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                   |
-| `integration.template-conflicts`  | The integration identity, structural issues, and non-blocking conflicts where an integration template id is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                |
+| `integration.template-conflicts`  | The integration identity, issues, and conflicts as {severity: info \| warning, relationship: replaces \| accidental, replaces?, command}.                                                                                                                                                                                                                                                                                                  |
 | `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                             |
-| `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps classified as intentional replacements, intentional extensions, or accidental same-name conflicts.                                                                                                                                                                                                                                                                      |
+| `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                     |
 | `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                                                                                                                                                                                                       |
 | `layout.check`                    | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                                                                                                                                                                                                                   |
 | `layout.grammar`                  | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                                                                                                                                                                                                        |
@@ -667,9 +668,10 @@ wrong type fails there; a field this CLI does not know is ignored with a
 warning naming it, so a manifest written against a newer CLI still contributes
 everything this one understands.
 
-Discovery is resilient: a broken or misconfigured integration is skipped with a
-one-line warning on stderr instead of crashing the CLI, and it never corrupts a
-`--json` envelope. To inspect problems, run
+Discovery is resilient. A manifest load failure skips that package with a warning.
+An invalid contribution kind remains reportable without hiding other valid kinds,
+and invalid template or component metadata is omitted without hiding valid siblings.
+Warnings go to stderr and never corrupt a `--json` envelope. To inspect problems, run
 `astryx doctor integration validate <package>` for structure, then use `templates`,
 `components`, or `docs` under the same `astryx doctor integration` group to check
 Core identity overlaps before publishing. Bare `astryx doctor` checks overall
@@ -679,5 +681,5 @@ For the full authoring walkthrough (component doc format, template packaging
 and `exports` requirements, and codemod authoring), see the guide:
 
 ```bash
-astryx docs cli-integrations
+astryx docs cli/integrations
 ```

package/api/component/_adapter.d.mts

@@ -2,9 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
- * which is either a single-component or multi-component doc; this loose view
- * captures the fields the API reads across both forms.
+ * A loaded component doc. The shared validated loader accepts stamped and legacy
+ * component docs; this loose view captures the fields the API reads across both.
  * @typedef {object} LoadedComponentDoc
  * @property {string} [name]
  * @property {string} [description]
@@ -15,9 +14,7 @@
  * @property {string} [import] set when the doc states its own import specifier
  */
 /**
- * Options object for `loadDocs`, matching its declared parameter shape (used
- * as a cast target so `lang` (which the API may hold as `string|null`) type
- * checks against `loadDocs`'s `lang?: string`).
+ * Options object for the shared component-doc loader.
  * @typedef {{zh?: boolean, dense?: boolean, lang?: string}} LoadDocsOpts
  */
 /**
@@ -184,9 +181,8 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
 } | null;
 export { CORE_PACKAGE };
 /**
- * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
- * which is either a single-component or multi-component doc; this loose view
- * captures the fields the API reads across both forms.
+ * A loaded component doc. The shared validated loader accepts stamped and legacy
+ * component docs; this loose view captures the fields the API reads across both.
  */
 export type LoadedComponentDoc = {
     name?: string | undefined;
@@ -203,9 +199,7 @@ export type LoadedComponentDoc = {
     import?: string | undefined;
 };
 /**
- * Options object for `loadDocs`, matching its declared parameter shape (used
- * as a cast target so `lang` (which the API may hold as `string|null`) type
- * checks against `loadDocs`'s `lang?: string`).
+ * Options object for the shared component-doc loader.
  */
 export type LoadDocsOpts = {
     zh?: boolean;

package/api/component/_adapter.mjs

@@ -35,16 +35,15 @@ import {
   resolveIntegrationImportPath as resolveIntegrationImport,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {Project} from '../../foundation/config/project.mjs';
-import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
+import {loadComponentDoc as loadValidatedComponentDoc} from '../../foundation/discovery/component-loader.mjs';
 import {searchComponents} from '../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../error.mjs';
 
 export {CORE_PACKAGE};
 
 /**
- * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
- * which is either a single-component or multi-component doc; this loose view
- * captures the fields the API reads across both forms.
+ * A loaded component doc. The shared validated loader accepts stamped and legacy
+ * component docs; this loose view captures the fields the API reads across both.
  * @typedef {object} LoadedComponentDoc
  * @property {string} [name]
  * @property {string} [description]
@@ -56,9 +55,7 @@ export {CORE_PACKAGE};
  */
 
 /**
- * Options object for `loadDocs`, matching its declared parameter shape (used
- * as a cast target so `lang` (which the API may hold as `string|null`) type
- * checks against `loadDocs`'s `lang?: string`).
+ * Options object for the shared component-doc loader.
  * @typedef {{zh?: boolean, dense?: boolean, lang?: string}} LoadDocsOpts
  */
 
@@ -381,9 +378,22 @@ export async function resolveUnscopedDoc(dirName, {coreDir, cwd, name}) {
  */
 export async function loadComponentDoc(docPath, opts = {}) {
   const {zh = false, dense = false, lang = null} = opts;
-  return /** @type {LoadedComponentDoc} */ (
-    await loadDocs(docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang}))
-  );
+  try {
+    return /** @type {LoadedComponentDoc} */ (
+      await loadValidatedComponentDoc(
+        docPath,
+        /** @type {LoadDocsOpts} */ ({zh, dense, lang}),
+      )
+    );
+  } catch (err) {
+    throw new AstryxError(
+      `Cannot load component metadata: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DOC,
+    );
+  }
 }
 
 /**

package/api/component/component.mjs

@@ -143,14 +143,20 @@ export async function component(name, options = {}) {
   // Searches that package first — critical for names that exist in both core
   // and an external package (AppShell, Button, SideNav).
   if (packageScope) {
-    const scoped = classifyScope(packageScope, {owners, loadedIntegrations, cwd, name});
+    const scoped = classifyScope(packageScope, {
+      owners,
+      loadedIntegrations,
+      cwd,
+      name,
+    });
 
     if (scoped.kind === 'core' || scoped.kind === 'integration') {
       const owner = scoped.owner;
       if (source) {
         return componentDetailSource(dirName, owner.sourcePath, {
           name,
-          notFoundInPackage: scoped.kind === 'integration' ? packageScope : null,
+          notFoundInPackage:
+            scoped.kind === 'integration' ? packageScope : null,
         });
       }
       // showcase/blocks were previously dropped on the scoped path — a
@@ -187,17 +193,48 @@ export async function component(name, options = {}) {
       }
       const docs = await loadComponentDoc(extDocPath, docOpts);
       if (props) return componentDetailProps(docs);
-      return componentDetail(docs, {package: scoped.ext.name, sourcePath: null}, dirName, coreDir);
+      return componentDetail(
+        docs,
+        {package: scoped.ext.name, sourcePath: null},
+        dirName,
+        coreDir,
+      );
+    }
+    throw new AstryxError(
+      `No component "${name}" in package "${packageScope}"`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  // Invalid integration metadata does not create ambiguity against a valid
+  // owner. Keep raw owners only when no doc owner is valid, so an integration-
+  // only component still exposes its source and returns ERR_INVALID_DOC for
+  // detail instead of degrading to an unrelated unknown-component error.
+  const validOwners = [];
+  for (const owner of owners) {
+    if (owner.package === CORE_PACKAGE) {
+      validOwners.push(owner);
+      continue;
+    }
+    try {
+      await loadComponentDoc(owner.docPath);
+      validOwners.push(owner);
+    } catch {
+      // Project/Doctor report invalid metadata; it is not an effective owner.
     }
-    throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
   }
+  const effectiveOwners = validOwners.length > 0 ? validOwners : owners;
 
-  // ── Ambiguity: owned by MORE THAN ONE package, no --package ─────
-  assertUnambiguousOwners(owners, dirName);
+  // ── Ambiguity: owned by MORE THAN ONE valid package, no --package ──
+  assertUnambiguousOwners(effectiveOwners, dirName);
 
   // ── Single non-core owner (an integration provides it, core does not) ──
-  if (owners.length === 1 && owners[0].package !== CORE_PACKAGE) {
-    const owner = owners[0];
+  if (
+    effectiveOwners.length === 1 &&
+    effectiveOwners[0].package !== CORE_PACKAGE
+  ) {
+    const owner = effectiveOwners[0];
     if (source) {
       return componentDetailSource(dirName, owner.sourcePath, {name});
     }
@@ -213,7 +250,11 @@ export async function component(name, options = {}) {
   // ── No-scope core path ─────────────────────────────────────────
   // `--source` reads core directly (no external/fuzzy fallback).
   if (source) {
-    return componentDetailSource(dirName, resolveCoreSourcePath(coreDir, dirName), {name});
+    return componentDetailSource(
+      dirName,
+      resolveCoreSourcePath(coreDir, dirName),
+      {name},
+    );
   }
   if (showcase) {
     return componentDetailShowcase(dirName, {cwd, name});
@@ -232,10 +273,14 @@ export async function component(name, options = {}) {
   // scope the response to just the matching sub-component.
   const sub = scopeSubComponent(docs, dirName, coreDir);
   if (sub) {
-    if (props) return componentDetailProps({props: sub.matchingComponent.props});
+    if (props)
+      return componentDetailProps({props: sub.matchingComponent.props});
     return componentDetail(
       sub.scoped,
-      {package: resolved.resolvedOwnerPackage, sourcePath: resolved.resolvedSourcePath},
+      {
+        package: resolved.resolvedOwnerPackage,
+        sourcePath: resolved.resolvedSourcePath,
+      },
       dirName,
       coreDir,
     );
@@ -244,7 +289,10 @@ export async function component(name, options = {}) {
   if (props) return componentDetailProps(docs);
   return componentDetail(
     docs,
-    {package: resolved.resolvedOwnerPackage, sourcePath: resolved.resolvedSourcePath},
+    {
+      package: resolved.resolvedOwnerPackage,
+      sourcePath: resolved.resolvedSourcePath,
+    },
     resolved.resolvedName,
     coreDir,
   );

package/api/component/list/list.mjs

@@ -15,7 +15,7 @@ import {
   CORE_PACKAGE,
   discoverComponents,
   discoverExternalComponentsGrouped,
-  discoverIntegrationComponents,
+  discoverValidIntegrationComponents,
   findComponentReadme,
   findExternalComponentDoc,
   resolveImportPath,
@@ -228,7 +228,8 @@ export async function componentList(
   const seenIntegration = new Set();
   for (const integration of loadedIntegrations) {
     seenIntegration.add(integration.name);
-    const owned = discoverIntegrationComponents(integration);
+    const {components: owned} =
+      await discoverValidIntegrationComponents(integration);
     // Group integration components by their doc `group`, falling back to the
     // package name. Keys are package-qualified so they never collide with
     // core groups or each other.

package/api/docs/_adapter.d.mts

@@ -16,16 +16,75 @@
  */
 export function loadDocsCatalog(cwd?: string): Promise<DocsCatalog>;
 /**
- * One topic, lowered for `lang`: overlaid, extensions merged, keys stamped.
- * Memoized per catalog, so a read that references a topic twice loads it once.
- * Every read of the catalog shares the memoized node, so it is frozen; the
- * lenses hand readers copies.
+ * The CLI's own topics alone, for a check that runs without a project.
+ * @returns {DocsCatalog}
+ */
+export function builtinCatalog(): DocsCatalog;
+/**
+ * One topic, lowered for `lang` with every link between docs resolved
+ * (spec:AST-047 FR9): an inline `{@link <target>}` reads as the command that
+ * opens its doc, and a `reference` or `workflow` block carries the doc it
+ * names. Memoized per catalog and frozen, like the lowered node.
  * @param {DocsCatalog} catalog
- * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @param {DocsTopicEntry} entry
  * @param {string | null} [lang]
  * @returns {Promise<import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode>}
  */
-export function lowerTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
+export function lowerTopic(catalog: DocsCatalog, entry: DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
+/**
+ * Each link in a topic that names no doc.
+ * @param {DocsCatalog} catalog
+ * @param {DocsTopicEntry} entry
+ * @returns {Promise<LinkProblem[]>}
+ */
+export function topicLinkProblems(catalog: DocsCatalog, entry: DocsTopicEntry): Promise<LinkProblem[]>;
+/**
+ * The project's docs tree: the CLI's own docs plus the namespace docs and
+ * placed guides the configured integrations ship (spec:AST-046), built once
+ * per catalog. Without integration docs it is the CLI's tree, built once per
+ * process.
+ * @param {DocsCatalog} catalog
+ * @param {{fresh?: boolean}} [options] `fresh`: reread the CLI's tree files
+ * @returns {Promise<DocsTree>}
+ */
+export function projectTree(catalog: DocsCatalog, { fresh }?: {
+    fresh?: boolean;
+}): Promise<DocsTree>;
+/**
+ * How a doc's links find their targets (spec:AST-047 FR9): a doc in the
+ * project's docs tree by its identity, or a flat topic by its provider and
+ * name. A target that matches neither is a problem, never a guess.
+ * @param {DocsCatalog} catalog
+ * @param {string} fromProvider the provider id of the doc the links sit in
+ * @returns {Promise<LinkResolver>}
+ */
+export function linkResolver(catalog: DocsCatalog, fromProvider: string): Promise<LinkResolver>;
+/**
+ * Every link in the project's docs that names no doc: in each topic, each
+ * guide the tree places, and each typed doc.
+ * @param {DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {{owner?: string}} [options] `owner`: only the docs this package owns
+ * @returns {Promise<string[]>}
+ */
+export function docsLinkProblems(catalog: DocsCatalog, tree: DocsTree, { owner }?: {
+    owner?: string;
+}): Promise<string[]>;
+/**
+ * What \`astryx doctor integration docs\` checks in one integration's docs: the
+ * docs tree they build beside the CLI's (namespaces, placements, routes) and
+ * every link in them (spec:AST-046, spec:AST-047).
+ * @param {{name: string}} integration
+ * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
+ * @returns {Promise<string[]>}
+ */
+export function packageDocsProblems(integration: {
+    name: string;
+}, discovered: {
+    records: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicRecord[];
+    namespaces: import("../../foundation/doc-compiler/tree.mjs").TreeNamespaceInput[];
+    guides: import("../../foundation/doc-compiler/tree.mjs").TreeDocInput[];
+}): Promise<string[]>;
 /**
  * How a token reference finds its target: the topic it names in `catalog`,
  * lowered for the same language.
@@ -43,34 +102,156 @@ export function referenceTargets(catalog: DocsCatalog, lang: string | null): (to
  */
 export function compileTopic(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry, lang?: string | null): Promise<import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode>;
 /**
- * Resolve `topic` against the project's catalog (throwing `ERR_UNKNOWN_TOPIC`
- * when unmatched) and lower it with any --dense/--zh overlay and any
- * integration extension applied. Shared by the leaves so topic normalization
- * and unknown-topic handling live in exactly one place.
- *
- * @param {string} topic
- * @param {object} [options]
- * @param {string} [options.lang]
- * @param {boolean} [options.zh]
- * @param {boolean} [options.dense]
- * @param {string} [options.cwd]
- * @returns {Promise<{
- *   catalog: DocsCatalog,
- *   node: import('../../foundation/doc-compiler/compile.mjs').CompiledReferenceNode,
- *   lang: string | null,
- * }>}
- */
-export function resolveTopicDocs(topic: string, options?: {
-    lang?: string | undefined;
-    zh?: boolean | undefined;
-    dense?: boolean | undefined;
-    cwd?: string | undefined;
+ * A guide the docs tree places, as a topic entry the topic readers open by its
+ * route. It is never a flat topic: `astryx docs <route>` is its only name.
+ * @param {import('../../foundation/doc-compiler/tree.mjs').TreeNode} node
+ * @returns {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry}
+ */
+export function guideEntry(node: import("../../foundation/doc-compiler/tree.mjs").TreeNode): import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
+/**
+ * What a typed doc in the docs tree prints: its content, with every link to
+ * another doc resolved (spec:AST-047 FR9). A namespace has no content. The
+ * CLI's doc modules are discovery, so this lives in the adapter
+ * (architecture:cli-surface INV21).
+ * @param {DocsCatalog} catalog
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {Promise<{content: any[], problems: LinkProblem[]}>}
+ */
+export function nodeContent(catalog: DocsCatalog, tree: DocsTree, node: TreeNode): Promise<{
+    content: any[];
+    problems: LinkProblem[];
+}>;
+/**
+ * The command that opens the level a topic sits in when the tree cannot say:
+ * a guide's parent namespace, or the topic list.
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {import('./docs.type.mjs').DocsCommand}
+ */
+export function topicUp(entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): import("./docs.type.mjs").DocsCommand;
+/**
+ * The moves from a node's place in the tree (spec:AST-047 FR2, FR4): up to its
+ * parent (the topic list, at the top), and across to the nodes before and
+ * after it in its parent's slot.
+ * @param {DocsTree} tree
+ * @param {TreeNode} node
+ * @returns {import('./docs.type.mjs').DocsLinks}
+ */
+export function placeLinks(tree: DocsTree, node: TreeNode): import("./docs.type.mjs").DocsLinks;
+/**
+ * The moves a topic read offers: from its place in the tree, where a guide
+ * sits in its namespace and a flat topic in the Unorganized level.
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {Promise<import('./docs.type.mjs').DocsLinks>}
+ */
+export function topicLinks(catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): Promise<import("./docs.type.mjs").DocsLinks>;
+/**
+ * What a docs argument names: a topic (a flat one, or a guide the docs tree
+ * places), a namespace or typed doc in the tree, or nothing, as nameOwner
+ * decides.
+ * @param {unknown} topic
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<
+ *   | {kind: 'topic', catalog: DocsCatalog, entry: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry}
+ *   | {kind: 'node', catalog: DocsCatalog, tree: import('../../foundation/doc-compiler/tree.mjs').DocsTree, node: import('../../foundation/doc-compiler/tree.mjs').TreeNode}
+ *   | {kind: 'unknown', catalog: DocsCatalog}
+ * >}
+ */
+export function resolveDocsArgument(topic: unknown, { cwd }?: {
+    cwd?: string;
+}): Promise<{
+    kind: "topic";
+    catalog: DocsCatalog;
+    entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
+} | {
+    kind: "node";
+    catalog: DocsCatalog;
+    tree: import("../../foundation/doc-compiler/tree.mjs").DocsTree;
+    node: import("../../foundation/doc-compiler/tree.mjs").TreeNode;
+} | {
+    kind: "unknown";
+    catalog: DocsCatalog;
+}>;
+/**
+ * Who answers to a name a reader types (spec:AST-046 FR5, FR11). The tree
+ * decides first: the node at that route, compared without case, holds it. A
+ * name with no node of its own is a topic's other name (its `replaces`
+ * alias), and that topic answers, unless the tree gave the topic's own route
+ * to another doc. Reads, the topic list, and search all ask this, so they
+ * agree on every name.
+ * @param {DocsTree} tree
+ * @param {DocsCatalog} catalog
+ * @param {string} name
+ * @returns {{kind: 'topic', entry: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} | {kind: 'node', node: TreeNode} | null}
+ */
+export function nameOwner(tree: DocsTree, catalog: DocsCatalog, name: string): {
+    kind: "topic";
+    entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
+} | {
+    kind: "node";
+    node: TreeNode;
+} | null;
+/**
+ * Whether a topic answers to its own name: what the topic list and search
+ * offer must open that topic.
+ * @param {DocsTree} tree
+ * @param {DocsCatalog} catalog
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {boolean}
+ */
+export function holdsOwnName(tree: DocsTree, catalog: DocsCatalog, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): boolean;
+/**
+ * The doc that took a flat topic's route in the docs tree, when it is not
+ * that topic (spec:AST-046 FR11): the CLI keeps its routes, such as `cli`
+ * and `unorganized`, and a namespace keeps its route over a topic of the same
+ * name. Null when the topic owns its route, or the tree has no node there.
+ * @param {DocsTree} tree
+ * @param {import('../../foundation/discovery/docs-discovery.mjs').DocsTopicEntry} entry
+ * @returns {TreeNode | null}
+ */
+export function routeOwner(tree: DocsTree, entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry): TreeNode | null;
+/**
+ * The error for a docs argument that names nothing. For a route, it suggests
+ * the children of the deepest namespace the route reaches; otherwise, every
+ * topic and every top-level namespace.
+ * @param {unknown} topic
+ * @param {DocsCatalog} catalog
+ * @returns {Promise<AstryxError>}
+ */
+export function unknownTopicError(topic: unknown, catalog: DocsCatalog): Promise<AstryxError>;
+/**
+ * A sentence naming the packages whose docs did not load, or nothing: a doc
+ * that fails to load withdraws its package's docs, so a reader who cannot
+ * find one learns where to look.
+ * @param {DocsCatalog} catalog
+ * @returns {string}
+ */
+export function notLoaded(catalog: DocsCatalog): string;
+/**
+ * Resolve a topic (a flat one, or a guide the docs tree places by its route)
+ * and lower it for the topic readers.
+ * @param {unknown} topic
+ * @param {{lang?: string | null, zh?: boolean, dense?: boolean, cwd?: string}} [options]
+ */
+export function resolveTopicDocs(topic: unknown, options?: {
+    lang?: string | null;
+    zh?: boolean;
+    dense?: boolean;
+    cwd?: string;
 }): Promise<{
     catalog: DocsCatalog;
     node: import("../../foundation/doc-compiler/compile.mjs").CompiledReferenceNode;
     lang: string | null;
+    entry: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 }>;
+export type DocsTree = import("../../foundation/doc-compiler/tree.mjs").DocsTree;
+export type TreeNode = import("../../foundation/doc-compiler/tree.mjs").TreeNode;
+export type LinkProblem = import("../../foundation/doc-compiler/links.mjs").LinkProblem;
+export type LinkResolver = import("../../foundation/doc-compiler/links.mjs").LinkResolver;
+export type DocsTopicEntry = import("../../foundation/discovery/docs-discovery.mjs").DocsTopicEntry;
 import { DocsCatalog } from '../../foundation/discovery/docs-discovery.mjs';
+import { AstryxError } from '../error.mjs';
 import { OVERLAY_LANGUAGES } from '../../foundation/doc-compiler/read.mjs';
 import { overlayLanguages } from '../../foundation/doc-compiler/read.mjs';
 export { OVERLAY_LANGUAGES, overlayLanguages };