@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.f04b501

package/api/hook/hook.type.mjs

@@ -11,14 +11,14 @@
  *
  * Invocation                                 -> type discriminator
  * ------------------------------------------------------------------
- * xds --json hook                           -> hook.list (data.detail='names')
- * xds --json hook --list                    -> hook.list (data.detail='names')
- * xds --json hook --category State          -> hook.list (filtered)
- * xds --json hook --list --detail compact   -> hook.list (data.detail='compact')
- * xds --json hook --list --detail full      -> hook.list (data.detail='full')
- * xds --json hook useMediaQuery             -> hook.detail
- * xds --json hook useMediaQuery --params    -> hook.detail.params
- * (not found)                               -> CLIError
+ * astryx --json hook                         -> hook.list (data.detail='names')
+ * astryx --json hook --list                  -> hook.list (data.detail='names')
+ * astryx --json hook --category State        -> hook.list (filtered)
+ * astryx --json hook --list --detail compact -> hook.list (data.detail='compact')
+ * astryx --json hook --list --detail full    -> hook.list (data.detail='full')
+ * astryx --json hook useMediaQuery           -> hook.detail
+ * astryx --json hook useMediaQuery --params  -> hook.detail.params
+ * (not found)                                -> CLIError
  */
 
 // Re-export the authored-doc types from core so the hook leaves reference these
@@ -28,7 +28,7 @@
 /** @typedef {import('@astryxdesign/cli/authoring').HookParamDoc} HookParamDoc */
 
 /**
- * xds --json hook [--list] [--category X] [--detail names|compact|full]
+ * astryx --json hook [--list] [--category X] [--detail names|compact|full]
  *
  * The list view emits ONE `hook.list` type across all three detail levels; the
  * depth is carried in `data.detail` and `data.components` holds the grouped map
@@ -56,14 +56,14 @@
  */
 
 /**
- * xds --json hook <name>
+ * astryx --json hook <name>
  * @typedef {object} HookDetailResponse
  * @property {'hook.detail'} type
  * @property {HookDoc} data
  */
 
 /**
- * xds --json hook <name> --params
+ * astryx --json hook <name> --params
  * @typedef {object} HookDetailParamsResponse
  * @property {'hook.detail.params'} type
  * @property {HookParamDoc[]} data

package/api/hook/list/list.d.mts

@@ -10,10 +10,10 @@
  * @param {string|null} [options.lang]
  * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
  */
-export function list({ cwd, category, detail, zh, lang }?: {
+export function list({ cwd, category, detail, zh, lang, }?: {
     cwd?: string | undefined;
     category?: string | undefined;
-    detail?: "names" | "compact" | "full" | "brief" | undefined;
+    detail?: "compact" | "full" | "names" | "brief" | undefined;
     zh?: boolean | undefined;
     lang?: string | null | undefined;
 }): Promise<import("../hook.type.mjs").HookListResponse>;

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/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.',
@@ -90,6 +91,10 @@ export const doc = {
       code: 'ERR_FILE_EXISTS',
       when: 'scaffolding a template would overwrite an existing page.tsx',
     },
+    {
+      code: 'ERR_PATH_TRAVERSAL',
+      when: 'the template output path resolves outside cwd, for example through a symlinked src directory',
+    },
   ],
   examples: [
     {label: 'Default setup', code: 'const r = await init();'},

package/api/init/init.test.mjs

@@ -230,13 +230,40 @@ describe('init() — logger', () => {
       errSpy.mockRestore();
     }
     const text = lines.join('\n');
-    expect(text).toContain('✓ AI agent docs installed → AGENTS.md');
+    expect(text).toContain('[ok] AI agent docs installed -> AGENTS.md');
     expect(text).toContain('  Next steps:');
     // The exact next-steps block the CLI prints comes from getNextSteps().
     expect(text).toContain(getNextSteps('npx astryx')[2].slice(0, 20));
   });
 });
 
+describe('init() — ASCII output', () => {
+  it('prints only ASCII on the default, all-features, re-run, template, and remove paths', async () => {
+    /** @type {string[]} */
+    const lines = [];
+    const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation((...a) => lines.push(a.join(' ')));
+    const empty = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-remove-'));
+    logger.setSilent(false);
+    try {
+      await init({}, {cwd: tmpDir});
+      await init({all: true}, {cwd: tmpDir});
+      await init({all: true}, {cwd: tmpDir});
+      await init({features: 'template', templateName: 'blank'}, {cwd: tmpDir});
+      await init({removeAgents: true}, {cwd: tmpDir});
+      await init({removeAgents: true}, {cwd: empty});
+    } finally {
+      logger.setSilent(true);
+      logSpy.mockRestore();
+      errSpy.mockRestore();
+      fs.rmSync(empty, {recursive: true, force: true});
+    }
+    expect(lines.length).toBeGreaterThan(0);
+    expect(lines.some(line => line.startsWith('[ok] Removed'))).toBe(true);
+    expect(lines.filter(line => /[\u0080-\uFFFF]/.test(line))).toEqual([]);
+  });
+});
+
 describe('init() — write-path safety', () => {
   it('template scaffold refuses to clobber an existing page.tsx', async () => {
     const dest = path.join(tmpDir, 'src', 'pages', 'blank');
@@ -260,4 +287,17 @@ describe('init() — write-path safety', () => {
       init({features: 'template', templateName: '../../etc/evil'}, {cwd: tmpDir}),
     ).rejects.toMatchObject({code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
   });
+
+  it('refuses a template write that a symlinked src would carry outside cwd (ERR_PATH_TRAVERSAL)', async () => {
+    const outside = fs.mkdtempSync(path.join(process.cwd(), '.astryx-init-outside-'));
+    try {
+      fs.symlinkSync(outside, path.join(tmpDir, 'src'), 'dir');
+      await expect(
+        init({features: 'template', templateName: 'blank'}, {cwd: tmpDir}),
+      ).rejects.toMatchObject({code: ERROR_CODES.ERR_PATH_TRAVERSAL});
+      expect(fs.readdirSync(outside)).toEqual([]);
+    } finally {
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
 });

package/api/init/remove/remove.mjs

@@ -24,6 +24,6 @@ import {logger} from '../../logger.mjs';
  */
 export async function remove({cwd = process.cwd()} = {}) {
   removeAgentDocs(cwd);
-  logger.log('✓ AI agent docs removed.');
+  logger.log('[ok] AI agent docs removed.');
   return {type: 'init.remove', data: {removed: true}};
 }

package/api/init/run/run.mjs

@@ -17,7 +17,7 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
-import {PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {PathSafetyError, assertWithin} from '../../../foundation/fs/path-safety.mjs';
 import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 import {
   installAgentDocs,
@@ -98,7 +98,7 @@ async function applyAgents(cwd, options, invocation, data) {
       renderedBlock,
     });
     data.docsWritten = written;
-    logger.log(`✓ AI agent docs installed → ${written.join(', ')}`);
+    logger.log(`[ok] AI agent docs installed -> ${written.join(', ')}`);
   } catch (err) {
     // PathSafetyError carries a precise, user-actionable message — surface it
     // (and flag exit 1) instead of the generic "could not install" warning so
@@ -132,8 +132,8 @@ function applyTheme(cwd, invocation, data) {
     data.themeTemplatePath = didWrite ? written : null;
     logger.log(
       didWrite
-        ? `✓ Theme template written → ${written}`
-        : `• ${written} already exists — left as is.`,
+        ? `[ok] Theme template written -> ${written}`
+        : `- ${written} already exists - left as is.`,
     );
   } catch {
     // Soft failure, like agent docs: the guidance below is still useful.
@@ -166,16 +166,16 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
     // Point agents at the build workflow rather than dumping page-template
     // names — `build` surfaces pages AND blocks AND components for an idea,
     // and `build` with no args is the full how-to-build playbook.
-    logger.log('✓ To build UI, use these commands:');
+    logger.log('[ok] To build UI, use these commands:');
     logger.log('');
     logger.log(
-      `    ${invocation} build "<what you're building>"   build a page — kit: closest template + blocks + components`,
+      `    ${invocation} build "<what you're building>"   build a page - kit: closest template + blocks + components`,
     );
     logger.log(
       `    ${invocation} build                            the how-to-build workflow (read this first)`,
     );
     logger.log(
-      `    ${invocation} search <query>                   find anything — components, docs, templates, blocks`,
+      `    ${invocation} search <query>                   find anything - components, docs, templates, blocks`,
     );
     logger.log('');
     data.template = 'workflow';
@@ -190,9 +190,19 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
     );
   }
 
-  const outputDir = path.resolve(cwd, `./src/pages/${templateName}`);
+  let destFile;
+  try {
+    destFile = assertWithin(path.join('src', 'pages', templateName, 'page.tsx'), cwd, {
+      label: 'template output path',
+    });
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+  const outputDir = path.dirname(destFile);
   const srcPath = path.join(CLI_ROOT, 'assets', 'templates', 'pages', templateName, 'page.tsx');
-  const destFile = path.join(outputDir, 'page.tsx');
   // Don't clobber a user's existing page — same guard the peer template/copy and
   // theme/add write-leaves apply (init is a public API surface too).
   if (fs.existsSync(destFile)) {
@@ -206,7 +216,7 @@ function applyTemplate(cwd, {templateName}, invocation, data) {
   fs.mkdirSync(outputDir, {recursive: true});
   fs.copyFileSync(srcPath, destFile);
   const rel = path.relative(cwd, outputDir);
-  logger.log(`✓ Template created at ${rel}/page.tsx`);
+  logger.log(`[ok] Template created at ${rel}/page.tsx`);
   data.template = 'created';
   data.templatePath = rel;
 }

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

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {integrationAdd, integrationAddComponent} from './add-contribution.mjs';
+import {discoverIntegrationComponents} from '../../foundation/discovery/component-discovery.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-add-component-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    `${JSON.stringify({name: '@acme/widgets', version: '1.0.0', files: ['dist']}, null, 2)}\n`,
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    "export default {\n  components: './components',\n};\n",
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} relativeDoc */
+function writeAuthoredComponent(relativeDoc) {
+  const doc = path.join(tmpDir, relativeDoc);
+  fs.mkdirSync(path.dirname(doc), {recursive: true});
+  fs.writeFileSync(
+    doc,
+    "export default {\n  type: 'component',\n  name: 'AcmeWidget',\n  description: 'The authored AcmeWidget.',\n  props: [],\n};\n",
+  );
+  fs.writeFileSync(
+    doc.replace(/\.doc\.(?:ts|mjs|js)$/u, '.tsx'),
+    'export function AcmeWidget() {\n  return <div>Authored</div>;\n}\n',
+  );
+}
+
+/** Every file under the package, with its bytes. */
+function snapshot() {
+  /** @type {Record<string, string>} */
+  const files = {};
+  /** @param {string} dir */
+  const walk = dir => {
+    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else files[path.relative(tmpDir, full)] = fs.readFileSync(full, 'utf-8');
+    }
+  };
+  walk(tmpDir);
+  return files;
+}
+
+describe('integrationAddComponent name collisions', () => {
+  it('refuses a name a nested component doc already defines', async () => {
+    writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
+    const before = snapshot();
+
+    await expect(
+      integrationAddComponent('AcmeWidget', {cwd: tmpDir}),
+    ).rejects.toMatchObject({
+      code: 'ERR_FILE_EXISTS',
+      message: expect.stringContaining(
+        'components/AcmeWidget/AcmeWidget.doc.mjs',
+      ),
+    });
+    expect(snapshot()).toEqual(before);
+    expect(
+      discoverIntegrationComponents({
+        name: '@acme/widgets',
+        components: path.join(tmpDir, 'components'),
+      }).map(component => path.relative(tmpDir, component.docPath)),
+    ).toEqual([path.join('components', 'AcmeWidget', 'AcmeWidget.doc.mjs')]);
+  });
+
+  it('refuses the same collision under --dry-run', async () => {
+    writeAuthoredComponent('components/widgets/AcmeWidget.doc.mjs');
+
+    await expect(
+      integrationAdd('component', 'AcmeWidget', {cwd: tmpDir, dryRun: true}),
+    ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+  });
+
+  it('refuses a same-stem doc with another extension in the root', async () => {
+    fs.mkdirSync(path.join(tmpDir, 'components'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'components', 'AcmeWidget.doc.ts'),
+      "export default {type: 'component', name: 'AcmeWidget', props: []};\n",
+    );
+    const before = snapshot();
+
+    await expect(
+      integrationAddComponent('AcmeWidget', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+    expect(snapshot()).toEqual(before);
+  });
+
+  it('still adds a component whose name is free', async () => {
+    writeAuthoredComponent('components/AcmeWidget/AcmeWidget.doc.mjs');
+
+    const result = await integrationAddComponent('AcmeBadge', {cwd: tmpDir});
+
+    expect(result.data.files).toEqual([
+      'components/AcmeBadge.doc.mjs',
+      'components/AcmeBadge.tsx',
+      'package.json',
+    ]);
+    expect(
+      discoverIntegrationComponents({
+        name: '@acme/widgets',
+        components: path.join(tmpDir, 'components'),
+      })
+        .map(component => component.name)
+        .sort(),
+    ).toEqual(['AcmeBadge', 'AcmeWidget']);
+  });
+});

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,7 @@ import {
 } from '../../foundation/integrations/integrations.mjs';
 import {isValidSemver} from '../../foundation/env/semver.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
+import {findIntegrationComponentDoc} from '../../foundation/discovery/component-discovery.mjs';
 import {parseAgentDocsField} from '../../authoring/integration/schema.mjs';
 import {integrationAddTheme} from './add-theme.mjs';
 import {
@@ -248,10 +248,21 @@ async function addComponent(name, options) {
       ERROR_CODES.ERR_FILE_EXISTS,
     );
   }
+  // Discovery keys components by doc stem anywhere under the root, so a second
+  // doc with this name would shadow one of the two.
+  const existingDoc = findIntegrationComponentDoc({components: root}, name);
+  if (existingDoc != null) {
+    throw new AstryxError(
+      `Refusing to add component "${name}": ${projectPath(path.relative(packageDir, existingDoc))} already defines it.`,
+      undefined,
+      ERROR_CODES.ERR_FILE_EXISTS,
+    );
+  }
 
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
-  const importSpecifier = `${owner}/${sourcePath}`;
-  const docContents = `export default {\n  type: 'component',\n  name: '${name}',\n  import: ${JSON.stringify(importSpecifier)},\n  description: '${name} component.',\n  props: [],\n};\n`;
+  const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
+  const importSpecifier = `${owner}/${extensionlessPath}`;
+  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[]} */
@@ -263,7 +274,7 @@ async function addComponent(name, options) {
     packageFile,
     rootPath,
     path.basename(manifestFile),
-    [{subpath: sourcePath, target: sourcePath}],
+    [{subpath: extensionlessPath, target: sourcePath}],
   );
   if (pkgUpdate != null) {
     plans.push({
@@ -426,7 +437,7 @@ async function addDoc(name, options) {
     : 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`;
+  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}];
@@ -553,8 +564,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',
@@ -576,7 +587,9 @@ async function addTemplate(name, options) {
 
   const pascalName = kebabToPascal(name);
   const sourcePath = projectPath(path.relative(packageDir, sourceFile));
-  const specContents = `export default {\n  type: '${templateType}',\n  name: '${name}',\n  description: '${kebabToTitle(name)} template.',\n};\n`;
+  const extensionlessPath = sourcePath.replace(/\.tsx?$/u, '');
+  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[]} */
@@ -588,7 +601,7 @@ async function addTemplate(name, options) {
     packageFile,
     rootPath,
     path.basename(manifestFile),
-    [{subpath: sourcePath, target: sourcePath}],
+    [{subpath: extensionlessPath, target: sourcePath}],
   );
   if (pkgUpdate != null) {
     plans.push({