@astryxdesign/cli 0.7.2 → 0.7.3-canary.06872b4

package/assets/docs/tree/host-entry.doc.mjs

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/host-entry`: run the CLI from a tool that carries it,
+ * through `@astryxdesign/cli/host` (spec AST-081 FR1,
+ * architecture:cli-surface INV30).
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = {
+  type: 'generic',
+  name: 'host-entry',
+  placement: {parent: 'namespace:cli', slot: 'guides', order: 15},
+  title: 'Host entry',
+  category: 'guide',
+  keywords: [
+    'host entry',
+    'runHostedCli',
+    '@astryxdesign/cli/host',
+    'carry the cli',
+    'embed the cli',
+    'programmatic run',
+    'package sets',
+    'cliCommand',
+  ],
+  description:
+    'Run the Astryx CLI from your own command-line tool: the inputs `runHostedCli` takes, what it returns, and when the process ends instead.',
+  sections: [
+    {
+      id: 'start',
+      title: 'Start a run',
+      content: [
+        {
+          type: 'prose',
+          text: "A tool that carries the CLI for its own users starts one run per process with `runHostedCli` from `@astryxdesign/cli/host`. The run behaves as the CLI's own command does with the same arguments in the same folder, and the commands it prints start with your tool's command.",
+        },
+        {
+          type: 'code',
+          lang: 'javascript',
+          code: "import {runHostedCli} from '@astryxdesign/cli/host';\n\nconst {status} = await runHostedCli({\n  argv: process.argv.slice(2),\n  cwd: process.cwd(),\n  cliCommand: 'acme astryx',\n});\nprocess.exitCode = status;",
+        },
+      ],
+    },
+    {
+      id: 'options',
+      title: 'Options',
+      content: [
+        {
+          type: 'table',
+          headers: ['Option', 'Default', 'Meaning'],
+          rows: [
+            [
+              '`argv`',
+              'none',
+              'The command-line arguments, without the command name.',
+            ],
+            [
+              '`cwd`',
+              "the process's working folder",
+              'The folder the run works in. It must exist.',
+            ],
+            [
+              '`cliCommand`',
+              "the package manager's name",
+              'The command your users type, such as `acme astryx`: a non-blank single line of at most 120 characters, with no surrounding spaces.',
+            ],
+            [
+              '`declinedProjectCli`',
+              'none',
+              "Why you did not run the project's own CLI, such as `untrusted`: a non-blank single line of at most 120 characters. That CLI then never runs.",
+            ],
+            [
+              '`roots`',
+              'none',
+              'Your package sets, in order of preference: folders whose `node_modules` each hold a CLI, the Core of the same release, and integrations. A run never installs a release; it takes the release a project needs from the first set that holds it.',
+            ],
+            [
+              '`integrations`',
+              'none',
+              'Integrations you approve for use outside a project, by package name.',
+            ],
+            [
+              '`discoverSources`',
+              'none',
+              "Your own discover sources. `astryx discover` reports each as the host's.",
+            ],
+          ],
+        },
+      ],
+    },
+    {
+      id: 'result',
+      title: 'Result and errors',
+      content: [
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            "It resolves with `{status, packages}`: the exit status the CLI's own command would exit with, and each package the run used, with its version and whether it came from the project or a package set.",
+            'When another release answers from one of your package sets through its own host entry, that entry runs in the same process with the same inputs, and the call resolves with its result.',
+            'It rejects with a `TypeError`, before anything runs, for an unknown option or an invalid value, and with an `Error` when a run already started in the process. Start each run in a new process.',
+          ],
+        },
+      ],
+    },
+    {
+      id: 'process-ends',
+      title: 'When the process ends instead',
+      content: [
+        {
+          type: 'prose',
+          text: "Like the CLI's own command, a run ends the process with its exit status, and the call never resolves, when it:",
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'prints help or the version (`--help`, `-h`, `help`, `--version`, `-V`, `--version --json`);',
+            'rejects the command line, such as an unknown command or option;',
+            'reports an error it stops on, including every error in `--json` mode;',
+            'meets an unexpected error;',
+            "hands the run to another CLI's own command: the project's CLI when you pass no `declinedProjectCli`, or a package set whose CLI has no host entry.",
+          ],
+        },
+      ],
+    },
+  ],
+};

package/assets/docs/tree/template-grading-rubric.doc.mjs

@@ -102,7 +102,11 @@ const gradeRows = TEMPLATE_RUBRIC.grades.map(({grade, min, max, meaning}) => [
 export const docs = {
   type: 'generic',
   name: 'template-grading-rubric',
-  placement: {parent: 'namespace:write-good-templates', slot: 'guides', order: 10},
+  placement: {
+    parent: 'namespace:write-good-templates',
+    slot: 'guides',
+    order: 10,
+  },
   title: 'Full grading rubric',
   category: 'guide',
   description:
@@ -112,6 +116,10 @@ export const docs = {
       id: 'understand-the-score',
       title: 'Understand the score',
       content: [
+        {
+          type: 'prose',
+          text: 'Start with {@link generic:is-my-code-good}: it owns the shared Astryx quality criteria. This rubric adds template weights, counting rules, and template-only checks, and each category that scores a shared criterion names it.',
+        },
         {
           type: 'prose',
           text: `Template rubric ${TEMPLATE_RUBRIC.version} scores seven categories for 100 points. Aim for 100; ${TEMPLATE_RUBRIC.minimumGrade} (${TEMPLATE_RUBRIC.minimumScore}) is the publication floor, not the target. Each category below lists its weight. Never award points for anything you did not inspect.`,
@@ -137,11 +145,11 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Count every JSX opening tag in the copied `.tsx` source. An Astryx element is a component imported from `@astryxdesign/core` or from a public component export of the integration package. A raw HTML element is any lowercase intrinsic JSX tag. Count occurrences, not only unique tag names.',
+          text: 'This category scores the Astryx components criterion in {@link generic:is-my-code-good}. Count every JSX opening tag in the copied `.tsx` source. An Astryx element is a component imported from `@astryxdesign/core` or from a public component export of the integration package. A raw HTML element is any lowercase intrinsic JSX tag. Count occurrences, not only unique tag names.',
         },
         {
           type: 'prose',
-          text: 'Do not count fragments or a PascalCase helper defined in the same file. Inspect that helper and count the raw HTML inside it. For each raw element, decide whether it is necessary because Astryx has no equivalent, or unnecessary because an Astryx component can replace it.',
+          text: 'Do not count fragments or a PascalCase helper defined in the same file. Inspect that helper and count the raw HTML inside it. For each raw element, decide with that guide whether it is necessary because Astryx has no equivalent, or unnecessary because an Astryx component can replace it.',
         },
         {
           type: 'table',
@@ -156,35 +164,6 @@ export const docs = {
             ['21 or more', '0'],
           ],
         },
-        {
-          type: 'table',
-          headers: ['Raw HTML use', 'Astryx replacement'],
-          rows: [
-            [
-              '`div` for layout',
-              '`VStack`, `HStack`, `Card`, `Section`, or `Center`',
-            ],
-            ['`div` for a grid', '`Grid`'],
-            ['`span` or `p` for text', '`Text`'],
-            ['`h1` through `h6`', '`Heading level={N}`'],
-            ['`button`', '`Button` or `IconButton`'],
-            ['`a`', '`Link`'],
-            ['In-page `nav` or `aside`', '`LayoutPanel` in the start slot'],
-            [
-              '`header` or `main`',
-              '`LayoutHeader` or `LayoutContent` in `Layout`',
-            ],
-            ['`ul`, `ol`, or `li`', '`List` and `ListItem`'],
-            [
-              '`input`, `textarea`, or `select`',
-              'The matching Astryx form control',
-            ],
-            ['`table`, `tr`, or `td`', '`Table`'],
-            ['`hr`', '`Divider`'],
-            ['`dialog`', '`Dialog`'],
-            ['`details` or `summary`', '`Collapsible`'],
-          ],
-        },
         {
           type: 'list',
           style: 'unordered',
@@ -202,7 +181,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Count raw icon markup in the copied file. {@link generic:template-icons} shows how to render icons through Astryx instead.',
+          text: 'This category scores the Icons criterion in {@link generic:is-my-code-good}. Count raw icon markup in the copied file. {@link generic:template-icons} shows how to render icons through Astryx instead.',
         },
         {
           type: 'list',
@@ -231,7 +210,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Prefer Astryx component props and design tokens. Count individual CSS properties inside `stylex.create` and inline `style` objects. Count each `className` and `stylex.props` use once. Do not count Astryx props such as `gap`, `padding`, `variant`, `size`, `color`, `level`, `columns`, `contentPadding`, or `height`.',
+          text: 'This category scores the Styling criterion in {@link generic:is-my-code-good}. Count individual CSS properties inside `stylex.create` and inline `style` objects. Count each `className` and `stylex.props` use once. Do not count Astryx props such as `gap`, `padding`, `variant`, `size`, `color`, `level`, `columns`, `contentPadding`, or `height`.',
         },
         {
           type: 'table',
@@ -260,7 +239,7 @@ export const docs = {
           type: 'list',
           style: 'ordered',
           items: [
-            'Use `Layout` or `Center` as the page root. A template whose category starts with `Shell -` uses `AppShell` because global chrome is its purpose.',
+            'Choose the page root with the Layout criterion in {@link generic:is-my-code-good}. In a template, only a category that starts with `Shell -` owns global chrome, so it uses `AppShell`; every other page template uses `Layout` or `Center`.',
             'Outside a `Shell -` template, leave global navigation to the host app. Put in-page navigation in a `LayoutPanel` and page headings in `LayoutHeader`.',
             'Use `Grid` with `columns={{minWidth: 280}}` for responsive collections. Do not fix the column count or rebuild the grid in raw CSS.',
             'Use `Center` for centered content instead of custom flexbox workarounds.',
@@ -385,7 +364,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Inspect every image reference in the copied file against {@link generic:template-images-media}.',
+          text: 'This category scores the Images and assets criterion in {@link generic:is-my-code-good}. Inspect every image reference in the copied file against {@link generic:template-images-media}.',
         },
         {
           type: 'table',
@@ -413,7 +392,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Award 2 points for each condition. Grade the copied file, not only the package source.',
+          text: 'This category scores the Code health criterion in {@link generic:is-my-code-good}, plus conditions only a template has. Award 2 points for each condition. Grade the copied file, not only the package source.',
         },
         {
           type: 'table',

package/assets/docs/tree/tokens-data.doc.mjs

@@ -17,14 +17,14 @@ export const docs = {
     "order": 20
   },
   "category": "foundations",
-  "description": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Retaining any member emits the complete 56-variable group; an unused graph emits none.",
+  "description": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Source compilation emits the complete 56-variable group when any member is retained and none for an unused graph. Prebuilt CSS consumers load @astryxdesign/core/astryx.css, which defines the complete group for the already-compiled dataVars entry.",
   "sections": [
     {
       "title": "Data Visualization Tokens",
       "content": [
         {
           "type": "prose",
-          "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Retaining any member emits the complete 56-variable group; an unused graph emits none."
+          "text": "Colors for charts and graphs: one categorical accent per series, a neutral for labels and reference lines, and sequential ramps from 5 (darkest) to 1 (lightest) for ordered scales and heatmaps. Import dataVars from @astryxdesign/core/theme/dataTokens.stylex for CSS-capable code. Source compilation emits the complete 56-variable group when any member is retained and none for an unused graph. Prebuilt CSS consumers load @astryxdesign/core/astryx.css, which defines the complete group for the already-compiled dataVars entry."
         },
         {
           "type": "table",

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

@@ -44,7 +44,7 @@ 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',
@@ -55,7 +55,11 @@ astryx init --features agents --agent cursor    # .cursorrules if present, else
 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, else AGENTS.md and .claude/CLAUDE.md`,
+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',

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/authoring/debug/parse.d.mts

@@ -79,9 +79,9 @@ declare const eventSchema: z.ZodObject<{
             none: "none";
             component: "component";
             hook: "hook";
+            theme: "theme";
             doc: "doc";
             template: "template";
-            theme: "theme";
             integration: "integration";
             migration: "migration";
             mixed: "mixed";

package/clients/cli/bin/astryx.mjs

@@ -53,84 +53,13 @@ if (!isNodeVersionSupported(process.versions.node)) {
   process.exit(1);
 }
 
-// Global mode: choose the release that answers this folder and, when it is
-// not this copy, hand the run to it before anything the project provides (its
-// astryx.config, integrations, or Core) is loaded. Returns only when this copy
-// answers. See foundation/release/handoff.mjs and spec AST-081 FR2 and FR9.
-const {startRun} = await importSrc('../../foundation/release/handoff.mjs');
-await startRun({
+// Global mode: the run chooses the release that answers this folder and, when
+// it is not this copy, hands the run to it before anything the project
+// provides (its astryx.config, integrations, or Core) is loaded; only then
+// does it load and dispatch the command. See clients/cli/run.mjs,
+// foundation/release/handoff.mjs, and spec AST-081 FR2 and FR9.
+const {runCli} = await importSrc('run.mjs');
+await runCli({
   cliRoot: join(binDir, '..', '..', '..'),
   argv: process.argv.slice(2),
 });
-
-// Imports that transitively load `styleText` must happen AFTER the gate above,
-// so they are dynamically imported here rather than at the top of the module.
-const {
-  program,
-  loadProjectDebugHandler,
-  loadProjectForHelp,
-  handleVersionJsonPreflight,
-} = await importSrc('index.mjs');
-const {isJsonMode, toErrorEnvelope} = await importSrc('../../foundation/response/json.mjs');
-const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
-const {setOutcome} = await importSrc('../../foundation/debug/index.mjs');
-
-/**
- * Top-level error boundary (contract guarantee #4): an uncaught throw must
- * never reach a --json consumer as a raw stack trace. If we're in JSON mode,
- * convert it to the contract's error envelope on stdout and exit 1; otherwise
- * preserve the normal human-facing behavior.
- *
- * We detect JSON mode two ways: the global flag (set once root options are
- * parsed) and a raw argv check, since a throw can occur during parsing/command
- * load — before the preAction hook engages the flag.
- */
-function inJsonMode() {
-  return isJsonMode() || process.argv.slice(2).includes('--json');
-}
-
-/** @param {unknown} err */
-function handleFatal(err) {
-  // CommanderError (parse errors, --help, unknown command) routes
-  // through the JSON shim so that a --json consumer always gets a
-  // valid envelope and the right exit code. handleCommanderError
-  // calls process.exit when it owns the error.
-  if (handleCommanderError(err)) return;
-
-  // Anything still here is an uncaught throw or an unhandled rejection —
-  // a bug rather than a user error, and the class of failure most worth
-  // having a record of.
-  setOutcome('fatal', {exitCode: 1, error: err});
-
-  if (inJsonMode()) {
-    // Only emit if a command didn't already produce an envelope.
-    if (!process.__xdsJsonHandled) {
-      process.__xdsJsonHandled = true;
-      console.log(JSON.stringify(toErrorEnvelope(err), null, 2));
-    }
-    process.exit(1);
-  }
-  // Human mode: preserve Commander/Node default-ish behavior.
-  console.error(err instanceof Error ? err.stack || err.message : String(err));
-  process.exit(1);
-}
-
-process.on('unhandledRejection', handleFatal);
-process.on('uncaughtException', handleFatal);
-
-// Pick up the project's `debug` function before parsing, so parse errors and
-// `--help` — which short-circuit before any hook runs — are reported too.
-await loadProjectDebugHandler();
-// Help prints its commands while Commander parses, so a help run reads the
-// project's declared `cliCommand` here.
-await loadProjectForHelp();
-
-// `--version --json` answers and exits without Commander, so it runs here —
-// after the handler exists, or the run would go unrecorded.
-handleVersionJsonPreflight();
-
-try {
-  await program.parseAsync(process.argv);
-} catch (err) {
-  handleFatal(err);
-}

package/clients/cli/commands/doctor.mjs

@@ -179,6 +179,34 @@ function docTypesBlocks(report, failed) {
   return blocks;
 }
 
+/**
+ * The component doc names that could not be judged against their sources.
+ * @param {import('../../../api/integration/validate-integration.type.mjs').DocNamesReport | undefined} report
+ */
+function docNamesBlocks(report) {
+  if (!report || report.unchecked.length === 0) return [];
+  return [
+    text(
+      `[info] Component names not checked: ${report.unchecked.length} doc(s) whose source exports this check cannot read:`,
+    ),
+    records(report.unchecked, {fields: ['file', 'name', 'reason']}),
+  ];
+}
+
+/**
+ * The block component names this check could not judge.
+ * @param {import('../../../api/integration/validate-integration.type.mjs').BlockComponentsReport | undefined} report
+ */
+function blockComponentsBlocks(report) {
+  if (!report || report.unchecked.length === 0) return [];
+  return [
+    text(
+      `[info] Block component names not checked: ${report.unchecked.length} name(s) this check could not judge:`,
+    ),
+    records(report.unchecked, {fields: ['file', 'name', 'reason']}),
+  ];
+}
+
 /**
  * @param {import('../../../api/integration/validate-integration.type.mjs').ValidateIntegrationResponse['data']} data
  */
@@ -204,6 +232,8 @@ function printIntegrationValidation(data) {
         `${warnings} warning${warnings === 1 ? '' : 's'}`,
     ),
     ...docTypesBlocks(data.docTypes, errors > 0),
+    ...docNamesBlocks(data.docNames),
+    ...blockComponentsBlocks(data.blockComponents),
   );
 }
 

package/clients/cli/commands/doctor.test.mjs

@@ -191,6 +191,31 @@ describe('doctor — individual checks', () => {
     expect(res.fix).toContain('`npx astryx init --features agents`');
   });
 
+  it('agent-docs: at the top of a home settings folder, the fix moves the project or edits by hand, never init', () => {
+    const saved = {HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE};
+    process.env.HOME = tmpDir;
+    process.env.USERPROFILE = tmpDir;
+    try {
+      const project = path.join(tmpDir, '.dotfiles');
+      fs.mkdirSync(project);
+      fs.writeFileSync(path.join(project, 'package.json'), '{"name":"dots"}');
+      for (const content of [null, '# Agents\nno markers here\n']) {
+        if (content != null) fs.writeFileSync(path.join(project, 'AGENTS.md'), content);
+        const res = checkAgentDocs({cwd: project});
+        expect(res.fix).toContain('Agent docs are not written into the home folder');
+        expect(res.fix).toContain(
+          'Move the project into a folder of its own, or edit the Astryx block in its agent file by hand.',
+        );
+        expect(res.fix).not.toContain('init --features agents');
+      }
+    } finally {
+      for (const [key, value] of Object.entries(saved)) {
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+      }
+    }
+  });
+
   it('agent-docs: WARN when docs exist without XDS markers', () => {
     fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# AGENTS\nno markers here');
     const res = checkAgentDocs({cwd: tmpDir});
@@ -221,6 +246,25 @@ describe('doctor — individual checks', () => {
     );
   });
 
+  it('agent-docs: PASS from a nested package, reading the root that declares Astryx', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({dependencies: {'@astryxdesign/core': '0.7.0'}}),
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'AGENTS.md'),
+      '<!-- ASTRYX:START -->\nstuff\n<!-- ASTRYX:END -->\n',
+    );
+    const functions = path.join(tmpDir, 'functions');
+    fs.mkdirSync(path.join(functions, 'src'), {recursive: true});
+    fs.writeFileSync(path.join(functions, 'package.json'), '{"name":"functions"}');
+
+    expect(checkAgentDocs({cwd: path.join(functions, 'src')})).toMatchObject({
+      status: 'pass',
+      message: `Astryx agent docs section present in ${path.join('..', '..', 'AGENTS.md')}.`,
+    });
+  });
+
   it('agent-docs: reads every file init can write, Hermes included', () => {
     fs.writeFileSync(
       path.join(tmpDir, 'HERMES.md'),
@@ -232,6 +276,27 @@ describe('doctor — individual checks', () => {
     });
   });
 
+  it('agent-docs: FAIL when GEMINI.md imports an AGENTS.md that holds no block', () => {
+    const geminiImport = '<!-- ASTRYX:START -->\n@./AGENTS.md\n<!-- ASTRYX:END -->\n';
+    fs.writeFileSync(path.join(tmpDir, 'GEMINI.md'), geminiImport);
+    expect(checkAgentDocs({cwd: tmpDir})).toMatchObject({
+      status: 'fail',
+      message: expect.stringMatching(/^GEMINI\.md imports AGENTS\.md, which holds no Astryx block/),
+      fix: expect.stringMatching(/init --features agents/),
+    });
+
+    // A copy elsewhere does not mend it: Codex and Gemini CLI still get none.
+    fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '<!-- ASTRYX:START -->\nstuff\n<!-- ASTRYX:END -->\n');
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n');
+    expect(checkAgentDocs({cwd: tmpDir}).status).toBe('fail');
+
+    fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '<!-- ASTRYX:START -->\nstuff\n<!-- ASTRYX:END -->\n');
+    expect(checkAgentDocs({cwd: tmpDir})).toMatchObject({
+      status: 'pass',
+      message: 'Astryx agent docs section present in AGENTS.md, CLAUDE.md.',
+    });
+  });
+
   it('agent-docs: INFO names what it looked for and where', () => {
     const res = checkAgentDocs({cwd: tmpDir});
     expect(res.status).toBe('info');