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

package/clients/cli/commands/{component/index.mjs → component.mjs}

@@ -6,30 +6,30 @@
  * Global options: --detail full|compact|brief, --lang en|zh|dense
  */
 
-import {findCoreDir} from '../../../../foundation/fs/paths.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {
   resolveImportPath,
-} from '../../../../foundation/discovery/component-discovery.mjs';
+} from '../../../foundation/discovery/component-discovery.mjs';
 import {
   formatFull,
   formatCompact,
   formatBrief,
   formatProps,
   formatBriefAll,
-} from '../../lib/component-format.mjs';
-import {resolveTheme} from '../../lib/resolve-theme.mjs';
-import {getCliInvocation} from '../../../../foundation/env/package-manager.mjs';
-import {jsonOut} from '../../../../foundation/response/json.mjs';
-import {emit, section, text, list, record, records, code} from '../../formatters/index.mjs';
-import {cliError} from '../../lib/cli-error.mjs';
-import {defineCommand} from '../../lib/define-command.mjs';
-import {resultSet} from '../../../../foundation/debug/index.mjs';
-import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {component as componentApi} from '../../../../api/component/component.mjs';
-import {Project} from '../../../../foundation/config/project.mjs';
-import {warnOnIntegrationIssues} from '../../../../foundation/integrations/integration-warnings.mjs';
-import {doc as componentCommand} from '../component.doc.mjs';
-import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
+} from '../lib/component-format.mjs';
+import {resolveTheme} from '../lib/resolve-theme.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, record, records, code} from '../formatters/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {component as componentApi} from '../../../api/component/component.mjs';
+import {Project} from '../../../foundation/config/project.mjs';
+import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
+import {doc as componentCommand} from './component.doc.mjs';
+import {doc as componentFn} from '../../../api/component/component.doc.mjs';
 
 /**
  * The api layer's component() widens its return to `{type: string, data: unknown}`,
@@ -37,13 +37,13 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
  * src/types/component to get narrowing + typed data.
  *
  * @typedef {(
- *   | import('../../../../api/component/component.type.mjs').ComponentListResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentBatchResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailPropsResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailSourceResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailShowcaseResponse
- *   | import('../../../../api/component/component.type.mjs').ComponentDetailBlocksResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentListResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentBatchResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailPropsResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailSourceResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailShowcaseResponse
+ *   | import('../../../api/component/component.type.mjs').ComponentDetailBlocksResponse
  * )} ComponentResult
  */
 
@@ -57,7 +57,7 @@ import {doc as componentFn} from '../../../../api/component/component.doc.mjs';
  * the thing that resolved (the component) is not the thing being counted.
  *
  * @param {ComponentResult} result
- * @returns {import('../../../../foundation/debug/command-result.mjs').CommandResult}
+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
  */
 function summarize(result) {
   switch (result.type) {
@@ -90,11 +90,11 @@ function summarize(result) {
 
 /**
  * Project one single-component API result through the existing formatter kit.
- * @param {import('../../../../api/component/component.type.mjs').ComponentSingleResponse} result
+ * @param {import('../../../api/component/component.type.mjs').ComponentSingleResponse} result
  * @param {string} requestedName
  * @param {'full'|'compact'|'brief'} detail
  * @param {Awaited<ReturnType<typeof resolveTheme>>} themeData
- * @returns {import('../../formatters/index.mjs').Block[]}
+ * @returns {import('../formatters/index.mjs').Block[]}
  */
 function componentDetailBlocks(result, requestedName, detail, themeData) {
   const requested = (requestedName.split('/').pop() ?? requestedName).replace(
@@ -111,7 +111,7 @@ function componentDetailBlocks(result, requestedName, detail, themeData) {
       : requested;
   switch (result.type) {
     case 'component.detail': {
-      /** @type {import('../../formatters/index.mjs').Block[]} */
+      /** @type {import('../formatters/index.mjs').Block[]} */
       const out = [record({package: result.package})];
       if (result.data.parentDoc) {
         out.push(record(result.data, {fields: ['parentDoc']}));
@@ -150,7 +150,7 @@ function componentDetailBlocks(result, requestedName, detail, themeData) {
       /** @param {{package: string}} block @param {string} label */
       const owned = (block, label) =>
         block.package === result.package ? label : `${label} (${block.package})`;
-      /** @type {import('../../formatters/index.mjs').Block[]} */
+      /** @type {import('../formatters/index.mjs').Block[]} */
       const out = [record({package: result.package})];
       if (showcase) {
         out.push(
@@ -243,7 +243,7 @@ export function registerComponent(program) {
           lang, zh, dense,
         }));
       } catch (e) {
-        const err = /** @type {import('../../../../api/error.mjs').AstryxError} */ (e);
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
         return cliError(err.message, {suggestions: err.suggestions, code: err.code});
       }
 
@@ -326,7 +326,7 @@ export function registerComponent(program) {
             // description), grouped by category. Fields mirror the JSON keys.
             const groups = result.data.components;
             const entries = Object.entries(groups);
-            /** @type {import('../../formatters/index.mjs').Block[]} */
+            /** @type {import('../formatters/index.mjs').Block[]} */
             const out = [];
             for (const [cat, items] of entries) {
               // Skip the synthetic group header when there's only one ungrouped category
@@ -362,7 +362,7 @@ export function registerComponent(program) {
               nameCounts.set(item.name, set);
             }
           }
-          /** @param {import('../../../../api/component/component.type.mjs').ComponentListEntry} item */
+          /** @param {import('../../../api/component/component.type.mjs').ComponentListEntry} item */
           const importCell = item => {
             // Use a precomputed import when the API supplies one (integration
             // components carry it); only fall back to the core resolver for
@@ -392,7 +392,7 @@ export function registerComponent(program) {
         }
 
         case 'component.batch': {
-          /** @type {import('../../formatters/index.mjs').Block[]} */
+          /** @type {import('../formatters/index.mjs').Block[]} */
           const out = [
             section('Component batch'),
             record({count: result.data.count}),
@@ -474,8 +474,8 @@ export function registerComponent(program) {
 
 // Re-export lib functions for backward compatibility
 // (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)
-export {discoverComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../../../foundation/discovery/component-discovery.mjs';
-export {discoverExternalPackages} from '../../../../foundation/fs/paths.mjs';
-export {loadDocs} from '../../../../foundation/discovery/component-loader.mjs';
-export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
-export {levenshteinDistance, findClosestComponents, searchComponents} from '../../../../foundation/text/string-utils.mjs';
+export {discoverComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../../foundation/discovery/component-discovery.mjs';
+export {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';
+export {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
+export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../lib/component-format.mjs';
+export {levenshteinDistance, findClosestComponents, searchComponents} from '../../../foundation/text/string-utils.mjs';

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

@@ -12,7 +12,7 @@ import {
   findComponentSource,
   levenshteinDistance,
   findClosestComponents,
-} from './component/index.mjs';
+} from './component.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 
 const REPO_ROOT = path.resolve(import.meta.dirname, '../../../../..');
@@ -528,7 +528,7 @@ describe('findExternalComponentDoc', () => {
 describe('searchComponents', () => {
   it('finds Collapsible when searching "accordion"', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'accordion',
@@ -542,7 +542,7 @@ describe('searchComponents', () => {
 
   it('finds Dialog when searching "modal"', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'modal',
@@ -556,7 +556,7 @@ describe('searchComponents', () => {
 
   it('returns multiple matches for ambiguous terms like "select"', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'select',
@@ -571,7 +571,7 @@ describe('searchComponents', () => {
 
   it('finds exact name matches with score 100', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'Button',
@@ -584,7 +584,7 @@ describe('searchComponents', () => {
 
   it('returns empty array for complete gibberish', async () => {
     const {searchComponents, discoverComponents} =
-      await import('./component/index.mjs');
+      await import('./component.mjs');
     const components = discoverComponents('packages/core');
     const results = await searchComponents(
       'zzzzzzzzzzz',

package/clients/cli/commands/docs.doc.mjs

@@ -58,10 +58,10 @@ export const doc = {
     {label: 'Every CLI doc, one line each', cli: 'astryx docs cli --depth all'},
     {
       label: 'The integration guides as one read',
-      cli: 'astryx docs cli/integrations --depth all --detail full',
+      cli: 'astryx docs authoring --depth all --detail full',
     },
     {label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
-    {label: 'A whole guide', cli: 'astryx docs cli/integrations/quick-start --full'},
+    {label: 'A whole guide', cli: 'astryx docs authoring/quick-start --full'},
   ],
   outsideProject: 'same',
   exitCodes: [

package/clients/cli/commands/docs.mjs

@@ -535,7 +535,7 @@ function emitNode(node, detail, run) {
       text(
         [
           // A child's route is its parent's route and its name, except a flat
-          // topic in the Unorganized level, which keeps its own name.
+          // topic in a topic level, which keeps its own name.
           node.slots.every(slot =>
             slot.children.every(child => child.route.startsWith(`${node.route}/`)),
           )

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

@@ -227,7 +227,7 @@ describe('the docs tree, one level at a time', () => {
   it('wraps namespace summaries without discarding searchable words', async () => {
     const {status, stdout} = await runCli([
       'docs',
-      'cli/integrations/building-blocks/templates',
+      'authoring/building-blocks/templates',
     ]);
     expect(status).toBe(0);
     expect(stdout).toMatch(/^start-a-template +Help others build apps faster/m);
@@ -274,8 +274,8 @@ describe('the docs tree, one level at a time', () => {
   }, SLOW);
 
   it('reads the integration guides by their routes, and not by the old name', async () => {
-    // cli/integrations is a namespace: one level, its guides by slot.
-    const level = await runCli(['docs', 'cli/integrations']);
+    // authoring is a namespace: one level, its guides by slot.
+    const level = await runCli(['docs', 'authoring']);
     expect(level.status).toBe(0);
     expect(level.stdout).toMatch(
       /^quick-start +Create a new integration package/m,
@@ -283,42 +283,42 @@ describe('the docs tree, one level at a time', () => {
     expect(level.stdout).toMatch(/^building-blocks +/m);
     const guide = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       '--index',
     ]);
     expect(guide.status).toBe(0);
     expect(guide.stdout).toMatch(
-      /Read one section: .*docs cli\/integrations\/building-blocks\/codemods <section>/,
+      /Read one section: .*docs authoring\/building-blocks\/codemods <section>/,
     );
     // A bare read is one level too: the sections, and how to read it all.
     const bare = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
     ]);
     expect(bare.status).toBe(0);
     expect(bare.stdout).toBe(guide.stdout);
     expect(bare.stdout).toMatch(
-      /Read everything: +.*docs cli\/integrations\/building-blocks\/codemods --full$/m,
+      /Read everything: +.*docs authoring\/building-blocks\/codemods --full$/m,
     );
     const one = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       'which-codemods-run',
     ]);
     expect(one.status).toBe(0);
     expect(one.stdout).toMatch(/^## Choose when a codemod runs$/m);
     expect(one.stdout).toMatch(
-      /^Up: .*docs cli\/integrations\/building-blocks\/codemods --index$/m,
+      /^Up: .*docs authoring\/building-blocks\/codemods --index$/m,
     );
     expect(one.stdout).toMatch(
-      /^Previous: .*docs cli\/integrations\/building-blocks\/codemods write-the-transform$/m,
+      /^Previous: .*docs authoring\/building-blocks\/codemods write-the-transform$/m,
     );
     expect(one.stdout).toMatch(
-      /^Next: .*docs cli\/integrations\/building-blocks\/codemods run-codemods-in-an-app$/m,
+      /^Next: .*docs authoring\/building-blocks\/codemods run-codemods-in-an-app$/m,
     );
     const full = await runCli([
       'docs',
-      'cli/integrations/building-blocks/codemods',
+      'authoring/building-blocks/codemods',
       '--full',
     ]);
     expect(full.status).toBe(0);
@@ -343,11 +343,11 @@ describe('the docs tree, one level at a time', () => {
       type: 'docs.detail.section',
       data: {id: 'side-panels', title: 'Side panels'},
     });
-    const missing = await runCli(['docs', 'cli', 'zzzz-nope', '--json']);
+    const missing = await runCli(['docs', 'authoring', 'zzzz-nope', '--json']);
     expect(missing.status).toBe(1);
     const error = JSON.parse(missing.stdout);
     expect(error).toMatchObject({code: 'ERR_UNKNOWN_SECTION'});
-    expect(error.suggestions.map(s => s.name)).toContain('cli/integrations/quick-start');
+    expect(error.suggestions.map(s => s.name)).toContain('authoring/quick-start');
   }, SLOW);
 });
 

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

@@ -19,7 +19,10 @@ import {Command} from 'commander';
 import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
 import {discoverOwnedComponents} from '../../../foundation/discovery/component-discovery.mjs';
 import {discoverBuiltinTopics} from '../../../foundation/discovery/docs-discovery.mjs';
-import {findCoreDir, findProjectCoreDir} from '../../../foundation/fs/paths.mjs';
+import {
+  findCoreDir,
+  findProjectCoreDir,
+} from '../../../foundation/fs/paths.mjs';
 import {registerDoctor} from './doctor.mjs';
 import {expectRecordsCarry} from '../../../test-utils/text-projection.mjs';
 
@@ -674,6 +677,51 @@ describe('doctor integration — command', () => {
     }
   });
 
+  it('validate prints the public-import findings as listed only, and still exits 0', async () => {
+    writeIntegration({id: 'hero', name: 'Hero', type: 'block'});
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: '@acme/widgets', version: '1.2.3', exports: {}}),
+    );
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+      'validate',
+    ]);
+
+    const output = logCalls.join('\n');
+    expect(output).toContain('note (template_import_not_exported):');
+    expect(output).toContain('Fix:');
+    expect(output).toContain('[ok] No integration issues found.');
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('validate lists, as not checked, the imports it cannot judge when package.json has no name', async () => {
+    writeIntegration({id: 'hero', name: 'Hero', type: 'block'});
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({version: '1.2.3'}),
+    );
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+      'validate',
+    ]);
+
+    const output = logCalls.join('\n');
+    expect(output).toMatch(/\[info\] Imports not checked: 1:/);
+    expect(output).toContain('package.json has no "name"');
+    expect(process.exitCode).toBeUndefined();
+  });
+
   it('templates warns on a Core id and writes the exact --package command', async () => {
     const [core] = await discoverCoreTemplates();
     expect(core).toBeDefined();

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

@@ -21,7 +21,7 @@ export const doc = {
     "the docs the CLI reads, the newest release the computer knows of, with the install and upgrade commands when the project's release is older, and every `astryx` command on the search path, warning when the first one is not the Astryx CLI or predates the hand-off. It writes nothing, but loading astryx.config runs that file's code. " +
     'The `integration` subcommands provide authoring checks for one integration package. ' +
     'Outside a project it checks the computer instead: the Node version, the release that answered, ' +
-    'the newest release this computer knows of, with the command that upgrades the CLI installed for the computer when it is older, the astryx commands on the search path, the integrations installed for the computer (warning about one it skips), and whether the computer-level agent text (`astryx init --user`) is present, matches this release, was edited, or is turned off (info only). ' +
+    "the newest release this computer knows of, with the command that upgrades the CLI installed for the computer when it is older, the astryx commands on the search path, the integrations installed for the computer (warning about one it skips), and whether the computer-level agent text (`astryx init --user`) is present, matches this release, was edited, or is turned off (info only); when that text names `astryx` and no `astryx` command is on the search path, apart from a package runner's own copy, it says so and names the install step the text records, or npm's when it records none. " +
     'It never fails a check because the folder has no project.',
   fn: 'doctor',
   subcommands: ['integration'],

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,18 @@ function printIntegrationValidation(data) {
         `${warnings} warning${warnings === 1 ? '' : 's'}`,
     ),
     ...docTypesBlocks(data.docTypes, errors > 0),
+    ...docNamesBlocks(data.docNames),
+    ...blockComponentsBlocks(data.blockComponents),
+    ...(data.publicImports && data.publicImports.unchecked.length > 0
+      ? [
+          text(
+            `[info] Imports not checked: ${data.publicImports.unchecked.length}:`,
+          ),
+          records(data.publicImports.unchecked, {
+            fields: ['file', 'specifier', 'reason'],
+          }),
+        ]
+      : []),
   );
 }
 

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');

package/clients/cli/commands/{hook/index.mjs → hook.mjs}

@@ -11,17 +11,17 @@ import {
   formatHookCompact,
   formatHookBrief,
   formatHookParams,
-} from '../../lib/hook-format.mjs';
-import {getCliInvocation} from '../../../../foundation/env/package-manager.mjs';
-import {jsonOut} from '../../../../foundation/response/json.mjs';
-import {emit, section, text, list, records, code, record} from '../../formatters/index.mjs';
-import {cliError} from '../../lib/cli-error.mjs';
-import {defineCommand} from '../../lib/define-command.mjs';
-import {resultSet} from '../../../../foundation/debug/index.mjs';
-import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {hook as hookApi} from '../../../../api/hook/hook.mjs';
-import {doc as hookCommand} from '../hook.doc.mjs';
-import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
+} from '../lib/hook-format.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, records, code, record} from '../formatters/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {resultSet} from '../../../foundation/debug/index.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {hook as hookApi} from '../../../api/hook/hook.mjs';
+import {doc as hookCommand} from './hook.doc.mjs';
+import {doc as hookFn} from '../../../api/hook/hook.doc.mjs';
 
 /**
  * The api layer's hook() widens its return to `{type: string, data: unknown}`,
@@ -29,9 +29,9 @@ import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
  * the colocated api/hook/hook.type.mjs to get narrowing + typed data.
  *
  * @typedef {(
- *   | import('../../../../api/hook/hook.type.mjs').HookListResponse
- *   | import('../../../../api/hook/hook.type.mjs').HookDetailResponse
- *   | import('../../../../api/hook/hook.type.mjs').HookDetailParamsResponse
+ *   | import('../../../api/hook/hook.type.mjs').HookListResponse
+ *   | import('../../../api/hook/hook.type.mjs').HookDetailResponse
+ *   | import('../../../api/hook/hook.type.mjs').HookDetailParamsResponse
  * )} HookResult
  */
 
@@ -40,7 +40,7 @@ import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
  * count is every hook across the groups — names or docs, depending on detail.
  *
  * @param {HookResult} result
- * @returns {import('../../../../foundation/debug/command-result.mjs').CommandResult}
+ * @returns {import('../../../foundation/debug/command-result.mjs').CommandResult}
  */
 function summarize(result) {
   if (result.type === 'hook.list') {
@@ -90,7 +90,7 @@ export function registerHook(program) {
           lang, zh,
         }));
       } catch (e) {
-        const err = /** @type {import('../../../../api/error.mjs').AstryxError} */ (e);
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
         return cliError(err.message, {suggestions: err.suggestions, code: err.code});
       }
 
@@ -112,7 +112,7 @@ export function registerHook(program) {
             // The whole view is one markdown document: a `## <category>` heading
             // over each category's concatenated hook docs.
             const groups = result.data.components;
-            /** @type {import('../../formatters/index.mjs').Block[]} */
+            /** @type {import('../formatters/index.mjs').Block[]} */
             const out = [];
             for (const [cat, items] of Object.entries(groups)) {
               const body = items
@@ -130,7 +130,7 @@ export function registerHook(program) {
             // --detail compact — one record (name + description) per hook,
             // grouped by category.
             const groups = result.data.components;
-            /** @type {import('../../formatters/index.mjs').Block[]} */
+            /** @type {import('../formatters/index.mjs').Block[]} */
             const out = [];
             for (const [cat, items] of Object.entries(groups)) {
               out.push(section(cat), records(items, {fields: ['name', 'description']}));
@@ -147,7 +147,7 @@ export function registerHook(program) {
             const [cat, hookNames] = Object.entries(groups)[0];
             emit(section(`${cat}:`), list(hookNames));
           } else {
-            /** @type {import('../../formatters/index.mjs').Block[]} */
+            /** @type {import('../formatters/index.mjs').Block[]} */
             const out = [];
             for (const [category, hookNames] of Object.entries(groups)) {
               out.push(section(category), list(hookNames));
@@ -197,12 +197,12 @@ export function registerHook(program) {
 }
 
 // Re-export lib functions for external consumers
-export {discoverHooks, findHookDoc, getAllHookNames} from '../../../../foundation/discovery/hook-discovery.mjs';
-export {loadDocs} from '../../../../foundation/discovery/component-loader.mjs';
+export {discoverHooks, findHookDoc, getAllHookNames} from '../../../foundation/discovery/hook-discovery.mjs';
+export {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 export {
   formatHookFull,
   formatHookCompact,
   formatHookBrief,
   formatHookBriefAll,
   formatHookParams,
-} from '../../lib/hook-format.mjs';
+} from '../lib/hook-format.mjs';