@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src/codemods → codemods}/transforms/v0.1.7/rename-table-renderprops-styles-to-xstyle.mjs

@@ -58,7 +58,7 @@ const RENDER_PROP_TYPES = new Set([
 ]);
 
 /** Resolve the base type name from a TS type annotation node. */
-function typeNameOf(typeAnnotation) {
+function typeNameOf(/** @type {any} */ typeAnnotation) {
   // `x: TableRenderProps`
   const t = typeAnnotation?.typeAnnotation ?? typeAnnotation;
   if (!t) return null;
@@ -68,6 +68,11 @@ function typeNameOf(typeAnnotation) {
   return null;
 }
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -77,7 +82,7 @@ export default function transformer(file, api) {
   // Function/arrow params: (props: TableRenderProps) => ...
   const renderPropBindings = new Set();
 
-  function collectParam(param) {
+  function collectParam(/** @type {any} */ param) {
     if (
       param.type === 'Identifier' &&
       RENDER_PROP_TYPES.has(typeNameOf(param.typeAnnotation))
@@ -88,19 +93,19 @@ export default function transformer(file, api) {
 
   root
     .find(j.Function)
-    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+    .forEach((/** @type {any} */ p) => (p.node.params ?? []).forEach(collectParam));
   root
     .find(j.FunctionDeclaration)
-    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+    .forEach((/** @type {any} */ p) => (p.node.params ?? []).forEach(collectParam));
   root
     .find(j.FunctionExpression)
-    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+    .forEach((/** @type {any} */ p) => (p.node.params ?? []).forEach(collectParam));
   root
     .find(j.ArrowFunctionExpression)
-    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+    .forEach((/** @type {any} */ p) => (p.node.params ?? []).forEach(collectParam));
 
   // Variable declarations: `const rp: BodyCellRenderProps = ...`
-  root.find(j.VariableDeclarator).forEach((p) => {
+  root.find(j.VariableDeclarator).forEach((/** @type {any} */ p) => {
     const id = p.node.id;
     if (
       id?.type === 'Identifier' &&
@@ -119,10 +124,10 @@ export default function transformer(file, api) {
   //  2. A spread of a tracked render-prop binding (`{...props, styles: [...]}`)
   //     — the common "carry the render-prop object forward, override styles"
   //     shape. (Only counts when `renderPropBindings` is non-empty.)
-  function isRenderPropShapedObject(objExpr) {
+  function isRenderPropShapedObject(/** @type {any} */ objExpr) {
     if (objExpr.type !== 'ObjectExpression') return false;
     const keyNames = objExpr.properties
-      .map((pr) =>
+      .map((/** @type {any} */ pr) =>
         pr.type === 'ObjectProperty' || pr.type === 'Property'
           ? pr.key?.name ?? pr.key?.value
           : null,
@@ -133,7 +138,7 @@ export default function transformer(file, api) {
     }
     // Spread of a tracked render-prop binding.
     const spreadsRenderProp = objExpr.properties.some(
-      (pr) =>
+      (/** @type {any} */ pr) =>
         (pr.type === 'SpreadElement' || pr.type === 'ExperimentalSpreadProperty') &&
         pr.argument?.type === 'Identifier' &&
         renderPropBindings.has(pr.argument.name),
@@ -146,7 +151,7 @@ export default function transformer(file, api) {
     // render-prop-shaped object literals (htmlProps + styles siblings);
     // never touch bare `styles` in this file (too ambiguous).
     let touched = false;
-    root.find(j.ObjectExpression).forEach((p) => {
+    root.find(j.ObjectExpression).forEach((/** @type {any} */ p) => {
       if (!isRenderPropShapedObject(p.node)) return;
       for (const prop of p.node.properties) {
         if (
@@ -165,7 +170,7 @@ export default function transformer(file, api) {
   }
 
   // --- 2. Rewrite `<binding>.styles` member access -> `.xstyle`. ---
-  root.find(j.MemberExpression).forEach((p) => {
+  root.find(j.MemberExpression).forEach((/** @type {any} */ p) => {
     const {object, property, computed} = p.node;
     if (computed) return;
     if (property?.type !== 'Identifier' || property.name !== 'styles') return;
@@ -177,7 +182,7 @@ export default function transformer(file, api) {
   });
 
   // --- 3. Rewrite `styles:` keys on render-prop-shaped object literals. ---
-  root.find(j.ObjectExpression).forEach((p) => {
+  root.find(j.ObjectExpression).forEach((/** @type {any} */ p) => {
     if (!isRenderPropShapedObject(p.node)) return;
     for (const prop of p.node.properties) {
       if (

package/codemods/transforms/v0.1.8/__tests__/rename-avatar-size-scale.test.mjs

@@ -0,0 +1,161 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} = await import('../rename-avatar-size-scale.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('rename-avatar-size-scale', () => {
+  it('renames every named size on an Avatar JSX size attribute', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const a = <Avatar name="A" size="tiny" />;
+const b = <Avatar name="B" size="xsmall" />;
+const c = <Avatar name="C" size="small" />;
+const d = <Avatar name="D" size="medium" />;
+const e = <Avatar name="E" size="large" />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size='xsm'`);
+    expect(output).toContain(`size='sm'`);
+    expect(output).toContain(`size='md'`);
+    expect(output).toContain(`size='lg'`);
+    expect(output).toContain(`size='xl'`);
+    for (const old of ['tiny', 'xsmall', 'small', 'medium', 'large']) {
+      expect(output).not.toContain(`size="${old}"`);
+    }
+  });
+
+  it('renames size on AvatarGroup', async () => {
+    const input = `import {AvatarGroup} from '@astryxdesign/core';
+const x = <AvatarGroup size="medium">{kids}</AvatarGroup>;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size='lg'`);
+  });
+
+  it('leaves numeric sizes untouched', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const x = <Avatar name="A" size={48} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain('size={48}');
+  });
+
+  it('is alias-aware', async () => {
+    const input = `import {Avatar as Face} from '@astryxdesign/core';
+const x = <Face name="A" size="small" />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size='md'`);
+  });
+
+  it('renames the subpath and legacy import sources', async () => {
+    const sub = `import {Avatar} from '@astryxdesign/core/Avatar';
+const x = <Avatar name="A" size="large" />;`;
+    expect(await applyTransform(sub)).toContain(`size='xl'`);
+    const legacy = `import {Avatar} from '@xds/core';
+const x = <Avatar name="A" size="tiny" />;`;
+    expect(await applyTransform(legacy)).toContain(`size='xsm'`);
+  });
+
+  it('renames a size inside a ternary on an Avatar element', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const x = <Avatar name="A" size={big ? 'large' : 'small'} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`big ? 'xl' : 'md'`);
+  });
+
+  it('renames the UNIQUE names tiny/xsmall in Storybook options and size args', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const meta = {
+  argTypes: {size: {control: 'select', options: ['tiny', 'xsmall']}},
+  args: {size: 'tiny'},
+};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`['xsm', 'sm']`);
+    expect(output).toContain(`size: 'xsm'`);
+  });
+
+  it('renames a FULL Storybook options array (unique name unlocks ambiguous members)', async () => {
+    // The presence of a unique name (tiny/xsmall) proves the whole array is the
+    // Avatar size enum, so small/medium/large in it are safe to rename too.
+    const input = `import {Avatar} from '@astryxdesign/core';
+const meta = {
+  argTypes: {size: {control: 'select', options: ['tiny', 'xsmall', 'small', 'medium', 'large']}},
+};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`['xsm', 'sm', 'md', 'lg', 'xl']`);
+  });
+
+  it('renames a standalone Avatar-size array literal used with .map()', async () => {
+    const input = `import {AvatarGroup} from '@astryxdesign/core';
+const sizes = (['tiny', 'xsmall', 'small', 'medium', 'large'] as const).map(s => s);`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`['xsm', 'sm', 'md', 'lg', 'xl']`);
+  });
+
+  it('does NOT rename an array of ambiguous words with no unique Avatar name', async () => {
+    // Without tiny/xsmall, the array could be anything (priorities, densities),
+    // so ambiguous members are left untouched.
+    const input = `import {Avatar} from '@astryxdesign/core';
+const densities = ['small', 'medium', 'large'] as const;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`['small', 'medium', 'large']`);
+  });
+
+  it('renames a UNIQUE name in a size-typed union literal', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+type Props = {size: 'tiny' | 'xsmall'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`'xsm' | 'sm'`);
+  });
+
+  // --- Precision guards: ambiguous common words must NOT be corrupted in
+  // --- context-blind positions, even in files that import Avatar. ---
+
+  it('does NOT rename ambiguous names in an unrelated union type', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+type TaskPriority = 'urgent' | 'high' | 'medium' | 'low' | 'none';`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`'medium'`);
+    expect(output).not.toContain(`'lg'`);
+  });
+
+  it('does NOT rename an ambiguous name in a non-size object property', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const cfg = {priority: 'medium', density: 'large'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`priority: 'medium'`);
+    expect(output).toContain(`density: 'large'`);
+  });
+
+  it('does NOT rename an ambiguous name in a size-keyed object property (component unknown)', async () => {
+    // A `size: 'small'` object entry could belong to any component; renaming it
+    // blind would be unsafe, so it is left for manual migration.
+    const input = `import {Avatar} from '@astryxdesign/core';
+const args = {size: 'small'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size: 'small'`);
+  });
+
+  it('does not touch files that never import Avatar/AvatarGroup', async () => {
+    const input = `import {Badge} from '@astryxdesign/core';
+const x = <Badge size="small" />;
+type P = 'tiny' | 'xsmall';`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`size="small"`);
+    expect(output).toContain(`'tiny' | 'xsmall'`);
+  });
+
+  it('does not rename an unrelated non-size string in an Avatar file', async () => {
+    const input = `import {Avatar} from '@astryxdesign/core';
+const label = 'small';
+const x = <Avatar name="A" size="small" />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`const label = 'small'`);
+    expect(output).toContain(`size='md'`);
+  });
+});

package/codemods/transforms/v0.1.8/index.mjs

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.8 transform manifest
+ *
+ * Lists all codemods for the v0.1.8 release in the order they should run.
+ */
+
+import renameAvatarSizeScale, {
+  meta as renameAvatarSizeScaleMeta,
+} from './rename-avatar-size-scale.mjs';
+
+export default [
+  {
+    name: 'rename-avatar-size-scale',
+    transform: renameAvatarSizeScale,
+    meta: renameAvatarSizeScaleMeta,
+  },
+];

package/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs

@@ -0,0 +1,239 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Avatar named sizes to Icon's abbreviated scale
+ * @see https://github.com/facebook/astryx/issues/2672
+ *
+ * As of v0.1.8, Avatar and AvatarGroup use the same abbreviated size scale as
+ * Icon (`xsm`/`sm`/`md`/`lg`/`xl`) instead of full words. Pixel values are
+ * unchanged — only the names move:
+ *
+ *   tiny (20px)   → xsm
+ *   xsmall (24px) → sm
+ *   small (36px)  → md   ← also the new default (was `small`)
+ *   medium (48px) → lg
+ *   large (128px) → xl
+ *
+ * The default size shifts from `small` to `md`, but that is the SAME 36px, so
+ * call sites that relied on the default need no change.
+ *
+ * ## Precision
+ *
+ * `small`, `medium`, and `large` are common English words that appear as
+ * unrelated string/type literals (priorities, statuses, breakpoints, …). To
+ * avoid corrupting those, the three AMBIGUOUS names are renamed ONLY in a
+ * precise context: a `size` JSX attribute on a component that resolves to an
+ * Avatar/AvatarGroup import (alias-aware).
+ *
+ * `tiny` and `xsmall` are unique to Avatar's scale, so they are additionally
+ * renamed in context-blind positions (object properties keyed `size`/`*Size`,
+ * Storybook `options` arrays, and size-typed union literals) within files that
+ * import Avatar/AvatarGroup.
+ */
+
+export const meta = {
+  title: 'Rename Avatar named sizes tiny/xsmall/small/medium/large → xsm/sm/md/lg/xl',
+  description:
+    'Avatar and AvatarGroup adopt Icon\'s abbreviated size scale ' +
+    '(xsm/sm/md/lg/xl). Pixel values are unchanged; the default moves from ' +
+    '`small` to `md` (both 36px). The ambiguous names small/medium/large are ' +
+    'only renamed on Avatar/AvatarGroup `size` JSX attributes; the unique ' +
+    'names tiny/xsmall are also renamed in size-keyed props, Storybook ' +
+    'options, and union types in files importing Avatar/AvatarGroup.',
+  pr: '#2672',
+};
+
+/** Import sources that provide the Astryx Avatar/AvatarGroup components. */
+const IMPORT_SOURCES = new Set([
+  '@astryxdesign/core',
+  '@astryxdesign/core/Avatar',
+  '@astryxdesign/core/AvatarGroup',
+  '@xds/core',
+  '@xds/core/Avatar',
+  '@xds/core/AvatarGroup',
+]);
+
+/** Component names whose `size` prop is renamed. */
+const TARGET_IMPORTED_NAMES = new Set(['Avatar', 'AvatarGroup']);
+
+/** Old → new size-name mapping. */
+const RENAMES = new Map([
+  ['tiny', 'xsm'],
+  ['xsmall', 'sm'],
+  ['small', 'md'],
+  ['medium', 'lg'],
+  ['large', 'xl'],
+]);
+
+/**
+ * Ambiguous names — common words that must ONLY be renamed in a precise
+ * context. `tiny`/`xsmall` are omitted because they are unique to Avatar's
+ * scale; their presence in a collection proves it is an Avatar size enum.
+ */
+const AMBIGUOUS = new Set(['small', 'medium', 'large']);
+
+/** Names that appear only in Avatar's scale — safe signals of Avatar sizing. */
+const UNIQUE = new Set(['tiny', 'xsmall']);
+
+/**
+ * Rename a string-literal node if its value is an old size name.
+ * Unwraps `'small' as const`. In non-precise contexts, ambiguous names are
+ * skipped. Returns true when a rename occurred.
+ */
+function renameValue(/** @type {any} */ node, {precise = false} = {}) {
+  if (!node) return false;
+  const target = node.type === 'TSAsExpression' ? node.expression : node;
+  const isString =
+    target.type === 'StringLiteral' || target.type === 'Literal';
+  if (!isString || typeof target.value !== 'string') return false;
+  const replacement = RENAMES.get(target.value);
+  if (!replacement) return false;
+  if (!precise && AMBIGUOUS.has(target.value)) return false;
+  target.value = replacement;
+  if (target.raw) target.raw = undefined;
+  return true;
+}
+
+/** Extract a plain string value from a literal-ish node, or null. */
+function literalString(/** @type {any} */ node) {
+  const target = node?.type === 'TSAsExpression' ? node.expression : node;
+  if (
+    target &&
+    (target.type === 'StringLiteral' || target.type === 'Literal') &&
+    typeof target.value === 'string'
+  ) {
+    return target.value;
+  }
+  return null;
+}
+
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // Track alias-aware local names for the target components.
+  const targetLocals = new Set();
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!IMPORT_SOURCES.has(path.node.source.value)) return;
+    for (const spec of path.node.specifiers ?? []) {
+      if (
+        spec.type === 'ImportSpecifier' &&
+        TARGET_IMPORTED_NAMES.has(spec.imported.name)
+      ) {
+        targetLocals.add(spec.local.name);
+      }
+    }
+  });
+
+  if (targetLocals.size === 0) return undefined;
+
+  function renameArrayElements(/** @type {any} */ node) {
+    let arr = node;
+    if (arr.type === 'TSAsExpression') arr = arr.expression;
+    if (arr.type !== 'ArrayExpression') return;
+    // If the array contains a name unique to Avatar's scale (tiny/xsmall), the
+    // whole collection is unambiguously the Avatar size enum, so it is safe to
+    // rename the ambiguous members too. Otherwise stay conservative.
+    const precise = arr.elements.some((/** @type {any} */ el) => UNIQUE.has(literalString(el)));
+    for (const el of arr.elements) {
+      if (renameValue(el, {precise})) hasChanges = true;
+    }
+  }
+
+  // 1. `size` JSX attributes on target components — PRECISE (component known),
+  //    so all five names, including the ambiguous ones, are renamed here.
+  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !targetLocals.has(componentName)) return;
+
+    for (const attr of path.node.attributes) {
+      if (attr.type !== 'JSXAttribute' || attr.name?.name !== 'size') continue;
+      const value = attr.value;
+
+      // size="small"
+      if (renameValue(value, {precise: true})) {
+        hasChanges = true;
+        continue;
+      }
+      if (
+        value &&
+        value.type === 'JSXExpressionContainer' &&
+        value.expression
+      ) {
+        // size={'small'}
+        if (renameValue(value.expression, {precise: true})) {
+          hasChanges = true;
+          continue;
+        }
+        // size={cond ? 'small' : 'large'}
+        if (value.expression.type === 'ConditionalExpression') {
+          if (renameValue(value.expression.consequent, {precise: true}))
+            hasChanges = true;
+          if (renameValue(value.expression.alternate, {precise: true}))
+            hasChanges = true;
+        }
+      }
+    }
+  });
+
+  // 2. Object properties keyed `size` (or `*Size`) + Storybook `options`
+  //    arrays — NON-PRECISE (the component isn't known here), so only the
+  //    unique names tiny/xsmall are renamed.
+  const PropertyType = j.ObjectProperty ?? j.Property;
+  root.find(PropertyType).forEach((/** @type {any} */ path) => {
+    const key = path.node.key;
+    const keyName =
+      key.type === 'Identifier'
+        ? key.name
+        : key.type === 'StringLiteral' || key.type === 'Literal'
+          ? key.value
+          : null;
+    if (typeof keyName !== 'string') return;
+
+    const lower = keyName.toLowerCase();
+    if (lower !== 'size' && !lower.endsWith('size')) return;
+
+    const value = path.node.value;
+    // size: 'tiny'
+    if (renameValue(value)) {
+      hasChanges = true;
+      return;
+    }
+    // size: { control: 'select', options: ['tiny', ...] }
+    if (value.type === 'ObjectExpression') {
+      const optionsProp = value.properties.find(
+        (/** @type {any} */ p) => p.key && (p.key.name === 'options' || p.key.value === 'options'),
+      );
+      if (optionsProp) renameArrayElements(optionsProp.value);
+    }
+    // size: ['tiny', 'xsmall', ...]
+    renameArrayElements(value);
+  });
+
+  // 3. Union-type literals — NON-PRECISE, so only the unique names tiny/xsmall
+  //    are renamed. This avoids corrupting unrelated unions that happen to use
+  //    common words like 'medium' (e.g. a priority or breakpoint type) in a
+  //    file that also imports Avatar.
+  root.find(j.TSLiteralType).forEach((/** @type {any} */ path) => {
+    if (renameValue(path.node.literal)) hasChanges = true;
+  });
+
+  // 4. Standalone array literals whose members are exactly the Avatar size
+  //    scale (identified by the presence of a unique name like tiny/xsmall) —
+  //    e.g. `(['tiny', 'xsmall', 'small', 'medium', 'large'] as const).map(...)`
+  //    used to render every size. The unique name proves the whole array is the
+  //    Avatar enum, so its ambiguous members can be renamed safely.
+  root.find(j.ArrayExpression).forEach((/** @type {any} */ path) => {
+    renameArrayElements(path.node);
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/docs/cli-integrations.doc.mjs

@@ -0,0 +1,150 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../core/src/docs-types').ReferenceDoc} */
+
+export const docs = {
+  name: 'cli-integrations',
+  title: 'CLI Integrations',
+  category: 'guide',
+  description:
+    'Author an npm package that contributes components, templates, and upgrade codemods to Astryx.',
+
+  sections: [
+    {
+      title: 'Overview',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'An integration is an npm package that contributes components, templates, and/or upgrade codemods to a consumer\u2019s design-system workflow. Consumers install the package and add it to their `astryx.config`; from then on the integration\u2019s contributions show up alongside core\u2019s in the same CLI commands.',
+        },
+        {
+          type: 'prose',
+          text: 'The system runs on two files. The consumer writes `astryx.config.{ts,mjs,js}` at their project root to list which packages to load. The author writes `astryx.integration.{ts,mjs,js}` at the package root to declare what the package contributes. This page is the author\u2019s guide. For the consumer side, run `npx astryx docs getting-started`.',
+        },
+        {
+          type: 'prose',
+          text: 'On the consumer side, adding your package is one line:',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "import {createConfig} from '@astryxdesign/core/config';\n\nexport default createConfig({\n  integrations: ['@acme/astryx-widgets'],\n});",
+        },
+        {
+          type: 'prose',
+          text: 'Your components and templates then appear next to core\u2019s:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx component --list --package @acme/astryx-widgets\nastryx component AcmeCarousel --props',
+        },
+      ],
+    },
+    {
+      title: 'The Integration File',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'To register your package as an integration, add an `astryx.integration.{ts,mjs,js}` file as a sibling of your `package.json`. It tells the CLI where to find your components, templates, and codemods. Identity (name, version) comes from your `package.json`, not this file.',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// astryx.integration.ts\nimport {createIntegration} from '@astryxdesign/core/authoring';\n\nexport default createIntegration({\n  components: './components',\n  templates: './templates',\n  codemods: './codemods',\n  issuesUrl: 'https://github.com/acme/widgets/issues',\n});",
+        },
+        {
+          type: 'prose',
+          text: 'Every field is optional. Declare only the contribution roots your package ships. `createIntegration` is a type-preserving helper for editor autocomplete and type-checking. It lives in `@astryxdesign/core/authoring` and is also re-exported from `@astryxdesign/cli/integration` for back-compat.',
+        },
+      ],
+    },
+    {
+      title: 'Components',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`.',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// AcmeCarousel.doc.ts\nimport {createComponentDoc} from '@astryxdesign/core/authoring';\n\nexport default createComponentDoc({\n  name: 'AcmeCarousel',\n  description: 'A carousel that cycles through slides.',\n  // props, usage, examples, ...\n});",
+        },
+      ],
+    },
+    {
+      title: 'Templates',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template with `createPageTemplate` (full pages) or `createBlockTemplate` (smaller chunks) in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`.',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// AcmeLandingPage.template.ts\nimport {createPageTemplate} from '@astryxdesign/core/authoring';\n\nexport default createPageTemplate({\n  // name, description, preview, ...\n});",
+        },
+        {
+          type: 'prose',
+          text: 'The CLI needs the template source at consume time, so make sure it is included in your published package. This is typically done via the `exports` key in `package.json`. It also lets the docsite render template previews in the future.',
+        },
+        {
+          type: 'code',
+          lang: 'jsonc',
+          code: '{\n  "exports": {\n    // ...\n    "./templates/*.tsx": "./templates/*.tsx"\n  }\n}',
+        },
+        {
+          type: 'prose',
+          text: 'To verify it resolves, try importing the template component with its `.tsx` extension. An extensionless specifier will not resolve under `moduleResolution: bundler`, and the extensionful export above is what lets this type-check without consumers enabling `allowImportingTsExtensions`.',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');",
+        },
+      ],
+    },
+    {
+      title: 'Codemods',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Ship codemods so `astryx upgrade` can migrate consumers across breaking changes in your package. Point the integration file\u2019s `codemods` field at your codemods root, and author each one with `createCodemod` (transforms source files) or `createConfigCodemod` (rewrites the consumer\u2019s `astryx.config`).',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          code: "// codemods/v2-rename-prop.ts\nimport {createCodemod} from '@astryxdesign/cli/codemod';\n\nexport default createCodemod({\n  // version, description, transform, ...\n});",
+        },
+        {
+          type: 'prose',
+          text: 'The codemod helpers live in `@astryxdesign/cli/codemod`, not `@astryxdesign/core/authoring` like the doc, integration, and template helpers. Consumers can also run their own post-codemod hooks, such as a reinstall or rebuild, via `hooks.postCodemod` in their `astryx.config`.',
+        },
+      ],
+    },
+    {
+      title: 'How It Works',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Every CLI command loads the consumer\u2019s `astryx.config`, resolves each listed integration\u2019s manifest from `node_modules`, and discovers its contributions. Everything is validated against one strict schema at the load boundary. The `create*` helpers do not validate. They are identity functions whose value is their TypeScript surface, so validation happens when the CLI loads the file, not when you author it.',
+        },
+        {
+          type: 'prose',
+          text: 'Discovery is resilient. A broken or misconfigured integration is skipped with a single non-blocking warning on stderr instead of crashing the CLI, and it never corrupts a `--json` stdout envelope. Everyday commands keep working with the remaining valid contributions.',
+        },
+        {
+          type: 'prose',
+          text: 'To inspect problems, run `astryx validate-integration <package>` for a detailed report on one package, or `astryx doctor` for an overall health check of the setup.',
+        },
+      ],
+    },
+  ],
+};