@astryxdesign/cli 0.7.2 → 0.7.3-canary.0bf23bd

package/api/docs/integration-tree.test.mjs

@@ -246,7 +246,7 @@ describe('integration docs in the docs tree', () => {
     });
     scaffold({
       ...kit(),
-      'unorganized.doc.mjs': {...NAMESPACE, name: 'unorganized', title: 'Mine', summary: 'Mine.'},
+      'guides.doc.mjs': {...NAMESPACE, name: 'guides', title: 'Mine', summary: 'Mine.'},
       'use-a-theme.doc.mjs': {...NAMESPACE, name: 'use-a-theme', title: 'Acme use-a-theme', summary: 'Acme use-a-theme.'},
       'cli.doc.mjs': flat('cli'),
     });
@@ -254,26 +254,26 @@ describe('integration docs in the docs tree', () => {
     expect(listed.meta.namespaces).toEqual(
       expect.arrayContaining([
         expect.objectContaining({topic: 'cli', package: '@astryxdesign/cli'}),
-        expect.objectContaining({topic: 'unorganized', package: '@astryxdesign/cli'}),
+        expect.objectContaining({topic: 'guides', package: '@astryxdesign/cli'}),
       ]),
     );
-    expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'unorganized'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
+    expect(listed.meta.namespaces.filter(n => ['use-a-theme', 'guides'].includes(n.topic) && n.package === '@acme/kit')).toEqual([]);
     expect(listed.data.map(entry => entry.topic)).not.toContain('cli');
     // Each name opens the CLI's doc, and a CLI topic keeps its home.
     expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
-    expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
+    expect((await docs('guides', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
     const tokens = await docs('use-a-theme', undefined, {cwd: tmpDir});
     expect(tokens.type).toBe('docs.detail');
-    expect(tokens.data.links.up).toBe('astryx docs unorganized');
+    expect(tokens.data.links.up).toBe('astryx docs guides');
     // The project doctor and the package doctor both name the claims.
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
-    expect(check.message).toContain('takes the route "unorganized", which the CLI\'s own docs keep');
+    expect(check.message).toContain('takes the route "guides", which the CLI\'s own docs keep');
     expect(check.message).toContain('takes the route "use-a-theme"');
     expect(check.message).toContain('both have the route "cli"');
     const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = result.data.issues.filter(issue => issue.code === 'invalid_doc_graph').map(issue => issue.message).join('\n');
-    expect(graph).toContain('takes the route "unorganized"');
+    expect(graph).toContain('takes the route "guides"');
     expect(graph).toContain('takes the route "use-a-theme"');
     expect(graph).toContain('route "cli"');
   }, SLOW);
@@ -294,16 +294,16 @@ describe('integration docs in the docs tree', () => {
     const nested = path.join(tmpDir, 'node_modules', '@acme', 'kit', 'docs', 'nested');
     fs.mkdirSync(nested, {recursive: true});
     fs.writeFileSync(
-      path.join(nested, 'caps-unorganized.doc.mjs'),
-      `export const docs = ${JSON.stringify(flat('Unorganized'), null, 2)};\n`,
+      path.join(nested, 'caps-guides.doc.mjs'),
+      `export const docs = ${JSON.stringify(flat('Guides'), null, 2)};\n`,
     );
     fs.writeFileSync(
       path.join(nested, 'caps-use-a-theme.doc.mjs'),
       `export const docs = ${JSON.stringify(flat('USE-A-THEME'), null, 2)};\n`,
     );
     expect((await docs('cli', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
-    expect((await docs('unorganized', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
-    expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs unorganized');
+    expect((await docs('guides', undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
+    expect((await docs('theme', undefined, {cwd: tmpDir, index: true})).data.links.up).toBe('astryx docs guides');
     const listed = await docs(undefined, undefined, {cwd: tmpDir});
     expect(listed.data.map(entry => entry.topic.toLowerCase())).not.toContain('cli');
     // Search does not offer a topic whose route another doc owns.
@@ -314,10 +314,10 @@ describe('integration docs in the docs tree', () => {
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
     expect(check.message).toContain('route "CLI"');
-    expect(check.message).toContain('takes the route "Unorganized"');
+    expect(check.message).toContain('takes the route "Guides"');
     // `USE-A-THEME` is the CLI's topic `use-a-theme` in another spelling: the CLI's wins.
     const tokens = await docs('USE-A-THEME', undefined, {cwd: tmpDir, index: true});
-    expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs unorganized'}});
+    expect(tokens.data).toMatchObject({name: 'use-a-theme', links: {up: 'astryx docs guides'}});
     expect(tokens.data.title).not.toBe('Acme USE-A-THEME');
     const result = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = result.data.issues
@@ -325,7 +325,7 @@ describe('integration docs in the docs tree', () => {
       .map(issue => issue.message)
       .join('\n');
     expect(graph).toContain('route "CLI"');
-    expect(graph).toContain('takes the route "Unorganized"');
+    expect(graph).toContain('takes the route "Guides"');
   }, SLOW);
 
   it("keeps a replaced name for the topic that replaces it, over another integration's namespace", async () => {
@@ -420,9 +420,9 @@ describe('integration docs in the docs tree', () => {
     scaffold({
       ...kit(),
       'a-cli.doc.mjs': flat('cli'),
-      'a-unorganized.doc.mjs': flat('Unorganized'),
+      'a-guides.doc.mjs': flat('Guides'),
       'z-b2.doc.mjs': flat('b2', {replaces: 'cli'}),
-      'z-u2.doc.mjs': flat('u2', {replaces: 'Unorganized'}),
+      'z-u2.doc.mjs': flat('u2', {replaces: 'Guides'}),
     });
     // Another package carries the chain on: c3 replaces b2, which replaced cli.
     const three = path.join(tmpDir, 'node_modules', '@acme', 'three');
@@ -440,8 +440,8 @@ describe('integration docs in the docs tree', () => {
     for (const name of ['cli', 'CLI']) {
       expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'cli', package: '@astryxdesign/cli'});
     }
-    for (const name of ['unorganized', 'UNORGANIZED']) {
-      expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'unorganized', package: '@astryxdesign/cli'});
+    for (const name of ['guides', 'GUIDES']) {
+      expect((await docs(name, undefined, {cwd: tmpDir})).data).toMatchObject({route: 'guides', package: '@astryxdesign/cli'});
     }
     // The replacement still answers to its own names.
     for (const name of ['b2', 'c3']) {
@@ -456,7 +456,7 @@ describe('integration docs in the docs tree', () => {
     const check = await checkDocsTree({docsCatalog: await loadDocsCatalog(tmpDir)});
     expect(check.status).toBe('warn');
     expect(check.message).toContain('The topic "c3" answers to "cli" through replaces');
-    expect(check.message).toContain('The topic "u2" answers to "unorganized" through replaces');
+    expect(check.message).toContain('The topic "u2" answers to "guides" through replaces');
     const inPackage = await integrationDocConflicts('@acme/kit', {cwd: tmpDir});
     const graph = inPackage.data.issues
       .filter(issue => issue.code === 'invalid_doc_graph')
@@ -519,7 +519,7 @@ describe('integration docs in the docs tree', () => {
     });
     const {data} = await docs('theme', 'acme-theming-notes', {cwd: tmpDir});
     // `generic:integrations` is the extension's own guide, never the CLI's
-    // `cli/integrations`; a provider-qualified link reaches the CLI's topic.
+    // `authoring`; a provider-qualified link reaches the CLI's topic.
     expect(data.content[0].text).toBe(
       'See `astryx docs acme/integrations`, and `astryx docs tokens` for the tokens.',
     );

package/api/docs/integrationDocs.test.mjs

@@ -447,7 +447,7 @@ describe('integration-contributed topics', () => {
     // places it.
     expect(top).toContain('troubleshooting');
     expect(
-      top.some(name => /^cli\/integrations\/(?:.+\/)?troubleshooting$/.test(name)),
+      top.some(name => /^authoring\/(?:.+\/)?troubleshooting$/.test(name)),
       top.join(', '),
     ).toBe(true);
   }, SLOW);

package/api/docs/namespace-section.test.mjs

@@ -157,13 +157,13 @@ describe('a section read on a namespace', () => {
       expect(names).toContain('layout/side-panels');
       expect(names.every(name => name.startsWith('layout/'))).toBe(true);
       // At any depth: guides under nested namespaces are named, namespaces are not.
-      const cli = await docs('cli', 'zzzz-nope').catch(e => e);
-      expect(cli.code).toBe('ERR_UNKNOWN_SECTION');
-      expect(cli.suggestions.map(s => s.name)).toContain(
-        'cli/integrations/quick-start',
+      const authoring = await docs('authoring', 'zzzz-nope').catch(e => e);
+      expect(authoring.code).toBe('ERR_UNKNOWN_SECTION');
+      expect(authoring.suggestions.map(s => s.name)).toContain(
+        'authoring/building-blocks/components/add-a-component',
       );
-      expect(cli.suggestions.map(s => s.name)).not.toContain(
-        'cli/integrations',
+      expect(authoring.suggestions.map(s => s.name)).not.toContain(
+        'authoring/building-blocks',
       );
     },
     SLOW,

package/api/docs/reference-blocks.test.mjs

@@ -300,11 +300,11 @@ describe('a reference block that includes what it names', () => {
 });
 
 describe('what a reference block names', () => {
-  it('resolves a CLI authoring schema by identity, to its section of `astryx docs authoring`', async () => {
+  it('resolves a CLI authoring schema by identity, to its section of the field reference', async () => {
     const resolve = await linkResolver(builtinCatalog(), CLI_PROVIDER_ID);
     expect(await resolve('schema:integration')).toMatchObject({
       id: createDocId(CLI_PROVIDER_ID, 'schema', 'integration'),
-      route: 'authoring',
+      route: 'authoring/field-reference',
       title: 'Astryx Integration',
       command: 'astryx docs authoring integration',
     });

package/api/doctor/doctor.mjs

@@ -28,7 +28,15 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/node-version.mjs';
-import {AGENT_DOC_PATHS} from '../../foundation/agent-docs/agent-doc-state.mjs';
+import {
+  AGENT_DOC_PATHS,
+  holdsAstryxBlock,
+} from '../../foundation/agent-docs/agent-doc-state.mjs';
+import {
+  agentDocsTargetDir,
+  assertAgentDocsTarget,
+  resolveAgentDocsRoot,
+} from '../../foundation/agent-docs/agent-docs.mjs';
 import {CLI_ROOT, findProjectCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
 import {explainPackageManager, formatCliCommand, getCliInvocation, guessCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {chooseDeclaredCliCommand, declaredCliCommandsOf} from '../../foundation/env/cli-command.mjs';
@@ -610,6 +618,21 @@ export function checkConfiguredIntegrations(ctx) {
   };
 }
 
+/**
+ * Why init writes no agent docs for `cwd`, or null when it does: the folder
+ * it would write to is the home folder or the top of a settings folder in it.
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+function agentDocsRefusal(cwd) {
+  try {
+    assertAgentDocsTarget(agentDocsTargetDir(cwd));
+    return null;
+  } catch (err) {
+    return err instanceof Error && err.name === 'AgentDocsHomeError' ? err.message : null;
+  }
+}
+
 /**
  * Check 7 — agent docs exist and contain the Astryx section markers.
  * @param {DoctorContext} ctx
@@ -617,8 +640,15 @@ export function checkConfiguredIntegrations(ctx) {
  */
 export function checkAgentDocs(ctx) {
   // Every file init can write (one shared list), looked for in the working
-  // directory and in the project root: run from src/, the docs sit at the root.
-  const dirs = [...new Set([ctx.cwd, projectRootOf(ctx)])];
+  // directory, the project root, and the folder init writes them to: run from
+  // src/ or a nested package, the docs sit at the root.
+  const dirs = [
+    ...new Set(
+      [ctx.cwd, projectRootOf(ctx), resolveAgentDocsRoot(ctx.cwd) ?? ctx.cwd].map(dir =>
+        path.resolve(dir),
+      ),
+    ),
+  ];
   const present = dirs.flatMap(dir =>
     AGENT_DOC_PATHS.map(rel => path.join(dir, rel)).filter(abs =>
       fs.existsSync(abs),
@@ -626,6 +656,15 @@ export function checkAgentDocs(ctx) {
   );
   /** @param {string} abs */
   const shown = abs => path.relative(ctx.cwd, abs) || path.basename(abs);
+  // In the home folder, or at the top of a settings folder in it, init
+  // writes no agent docs (INV31), so the fix is moving the project or a hand
+  // edit, never init.
+  const refusal = agentDocsRefusal(ctx.cwd);
+  /** @param {string} initFix */
+  const fixFor = initFix =>
+    refusal
+      ? `${refusal} Move the project into a folder of its own, or edit the Astryx block in its agent file by hand.`
+      : initFix;
 
   if (present.length === 0) {
     return {
@@ -633,29 +672,64 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'info',
       message: `No agent docs found: looked for ${AGENT_DOC_PATHS.join(', ')} in ${dirs.map(dir => path.relative(ctx.cwd, dir) || '.').join(' and ')}.`,
-      fix: `Generate agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      fix: fixFor(
+        `Generate agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      ),
     };
   }
 
-  const withMarkers = present.filter(abs => {
+  /** @param {string} abs */
+  const read = abs => {
     try {
-      const content = fs.readFileSync(abs, 'utf-8');
-      return (
-        (content.includes('<!-- ASTRYX:START -->') || content.includes('<!-- XDS:START -->')) &&
-        (content.includes('<!-- ASTRYX:END -->') || content.includes('<!-- XDS:END -->'))
-      );
+      return fs.readFileSync(abs, 'utf-8');
     } catch {
-      return false;
+      return '';
     }
+  };
+  const withMarkers = present.filter(abs => {
+    const content = read(abs);
+    return (
+      (content.includes('<!-- ASTRYX:START -->') || content.includes('<!-- XDS:START -->')) &&
+      (content.includes('<!-- ASTRYX:END -->') || content.includes('<!-- XDS:END -->')) &&
+      holdsAstryxBlock(content)
+    );
   });
 
+  // A managed block that only imports another file (init's GEMINI.md import
+  // of AGENTS.md) is broken when that file holds no block: the agents that
+  // read either file get no Astryx docs.
+  const dangling = present.flatMap(abs => {
+    const match = /<!-- ASTRYX:START -->\s*@(\S+)\s*<!-- ASTRYX:END -->/.exec(read(abs));
+    if (match == null) return [];
+    const target = path.resolve(path.dirname(abs), match[1]);
+    return holdsAstryxBlock(read(target)) ? [] : [{abs, target}];
+  });
+  if (dangling.length > 0) {
+    return {
+      id: 'agent-docs',
+      label: 'AI agent docs',
+      status: 'fail',
+      message: dangling
+        .map(
+          ({abs, target}) =>
+            `${shown(abs)} imports ${shown(target)}, which holds no Astryx block, so agents that read them get no Astryx docs.`,
+        )
+        .join(' '),
+      fix: fixFor(
+        `Write the block again with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      ),
+    };
+  }
+
   if (withMarkers.length === 0) {
     return {
       id: 'agent-docs',
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.map(shown).join(', ')}) but no Astryx section markers found.`,
-      fix: `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      fix: fixFor(
+        `Add the Astryx section to your agent docs with \`${getCliInvocation(ctx.cwd)} init --features agents\`.`,
+      ),
     };
   }
 
@@ -974,16 +1048,20 @@ function nameTypes(names) {
 }
 
 /**
- * The section keys `astryx docs authoring --index` lists, read the way that
- * command reads them.
+ * The section keys the field reference lists (`astryx docs
+ * authoring/field-reference --index`), read the way that command reads them.
  * @returns {Promise<{keys: Set<string>} | {keys: null, error: string}>}
  */
 async function authoringTopicKeys() {
   try {
+    const {AUTHORING_REFERENCE_ROUTE} =
+      await import('../../foundation/discovery/authoring-self-docs.mjs');
     const catalog = DocsCatalog.fromBuiltins();
-    const entry = catalog.resolve('authoring');
-    if (!entry) return {keys: null, error: 'it is not a built-in topic'};
-    const index = indexView(await lowerTopic(catalog, entry));
+    const node = (await projectTree(catalog)).get(AUTHORING_REFERENCE_ROUTE);
+    if (!node?.ref?.topicFile) {
+      return {keys: null, error: 'the docs tree has no field reference'};
+    }
+    const index = indexView(await lowerTopic(catalog, guideEntry(node)));
     return {keys: new Set(index.sections.map(section => section.id))};
   } catch (err) {
     return {
@@ -1002,7 +1080,7 @@ function surfaceProblems(surface) {
   const problems = [];
   if (surface.types === 0 && surface.untraced.length === 0) {
     problems.push(
-      `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring')}\``,
+      `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring/field-reference')}\``,
     );
   }
   for (const {module, names, reason, source, key} of surface.unreadable) {
@@ -1015,7 +1093,7 @@ function surfaceProblems(surface) {
             ? `${source} does not load`
             : `${source} renders section "${key}", which the topic's index does not list`;
     problems.push(
-      `${nameTypes(names)} from ${module} ${names.length === 1 ? 'has' : 'have'} no doc in \`${formatCliCommand('docs authoring')}\`: ${why}`,
+      `${nameTypes(names)} from ${module} ${names.length === 1 ? 'has' : 'have'} no doc in \`${formatCliCommand('docs authoring/field-reference')}\`: ${why}`,
     );
   }
   for (const {name, reason} of surface.untraced) {
@@ -1056,7 +1134,7 @@ export async function checkAuthoringDocs(_ctx, options = {}) {
     const audit = await auditAuthoringSelfDocs({root, sources});
     const problems = [
       ...audit.unreachable.map(
-        source => `${source} is not in \`${formatCliCommand('docs authoring')}\``,
+        source => `${source} is not in \`${formatCliCommand('docs authoring/field-reference')}\``,
       ),
       ...audit.failed.map(
         ({source, error}) => `${source} failed to load: ${error}`,
@@ -1072,7 +1150,7 @@ export async function checkAuthoringDocs(_ctx, options = {}) {
         : {keys: options.topicKeys};
     const surface = [
       ...('error' in topic
-        ? [`\`${formatCliCommand('docs authoring')}\` could not be read: ${topic.error}`]
+        ? [`\`${formatCliCommand('docs authoring/field-reference')}\` could not be read: ${topic.error}`]
         : []),
       ...surfaceProblems(
         await auditAuthoringSurface({root, sources, topicKeys: topic.keys}),
@@ -1096,7 +1174,7 @@ export async function checkAuthoringDocs(_ctx, options = {}) {
       id,
       label,
       status: 'pass',
-      message: `All ${audit.sections} authoring schemas are readable in \`${formatCliCommand('docs authoring')}\`.`,
+      message: `All ${audit.sections} authoring schemas are readable in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
     };
   } catch (err) {
     return {
@@ -1164,7 +1242,7 @@ export async function checkCliDocs(_ctx, options = {}) {
       id,
       label,
       status: 'pass',
-      message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring')}\`.`,
+      message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
     };
   } catch (err) {
     return {
@@ -1281,7 +1359,7 @@ export async function checkDocsProgressiveDisclosure(ctx) {
     // A guide the docs tree places is a topic read by its route; it is held
     // to the same budget as every flat topic.
     const guides = [...(await projectTree(catalog)).nodes.values()]
-      // A flat topic in the Unorganized level is checked above, as a topic.
+      // A flat topic in a topic level is checked above, as a topic.
       .filter(node => node.kind === 'generic' && !node.ref?.flatTopic)
       .map(guideEntry);
     for (const entry of [...catalog.entries(), ...guides]) {

package/api/doctor/doctor.test.mjs

@@ -652,7 +652,7 @@ describe('checkAuthoringDocs', () => {
   it('passes when every authoring self-doc is reachable and fits one read', async () => {
     const c = await checkAuthoringDocs();
     expect(c).toMatchObject({id: 'authoring-docs', status: 'pass'});
-    expect(c.message).toContain(formatCliCommand('docs authoring'));
+    expect(c.message).toContain(formatCliCommand('docs authoring/field-reference'));
   }, SLOW);
 });
 
@@ -680,7 +680,7 @@ describe('checkCliDocs', () => {
         id: 'cli-docs',
         label: 'CLI docs',
         status: 'pass',
-        message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring')}\`.`,
+        message: `All ${audit.docs} CLI docs are readable: ${audit.tree} in the \`${formatCliCommand('docs cli')}\` tree and ${audit.authoring} in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
       });
     },
     SLOW,
@@ -790,7 +790,7 @@ describe('checkDocsTree', () => {
 describe('checkAuthoringDocs against the public authoring surface', () => {
   const NAMESPACE = 'doctypes/namespace/namespace.doc.mjs';
   const NAMESPACE_TYPES =
-    `NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in \`${formatCliCommand('docs authoring')}\``;
+    `NamespaceDoc, NamespaceProviderScope, NamespaceSlotAcceptance, NamespaceSlot, NamespaceAdoptionSource, NamespaceAdoptionRule from doctypes/namespace/type.ts have no doc in \`${formatCliCommand('docs authoring/field-reference')}\``;
   const SURFACE_FIX =
     'Put a self-doc beside each module whose types @astryxdesign/cli/authoring exports and list it in AUTHORING_SELF_DOCS; export what each listed self-doc documents, or remove that self-doc.';
 
@@ -820,7 +820,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
         id: 'authoring-docs',
         label: 'Authoring docs',
         status: 'pass',
-        message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`${formatCliCommand('docs authoring')}\`.`,
+        message: `All ${AUTHORING_SELF_DOCS.length} authoring schemas are readable in \`${formatCliCommand('docs authoring/field-reference')}\`.`,
       });
     },
     SLOW,
@@ -849,7 +849,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
       });
       expect(c.status).toBe('fail');
       expect(c.message).toBe(
-        `2 problems: ${NAMESPACE} is not in \`${formatCliCommand('docs authoring')}\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
+        `2 problems: ${NAMESPACE} is not in \`${formatCliCommand('docs authoring/field-reference')}\`; ${NAMESPACE_TYPES}: ${NAMESPACE} is not listed in AUTHORING_SELF_DOCS`,
       );
     },
     SLOW,
@@ -858,7 +858,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
   it(
     "fails when the topic's index no longer exposes the NamespaceDoc section",
     async () => {
-      const index = await docs('authoring', undefined, {index: true});
+      const index = await docs('authoring/field-reference', undefined, {index: true});
       const topicKeys = new Set(
         index.data.sections
           .map((/** @type {any} */ s) => s.id)
@@ -947,7 +947,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
       expect(c.fix).toBe(SURFACE_FIX);
       expect(c.message).toMatch(
         new RegExp(
-          `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`${escape(formatCliCommand('docs authoring'))}\`: no self-doc sits beside ${escape(module)}$`,
+          `^[A-Za-z, ]+ from ${escape(module)} have no doc in \`${escape(formatCliCommand('docs authoring/field-reference'))}\`: no self-doc sits beside ${escape(module)}$`,
         ),
       );
       for (const name of names) {
@@ -990,7 +990,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
         expect(await checkAuthoringDocs()).toMatchObject({
           status: 'fail',
           message:
-            `\`${formatCliCommand('docs authoring')}\` could not be read: no built-in docs`,
+            `\`${formatCliCommand('docs authoring/field-reference')}\` could not be read: no built-in docs`,
           fix: SURFACE_FIX,
         });
       } finally {
@@ -1011,7 +1011,7 @@ describe('checkAuthoringDocs against the public authoring surface', () => {
       const c = await checkAuthoringDocs(undefined, {root});
       expect(c.status).toBe('fail');
       expect(c.message).toContain(
-        `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring')}\``,
+        `@astryxdesign/cli/authoring exports no types, so nothing was compared with \`${formatCliCommand('docs authoring/field-reference')}\``,
       );
     },
     SLOW,
@@ -1317,8 +1317,12 @@ describe('a configured integration that cannot load fails the gate', () => {
     'astryx.config.mjs': "export default { integrations: ['@acme/widgets'] };\n",
   };
 
-  /** Run doctor on a project under the working directory. */
-  async function report(files) {
+  /**
+   * Run doctor on a project under the working directory, in its folder `at`.
+   * @param {Record<string, string>} files
+   * @param {string} [at]
+   */
+  async function report(files, at = '.') {
     const dir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-gate-'));
     tmpDirs.push(dir);
     for (const [rel, content] of Object.entries(files)) {
@@ -1326,7 +1330,7 @@ describe('a configured integration that cannot load fails the gate', () => {
       fs.mkdirSync(path.dirname(abs), {recursive: true});
       fs.writeFileSync(abs, content);
     }
-    const {checks, summary} = (await doctor({cwd: dir})).data;
+    const {checks, summary} = (await doctor({cwd: path.join(dir, at)})).data;
     return {by: Object.fromEntries(checks.map(c => [c.id, c])), summary};
   }
 
@@ -1354,6 +1358,27 @@ describe('a configured integration that cannot load fails the gate', () => {
     SLOW,
   );
 
+  it(
+    'passes in a workspace member whose configured integration is hoisted to the root',
+    async () => {
+      const {by} = await report(
+        {
+          'package.json': JSON.stringify({name: 'root', private: true, workspaces: ['apps/*']}),
+          ...CORE_STUB,
+          ...widgets(),
+          'apps/web/package.json': '{"name":"web"}',
+          'apps/web/astryx.config.mjs': "export default { integrations: ['@acme/widgets'] };\n",
+        },
+        'apps/web',
+      );
+      expect(by['configured-integrations'].status).toBe('pass');
+      expect(by['configured-integrations'].message).toBe(
+        '1 integration named in astryx.config loaded: @acme/widgets.',
+      );
+    },
+    SLOW,
+  );
+
   it(
     'counts the package being authored when its own config names it',
     async () => {

package/api/hook/hook.mjs

@@ -43,7 +43,7 @@ export async function hook(name, options = {}) {
     zh = false,
   } = options;
 
-  // Default detail level mirrors the CLI (see commands/hook/index.mjs):
+  // Default detail level mirrors the CLI (see commands/hook.mjs):
   // single-hook views default to 'full', list-style views (--list,
   // --category, or no name) default to 'brief' (scannable name lists).
   // Keeping this in sync with the CLI is what the API↔CLI parity test checks.

package/api/init/init.doc.mjs

@@ -17,11 +17,22 @@ export const doc = {
     'Non-interactive project setup: install agent docs and point at the theme + build workflows.',
   description:
     'Sets a project up with NO prompts, so it behaves identically for humans, ' +
-    'agents, CI, and piped I/O. By default it installs the AGENTS.md/CLAUDE.md ' +
-    'agent-docs cheat sheet, including guidance from configured integrations, and ' +
+    'agents, CI, and piped I/O. By default it writes the agent-docs cheat sheet, ' +
+    'including guidance from configured integrations, at the project root (the nearest ' +
+    'package.json that declares an @astryxdesign package, else the nearest package.json, ' +
+    'searching no higher than the repository root): to AGENTS.md, ' +
+    "to the project's Claude Code file (CLAUDE.md, else .claude/CLAUDE.md; when CLAUDE.md " +
+    'exists, a block 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), and as a ' +
+    'one-line import of AGENTS.md in GEMINI.md unless GEMINI.md already imports it. ' +
+    'In the home folder, or in a settings folder in it outside a project, it writes none: every ' +
+    'folder of the home folder whose name starts with a dot is a settings folder, and such a folder itself never ' +
+    'counts as a project, even with a package.json; a folder below it with a package.json does. ' +
+    'The managed block is Astryx-owned: it is written, refreshed, and removed whatever ignore rules ' +
+    'or generated markers say, and the text around it is never changed. It then ' +
     "prints getting-started guidance; `features` / `all` print only the chosen features' " +
     'guidance instead (the theme feature also writes the annotated theme template). ' +
-    'With `removeAgents` it removes the managed agent-docs block instead of installing. ' +
+    'With `removeAgents` it removes the managed agent-docs block, at the project root and in `ctx.cwd`, instead of installing. ' +
     'Outside a project it writes the same files but prints no getting-started steps and no step that adds a theme to an app, since those set up a project the folder does not have. ' +
         "With `user` it sets up the computer instead of the folder: it writes the computer-level agent text, one skill file at `~/.agents/skills/astryx/SKILL.md`, linked into the skill folders of agents that read only their own (`~/.claude/skills` always; Kiro, Windsurf, Letta, Xcode's coding assistant, and `~/.config/agents/skills` when that folder exists), with a managed copy for Continue, whose scanner skips links,, telling agents anywhere on the computer that Astryx is there and when to use it; with `user` and `removeAgents` it removes the file and the links it made and records that the text is turned off. " +
     'The CLI installed for the computer refreshes the file in the background after each upgrade; package install scripts, project setup, and upgrade never write it.' +
@@ -46,7 +57,7 @@ export const doc = {
       name: 'options.removeAgents',
       type: 'boolean',
       description:
-        'Remove the managed agent-docs block instead of installing. With `user`, remove the computer-level agent text instead.',
+        'Remove the managed agent-docs block, at the project root and in `ctx.cwd`, instead of installing. With `user`, remove the computer-level agent text instead.',
     },
     {
       name: 'options.user',
@@ -62,7 +73,10 @@ export const doc = {
       name: 'options.agent',
       type: 'string',
       description:
-        'Agent preset: claude, cursor, codex, hermes, muse, all. Used only when the agents feature runs. Refused with `user`.',
+        'Agent preset: claude, cursor, codex, hermes, muse, all. `all` writes every existing agent doc except GEMINI.md, ' +
+        'which keeps its one-line import of AGENTS.md. With claude and all, when CLAUDE.md gets the block, a block in ' +
+        '.claude/CLAUDE.md is removed, unless the project ignores CLAUDE.md, in which case a .claude/CLAUDE.md the ' +
+        'project commits gets a copy too. Used only when the agents feature runs. Refused with `user`.',
     },
     {
       name: 'options.agentDocsPath',
@@ -122,7 +136,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file resolves outside cwd through a symlink',
+      when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file in cwd, or at the project root when run there, resolves outside that folder through a symlink (run below the root, a project-root file is left as it is with a note)',
     },
   ],
   examples: [