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

package/clients/cli/index.mjs

@@ -26,13 +26,17 @@ import {projectRootOf} from '../../foundation/release/choose.mjs';
 import {readReleaseFacts} from '../../foundation/release/project.mjs';
 import {buildManifest} from './lib/manifest.mjs';
 import {cliError} from './lib/cli-error.mjs';
-import {emit, section, text, records} from './formatters/index.mjs';
+import {section, text, records} from './formatters/index.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
-import {addDocHelp, markReportsResult} from './lib/define-command.mjs';
-import {doc as manifestDoc} from './commands/manifest.doc.mjs';
-import {isAstryxInitialized, isAstryxPromptInReach} from '../../foundation/agent-docs/agent-docs.mjs';
+import {markReportsResult} from './lib/define-command.mjs';
+import {
+  agentDocsTargetDir,
+  assertAgentDocsTarget,
+  isAstryxInitialized,
+  isAstryxPromptInReach,
+} from '../../foundation/agent-docs/agent-docs.mjs';
 import {CLI_ROOT} from '../../foundation/fs/paths.mjs';
 import {setupNudge} from '../../foundation/agent-docs/agent-doc-state.mjs';
 import * as debug from '../../foundation/debug/index.mjs';
@@ -292,7 +296,7 @@ function captureInvocation(actionCommand, root) {
  */
 const commands = [
   {name: 'init', path: './commands/init.mjs', register: 'registerInit'},
-  {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
+  {name: 'component', path: './commands/component.mjs', register: 'registerComponent'},
   {name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
   {name: 'blog', path: './commands/blog.mjs', register: 'registerBlog'},
   {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
@@ -300,13 +304,17 @@ const commands = [
   // agent-docs folded into init — functions still importable from agent-docs.mjs
   {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
   {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
-  {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},
+  {name: 'theme', path: './commands/theme.mjs', register: 'registerTheme'},
   {name: 'integration', path: './commands/integration.mjs', register: 'registerIntegration'},
-  {name: 'hook', path: './commands/hook/index.mjs', register: 'registerHook'},
+  {name: 'hook', path: './commands/hook.mjs', register: 'registerHook'},
   {name: 'discover', path: './commands/discover.mjs', register: 'registerDiscover'},
   {name: 'search', path: './commands/search.mjs', register: 'registerSearch'},
   {name: 'build', path: './commands/build.mjs', register: 'registerBuild'},
   {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
+  // Registered after every other command: the manifest lists the commands in
+  // registration order.
+  {name: 'manifest', path: './commands/manifest.mjs', register: 'registerManifest'},
+  {name: 'postinstall', path: './commands/postinstall.mjs', register: 'registerPostinstall'},
 ];
 
 const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
@@ -635,6 +643,19 @@ export async function createProgram() {
       if (INTEGRATION_MANIFEST_FILES.some(file => fs.existsSync(path.join(cwd, file)))) return;
       if (inOwnSourceCheckout(cwd)) return; // developing Astryx itself, not an app
       if (isAstryxPromptInReach(cwd)) return; // already set up — stay quiet
+      // Where init writes the docs, by init's own rule: the project root, which
+      // can sit above a nested package such as functions/. Inside a git
+      // repository the walk above already reaches it (the root never lies
+      // above the repository root), so this changes nothing there; outside a
+      // repository the walk checks only cwd, and this finds the root.
+      if (isAstryxInitialized(agentDocsTargetDir(cwd))) return;
+      // In the home folder, or at the top of a settings folder in it, init
+      // writes no agent docs, so naming it would repeat on every command.
+      try {
+        assertAgentDocsTarget(agentDocsTargetDir(cwd));
+      } catch {
+        return;
+      }
       // Same wording as the core/cli postinstall nudges. getCliInvocation()
       // renders the correct form for THIS project — an integration's cliCommand,
       // scoped `npx @astryxdesign/cli` one-off, or `<pm> astryx` when installed —
@@ -659,7 +680,7 @@ export async function createProgram() {
   for (const cmd of commands) {
     try {
       const mod = await import(cmd.path);
-      mod[cmd.register](program);
+      mod[cmd.register](program, {jsonSupported: JSON_SUPPORTED, version: pkg.version});
     } catch (e) {
       // Command fails to load but CLI still works
       const reason = /** @type {any} */ (e).message;
@@ -679,84 +700,6 @@ export async function createProgram() {
     }
   }
 
-  // Capability manifest — a single, self-describing view of the whole CLI so
-  // agents can discover every command, argument, flag, and response type without
-  // scraping `--help`. `astryx manifest --json` is the dedicated surface; the bare
-  // `xds --json` embeds the same payload under data.manifest for convenience.
-  // Intentionally CLI-special — no `api/manifest`. It introspects the live
-  // Commander `program`, so extracting it to `api/` would create the `api → cli`
-  // cycle from #4302. `buildManifest(program)` lives in lib/; see its header.
-  const manifestCommand = program
-    .command('manifest')
-    .description('Print the full CLI capability manifest (use with --json)')
-    .action(() => {
-      const manifest = buildManifest(program, {
-        jsonSupported: JSON_SUPPORTED,
-        version: pkg.version,
-      });
-      // The manifest IS a result set: one entry per command the CLI ships.
-      debug.recordCommandResult(
-        debug.resultSet({
-          count: manifest.commands.length,
-          resultKind: 'command',
-        }),
-      );
-      if (program.opts().json) {
-        process.__xdsJsonHandled = true;
-        console.log(JSON.stringify({apiVersion: API_VERSION, type: 'manifest', data: manifest, meta: {answeredBy: answeredBy()}}, null, 2));
-        return;
-      }
-      // Human-readable summary as greppable records (agents should use --json).
-      // One record per command: name, whether it supports --json, and the
-      // description. Field names are the manifest entry's own keys.
-      emit(
-        section(`${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`),
-        records(
-          manifest.commands.map(c => ({
-            name: c.name,
-            json: c.json ? 'yes' : '',
-            description: c.description || '',
-          })),
-          {fields: ['name', 'json', 'description']},
-        ),
-        text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
-      );
-    });
-  addDocHelp(manifestCommand, manifestDoc);
-  markReportsResult(manifestCommand);
-
-  // Hidden command used by package.json postinstall scripts
-  const postinstallCommand = program
-    .command('postinstall', {hidden: true})
-    .action(() => {
-      // Prints the welcome box. Nothing is looked up.
-      debug.recordCommandResult(debug.NO_RESULT_SET);
-      const r = getCliInvocation();
-      const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));
-      const W = 49; // inner width of the box
-      const line = (/** @type {string} */ s) => `  │ ${pad(s, W)}│`;
-      console.log(`
-  ╭${'─'.repeat(W + 2)}╮
-${line('')}
-${line('  Design system installed!')}
-${line('')}
-${line('  Get started:')}
-${line(`    ${r} init          Setup + AI agent docs`)}
-${line(`    ${r} --help        See all commands`)}
-${line('')}
-${line('  Or run directly:')}
-${line(`    ${r} init           Setup + AI agent docs`)}
-${line(`    ${r} component     Browse component docs`)}
-${line(`    ${r} hook          Browse hook docs`)}
-${line(`    ${r} docs          Design system reference`)}
-${line(`    ${r} swizzle       Customize a component`)}
-${line(`    ${r} template      Add a page template`)}
-${line('')}
-  ╰${'─'.repeat(W + 2)}╯
-`);
-    });
-  markReportsResult(postinstallCommand);
-
   // Install the JSON shim AFTER all commands are registered so we can
   // patch outputHelp on every command (root + subcommands). The shim
   // extends the --json contract to cover Commander's parse-time short

package/clients/cli/lib/component-format.mjs

@@ -21,7 +21,7 @@ import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
  * (→ `.astryx-table-cell`), and `astryx-button` → key `button`.
  *
  * Keep the `astryx-` literal in sync with packages/core/src/naming.ts
- * (NAMESPACE / classPrefix), the same way build-theme.mjs mirrors it.
+ * (NAMESPACE / classPrefix), the same way commands/theme.mjs mirrors it.
  * <!-- SYNC: packages/core/src/naming.ts (namespace prefix source of truth) -->
  * @param {import('@astryxdesign/cli/authoring').ComponentThemingTarget} target
  * @returns {string}

package/clients/cli/lib/define-command.mjs

@@ -63,10 +63,10 @@ export function reportsResultVia(cmd) {
 /**
  * Mark a hand-registered command as reporting its result.
  *
- * For the handful of commands that cannot come from a CommandDoc — the root
- * program, `manifest` (it introspects the live program, so it cannot be
- * declared by one), `postinstall`, and the stub left behind when a command
- * module fails to load. They call {@link recordCommandResult} themselves; this
+ * For what does not come from a CommandDoc: the root program, and the stub
+ * left behind when a command module fails to load. Every command, `manifest`
+ * and the hidden `postinstall` hook included, registers through
+ * {@link defineCommand}. These call {@link recordCommandResult} themselves; this
  * says so, and the coverage test pins the set of commands allowed to, so the
  * mark cannot become a quiet way around the contract.
  *
@@ -105,10 +105,12 @@ export function commandDocsOf(cmd) {
  *   fn?: import('@astryxdesign/cli/authoring').FunctionDoc,
  *   action?: (...args: any[]) => import('../../../foundation/debug/command-result.mjs').CommandResult
  *     | Promise<import('../../../foundation/debug/command-result.mjs').CommandResult>,
- * }} [impl]
+ *   hidden?: boolean,
+ * }} [impl] `hidden` keeps the command out of help and the manifest (a
+ *   package-script hook, not a command for people or agents).
  * @returns {import('commander').Command} the created command.
  */
-export function defineCommand(parent, doc, {fn, action} = {}) {
+export function defineCommand(parent, doc, {fn, action, hidden} = {}) {
   // The command token is the last path segment ("theme build" -> "build"),
   // since subcommands are added to their group command, not the program.
   const token = doc.name.split(' ').pop() ?? doc.name;
@@ -119,7 +121,10 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
     })
     .join(' ');
 
-  const cmd = parent.command(argSpec ? `${token} ${argSpec}` : token);
+  const cmd = parent.command(
+    argSpec ? `${token} ${argSpec}` : token,
+    hidden ? {hidden: true} : {},
+  );
   Object.defineProperty(cmd, COMMAND_DOCS, {value: {doc, fn}, configurable: true});
   if (doc.summary) cmd.description(doc.summary);
   if (doc.deprecated) {

package/clients/cli/lib/exit-codes.test.mjs

@@ -24,6 +24,10 @@ for (const file of fs.readdirSync(COMMANDS).sort()) {
 }
 
 const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
+/** Hidden commands (a package-script hook): documented, never in the manifest. */
+const HIDDEN = new Set(
+  program.commands.filter((c) => /** @type {any} */ (c)._hidden).map((c) => c.name()),
+);
 /** @type {Map<string, any>} */
 const entries = new Map();
 const walk = (/** @type {any} */ c) => {
@@ -98,6 +102,7 @@ describe('command exit codes', () => {
 
   it('the manifest carries every command exit code', () => {
     for (const doc of commandDocs) {
+      if (HIDDEN.has(doc.name)) continue;
       expect(entries.get(doc.name)?.exitCodes, doc.name).toEqual(
         doc.exitCodes.map(({code, when}) => ({code, when})),
       );

package/clients/cli/lib/manifest.test.mjs

@@ -55,6 +55,10 @@ const CLI_LAYER_TYPES = {
 };
 
 const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
+/** Hidden commands (a package-script hook): documented, never in the manifest. */
+const HIDDEN = new Set(
+  program.commands.filter((c) => /** @type {any} */ (c)._hidden).map((c) => c.name()),
+);
 
 /** Flatten the manifest command tree into fully-qualified names. */
 function flatten(cmds, out = []) {
@@ -116,12 +120,19 @@ describe('manifest: drift guards', () => {
 
   it('takes every command example from its CommandDoc', () => {
     for (const [name, doc] of commandDocs) {
+      if (HIDDEN.has(name)) continue;
       const entry = allEntries.find((c) => c.name === name);
       expect(entry, `CommandDoc "${name}" has no manifest entry`).toBeDefined();
       expect(entry.examples ?? [], name).toEqual((doc.examples ?? []).map((e) => e.cli));
     }
   });
 
+  it('documents the hidden postinstall hook and keeps it out of the manifest', () => {
+    expect([...HIDDEN]).toEqual(['postinstall']);
+    expect(commandDocs.has('postinstall')).toBe(true);
+    expect(allNames.has('postinstall')).toBe(false);
+  });
+
   it('lists every response type the wrapped API function returns', () => {
     for (const [name, doc] of commandDocs) {
       if (!doc.fn) continue;
@@ -152,6 +163,7 @@ describe('manifest: drift guards', () => {
 
   it('takes response types from the wrapped FunctionDoc, plus CLI-layer envelopes', () => {
     for (const [name, doc] of commandDocs) {
+      if (HIDDEN.has(name)) continue;
       const entry = allEntries.find((c) => c.name === name);
       const returns = doc.fn ? functionDocs.get(doc.fn).returns.map((r) => r.type) : [];
       const expected = [...returns, ...(CLI_LAYER_TYPES[name] ?? [])];

package/clients/cli/lib/welcome-box.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The welcome box `astryx postinstall` prints after the package installs.
+ *
+ * A fixed banner, not tabular output, so it is drawn here rather than with the
+ * formatter kit; the command prints it verbatim through `emit(code(...))`.
+ * @input The CLI invocation for this project (e.g. `pnpm exec astryx`).
+ * @output {@link welcomeBox}
+ * @position clients/cli/lib — presentation helper for commands/postinstall.mjs
+ */
+
+/** Inner width of the box. */
+const W = 49;
+
+/**
+ * @param {string} s
+ * @param {number} len
+ */
+const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
+
+/** @param {string} s */
+const line = s => `  │ ${pad(s, W)}│`;
+
+/**
+ * The welcome box, with a blank line before and after it.
+ * @param {string} r the CLI invocation, e.g. `pnpm exec astryx`
+ * @returns {string}
+ */
+export function welcomeBox(r) {
+  return `
+  ╭${'─'.repeat(W + 2)}╮
+${line('')}
+${line('  Design system installed!')}
+${line('')}
+${line('  Get started:')}
+${line(`    ${r} init          Setup + AI agent docs`)}
+${line(`    ${r} --help        See all commands`)}
+${line('')}
+${line('  Or run directly:')}
+${line(`    ${r} init           Setup + AI agent docs`)}
+${line(`    ${r} component     Browse component docs`)}
+${line(`    ${r} hook          Browse hook docs`)}
+${line(`    ${r} docs          Design system reference`)}
+${line(`    ${r} swizzle       Customize a component`)}
+${line(`    ${r} template      Add a page template`)}
+${line('')}
+  ╰${'─'.repeat(W + 2)}╯
+`;
+}

package/clients/cli/run.mjs

@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file One run of the CLI, after the Node version gate: choose who answers
+ * the folder, hand the run off when that is another release (spec AST-081
+ * FR2, FR9), then dispatch the command.
+ *
+ * @input The arguments after `astryx`, read from `process.argv`; the CLI
+ *   package root; and, for a run a programmatic host started, the reason the
+ *   host declined the project's own CLI.
+ * @output The command's effects. The run owns the process: its exit status is
+ *   `process.exitCode`, unless a hand-off or a failure exits the process.
+ * @position clients/cli — called by `bin/astryx.mjs` and by the host entry
+ *   (`host/index.mjs`).
+ */
+
+/**
+ * Run the CLI once in this process.
+ *
+ * Every import here is dynamic: modules that load `styleText` must load only
+ * after the bin's Node version gate, and the release choice must run before
+ * the command modules load, so a run handed to another release loads none of
+ * them.
+ *
+ * @param {{cliRoot: string, argv: string[], declinedProjectCli?: string}} input
+ * @returns {Promise<import('../../host/index.js').HostedCliResult | undefined>}
+ *   resolves when the command has finished; with another release's result
+ *   when, in a hosted run, that release's host entry answered
+ */
+export async function runCli({cliRoot, argv, declinedProjectCli}) {
+  const {startRun} = await import('../../foundation/release/handoff.mjs');
+  const answered = await startRun({cliRoot, argv, declinedProjectCli});
+  if (answered) return answered;
+
+  const {
+    program,
+    loadProjectDebugHandler,
+    loadProjectForHelp,
+    handleVersionJsonPreflight,
+  } = await import('./index.mjs');
+  const {isJsonMode, toErrorEnvelope} =
+    await import('../../foundation/response/json.mjs');
+  const {handleCommanderError} = await import('./lib/json-shim.mjs');
+  const {setOutcome} = await import('../../foundation/debug/index.mjs');
+
+  /**
+   * Top-level error boundary (contract guarantee #4): an uncaught throw must
+   * never reach a --json consumer as a raw stack trace. If we're in JSON mode,
+   * convert it to the contract's error envelope on stdout and exit 1;
+   * otherwise preserve the normal human-facing behavior.
+   *
+   * We detect JSON mode two ways: the global flag (set once root options are
+   * parsed) and a raw argv check, since a throw can occur during
+   * parsing/command load — before the preAction hook engages the flag.
+   */
+  function inJsonMode() {
+    return isJsonMode() || process.argv.slice(2).includes('--json');
+  }
+
+  /** @param {unknown} err */
+  function handleFatal(err) {
+    // CommanderError (parse errors, --help, unknown command) routes
+    // through the JSON shim so that a --json consumer always gets a
+    // valid envelope and the right exit code. handleCommanderError
+    // calls process.exit when it owns the error.
+    if (handleCommanderError(err)) return;
+
+    // Anything still here is an uncaught throw or an unhandled rejection —
+    // a bug rather than a user error, and the class of failure most worth
+    // having a record of.
+    setOutcome('fatal', {exitCode: 1, error: err});
+
+    if (inJsonMode()) {
+      // Only emit if a command didn't already produce an envelope.
+      if (!process.__xdsJsonHandled) {
+        process.__xdsJsonHandled = true;
+        console.log(JSON.stringify(toErrorEnvelope(err), null, 2));
+      }
+      process.exit(1);
+    }
+    // Human mode: preserve Commander/Node default-ish behavior.
+    console.error(
+      err instanceof Error ? err.stack || err.message : String(err),
+    );
+    process.exit(1);
+  }
+
+  process.on('unhandledRejection', handleFatal);
+  process.on('uncaughtException', handleFatal);
+
+  // Pick up the project's `debug` function before parsing, so parse errors
+  // and `--help` — which short-circuit before any hook runs — are reported
+  // too.
+  await loadProjectDebugHandler();
+  // Help prints its commands while Commander parses, so a help run reads the
+  // project's declared `cliCommand` here.
+  await loadProjectForHelp();
+
+  // `--version --json` answers and exits without Commander, so it runs here —
+  // after the handler exists, or the run would go unrecorded.
+  handleVersionJsonPreflight();
+
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    handleFatal(err);
+  }
+}

package/foundation/agent-docs/agent-doc-state.d.mts

@@ -4,15 +4,25 @@
 /**
  * Find all existing agent doc files in a directory, across EVERY location any
  * preset can write (see {@link AGENT_DOC_PATHS}: AGENTS.md, CLAUDE.md,
- * .claude/CLAUDE.md, .cursorrules, .hermes.md, HERMES.md).
+ * .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md, HERMES.md).
  * @param {string} targetDir
  * @returns {string[]} Relative paths of existing agent doc files
  */
 export function discoverAgentDocs(targetDir: string): string[];
+/**
+ * Whether `content` holds an Astryx block. A managed block that only imports
+ * another file (the one-line `@./AGENTS.md` that init writes to GEMINI.md) does
+ * not count: it holds nothing once that file has lost its block. A malformed
+ * block still counts, so a half-written file reads as set up.
+ *
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function holdsAstryxBlock(content: string): boolean;
 /**
  * Single source of truth for "is Astryx set up in this project?" — true when any
- * agent-doc file already carries the Astryx marker, i.e. `init` / `agent-docs`
- * has run. Reused by the init & upgrade commands, the per-command setup nudge
+ * agent-doc file already holds an Astryx block, i.e. `init` / `agent-docs` has
+ * run. Reused by the init & upgrade commands, the per-command setup nudge
  * (enforcement layer 3), and the cli postinstall nudge (layer 2). Core's
  * postinstall (separate package, layer 1) mirrors the same marker contract.
  *
@@ -68,6 +78,7 @@ export function shouldNudge({ scriptPath, npmCommand, isSetUp }?: {
 export const AGENTS_MD: "AGENTS.md";
 export const CLAUDE_MD: "CLAUDE.md";
 export const CLAUDE_DIR_MD: ".claude/CLAUDE.md";
+export const GEMINI_MD: "GEMINI.md";
 export const CURSOR_RULES: ".cursorrules";
 export const HERMES_DOT_MD: ".hermes.md";
 export const HERMES_MD: "HERMES.md";
@@ -77,10 +88,12 @@ export const LEGACY_MARKER_START: "<!-- XDS:START -->";
 export const LEGACY_MARKER_END: "<!-- XDS:END -->";
 /**
  * The canonical set of EVERY location an --agent preset (or the default) can
- * write the Astryx block. SINGLE SOURCE OF TRUTH: discovery, removal, and the
- * `isAstryxInitialized` predicate all derive from this list, so "where init
- * writes" and "where we look" can never drift. (Explicit --agent-docs-path
- * targets are user-chosen and not enumerable here.)
+ * write a managed Astryx block — the full block, or the one-line import of
+ * AGENTS.md that the default writes to GEMINI.md. SINGLE
+ * SOURCE OF TRUTH: discovery, removal, and the `isAstryxInitialized` predicate
+ * all derive from this list, so "where init writes" and "where we look" can
+ * never drift. (Explicit --agent-docs-path targets are user-chosen and not
+ * enumerable here.)
  */
 export const AGENT_DOC_PATHS: string[];
 /**

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

@@ -29,6 +29,7 @@ import * as path from 'node:path';
 export const AGENTS_MD = 'AGENTS.md';
 export const CLAUDE_MD = 'CLAUDE.md';
 export const CLAUDE_DIR_MD = '.claude/CLAUDE.md'; // cross-platform literal
+export const GEMINI_MD = 'GEMINI.md';
 export const CURSOR_RULES = '.cursorrules';
 export const HERMES_DOT_MD = '.hermes.md';
 export const HERMES_MD = 'HERMES.md';
@@ -41,15 +42,18 @@ export const LEGACY_MARKER_END = '<!-- XDS:END -->';
 
 /**
  * The canonical set of EVERY location an --agent preset (or the default) can
- * write the Astryx block. SINGLE SOURCE OF TRUTH: discovery, removal, and the
- * `isAstryxInitialized` predicate all derive from this list, so "where init
- * writes" and "where we look" can never drift. (Explicit --agent-docs-path
- * targets are user-chosen and not enumerable here.)
+ * write a managed Astryx block — the full block, or the one-line import of
+ * AGENTS.md that the default writes to GEMINI.md. SINGLE
+ * SOURCE OF TRUTH: discovery, removal, and the `isAstryxInitialized` predicate
+ * all derive from this list, so "where init writes" and "where we look" can
+ * never drift. (Explicit --agent-docs-path targets are user-chosen and not
+ * enumerable here.)
  */
 export const AGENT_DOC_PATHS = [
   AGENTS_MD, // Codex / ChatGPT / Muse / generic
   CLAUDE_MD, // Claude Code (root)
   CLAUDE_DIR_MD, // Claude Code (.claude/CLAUDE.md)
+  GEMINI_MD, // Gemini CLI
   CURSOR_RULES, // Cursor
   HERMES_DOT_MD, // Hermes
   HERMES_MD, // Hermes
@@ -64,7 +68,7 @@ export const INIT_MARKERS = [MARKER_START, LEGACY_MARKER_START];
 /**
  * Find all existing agent doc files in a directory, across EVERY location any
  * preset can write (see {@link AGENT_DOC_PATHS}: AGENTS.md, CLAUDE.md,
- * .claude/CLAUDE.md, .cursorrules, .hermes.md, HERMES.md).
+ * .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md, HERMES.md).
  * @param {string} targetDir
  * @returns {string[]} Relative paths of existing agent doc files
  */
@@ -72,10 +76,33 @@ export function discoverAgentDocs(targetDir) {
   return AGENT_DOC_PATHS.filter(p => fs.existsSync(path.join(targetDir, p)));
 }
 
+/**
+ * Whether `content` holds an Astryx block. A managed block that only imports
+ * another file (the one-line `@./AGENTS.md` that init writes to GEMINI.md) does
+ * not count: it holds nothing once that file has lost its block. A malformed
+ * block still counts, so a half-written file reads as set up.
+ *
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function holdsAstryxBlock(content) {
+  for (const marker of INIT_MARKERS) {
+    let at = content.indexOf(marker);
+    while (at !== -1) {
+      const from = at + marker.length;
+      const end = content.indexOf('<!--', from);
+      const inner = (end === -1 ? content.slice(from) : content.slice(from, end)).trim();
+      if (!/^@\S+$/.test(inner)) return true;
+      at = content.indexOf(marker, from);
+    }
+  }
+  return false;
+}
+
 /**
  * Single source of truth for "is Astryx set up in this project?" — true when any
- * agent-doc file already carries the Astryx marker, i.e. `init` / `agent-docs`
- * has run. Reused by the init & upgrade commands, the per-command setup nudge
+ * agent-doc file already holds an Astryx block, i.e. `init` / `agent-docs` has
+ * run. Reused by the init & upgrade commands, the per-command setup nudge
  * (enforcement layer 3), and the cli postinstall nudge (layer 2). Core's
  * postinstall (separate package, layer 1) mirrors the same marker contract.
  *
@@ -86,7 +113,7 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
   for (const rel of discoverAgentDocs(targetDir)) {
     try {
       const content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');
-      if (INIT_MARKERS.some(m => content.includes(m))) {
+      if (holdsAstryxBlock(content)) {
         return true;
       }
     } catch {