@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/api/hook/list/list.mjs

@@ -13,7 +13,10 @@
  * @position api/hook/list/list.mjs — dispatched from ../hook.mjs
  */
 
-import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
+import {
+  discoverHooks,
+  findHookDoc,
+} from '../../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
@@ -28,7 +31,13 @@ import {resolveCoreDir} from '../_adapter.mjs';
  * @param {string|null} [options.lang]
  * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
  */
-export async function list({cwd = process.cwd(), category, detail = 'names', zh = false, lang = null} = {}) {
+export async function list({
+  cwd = process.cwd(),
+  category,
+  detail = 'names',
+  zh = false,
+  lang = null,
+} = {}) {
   const coreDir = resolveCoreDir(cwd);
   const hooks = discoverHooks(coreDir);
 
@@ -51,20 +60,31 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+            const docs = await loadDocs(docPath, {zh, lang, root: 'hooks'});
             entries.push({
               name: hookName,
               description: docs.usage?.description || '',
               import: docs.importPath || '@astryxdesign/core/hooks',
             });
           } catch {
-            entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+            entries.push({
+              name: hookName,
+              description: '',
+              import: '@astryxdesign/core/hooks',
+            });
           }
         } else {
-          entries.push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+          entries.push({
+            name: hookName,
+            description: '',
+            import: '@astryxdesign/core/hooks',
+          });
         }
       }
-      return {type: 'hook.list', data: {detail: 'compact', components: {[match[0]]: entries}}};
+      return {
+        type: 'hook.list',
+        data: {detail: 'compact', components: {[match[0]]: entries}},
+      };
     }
 
     if (detail === 'full') {
@@ -74,19 +94,33 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            entries.push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
+            entries.push(await loadDocs(docPath, {zh, lang, root: 'hooks'}));
           } catch {
-            entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+            entries.push(
+              /** @type {import('../hook.type.mjs').HookDoc} */ ({
+                name: hookName,
+              }),
+            );
           }
         } else {
-          entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+          entries.push(
+            /** @type {import('../hook.type.mjs').HookDoc} */ ({
+              name: hookName,
+            }),
+          );
         }
       }
-      return {type: 'hook.list', data: {detail: 'full', components: {[match[0]]: entries}}};
+      return {
+        type: 'hook.list',
+        data: {detail: 'full', components: {[match[0]]: entries}},
+      };
     }
 
     // Default: names only
-    return {type: 'hook.list', data: {detail: 'names', components: {[match[0]]: match[1]}}};
+    return {
+      type: 'hook.list',
+      data: {detail: 'names', components: {[match[0]]: match[1]}},
+    };
   }
 
   // All hooks
@@ -99,17 +133,25 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            const docs = await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+            const docs = await loadDocs(docPath, {zh, lang, root: 'hooks'});
             result[cat].push({
               name: hookName,
               description: docs.usage?.description || '',
               import: docs.importPath || '@astryxdesign/core/hooks',
             });
           } catch {
-            result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+            result[cat].push({
+              name: hookName,
+              description: '',
+              import: '@astryxdesign/core/hooks',
+            });
           }
         } else {
-          result[cat].push({name: hookName, description: '', import: '@astryxdesign/core/hooks'});
+          result[cat].push({
+            name: hookName,
+            description: '',
+            import: '@astryxdesign/core/hooks',
+          });
         }
       }
     }
@@ -125,12 +167,22 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
         const docPath = findHookDoc(coreDir, hookName);
         if (docPath) {
           try {
-            result[cat].push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
+            result[cat].push(
+              await loadDocs(docPath, {zh, lang, root: 'hooks'}),
+            );
           } catch {
-            result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+            result[cat].push(
+              /** @type {import('../hook.type.mjs').HookDoc} */ ({
+                name: hookName,
+              }),
+            );
           }
         } else {
-          result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
+          result[cat].push(
+            /** @type {import('../hook.type.mjs').HookDoc} */ ({
+              name: hookName,
+            }),
+          );
         }
       }
     }

package/api/index.d.mts

@@ -38,7 +38,7 @@ export * from "./integration/pack-check.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export * from "./integration/authoring-checks.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
-export { themeBuild, themeAdd, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
+export { themeBuild, themeAdd, themeTemplate, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
 export { layoutExpand, layoutCheck, layoutGrammar } from "./layout/layout.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";
 export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";

package/api/index.mjs

@@ -28,6 +28,7 @@ export {template} from './template/template.mjs';
 export {
   themeBuild,
   themeAdd,
+  themeTemplate,
   themeList,
   themeListAvailable,
   themeTargets,

package/api/init/init.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'init',
+  namespace: 'cli/api',
   displayName: 'init()',
   summary:
     'Non-interactive project setup: install agent docs and point at the theme + build workflows.',
@@ -101,5 +102,5 @@ export const doc = {
     {label: 'Remove agent docs', code: 'await init({removeAgents: true});'},
   ],
   command: 'init',
-  related: ['doctor', 'upgrade', 'build', 'theme'],
+  related: ['doctor', 'upgrade', 'build', 'themeTemplate'],
 };

package/api/integration/add-contribution.d.mts

@@ -31,7 +31,7 @@ export function integrationAddAgentDoc(line: string, options?: import("./integra
  *
  * @param {'component'|'doc'|'template'|'codemod'|'agent-doc'|'theme'} kind
  * @param {string} name
- * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string}} [options]
+ * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string}} [options]
  * @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
  */
 export function integrationAdd(kind: "component" | "doc" | "template" | "codemod" | "agent-doc" | "theme", name: string, options?: {
@@ -41,4 +41,5 @@ export function integrationAdd(kind: "component" | "doc" | "template" | "codemod
     to?: string;
     replaces?: string;
     extends?: string;
+    parent?: string;
 }): Promise<import("./integration-authoring.type.mjs").IntegrationAddResponse>;

package/api/integration/add-contribution.mjs

@@ -5,8 +5,7 @@
  * contribution into an integration package.
  *
  * Dispatches component, doc, template, codemod, and agent-doc. Theme
- * delegates to the existing `integrationAddTheme` (not modified here).
- * Every root-based kind shares: first add creates the manifest; one shared
+ * delegates to the dedicated same-stem descriptor writer. Every root-based kind shares: first add creates the manifest; one shared
  * writer; never creates `files`/`exports`; atomic staged writes; no clobber;
  * dry-run receipt predicts real run; post-write verify through the real
  * discovery/parser seam.
@@ -35,6 +34,11 @@ import {
 } from '../../foundation/integrations/integrations.mjs';
 import {isValidSemver} from '../../foundation/env/semver.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
+import {
+  docsTreeCliProblem,
+  withDocsTreeCli,
+} from '../../foundation/integrations/cli-requirement.mjs';
+import {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
 import {findIntegrationComponentDoc} from '../../foundation/discovery/component-discovery.mjs';
 import {parseAgentDocsField} from '../../authoring/integration/schema.mjs';
 import {integrationAddTheme} from './add-theme.mjs';
@@ -84,6 +88,17 @@ function resolvePackage(cwd) {
   }
   const owner = typeof pkg.name === 'string' ? pkg.name : '(local integration)';
   const existingManifest = findLocalIntegrationManifestOrNull(packageDir);
+  // The nearest package.json above the cwd may belong to another package (an
+  // app that contains the folder). Only a package that is already an
+  // integration is found from a subfolder; the first add runs in the package.
+  const here = path.resolve(cwd ?? process.cwd());
+  if (existingManifest == null && path.resolve(packageDir) !== here) {
+    throw new AstryxError(
+      `${here} has no package.json. The nearest is ${packageFile} (${owner}), which is not an Astryx integration yet. Run this in your integration package's own directory, next to its package.json.`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
   const manifestFile =
     existingManifest ?? path.join(packageDir, 'astryx.integration.mjs');
   return {
@@ -263,7 +278,7 @@ async function addComponent(name, options) {
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
   const importSpecifier = `${owner}/${extensionlessPath}`;
-  const docContents = `export default {\n  type: 'component',\n  name: '${name}',\n  import: ${JSON.stringify(importSpecifier)},\n  description: '${name} component.',\n  props: [],\n};\n`;
+  const docContents = `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */\nexport default {\n  type: 'component',\n  name: '${name}',\n  displayName: '${name}',\n  import: ${JSON.stringify(importSpecifier)},\n  usage: {description: '${name} component.'},\n  props: [],\n};\n`;
   const sourceContents = `export function ${name}() {\n  return <div>${name}</div>;\n}\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */
@@ -354,7 +369,7 @@ async function addComponent(name, options) {
 
 /**
  * @param {string} name  topic name (must match [\w-]+)
- * @param {{cwd?: string, dryRun?: boolean, replaces?: string, extends?: string}} options
+ * @param {{cwd?: string, dryRun?: boolean, replaces?: string, extends?: string, parent?: string}} options
  * @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
  */
 async function addDoc(name, options) {
@@ -373,6 +388,20 @@ async function addDoc(name, options) {
       ERROR_CODES.ERR_INVALID_ARGUMENT,
     );
   }
+  if (options.parent != null && (options.replaces != null || options.extends != null)) {
+    throw new AstryxError(
+      'A guide placed in a namespace has its own route: it cannot also replace or extend a topic.',
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  if (options.parent != null && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(options.parent)) {
+    throw new AstryxError(
+      '--parent must name a namespace in lowercase letters and digits joined by single hyphens, such as "acme".',
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
   for (const [option, value] of [
     ['--replaces', options.replaces],
     ['--extends', options.extends],
@@ -433,20 +462,92 @@ async function addDoc(name, options) {
   }
 
   const title = kebabToTitle(name);
+  // --parent names a namespace of this package by its name, wherever its file
+  // is. An existing one is used as it is: its `guides` slot, or else its only
+  // slot that takes a guide. Otherwise the namespace doc is written, unless a
+  // file of that name is already something else (spec:AST-046 FR11).
+  const namespaceFile =
+    options.parent == null
+      ? null
+      : assertWithin(`${options.parent}.doc.mjs`, root, {
+          label: 'namespace doc file',
+        });
+  let parentSlot = 'guides';
+  let writeNamespace = false;
+  if (options.parent != null && namespaceFile != null) {
+    const {namespaces} = await discoverIntegrationDocs({
+      name: owner,
+      docs: root,
+    });
+    const existing = namespaces.find(ns => ns.doc.name === options.parent);
+    if (existing != null) {
+      const takesGuides = Object.entries(existing.doc.slots ?? {})
+        .filter(([, slot]) => slot?.accepts?.kinds?.includes('generic'))
+        .map(([slotName]) => slotName);
+      const slot = takesGuides.includes('guides')
+        ? 'guides'
+        : takesGuides.length === 1
+          ? takesGuides[0]
+          : null;
+      if (slot == null) {
+        throw new AstryxError(
+          takesGuides.length === 0
+            ? `Namespace "${options.parent}" (${existing.source}) has no slot that takes a guide. Add one, such as guides: {title: 'Guides', accepts: {kinds: ['generic']}}.`
+            : `Namespace "${options.parent}" (${existing.source}) has more than one slot that takes a guide (${takesGuides.join(', ')}). Write the guide yourself, and name its slot in its placement.`,
+          undefined,
+          ERROR_CODES.ERR_INVALID_ARGUMENT,
+        );
+      }
+      parentSlot = slot;
+    } else if (fs.existsSync(namespaceFile)) {
+      throw new AstryxError(
+        `${projectPath(path.relative(packageDir, namespaceFile))} exists but does not load as the namespace "${options.parent}". Fix or rename that file, or pass another --parent.`,
+        undefined,
+        ERROR_CODES.ERR_FILE_EXISTS,
+      );
+    } else {
+      writeNamespace = true;
+    }
+  }
   const relationship = options.replaces
     ? `\n  replaces: '${options.replaces}',`
     : options.extends
       ? `\n  extends: '${options.extends}',`
-      : '';
-  const docContents = `export default {\n  type: 'generic',\n  name: '${name}',\n  title: '${title}',\n  description: '${title} documentation.',${relationship}\n  sections: [\n    {\n      title: 'Overview',\n      content: [\n        { type: 'prose', text: '${title} documentation.' },\n      ],\n    },\n  ],\n};\n`;
+      : options.parent
+        ? `\n  placement: {parent: 'namespace:${options.parent}', slot: '${parentSlot}'},`
+        : '';
+  const namespaceTitle =
+    options.parent == null ? '' : kebabToTitle(options.parent);
+  const namespaceContents = `/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */\nexport default {\n  type: 'namespace',\n  name: '${options.parent}',\n  title: '${namespaceTitle}',\n  summary: 'Guides for ${namespaceTitle}.',\n  slots: {\n    guides: {title: 'Guides', accepts: {kinds: ['generic']}},\n  },\n};\n`;
+  const docContents = `/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n  type: 'generic',\n  name: '${name}',\n  title: '${title}',\n  description: '${title} documentation.',${relationship}\n  sections: [\n    {\n      title: 'Overview',\n      content: [\n        { type: 'prose', text: '${title} documentation.' },\n      ],\n    },\n  ],\n};\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */
   const plans = [{path: docFile, contents: docContents, createOnly: true}];
-  const pkgUpdate = packageJsonUpdate(
+  if (namespaceFile != null && writeNamespace) {
+    plans.push({path: namespaceFile, contents: namespaceContents, createOnly: true});
+  }
+  let pkgUpdate = packageJsonUpdate(
     packageFile,
     rootPath,
     path.basename(manifestFile),
   );
+  // A namespace doc needs a CLI that reads it: an older one hides every doc
+  // topic the package ships. Declare that CLI as a peer, so an older one fails
+  // at install instead (spec:AST-046 FR11).
+  if (options.parent != null) {
+    const expectedOriginal =
+      pkgUpdate?.expectedOriginal ?? fs.readFileSync(packageFile);
+    const text = pkgUpdate?.contents ?? expectedOriginal.toString('utf-8');
+    const current = JSON.parse(text);
+    if (docsTreeCliProblem(current) != null) {
+      pkgUpdate = {
+        contents:
+          JSON.stringify(withDocsTreeCli(current), null, 2) +
+          (text.endsWith('\n') ? '\n' : ''),
+        expectedOriginal,
+      };
+    }
+  }
   if (pkgUpdate != null) {
     plans.push({
       path: packageFile,
@@ -565,8 +666,8 @@ async function addTemplate(name, options) {
     throw error;
   }
 
-  const specFile = assertWithin(`${name}.template.mjs`, root, {
-    label: 'template spec',
+  const specFile = assertWithin(`${name}.doc.mjs`, root, {
+    label: 'template descriptor',
   });
   const sourceFile = assertWithin(`${name}.tsx`, root, {
     label: 'template source',
@@ -589,7 +690,8 @@ async function addTemplate(name, options) {
   const pascalName = kebabToPascal(name);
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
   const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
-  const specContents = `export default {\n  type: '${templateType}',\n  name: '${name}',\n  description: '${kebabToTitle(name)} template.',\n};\n`;
+  const blockFields = templateType === 'block' ? '\n  aspectRatio: 1,' : '';
+  const specContents = `/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n  type: '${templateType}',\n  name: '${name}',\n  displayName: '${kebabToTitle(name)}',\n  description: '${kebabToTitle(name)} template.',${blockFields}\n};\n`;
   const sourceContents = `export default function ${pascalName}() {\n  return <div>${kebabToTitle(name)}</div>;\n}\n`;
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */
@@ -1105,7 +1207,7 @@ export function integrationAddAgentDoc(line, options = {}) {
 
 const KIND_OPTIONS = {
   component: new Set(['cwd', 'dryRun']),
-  doc: new Set(['cwd', 'dryRun', 'replaces', 'extends']),
+  doc: new Set(['cwd', 'dryRun', 'replaces', 'extends', 'parent']),
   template: new Set(['cwd', 'dryRun', 'templateType']),
   codemod: new Set(['cwd', 'dryRun', 'to']),
   'agent-doc': new Set(['cwd', 'dryRun']),
@@ -1136,7 +1238,7 @@ function validateKindOptions(kind, options) {
  *
  * @param {'component'|'doc'|'template'|'codemod'|'agent-doc'|'theme'} kind
  * @param {string} name
- * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string}} [options]
+ * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string}} [options]
  * @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
  */
 export async function integrationAdd(kind, name, options = {}) {

package/api/integration/add-contribution.test.mjs

@@ -12,6 +12,7 @@ import {
   integrationAddTemplate,
 } from './add-contribution.mjs';
 import {validateLocalIntegration} from './validate-integration.mjs';
+import {DOCS_TREE_CLI} from '../../foundation/integrations/cli-requirement.mjs';
 
 let tmpDir;
 
@@ -77,6 +78,7 @@ describe('integrationAdd component', () => {
       path.join(tmpDir, 'components/MyWidget.doc.mjs'),
       'utf-8',
     );
+    expect(doc).toContain("@astryxdesign/cli/authoring').ComponentDoc");
     expect(doc).toContain("type: 'component'");
     expect(doc).toContain("name: 'MyWidget'");
     expect(doc).toContain('props: []');
@@ -304,6 +306,7 @@ describe('integrationAdd doc', () => {
       path.join(tmpDir, 'docs/my-guide.doc.mjs'),
       'utf-8',
     );
+    expect(doc).toContain("@astryxdesign/cli/authoring').ReferenceDoc");
     expect(doc).toContain("type: 'generic'");
     expect(doc).toContain("name: 'my-guide'");
 
@@ -312,6 +315,142 @@ describe('integrationAdd doc', () => {
     expect(docErrors).toEqual([]);
   });
 
+  it('refuses to write from a folder with no package.json into the package above it', async () => {
+    setupBare();
+    const inside = path.join(tmpDir, 'kit');
+    fs.mkdirSync(inside);
+    await expect(
+      integrationAdd('doc', 'my-guide', {cwd: inside, parent: 'acme'}),
+    ).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: expect.stringContaining('has no package.json'),
+    });
+    expect(fs.existsSync(path.join(tmpDir, 'docs'))).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'astryx.integration.mjs'))).toBe(false);
+  });
+
+  it('finds an integration from a folder inside it', async () => {
+    setup();
+    const inside = path.join(tmpDir, 'src');
+    fs.mkdirSync(inside);
+    const result = await integrationAdd('doc', 'my-guide', {cwd: inside});
+    expect(result.data.files).toContain('docs/my-guide.doc.mjs');
+    expect(fs.existsSync(path.join(tmpDir, 'docs/my-guide.doc.mjs'))).toBe(true);
+  });
+
+  it('places a guide in a namespace of the package, writing the namespace once', async () => {
+    setup();
+    const first = await integrationAdd('doc', 'deploying', {
+      cwd: tmpDir,
+      parent: 'acme',
+    });
+    expect(first.data.files).toEqual(
+      expect.arrayContaining(['docs/deploying.doc.mjs', 'docs/acme.doc.mjs']),
+    );
+    const guide = fs.readFileSync(path.join(tmpDir, 'docs/deploying.doc.mjs'), 'utf-8');
+    expect(guide).toContain("placement: {parent: 'namespace:acme', slot: 'guides'}");
+    const namespace = fs.readFileSync(path.join(tmpDir, 'docs/acme.doc.mjs'), 'utf-8');
+    expect(namespace).toContain("type: 'namespace'");
+    expect(namespace).toContain("guides: {title: 'Guides', accepts: {kinds: ['generic']}}");
+
+    // The namespace doc needs a CLI that reads it, declared as an optional peer.
+    const pkg = JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'));
+    expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': `>=${DOCS_TREE_CLI}`});
+    expect(pkg.peerDependenciesMeta).toEqual({'@astryxdesign/cli': {optional: true}});
+
+    const second = await integrationAdd('doc', 'upgrading', {
+      cwd: tmpDir,
+      parent: 'acme',
+    });
+    expect(second.data.files).not.toContain('docs/acme.doc.mjs');
+
+    const validation = await validateLocalIntegration(tmpDir);
+    expect(validation.issues.filter(i => i.code === 'invalid_doc')).toEqual([]);
+  });
+
+  it('finds the --parent namespace by its name, wherever its file is, and uses its slot', async () => {
+    setup({manifest: "export default {docs: './docs'};\n"});
+    fs.mkdirSync(path.join(tmpDir, 'docs', 'ns'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'ns', 'acme.doc.mjs'),
+      "export default {type: 'namespace', name: 'acme', title: 'Acme', summary: 'Acme.', slots: {items: {title: 'Items', accepts: {kinds: ['generic']}}}};\n",
+    );
+    const result = await integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'acme'});
+    expect(result.data.files).not.toContain('docs/acme.doc.mjs');
+    expect(fs.existsSync(path.join(tmpDir, 'docs', 'acme.doc.mjs'))).toBe(false);
+    expect(fs.readFileSync(path.join(tmpDir, 'docs', 'deploying.doc.mjs'), 'utf-8')).toContain(
+      "placement: {parent: 'namespace:acme', slot: 'items'}",
+    );
+  });
+
+  it('refuses --parent when its file is not that namespace, or the namespace has no slot for a guide', async () => {
+    setup({manifest: "export default {docs: './docs'};\n"});
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    const nsFile = path.join(tmpDir, 'docs', 'acme.doc.mjs');
+    fs.writeFileSync(
+      nsFile,
+      "export default {type: 'generic', name: 'acme', title: 'Acme', description: 'A topic.', sections: [{title: 'Only', content: [{type: 'prose', text: 'x'}]}]};\n",
+    );
+    await expect(
+      integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'acme'}),
+    ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+    // A fresh file: the module loader keeps the first import of a path.
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'beta.doc.mjs'),
+      "export default {type: 'namespace', name: 'beta', title: 'Beta', summary: 'Beta.', slots: {items: {title: 'Items', accepts: {kinds: ['function']}}}};\n",
+    );
+    await expect(
+      integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'beta'}),
+    ).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: expect.stringContaining('no slot that takes a guide'),
+    });
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'gamma.doc.mjs'),
+      "export default {type: 'namespace', name: 'gamma', title: 'Gamma', summary: 'Gamma.', slots: {guides: {title: 'Guides', accepts: {kinds: ['function']}}, more: {title: 'More', accepts: {kinds: ['generic']}}, extra: {title: 'Extra', accepts: {kinds: ['generic']}}}};\n",
+    );
+    await expect(
+      integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'gamma'}),
+    ).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: expect.stringContaining('more than one slot that takes a guide (more, extra)'),
+    });
+    expect(fs.existsSync(path.join(tmpDir, 'docs', 'deploying.doc.mjs'))).toBe(false);
+  });
+
+  it('raises a CLI peer that admits a CLI too old for namespace docs, and keeps one that does not', async () => {
+    setup();
+    const file = path.join(tmpDir, 'package.json');
+    const write = (/** @type {string} */ range) => {
+      const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      pkg.peerDependencies = {'@astryxdesign/cli': range};
+      fs.writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+    };
+    write('^0.6.0');
+    await integrationAdd('doc', 'deploying', {cwd: tmpDir, parent: 'acme'});
+    expect(JSON.parse(fs.readFileSync(file, 'utf-8')).peerDependencies).toEqual({
+      '@astryxdesign/cli': `>=${DOCS_TREE_CLI}`,
+    });
+    write('^9.1.0');
+    await integrationAdd('doc', 'upgrading', {cwd: tmpDir, parent: 'acme'});
+    expect(JSON.parse(fs.readFileSync(file, 'utf-8')).peerDependencies).toEqual({
+      '@astryxdesign/cli': '^9.1.0',
+    });
+  });
+
+  it('refuses --parent with a relationship, or a namespace name that is not a route segment', async () => {
+    setup();
+    await expect(
+      integrationAdd('doc', 'x', {cwd: tmpDir, parent: 'acme', replaces: 'getting-started'}),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+    await expect(
+      integrationAdd('doc', 'x', {cwd: tmpDir, parent: 'Acme Kit'}),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+    await expect(
+      integrationAdd('template', 'x', {cwd: tmpDir, parent: 'acme'}),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+  });
+
   it('includes replaces in the generated doc', async () => {
     setup();
     const result = await integrationAdd('doc', 'my-tokens', {
@@ -390,13 +529,14 @@ describe('integrationAdd template', () => {
     expect(result.data.kind).toBe('template');
     expect(result.data.name).toBe('my-widget');
     expect(result.data.root).toEqual({path: './templates', created: true});
-    expect(result.data.files).toContain('templates/my-widget.template.mjs');
+    expect(result.data.files).toContain('templates/my-widget.doc.mjs');
     expect(result.data.files).toContain('templates/my-widget.tsx');
 
     const spec = fs.readFileSync(
-      path.join(tmpDir, 'templates/my-widget.template.mjs'),
+      path.join(tmpDir, 'templates/my-widget.doc.mjs'),
       'utf-8',
     );
+    expect(spec).toContain("@astryxdesign/cli/authoring').TemplateDoc");
     expect(spec).toContain("type: 'page'");
     expect(spec).toContain("name: 'my-widget'");
 
@@ -432,10 +572,11 @@ describe('integrationAdd template', () => {
       templateType: 'block',
     });
     const spec = fs.readFileSync(
-      path.join(tmpDir, 'templates/my-card.template.mjs'),
+      path.join(tmpDir, 'templates/my-card.doc.mjs'),
       'utf-8',
     );
     expect(spec).toContain("type: 'block'");
+    expect(spec).toContain('aspectRatio: 1');
   });
 
   it('rejects an invalid template type', async () => {
@@ -676,6 +817,35 @@ describe('custom root preservation', () => {
   });
 });
 
+describe('typed descriptor conformance', () => {
+  it('emits a strongly typed .doc.mjs for every canonical item writer', async () => {
+    setup();
+    await integrationAdd('component', 'MyWidget', {cwd: tmpDir});
+    await integrationAdd('doc', 'my-guide', {cwd: tmpDir});
+    await integrationAdd('template', 'my-page', {cwd: tmpDir});
+    await integrationAdd('theme', 'ocean', {cwd: tmpDir});
+
+    // Codemod and agent-doc keep their released formats for compatibility;
+    // no new kind may copy those exceptions.
+    for (const [relativePath, type] of [
+      ['components/MyWidget.doc.mjs', 'ComponentDoc'],
+      ['docs/my-guide.doc.mjs', 'ReferenceDoc'],
+      ['templates/my-page.doc.mjs', 'TemplateDoc'],
+      ['themes/ocean/oceanTheme.doc.mjs', 'ThemeDoc'],
+    ]) {
+      const source = fs.readFileSync(path.join(tmpDir, relativePath), 'utf-8');
+      expect(source).toContain(`@astryxdesign/cli/authoring').${type}`);
+      expect(source).toContain('export default {');
+    }
+    expect(
+      fs.existsSync(path.join(tmpDir, 'templates/my-page.template.mjs')),
+    ).toBe(false);
+    expect(fs.existsSync(path.join(tmpDir, 'themes/manifest.json'))).toBe(
+      false,
+    );
+  });
+});
+
 describe('public per-kind APIs', () => {
   it('exposes narrow functions for every non-theme contribution kind', async () => {
     setup();
@@ -711,6 +881,7 @@ describe('public dispatcher', () => {
     const result = await integrationAdd('theme', 'ocean', {cwd: tmpDir});
     expect(result.data).toMatchObject({kind: 'theme', name: 'ocean'});
     expect(result.data.files).toContain('themes/ocean/oceanTheme.ts');
+    expect(result.data.files).toContain('themes/ocean/oceanTheme.doc.mjs');
   });
 
   it('refuses a kind-specific option on the wrong kind', async () => {