@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.3-canary.02f5fe4

package/assets/docs/tree/who-answers.doc.mjs

@@ -0,0 +1,119 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs global/who-answers`: which version answers in each folder, the
+ * hand-off, and how to see who answered (spec AST-081 FR2, FR3, FR5, FR9).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'who-answers',
+  placement: {
+    parent: 'namespace:global',
+    slot: 'guides',
+    order: 3,
+  },
+  title: 'Which version runs, and why',
+  category: 'guide',
+  keywords: [
+    'which release',
+    'wrong version',
+    'different version',
+    'answered by',
+    'answeredBy',
+    'hand-off',
+    'handed over',
+    'project version',
+  ],
+  description:
+    "Inside a project, the project's own CLI answers, whichever astryx command you start; in a project with only Core, the astryx command you started answers. Outside a project, your global install answers. How to see which one did.",
+  sections: [
+    {
+      id: 'in-a-project',
+      title: "In a project, the project's version",
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "The project installs the CLI, as recommended: that CLI answers, whatever its version, as it always has. When you type the global astryx command instead, it passes the run to the project's CLI, with the same arguments, input, output, and exit status, so either command gives the same answer.",
+            "The project installs only Core, or nothing is installed yet, as in a fresh clone: the astryx command you started answers, as it always has. When its version differs from the project's Core, a hint after the command, once a day, names the command that adds the CLI at Core's version.",
+            "The project's CLI is installed but cannot start: the CLI version equal to the project's Core answers instead (from the installed Core, else the lockfile, else the newest one the declared range allows), installed once into a cache.",
+          ],
+        },
+        {
+          type: 'prose',
+          text: "Components come from `@astryxdesign/core`, and templates, docs, and agent guides come from the CLI. In a project, that Core is the one the project installs, so component commands work offline once the project's dependencies are installed. Outside a project, or in a project with nothing installed yet (a fresh clone), they use the answering version's own Core, from beside the CLI or the cache; when that Core cannot be downloaded, the error says to install the project's dependencies. When the project's CLI and Core are different versions, `astryx doctor` warns and prints the command that brings them to one version.",
+        },
+      ],
+    },
+    {
+      id: 'outside',
+      title: 'Outside a project, your global install',
+      content: [
+        {
+          type: 'prose',
+          text: 'In a folder that belongs to no project, your global install answers as a brand-new project on its version would, so you and your agents can read every component and doc. It never installs a newer version by itself.',
+        },
+        {
+          type: 'prose',
+          text: 'A few commands work on your computer rather than a folder, such as `astryx init --user`: your global install answers them in any folder.',
+        },
+      ],
+    },
+    {
+      id: 'see-it',
+      title: 'See which version answered',
+      content: [
+        {
+          type: 'prose',
+          text: 'In a project with only Core, the hint looks like this, after the command, at most once a day per project:',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: 'astryx: this project has no Astryx CLI installed; answered by CLI 0.7.2 while its Core is 0.6.8. To match, run: npm install @astryxdesign/cli@0.6.8',
+        },
+        {
+          type: 'prose',
+          text: "Otherwise, in text mode, one line on standard error names the version, unless the project's own CLI answered directly:",
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: "astryx: answered by this project's CLI 0.6.8, handed over from CLI 0.7.2\nastryx: answered by CLI 0.6.8 with Core 0.6.8, the release that matches this project's Core\nastryx: answered by CLI 0.7.2 with Core 0.7.2, outside a project\nastryx: answered by CLI 0.7.2 with Core 0.7.2, for this computer",
+        },
+        {
+          type: 'prose',
+          text: 'With `--json` nothing extra prints; every result carries `meta.answeredBy` instead ({@link generic:reference}):',
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          code: '{"meta": {"answeredBy": {"cli": "0.7.2", "core": "0.6.8", "copy": "starting"}}}',
+        },
+      ],
+    },
+    {
+      id: 'printed-commands',
+      title: 'Commands Astryx prints',
+      content: [
+        {
+          type: 'prose',
+          text: "Commands the CLI prints for you to run start with a name that reaches the same version: the project's runner (such as `pnpm exec astryx`) in a project, `astryx` outside a project when your global install answered, and otherwise the CLI pinned to the version, such as `npx @astryxdesign/cli@0.6.8`. An integration can name its own command: {@link generic:cli-command}.",
+        },
+      ],
+    },
+    {
+      id: 'more',
+      title: 'More on global mode',
+      content: [
+        {
+          type: 'prose',
+          text: 'This page is part of {@link namespace:global}, which explains what global mode is and how each part works. To check your computer, run `astryx doctor` outside any project ({@link command:doctor}). Monorepos: {@link generic:monorepos}.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/write-good-templates.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/building-blocks/templates/write-good-templates`:
+ * @file `astryx docs authoring/building-blocks/templates/write-good-templates`:
  * what makes a template good, the rubric that scores it, and grading with an agent.
  */
 

package/assets/docs/tree/write-the-template-file.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/write-the-template-file`:
+ * @file `astryx docs authoring/building-blocks/templates/build-the-template/write-the-template-file`:
  * what gets copied, where the copied file lands, and the imports and
  * export a copied template needs.
  */
@@ -44,13 +44,13 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           code: `# Page: src/app/account/page.tsx
-npx astryx template acme-account src/app/account
+astryx template acme-account src/app/account
 
 # Block: src/features/account/acme-stat-card.tsx
-npx astryx template acme-stat-card src/features/account
+astryx template acme-stat-card src/features/account
 
 # Exact destination for either kind
-npx astryx template acme-stat-card src/features/account/StatusCard.tsx`,
+astryx template acme-stat-card src/features/account/StatusCard.tsx`,
         },
         {
           type: 'prose',
@@ -91,8 +91,9 @@ npx astryx template acme-stat-card src/features/account/StatusCard.tsx`,
           lang: 'tsx',
           code: `import {Button} from '@astryxdesign/core/Button';
 import {Card} from '@astryxdesign/core/Card';
-import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {HStack} from '@astryxdesign/core/HStack';
 import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/VStack';
 import {AcmeStatusCard} from '@acme/astryx-widgets/components/AcmeStatusCard';
 
 const metrics = [
@@ -144,7 +145,7 @@ export default function AcmeAccountSummary() {
           type: 'list',
           style: 'unordered',
           items: [
-            'Add `use client` as the first statement only when hooks, event handlers, or browser APIs need a client boundary.',
+            'Add `use client` as the first statement only when hooks, event handlers, browser APIs, or a component passed as a prop, such as `icon={BellIcon}`, need a client boundary.',
             'Keep a static template server-compatible when it needs no client behavior.',
           ],
         },

package/assets/docs/use-a-theme.doc.mjs

@@ -25,13 +25,13 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Wire the generated module once',
-          code: "import {Theme} from '@astryxdesign/core';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n  return (\n    <Theme theme={themes[defaultThemeSlug]}>\n      <YourApp />\n    </Theme>\n  );\n}",
+          code: "import {Theme} from '@astryxdesign/core/theme';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n  return (\n    <Theme theme={themes[defaultThemeSlug]}>\n      <YourApp />\n    </Theme>\n  );\n}",
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Switch among added themes',
-          code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
+          code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core/theme';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
         },
         {
           type: 'prose',

package/assets/docs/use-integrations.doc.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+  type: 'generic',
+  name: 'use-integrations',
+  title: 'Use integrations',
+  category: 'guide',
+  description:
+    'Install, discover, and use integration packages that add components, templates, themes, and docs to your app.',
+  keywords: [
+    'install an integration',
+    'add an integration',
+    'install a package',
+    'use an integration',
+    'discover integrations',
+    'integration',
+    'package',
+    'third party',
+    'plugin',
+    'extension',
+  ],
+
+  sections: [
+    {
+      title: 'Discover integrations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Integration packages extend Astryx with extra components, templates, themes, docs, and codemods. They are published as regular npm packages.',
+        },
+        {
+          type: 'prose',
+          text: 'Search for what you need:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx search carousel\nastryx discover',
+        },
+        {
+          type: 'prose',
+          text: '`search` looks across everything the CLI knows (components, docs, templates, themes, and hooks), so a word like "carousel" finds it whether it is a component, a template, or a doc page. `discover` lists every integration the project has, and, with a discover source, packages it could add.',
+        },
+      ],
+    },
+    {
+      title: 'Install an integration',
+      content: [
+        {
+          type: 'prose',
+          text: 'Install the package with your package manager. Integrations autolink: the CLI finds them among your dependencies, so installing is all it takes:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'npm install @acme/brand-integration',
+        },
+        {
+          type: 'prose',
+          text: 'Run `astryx doctor` to confirm everything is wired up. If you need to load a package that is not a direct dependency, add it explicitly to `astryx.config.mjs`:',
+        },
+        {
+          type: 'code',
+          lang: 'js',
+          label: 'Optional: explicit config entry',
+          code: "export default {\n  integrations: ['@acme/brand-integration'],\n};",
+        },
+      ],
+    },
+    {
+      title: 'Use what it adds',
+      content: [
+        {
+          type: 'prose',
+          text: 'Once installed, the integration\'s contributions appear alongside Core:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`astryx component --list` shows its components next to Core components.',
+            '`astryx template --list` includes its page and block templates.',
+            '`astryx theme list` lists its themes; add one with `astryx theme add <slug> --package @acme/brand-integration`.',
+            '`astryx docs` shows any guides it provides.',
+            '`astryx search <query>` finds everything, from every installed integration.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Import components at the subpath the integration documents. Run `astryx component <Name>` to see the exact import:',
+        },
+        {
+          type: 'code',
+          lang: 'jsx',
+          code: "import {AcmeCarousel} from '@acme/brand-integration/components/AcmeCarousel';",
+        },
+        {
+          type: 'prose',
+          text: 'For themes, see {@link generic:use-a-theme}. To build an integration of your own, see {@link namespace:authoring}.',
+        },
+      ],
+    },
+    {
+      title: 'Check for problems',
+      content: [
+        {
+          type: 'prose',
+          text: 'Run `astryx doctor` to see integration issues: missing roots, invalid contributions, or a CLI version mismatch. The doctor check is the one place every issue for every package is listed.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx doctor',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/working-with-ai.doc.mjs

@@ -36,7 +36,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/cli and run `npx @astryxdesign/cli init --features agents` to set up your Astryx context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `astryx init --features agents` to set up your Astryx context. Read the generated file.',
         },
         {
           type: 'prose',
@@ -44,18 +44,26 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'By default this creates `AGENTS.md` (the tool-agnostic standard most agents read). To target a specific tool\'s file instead:',
+          text: "By default this writes the instructions to `AGENTS.md` (the tool-agnostic standard most agents read), in the project root: the nearest folder whose `package.json` declares an Astryx package, else the nearest with any `package.json`. The search stops at the repository root. In the home folder, or in a settings folder in it outside a project, init writes no agent docs: every folder of the home folder whose name starts with a dot (`~/.claude`, `~/.gemini`, `~/.codex`) is a settings folder, and such a folder itself never counts as a project, even with a `package.json`; a project below it with its own `package.json`, such as an agent worktree, is set up normally. Claude Code skips `AGENTS.md` when the project has a `CLAUDE.md` or `.claude/CLAUDE.md`, so init also writes them to that file, even when it imports `AGENTS.md`: Claude Code does not follow that import in a session started in a subfolder. When both files exist, root `CLAUDE.md` gets the copy and a copy in `.claude/CLAUDE.md` is removed, unless the project ignores `CLAUDE.md`, in which case a `.claude/CLAUDE.md` the project commits keeps a copy. Gemini CLI reads only `GEMINI.md`, so init adds a one-line import of `AGENTS.md` there, unless `GEMINI.md` already imports it. `upgrade` keeps the copies in sync. The block between the Astryx markers belongs to Astryx: init and `upgrade` write, refresh, and remove it whatever the project's ignore rules or generated markers say, and never change the text around it. To target a specific tool's file instead:",
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Manual options',
-          code: `npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md if present, else .claude/CLAUDE.md
-npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules if present, else AGENTS.md
-npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
-npx @astryxdesign/cli init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
-npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)
-npx @astryxdesign/cli init --features agents --agent all       # every agent file present, else AGENTS.md and .claude/CLAUDE.md`,
+          code: `astryx init --features agents --agent claude    # CLAUDE.md if present, else .claude/CLAUDE.md
+astryx init --features agents --agent cursor    # .cursorrules if present, else AGENTS.md
+astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
+astryx init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
+astryx init --features agents --agent muse      # AGENTS.md (Muse)
+astryx init --features agents --agent all       # every agent file present except GEMINI.md, else AGENTS.md and .claude/CLAUDE.md`,
+        },
+        {
+          type: 'prose',
+          text: 'With `--agent all`, `GEMINI.md` keeps its one-line import of `AGENTS.md`. With `--agent claude` or `--agent all`, as by default, when `CLAUDE.md` gets the instructions, `.claude/CLAUDE.md` gets none and a copy already there is removed, unless the project ignores `CLAUDE.md`: a fresh clone does not have it, so a `.claude/CLAUDE.md` the project commits gets a copy too, with `--agent claude` and `--agent all` alike. `init --remove-agents` removes them at the project root and in the folder it runs in.',
+        },
+        {
+          type: 'prose',
+          text: "For agents that work outside any one project, your global install keeps one short Astryx skill, `~/.agents/skills/astryx/SKILL.md`, linked into the skill folders agent tools read, such as `~/.claude/skills/astryx`. It tells agents Astryx is there and when to use it; `astryx init --user` writes it now or, with `--remove-agents`, turns it off. Inside a project, agents follow that project's own agent docs. See {@link generic:computer-agent-guide}.",
         },
       ],
     },
@@ -92,7 +100,7 @@ npx @astryxdesign/cli init --features agents --agent all       # every agent fil
           type: 'code',
           lang: 'bash',
           label: 'Install as a Cursor project rule',
-          code: `npx @astryxdesign/cli init --features agents --agent-docs-path .cursor/rules/astryx.mdc`,
+          code: `astryx init --features agents --agent-docs-path .cursor/rules/astryx.mdc`,
         },
         {
           type: 'prose',
@@ -117,7 +125,7 @@ npx @astryxdesign/cli init --features agents --agent all       # every agent fil
 2. How do you make a Dialog non-dismissible?
 3. What prop does Selector use for its items?
 
-If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
+If you don't know all three, run \`astryx init --features agents\` to generate agent docs, then read the generated file.`,
         },
       ],
     },
@@ -182,26 +190,75 @@ astryx docs principles --dense`,
         },
         {
           type: 'prose',
-          text: 'Add the server to your MCP config file. This works with any MCP-compatible tool: Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Cline, and others.',
+          text: 'Add the server to your MCP config file. The entry is a remote HTTP server, and the exact shape differs per client, so use the snippet for the tool you run. An entry with an unrecognized transport is skipped with a warning rather than an error, which reads as a server that connects but exposes no tools.',
         },
         {
           type: 'code',
           lang: 'json',
-          label: 'MCP config (same for all tools)',
+          label: 'Claude Code (.mcp.json)',
           code: `{
   "mcpServers": {
     "astryx": {
-      "type": "url",
+      "type": "http",
       "url": "https://astryx.atmeta.com/mcp"
     }
   }
 }`,
         },
+        {
+          type: 'prose',
+          text: 'Claude Code can also write that entry from the terminal:',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: `claude mcp add --transport http astryx https://astryx.atmeta.com/mcp`,
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label: 'Cline (cline_mcp_settings.json) - type is streamableHttp',
+          code: `{
+  "mcpServers": {
+    "astryx": {
+      "type": "streamableHttp",
+      "url": "https://astryx.atmeta.com/mcp"
+    }
+  }
+}`,
+        },
+        {
+          type: 'code',
+          lang: 'json',
+          label:
+            'Cursor (.cursor/mcp.json) - remote servers take no type field',
+          code: `{
+  "mcpServers": {
+    "astryx": {
+      "url": "https://astryx.atmeta.com/mcp"
+    }
+  }
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'Claude Desktop is the exception: claude_desktop_config.json holds local stdio servers, so a remote server is added through Settings, then Connectors, then Add custom connector, pasting the URL above.',
+        },
         {
           type: 'prose',
           text: 'Once connected, your AI tool can search for components by natural language (e.g. "dropdown menu", "success message") and retrieve full documentation without any manual CLI invocation. The server uses the same keyword index from component docs, so search quality improves automatically as component documentation is updated.',
         },
       ],
     },
+    {
+      id: 'global-mode',
+      title: 'In global mode',
+      content: [
+        {
+          type: 'prose',
+          text: "In global mode: your global install keeps one Astryx skill in your home folder, linked into the folders agent tools read, so agents outside any project know Astryx is there; inside a project, its own agent docs come first. See {@link namespace:global} and {@link generic:computer-agent-guide}.",
+        },
+      ],
+    },
   ],
 };

package/assets/templates/themes/butter/butterTheme.ts

@@ -81,7 +81,8 @@ const SECONDARY_SELECTOR = {
 
 /**
  * The secondary Button treatment on ComplexSelector triggers (AST-079 FR2), with
- * the hover kept off a disabled trigger, whose inner button is disabled.
+ * the hover kept off a disabled trigger, whose inner button is disabled
+ * (natively or, keeping its tab stop, with `aria-disabled`).
  */
 const SECONDARY_COMPLEX_SELECTOR = {
   backgroundColor: SECONDARY_BUTTON.backgroundColor,
@@ -89,7 +90,8 @@ const SECONDARY_COMPLEX_SELECTOR = {
   borderStyle: SECONDARY_BUTTON.borderStyle,
   borderColor: SECONDARY_BUTTON.borderColor,
   color: SECONDARY_BUTTON.color,
-  ':hover:not(:has(> :disabled))': SECONDARY_BUTTON[':hover'],
+  ':hover:not(:has(> :is(:disabled, [aria-disabled="true"])))':
+    SECONDARY_BUTTON[':hover'],
 } as const;
 
 export const butterTheme = defineTheme({

package/assets/templates/themes/stone/stoneTheme.ts

@@ -100,14 +100,16 @@ const SECONDARY_SELECTOR = {
 
 /**
  * The secondary Button treatment on ComplexSelector triggers (AST-079 FR2), with
- * the hover kept off a disabled trigger, whose inner button is disabled.
+ * the hover kept off a disabled trigger, whose inner button is disabled
+ * (natively or, keeping its tab stop, with `aria-disabled`).
  */
 const SECONDARY_COMPLEX_SELECTOR = {
   backgroundColor: SECONDARY_BUTTON.backgroundColor,
   borderWidth: SECONDARY_BUTTON.borderWidth,
   borderStyle: SECONDARY_BUTTON.borderStyle,
   borderColor: SECONDARY_BUTTON.borderColor,
-  ':hover:not(:has(> :disabled))': SECONDARY_BUTTON[':hover'],
+  ':hover:not(:has(> :is(:disabled, [aria-disabled="true"])))':
+    SECONDARY_BUTTON[':hover'],
 } as const;
 
 export const stoneTheme = defineTheme({

package/assets/templates/themes/y2k/y2kTheme.ts

@@ -76,7 +76,8 @@ const SECONDARY_SELECTOR = {
 
 /**
  * The secondary Button treatment on ComplexSelector triggers (AST-079 FR2), with
- * the hover kept off a disabled trigger, whose inner button is disabled.
+ * the hover kept off a disabled trigger, whose inner button is disabled
+ * (natively or, keeping its tab stop, with `aria-disabled`).
  */
 const SECONDARY_COMPLEX_SELECTOR = {
   backgroundColor: SECONDARY_BUTTON.backgroundColor,
@@ -84,7 +85,8 @@ const SECONDARY_COMPLEX_SELECTOR = {
   borderStyle: SECONDARY_BUTTON.borderStyle,
   borderColor: SECONDARY_BUTTON.borderColor,
   color: SECONDARY_BUTTON.color,
-  ':hover:not(:has(> :disabled))': SECONDARY_BUTTON[':hover'],
+  ':hover:not(:has(> :is(:disabled, [aria-disabled="true"])))':
+    SECONDARY_BUTTON[':hover'],
 } as const;
 
 export const y2kTheme = defineTheme({

package/assets/theme.template.ts

@@ -18,7 +18,7 @@
  *
  * 1. WRAP THE APP. A theme does nothing until it is provided.
  *
- *      import {Theme} from '@astryxdesign/core';
+ *      import {Theme} from '@astryxdesign/core/theme';
  *      import {myTheme} from './theme';
  *
  *      <Theme theme={myTheme} mode="system">   // 'system' | 'light' | 'dark'

package/authoring/codemod/codemod.doc.mjs

@@ -17,7 +17,8 @@ export const doc = {
     'A codemod module the CLI runs during `astryx upgrade`. Default-export a ' +
     "plain object with a `type` discriminant: 'code' rewrites source files, " +
     "'config' rewrites the astryx.config.* file. There is no factory to call.",
-  appliesTo: 'the codemods/ dir of an integration',
+  appliesTo:
+    '`<codemods>/<version>/<id>.{ts,mjs,js}` in an integration package: `<codemods>` is the codemods root of astryx.integration.*, and `<version>` is the exact @astryxdesign/core version (such as 0.7.0) whose upgrade runs the codemod. A file directly in the root never runs.',
   fields: [
     {
       name: 'title',
@@ -44,6 +45,7 @@ export const doc = {
       description:
         'File extensions this codemod applies to. Code codemods only; a ' +
         'config codemod always targets astryx.config.*.',
+      default: "['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs']",
       example: "['.tsx', '.ts']",
     },
     {
@@ -58,6 +60,7 @@ export const doc = {
           name: 'file',
           type: 'AstryxCodemodFile',
           description: 'The source file presented to the transform.',
+          required: true,
           fields: [
             {
               name: 'file.path',
@@ -77,6 +80,7 @@ export const doc = {
           name: 'api',
           type: 'AstryxCodemodApi',
           description: 'Helpers and context passed as the second argument.',
+          required: true,
           fields: [
             {
               name: 'api.jscodeshift',
@@ -89,14 +93,14 @@ export const doc = {
               name: 'api.stats',
               type: '(...args: unknown[]) => void',
               description:
-                'Report a statistic (no-op-friendly; provided for jscodeshift parity).',
+                'Accepted for jscodeshift parity. A call does nothing, and upgrade shows nothing for it.',
               required: true,
             },
             {
               name: 'api.report',
               type: '(...args: unknown[]) => void',
               description:
-                'Report progress (no-op-friendly; provided for jscodeshift parity).',
+                'Accepted for jscodeshift parity. A call does nothing, and upgrade shows nothing for it.',
               required: true,
             },
           ],

package/authoring/config/config.doc.mjs

@@ -15,8 +15,8 @@ export const doc = {
   description:
     'The optional astryx.config.* file at your project root. Declares which ' +
     'integrations to load, where to route issue links, post-codemod hooks, local ' +
-    'debug-log and gap-report handlers, and experimental layout components. All ' +
-    'optional; {} is valid.',
+    'debug-log and gap-report handlers, a discover source, and experimental ' +
+    'layout components. All optional; {} is valid.',
   appliesTo: 'astryx.config.{ts,mjs,js}',
   fields: [
     {
@@ -29,7 +29,9 @@ export const doc = {
     {
       name: 'issuesUrl',
       type: 'string',
-      description: 'URL that "report an issue" affordances link to.',
+      description:
+        "Where reports about Core go: `astryx gap-report` routes a Core report here when no handler is loaded, gapReport handlers receive it as `report.target.issuesUrl`, and `astryx swizzle` prints it as the feedback link for a Core component. A report or swizzle for an integration's component uses that integration's own issuesUrl, never this one. An absolute URL; a value that is not a URL makes the config invalid.",
+      default: "'https://github.com/facebook/astryx/issues/new'",
     },
     {
       name: 'hooks',
@@ -40,7 +42,7 @@ export const doc = {
           name: 'hooks.postCodemod',
           type: 'PostCodemodHook[]',
           description:
-            'Commands run after an upgrade applies codemods (e.g. re-run your formatter). Each hook returns a command to execute, or null to skip.',
+            'Commands to run after `astryx upgrade` changes files (e.g. re-run your formatter). Each hook is an object `{name?, buildCommand}`: buildCommand gets `{packageDir, files}` and returns `{command, args?, options?}` to run, or null to skip. A dry run prints each command instead of running it.',
         },
       ],
     },
@@ -77,7 +79,7 @@ export const doc = {
           name: 'experimental.xle.components',
           type: 'Record<string, XleComponent>',
           description:
-            'Custom components the layout expander (XLE) may emit, keyed by tag.',
+            'Custom components for the removed layout expander, keyed by component name. The CLI still validates the field, so an entry without a string `from` makes `astryx.config` invalid, but nothing reads it.',
         },
       ],
     },
@@ -90,6 +92,7 @@ export const doc = {
     {
       label: 'Send every command run somewhere of your own',
       code:
+        "import {appendFileSync} from 'node:fs';\n\n" +
         'export default {\n' +
         '  debug: event => appendFileSync("runs.ndjson", JSON.stringify(event) + "\\n"),\n' +
         '};',
@@ -98,7 +101,7 @@ export const doc = {
   notes: [
     {
       type: 'prose',
-      text: 'The config is validated at load with a strict schema: unknown keys are errors, so a typo fails fast rather than being silently ignored.',
+      text: 'The config is validated at load with a strict schema: an unknown key, a misspelled one included, or a value of the wrong type makes the whole file invalid. `astryx gap-report`, `astryx discover`, and `astryx upgrade` stop with the error, and `astryx doctor` fails its `config` check (exit 1). Reads such as `component`, `docs`, `search`, `template`, and `theme` carry on silently as if there were no config and no integrations, and no debug handler runs, so run `astryx doctor` after editing the file.',
     },
   ],
 };

package/authoring/config/type.ts

@@ -115,8 +115,10 @@ export interface AstryxConfig {
     /** Experimental XLE (layout expression) configuration. */
     xle?: {
       /**
-       * Register app-local components so XLE layout expressions can
-       * reference them by name via {hint}. Keyed by component name.
+       * Custom components for the removed layout expander, keyed by
+       * component name. The CLI still validates the field, so an entry
+       * without a string `from` makes `astryx.config` invalid, but nothing
+       * reads it.
        */
       components?: Record<string, XleComponent>;
     };