@agentex/agent 0.0.37 → 0.0.38

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.0.38 — AGENTS.md is the workspace instruction file for every runtime
+
+Claude Code reads `AGENTS.md` since 2.1.277, loaded exactly where `CLAUDE.md` would be, but only in a folder with no `CLAUDE.md`. A `CLAUDE.md`, a `CLAUDE.local.md`, or one in a parent folder hides `AGENTS.md` completely (verified against 2.1.281). Not yet on Bedrock, Vertex or Foundry.
+
+### Changed (breaking)
+
+- **`installInstructions` writes `AGENTS.md` only by default.** Claude's workspace file is now `AGENTS.md`, like every other runtime. `CLAUDE.md` is Claude's native file, written only with `includeNativeFiles: true`, and then as a one-line `@AGENTS.md` pointer in the managed region instead of a second copy of the brief. A copy would have made anything the user writes in `AGENTS.md` invisible to Claude. Opt in for Claude Code before 2.1.277 or on a third-party API provider. `includeNativeFiles` still writes Gemini's `GEMINI.md` as a copy.
+- **An existing workspace `CLAUDE.md` is reconciled** whenever `claude` is among the runtimes and the opt-in is off, because it would hide `AGENTS.md`: one holding nothing but this installer's managed region (for example the full brief 0.0.37 and earlier wrote) is deleted, and one the user wrote keeps their content and gains `@AGENTS.md` in the managed region. `managed: false` leaves it alone.
+- **`removeInstructions` always checks native files** (`CLAUDE.md`, `GEMINI.md`), so an opt-in install is fully removable. It still only strips the managed region.
+
+### Added
+
+- `InstructionStatus` gains `"removed"`, and `InstructionInstallResult` a `removed` count.
+- `InstructionTarget.importsFile` marks a pointer file (`"AGENTS.md"` on an opt-in `CLAUDE.md`).
+
+### Migration
+
+A host that relied on the default `CLAUDE.md` gets `AGENTS.md` only. Nothing else is needed on Claude Code 2.1.277+ with first-party auth: the next install deletes the old managed-only `CLAUDE.md`. Elsewhere, pass `includeNativeFiles: true`.
+
 ## 0.0.37 — Turn liveness and background-task identity (Claude)
 
 Claude Code starts turns by itself. When a background task finishes, the CLI

package/README.md

@@ -1041,11 +1041,11 @@ Channels and locations follow the emerging `.agents/skills/` + `.claude/skills/`
 import { installInstructions, removeInstructions } from "@agentex/agent";
 
 // Workspace (repo-root) install — the common case.
-// Writes the brief into {cwd}/CLAUDE.md and {cwd}/AGENTS.md (deduped by filename).
+// Writes the brief into {cwd}/AGENTS.md, which every runtime reads.
 await installInstructions(brief, {
   location: "workspace",      // or "global"
   cwd: process.cwd(),         // required for workspace installs
-  includeNativeFiles: false,  // true also writes Gemini's native GEMINI.md
+  includeNativeFiles: false,  // true also writes CLAUDE.md (an @AGENTS.md pointer) and GEMINI.md
   managed: true,              // wrap in markers + merge (default); false overwrites the file
   managedTag: "agentex",      // marker tag → <!-- agentex:managed:start -->
 });
@@ -1058,7 +1058,12 @@ await installInstructions(brief, { location: "global" });
 await removeInstructions({ location: "workspace", cwd: process.cwd() });
 ```
 
-Every runtime except Claude reads `AGENTS.md`; Claude reads `CLAUDE.md`. Gemini reads `GEMINI.md` by default (only reads `AGENTS.md` when configured), so it gets a native escape hatch via `includeNativeFiles`. Re-installing unchanged content is idempotent (reported as `skipped`). Use `resolveInstructionTargets(opts)` to see which files *would* be written without touching disk, and `upsertManagedBlock` / `stripManagedBlock` for the low-level merge.
+Every runtime reads `AGENTS.md` at a workspace root. Claude Code does since 2.1.277, but only where the folder has no `CLAUDE.md`: a `CLAUDE.md`, a `CLAUDE.local.md`, or one in a parent folder hides `AGENTS.md` completely. So a workspace `CLAUDE.md` is only ever a one-line `@AGENTS.md` pointer, never a second copy of the brief:
+
+- `includeNativeFiles: true` writes the pointer. Use it for Claude Code before 2.1.277, or on Bedrock, Vertex or Foundry, where Claude doesn't read `AGENTS.md` on its own. It also writes Gemini's native `GEMINI.md` (a copy), since Gemini reads `AGENTS.md` only when configured.
+- With the opt-in off, an existing `CLAUDE.md` is reconciled whenever Claude is among the runtimes: one holding nothing but the managed region is removed (reported `removed`), and one the user wrote gets `@AGENTS.md` in its managed region, so the brief still reaches Claude.
+
+Re-installing unchanged content is idempotent (reported as `skipped`). Use `resolveInstructionTargets(opts)` to see which files *would* be written without touching disk, and `upsertManagedBlock` / `stripManagedBlock` for the low-level merge.
 
 ### Discover Slash-Invokable Skills
 
@@ -1268,7 +1273,7 @@ registerProvider(myProvider);
 - `renderTemplate(template, ctx)` — `{{var}}` interpolation.
 - `redactEnvForLogs(env)` — redact sensitive values before logging.
 - `resolveInstructions(path?)` — read an instructions file, or `null` if no path.
-- `installInstructions(content, opts?)` / `removeInstructions(opts?)` — write/remove a managed instruction brief across per-runtime files (`CLAUDE.md` / `AGENTS.md` / native `GEMINI.md`), workspace or global.
+- `installInstructions(content, opts?)` / `removeInstructions(opts?)` — write/remove a managed instruction brief across per-runtime files (`AGENTS.md`, plus opt-in native `CLAUDE.md` pointer / `GEMINI.md`), workspace or global.
 - `resolveInstructionTargets(opts?)` — list which instruction files would be written, without touching disk.
 - `upsertManagedBlock(existing, content, opts?)` / `stripManagedBlock(existing, opts?)` — low-level managed-region merge/strip (preserves content outside the markers).
 - `getDefaultRuntimeHome(runtime, homeDir?)` — pass `homeDir` to resolve against a sandboxed base instead of `os.homedir()`.

package/dist/utils/instructions.d.ts

@@ -14,15 +14,20 @@ export interface InstallInstructionsOptions {
     cwd?: string;
     /**
      * Also write each runtime's native file when it differs from the shared
-     * standard (currently only Gemini's GEMINI.md). Only affects "workspace";
-     * "global" always uses native files. Default: false.
+     * AGENTS.md: Claude's CLAUDE.md (as a one-line `@AGENTS.md` pointer) and
+     * Gemini's GEMINI.md (as a copy). Only affects "workspace"; "global" always
+     * uses native files. Default: false.
+     *
+     * Opt in for Claude Code before 2.1.277, or on Bedrock, Vertex or Foundry,
+     * where Claude doesn't read AGENTS.md on its own.
      */
     includeNativeFiles?: boolean;
     /**
      * Wrap `content` in managed markers and merge into any existing file,
      * replacing only the previously-managed region and preserving everything the
      * user wrote outside it. Default: true. When false, the file is overwritten
-     * with raw `content` (escape hatch for fully-owned files).
+     * with raw `content` (escape hatch for fully-owned files), and an existing
+     * CLAUDE.md is left alone even though it hides AGENTS.md from Claude Code.
      */
     managed?: boolean;
     /** Marker tag, so the comment reads `<!-- <tag>:managed:start -->`. Default: "agentex". */
@@ -33,7 +38,11 @@ export interface InstallInstructionsOptions {
      */
     homeDir?: string;
 }
-export type InstructionStatus = "created" | "updated" | "skipped" | "error";
+/**
+ * "removed": a workspace CLAUDE.md that held nothing but this installer's
+ * managed region, deleted because the opt-in (`includeNativeFiles`) is off.
+ */
+export type InstructionStatus = "created" | "updated" | "skipped" | "removed" | "error";
 export interface InstructionInstallEntry {
     /** The filename written, e.g. "AGENTS.md", "CLAUDE.md", "GEMINI.md". */
     filename: string;
@@ -41,6 +50,8 @@ export interface InstructionInstallEntry {
     targetPath: string;
     /** Which requested runtimes this file serves. */
     runtimes: SkillRuntime[];
+    /** Set when the file is a pointer: its managed region is `@<importsFile>`, not the brief. */
+    importsFile?: string;
     status: InstructionStatus;
     error?: string;
 }
@@ -49,12 +60,15 @@ export interface InstructionInstallResult {
     installed: number;
     updated: number;
     skipped: number;
+    removed: number;
     errors: number;
 }
 export interface InstructionTarget {
     filename: string;
     targetPath: string;
     runtimes: SkillRuntime[];
+    /** Set when the file is a pointer: its managed region is `@<importsFile>`, not the brief. */
+    importsFile?: string;
 }
 export interface RemoveInstructionsOptions {
     runtimes?: SkillRuntime[];
@@ -85,7 +99,8 @@ export interface ManagedBlockOptions {
  * without touching disk.
  *
  * - "workspace": files dedupe by name under {cwd}/ (the default writes
- *   CLAUDE.md + AGENTS.md once each). `includeNativeFiles` adds GEMINI.md.
+ *   AGENTS.md once). `includeNativeFiles` adds CLAUDE.md (a pointer, marked by
+ *   `importsFile`) and GEMINI.md.
  * - "global": one file per runtime in each runtime's home dir. Runtimes without
  *   a file-based global config (Cursor) are omitted.
  */
@@ -99,18 +114,25 @@ export declare function resolveInstructionTargets(options?: {
 /**
  * Install an instruction brief into the right per-runtime files.
  *
- * By default merges `content` into a managed region of `{cwd}/CLAUDE.md` and
- * `{cwd}/AGENTS.md`, preserving any user-authored content outside the markers.
- * Idempotent: a re-install with unchanged content reports every entry as
- * "skipped".
+ * By default merges `content` into a managed region of `{cwd}/AGENTS.md`,
+ * preserving any user-authored content outside the markers. Idempotent: a
+ * re-install with unchanged content reports every entry as "skipped".
+ *
+ * When Claude is among the runtimes, a `{cwd}/CLAUDE.md` already on disk is
+ * reconciled, because it would hide AGENTS.md from Claude Code: one holding
+ * nothing but this installer's managed region is removed, and one the user
+ * wrote gets `@AGENTS.md` in its managed region. With `includeNativeFiles`,
+ * CLAUDE.md is written as that pointer either way. `managed: false` leaves an
+ * existing CLAUDE.md alone.
  *
  * @example
  * ```ts
  * // Workspace (repo-root) install — the common case.
  * await installInstructions(brief, { location: "workspace", cwd: projectDir });
- * // → {cwd}/CLAUDE.md + {cwd}/AGENTS.md
+ * // → {cwd}/AGENTS.md
  *
- * // Also drop Gemini's native GEMINI.md (it doesn't read AGENTS.md by default).
+ * // Also write the native files: CLAUDE.md as an `@AGENTS.md` pointer (for
+ * // Claude Code before 2.1.277, or on Bedrock/Vertex/Foundry) and GEMINI.md.
  * await installInstructions(brief, { location: "workspace", cwd, includeNativeFiles: true });
  *
  * // Global install — per-runtime home files.
@@ -123,7 +145,9 @@ export declare function installInstructions(content: string, options?: InstallIn
  * Remove the managed region installed by {@link installInstructions}, preserving
  * any user-authored content outside the markers. If the file contains nothing
  * but the managed block, it is deleted. User-owned files (no managed region) are
- * left untouched and reported as "skipped".
+ * left untouched and reported as "skipped". Native files (CLAUDE.md, GEMINI.md)
+ * are always checked, whether or not they were installed with
+ * `includeNativeFiles`.
  */
 export declare function removeInstructions(options?: RemoveInstructionsOptions): Promise<InstructionRemoveResult>;
 /**

package/dist/utils/instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}

package/dist/utils/instructions.js

@@ -22,12 +22,12 @@ export async function resolveInstructions(filePath) {
     }
 }
 const RUNTIME_INSTRUCTIONS = {
-    claude: { projectFile: "CLAUDE.md", nativeFile: "CLAUDE.md", hasGlobalFile: true },
-    codex: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
-    opencode: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
-    gemini: { projectFile: "AGENTS.md", nativeFile: "GEMINI.md", hasGlobalFile: true },
-    cursor: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: false },
-    pi: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
+    claude: { projectFile: "AGENTS.md", nativeFile: "CLAUDE.md", nativeFileMode: "pointer", hasGlobalFile: true },
+    codex: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
+    opencode: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
+    gemini: { projectFile: "AGENTS.md", nativeFile: "GEMINI.md", nativeFileMode: "copy", hasGlobalFile: true },
+    cursor: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: false },
+    pi: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
 };
 const ALL_RUNTIMES = ["claude", "codex", "gemini", "cursor", "opencode", "pi"];
 const DEFAULT_MANAGED_TAG = "agentex";
@@ -39,7 +39,8 @@ const DEFAULT_MANAGED_TAG = "agentex";
  * without touching disk.
  *
  * - "workspace": files dedupe by name under {cwd}/ (the default writes
- *   CLAUDE.md + AGENTS.md once each). `includeNativeFiles` adds GEMINI.md.
+ *   AGENTS.md once). `includeNativeFiles` adds CLAUDE.md (a pointer, marked by
+ *   `importsFile`) and GEMINI.md.
  * - "global": one file per runtime in each runtime's home dir. Runtimes without
  *   a file-based global config (Cursor) are omitted.
  */
@@ -51,23 +52,24 @@ export function resolveInstructionTargets(options) {
         if (!cwd)
             throw new Error("cwd is required when location is 'workspace'");
         const byFile = new Map();
-        const add = (filename, runtime) => {
-            const list = byFile.get(filename) ?? [];
-            list.push(runtime);
-            byFile.set(filename, list);
+        const add = (filename, runtime, importsFile) => {
+            const target = byFile.get(filename) ?? {
+                filename,
+                targetPath: path.join(cwd, filename),
+                runtimes: [],
+                ...(importsFile !== undefined && { importsFile }),
+            };
+            target.runtimes.push(runtime);
+            byFile.set(filename, target);
         };
         for (const runtime of runtimes) {
             const spec = RUNTIME_INSTRUCTIONS[runtime];
             add(spec.projectFile, runtime);
             if (options?.includeNativeFiles && spec.nativeFile !== spec.projectFile) {
-                add(spec.nativeFile, runtime);
+                add(spec.nativeFile, runtime, spec.nativeFileMode === "pointer" ? spec.projectFile : undefined);
             }
         }
-        return [...byFile.entries()].map(([filename, rts]) => ({
-            filename,
-            targetPath: path.join(cwd, filename),
-            runtimes: dedupeRuntimes(rts),
-        }));
+        return [...byFile.values()].map((target) => ({ ...target, runtimes: dedupeRuntimes(target.runtimes) }));
     }
     // global: each runtime reads its own native file in its own home dir.
     const targets = [];
@@ -93,18 +95,25 @@ function dedupeRuntimes(runtimes) {
 /**
  * Install an instruction brief into the right per-runtime files.
  *
- * By default merges `content` into a managed region of `{cwd}/CLAUDE.md` and
- * `{cwd}/AGENTS.md`, preserving any user-authored content outside the markers.
- * Idempotent: a re-install with unchanged content reports every entry as
- * "skipped".
+ * By default merges `content` into a managed region of `{cwd}/AGENTS.md`,
+ * preserving any user-authored content outside the markers. Idempotent: a
+ * re-install with unchanged content reports every entry as "skipped".
+ *
+ * When Claude is among the runtimes, a `{cwd}/CLAUDE.md` already on disk is
+ * reconciled, because it would hide AGENTS.md from Claude Code: one holding
+ * nothing but this installer's managed region is removed, and one the user
+ * wrote gets `@AGENTS.md` in its managed region. With `includeNativeFiles`,
+ * CLAUDE.md is written as that pointer either way. `managed: false` leaves an
+ * existing CLAUDE.md alone.
  *
  * @example
  * ```ts
  * // Workspace (repo-root) install — the common case.
  * await installInstructions(brief, { location: "workspace", cwd: projectDir });
- * // → {cwd}/CLAUDE.md + {cwd}/AGENTS.md
+ * // → {cwd}/AGENTS.md
  *
- * // Also drop Gemini's native GEMINI.md (it doesn't read AGENTS.md by default).
+ * // Also write the native files: CLAUDE.md as an `@AGENTS.md` pointer (for
+ * // Claude Code before 2.1.277, or on Bedrock/Vertex/Foundry) and GEMINI.md.
  * await installInstructions(brief, { location: "workspace", cwd, includeNativeFiles: true });
  *
  * // Global install — per-runtime home files.
@@ -115,36 +124,16 @@ function dedupeRuntimes(runtimes) {
 export async function installInstructions(content, options) {
     const managed = options?.managed ?? true;
     const tag = options?.managedTag ?? DEFAULT_MANAGED_TAG;
-    const targets = resolveInstructionTargets(options);
     const entries = [];
-    for (const target of targets) {
-        try {
-            const existing = await readFileOrNull(target.targetPath);
-            const next = managed
-                ? upsertManagedBlock(existing, content, { tag })
-                : ensureTrailingNewline(content);
-            let status;
-            if (existing === null) {
-                status = "created";
-            }
-            else if (existing === next) {
-                status = "skipped";
-            }
-            else {
-                status = "updated";
-            }
-            if (status !== "skipped") {
-                await fs.mkdir(path.dirname(target.targetPath), { recursive: true });
-                await fs.writeFile(target.targetPath, next, { mode: 0o644 });
-            }
-            entries.push({ ...target, status });
-        }
-        catch (err) {
-            entries.push({
-                ...target,
-                status: "error",
-                error: err instanceof Error ? err.message : String(err),
-            });
+    for (const target of resolveInstructionTargets(options)) {
+        const body = target.importsFile !== undefined ? `@${target.importsFile}` : content;
+        entries.push(await writeTarget(target, body, managed, tag));
+    }
+    if (managed) {
+        for (const target of unrequestedPointerTargets(options)) {
+            const entry = await reconcilePointer(target, tag);
+            if (entry)
+                entries.push(entry);
         }
     }
     return {
@@ -152,14 +141,75 @@ export async function installInstructions(content, options) {
         installed: entries.filter((e) => e.status === "created").length,
         updated: entries.filter((e) => e.status === "updated").length,
         skipped: entries.filter((e) => e.status === "skipped").length,
+        removed: entries.filter((e) => e.status === "removed").length,
         errors: entries.filter((e) => e.status === "error").length,
     };
 }
+async function writeTarget(target, body, managed, tag) {
+    try {
+        const existing = await readFileOrNull(target.targetPath);
+        const next = managed ? upsertManagedBlock(existing, body, { tag }) : ensureTrailingNewline(body);
+        let status;
+        if (existing === null) {
+            status = "created";
+        }
+        else if (existing === next) {
+            status = "skipped";
+        }
+        else {
+            status = "updated";
+        }
+        if (status !== "skipped") {
+            await fs.mkdir(path.dirname(target.targetPath), { recursive: true });
+            await fs.writeFile(target.targetPath, next, { mode: 0o644 });
+        }
+        return { ...target, status };
+    }
+    catch (err) {
+        return { ...target, status: "error", error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Pointer files (a workspace CLAUDE.md) for the requested runtimes that the
+ * install doesn't write because the opt-in is off, but that still need
+ * reconciling if they exist.
+ */
+function unrequestedPointerTargets(options) {
+    if ((options?.location ?? "workspace") !== "workspace" || options?.includeNativeFiles)
+        return [];
+    return resolveInstructionTargets({ ...options, includeNativeFiles: true }).filter((target) => target.importsFile !== undefined);
+}
+/**
+ * An existing pointer file with the opt-in off: delete it when nothing but our
+ * managed region is in it, otherwise keep the user's content and make sure it
+ * imports the project file. Returns null when there is no file.
+ */
+async function reconcilePointer(target, tag) {
+    try {
+        const existing = await readFileOrNull(target.targetPath);
+        if (existing === null)
+            return null;
+        if (stripManagedBlock(existing, { tag }) === null) {
+            await fs.rm(target.targetPath, { force: true });
+            return { ...target, status: "removed" };
+        }
+        const next = upsertManagedBlock(existing, `@${target.importsFile}`, { tag });
+        if (next === existing)
+            return { ...target, status: "skipped" };
+        await fs.writeFile(target.targetPath, next);
+        return { ...target, status: "updated" };
+    }
+    catch (err) {
+        return { ...target, status: "error", error: err instanceof Error ? err.message : String(err) };
+    }
+}
 /**
  * Remove the managed region installed by {@link installInstructions}, preserving
  * any user-authored content outside the markers. If the file contains nothing
  * but the managed block, it is deleted. User-owned files (no managed region) are
- * left untouched and reported as "skipped".
+ * left untouched and reported as "skipped". Native files (CLAUDE.md, GEMINI.md)
+ * are always checked, whether or not they were installed with
+ * `includeNativeFiles`.
  */
 export async function removeInstructions(options) {
     const tag = options?.managedTag ?? DEFAULT_MANAGED_TAG;
@@ -167,6 +217,7 @@ export async function removeInstructions(options) {
         runtimes: options?.runtimes,
         location: options?.location,
         cwd: options?.cwd,
+        includeNativeFiles: true,
         homeDir: options?.homeDir,
     });
     const entries = [];

package/dist/utils/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentex/agent",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "description": "Programmatic execution of AI coding agents including Claude Code, Codex, Cursor, and OpenCode",
   "repository": {
     "type": "git",

package/src/utils/instructions.ts

@@ -29,18 +29,27 @@ export async function resolveInstructions(filePath?: string): Promise<string | n
 // (.agents/skills + .claude/skills) with a per-runtime "native" escape hatch.
 // Instruction files follow the same shape:
 //
-//   - every runtime except Claude reads AGENTS.md; Claude reads CLAUDE.md
-//   - Gemini reads GEMINI.md by default (AGENTS.md only when configured), so it
-//     gets a native escape hatch
+//   - every runtime reads AGENTS.md at a workspace root (Claude Code since
+//     2.1.277, where the folder has no CLAUDE.md)
+//   - Claude's CLAUDE.md and Gemini's GEMINI.md are native files, written only
+//     on opt-in (`includeNativeFiles`)
 //
 // Two locations, mirroring installSkills:
 //
 //   - "workspace": files at {cwd}/ — the repo-root AGENTS.md convention. Files
-//     dedupe by name, so the default writes CLAUDE.md + AGENTS.md once each.
+//     dedupe by name, so the default writes AGENTS.md once.
 //   - "global": each runtime reads its own file in its own home dir
 //     (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ...). There
 //     is no universal ~/AGENTS.md, so global is inherently per-runtime.
 //
+// Claude Code reads AGENTS.md only where no CLAUDE.md exists: a CLAUDE.md (or
+// a CLAUDE.local.md, or one in a parent directory) hides AGENTS.md completely.
+// So a workspace CLAUDE.md is only ever a one-line pointer (`@AGENTS.md`),
+// never a second copy of the brief, and a CLAUDE.md already on disk is
+// reconciled on every install: one holding nothing but our managed region is
+// removed when the opt-in is off, and one the user wrote gets the pointer so
+// the brief still reaches Claude.
+//
 // Unlike skills (which are symlinked dirs), instruction files carry content, so
 // installInstructions does a managed-region merge: it wraps `content` in marker
 // comments and replaces only that region on re-install, preserving anything the
@@ -48,21 +57,28 @@ export async function resolveInstructions(filePath?: string): Promise<string | n
 // ===========================================================================
 
 interface RuntimeInstructionSpec {
-  /** File this runtime reads at a workspace/repo root. AGENTS.md for all but Claude. */
+  /** File this runtime reads at a workspace/repo root. AGENTS.md for every runtime. */
   projectFile: string;
-  /** The runtime's own preferred filename. Differs from projectFile only for Gemini (GEMINI.md). */
+  /** The runtime's own preferred filename. Written in a workspace only on opt-in (`includeNativeFiles`). */
   nativeFile: string;
+  /**
+   * How an opt-in native file carries the brief. "pointer": only an import of
+   * the project file (`@AGENTS.md`), because the native file's mere presence
+   * hides the project file from the runtime (Claude). "copy": the brief itself
+   * (Gemini, which doesn't read AGENTS.md by default).
+   */
+  nativeFileMode: "pointer" | "copy";
   /** Whether the runtime has a file-based global config. False for Cursor (global = app User Rules). */
   hasGlobalFile: boolean;
 }
 
 const RUNTIME_INSTRUCTIONS: Record<SkillRuntime, RuntimeInstructionSpec> = {
-  claude: { projectFile: "CLAUDE.md", nativeFile: "CLAUDE.md", hasGlobalFile: true },
-  codex: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
-  opencode: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
-  gemini: { projectFile: "AGENTS.md", nativeFile: "GEMINI.md", hasGlobalFile: true },
-  cursor: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: false },
-  pi: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
+  claude: { projectFile: "AGENTS.md", nativeFile: "CLAUDE.md", nativeFileMode: "pointer", hasGlobalFile: true },
+  codex: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
+  opencode: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
+  gemini: { projectFile: "AGENTS.md", nativeFile: "GEMINI.md", nativeFileMode: "copy", hasGlobalFile: true },
+  cursor: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: false },
+  pi: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", nativeFileMode: "copy", hasGlobalFile: true },
 };
 
 const ALL_RUNTIMES: SkillRuntime[] = ["claude", "codex", "gemini", "cursor", "opencode", "pi"];
@@ -78,15 +94,20 @@ export interface InstallInstructionsOptions {
   cwd?: string;
   /**
    * Also write each runtime's native file when it differs from the shared
-   * standard (currently only Gemini's GEMINI.md). Only affects "workspace";
-   * "global" always uses native files. Default: false.
+   * AGENTS.md: Claude's CLAUDE.md (as a one-line `@AGENTS.md` pointer) and
+   * Gemini's GEMINI.md (as a copy). Only affects "workspace"; "global" always
+   * uses native files. Default: false.
+   *
+   * Opt in for Claude Code before 2.1.277, or on Bedrock, Vertex or Foundry,
+   * where Claude doesn't read AGENTS.md on its own.
    */
   includeNativeFiles?: boolean;
   /**
    * Wrap `content` in managed markers and merge into any existing file,
    * replacing only the previously-managed region and preserving everything the
    * user wrote outside it. Default: true. When false, the file is overwritten
-   * with raw `content` (escape hatch for fully-owned files).
+   * with raw `content` (escape hatch for fully-owned files), and an existing
+   * CLAUDE.md is left alone even though it hides AGENTS.md from Claude Code.
    */
   managed?: boolean;
   /** Marker tag, so the comment reads `<!-- <tag>:managed:start -->`. Default: "agentex". */
@@ -98,7 +119,11 @@ export interface InstallInstructionsOptions {
   homeDir?: string;
 }
 
-export type InstructionStatus = "created" | "updated" | "skipped" | "error";
+/**
+ * "removed": a workspace CLAUDE.md that held nothing but this installer's
+ * managed region, deleted because the opt-in (`includeNativeFiles`) is off.
+ */
+export type InstructionStatus = "created" | "updated" | "skipped" | "removed" | "error";
 
 export interface InstructionInstallEntry {
   /** The filename written, e.g. "AGENTS.md", "CLAUDE.md", "GEMINI.md". */
@@ -107,6 +132,8 @@ export interface InstructionInstallEntry {
   targetPath: string;
   /** Which requested runtimes this file serves. */
   runtimes: SkillRuntime[];
+  /** Set when the file is a pointer: its managed region is `@<importsFile>`, not the brief. */
+  importsFile?: string;
   status: InstructionStatus;
   error?: string;
 }
@@ -116,6 +143,7 @@ export interface InstructionInstallResult {
   installed: number; // newly created files
   updated: number; // existing files whose content changed
   skipped: number; // content already current → no write
+  removed: number; // managed-only CLAUDE.md deleted because the opt-in is off
   errors: number;
 }
 
@@ -123,6 +151,8 @@ export interface InstructionTarget {
   filename: string;
   targetPath: string;
   runtimes: SkillRuntime[];
+  /** Set when the file is a pointer: its managed region is `@<importsFile>`, not the brief. */
+  importsFile?: string;
 }
 
 export interface RemoveInstructionsOptions {
@@ -163,7 +193,8 @@ export interface ManagedBlockOptions {
  * without touching disk.
  *
  * - "workspace": files dedupe by name under {cwd}/ (the default writes
- *   CLAUDE.md + AGENTS.md once each). `includeNativeFiles` adds GEMINI.md.
+ *   AGENTS.md once). `includeNativeFiles` adds CLAUDE.md (a pointer, marked by
+ *   `importsFile`) and GEMINI.md.
  * - "global": one file per runtime in each runtime's home dir. Runtimes without
  *   a file-based global config (Cursor) are omitted.
  */
@@ -181,26 +212,27 @@ export function resolveInstructionTargets(options?: {
     const cwd = options?.cwd;
     if (!cwd) throw new Error("cwd is required when location is 'workspace'");
 
-    const byFile = new Map<string, SkillRuntime[]>();
-    const add = (filename: string, runtime: SkillRuntime) => {
-      const list = byFile.get(filename) ?? [];
-      list.push(runtime);
-      byFile.set(filename, list);
+    const byFile = new Map<string, InstructionTarget>();
+    const add = (filename: string, runtime: SkillRuntime, importsFile?: string) => {
+      const target: InstructionTarget = byFile.get(filename) ?? {
+        filename,
+        targetPath: path.join(cwd, filename),
+        runtimes: [],
+        ...(importsFile !== undefined && { importsFile }),
+      };
+      target.runtimes.push(runtime);
+      byFile.set(filename, target);
     };
 
     for (const runtime of runtimes) {
       const spec = RUNTIME_INSTRUCTIONS[runtime];
       add(spec.projectFile, runtime);
       if (options?.includeNativeFiles && spec.nativeFile !== spec.projectFile) {
-        add(spec.nativeFile, runtime);
+        add(spec.nativeFile, runtime, spec.nativeFileMode === "pointer" ? spec.projectFile : undefined);
       }
     }
 
-    return [...byFile.entries()].map(([filename, rts]) => ({
-      filename,
-      targetPath: path.join(cwd, filename),
-      runtimes: dedupeRuntimes(rts),
-    }));
+    return [...byFile.values()].map((target) => ({ ...target, runtimes: dedupeRuntimes(target.runtimes) }));
   }
 
   // global: each runtime reads its own native file in its own home dir.
@@ -229,18 +261,25 @@ function dedupeRuntimes(runtimes: SkillRuntime[]): SkillRuntime[] {
 /**
  * Install an instruction brief into the right per-runtime files.
  *
- * By default merges `content` into a managed region of `{cwd}/CLAUDE.md` and
- * `{cwd}/AGENTS.md`, preserving any user-authored content outside the markers.
- * Idempotent: a re-install with unchanged content reports every entry as
- * "skipped".
+ * By default merges `content` into a managed region of `{cwd}/AGENTS.md`,
+ * preserving any user-authored content outside the markers. Idempotent: a
+ * re-install with unchanged content reports every entry as "skipped".
+ *
+ * When Claude is among the runtimes, a `{cwd}/CLAUDE.md` already on disk is
+ * reconciled, because it would hide AGENTS.md from Claude Code: one holding
+ * nothing but this installer's managed region is removed, and one the user
+ * wrote gets `@AGENTS.md` in its managed region. With `includeNativeFiles`,
+ * CLAUDE.md is written as that pointer either way. `managed: false` leaves an
+ * existing CLAUDE.md alone.
  *
  * @example
  * ```ts
  * // Workspace (repo-root) install — the common case.
  * await installInstructions(brief, { location: "workspace", cwd: projectDir });
- * // → {cwd}/CLAUDE.md + {cwd}/AGENTS.md
+ * // → {cwd}/AGENTS.md
  *
- * // Also drop Gemini's native GEMINI.md (it doesn't read AGENTS.md by default).
+ * // Also write the native files: CLAUDE.md as an `@AGENTS.md` pointer (for
+ * // Claude Code before 2.1.277, or on Bedrock/Vertex/Foundry) and GEMINI.md.
  * await installInstructions(brief, { location: "workspace", cwd, includeNativeFiles: true });
  *
  * // Global install — per-runtime home files.
@@ -254,37 +293,16 @@ export async function installInstructions(
 ): Promise<InstructionInstallResult> {
   const managed = options?.managed ?? true;
   const tag = options?.managedTag ?? DEFAULT_MANAGED_TAG;
-  const targets = resolveInstructionTargets(options);
   const entries: InstructionInstallEntry[] = [];
 
-  for (const target of targets) {
-    try {
-      const existing = await readFileOrNull(target.targetPath);
-      const next = managed
-        ? upsertManagedBlock(existing, content, { tag })
-        : ensureTrailingNewline(content);
-
-      let status: InstructionStatus;
-      if (existing === null) {
-        status = "created";
-      } else if (existing === next) {
-        status = "skipped";
-      } else {
-        status = "updated";
-      }
-
-      if (status !== "skipped") {
-        await fs.mkdir(path.dirname(target.targetPath), { recursive: true });
-        await fs.writeFile(target.targetPath, next, { mode: 0o644 });
-      }
-
-      entries.push({ ...target, status });
-    } catch (err) {
-      entries.push({
-        ...target,
-        status: "error",
-        error: err instanceof Error ? err.message : String(err),
-      });
+  for (const target of resolveInstructionTargets(options)) {
+    const body = target.importsFile !== undefined ? `@${target.importsFile}` : content;
+    entries.push(await writeTarget(target, body, managed, tag));
+  }
+  if (managed) {
+    for (const target of unrequestedPointerTargets(options)) {
+      const entry = await reconcilePointer(target, tag);
+      if (entry) entries.push(entry);
     }
   }
 
@@ -293,15 +311,84 @@ export async function installInstructions(
     installed: entries.filter((e) => e.status === "created").length,
     updated: entries.filter((e) => e.status === "updated").length,
     skipped: entries.filter((e) => e.status === "skipped").length,
+    removed: entries.filter((e) => e.status === "removed").length,
     errors: entries.filter((e) => e.status === "error").length,
   };
 }
 
+async function writeTarget(
+  target: InstructionTarget,
+  body: string,
+  managed: boolean,
+  tag: string,
+): Promise<InstructionInstallEntry> {
+  try {
+    const existing = await readFileOrNull(target.targetPath);
+    const next = managed ? upsertManagedBlock(existing, body, { tag }) : ensureTrailingNewline(body);
+
+    let status: InstructionStatus;
+    if (existing === null) {
+      status = "created";
+    } else if (existing === next) {
+      status = "skipped";
+    } else {
+      status = "updated";
+    }
+
+    if (status !== "skipped") {
+      await fs.mkdir(path.dirname(target.targetPath), { recursive: true });
+      await fs.writeFile(target.targetPath, next, { mode: 0o644 });
+    }
+    return { ...target, status };
+  } catch (err) {
+    return { ...target, status: "error", error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Pointer files (a workspace CLAUDE.md) for the requested runtimes that the
+ * install doesn't write because the opt-in is off, but that still need
+ * reconciling if they exist.
+ */
+function unrequestedPointerTargets(options?: InstallInstructionsOptions): InstructionTarget[] {
+  if ((options?.location ?? "workspace") !== "workspace" || options?.includeNativeFiles) return [];
+  return resolveInstructionTargets({ ...options, includeNativeFiles: true }).filter(
+    (target) => target.importsFile !== undefined,
+  );
+}
+
+/**
+ * An existing pointer file with the opt-in off: delete it when nothing but our
+ * managed region is in it, otherwise keep the user's content and make sure it
+ * imports the project file. Returns null when there is no file.
+ */
+async function reconcilePointer(
+  target: InstructionTarget,
+  tag: string,
+): Promise<InstructionInstallEntry | null> {
+  try {
+    const existing = await readFileOrNull(target.targetPath);
+    if (existing === null) return null;
+    if (stripManagedBlock(existing, { tag }) === null) {
+      await fs.rm(target.targetPath, { force: true });
+      return { ...target, status: "removed" };
+    }
+    const next = upsertManagedBlock(existing, `@${target.importsFile}`, { tag });
+    if (next === existing) return { ...target, status: "skipped" };
+    await fs.writeFile(target.targetPath, next);
+    return { ...target, status: "updated" };
+  } catch (err) {
+    return { ...target, status: "error", error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 /**
  * Remove the managed region installed by {@link installInstructions}, preserving
  * any user-authored content outside the markers. If the file contains nothing
  * but the managed block, it is deleted. User-owned files (no managed region) are
- * left untouched and reported as "skipped".
+ * left untouched and reported as "skipped". Native files (CLAUDE.md, GEMINI.md)
+ * are always checked, whether or not they were installed with
+ * `includeNativeFiles`.
  */
 export async function removeInstructions(
   options?: RemoveInstructionsOptions,
@@ -311,6 +398,7 @@ export async function removeInstructions(
     runtimes: options?.runtimes,
     location: options?.location,
     cwd: options?.cwd,
+    includeNativeFiles: true,
     homeDir: options?.homeDir,
   });
   const entries: InstructionRemoveEntry[] = [];