@astryxdesign/cli 0.3.0-canary.82d4dab → 0.3.0-canary.d1b7d82

package/README.md

@@ -56,19 +56,28 @@ Options:
 
 ## Commands
 
-| Command       | Description                                                                                          |
-| ------------- | ---------------------------------------------------------------------------------------------------- |
-| `init`        | Initialize the design system in your project: installs packages, sets up theming, adds AI agent docs |
-| `component`   | List components or print detailed docs, props, usage examples, and source                            |
-| `search`      | Find components, hooks, docs, and templates in one ranked, cross-domain result set                   |
-| `docs`        | Print reference documentation (tokens, theme, color, typography, spacing, etc.)                      |
-| `template`    | Inject page or block templates into your project                                                     |
-| `hook`        | List hooks and print hook documentation                                                              |
-| `swizzle`     | Copy component source into your project for deep customization                                       |
-| `upgrade`     | Run codemods to migrate between versions                                                             |
-| `theme build` | Compile a defineTheme file to production CSS and JS                                                  |
-| `discover`    | Discover external packages and components                                                            |
-| `doctor`      | Diagnose your Astryx setup and report problems with fixes (CI-friendly via exit code)                |
+<!-- BEGIN GENERATED: commands -->
+
+| Command                | Description                                                                   |
+| ---------------------- | ----------------------------------------------------------------------------- |
+| `blog`                 | Read the Astryx blog from the published feed                                  |
+| `build`                | Build a page: composition kit for an idea, or the workflow playbook (no args) |
+| `component`            | List components or print component docs                                       |
+| `discover`             | Discover external packages and components                                     |
+| `docs`                 | Print reference docs                                                          |
+| `doctor`               | Diagnose your XDS setup and report problems with fixes                        |
+| `hook`                 | List hooks or print hook docs                                                 |
+| `init`                 | Initialize the design system in your project                                  |
+| `layout`               | Generate XDS layouts from compressed expressions (XLE/XLO)                    |
+| `search`               | Search components, hooks, docs, and templates in one ranked list              |
+| `swizzle`              | Copy component source for customization                                       |
+| `template`             | Inject a page or block template                                               |
+| `theme`                | Theme tools — build, export, and manage themes                                |
+| `upgrade`              | Run codemods to migrate between versions                                      |
+| `validate-integration` | Validate an Astryx integration package (manifest + contributions)             |
+
+<!-- END GENERATED: commands -->
+<!-- Generated by scripts/generate-cli-readme.mjs from `astryx manifest`. Run `pnpm -F @astryxdesign/cli readme`. -->
 
 ### Global options
 
@@ -127,45 +136,56 @@ if (isError(result)) {
 
 ### Error codes
 
-| Code                     | Meaning                                                                                |
-| ------------------------ | -------------------------------------------------------------------------------------- |
-| `ERR_UNKNOWN`            | Generic fallback for any error without a more specific code.                           |
-| `ERR_UNKNOWN_COMMAND`    | A top-level command name was not recognized (e.g. `astryx bogus`).                     |
-| `ERR_UNKNOWN_SUBCOMMAND` | A subcommand under a group was not recognized (e.g. `astryx theme bogus`).             |
-| `ERR_INVALID_OPTION`     | An unknown flag was passed, or `--json` was used on a command that doesn't support it. |
-| `ERR_INVALID_ARGUMENT`   | An option/argument value was rejected, or required flags were missing.                 |
-| `ERR_MISSING_ARGUMENT`   | A required positional argument was omitted (e.g. `astryx theme build` with no file).   |
-| `ERR_INVALID_LANG`       | `--lang` was given a value outside its choices (`en`, `zh`, `dense`).                  |
-| `ERR_INVALID_DETAIL`     | `--detail` was given a value outside its choices (`full`, `compact`, `brief`).         |
-| `ERR_NODE_VERSION`       | The running Node.js version is below the supported minimum.                            |
-| `ERR_CORE_NOT_FOUND`     | `@astryxdesign/core` could not be located (not installed / not in a monorepo).         |
-| `ERR_UNKNOWN_COMPONENT`  | No component matched the requested name.                                               |
-| `ERR_UNKNOWN_HOOK`       | No hook matched the requested name.                                                    |
-| `ERR_UNKNOWN_TOPIC`      | No docs topic matched the requested name.                                              |
-| `ERR_UNKNOWN_SECTION`    | A docs topic exists but the requested section within it does not.                      |
-| `ERR_UNKNOWN_CATEGORY`   | A `--category` filter value did not match any known category.                          |
-| `ERR_UNKNOWN_TEMPLATE`   | No template matched the requested name.                                                |
-| `ERR_UNKNOWN_PACKAGE`    | No package matched the requested name (discover).                                      |
-| `ERR_UNKNOWN_AGENT`      | An unrecognized `--agent` value was passed (agent docs / init).                        |
-| `ERR_UNKNOWN_FEATURE`    | An unrecognized `--features` value was passed to `init`.                               |
-| `ERR_UNKNOWN_CODEMOD`    | A `--codemod` value did not match any registered codemod (upgrade).                    |
-| `ERR_NOT_FOUND`          | A discover/lookup query matched nothing in any package.                                |
-| `ERR_NO_DOC`             | A component exists but has no typed `.doc.mjs` file.                                   |
-| `ERR_NO_SHOWCASE`        | No showcase exists for the requested component.                                        |
-| `ERR_NO_SOURCE`          | No source file could be located for the component/template.                            |
-| `ERR_INVALID_DOC`        | A component's docs failed validation (malformed `.doc.mjs`).                           |
-| `ERR_FILE_NOT_FOUND`     | A required input file did not exist.                                                   |
-| `ERR_FILE_EXISTS`        | Refused to overwrite an existing file in non-interactive mode.                         |
-| `ERR_PATH_TRAVERSAL`     | A path escaped its allowed root, or a name contained traversal markers.                |
-| `ERR_WRITE_FAILED`       | Writing output files failed (and was rolled back).                                     |
-| `ERR_THEME_INVALID`      | A theme definition was missing a required property (e.g. `name`).                      |
-| `ERR_THEME_LOAD`         | A theme file could not be loaded / parsed into a `defineTheme` result.                 |
-| `ERR_TEMPLATE_CONFIG`    | `template.get` is not configured in `astryx.config.mjs` (fetch-by-id).                 |
-| `ERR_TEMPLATE_GET`       | A configured `template.get` threw or returned an invalid value.                        |
-| `ERR_VERSION_DETECT`     | The current `@astryxdesign/core` version could not be detected.                        |
-| `ERR_INVALID_VERSION`    | A `--from`/`--to` value was not a valid semver string.                                 |
-| `ERR_DEP_MISSING`        | A required external dependency (e.g. jscodeshift) is missing.                          |
-| `ERR_GH_CLI`             | GitHub CLI (`gh`) is not installed or not authenticated.                               |
+<!-- BEGIN GENERATED: error-codes -->
+
+| Code                      | Meaning                                                                               |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| `ERR_UNKNOWN`             | Fallback for any error without a more specific code.                                  |
+| `ERR_UNKNOWN_COMMAND`     | A top-level command name was not recognized (e.g. `astryx bogus`).                    |
+| `ERR_UNKNOWN_SUBCOMMAND`  | A subcommand under a command group was not recognized (e.g. `astryx theme bogus`).    |
+| `ERR_INVALID_OPTION`      | An unknown flag/option was passed (Commander `unknownOption`).                        |
+| `ERR_INVALID_ARGUMENT`    | An option/argument had a value Commander's parser rejected.                           |
+| `ERR_MISSING_ARGUMENT`    | A required positional argument was omitted (Commander `missingArgument`).             |
+| `ERR_INVALID_LANG`        | `--lang` was given a value outside its choices (en, zh, dense).                       |
+| `ERR_INVALID_DETAIL`      | `--detail` was given a value outside its choices (full, compact, brief).              |
+| `ERR_NODE_VERSION`        | The running Node.js version is below the supported minimum.                           |
+| `ERR_CORE_NOT_FOUND`      | `@astryxdesign/core` could not be located (not installed / not in a monorepo).        |
+| `ERR_UNKNOWN_COMPONENT`   | No component matched the requested name.                                              |
+| `ERR_UNKNOWN_HOOK`        | No hook matched the requested name.                                                   |
+| `ERR_UNKNOWN_TOPIC`       | No docs topic matched the requested name.                                             |
+| `ERR_UNKNOWN_SECTION`     | A docs topic exists but the requested section within it does not.                     |
+| `ERR_UNKNOWN_CATEGORY`    | A `--category` filter value did not match any known category.                         |
+| `ERR_UNKNOWN_TEMPLATE`    | No template matched the requested name.                                               |
+| `ERR_AMBIGUOUS_TEMPLATE`  | A template id matched more than one template (narrow with --type/--package).          |
+| `ERR_AMBIGUOUS_COMPONENT` | A component name is owned by more than one package (narrow with --package).           |
+| `ERR_UNKNOWN_THEME`       | No theme matched the requested slug (theme add).                                      |
+| `ERR_UNKNOWN_PACKAGE`     | No package matched the requested name (discover).                                     |
+| `ERR_UNKNOWN_AGENT`       | An unrecognized `--agent` value was passed to agent-docs/init.                        |
+| `ERR_UNKNOWN_FEATURE`     | An unrecognized `--features` value was passed to init.                                |
+| `ERR_UNKNOWN_CODEMOD`     | A `--codemod` value did not match any registered codemod (upgrade).                   |
+| `ERR_CODEMOD_FAILED`      | One or more codemods failed during an upgrade run.                                    |
+| `ERR_NOT_FOUND`           | A generic discover/lookup query matched nothing in any package.                       |
+| `ERR_NO_DOC`              | A component exists but has no typed `.doc.mjs` file.                                  |
+| `ERR_NO_SHOWCASE`         | No showcase exists for the requested component.                                       |
+| `ERR_NO_SOURCE`           | No source file could be located for the requested component/template.                 |
+| `ERR_INVALID_DOC`         | A component's docs failed validation (malformed `.doc.mjs`).                          |
+| `ERR_FILE_NOT_FOUND`      | A required input file did not exist.                                                  |
+| `ERR_FILE_EXISTS`         | Refused to overwrite an existing file in non-interactive mode.                        |
+| `ERR_PATH_TRAVERSAL`      | A path escaped its allowed root, or a name contained traversal markers.               |
+| `ERR_WRITE_FAILED`        | Writing output files failed (and was rolled back).                                    |
+| `ERR_THEME_INVALID`       | A theme definition was missing a required property (e.g. `name`).                     |
+| `ERR_THEME_LOAD`          | A theme file could not be loaded / parsed into a defineTheme result.                  |
+| `ERR_VERSION_DETECT`      | The current `@astryxdesign/core` version could not be detected.                       |
+| `ERR_INVALID_VERSION`     | A `--from`/`--to` value was not a valid semver string.                                |
+| `ERR_DEP_MISSING`         | A required external dependency (e.g. jscodeshift) is missing.                         |
+| `ERR_GH_CLI`              | GitHub CLI (`gh`) is not installed or not authenticated.                              |
+| `ERR_UNKNOWN_POST`        | No blog post matched the requested slug in the feed.                                  |
+| `ERR_FETCH_FAILED`        | A network fetch (RSS feed or post text) failed.                                       |
+| `ERR_LAYOUT_PARSE`        | A layout expression failed to parse (syntax error, with line/col).                    |
+| `ERR_LAYOUT_INVALID`      | A layout expression parsed but failed validation (unknown component/prop/enum/block). |
+
+<!-- END GENERATED: error-codes -->
+<!-- Generated by scripts/generate-cli-readme.mjs from the error-codes EnumDoc (== ERROR_CODES). Run `pnpm -F @astryxdesign/cli readme`. -->
 
 ## Capability manifest (agent discovery)
 
@@ -359,39 +379,55 @@ detail.data.name; // narrowed
 
 ### Type discriminators
 
-Every response has a `type` string that uniquely identifies it:
-
-| Command                                                            | Type                                 | Response                          |
-| ------------------------------------------------------------------ | ------------------------------------ | --------------------------------- |
-| `astryx --json component [--list] [--detail names\|compact\|full]` | `component.list` (see `data.detail`) | `ComponentListResponse`           |
-| `astryx --json component <name>`                                   | `component.detail`                   | `ComponentDetailResponse`         |
-| `astryx --json component <name> --props`                           | `component.detail.props`             | `ComponentDetailPropsResponse`    |
-| `astryx --json component <name> --source`                          | `component.detail.source`            | `ComponentDetailSourceResponse`   |
-| `astryx --json component <name> --showcase`                        | `component.detail.showcase`          | `ComponentDetailShowcaseResponse` |
-| `astryx --json component <name> --blocks`                          | `component.detail.blocks`            | `ComponentDetailBlocksResponse`   |
-| `astryx --json discover`                                           | `discover.list`                      | `DiscoverListResponse`            |
-| `astryx --json discover @scope/name`                               | `discover.detail`                    | `DiscoverDetailResponse`          |
-| `astryx --json discover @scope/name/Comp`                          | `discover.detail.doc`                | `DiscoverDetailDocResponse`       |
-| `astryx --json discover <search>`                                  | `discover.search`                    | `DiscoverSearchResponse`          |
-| `astryx --json docs`                                               | `docs.list`                          | `DocsListResponse`                |
-| `astryx --json docs <topic>`                                       | `docs.detail`                        | `DocsDetailResponse`              |
-| `astryx --json docs <topic> <section>`                             | `docs.detail.section`                | `DocsDetailSectionResponse`       |
-| `astryx --json template [--list]`                                  | `template.list`                      | `TemplateListResponse`            |
-| `astryx --json template <name>`                                    | `template.show`                      | `TemplateShowResponse`            |
-| `astryx --json template <name> --skeleton`                         | `template.skeleton`                  | `TemplateSkeletonResponse`        |
-| `astryx --json template <name> [path]`                             | `template.copy`                      | `TemplateCopyResponse`            |
-| `astryx --json hook [--list] [--detail names\|compact\|full]`      | `hook.list` (see `data.detail`)      | `HookListResponse`                |
-| `astryx --json hook <name>`                                        | `hook.detail`                        | `HookDetailResponse`              |
-| `astryx --json hook <name> --params`                               | `hook.detail.params`                 | `HookDetailParamsResponse`        |
-| `astryx --json search <query>`                                     | `search`                             | `SearchResponse`                  |
-| `astryx --json swizzle [--list]`                                   | `swizzle.list`                       | `SwizzleListResponse`             |
-| `astryx --json swizzle <component>`                                | `swizzle.copy`                       | `SwizzleCopyResponse`             |
-| `astryx --json theme build <file>`                                 | `theme.build`                        | `ThemeBuildResponse`              |
-| `astryx --json upgrade --list`                                     | `upgrade.list`                       | `UpgradeListResponse`             |
-| `astryx --json upgrade [--apply]`                                  | `upgrade.run`                        | `UpgradeRunResponse`              |
-| `astryx --json doctor`                                             | `doctor`                             | `DoctorResponse`                  |
-| any error                                                          | —                                    | `CLIError`                        |
-| unsupported command                                                | —                                    | `CLIUnsupportedError`             |
+Every response has a `type` discriminant. The full set is below (generated from the manifest). Each command's `type`s are also listed in `astryx manifest --json`, and the matching `*Response` TypeScript types (e.g. `ComponentDetailResponse`) are exported from `@astryxdesign/cli/json`. Errors use `CLIError`, and unsupported commands use `CLIUnsupportedError`.
+
+<!-- BEGIN GENERATED: response-types -->
+
+| Type                        | What `data` carries                                                                                                                                                                                                                  |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `component.list`            | The component catalog grouped by category: `detail` (the level — names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                      |
+| `component.detail`          | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                    |
+| `component.detail.props`    | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                               |
+| `component.detail.source`   | One component's source file, as {component, source}.                                                                                                                                                                                 |
+| `component.detail.showcase` | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                               |
+| `component.detail.blocks`   | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                           |
+| `docs.list`                 | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                              |
+| `docs.detail`               | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                        |
+| `docs.detail.section`       | A single ReferenceSection of a topic — the first whose title contains the section query.                                                                                                                                             |
+| `blog.list`                 | The feed URL plus every post parsed from the RSS feed — each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                            |
+| `blog.detail`               | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                            |
+| `discover.list`             | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                   |
+| `discover.detail`           | A single external package entry, for an @scope/name query.                                                                                                                                                                           |
+| `discover.detail.doc`       | The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                      |
+| `discover.search`           | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                     |
+| `search`                    | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                                                    |
+| `build.help`                | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                         |
+| `build.kit`                 | The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays.             |
+| `swizzle.list`              | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                       |
+| `swizzle.copy`              | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                       |
+| `template.list`             | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                 |
+| `template.show`             | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                  |
+| `template.skeleton`         | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                         |
+| `template.copy`             | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                |
+| `hook.list`                 | The hook catalog grouped by category: `detail` (the level — names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                   |
+| `hook.detail`               | One hook's full authored HookDoc.                                                                                                                                                                                                    |
+| `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                   |
+| `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                    |
+| `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                 |
+| `theme.list`                | Every bundled theme as a ThemeListEntry[] — each with slug, displayName, description, and a maintained flag.                                                                                                                         |
+| `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                           |
+| `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                           |
+| `upgrade.status`            | A short-circuit outcome with no codemods run — up_to_date, no_codemods, or config_fixable — each carrying the agent-docs summary.                                                                                                    |
+| `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                          |
+| `manifest`                  | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.        |
+| `doctor`                    | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                          |
+| `integration.validate`      | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                             |
+| `layout.expand`             | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written). |
+| `layout.check`              | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).             |
+| `layout.grammar`            | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                  |
+
+<!-- END GENERATED: response-types -->
+<!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
 
 ## Doctor
 

package/api/api-docs-parse.test.mjs

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Validates every colocated FunctionDoc under `api/**` — each `*.doc.mjs`
+ * must export a `doc` that passes `parseDoc` (stamped `type: 'function'`). This
+ * is the safety net for the hand-authored API function docs.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {describe, it, expect} from 'vitest';
+import {parseDoc} from '../authoring/index.mjs';
+
+const API_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+/** @param {string} dir @returns {string[]} */
+function findDocs(dir) {
+  /** @type {string[]} */
+  const out = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...findDocs(p));
+    else if (entry.name.endsWith('.doc.mjs')) out.push(p);
+  }
+  return out;
+}
+
+describe('api FunctionDocs', () => {
+  const files = findDocs(API_DIR);
+
+  it('discovers colocated function docs', () => {
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  for (const file of files) {
+    const rel = path.relative(API_DIR, file);
+    it(`parses ${rel}`, async () => {
+      const mod = await import(pathToFileURL(file).href);
+      const doc = mod.doc ?? mod.docs;
+      expect(doc, `${rel} must export \`doc\``).toBeTruthy();
+      expect(doc.type, `${rel} should be a function doc`).toBe('function');
+      const parsed = parseDoc(doc);
+      expect(parsed.name, `${rel} needs a name`).toBeTruthy();
+    });
+  }
+});

package/api/blog/blog.doc.d.mts

@@ -0,0 +1,10 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `blog()` / `astryx blog`. Colocated with the API
+ * function it documents; the shape source of truth stays in `blog.type.mjs`.
+ * @position packages/cli/api/blog — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/blog/blog.doc.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `blog()` / `astryx blog`. Colocated with the API
+ * function it documents; the shape source of truth stays in `blog.type.mjs`.
+ * @position packages/cli/api/blog — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'blog',
+  displayName: 'blog()',
+  summary: 'List blog posts, or read one, from the published RSS feed.',
+  description:
+    'Reads the design system blog the same way any feed reader does — over the ' +
+    "published RSS feed, never the blog's source files. With no slug it lists every " +
+    "post parsed from the feed; with a slug it reads that post's full plaintext body " +
+    'via the .txt alternate the feed advertises. Both envelopes carry feedUrl so a ' +
+    'caller can hit the RSS feed directly.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'blog(slug?: string): Promise<BlogListResponse | BlogDetailResponse>',
+  keywords: ['blog', 'posts', 'rss', 'feed', 'news', 'article'],
+  params: [
+    {
+      name: 'slug',
+      type: 'string',
+      description:
+        'Post slug (matched case-insensitively) to read in full. Omit to list every post.',
+    },
+  ],
+  returns: [
+    {
+      type: 'blog.list',
+      description:
+        'The feed URL plus every post parsed from the feed — each with slug, title, description, date, type, authors, link, and its plaintext URL.',
+    },
+    {
+      type: 'blog.detail',
+      description:
+        "One post's metadata plus the feed URL and the post's full plaintext body.",
+    },
+  ],
+  throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: 'the slug is provided but is not a string',
+    },
+    {
+      code: 'ERR_UNKNOWN_POST',
+      when: 'no post in the feed matches the requested slug',
+    },
+    {
+      code: 'ERR_FETCH_FAILED',
+      when: 'the RSS feed or post text cannot be fetched (network error, timeout, non-2xx, or oversized), or the post has no plaintext alternate in the feed',
+    },
+  ],
+  examples: [
+    {label: 'List posts', code: 'const {data} = await blog();'},
+    {label: 'Read one post', code: "await blog('introducing-astryx');"},
+  ],
+  command: 'blog',
+  related: ['docs', 'search'],
+};

package/api/build/build.doc.d.mts

@@ -0,0 +1,10 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `build()` / `astryx build`. Colocated with the API
+ * function it documents; the shape source of truth stays in `build.type.mjs`.
+ * @position packages/cli/api/build — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;

package/api/build/build.doc.mjs

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file FunctionDoc for `build()` / `astryx build`. Colocated with the API
+ * function it documents; the shape source of truth stays in `build.type.mjs`.
+ * @position packages/cli/api/build — function documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc = {
+  type: 'function',
+  kind: 'api',
+  name: 'build',
+  displayName: 'build()',
+  summary:
+    'Page-building assistant: the how-to-build playbook, or a composition kit for an idea.',
+  description:
+    'The "assemble a page" entry point. Called with no query it returns the ' +
+    'playbook signal that the renderer expands into the how-to-build-a-page ' +
+    'workflow. Called with a query it runs the unified search and groups the ' +
+    'hits into a composition KIT: the closest page templates, drop-in blocks, ' +
+    'and idea-specific components/hooks, plus the always-on frame + foundation.',
+  importPath: '@astryxdesign/cli/api',
+  signature:
+    'build(query?: string, options?: BuildOptions): Promise<BuildHelpResponse | BuildKitResponse>',
+  keywords: ['build', 'compose', 'assemble', 'page', 'kit', 'scaffold'],
+  params: [
+    {
+      name: 'query',
+      type: 'string',
+      description:
+        'What you\'re building (e.g. "analytics dashboard"). Omit for the how-to-build playbook.',
+    },
+    {
+      name: 'options.cwd',
+      type: 'string',
+      description:
+        'Directory to resolve @astryxdesign/core and templates from.',
+    },
+    {
+      name: 'options.type',
+      type: "'component' | 'hook' | 'doc' | 'template'",
+      description: 'Restrict the underlying search to a single domain.',
+    },
+    {
+      name: 'options.limit',
+      type: 'number',
+      description:
+        'Max results pulled from search before grouping into the kit.',
+      default: '60',
+    },
+  ],
+  returns: [
+    {
+      type: 'build.help',
+      description:
+        'Emitted when the query is omitted — a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
+    },
+    {
+      type: 'build.kit',
+      description:
+        'The grouped composition kit: the echoed query, hasResults/directMatch flags, the closest page templates (≤3), drop-in block patterns (≤5), idea-specific components/hooks (≤6), and the always-on frame + foundation component-name arrays.',
+    },
+  ],
+  throws: [
+    {
+      code: 'ERR_INVALID_ARGUMENT',
+      when: 'options.type is not a known domain, or options.limit is not a positive integer',
+    },
+  ],
+  examples: [
+    {label: 'Get the playbook', code: 'const r = await build();'},
+    {label: 'Compose a page', code: "await build('analytics dashboard');"},
+    {
+      label: 'Restrict + limit',
+      code: "await build('pricing', {type: 'template', limit: 10});",
+    },
+  ],
+  command: 'build',
+  related: ['search', 'template', 'component', 'hook', 'init'],
+};

package/api/component/_adapter.mjs

@@ -270,6 +270,9 @@ export async function resolveUnscopedDoc(dirName, {coreDir, cwd, name}) {
   let resolvedName = dirName;
   // Track the resolving owner so the detail payload can carry ownership info.
   // Defaults to core; the legacy-external fallback below may reassign it.
+  // Annotated because CORE_PACKAGE's generated declaration carries the literal
+  // type, which (unlike a fresh literal) does not widen on assignment.
+  /** @type {string} */
   let resolvedOwnerPackage = CORE_PACKAGE;
   let resolvedSourcePath = readmePath ? findComponentSource(coreDir, dirName) : null;
 

package/api/component/component.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file FunctionDoc for `component()` / `astryx component`. Colocated with the
+ * API function it documents; the shape source of truth stays in
+ * `component.type.mjs`.
+ * @position packages/cli/api/component — function documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').FunctionDoc} */
+export const doc: import("@astryxdesign/cli/authoring").FunctionDoc;