@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/foundation/agent-docs/agent-docs.mjs

@@ -22,11 +22,12 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {findCoreDir, CLI_ROOT} from '../fs/paths.mjs';
-import {assertWithin} from '../fs/path-safety.mjs';
+import {assertWithin, PathSafetyError} from '../fs/path-safety.mjs';
 import {getCliInvocation} from '../env/package-manager.mjs';
 import {discoverComponents} from '../discovery/component-discovery.mjs';
 import {Project} from '../config/project.mjs';
 import {humanLog} from '../response/json.mjs';
+import {ERROR_CODES} from '../response/error-codes.mjs';
 import {
   AGENTS_MD,
   CLAUDE_MD,
@@ -353,8 +354,9 @@ export function detectStylingSystem(targetDir) {
  * Generate the agent cheat sheet from live CLI metadata.
  *
  * Structured as: workflow (behavioral) → rules (error prevention) → CLI reference.
- * Templates are positioned first in the workflow to teach agents the
- * "look at reference code" reflex before writing any UI.
+ * Templates lead the workflow: every page starts from a scaffolded template,
+ * because the template already carries the frame and spacing that an agent
+ * composing from components would have to re-derive, and usually gets wrong.
  *
  * `stylingSystem` tailors the custom-styling guidance to what the project has
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
@@ -427,17 +429,19 @@ export function generateCompressedIndex(
   lines.push('  import "@astryxdesign/core/astryx.css";');
   lines.push('');
 
-  // Workflow — `build` is the front door; discover before writing UI.
-  lines.push("WORKFLOW — discover, don't guess. Before writing UI:");
-  lines.push('1. `astryx build "<idea>"` — START HERE: returns a kit (closest [page] + [block]s + [component]s). No args = full playbook.');
-  lines.push('2. `astryx template <name> [--skeleton]` — scaffold the [page]/[block]s it named, or study their layout. Templates are reference code.');
-  lines.push('3. `astryx component <Name>` — props + examples for every component you use.');
+  // Workflow — `build` is the front door, and every page starts from the
+  // template it names.
+  lines.push('WORKFLOW — start every page from a template. Never lay out a page from scratch:');
+  lines.push('1. `astryx build "<idea>"` — START HERE: names the [page] template to start from (always one: the closest match, or the app shell), two other templates, and the [block]s + [component]s for parts it lacks. No args = full playbook.');
+  lines.push('2. `astryx template <name> <path>` — scaffold that template into your project. Keep its frame, gap and padding; replace its data, copy and sections; delete sections you do not need.');
+  lines.push('3. `astryx template <Block>` for a part the template lacks; `astryx component <Name>` for props + examples before you use or change a component.');
+  lines.push('Changing a page you already have? Keep it: skip step 2 and add blocks and components inside its sections.');
   lines.push('');
 
   // Rules — the top error-preventers.
   lines.push('RULES:');
   lines.push('- No <div> — components do all layout/spacing, page frame included.');
-  lines.push('- Frame first: read `astryx docs layout` before writing any page or screen — page frame, region widths, breakpoint behavior.');
+  lines.push('- Frame first: the template you scaffold sets the page frame. Read `astryx docs layout` before you change it — region widths, breakpoint behavior.');
   lines.push('- Dense data = rows (Table, List/Item), never Card-wrapped list items; Card is for standalone widgets. Status = StatusDot/Token; Badge = counts only.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
@@ -462,7 +466,7 @@ export function generateCompressedIndex(
     css: 'replace any raw <div>/<span> layout, imported .css/@apply, or hardcoded value (#hex, 16px) with the component or a token (var(--color-*|--spacing-*|…))',
   };
   lines.push(
-    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
+    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. Confirm the page kept its template's frame, gap and padding. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
   );
   lines.push('');
 
@@ -485,6 +489,7 @@ export function generateCompressedIndex(
   if (resolvedTopics.length > 0) {
     lines.push(`  docs <topic>       ${resolvedTopics.join(', ')}`);
   }
+  lines.push('  docs cli           commands, API reference, integration authoring (one level at a time)');
   lines.push('  swizzle <Name>     eject component source for deep customization');
   lines.push('  upgrade --apply    run after any Astryx or integration dependency bump');
   const appendCount = agentDocs.reduce(
@@ -705,12 +710,65 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
   return true;
 }
 
+/**
+ * Whether an agent-doc file already carries a managed-block marker.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function hasManagedMarker(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return content.includes(MARKER_START) || content.includes(LEGACY_MARKER_START);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether `removeXdsBlock` would change `filePath`: it holds one well-formed
+ * managed block.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function hasRemovableBlock(filePath) {
+  try {
+    return findManagedBlock(fs.readFileSync(filePath, 'utf-8')) != null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every file a run writes must resolve inside `targetDir`, symlinks
+ * included. Checked for the whole write set before the first write, so an
+ * escape writes nothing.
+ * @param {string} targetDir
+ * @param {Iterable<string>} relPaths
+ */
+function assertTargetsWithin(targetDir, relPaths) {
+  for (const p of relPaths) {
+    assertWithin(p, targetDir, {label: 'agent docs path'});
+  }
+}
+
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
+ *   resolves outside `targetDir`; nothing is changed.
  */
 export function removeAgentDocs(targetDir) {
   const allPaths = discoverAgentDocs(targetDir);
+  try {
+    assertTargetsWithin(
+      targetDir,
+      allPaths.filter(p => hasRemovableBlock(path.join(targetDir, p))),
+    );
+  } catch (err) {
+    // The code reaches the error envelope as is, so it must be registered.
+    if (!(err instanceof PathSafetyError)) throw err;
+    throw new PathSafetyError(err.message, ERROR_CODES.ERR_PATH_TRAVERSAL);
+  }
 
   for (const p of allPaths) {
     const filePath = path.join(targetDir, p);
@@ -718,9 +776,9 @@ export function removeAgentDocs(targetDir) {
     const deleteIfEmpty = p === AGENTS_MD || p === CLAUDE_DIR_MD;
     if (removeXdsBlock(filePath, {deleteIfEmpty})) {
       if (!fs.existsSync(filePath)) {
-        humanLog(`✓ Removed empty ${p}`);
+        humanLog(`[ok] Removed empty ${p}`);
       } else {
-        humanLog(`✓ Removed design system section from ${p}`);
+        humanLog(`[ok] Removed design system section from ${p}`);
       }
     }
   }
@@ -750,6 +808,8 @@ export function removeAgentDocs(targetDir) {
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
  * @returns {string[]} List of files written
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
+ *   write resolves outside `targetDir`; nothing is written.
  */
 export function installAgentDocs(
   targetDir,
@@ -806,6 +866,7 @@ export function installAgentDocs(
   // Agent preset
   if (agent) {
     const {inject, create} = resolveAgentPaths(targetDir, agent);
+    assertTargetsWithin(targetDir, [...inject, ...create]);
     for (const p of inject) {
       injectXdsBlock(path.join(targetDir, p), compressedIndex);
       written.push(p);
@@ -833,6 +894,14 @@ export function installAgentDocs(
   if (existing.length > 0) {
     const wrappers = discoverAgentDocWrappers(targetDir, existing);
     const targets = existing.filter(p => !wrappers.has(p));
+    // A refresh skips unmarked files and a wrapper is only written when it
+    // carries a block, so only the files this run writes are checked.
+    /** @param {string} p */
+    const marked = p => hasManagedMarker(path.join(targetDir, p));
+    assertTargetsWithin(targetDir, [
+      ...targets.filter(p => !onlyReplace || marked(p)),
+      ...[...wrappers].filter(marked),
+    ]);
 
     for (const p of targets) {
       const didWrite = injectXdsBlock(path.join(targetDir, p), compressedIndex, {onlyReplace});
@@ -860,6 +929,7 @@ export function installAgentDocs(
   if (onlyReplace) return written;
 
   const defaultPath = AGENTS_MD;
+  assertTargetsWithin(targetDir, [defaultPath]);
   injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
     createIfMissing: true,
     header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,

package/foundation/agent-docs/agent-docs.path-safety.test.mjs

@@ -1,22 +1,31 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Path-safety regression tests for `--agent-docs-path`.
+ * @file Path-safety regression tests for agent-doc writes.
  *
  * `installAgentDocs(targetDir, {paths})` previously joined each path
  * onto `targetDir` with no validation, so:
  *   - `../OUT.md` wrote outside `targetDir`
  *   - `/tmp/x.md` was silently re-rooted under `targetDir`
  *
- * Both cases now throw PathSafetyError before any file is touched.
+ * Auto-detected and preset files were never checked at all, so a `CLAUDE.md`
+ * or `.claude/` symlinked out of the project had the block written through
+ * it. Every case now throws PathSafetyError before any file is touched.
+ *
+ * `removeAgentDocs` (`init --remove-agents`) stripped or deleted a block
+ * through the same kind of link and reported success. It now refuses with
+ * `ERR_PATH_TRAVERSAL` before any file is touched.
  */
 
-import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {installAgentDocs} from './agent-docs.mjs';
+import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';
 import {PathSafetyError} from '../fs/path-safety.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+const BLOCK = '<!-- ASTRYX:START -->\nmanaged\n<!-- ASTRYX:END -->';
 
 let tmpDir;
 beforeEach(() => {
@@ -26,6 +35,28 @@ afterEach(() => {
   fs.rmSync(tmpDir, {recursive: true, force: true});
 });
 
+/** A project dir plus a sibling dir outside it. */
+function layout() {
+  const project = path.join(tmpDir, 'project');
+  const outside = path.join(tmpDir, 'outside');
+  fs.mkdirSync(project, {recursive: true});
+  fs.mkdirSync(outside, {recursive: true});
+  return {project, outside};
+}
+
+/**
+ * @param {() => unknown} fn
+ * @returns {unknown} what `fn` threw
+ */
+function thrownBy(fn) {
+  try {
+    fn();
+  } catch (err) {
+    return err;
+  }
+  throw new Error('expected a throw');
+}
+
 describe('installAgentDocs path safety', () => {
   it('rejects --agent-docs-path that escapes the target directory', () => {
     const target = path.join(tmpDir, 'project');
@@ -64,3 +95,234 @@ describe('installAgentDocs path safety', () => {
     expect(fs.existsSync(path.join(tmpDir, 'escaped.md'))).toBe(false);
   });
 });
+
+describe('installAgentDocs never writes through a symlink out of the project', () => {
+  it('refuses an auto-detected file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      /outside the project root/,
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  });
+
+  it('refuses a preset file reached through a symlinked directory', () => {
+    const {project, outside} = layout();
+    fs.symlinkSync(outside, path.join(project, '.claude'));
+
+    expect(() =>
+      installAgentDocs(project, {agent: 'claude', renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readdirSync(outside)).toEqual([]);
+  });
+
+  it('refuses an existing preset file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    expect(() =>
+      installAgentDocs(project, {agent: 'cursor', renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('writes nothing when any file of the set escapes', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      PathSafetyError,
+    );
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  });
+
+  it('refuses to refresh a managed block that lives outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK.replace('managed', 'old')}\n`);
+    const before = fs.readFileSync(shared, 'utf-8');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() =>
+      installAgentDocs(project, {onlyReplace: true, renderedBlock: BLOCK}),
+    ).toThrow(PathSafetyError);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(before);
+  });
+
+  it('refuses to strip a duplicate block from a wrapper that links outside', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\n${BLOCK}\n`);
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `@AGENTS.md\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(() => installAgentDocs(project, {renderedBlock: BLOCK})).toThrow(
+      PathSafetyError,
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`@AGENTS.md\n\n${BLOCK}\n`);
+  });
+
+  it('still refreshes in-project blocks beside an unmarked outside link it skips', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(
+      path.join(project, 'AGENTS.md'),
+      `# Agents\n\n${BLOCK.replace('managed', 'old')}\n`,
+    );
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    expect(
+      installAgentDocs(project, {onlyReplace: true, renderedBlock: BLOCK}),
+    ).toEqual(['AGENTS.md']);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toContain(
+      'managed',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('writes through a symlink that stays inside the project', () => {
+    const {project} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), '# Agents\n');
+    fs.symlinkSync('AGENTS.md', path.join(project, 'CLAUDE.md'));
+
+    expect(installAgentDocs(project, {renderedBlock: BLOCK})).toEqual([
+      'AGENTS.md',
+      'CLAUDE.md',
+    ]);
+    const content = fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8');
+    expect(content.split('<!-- ASTRYX:START -->')).toHaveLength(2);
+  });
+});
+
+describe('init --features agents with an agent doc linked outside the project', () => {
+  it('writes nothing outside, reports path-safety, and exits 1 in both modes', async () => {
+    const project = path.join(tmpDir, 'project');
+    const outside = path.join(tmpDir, 'outside');
+    fs.mkdirSync(project, {recursive: true});
+    fs.mkdirSync(outside, {recursive: true});
+    fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, '# Shared\n');
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const json = await runCli(['init', '--features', 'agents', '--json'], project);
+    expect(json.status).toBe(1);
+    const env = JSON.parse(json.stdout);
+    expect(env.type).toBe('init.run');
+    expect(env.data.docsError).toMatchObject({kind: 'path-safety'});
+
+    const text = await runCli(['init', '--features', 'agents'], project);
+    expect(text.status).toBe(1);
+
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('# Shared\n');
+  }, 30_000);
+});
+
+describe('removeAgentDocs never changes a file out of the project', () => {
+  beforeEach(() => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('refuses to strip a block from a file that links outside', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const err = thrownBy(() => removeAgentDocs(project));
+    expect(err).toBeInstanceOf(PathSafetyError);
+    expect(err).toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`# Shared\n\n${BLOCK}\n`);
+  });
+
+  it('refuses to delete a file reached through a symlinked directory', () => {
+    const {project, outside} = layout();
+    const shared = path.join(outside, 'CLAUDE.md');
+    const content = `# CLAUDE\n\nProject-specific guidance for AI coding agents.\n\n${BLOCK}\n`;
+    fs.writeFileSync(shared, content);
+    fs.symlinkSync(outside, path.join(project, '.claude'));
+
+    expect(thrownBy(() => removeAgentDocs(project))).toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(content);
+  });
+
+  it('changes nothing when any file of the set escapes', () => {
+    const {project, outside} = layout();
+    const agents = `# Agents\n\nkeep\n\n${BLOCK}\n`;
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), agents);
+    const shared = path.join(outside, 'CLAUDE.md');
+    fs.writeFileSync(shared, `# Shared\n\n${BLOCK}\n`);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    expect(thrownBy(() => removeAgentDocs(project))).toBeInstanceOf(PathSafetyError);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(agents);
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(`# Shared\n\n${BLOCK}\n`);
+  });
+
+  it('still strips in-project blocks beside an unmarked outside link it skips', () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\nkeep\n\n${BLOCK}\n`);
+    const shared = path.join(outside, 'rules');
+    fs.writeFileSync(shared, 'rules\n');
+    fs.symlinkSync(shared, path.join(project, '.cursorrules'));
+
+    removeAgentDocs(project);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n\nkeep\n',
+    );
+    expect(fs.readFileSync(shared, 'utf-8')).toBe('rules\n');
+  });
+
+  it('strips through a symlink that stays inside the project', () => {
+    const {project} = layout();
+    fs.writeFileSync(path.join(project, 'AGENTS.md'), `# Agents\n\nkeep\n\n${BLOCK}\n`);
+    fs.symlinkSync('AGENTS.md', path.join(project, 'CLAUDE.md'));
+
+    removeAgentDocs(project);
+    expect(fs.readFileSync(path.join(project, 'AGENTS.md'), 'utf-8')).toBe(
+      '# Agents\n\nkeep\n',
+    );
+  });
+});
+
+describe('init --remove-agents with an agent doc linked outside the project', () => {
+  it('changes nothing outside, fails with ERR_PATH_TRAVERSAL, and exits 1 in both modes', async () => {
+    const {project, outside} = layout();
+    fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app"}\n');
+    const shared = path.join(outside, 'CLAUDE.md');
+    const content = `# Shared\n\n${BLOCK}\n`;
+    fs.writeFileSync(shared, content);
+    fs.symlinkSync(shared, path.join(project, 'CLAUDE.md'));
+
+    const json = await runCli(['init', '--remove-agents', '--json'], project);
+    expect(json.status).toBe(1);
+    const env = JSON.parse(json.stdout);
+    expect(env).toMatchObject({apiVersion: 1, code: 'ERR_PATH_TRAVERSAL'});
+    expect(env.error).toMatch(/"CLAUDE\.md": resolves outside the project root/);
+    expect(env).not.toHaveProperty('data');
+
+    const text = await runCli(['init', '--remove-agents'], project);
+    expect(text.status).toBe(1);
+    expect(text.stderr).toMatch(/^Error: .*"CLAUDE\.md": resolves outside the project root/m);
+    expect(text.stdout).not.toMatch(/removed/i);
+
+    expect(fs.readFileSync(shared, 'utf-8')).toBe(content);
+  }, 30_000);
+});

package/foundation/agent-docs/agent-docs.test.mjs

@@ -55,6 +55,15 @@ describe('generateCompressedIndex', () => {
     expect(frameRule).not.toMatch(/https?:/);
   });
 
+  it('starts every page from a template before any component', () => {
+    const lines = generateCompressedIndex('1.0.0').split('\n');
+    const workflow = lines.findIndex(l => l.startsWith('WORKFLOW'));
+    expect(lines[workflow]).toMatch(/start every page from a template/);
+    expect(lines[workflow + 1]).toMatch(/^1\. `astryx build /);
+    expect(lines[workflow + 2]).toMatch(/^2\. `astryx template <name> <path>`/);
+    expect(lines.join('\n')).not.toMatch(/reference code/);
+  });
+
   it('includes the post-generation self-check rule', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toContain('SELF-CHECK before you finish');
@@ -134,7 +143,6 @@ describe('generateCompressedIndex', () => {
     const line = topicLine(generateCompressedIndex('1.0.0'));
     for (const topic of [
       'getting-started',
-      'cli-integrations',
       'browser-support',
       'styling-libraries',
       'working-with-ai',
@@ -143,6 +151,16 @@ describe('generateCompressedIndex', () => {
     }
   });
 
+  it('points to the CLI docs tree on a line of its own', () => {
+    // The integration guide lives in the docs tree now (cli/integrations), so
+    // the topic line no longer names it; the tree's entry point does.
+    const block = generateCompressedIndex('1.0.0');
+    expect(block).toContain(
+      '  docs cli           commands, API reference, integration authoring (one level at a time)',
+    );
+    expect(topicLine(block)).not.toContain('cli-integrations');
+  });
+
   it('lists the topics it is given, so an integration’s reach the agent', () => {
     const line = topicLine(
       generateCompressedIndex('1.0.0', {topics: ['tokens', 'deploying']}),

package/foundation/config/integration-debug.test.mjs

@@ -63,11 +63,18 @@ function config(integrations, ownHandler = false) {
   );
 }
 
-/** @param {Record<string, unknown>} [astryx] */
-function packageJson(astryx) {
+/**
+ * @param {Record<string, unknown>} [astryx]
+ * @param {Record<string, string>} [dependencies]
+ */
+function packageJson(astryx, dependencies) {
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
-    JSON.stringify({name: 'consumer', ...(astryx ? {astryx} : {})}),
+    JSON.stringify({
+      name: 'consumer',
+      ...(dependencies ? {dependencies} : {}),
+      ...(astryx ? {astryx} : {}),
+    }),
   );
 }
 
@@ -172,6 +179,24 @@ describe('an app can refuse an inherited handler', () => {
 
     expect(fired()).toEqual(['reporting-integration']);
   });
+
+  it('keeps an autolinked handler in a project with no astryx.config', async () => {
+    packageJson(undefined, {'reporting-integration': '1.0.0'});
+    integration('reporting-integration');
+
+    await runOneCommand();
+
+    expect(fired()).toEqual(['reporting-integration']);
+  });
+
+  it('drops an autolinked handler under astryx.inheritDebug false with no astryx.config', async () => {
+    packageJson({inheritDebug: false}, {'reporting-integration': '1.0.0'});
+    integration('reporting-integration');
+
+    await runOneCommand();
+
+    expect(fired()).toEqual([]);
+  });
 });
 
 describe('loading the project twice delivers once', () => {

package/foundation/config/project-themes.test.mjs

@@ -15,6 +15,7 @@ function installThemeIntegration(packageName, slug) {
     ...packageName.split('/'),
   );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -22,28 +23,19 @@ function installThemeIntegration(packageName, slug) {
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: 'Ocean',
-          description: 'Blue and calm.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: 'Ocean', description: 'Blue and calm.', maintained: true};
+`,
   );
   fs.writeFileSync(
-    path.join(themeDir, 'oceanTheme.ts'),
-    `export const oceanTheme = {};\n`,
+    path.join(themeDir, `${stem}.ts`),
+    `export const ${stem} = {};
+`,
   );
 }
 
@@ -99,7 +91,7 @@ describe('Project themes', () => {
     ]);
   });
 
-  it('records an invalid integration theme catalog as an issue', async () => {
+  it('records an invalid integration theme descriptor as an issue', async () => {
     installThemeIntegration('@acme/themes', 'ocean');
     fs.rmSync(
       path.join(