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

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

@@ -77,6 +77,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 +305,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'");
 
@@ -390,13 +392,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 +435,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 +680,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 +744,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 () => {

package/api/integration/add-theme.mjs

@@ -1,9 +1,9 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx integration add theme` — scaffold one valid source theme into
- * an integration package, update its theme catalog, and declare the root on
- * first use.
+ * @file `astryx integration add theme` — scaffold one strongly typed,
+ * same-stem source/descriptor pair into an integration package and declare the
+ * themes root on first use.
  */
 
 import * as fs from 'node:fs';
@@ -15,16 +15,14 @@ import {
   PathSafetyError,
   sanitizeName,
 } from '../../foundation/fs/path-safety.mjs';
-import {
-  discoverThemeCatalog,
-  THEME_MANIFEST_BASENAME,
-} from '../../foundation/discovery/theme-discovery.mjs';
+import {discoverThemeDirectory} from '../../foundation/discovery/theme-discovery.mjs';
 import {
   findLocalIntegrationManifestOrNull,
   IntegrationRootConflictError,
   patchIntegrationRoot,
 } from '../../foundation/integrations/manifest-writer.mjs';
 import {loadManifestObject} from '../../foundation/integrations/integrations.mjs';
+import {themeDescriptorSource} from '../../foundation/integrations/theme-descriptor.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
 import {
   applyWrites,
@@ -70,6 +68,7 @@ function themeIdentity(slug) {
     displayName,
     exportName: `${identifier}Theme`,
     entry: `${identifier}Theme.ts`,
+    descriptor: `${identifier}Theme.doc.mjs`,
   };
 }
 
@@ -78,9 +77,20 @@ function themeSource(identity) {
   return `import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const ${identity.exportName} = defineTheme({\n  name: '${identity.slug}',\n});\n`;
 }
 
+/** @param {{slug: string, displayName: string}} identity */
+function themeDescriptor(identity) {
+  return themeDescriptorSource({
+    type: 'theme',
+    name: identity.slug,
+    displayName: identity.displayName,
+    description: `${identity.displayName} theme.`,
+    maintained: true,
+  });
+}
+
 /**
- * Read the bytes back through the same integration-theme discovery seam Project
- * uses. A write is not successful until the requested slug resolves.
+ * Read bytes back through the same discovery seam Project uses. A write is not
+ * successful until the requested slug resolves.
  * @param {string} packageDir
  * @param {string} manifestFile
  * @param {string} owner
@@ -176,6 +186,9 @@ export async function integrationAddTheme(name, options = {}) {
       dryRun: true,
       createIfMissing: true,
     });
+    if (fs.existsSync(root)) {
+      discoverThemeDirectory(root, owner);
+    }
   } catch (error) {
     if (error instanceof IntegrationRootConflictError) {
       throw new AstryxError(
@@ -197,72 +210,29 @@ export async function integrationAddTheme(name, options = {}) {
   const sourceFile = assertWithin(identity.entry, themeDir, {
     label: 'theme source file',
   });
-  if (fs.existsSync(sourceFile)) {
-    throw new AstryxError(
-      `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, sourceFile))}.`,
-      undefined,
-      ERROR_CODES.ERR_FILE_EXISTS,
-    );
-  }
-
-  const catalogFile = assertWithin(THEME_MANIFEST_BASENAME, root, {
-    label: 'theme catalog manifest',
+  const descriptorFile = assertWithin(identity.descriptor, themeDir, {
+    label: 'theme descriptor file',
   });
-  /** @type {{version: 1, themes: Array<Record<string, unknown>>, [key: string]: unknown}} */
-  let catalog = {version: 1, themes: []};
-  /** @type {Buffer|null} */
-  let catalogOriginal = null;
-  if (fs.existsSync(catalogFile)) {
-    try {
-      catalogOriginal = fs.readFileSync(catalogFile);
-      catalog = JSON.parse(catalogOriginal.toString('utf-8'));
-      // The discovery seam is the schema/source-of-truth validator. The write
-      // plan carries catalogOriginal, so any concurrent change between this read
-      // and publish is refused rather than overwritten with this snapshot.
-      discoverThemeCatalog(root, owner);
-    } catch (error) {
+  // An existing folder is filled; only a file this would write is refused.
+  for (const file of [sourceFile, descriptorFile]) {
+    if (fs.existsSync(file)) {
       throw new AstryxError(
-        error instanceof Error ? error.message : String(error),
+        `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, file))}.`,
         undefined,
-        ERROR_CODES.ERR_THEME_INVALID,
+        ERROR_CODES.ERR_FILE_EXISTS,
       );
     }
   }
-  if (
-    catalog.themes.some(
-      theme =>
-        typeof theme.slug === 'string' &&
-        theme.slug.toLowerCase() === identity.slug.toLowerCase(),
-    )
-  ) {
-    throw new AstryxError(
-      `Theme "${identity.slug}" already exists in ${projectPath(path.relative(packageDir, catalogFile))}.`,
-      undefined,
-      ERROR_CODES.ERR_FILE_EXISTS,
-    );
-  }
-
-  catalog.themes.push({
-    slug: identity.slug,
-    displayName: identity.displayName,
-    description: `${identity.displayName} theme.`,
-    maintained: true,
-    entry: identity.entry,
-    exportName: identity.exportName,
-    files: [identity.entry],
-  });
 
   /** @type {import('./add-helpers.mjs').WritePlan[]} */
-  const plans = [];
-  plans.push(
+  const plans = [
     {path: sourceFile, contents: themeSource(identity), createOnly: true},
     {
-      path: catalogFile,
-      contents: `${JSON.stringify(catalog, null, 2)}\n`,
-      createOnly: catalogOriginal == null,
-      expectedOriginal: catalogOriginal ?? undefined,
+      path: descriptorFile,
+      contents: themeDescriptor(identity),
+      createOnly: true,
     },
-  );
+  ];
   const packageUpdate = packageJsonUpdate(
     packageFile,
     rootPath,

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

@@ -32,7 +32,7 @@ afterEach(() => {
 });
 
 describe('integrationAddTheme', () => {
-  it('writes a valid source theme, catalog, root, package files entry, and receipt', async () => {
+  it('writes a typed same-stem descriptor and source with no central catalog', async () => {
     setup();
     const result = await integrationAddTheme('ocean', {cwd: tmpDir});
 
@@ -45,7 +45,7 @@ describe('integrationAddTheme', () => {
         manifest: 'astryx.integration.mjs',
         files: [
           'themes/ocean/oceanTheme.ts',
-          'themes/manifest.json',
+          'themes/ocean/oceanTheme.doc.mjs',
           'package.json',
           'astryx.integration.mjs',
         ],
@@ -56,21 +56,17 @@ describe('integrationAddTheme', () => {
     expect(
       fs.readFileSync(path.join(tmpDir, 'themes/ocean/oceanTheme.ts'), 'utf-8'),
     ).toContain('export const oceanTheme = defineTheme');
-    expect(
-      JSON.parse(
-        fs.readFileSync(path.join(tmpDir, 'themes/manifest.json'), 'utf-8'),
-      ),
-    ).toMatchObject({
-      version: 1,
-      themes: [
-        {
-          slug: 'ocean',
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    });
+
+    const descriptor = fs.readFileSync(
+      path.join(tmpDir, 'themes/ocean/oceanTheme.doc.mjs'),
+      'utf-8',
+    );
+    expect(descriptor).toContain("@astryxdesign/cli/authoring').ThemeDoc");
+    expect(descriptor).toContain("type: 'theme'");
+    expect(descriptor).toContain("name: 'ocean'");
+    expect(fs.existsSync(path.join(tmpDir, 'themes/manifest.json'))).toBe(
+      false,
+    );
     expect(
       fs.readFileSync(path.join(tmpDir, 'astryx.integration.mjs'), 'utf-8'),
     ).toContain("themes: './themes'");
@@ -96,6 +92,7 @@ describe('integrationAddTheme', () => {
     expect(result.data.dryRun).toBe(true);
     expect(result.data.root).toEqual({path: './themes', created: true});
     expect(result.data.files).toContain('themes/ocean/oceanTheme.ts');
+    expect(result.data.files).toContain('themes/ocean/oceanTheme.doc.mjs');
     expect(fs.existsSync(path.join(tmpDir, 'themes'))).toBe(false);
     expect(
       fs.readFileSync(path.join(tmpDir, 'astryx.integration.mjs'), 'utf-8'),
@@ -125,22 +122,69 @@ describe('integrationAddTheme', () => {
     expect(
       fs.existsSync(path.join(tmpDir, 'src/themes/ocean/oceanTheme.ts')),
     ).toBe(true);
+    expect(
+      fs.existsSync(path.join(tmpDir, 'src/themes/ocean/oceanTheme.doc.mjs')),
+    ).toBe(true);
   });
 
-  it('refuses an invalid existing catalog without changing its bytes', async () => {
+  it('keeps each theme to its own folder: a second theme touches no shared file', async () => {
+    setup({manifest: "export default {themes: './themes'};\n"});
+    await integrationAddTheme('ocean', {cwd: tmpDir});
+    const shared = ['package.json', 'astryx.integration.mjs'].map(file =>
+      fs.readFileSync(path.join(tmpDir, file), 'utf-8'),
+    );
+
+    const result = await integrationAddTheme('reef', {cwd: tmpDir});
+
+    expect(result.data.files).toEqual([
+      'themes/reef/reefTheme.ts',
+      'themes/reef/reefTheme.doc.mjs',
+    ]);
+    expect(fs.readdirSync(path.join(tmpDir, 'themes')).sort()).toEqual([
+      'ocean',
+      'reef',
+    ]);
+    expect(
+      ['package.json', 'astryx.integration.mjs'].map(file =>
+        fs.readFileSync(path.join(tmpDir, file), 'utf-8'),
+      ),
+    ).toEqual(shared);
+  });
+
+  it('refuses an obsolete central catalog without changing its bytes', async () => {
     setup();
     fs.mkdirSync(path.join(tmpDir, 'themes'));
     const catalog = path.join(tmpDir, 'themes', 'manifest.json');
-    fs.writeFileSync(catalog, '{not-json\n');
+    fs.writeFileSync(catalog, '{"version":1}\n');
 
     await expect(
       integrationAddTheme('ocean', {cwd: tmpDir}),
     ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
-    expect(fs.readFileSync(catalog, 'utf-8')).toBe('{not-json\n');
+    expect(fs.readFileSync(catalog, 'utf-8')).toBe('{"version":1}\n');
     expect(fs.existsSync(path.join(tmpDir, 'themes', 'ocean'))).toBe(false);
   });
 
-  it('refuses duplicate themes and existing source files', async () => {
+  it('refuses an invalid existing descriptor without changing it', async () => {
+    setup();
+    const existing = path.join(tmpDir, 'themes', 'forest');
+    fs.mkdirSync(existing, {recursive: true});
+    const descriptor = path.join(existing, 'forestTheme.doc.mjs');
+    fs.writeFileSync(descriptor, 'export default {type: "theme"};\n');
+    fs.writeFileSync(
+      path.join(existing, 'forestTheme.ts'),
+      'export const forestTheme = {};\n',
+    );
+
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
+    expect(fs.readFileSync(descriptor, 'utf-8')).toBe(
+      'export default {type: "theme"};\n',
+    );
+    expect(fs.existsSync(path.join(tmpDir, 'themes', 'ocean'))).toBe(false);
+  });
+
+  it('refuses a duplicate valid theme directory', async () => {
     setup();
     await integrationAddTheme('ocean', {cwd: tmpDir});
     await expect(
@@ -148,6 +192,46 @@ describe('integrationAddTheme', () => {
     ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
   });
 
+  it('refuses an existing invalid theme directory', async () => {
+    setup();
+    fs.mkdirSync(path.join(tmpDir, 'themes', 'ocean'), {recursive: true});
+    fs.writeFileSync(
+      path.join(tmpDir, 'themes', 'ocean', 'oceanTheme.ts'),
+      'export const oceanTheme = {};\n',
+    );
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: 'ERR_THEME_INVALID'});
+  });
+
+  it.each([
+    ['an empty folder', []],
+    ['a folder holding .gitkeep', ['.gitkeep']],
+    ['a folder holding NOTES.md', ['NOTES.md']],
+  ])('fills %s', async (_, files) => {
+    setup();
+    const dir = path.join(tmpDir, 'themes', 'ocean');
+    fs.mkdirSync(dir, {recursive: true});
+    for (const file of files) fs.writeFileSync(path.join(dir, file), 'x\n');
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.written).toBe(true);
+    expect(fs.readdirSync(dir).sort()).toEqual(
+      [...files, 'oceanTheme.doc.mjs', 'oceanTheme.ts'].sort(),
+    );
+  });
+
+  it('refuses to overwrite a file it would write', async () => {
+    setup();
+    await integrationAddTheme('ocean', {cwd: tmpDir});
+    await expect(
+      integrationAddTheme('ocean', {cwd: tmpDir}),
+    ).rejects.toMatchObject({
+      code: 'ERR_FILE_EXISTS',
+      message:
+        'Refusing to overwrite existing file themes/ocean/oceanTheme.ts.',
+    });
+  });
+
   it.each(['../ocean', 'Ocean', 'ocean theme', '.ocean'])(
     'refuses unsafe or noncanonical name %s',
     async name => {

package/api/integration/authoring-checks.test.mjs

@@ -33,7 +33,7 @@ function writeIntegration({id, name, type = 'block', root = tmpDir}) {
   const stem = path.join(root, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
+    `${stem}.doc.mjs`,
     `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
   );
   fs.writeFileSync(
@@ -176,7 +176,7 @@ describe('integrationTemplateConflicts', () => {
     );
     fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});
     fs.writeFileSync(
-      path.join(tmpDir, 'templates', 'broken.template.mjs'),
+      path.join(tmpDir, 'templates', 'broken.doc.mjs'),
       `throw new Error('broken fixture');\n`,
     );
     fs.writeFileSync(
@@ -221,7 +221,9 @@ describe('integrationComponentConflicts', () => {
     expect(core).toBeDefined();
     writeComponentIntegration(core.name);
 
-    const result = await integrationComponentConflicts(undefined, {cwd: tmpDir});
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
 
     expect(result.type).toBe('integration.component-conflicts');
     expect(result.data.issues).toEqual([]);
@@ -240,7 +242,9 @@ describe('integrationComponentConflicts', () => {
   it('does not flag an integration-only component name', async () => {
     writeComponentIntegration('AcmeOnlyWidget');
 
-    const result = await integrationComponentConflicts(undefined, {cwd: tmpDir});
+    const result = await integrationComponentConflicts(undefined, {
+      cwd: tmpDir,
+    });
 
     expect(result.data.conflicts).toEqual([]);
     expect(result.data.issues).toEqual([]);

package/api/integration/integration-block-exports.test.mjs

@@ -51,7 +51,7 @@ const ESBUILD_BIN = resolveBin('esbuild/bin/esbuild');
 let tmpDir;
 
 /**
- * Build an @acme/widgets fixture: a block template (`.template.ts` doc +
+ * Build an @acme/widgets fixture: a block template (released `.template.ts` compatibility descriptor +
  * same-stem `.tsx` source) under `templates/`, plus an astryx.integration
  * manifest, plus a caller-supplied `exports` map.
  * @param {Record<string, string> | undefined} exportsMap
@@ -71,7 +71,7 @@ function makeWidgets(exportsMap) {
     path.join(pkgDir, 'astryx.integration.mjs'),
     `export default { templates: './templates' };\n`,
   );
-  // The template-spec doc (canonical `.template.*` family).
+  // The released `.template.*` compatibility form remains resolvable.
   fs.writeFileSync(
     path.join(blockDir, 'GaugeShowcase.template.ts'),
     `export default { name: 'Gauge showcase', description: 'A gauge.' };\n`,
@@ -127,10 +127,14 @@ function writeTsconfig() {
 /** @returns {{ok: boolean, out: string}} */
 function runTsc() {
   try {
-    execFileSync(process.execPath, [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'], {
-      cwd: tmpDir,
-      stdio: 'pipe',
-    });
+    execFileSync(
+      process.execPath,
+      [TSC_BIN, '--noEmit', '-p', 'tsconfig.json'],
+      {
+        cwd: tmpDir,
+        stdio: 'pipe',
+      },
+    );
     return {ok: true, out: ''};
   } catch (e) {
     return {ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`};

package/api/integration/integrationAdd.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAdd',
+  namespace: 'cli/api',
   displayName: 'integrationAdd()',
   summary: 'Add one working contribution to an integration package.',
   description:

package/api/integration/integrationAddAgentDoc.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddAgentDoc',
+  namespace: 'cli/api',
   displayName: 'integrationAddAgentDoc()',
   summary: 'Append one validated agent-guidance line.',
   description:

package/api/integration/integrationAddCodemod.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddCodemod',
+  namespace: 'cli/api',
   displayName: 'integrationAddCodemod()',
   summary: 'Add a safe identity codemod at an exact target version.',
   description:

package/api/integration/integrationAddComponent.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddComponent',
+  namespace: 'cli/api',
   displayName: 'integrationAddComponent()',
   summary: 'Add a complete component contribution.',
   description:

package/api/integration/integrationAddDoc.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddDoc',
+  namespace: 'cli/api',
   displayName: 'integrationAddDoc()',
   summary: 'Add a complete reference-doc contribution.',
   description:

package/api/integration/integrationAddTemplate.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddTemplate',
+  namespace: 'cli/api',
   displayName: 'integrationAddTemplate()',
   summary: 'Add a complete page or block template contribution.',
   description:

package/api/integration/integrationAddTheme.doc.mjs

@@ -5,10 +5,11 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationAddTheme',
+  namespace: 'cli/api',
   displayName: 'integrationAddTheme()',
   summary: 'Add a source theme to an integration package.',
   description:
-    'Creates an integration manifest when the package has none, writes a minimal named-export defineTheme source file, adds its entry to the root theme catalog, declares the optional themes root on first use, and includes the manifest and root in package.json files when the package already uses an allowlist. Every path is confined to the package and existing theme files are never overwritten.',
+    'Creates an integration manifest when the package has none, writes a minimal named-export defineTheme source file plus its strongly typed same-stem ThemeDoc, declares the optional themes root on first use, and includes the manifest and root in package.json files when the package already uses an allowlist. Every path is confined to the package and existing theme directories are never overwritten.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationAddTheme(name: string, options?: IntegrationAddThemeOptions): Promise<IntegrationAddResponse>',
@@ -17,7 +18,7 @@ export const doc = {
     {
       name: 'name',
       type: 'string',
-      description: 'Lowercase kebab-case theme name and catalog slug.',
+      description: 'Lowercase kebab-case theme name and directory slug.',
       required: true,
     },
     {
@@ -51,7 +52,7 @@ export const doc = {
     },
     {
       code: 'ERR_FILE_EXISTS',
-      when: 'the theme slug or source file already exists',
+      when: 'the theme slug directory already exists',
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
@@ -63,7 +64,7 @@ export const doc = {
     },
     {
       code: 'ERR_THEME_INVALID',
-      when: 'the package, integration manifest, or theme catalog is invalid',
+      when: 'the package, integration manifest, or theme descriptor is invalid',
     },
     {
       code: 'ERR_WRITE_FAILED',
@@ -80,6 +81,6 @@ export const doc = {
       code: "await integrationAddTheme('ocean', {dryRun: true});",
     },
   ],
-  command: 'integration add',
+  command: 'integration add theme',
   related: ['themeList', 'themeAdd', 'validateIntegration'],
 };

package/api/integration/integrationComponentConflicts.doc.mjs

@@ -7,6 +7,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationComponentConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationComponentConflicts()',
   summary: 'Find integration component names that also exist in Core.',
   description:

package/api/integration/integrationDocConflicts.doc.mjs

@@ -7,6 +7,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationDocConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationDocConflicts()',
   summary: 'Classify integration doc overlaps with Core topics.',
   description:

package/api/integration/integrationPackCheck.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationPackCheck',
+  namespace: 'cli/api',
   displayName: 'integrationPackCheck()',
   summary: 'Prove an integration package survives npm packing.',
   description:

package/api/integration/integrationTemplateConflicts.doc.mjs

@@ -9,6 +9,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'integrationTemplateConflicts',
+  namespace: 'cli/api',
   displayName: 'integrationTemplateConflicts()',
   summary: 'Find integration template ids that also exist in Core.',
   description: