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

package/foundation/discovery/theme-discovery.mjs

@@ -22,6 +22,7 @@ import * as path from 'node:path';
 import {lowerDoc} from '../doc-compiler/compile.mjs';
 import {packageSource} from '../doc-compiler/source.mjs';
 import {CLI_ROOT} from '../fs/paths.mjs';
+import {formatCliCommand} from '../env/package-manager.mjs';
 import {LOCAL_THEME_ROOT} from '../config/theme-state.mjs';
 import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
 
@@ -958,6 +959,126 @@ function declaresThemeDoc(ast, exportDefault) {
   });
 }
 
+/**
+ * Whether a file is the module `astryx theme build` writes rather than a
+ * theme source: plain JavaScript that carries the build's generated header
+ * and never calls defineTheme.
+ * @param {string} file
+ */
+function isBuiltThemeModule(file) {
+  if (!/\.m?js$/u.test(file)) return false;
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return false;
+  }
+  return (
+    /@generated by `astryx theme build`/u.test(text) &&
+    !/\bdefineTheme\b/u.test(text)
+  );
+}
+
+/**
+ * The fix when a descriptor's stem names both a theme source and the module
+ * `astryx theme build` writes beside it (`brand.ts` and its built `brand.js`):
+ * the build names its output after the theme, so the source and descriptor
+ * take the `<name>Theme` stem instead. Null when no built module is among
+ * the matches, or the stem already ends in `Theme`.
+ * @param {string} sourceDir
+ * @param {string[]} sources same-stem module file names
+ * @param {string} doc the descriptor's file name
+ * @param {string} exportName the descriptor's stem
+ * @returns {string | null}
+ */
+function builtThemeSourceFix(sourceDir, sources, doc, exportName) {
+  if (exportName.endsWith('Theme')) return null;
+  const built = sources.filter(file =>
+    isBuiltThemeModule(path.join(sourceDir, file)),
+  );
+  const source = sources.filter(file => !built.includes(file));
+  if (built.length === 0 || source.length !== 1) return null;
+  const extension = source[0].slice(exportName.length);
+  const stem = `${exportName}Theme`;
+  return `Fix: ${built.map(file => `"${file}"`).join(', ')} is the module \`${formatCliCommand('theme build', sourceDir)}\` writes, which takes the theme's name; rename ${source[0]} to ${stem}${extension} and ${doc} to ${stem}${THEME_DOC_SUFFIX}, export \`${stem}\` from it, and build again.`;
+}
+
+/**
+ * Why a descriptor pairs with the built module and the built module lacks
+ * the export the descriptor's stem names (`ocean.doc.mjs` beside a built
+ * `ocean.js` that exports `oceanTheme`): the descriptor is named for the
+ * build's output, not the theme's source. The source is named only when the
+ * built module's `Source:` header, or a source whose defineTheme gives the
+ * theme's name, confirms it; otherwise the message stays generic. Null when
+ * the entry is not a built module.
+ * @param {string} label the descriptor, as messages name it
+ * @param {string} sourceDir
+ * @param {string} entry the file the descriptor pairs with
+ * @param {string} exportName the descriptor's stem
+ * @param {string} doc the descriptor's file name
+ * @param {string} slug the theme's name
+ * @param {string[]} files the theme folder's files
+ * @returns {string | null}
+ */
+function builtModuleDescriptorMessage(
+  label,
+  sourceDir,
+  entry,
+  exportName,
+  doc,
+  slug,
+  files,
+) {
+  if (!isBuiltThemeModule(path.join(sourceDir, entry))) return null;
+  const source = confirmedThemeSource(sourceDir, entry, slug, files);
+  const head = `${label} shares its stem with the built module "${entry}", which does not export "${exportName}": a descriptor must share its stem with the source that calls defineTheme.`;
+  if (source == null) {
+    return `${head} Fix: rename ${doc} to share its stem with the theme's source (the module that calls defineTheme, such as ${exportName}Theme.ts).`;
+  }
+  const stem = source.replace(/\.[^.]+$/u, '');
+  return `${head} The theme's source is "${source}". Fix: rename ${doc} to ${stem}${THEME_DOC_SUFFIX}.`;
+}
+
+/**
+ * The theme's source, when something confirms it: the file the built
+ * module's `Source:` header names, if it is in the folder, else the one
+ * module in the folder whose defineTheme gives the theme's name as a
+ * literal. Null otherwise: a `<name>Theme` file alone may be a helper.
+ * @param {string} sourceDir
+ * @param {string} built the built module's file name
+ * @param {string} slug
+ * @param {string[]} files
+ * @returns {string | null}
+ */
+function confirmedThemeSource(sourceDir, built, slug, files) {
+  const own = files.filter(
+    file =>
+      !file.includes('/') &&
+      file !== built &&
+      THEME_MODULE_EXTENSIONS.some(extension => file.endsWith(extension)),
+  );
+  /** @param {string} file */
+  const read = file => {
+    try {
+      return fs.readFileSync(path.join(sourceDir, file), 'utf8');
+    } catch {
+      return '';
+    }
+  };
+  const header = /^\s*\*?\s*Source:\s*(\S+)\s*$/mu.exec(read(built));
+  if (header) {
+    const named = path.posix.basename(header[1].replace(/\\/gu, '/'));
+    if (own.includes(named)) return named;
+  }
+  const quoted = slug.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+  const naming = new RegExp(
+    `\\bdefineTheme\\s*\\(\\s*\\{[^}]*\\bname\\s*:\\s*['"\`]${quoted}['"\`]`,
+    'u',
+  );
+  const matches = own.filter(file => naming.test(read(file)));
+  return matches.length === 1 ? matches[0] : null;
+}
+
 /** A module named for the theme it exports, such as `oceanTheme.ts`. */
 const THEME_SOURCE_RE = /^[$A-Z_a-z][$\w]*Theme\.(?:mjs|js|mts|ts|tsx|jsx)$/u;
 
@@ -1240,8 +1361,17 @@ export function discoverThemeDirectory(
           : evidence.includes('/')
             ? `; "${evidence}" is in a subfolder`
             : ` beside "${evidence}"`;
+      const themeDoc = formatCliCommand('docs authoring theme-doc', sourceDir);
+      const fix =
+        docs.length > 1
+          ? `Fix: keep the one descriptor that shares its stem with the theme's source and delete the rest.`
+          : evidence.includes('/')
+            ? `Fix: move "${evidence}" up into ${slug}/, beside where its descriptor goes.`
+            : THEME_SOURCE_RE.test(evidence)
+              ? `Fix: add ${evidence.replace(/\.[^.]+$/u, '')}${THEME_DOC_SUFFIX} beside it with type: 'theme' and name: '${slug}'; \`${themeDoc}\` lists its fields.`
+              : `Fix: add a descriptor that shares its stem with the theme's source, with type: 'theme' and name: '${slug}'; \`${themeDoc}\` lists its fields.`;
       throw new Error(
-        `${theme} must contain exactly one same-stem .doc.mjs descriptor; found ${docs.length}${detail}.`,
+        `${theme} must contain exactly one same-stem .doc.mjs descriptor; found ${docs.length}${detail}. ${fix}`,
       );
     }
     const nested = descriptors.find(file => file.includes('/'));
@@ -1267,8 +1397,13 @@ export function discoverThemeDirectory(
       extension => `${exportName}${extension}`,
     ).filter(file => listing.files.includes(file));
     if (sources.length !== 1) {
+      const fix =
+        sources.length > 1
+          ? (builtThemeSourceFix(sourceDir, sources, docs[0], exportName) ??
+            `Fix: keep one of them; the theme's source is a single module.`)
+          : `Fix: add ${exportName}.ts beside ${docs[0]}, exporting \`${exportName}\` from defineTheme.`;
       throw new Error(
-        `${theme} must contain exactly one same-stem source for ${docs[0]}; found ${sources.length}${sources.length > 1 ? `: ${quoted(sources)}` : ''}.`,
+        `${theme} must contain exactly one same-stem source for ${docs[0]}; found ${sources.length}${sources.length > 1 ? `: ${quoted(sources)}` : ''}. ${fix}`,
       );
     }
 
@@ -1314,7 +1449,16 @@ export function discoverThemeDirectory(
           )
         ) {
           throw new ThemeRuntimeExportError(
-            `Theme "${slug}" for ${owner} entry "${entry}" does not export "${exportName}".`,
+            builtModuleDescriptorMessage(
+              label,
+              sourceDir,
+              entry,
+              exportName,
+              docs[0],
+              slug,
+              listing.files,
+            ) ??
+              `Theme "${slug}" for ${owner} entry "${entry}" does not export "${exportName}".`,
           );
         }
       } catch (error) {

package/foundation/doc-compiler/doc-loads.test.mjs

@@ -102,7 +102,15 @@ const RUNNERS = {
     runs: SELF_DOCS,
     sites: ['import ../../../api/blog/blog.doc.mjs', 'import ./blog.doc.mjs'],
   },
-  'clients/cli/commands/build-theme.mjs': {
+  'clients/cli/commands/manifest.mjs': {
+    runs: SELF_DOCS,
+    sites: ['import ./manifest.doc.mjs'],
+  },
+  'clients/cli/commands/postinstall.mjs': {
+    runs: SELF_DOCS,
+    sites: ['import ./postinstall.doc.mjs'],
+  },
+  'clients/cli/commands/theme.mjs': {
     runs: `${SELF_DOCS}; and \`astryx theme build\`, a child process per theme`,
     sites: [
       'child_process.spawn',
@@ -135,11 +143,11 @@ const RUNNERS = {
       'import ./build.doc.mjs',
     ],
   },
-  'clients/cli/commands/component/index.mjs': {
+  'clients/cli/commands/component.mjs': {
     runs: SELF_DOCS,
     sites: [
-      'import ../../../../api/component/component.doc.mjs',
-      'import ../component.doc.mjs',
+      'import ../../../api/component/component.doc.mjs',
+      'import ./component.doc.mjs',
     ],
   },
   'clients/cli/commands/discover.mjs': {
@@ -180,11 +188,11 @@ const RUNNERS = {
       'import ./gap-report.doc.mjs',
     ],
   },
-  'clients/cli/commands/hook/index.mjs': {
+  'clients/cli/commands/hook.mjs': {
     runs: SELF_DOCS,
     sites: [
-      'import ../../../../api/hook/hook.doc.mjs',
-      'import ../hook.doc.mjs',
+      'import ../../../api/hook/hook.doc.mjs',
+      'import ./hook.doc.mjs',
     ],
   },
   'clients/cli/commands/init.mjs': {
@@ -233,8 +241,8 @@ const RUNNERS = {
     ],
   },
   'clients/cli/index.mjs': {
-    runs: 'the command modules, to register each command, and the manifest command doc',
-    sites: ['import ./commands/manifest.doc.mjs', 'import(<computed>)'],
+    runs: 'the command modules, to register each command',
+    sites: ['import(<computed>)'],
   },
   'clients/cli/lib/manifest.mjs': {
     runs: 'the manifest command doc, for the exit codes the manifest reports',
@@ -248,6 +256,10 @@ const RUNNERS = {
     runs: 'astryx.config, through the config parser',
     sites: ['loadModuleWithParser(..., parseConfig)'],
   },
+  'foundation/agent-docs/agent-docs.mjs': {
+    runs: 'git, sl or hg, to read whether the repository ignores an untracked agent file',
+    sites: ['child_process.spawnSync'],
+  },
   'foundation/fs/file-protection.mjs': {
     runs: 'the ignore matcher (CommonJS), loaded when a resolver first reads an ignore file',
     sites: ['require(ignore)'],
@@ -272,6 +284,10 @@ const RUNNERS = {
     runs: 'a contributed topic, for its catalog fields: name, title, description, category, and relationships',
     sites: ['importDocModule'],
   },
+  'foundation/discovery/runner-commands.mjs': {
+    runs: "the package's topics, to find each Astryx command written with a package runner",
+    sites: ['loadTopicModule'],
+  },
   'foundation/discovery/stray-pointers.mjs': {
     runs: "the CLI's own guides, for their names, to tell which written `astryx docs <name>` points at a doc that exists",
     sites: ['builtinGuideFiles'],
@@ -315,6 +331,10 @@ const RUNNERS = {
       'require.cache',
     ],
   },
+  'foundation/fs/read-record.mjs': {
+    runs: "nothing; it wraps node:fs's read calls to record the paths an operation reads, and republishes them to ESM imports",
+    sites: ['module.syncBuiltinESMExports'],
+  },
   'foundation/fs/paths.mjs': {
     runs: "Yarn's pnpapi, under Plug'n'Play, to find an installed package",
     sites: ['require(pnpapi)'],
@@ -339,6 +359,10 @@ const RUNNERS = {
     runs: "the CLI release that answers a project's run, when it is not this copy",
     sites: ['child_process.spawn'],
   },
+  'host/index.mjs': {
+    runs: "another release's host entry, from one of the host's package sets, when that release answers a hosted run",
+    sites: ['import(<computed>)'],
+  },
   'scripts/generate-cli-readme.mjs': {
     runs: '`astryx manifest` and the error-code and response-type docs, to write the README tables (build time, not shipped)',
     sites: ['child_process.spawnSync', 'import(<computed>)'],

package/foundation/doc-compiler/read.mjs

@@ -173,8 +173,23 @@ export async function readDocView(file, options) {
   );
   if (result.loadFailed) throw result.loadFailure;
   if (result.missing) {
-    if (strict)
+    if (strict) {
+      // A doc that exports nothing its reader takes (an empty file, or one
+      // with other exports) is said plainly, with what it does export and
+      // the fix; the schema would only say "(root): Invalid input".
+      const exported =
+        options.exports ??
+        /** @type {Record<string, readonly string[]>} */ (DOC_EXPORTS)[
+          options.root
+        ] ??
+        [];
+      const problem =
+        result.missingValue === undefined
+          ? await missingDocProblem(file, options, exported)
+          : null;
+      if (problem) throw new Error(`${options.label ?? file} ${problem}`);
       parserFor(options.root)(result.missingValue, options.label ?? file);
+    }
     return result.missingValue;
   }
   if (strict && result.failed) throw result.failure;
@@ -182,6 +197,49 @@ export async function readDocView(file, options) {
   return result.view;
 }
 
+/**
+ * Why a doc file exports no doc, with the fix: it is empty, or it exports
+ * other names than the ones its reader takes. Null when neither explains it.
+ * @param {string} file
+ * @param {ReadOptions} options
+ * @param {readonly string[]} exported the export names the reader takes
+ * @returns {Promise<string | null>}
+ */
+async function missingDocProblem(file, options, exported) {
+  // A theme descriptor is read statically, never imported.
+  if (options.root === 'themes') return null;
+  const fix =
+    'Fix: export the doc object as the default export: `export default {type: ..., name: ..., ...}`.';
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  const code = text
+    .replace(/^\uFEFF/u, '')
+    .replace(/\/\*[\s\S]*?\*\//gu, '')
+    .replace(/(^|[^:])\/\/.*$/gmu, '$1')
+    .trim();
+  if (code === '') return `is empty, so it documents nothing. ${fix}`;
+  /** @type {string[]} */
+  let names;
+  try {
+    const mod = await LOADERS[options.loader ?? 'user'](file);
+    names = Object.keys(mod ?? {}).filter(name => name !== 'default');
+  } catch {
+    return null;
+  }
+  const takes = exported.map(name =>
+    name === 'default' ? 'default export' : `\`${name}\` export`,
+  );
+  const found =
+    names.length > 0
+      ? ` (it exports ${names.map(name => `\`${name}\``).join(', ')})`
+      : ' (it exports nothing)';
+  return `has no ${takes.join(' or ')}${found}, so it documents nothing. ${fix}`;
+}
+
 /**
  * Load one file as its root reads it: the doc its module exports and, for a
  * component or hook, the translation it exports for `lang`.

package/foundation/doc-compiler/read.test.mjs

@@ -109,10 +109,19 @@ describe('readDocView', () => {
     }
   });
 
-  it("reads a file with no doc as undefined, or as its parser's error when checked", async () => {
+  it('reads a file with no doc as undefined, or, checked, says what it exports instead', async () => {
     const file = write('Empty.doc.mjs', 'export const unrelated = 1;\n');
     await expect(loadDocs(file)).resolves.toBeUndefined();
-    await expect(loadComponentDoc(file)).rejects.toThrow(`${file} is invalid`);
+    await expect(loadComponentDoc(file)).rejects.toThrow(
+      `${file} has no default export or \`docs\` export (it exports \`unrelated\`), so it documents nothing. Fix: export the doc object as the default export`,
+    );
+  });
+
+  it('says a checked doc file is empty', async () => {
+    const file = write('Blank.doc.mjs', '// nothing yet\n');
+    await expect(loadComponentDoc(file)).rejects.toThrow(
+      `${file} is empty, so it documents nothing.`,
+    );
   });
 
   it('applies the translation a module exports for the reading language', async () => {

package/foundation/doc-compiler/split-topic-keywords.test.mjs

@@ -3,7 +3,8 @@
 /**
  * @file A topic split into a namespace of guides indexes each term once, a
  * policy of the docs split itself (no spec clause states it). Below the CLI's own
- * root namespaces (every one but `cli`, its command and API reference), a
+ * root namespaces (every one but `cli`, its command and API reference, and
+ * `authoring`, the integration guides `cli` held before this rule), a
  * guide's search keywords are its own: none repeats a keyword its namespace,
  * a sibling, or a guide of another split topic declares. A term several
  * guides share belongs to their namespace, or to none.
@@ -45,7 +46,7 @@ describe('the keywords of a split topic', () => {
       return doc?.name;
     };
     const roots = [...docs.values()]
-      .filter(doc => doc.type === 'namespace' && !parentOf(doc) && doc.name !== 'cli')
+      .filter(doc => doc.type === 'namespace' && !parentOf(doc) && !['cli', 'authoring'].includes(doc.name))
       .map(doc => doc.name);
     expect(roots).toContain('layout');
 

package/foundation/doc-compiler/tree.d.mts

@@ -9,7 +9,7 @@
  * the one adoption rule in its package that matches its group and kind. A
  * placement that fails withdraws the doc; it never falls back to adoption. A
  * doc with neither is a flat topic: it keeps its flat name as its route, and its
- * home is the generated Unorganized level. The CLI keeps its own routes: an
+ * home is the generated level for its category. The CLI keeps its own routes: an
  * integration's node that would take one is withdrawn with a diagnostic.
  *
  * @param {{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], topics?: TreeTopicInput[]}} inputs
@@ -117,19 +117,39 @@ export const KIND_GROUPS: Readonly<Record<string, {
  */
 /**
  * A flat topic: a reference topic that no namespace places. The tree gives it
- * a home in the generated Unorganized level, under its own name.
+ * a home in the generated level for its category (Guides or Foundations),
+ * under its own name.
  * @typedef {object} TreeTopicInput
  * @property {string} provider the package that owns the topic
  * @property {string} providerId the provider's ProviderId
  * @property {string} name the topic's name, which stays its route
  * @property {string} title
  * @property {string} summary
+ * @property {string | null} [category] the topic's sidebar group:
+ *   `foundations` puts it in Foundations; anything else, in Guides
  * @property {string} source where the topic comes from, for diagnostics
  * @property {string[]} [aliases] every other name the topic answers to: the
  *   topics it replaced, directly or through a chain
  */
-/** The route of the generated level that holds every flat topic. */
-export const UNORGANIZED: "unorganized";
+/**
+ * The generated levels that hold the flat topics, by category
+ * (spec:AST-046 FR12). A topic keeps its own name as its route; its level is
+ * only where it sits. Readers see these titles in a topic's path, so each is
+ * a plain name for what the topics are.
+ */
+export const TOPIC_LEVELS: Readonly<{
+    guides: Readonly<{
+        route: "guides";
+        title: "Guides";
+        summary: "Guides that stand on their own: getting started, principles, theming, and working with AI. Each topic keeps its own name; open one by it.";
+    }>;
+    foundations: Readonly<{
+        route: "foundations";
+        title: "Foundations";
+        summary: "Color, elevation, icons, illustrations, motion, shape, and spacing: the visual foundations every component builds on. Each topic keeps its own name; open one by it.";
+    }>;
+}>;
+export function topicLevel(category: string | null | undefined): "guides" | "foundations";
 export type NamespaceDoc = import("../../authoring/doctypes/namespace/type").NamespaceDoc;
 export type DocPlacement = import("../../authoring/doctypes/base/type").DocPlacement;
 export type CompilerDiagnostic = import("./diagnostics.mjs").CompilerDiagnostic;
@@ -200,7 +220,8 @@ export type TreeSlot = {
 };
 /**
  * A flat topic: a reference topic that no namespace places. The tree gives it
- * a home in the generated Unorganized level, under its own name.
+ * a home in the generated level for its category (Guides or Foundations),
+ * under its own name.
  */
 export type TreeTopicInput = {
     /**
@@ -217,6 +238,11 @@ export type TreeTopicInput = {
     name: string;
     title: string;
     summary: string;
+    /**
+     * the topic's sidebar group:
+     * `foundations` puts it in Foundations; anything else, in Guides
+     */
+    category?: string | null | undefined;
     /**
      * where the topic comes from, for diagnostics
      */
@@ -265,7 +291,7 @@ export type TreeNode = {
     order: number | null;
     /**
      * made by the compiler (a `groupBy: 'kind'`
-     * level, or the Unorganized level), not authored
+     * level, or a flat topics' level), not authored
      */
     generated: boolean;
     /**

package/foundation/doc-compiler/tree.mjs

@@ -12,7 +12,7 @@
  * @position Between discovery and the readers: `astryx docs <route>`,
  *   `astryx doctor`, and the docsite build all read this tree. The CLI's docs
  *   and each integration's have a home here, and a flat topic's home is the
- *   generated Unorganized level.
+ *   generated level for its category: Guides or Foundations.
  *   A namespace never scans files and never lists its children: a child names
  *   its parent, or a namespace adopts a discovery group.
  */
@@ -113,20 +113,49 @@ export const KIND_GROUPS = Object.freeze({
 
 /**
  * A flat topic: a reference topic that no namespace places. The tree gives it
- * a home in the generated Unorganized level, under its own name.
+ * a home in the generated level for its category (Guides or Foundations),
+ * under its own name.
  * @typedef {object} TreeTopicInput
  * @property {string} provider the package that owns the topic
  * @property {string} providerId the provider's ProviderId
  * @property {string} name the topic's name, which stays its route
  * @property {string} title
  * @property {string} summary
+ * @property {string | null} [category] the topic's sidebar group:
+ *   `foundations` puts it in Foundations; anything else, in Guides
  * @property {string} source where the topic comes from, for diagnostics
  * @property {string[]} [aliases] every other name the topic answers to: the
  *   topics it replaced, directly or through a chain
  */
 
-/** The route of the generated level that holds every flat topic. */
-export const UNORGANIZED = 'unorganized';
+/**
+ * The generated levels that hold the flat topics, by category
+ * (spec:AST-046 FR12). A topic keeps its own name as its route; its level is
+ * only where it sits. Readers see these titles in a topic's path, so each is
+ * a plain name for what the topics are.
+ */
+export const TOPIC_LEVELS = Object.freeze({
+  guides: Object.freeze({
+    route: 'guides',
+    title: 'Guides',
+    summary:
+      'Guides that stand on their own: getting started, principles, theming, and working with AI. Each topic keeps its own name; open one by it.',
+  }),
+  foundations: Object.freeze({
+    route: 'foundations',
+    title: 'Foundations',
+    summary:
+      'Color, elevation, icons, illustrations, motion, shape, and spacing: the visual foundations every component builds on. Each topic keeps its own name; open one by it.',
+  }),
+});
+
+/**
+ * The generated level a flat topic sits in.
+ * @param {string | null | undefined} category
+ * @returns {'guides' | 'foundations'}
+ */
+export const topicLevel = category =>
+  category === 'foundations' ? 'foundations' : 'guides';
 
 /**
  * @typedef {object} TreeNode
@@ -145,7 +174,7 @@ export const UNORGANIZED = 'unorganized';
  * @property {string | null} slot the parent slot this node sits in
  * @property {number | null} order
  * @property {boolean} generated made by the compiler (a `groupBy: 'kind'`
- *   level, or the Unorganized level), not authored
+ *   level, or a flat topics' level), not authored
  * @property {TreeSlot[]} slots a namespace's slots; empty for a leaf
  * @property {string} source
  * @property {any} [ref]
@@ -216,7 +245,7 @@ function resolveParent(parent, provider, declared) {
  * the one adoption rule in its package that matches its group and kind. A
  * placement that fails withdraws the doc; it never falls back to adoption. A
  * doc with neither is a flat topic: it keeps its flat name as its route, and its
- * home is the generated Unorganized level. The CLI keeps its own routes: an
+ * home is the generated level for its category. The CLI keeps its own routes: an
  * integration's node that would take one is withdrawn with a diagnostic.
  *
  * @param {{namespaces: TreeNamespaceInput[], docs: TreeDocInput[], topics?: TreeTopicInput[]}} inputs
@@ -237,10 +266,15 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
     );
 
   // Routes the CLI's own docs keep (spec:AST-046 FR11): the name of each of
-  // its flat topics, and the generated Unorganized level. Its namespaces keep
-  // theirs by rank, because they go into the tree first. Routes compare
-  // without case, as topic names do, so `CLI` claims `cli`.
-  const cliRoutes = new Set(topics.length > 0 ? [UNORGANIZED] : []);
+  // its flat topics, and the generated levels that hold flat topics. Its
+  // namespaces keep theirs by rank, because they go into the tree first.
+  // Routes compare without case, as topic names do, so `CLI` claims `cli`.
+  /** @type {Set<string>} */
+  const cliRoutes = new Set(
+    topics.length > 0
+      ? Object.values(TOPIC_LEVELS).map(level => level.route)
+      : [],
+  );
   for (const topic of topics) {
     if (topic.provider === CLI_PROVIDER)
       cliRoutes.add(topic.name.toLowerCase());
@@ -592,20 +626,21 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
     );
   }
 
-  // The generated Unorganized level (spec:AST-046 FR12): every flat topic sits
-  // here, in the order the topic list reads, so every doc has a home in the
-  // tree. A topic keeps its own name as its route.
-  if (topics.length > 0) {
+  // The generated levels (spec:AST-046 FR12): every flat topic sits in the
+  // level for its category, in the order the topic list reads, so every doc
+  // has a named home in the tree. A topic keeps its own name as its route.
+  for (const [key, level] of Object.entries(TOPIC_LEVELS)) {
+    const members = topics.filter(topic => topicLevel(topic.category) === key);
+    if (members.length === 0) continue;
     const home = {
       id: null,
-      route: UNORGANIZED,
+      route: level.route,
       kind: 'namespace',
       provider: CLI_PROVIDER,
       providerId: CLI_PROVIDER_ID,
-      name: UNORGANIZED,
-      title: 'Unorganized',
-      summary:
-        'Every topic that no section places yet. Each keeps its own name; open one by it.',
+      name: level.route,
+      title: level.title,
+      summary: level.summary,
       parent: null,
       slot: null,
       order: null,
@@ -613,30 +648,29 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
       slots: [{name: 'topics', title: 'Topics', children: []}],
       source: 'generated',
     };
-    if (addNode(home, {provider: CLI_PROVIDER, source: 'generated'})) {
-      topics.forEach((topic, i) => {
-        addNode(
-          {
-            id: createDocId(topic.providerId, 'generic', topic.name),
-            route: topic.name,
-            kind: 'generic',
-            provider: topic.provider,
-            providerId: topic.providerId,
-            name: topic.name,
-            title: topic.title,
-            summary: topic.summary,
-            parent: UNORGANIZED,
-            slot: 'topics',
-            order: i,
-            generated: false,
-            slots: [],
-            source: topic.source,
-            ref: {flatTopic: topic.name},
-          },
-          topic,
-        );
-      });
-    }
+    if (!addNode(home, {provider: CLI_PROVIDER, source: 'generated'})) continue;
+    members.forEach((topic, i) => {
+      addNode(
+        {
+          id: createDocId(topic.providerId, 'generic', topic.name),
+          route: topic.name,
+          kind: 'generic',
+          provider: topic.provider,
+          providerId: topic.providerId,
+          name: topic.name,
+          title: topic.title,
+          summary: topic.summary,
+          parent: level.route,
+          slot: 'topics',
+          order: i,
+          generated: false,
+          slots: [],
+          source: topic.source,
+          ref: {flatTopic: topic.name},
+        },
+        topic,
+      );
+    });
   }
 
   // Children, per slot, in reading order: order, then title, then id.