@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/assets/docs/tree/writing-docs.doc.mjs

@@ -0,0 +1,286 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/writing-docs`: the guide to writing docs that readers,
+ * people and agents alike, find by search or by moving one level at a time.
+ * It lives in the docs tree under the `cli` namespace, so its only route is
+ * `cli/writing-docs`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'writing-docs',
+  placement: {parent: 'namespace:cli', slot: 'guides', order: 20},
+  title: 'Writing docs',
+  category: 'guide',
+  description:
+    'Write docs that people and agents find by search or by reading one level at a time.',
+
+  sections: [
+    {
+      title: 'How the docs work',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Every doc is one node in one docs graph, with a stable identity and one home in a tree.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "Identity: the doc's provider, its kind, and its name. Moving a doc never changes it.",
+            'Route: the names of the doc and its parents, such as `cli/api/functions/search`; `astryx docs <route>` reads it.',
+            'Moves: every read ends with Up, Previous, Next, and Related, each as a command you can run.',
+            'Search: a hit is the smallest part that answers, one section or one tree page. It gives the command that reads it and the command that opens the level above.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: "You never write moves or lists of children. The CLI derives them from each doc's home and its typed links.",
+        },
+      ],
+    },
+    {
+      title: 'Add a doc',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'To add a doc, write one `.doc.mjs` file named after the doc, and stamp the type that matches what it describes.',
+        },
+        {
+          type: 'table',
+          headers: ['You document', 'Doc type', '`type`'],
+          rows: [
+            ['A topic or a guide', 'ReferenceDoc', "'generic'"],
+            ['A CLI command', 'CommandDoc', "'command'"],
+            ['A CLI API function', 'FunctionDoc', "'function'"],
+            ['An object shape', 'SchemaDoc', "'schema'"],
+            ['A fixed list of values', 'EnumDoc', "'enum'"],
+            ['A component', 'ComponentDoc', "'component'"],
+            ['A level of the tree', 'NamespaceDoc', "'namespace'"],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'A topic or guide holds `sections`. Each section has a `title` and `content` blocks, and covers one idea. The `description` is one sentence that says what the doc covers.',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          label: 'docs/deploying.doc.mjs',
+          code: "export default {\n  type: 'generic',\n  name: 'deploying',\n  title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  sections: [\n    {\n      title: 'Build before you ship',\n      content: [\n        {type: 'prose', text: 'Build the app, then check it with {@link @astryxdesign/cli:command:doctor}.'},\n        {type: 'code', lang: 'bash', code: 'npm run build'},\n        {type: 'list', style: 'unordered', items: ['Check the output folder.']},\n        {type: 'table', headers: ['Env', 'Value'], rows: [['NODE_ENV', 'production']]},\n      ],\n    },\n  ],\n};",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'A name is a command argument, so use only letters, digits, `_`, and `-`. Use lowercase kebab-case, such as `writing-docs`, so the name and its route segment match.',
+            'Keep the name stable. Links name a doc by its identity, and the name is part of it.',
+            'A name that collides with an existing topic is an error unless the doc declares `replaces` or `extends`.',
+            'Name the cases a doc does not cover, and link to where they are covered. A reader cannot tell a case you left out from a case that does not exist.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Every field of every doc type is in {@link generic:authoring}.',
+        },
+      ],
+    },
+    {
+      title: 'Place a doc',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Each doc gets one home in one of three ways: a namespace adopts it, it places itself, or it stays a flat topic. Folders never decide a home.',
+        },
+        {
+          type: 'prose',
+          text: "Adopted: a CLI typed doc declares `namespace`, either `'cli/commands'` or `'cli/api'`. That namespace adopts it by kind, so its route is `cli/commands/<name>` or `cli/api/functions/<name>`.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "{type: 'function', name: 'search', namespace: 'cli/api' /* ... */} // cli/api/functions/search",
+        },
+        {
+          type: 'prose',
+          text: "Placed: a guide declares `placement`. The `parent` names a namespace of your own package, the `slot` is one that namespace declares for the doc's kind, and `order` sorts the siblings in the slot. A placement that fails withdraws the doc with an error.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "placement: {parent: 'namespace:cli', slot: 'guides', order: 20}, // cli/writing-docs",
+        },
+        {
+          type: 'prose',
+          text: 'Flat: a doc with neither is a flat topic, read with `astryx docs <name>`.',
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "{type: 'generic', name: 'tokens', title: 'All Tokens' /* ... */} // astryx docs tokens",
+        },
+      ],
+    },
+    {
+      title: 'Link docs',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Link a doc with `{@link <target>}` or a typed field, never by writing its `astryx docs` route in prose: a route you write goes stale when the doc moves. Other commands, such as `astryx doctor`, you write as they are.',
+        },
+        {
+          type: 'prose',
+          text: "Typed fields: a FunctionDoc's `command` names the CLI command that runs it, and its `related` names functions. A CommandDoc's `fn` names the function it runs, and its `related` names commands.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "{type: 'function', name: 'search', command: 'search', related: ['docs']}\n{type: 'command', name: 'search', fn: 'search', related: ['docs']}",
+        },
+        {
+          type: 'prose',
+          text: "Inside a section's text, write `{@link <target>}`, where the target is `[<provider>:]<kind>:<name>`; leave out the provider for a doc of your own provider. The CLI prints the command that opens the doc. It works in prose, list items, and table cells; link syntax inside code ticks is shown as written, and an older CLI prints the link as plain text. A namespace doc can also carry `reference` and `workflow` blocks in its `blocks`, though the CLI does not print them yet; a topic's sections cannot hold them.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "{type: 'prose', text: 'Check it with {@link command:doctor}.'}\n{type: 'list', style: 'unordered', items: ['Search with {@link @astryxdesign/cli:function:search}.']}\n\n// In a namespace doc's blocks only:\n{type: 'workflow', steps: [\n  {title: 'Write the doc', references: ['generic:authoring']},\n  {title: 'Check it', references: ['command:doctor']},\n]}",
+        },
+        {
+          type: 'prose',
+          text: "The route in the printed command is derived when the doc is read, so a link follows its doc when the doc moves. A target that names no doc prints as written, and so does a typed-field name that matches more than one doc; `astryx doctor` warns on both.",
+        },
+      ],
+    },
+    {
+      title: 'Keep reads short',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Keep every read short so a reader gets one answer per command: one idea per section, a summary first, and a hard size limit.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Give each section one idea. If it needs a second topic, split it into two sections.',
+            "A section's summary, shown in the section list and in search, is its first prose block or first list item, cut at 240 characters. Lead with what the section answers.",
+            'In text, a topic with more than one section reads as its section list. The reader opens one section, or prints everything with `--full`. With `--json`, a topic returns the whole doc and `--index` its section list.',
+            'Every read should fit in 32 KB; `astryx doctor` warns on one that does not. Aim for sections under about 30 lines.',
+          ],
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx docs cli/writing-docs\nastryx docs cli/writing-docs keep-reads-short\nastryx docs cli/writing-docs --full',
+        },
+      ],
+    },
+    {
+      title: 'Make docs findable',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Search finds a doc only by the words it indexes, so put the words a reader types where search looks.',
+        },
+        {
+          type: 'prose',
+          text: "Search matches titles, section titles, headings, each section's summary, and identifiers written in code ticks, such as `ERR_UNKNOWN_SECTION` or `token-ref`. It also matches a doc's own name and the `keywords` of a namespace or typed doc.",
+        },
+        {
+          type: 'list',
+          style: 'do',
+          items: [
+            'Title a section with the task or question, such as "Place a doc".',
+            'Start each section with a sentence that names its subject and answers it.',
+            'Write exact identifiers in code ticks: field names, block types, and error codes.',
+            'Add `keywords` only for words that are not already in the title or summary.',
+          ],
+        },
+        {
+          type: 'list',
+          style: 'dont',
+          items: [
+            'Open a section with background. Its first block is its summary.',
+            'Use vague titles such as "Overview" or "Details" when a specific one fits.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'Test it the way a new reader arrives: search for the question, not the title, and check that the first hit answers it.',
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          code: 'astryx search placement --type doc',
+        },
+      ],
+    },
+    {
+      title: 'Docs from an integration',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'An integration joins the same graph with a namespace doc in its docs directory and guides placed in it. The namespace shows in `astryx docs` beside `cli`, with the same moves, search, and links. You can place a doc only in a namespace of your own package.',
+        },
+        {
+          type: 'prose',
+          text: 'Let the CLI write the files: inside the package, `astryx integration add doc deploying --parent acme` writes the guide with its placement, declares the docs root, and writes the `acme` namespace doc the first time. Run `astryx docs` in the package to see it.',
+        },
+        {
+          type: 'prose',
+          text: "A CLI release that does not read the docs tree can hide every doc topic your package ships when the package contains a namespace doc or a placed guide: none appear in `astryx docs`, in text or JSON, and `astryx doctor` may not say why. So `--parent` also declares the CLI release your docs need as an optional `@astryxdesign/cli` peer in package.json, which makes npm warn when an older CLI is installed, and `astryx integration pack --check` fails a package that ships either one without it.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "// docs/acme.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */\nexport default {\n  type: 'namespace', name: 'acme', title: 'Acme widgets',\n  summary: 'Guides for building apps with Acme widgets.',\n  slots: {guides: {title: 'Guides', accepts: {kinds: ['generic']}}},\n};\n\n// docs/deploying.doc.mjs (route: acme/deploying)\n/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n  type: 'generic', name: 'deploying', title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  placement: {parent: 'namespace:acme', slot: 'guides', order: 10},\n  sections: [{title: 'Check before you ship', content: [\n    {type: 'prose', text: 'Run {@link @astryxdesign/cli:command:doctor} before every deploy.'},\n  ]}],\n};",
+        },
+        {
+          type: 'prose',
+          text: "The link names the `@astryxdesign/cli` provider because its target lives in another package. A link without a provider resolves against yours: your manifest's `providerId`, or else your package name. That holds in a topic that `extends` another package's topic too: your sections link your docs, and a link to the other package's docs names its provider.",
+        },
+        {
+          type: 'prose',
+          text: 'Everything else an integration ships is in {@link generic:integrations}.',
+        },
+      ],
+    },
+    {
+      title: 'Check your docs',
+      category: 'guide',
+      content: [
+        {
+          type: 'prose',
+          text: 'Run the doctor commands to check every home, link, and read in your docs.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`astryx doctor`, in a project, checks the whole graph: the tree, the links, and the size of each read.',
+            '`astryx doctor integration docs`, inside an integration package, runs the same checks on that package\'s docs before it ships.',
+            '`astryx integration pack --check` fails a package that ships a namespace doc or a placed guide without a CLI peer that reads them.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'No check can tell whether a doc is still true. Describe what the CLI does now, and change the doc in the same change that changes the behavior.',
+        },
+        {
+          type: 'prose',
+          text: 'A problem in the tree or a link is a warning: it names what to fix, but the exit code stays 0, so read the report (or its `--json`) before you ship.',
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/typography.doc.mjs

@@ -8,7 +8,6 @@ export const docs = {
   category: 'foundations',
   description:
     'Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.',
-  keywords: ['font', 'fonts', 'font size'],
   tokenCategory: 'typography',
 
   sections: [
@@ -45,10 +44,9 @@ export const docs = {
       ],
     },
 
-    // ── Custom Fonts ────────────────────────────────────────────────────────
+    // ── Loading Custom Fonts ────────────────────────────────────────────────
     {
-      id: 'loading-custom-fonts',
-      title: 'Custom fonts',
+      title: 'Loading Custom Fonts',
   category: 'foundations',
       content: [
         {
@@ -167,16 +165,11 @@ export const docs = {
       ],
     },
 
-    // ── Headings and text ───────────────────────────────────────────────────
+    // ── Usage ────────────────────────────────────────────────────────────────
     {
-      id: 'usage',
-      title: 'Headings and text',
+      title: 'Usage',
   category: 'foundations',
       content: [
-        {
-          type: 'prose',
-          text: 'Use `Heading` for document structure and `Text` for everything else; each maps its props to the type scale tokens.',
-        },
         {
           type: 'code',
           lang: 'tsx',
@@ -212,19 +205,6 @@ export const docs = {
 // Display without heading semantics (data callouts, decorative)
 <Text type="display-2">$1.2M Revenue</Text>`,
         },
-      ],
-    },
-
-    // ── Custom type scale ───────────────────────────────────────────────────
-    {
-      id: 'custom-type-scale',
-      title: 'Custom type scale',
-  category: 'foundations',
-      content: [
-        {
-          type: 'prose',
-          text: 'Change the whole ramp with `base` and `ratio` in `defineTheme`; every font size and line height recomputes from them.',
-        },
         {
           type: 'code',
           lang: 'tsx',

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

@@ -8,7 +8,6 @@ export const docs = {
   category: 'guide',
   description:
     'How to set up AI coding tools to generate correct component code.',
-  keywords: ['claude', 'cursor', 'codex', 'copilot', 'agents', 'mcp'],
 
   sections: [
     {
@@ -25,8 +24,7 @@ export const docs = {
       ],
     },
     {
-      id: 'quick-start',
-      title: 'Set up agent docs',
+      title: 'Quick Start',
       content: [
         {
           type: 'prose',
@@ -40,7 +38,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade --from <old version>` reports a stale block and adding `--apply` refreshes it.",
+          text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade` reports a stale block and `astryx upgrade --apply` refreshes it.",
         },
         {
           type: 'prose',
@@ -50,12 +48,10 @@ export const docs = {
           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
+          code: `npx @astryxdesign/cli init --features agents --agent claude    # .claude/CLAUDE.md
+npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules
 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`,
+npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)`,
         },
       ],
     },
@@ -86,17 +82,14 @@ npx @astryxdesign/cli init --features agents --agent all       # every agent fil
       content: [
         {
           type: 'prose',
-          text: 'Cursor reads project rules from `.cursor/rules/`. To keep the Astryx context in a rule of its own, write it there. Give a path relative to the project root, such as `.cursor/rules/astryx.mdc`; an absolute path is refused.',
+          text: 'Cursor project rules aren\'t always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.',
         },
         {
           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`,
-        },
-        {
-          type: 'prose',
-          text: 'Rerunning the same command rewrites only the Astryx block, so frontmatter you add above it (such as `alwaysApply: true`) stays.',
+          label: 'Install as a Cursor user rule',
+          code: `mkdir -p ~/.cursor/rules
+npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
         },
       ],
     },
@@ -105,7 +98,7 @@ npx @astryxdesign/cli init --features agents --agent all       # every agent fil
       content: [
         {
           type: 'prose',
-          text: 'Paste this into your AI before writing any component code. If your AI can\'t answer these questions, it\'ll know to install the agent docs first.',
+          text: 'Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can\'t answer them, it\'ll know to install the agent docs first.',
         },
         {
           type: 'code',
@@ -114,7 +107,7 @@ npx @astryxdesign/cli init --features agents --agent all       # every agent fil
           code: `Before writing any Astryx code, check your knowledge:
 
 1. What is the correct import path for Button?
-2. How do you make a Dialog non-dismissible?
+2. How do you make an 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.`,
@@ -138,34 +131,33 @@ If you don't know all three, run \`npx @astryxdesign/cli init --features agents\
         },
         {
           type: 'prose',
-          text: 'With this alias, agents run `npm run astryx -- component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+          text: 'With this alias, agents use `astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Reliable CLI invocation',
-          code: `npm run astryx -- component --list
-npm run astryx -- component Dialog --dense
-npm run astryx -- docs styling --full --detail brief
-npm run astryx -- docs tokens --dense`,
+          code: `astryx component --list
+astryx component Dialog --dense
+astryx docs styling --dense
+astryx docs tokens --dense`,
         },
       ],
     },
     {
-      id: 'the-dense-flag',
-      title: 'Shorter output: --detail and --dense',
+      title: 'The --dense Flag',
       content: [
         {
           type: 'prose',
-          text: 'For a shorter read, add `--detail brief` (one line per section) or `--detail compact`. `--dense` swaps in a shorter text where a doc ships one. Use them when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
+          text: 'Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Short output for pasting into AI conversations',
-          code: `astryx docs styling --full --detail brief
-astryx component Dialog --detail compact
-astryx docs principles --dense`,
+          label: 'Dense output for pasting into AI conversations',
+          code: `astryx component Dialog --dense
+astryx docs styling --dense
+astryx docs tokens --dense`,
         },
       ],
     },

package/assets/templates/blocks/components/InternationalizationProvider/InternationalizationProvider01ShippedLocale.tsx

@@ -4,7 +4,7 @@
 
 import {useState} from 'react';
 import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';
+import frFR from '@astryxdesign/core/locales/fr-FR.json';
 import {Stack} from '@astryxdesign/core/Layout';
 import {
   SegmentedControl,

package/authoring/config/config.doc.mjs

@@ -10,7 +10,7 @@
 export const doc = {
   type: 'schema',
   name: 'config',
-  displayName: 'astryx.config',
+  displayName: 'Astryx Config',
   namespace: 'authoring',
   description:
     'The optional astryx.config.* file at your project root. Declares which ' +
@@ -60,14 +60,6 @@ export const doc = {
       example:
         "{ audience: 'internal', async handle(report, {signal}) { return sendGap(report, {signal}); } }",
     },
-    {
-      name: 'discover',
-      type: 'DiscoverSource',
-      description:
-        'Tell `astryx discover` which integrations this project could add: an async function that returns a catalog. An integration can provide one too, as a `discover` named export from its manifest. Discover calls every source, yours first, and one that fails never hides the others. Discover only reads; your package manager installs.',
-      example:
-        "async ({signal, package: name, version}) => fetchCatalog({signal, name, version})",
-    },
     {
       name: 'experimental',
       type: '{ xle?: { components?: Record<string, XleComponent> } }',
@@ -77,7 +69,7 @@ export const doc = {
           name: 'experimental.xle.components',
           type: 'Record<string, XleComponent>',
           description:
-            'No effect. Its only reader was the removed `layout` command. The key is still accepted so existing configs keep loading; delete it.',
+            'Custom components the layout expander (XLE) may emit, keyed by tag.',
         },
       ],
     },

package/authoring/config/parse.d.mts

@@ -30,7 +30,6 @@ export type XleComponent = import("./type.js").XleComponent;
 export type DebugConfig = import("./type.js").DebugConfig;
 export type DebugEventHandler = import("../debug/type.js").DebugEventHandler;
 export type GapReportHandler = import("../gap-report/type.js").GapReportHandler;
-export type DiscoverSource = import("../discover/type.js").DiscoverSource;
 import { z } from 'zod';
 declare const configSchema: z.ZodObject<{
     integrations: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -49,7 +48,6 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$strict>>;
     debug: z.ZodOptional<z.ZodType<import("../debug/type.js").DebugEventHandler, any, z.core.$ZodTypeInternals<import("../debug/type.js").DebugEventHandler, any>>>;
     gapReport: z.ZodOptional<z.ZodType<import("../gap-report/type.js").GapReportHandler, any, z.core.$ZodTypeInternals<import("../gap-report/type.js").GapReportHandler, any>>>;
-    discover: z.ZodOptional<z.ZodType<import("../discover/type.js").DiscoverSource, any, z.core.$ZodTypeInternals<import("../discover/type.js").DiscoverSource, any>>>;
     experimental: z.ZodOptional<z.ZodObject<{
         xle: z.ZodOptional<z.ZodObject<{
             components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{

package/authoring/config/parse.mjs

@@ -12,7 +12,6 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 import {parseGapReportHandler} from '../gap-report/parse.mjs';
-import {parseDiscoverSource} from '../discover/parse.mjs';
 
 /** @typedef {import('./type.js').AstryxConfig} AstryxConfig */
 /** @typedef {import('./type.js').PostCodemodHook} PostCodemodHook */
@@ -20,7 +19,6 @@ import {parseDiscoverSource} from '../discover/parse.mjs';
 /** @typedef {import('./type.js').DebugConfig} DebugConfig */
 /** @typedef {import('../debug/type.js').DebugEventHandler} DebugEventHandler */
 /** @typedef {import('../gap-report/type.js').GapReportHandler} GapReportHandler */
-/** @typedef {import('../discover/type.js').DiscoverSource} DiscoverSource */
 
 // Typed `z.custom` so `z.infer` reproduces the real function type (not `unknown`).
 const buildCommand = /** @type {z.ZodType<PostCodemodHook['buildCommand']>} */ (
@@ -68,22 +66,6 @@ const gapReportHandlerSchema = /** @type {z.ZodType<GapReportHandler>} */ (
   )
 );
 
-// The same check an integration's `discover` named export passes. Typed
-// z.custom preserves the public function type.
-const discoverSourceSchema = /** @type {z.ZodType<DiscoverSource>} */ (
-  z.custom(
-    value => {
-      try {
-        parseDiscoverSource(value, 'discover');
-        return true;
-      } catch {
-        return false;
-      }
-    },
-    {message: 'Expected a discover source function'},
-  )
-);
-
 const configSchema = z
   .object({
     integrations: z.array(z.string()).optional(),
@@ -94,7 +76,6 @@ const configSchema = z
       .optional(),
     debug: debugSchema.optional(),
     gapReport: gapReportHandlerSchema.optional(),
-    discover: discoverSourceSchema.optional(),
     experimental: z
       .object({
         xle: z

package/authoring/config/parse.test.mjs

@@ -63,14 +63,6 @@ describe('parseConfig (load boundary)', () => {
     ).toEqual({audience: 'internal', handle});
   });
 
-  it('accepts a discover source function and refuses anything else', () => {
-    const discover = async () => ({});
-    expect(parseConfig({discover}).discover).toBe(discover);
-    expect(reason({discover: 'https://example.com/catalog.json'})).toContain(
-      'discover',
-    );
-  });
-
   it('rejects obsolete or extended gap-report handler shapes', () => {
     expect(reason({gapReport: {command: './report.mjs'}})).toContain(
       'gapReport',

package/authoring/config/type.ts

@@ -11,7 +11,6 @@
 
 import type {DebugEventHandler} from '../debug/type.js';
 import type {GapReportHandler} from '../gap-report/type.js';
-import type {DiscoverSource} from '../discover/type.js';
 
 /**
  * A command to run as part of a post-codemod hook. Returned by a hook's
@@ -97,16 +96,6 @@ export interface AstryxConfig {
   debug?: DebugConfig;
   /** Route gap reports through a project-owned handler. See {@link GapReportHandler}. */
   gapReport?: GapReportHandler;
-  /**
-   * Tell `astryx discover` about integrations this project could add. See
-   * {@link DiscoverSource}.
-   *
-   * An integration can provide a source too, as a `discover` named export from
-   * its `astryx.integration.*` module. Discover calls every source: this one
-   * first, then each integration's in load order, and one that fails never
-   * hides the others.
-   */
-  discover?: DiscoverSource;
   /**
    * EXPERIMENTAL — shape may change and is not part of the stable config
    * contract. Provisional home for features still being proven out.
@@ -115,8 +104,8 @@ export interface AstryxConfig {
     /** Experimental XLE (layout expression) configuration. */
     xle?: {
       /**
-       * No effect. Its only reader was the removed `layout` command. Still
-       * accepted so existing configs keep loading; delete it.
+       * Register app-local components so XLE layout expressions can
+       * reference them by name via {hint}. Keyed by component name.
        */
       components?: Record<string, XleComponent>;
     };