@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/api/doctor/doctor.type.d.mts

@@ -23,7 +23,7 @@ export type DoctorCheck = {
      */
     message: string;
     /**
-     * - Actionable remediation, present when status is not 'pass'.
+     * - Actionable remediation: always present on 'warn' and 'fail'; some 'info' checks carry one too.
      */
     fix?: string | undefined;
 };

package/api/doctor/doctor.type.mjs

@@ -19,7 +19,7 @@
  * @property {string} label - Human-readable check name.
  * @property {DoctorStatus} status
  * @property {string} message - One-line result summary.
- * @property {string} [fix] - Actionable remediation, present when status is not 'pass'.
+ * @property {string} [fix] - Actionable remediation: always present on 'warn' and 'fail'; some 'info' checks carry one too.
  */
 
 /**

package/api/gap-report/gap-report.doc.mjs

@@ -10,13 +10,18 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'gapReport',
+  namespace: 'cli/api',
   displayName: 'gapReport()',
-  summary: 'Route a design-system gap through the fan-out handler composition.',
+  summary:
+    'Report a missing or hard-to-use design-system capability to the package that owns it.',
   description:
-    'Creates a normalized gap report and fans it out to every effective handler: the project config handler first, then each loaded integration handler in config order, deduplicated by handle function identity. Each handler receives a structuredClone of the report and an AbortSignal, then runs in its own worker with a 30 s timeout and stdout redirected to stderr. A timed-out worker is terminated before the next handler starts, so process.exit, process.exitCode, and late continuations cannot affect the CLI process. A public handler requires confirmPublic per handler; internal handlers always run. When no handlers exist, a built-in GitHub/routed-only fallback runs. The aggregate response carries ordered deliveries with per-handler outcomes.',
+    'Sends a gap report to every configured handler: the project config handler first, then each integration handler in config order. ' +
+    'Each handler has 30 s to finish, and its output goes to stderr. Public handlers run only with confirmPublic; internal handlers always run. ' +
+    "With no handler, it files a GitHub issue for the owning package only with confirmPublic (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +
+    'The report records whether an agent or a person ran it, and the response lists each handler outcome in order.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'gapReport(component?: string, options?: GapReportOptions): Promise<GapReportCategoriesResponse | GapReportReceiptResponse>',
+    'gapReport(component: string | undefined, options?: GapReportOptions): Promise<GapReportCategoriesResponse | GapReportReceiptResponse>',
   keywords: [
     'gap',
     'report',
@@ -32,17 +37,19 @@ export const doc = {
       name: 'component',
       type: 'string',
       description:
-        'Component or general design-system area. Required unless listCategories is true.',
+        'Component or general design-system area, up to 120 characters. Required unless listCategories is true.',
     },
     {
       name: 'options.category',
       type: 'GapReportCategory',
-      description: 'Fixed category from the reported category vocabulary.',
+      description:
+        'Fixed category from the reported category vocabulary. Required unless listCategories is true.',
     },
     {
       name: 'options.reason',
       type: 'string',
-      description: 'What capability was missing or difficult.',
+      description:
+        'What capability was missing or difficult, up to 2000 characters. Required unless listCategories is true.',
     },
     {
       name: 'options.detail',
@@ -53,19 +60,20 @@ export const doc = {
       name: 'options.package',
       type: 'string',
       description:
-        'Explicit owning package when automatic routing is ambiguous.',
+        'Package that owns the gap: @astryxdesign/core, or a loaded integration by package name or config entry. Overrides automatic owner routing; required when more than one package provides the component.',
     },
     {
       name: 'options.confirmPublic',
       type: 'boolean',
       description:
-        'Explicitly consent to invoking public handlers or creating a GitHub issue.',
+        'Allow public delivery: public handlers run, and with no handler a GitHub issue is filed through the gh CLI.',
       default: 'false',
     },
     {
       name: 'options.listCategories',
       type: 'boolean',
-      description: 'Return categories without resolving a route or writing.',
+      description:
+        'Return categories without resolving a route or writing; the component and every other option are ignored.',
       default: 'false',
     },
     {
@@ -73,6 +81,7 @@ export const doc = {
       type: 'string',
       description:
         'Directory used to load project config and component ownership.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -83,17 +92,21 @@ export const doc = {
     {
       type: 'gap-report.file',
       description:
-        'An aggregate receipt with per-handler deliveries, filedCount/routedOnlyCount totals, and overall status.',
+        'Receipt: status (filed, partial, failed, routed_only, consent_required, skipped), package, issuesUrl, ordered deliveries (handlerType, handler, audience, status, url, message), filedCount, and routedOnlyCount.',
     },
   ],
   throws: [
+    {
+      code: 'ERR_MISSING_ARGUMENT',
+      when: 'component, category, or reason is missing, blank, or not a string (unless listCategories is true)',
+    },
     {
       code: 'ERR_UNKNOWN_CATEGORY',
       when: 'category is not one of the fixed gap-report values',
     },
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'a field value is invalid',
+      when: 'component is over 120 characters, category is over 80, reason is over 2000, or detail is not a string or is over 8000 characters',
     },
     {
       code: 'ERR_AMBIGUOUS_COMPONENT',
@@ -105,7 +118,7 @@ export const doc = {
     },
     {
       code: 'ERR_NOT_FOUND',
-      when: 'no handler and no issues URL available',
+      when: 'no report handler is configured and the owning package has no issues URL',
     },
   ],
   examples: [
@@ -118,8 +131,8 @@ export const doc = {
       code: "const receipt = await gapReport('Button', {category: 'missing_variant', reason: 'Need a compact size'});",
     },
     {
-      label: 'Confirm public filing',
-      code: "await gapReport('Button', {category: 'docs_gap', reason: 'Missing keyboard example', confirmPublic: true});",
+      label: 'Name the owning package',
+      code: "const receipt = await gapReport('Button', {category: 'docs_gap', reason: 'Missing keyboard example', package: '@astryxdesign/core'});",
     },
   ],
   command: 'gap-report',

package/api/hook/_adapter.mjs

@@ -15,7 +15,10 @@
  */
 
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
-import {findHookDoc, getAllHookNames} from '../../foundation/discovery/hook-discovery.mjs';
+import {
+  findHookDoc,
+  getAllHookNames,
+} from '../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../error.mjs';
@@ -30,7 +33,11 @@ import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 export function resolveCoreDir(cwd) {
   const coreDir = findCoreDir(cwd);
   if (!coreDir) {
-    throw new AstryxError('Could not find @astryxdesign/core package', undefined, ERROR_CODES.ERR_CORE_NOT_FOUND);
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
   }
   return coreDir;
 }
@@ -44,7 +51,11 @@ export function resolveCoreDir(cwd) {
  * @param {{zh?: boolean, lang?: string|null}} [opts]
  * @returns {Promise<import('./hook.type.mjs').HookDoc>}
  */
-export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} = {}) {
+export async function resolveHookDoc(
+  coreDir,
+  name,
+  {zh = false, lang = null} = {},
+) {
   const docPath = findHookDoc(coreDir, name);
 
   if (!docPath) {
@@ -59,7 +70,10 @@ export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} =
       .filter(m => m.distance <= 5)
       .sort((a, b) => a.distance - b.distance)
       .slice(0, 5)
-      .map(m => ({name: m.name, reason: `similar name (distance ${m.distance})`}));
+      .map(m => ({
+        name: m.name,
+        reason: `similar name (distance ${m.distance})`,
+      }));
 
     throw new AstryxError(
       `No hook named "${name}"`,
@@ -68,5 +82,5 @@ export async function resolveHookDoc(coreDir, name, {zh = false, lang = null} =
     );
   }
 
-  return loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}));
+  return loadDocs(docPath, {zh, lang, root: 'hooks'});
 }

package/api/hook/hook.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'hook',
+  namespace: 'cli/api',
   displayName: 'hook()',
   summary:
     'Resolve a hook by name, or list the catalog, with an optional params-only slice.',
@@ -33,6 +34,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory to resolve @astryxdesign/core from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.list',
@@ -42,7 +44,8 @@ export const doc = {
     {
       name: 'options.category',
       type: 'string',
-      description: 'List only hooks in this category.',
+      description:
+        "List only the hooks in this category, a key of the unfiltered list such as 'Media' or 'Focus'.",
     },
     {
       name: 'options.params',
@@ -53,7 +56,8 @@ export const doc = {
       name: 'options.detail',
       type: "'full' | 'compact' | 'brief'",
       description: 'Detail level for list views.',
-      default: "'full' for a named hook, 'brief' for list views",
+      default:
+        "'full' for a named hook; 'brief' for lists (returned as data.detail: 'names')",
     },
     {
       name: 'options.lang',
@@ -103,7 +107,7 @@ export const doc = {
     },
     {
       label: 'Browse a category',
-      code: "await hook(undefined, {category: 'State', detail: 'compact'});",
+      code: "await hook(undefined, {category: 'Media', detail: 'compact'});",
     },
   ],
   command: 'hook',

package/api/hook/hook.type.d.mts

@@ -4,7 +4,7 @@
 export type HookDoc = import("@astryxdesign/cli/authoring").HookDoc;
 export type HookParamDoc = import("@astryxdesign/cli/authoring").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
@@ -39,14 +39,14 @@ export type HookBriefEntry = {
     import: string;
 };
 /**
- * xds --json hook <name>
+ * astryx --json hook <name>
  */
 export type HookDetailResponse = {
     type: "hook.detail";
     data: HookDoc;
 };
 /**
- * xds --json hook <name> --params
+ * astryx --json hook <name> --params
  */
 export type HookDetailParamsResponse = {
     type: "hook.detail.params";

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/index.d.mts

@@ -18,6 +18,7 @@ export { integrationAddTheme } from "./integration/add-theme.mjs";
 export { integrationPackCheck } from "./integration/pack-check.mjs";
 export { AstryxError } from "./error.mjs";
 export { logger } from "./logger.mjs";
+export * from "../foundation/response/batch.type.mjs";
 export * from "./component/component.type.mjs";
 export * from "./docs/docs.type.mjs";
 export * from "./blog/blog.type.mjs";
@@ -38,7 +39,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

@@ -3,7 +3,7 @@
 /**
  * @file Programmatic API for the Astryx CLI.
  *
- * Every function returns the same { type, data } envelope that `xds --json` outputs.
+ * Every function returns the same { type, data } envelope that `astryx --json` outputs.
  * Errors throw AstryxError (with optional .suggestions).
  *
  * @example
@@ -28,6 +28,7 @@ export {template} from './template/template.mjs';
 export {
   themeBuild,
   themeAdd,
+  themeTemplate,
   themeList,
   themeListAvailable,
   themeTargets,
@@ -72,10 +73,12 @@ export {logger} from './logger.mjs';
  * @typedef {import('./logger.mjs').Logger} Logger
  */
 
-// ── Types (re-exported from each command's colocated `.type.mjs`) ─────
+// ── Types (re-exported from the shared response foundation and each command's
+// colocated `.type.mjs`) ──────────────────────────────────────────────────
 // Runtime no-ops (the .type.mjs files are `export {}`); tsc carries these
 // through to the generated api/index.d.mts so the public type surface exposes
-// every command's Options + response types by name.
+// the shared receipt vocabulary and every command's Options + response types.
+export * from '../foundation/response/batch.type.mjs';
 export * from './component/component.type.mjs';
 export * from './docs/docs.type.mjs';
 export * from './blog/blog.type.mjs';

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.',
@@ -18,10 +19,9 @@ export const doc = {
     'Sets a project up with NO prompts, so it behaves identically for humans, ' +
     'agents, CI, and piped I/O. By default it installs the AGENTS.md/CLAUDE.md ' +
     'agent-docs cheat sheet, including guidance from configured integrations, and ' +
-    'prints getting-started guidance; `features` / ' +
-    '`all` add theme and page-building guidance and can scaffold a starter ' +
-    'template. With `removeAgents` it removes the managed agent-docs block ' +
-    'instead of installing.',
+    "prints getting-started guidance; `features` / `all` print only the chosen features' " +
+    'guidance instead (the theme feature also writes the annotated theme template). ' +
+    'With `removeAgents` it removes the managed agent-docs block instead of installing.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'init(options?: InitOptions, ctx?: {cwd?: string}): Promise<InitRunResponse | InitRemoveResponse>',
@@ -31,7 +31,7 @@ export const doc = {
       name: 'options.features',
       type: 'string',
       description:
-        'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (page-template guidance).',
+        'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (the page-building commands; writes a page only with templateName).',
     },
     {
       name: 'options.all',
@@ -46,7 +46,8 @@ export const doc = {
     {
       name: 'options.agent',
       type: 'string',
-      description: 'Agent preset: claude, cursor, codex, hermes, muse, all.',
+      description:
+        'Agent preset: claude, cursor, codex, hermes, muse, all. Used only when the agents feature runs.',
     },
     {
       name: 'options.agentDocsPath',
@@ -57,9 +58,14 @@ export const doc = {
       name: 'options.templateName',
       type: 'string',
       description:
-        'Scaffold a named page template (programmatic only; the CLI never sets it).',
+        'Scaffold this page template to src/pages/<name>/page.tsx. Used only when the template feature runs (features includes template, or all); otherwise ignored. Programmatic only; the CLI never sets it.',
+    },
+    {
+      name: 'ctx.cwd',
+      type: 'string',
+      description: 'Directory to set up.',
+      default: 'process.cwd()',
     },
-    {name: 'ctx.cwd', type: 'string', description: 'Directory to set up.'},
   ],
   returns: [
     {
@@ -70,13 +76,13 @@ export const doc = {
     {
       type: 'init.remove',
       description:
-        'Confirmation that the managed agent-docs block was removed (`data.removed: true`), returned when `removeAgents` is set.',
+        'Returned when `removeAgents` is set. `data.removed` is always true, even when no managed block was found.',
     },
   ],
   throws: [
     {
       code: 'ERR_UNKNOWN_AGENT',
-      when: '`agent` is not one of claude, cursor, codex, hermes, muse, all',
+      when: 'the agents feature runs (default mode, features includes agents, or all) and `agent` is not one of claude, cursor, codex, hermes, muse, all',
     },
     {
       code: 'ERR_UNKNOWN_FEATURE',
@@ -84,12 +90,16 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_TEMPLATE',
-      when: '`templateName` matches no bundled template',
+      when: 'the template feature runs and `templateName` matches no bundled template',
     },
     {
       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), or, with removeAgents, a managed agent-docs file resolves outside cwd through a symlink',
+    },
   ],
   examples: [
     {label: 'Default setup', code: 'const r = await init();'},
@@ -97,5 +107,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'],
 };