@agentex/agent 0.0.20 → 0.0.21

package/README.md

@@ -693,6 +693,33 @@ await removeSkills(skillDirs, { location: "workspace", cwd: process.cwd() });
 
 Channels and locations follow the emerging `.agents/skills/` + `.claude/skills/` convention — see the `SkillRuntime`, `SkillLocation`, and `SkillChannel` types.
 
+### Install Instruction Files
+
+`installInstructions` is the instruction-file twin of `installSkills`: it drops an orientation brief into the right per-runtime file(s), merging into a **managed region** so any content the user wrote outside the markers is preserved.
+
+```typescript
+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).
+await installInstructions(brief, {
+  location: "workspace",      // or "global"
+  cwd: process.cwd(),         // required for workspace installs
+  includeNativeFiles: false,  // true also writes Gemini's native GEMINI.md
+  managed: true,              // wrap in markers + merge (default); false overwrites the file
+  managedTag: "agentex",      // marker tag → <!-- agentex:managed:start -->
+});
+
+// Global install — per-runtime home files (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md,
+// ~/.gemini/GEMINI.md, ~/.config/opencode/AGENTS.md, ~/.pi/AGENTS.md).
+await installInstructions(brief, { location: "global" });
+
+// Remove only the managed region; user-authored content (and user-owned files) survive.
+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.
+
 ### Discover Slash-Invokable Skills
 
 Use `discoverSkillCommands(...)` to parse local `SKILL.md` files into UI-ready descriptors. It reads frontmatter fields such as `description`, `argument-hint`, and `user-invocable`; if no description is present, it falls back to the first non-empty body paragraph.
@@ -901,6 +928,10 @@ 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.
+- `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()`.
 - `parseAskUserQuestion(req)` — extract structured question/option data from a `UserInputRequest`.
 - `parseExitPlanMode(req)` — extract the proposed plan text from an `ExitPlanMode` permission request (Claude plan mode).
 

package/dist/index.d.ts

@@ -11,7 +11,8 @@ export { redactEnvForLogs } from "./utils/env.js";
 export { parseAskUserQuestion } from "./utils/ask-user-question.js";
 export { parseExitPlanMode } from "./utils/exit-plan-mode.js";
 export { aggregateUsage } from "./types.js";
-export { resolveInstructions } from "./utils/instructions.js";
+export { resolveInstructions, installInstructions, removeInstructions, resolveInstructionTargets, upsertManagedBlock, stripManagedBlock, } from "./utils/instructions.js";
+export type { InstallInstructionsOptions, InstructionStatus, InstructionInstallEntry, InstructionInstallResult, InstructionTarget, RemoveInstructionsOptions, InstructionRemoveStatus, InstructionRemoveEntry, InstructionRemoveResult, ManagedBlockOptions, } from "./utils/instructions.js";
 export { getRuntimeHomeEnvVar, getDefaultRuntimeHome } from "./utils/runtime-homes.js";
 export { findBinary, ensureCommandResolvable, clearBinaryCache } from "./utils/binary.js";
 export type { ResolvedBinary } from "./utils/binary.js";

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -8,7 +8,7 @@ export { redactEnvForLogs } from "./utils/env.js";
 export { parseAskUserQuestion } from "./utils/ask-user-question.js";
 export { parseExitPlanMode } from "./utils/exit-plan-mode.js";
 export { aggregateUsage } from "./types.js";
-export { resolveInstructions } from "./utils/instructions.js";
+export { resolveInstructions, installInstructions, removeInstructions, resolveInstructionTargets, upsertManagedBlock, stripManagedBlock, } from "./utils/instructions.js";
 export { getRuntimeHomeEnvVar, getDefaultRuntimeHome } from "./utils/runtime-homes.js";
 export { findBinary, ensureCommandResolvable, clearBinaryCache } from "./utils/binary.js";
 export { detectAuth, resolveAuthForProvider, clearAuthCache, hasSubscription, hasApiKey, hasBedrock, isLoggedIn, loginCommandFor, } from "./utils/auth.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1F,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAU1C,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,gBAAgB,GACjB,MAAM,iCAAiC,CAAC;AAUzC,SAAS;AACT,OAAO,EACL,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,wBAAwB,GACzB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,kBAAkB,EAClB,4BAA4B,GAC7B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,yBAAyB,CAAC;AAajC,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1F,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,SAAS,EACT,UAAU,EACV,UAAU,EACV,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,kCAAkC,CAAC;AAU1C,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,gBAAgB,GACjB,MAAM,iCAAiC,CAAC;AAUzC,SAAS;AACT,OAAO,EACL,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,wBAAwB,GACzB,MAAM,2BAA2B,CAAC"}

package/dist/utils/instructions.d.ts

@@ -1,7 +1,147 @@
+import type { SkillRuntime, SkillLocation } from "./skills.js";
 /**
  * Read an instructions file and return its content.
  * Returns null if no path is provided.
  * Throws a clear error if the file doesn't exist.
  */
 export declare function resolveInstructions(filePath?: string): Promise<string | null>;
+export interface InstallInstructionsOptions {
+    /** Which runtimes to write instruction files for. Defaults to all known runtimes. */
+    runtimes?: SkillRuntime[];
+    /** "workspace" ({cwd}/) — default — or "global" (each runtime's home dir). */
+    location?: SkillLocation;
+    /** Working directory. Required for "workspace". */
+    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.
+     */
+    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).
+     */
+    managed?: boolean;
+    /** Marker tag, so the comment reads `<!-- <tag>:managed:start -->`. Default: "agentex". */
+    managedTag?: string;
+    /**
+     * Override the home-directory base for "global" installs (sandboxes / tests).
+     * Defaults to os.homedir().
+     */
+    homeDir?: string;
+}
+export type InstructionStatus = "created" | "updated" | "skipped" | "error";
+export interface InstructionInstallEntry {
+    /** The filename written, e.g. "AGENTS.md", "CLAUDE.md", "GEMINI.md". */
+    filename: string;
+    /** Absolute path written. */
+    targetPath: string;
+    /** Which requested runtimes this file serves. */
+    runtimes: SkillRuntime[];
+    status: InstructionStatus;
+    error?: string;
+}
+export interface InstructionInstallResult {
+    entries: InstructionInstallEntry[];
+    installed: number;
+    updated: number;
+    skipped: number;
+    errors: number;
+}
+export interface InstructionTarget {
+    filename: string;
+    targetPath: string;
+    runtimes: SkillRuntime[];
+}
+export interface RemoveInstructionsOptions {
+    runtimes?: SkillRuntime[];
+    location?: SkillLocation;
+    cwd?: string;
+    /** Marker tag whose managed region should be removed. Default: "agentex". */
+    managedTag?: string;
+    homeDir?: string;
+}
+export type InstructionRemoveStatus = "removed" | "not_found" | "skipped" | "error";
+export interface InstructionRemoveEntry {
+    filename: string;
+    targetPath: string;
+    runtimes: SkillRuntime[];
+    status: InstructionRemoveStatus;
+    error?: string;
+}
+export interface InstructionRemoveResult {
+    entries: InstructionRemoveEntry[];
+    removed: number;
+}
+export interface ManagedBlockOptions {
+    /** Marker tag. Default: "agentex". */
+    tag?: string;
+}
+/**
+ * Resolve which instruction files would be written for the given options,
+ * without touching disk.
+ *
+ * - "workspace": files dedupe by name under {cwd}/ (the default writes
+ *   CLAUDE.md + AGENTS.md once each). `includeNativeFiles` adds GEMINI.md.
+ * - "global": one file per runtime in each runtime's home dir. Runtimes without
+ *   a file-based global config (Cursor) are omitted.
+ */
+export declare function resolveInstructionTargets(options?: {
+    runtimes?: SkillRuntime[];
+    location?: SkillLocation;
+    cwd?: string;
+    includeNativeFiles?: boolean;
+    homeDir?: string;
+}): InstructionTarget[];
+/**
+ * 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".
+ *
+ * @example
+ * ```ts
+ * // Workspace (repo-root) install — the common case.
+ * await installInstructions(brief, { location: "workspace", cwd: projectDir });
+ * // → {cwd}/CLAUDE.md + {cwd}/AGENTS.md
+ *
+ * // Also drop Gemini's native GEMINI.md (it doesn't read AGENTS.md by default).
+ * await installInstructions(brief, { location: "workspace", cwd, includeNativeFiles: true });
+ *
+ * // Global install — per-runtime home files.
+ * await installInstructions(brief, { location: "global" });
+ * // → ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ...
+ * ```
+ */
+export declare function installInstructions(content: string, options?: InstallInstructionsOptions): Promise<InstructionInstallResult>;
+/**
+ * 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".
+ */
+export declare function removeInstructions(options?: RemoveInstructionsOptions): Promise<InstructionRemoveResult>;
+/**
+ * Merge `content` into `existing` as a managed region, preserving everything the
+ * user wrote outside the markers.
+ *
+ * - `existing` has a managed region → replace only the bytes between the markers.
+ * - `existing` has no markers → prepend the managed block, keep prior content below.
+ * - `existing` is null/empty → return just the managed block.
+ *
+ * The start marker embeds a short content hash, so re-running with identical
+ * content produces a byte-identical result (enabling cheap skip detection).
+ */
+export declare function upsertManagedBlock(existing: string | null, content: string, options?: ManagedBlockOptions): string;
+/**
+ * Remove the managed region (if any) from `existing`, preserving user content.
+ * Returns the cleaned string, the original string if there was no managed
+ * region, or null if nothing but the managed block remained.
+ */
+export declare function stripManagedBlock(existing: string, options?: ManagedBlockOptions): string | null;
 //# sourceMappingURL=instructions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWnF"}
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}

package/dist/utils/instructions.js

@@ -1,4 +1,7 @@
 import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { getDefaultRuntimeHome } from "./runtime-homes.js";
 /**
  * Read an instructions file and return its content.
  * Returns null if no path is provided.
@@ -18,4 +21,249 @@ export async function resolveInstructions(filePath) {
         throw err;
     }
 }
+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 },
+};
+const ALL_RUNTIMES = ["claude", "codex", "gemini", "cursor", "opencode", "pi"];
+const DEFAULT_MANAGED_TAG = "agentex";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve which instruction files would be written for the given options,
+ * without touching disk.
+ *
+ * - "workspace": files dedupe by name under {cwd}/ (the default writes
+ *   CLAUDE.md + AGENTS.md once each). `includeNativeFiles` adds GEMINI.md.
+ * - "global": one file per runtime in each runtime's home dir. Runtimes without
+ *   a file-based global config (Cursor) are omitted.
+ */
+export function resolveInstructionTargets(options) {
+    const location = options?.location ?? "workspace";
+    const runtimes = dedupeRuntimes(options?.runtimes ?? ALL_RUNTIMES);
+    if (location === "workspace") {
+        const cwd = options?.cwd;
+        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);
+        };
+        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);
+            }
+        }
+        return [...byFile.entries()].map(([filename, rts]) => ({
+            filename,
+            targetPath: path.join(cwd, filename),
+            runtimes: dedupeRuntimes(rts),
+        }));
+    }
+    // global: each runtime reads its own native file in its own home dir.
+    const targets = [];
+    for (const runtime of runtimes) {
+        const spec = RUNTIME_INSTRUCTIONS[runtime];
+        if (!spec.hasGlobalFile)
+            continue; // e.g. cursor global = app User Rules, not a file
+        const home = getDefaultRuntimeHome(runtime, options?.homeDir);
+        targets.push({
+            filename: spec.nativeFile,
+            targetPath: path.join(home, spec.nativeFile),
+            runtimes: [runtime],
+        });
+    }
+    return targets;
+}
+function dedupeRuntimes(runtimes) {
+    return [...new Set(runtimes)];
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 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".
+ *
+ * @example
+ * ```ts
+ * // Workspace (repo-root) install — the common case.
+ * await installInstructions(brief, { location: "workspace", cwd: projectDir });
+ * // → {cwd}/CLAUDE.md + {cwd}/AGENTS.md
+ *
+ * // Also drop Gemini's native GEMINI.md (it doesn't read AGENTS.md by default).
+ * await installInstructions(brief, { location: "workspace", cwd, includeNativeFiles: true });
+ *
+ * // Global install — per-runtime home files.
+ * await installInstructions(brief, { location: "global" });
+ * // → ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ...
+ * ```
+ */
+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),
+            });
+        }
+    }
+    return {
+        entries,
+        installed: entries.filter((e) => e.status === "created").length,
+        updated: entries.filter((e) => e.status === "updated").length,
+        skipped: entries.filter((e) => e.status === "skipped").length,
+        errors: entries.filter((e) => e.status === "error").length,
+    };
+}
+/**
+ * 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".
+ */
+export async function removeInstructions(options) {
+    const tag = options?.managedTag ?? DEFAULT_MANAGED_TAG;
+    const targets = resolveInstructionTargets({
+        runtimes: options?.runtimes,
+        location: options?.location,
+        cwd: options?.cwd,
+        homeDir: options?.homeDir,
+    });
+    const entries = [];
+    for (const target of targets) {
+        try {
+            const existing = await readFileOrNull(target.targetPath);
+            if (existing === null) {
+                entries.push({ ...target, status: "not_found" });
+                continue;
+            }
+            const stripped = stripManagedBlock(existing, { tag });
+            if (stripped === existing) {
+                // No managed region present — never touch user-owned files.
+                entries.push({ ...target, status: "skipped" });
+                continue;
+            }
+            if (stripped === null) {
+                await fs.rm(target.targetPath, { force: true });
+            }
+            else {
+                await fs.writeFile(target.targetPath, stripped, { mode: 0o644 });
+            }
+            entries.push({ ...target, status: "removed" });
+        }
+        catch (err) {
+            entries.push({
+                ...target,
+                status: "error",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { entries, removed: entries.filter((e) => e.status === "removed").length };
+}
+// ---------------------------------------------------------------------------
+// Managed-region merge (exported for low-level use / hosts with custom layouts)
+// ---------------------------------------------------------------------------
+/**
+ * Merge `content` into `existing` as a managed region, preserving everything the
+ * user wrote outside the markers.
+ *
+ * - `existing` has a managed region → replace only the bytes between the markers.
+ * - `existing` has no markers → prepend the managed block, keep prior content below.
+ * - `existing` is null/empty → return just the managed block.
+ *
+ * The start marker embeds a short content hash, so re-running with identical
+ * content produces a byte-identical result (enabling cheap skip detection).
+ */
+export function upsertManagedBlock(existing, content, options) {
+    const tag = options?.tag ?? DEFAULT_MANAGED_TAG;
+    const block = buildManagedBlock(content, tag);
+    if (existing === null || existing.length === 0) {
+        return `${block}\n`;
+    }
+    const re = managedBlockRegex(tag);
+    if (re.test(existing)) {
+        return existing.replace(re, block);
+    }
+    // No managed region yet — prepend it, keep the user's file below.
+    return `${block}\n\n${existing.replace(/^\n+/, "")}`;
+}
+/**
+ * Remove the managed region (if any) from `existing`, preserving user content.
+ * Returns the cleaned string, the original string if there was no managed
+ * region, or null if nothing but the managed block remained.
+ */
+export function stripManagedBlock(existing, options) {
+    const tag = options?.tag ?? DEFAULT_MANAGED_TAG;
+    const re = managedBlockRegex(tag);
+    if (!re.test(existing))
+        return existing;
+    const stripped = existing.replace(re, "").replace(/^\n+/, "");
+    return stripped.trim().length === 0 ? null : stripped;
+}
+function buildManagedBlock(content, tag) {
+    const body = content.replace(/\s+$/, "");
+    const hash = createHash("sha256").update(body).digest("hex").slice(0, 12);
+    return `<!-- ${tag}:managed:start hash=${hash} -->\n${body}\n<!-- ${tag}:managed:end -->`;
+}
+function managedBlockRegex(tag) {
+    const t = escapeRegExp(tag);
+    return new RegExp(`<!--\\s*${t}:managed:start[^>]*-->[\\s\\S]*?<!--\\s*${t}:managed:end\\s*-->`);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith("\n") ? s : `${s}\n`;
+}
+async function readFileOrNull(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
 //# sourceMappingURL=instructions.js.map

package/dist/utils/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAiB;IACzD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAiB;IACzD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAoCD,MAAM,oBAAoB,GAAiD;IACzE,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE;IAClF,KAAK,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE;IACjF,QAAQ,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE;IACpF,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE;IAClF,MAAM,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,EAAE;IACnF,EAAE,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE;CAC/E,CAAC;AAEF,MAAM,YAAY,GAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AAE/F,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAuFtC,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAMzC;IACC,MAAM,QAAQ,GAAkB,OAAO,EAAE,QAAQ,IAAI,WAAW,CAAC;IACjE,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,EAAE,QAAQ,IAAI,YAAY,CAAC,CAAC;IAEnE,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,CAAC;QACzB,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAE1E,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;QACjD,MAAM,GAAG,GAAG,CAAC,QAAgB,EAAE,OAAqB,EAAE,EAAE;YACtD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACxC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACnB,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC,CAAC;QAEF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;YAC3C,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC/B,IAAI,OAAO,EAAE,kBAAkB,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;gBACxE,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QAED,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;YACrD,QAAQ;YACR,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC;YACpC,QAAQ,EAAE,cAAc,CAAC,GAAG,CAAC;SAC9B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,sEAAsE;IACtE,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,aAAa;YAAE,SAAS,CAAC,kDAAkD;QACrF,MAAM,IAAI,GAAG,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC9D,OAAO,CAAC,IAAI,CAAC;YACX,QAAQ,EAAE,IAAI,CAAC,UAAU;YACzB,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC;YAC5C,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,cAAc,CAAC,QAAwB;IAC9C,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAe,EACf,OAAoC;IAEpC,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;IACzC,MAAM,GAAG,GAAG,OAAO,EAAE,UAAU,IAAI,mBAAmB,CAAC;IACvD,MAAM,OAAO,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,OAAO,GAA8B,EAAE,CAAC;IAE9C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACzD,MAAM,IAAI,GAAG,OAAO;gBAClB,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC;gBAChD,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;YAEnC,IAAI,MAAyB,CAAC;YAC9B,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtB,MAAM,GAAG,SAAS,CAAC;YACrB,CAAC;iBAAM,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBAC7B,MAAM,GAAG,SAAS,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,SAAS,CAAC;YACrB,CAAC;YAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBACrE,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/D,CAAC;YAED,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC;gBACX,GAAG,MAAM;gBACT,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO;QACP,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM;QAC/D,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM;QAC7D,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM;QAC7D,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,MAAM;KAC3D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAmC;IAEnC,MAAM,GAAG,GAAG,OAAO,EAAE,UAAU,IAAI,mBAAmB,CAAC;IACvD,MAAM,OAAO,GAAG,yBAAyB,CAAC;QACxC,QAAQ,EAAE,OAAO,EAAE,QAAQ;QAC3B,QAAQ,EAAE,OAAO,EAAE,QAAQ;QAC3B,GAAG,EAAE,OAAO,EAAE,GAAG;QACjB,OAAO,EAAE,OAAO,EAAE,OAAO;KAC1B,CAAC,CAAC;IACH,MAAM,OAAO,GAA6B,EAAE,CAAC;IAE7C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACzD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtB,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;gBACjD,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YACtD,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC1B,4DAA4D;gBAC5D,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC/C,SAAS;YACX,CAAC;YAED,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtB,MAAM,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACN,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YACnE,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC;gBACX,GAAG,MAAM;gBACT,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC;AACpF,CAAC;AAED,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAuB,EACvB,OAAe,EACf,OAA6B;IAE7B,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,mBAAmB,CAAC;IAChD,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAE9C,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,GAAG,KAAK,IAAI,CAAC;IACtB,CAAC;IAED,MAAM,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,kEAAkE;IAClE,OAAO,GAAG,KAAK,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,OAA6B;IAC/E,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,mBAAmB,CAAC;IAChD,MAAM,EAAE,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAExC,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9D,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;AACxD,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAe,EAAE,GAAW;IACrD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1E,OAAO,QAAQ,GAAG,uBAAuB,IAAI,SAAS,IAAI,UAAU,GAAG,kBAAkB,CAAC;AAC5F,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,IAAI,MAAM,CAAC,WAAW,CAAC,2CAA2C,CAAC,qBAAqB,CAAC,CAAC;AACnG,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,qBAAqB,CAAC,CAAS;IACtC,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;AACzC,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,QAAgB;IAC5C,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAClE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/utils/runtime-homes.d.ts

@@ -8,6 +8,9 @@ import type { SkillRuntime } from "./skills.js";
 export declare function getRuntimeHomeEnvVar(runtime: SkillRuntime): string | null;
 /**
  * Returns the default global home directory path for the given runtime.
+ *
+ * Pass `homeDir` to resolve against a base other than the user's real home
+ * directory (useful for sandboxed installs and tests). Defaults to os.homedir().
  */
-export declare function getDefaultRuntimeHome(runtime: SkillRuntime): string;
+export declare function getDefaultRuntimeHome(runtime: SkillRuntime, homeDir?: string): string;
 //# sourceMappingURL=runtime-homes.d.ts.map

package/dist/utils/runtime-homes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-homes.d.ts","sourceRoot":"","sources":["../../src/utils/runtime-homes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA2BhD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAEzE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAEnE"}
+{"version":3,"file":"runtime-homes.d.ts","sourceRoot":"","sources":["../../src/utils/runtime-homes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA2BhD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,MAAqB,GAAG,MAAM,CAGnG"}

package/dist/utils/runtime-homes.js

@@ -13,15 +13,15 @@ const ENV_VAR_MAP = {
     pi: "PI_HOME",
 };
 /**
- * Default global home directory path for each runtime.
+ * Home directory subpath (relative to the home base) for each runtime.
  */
-const DEFAULT_HOME_MAP = {
-    claude: path.join(os.homedir(), ".claude"),
-    codex: path.join(os.homedir(), ".codex"),
-    gemini: path.join(os.homedir(), ".gemini"),
-    cursor: path.join(os.homedir(), ".cursor"),
-    opencode: path.join(os.homedir(), ".config", "opencode"),
-    pi: path.join(os.homedir(), ".pi"),
+const HOME_SUBPATH_MAP = {
+    claude: [".claude"],
+    codex: [".codex"],
+    gemini: [".gemini"],
+    cursor: [".cursor"],
+    opencode: [".config", "opencode"],
+    pi: [".pi"],
 };
 /**
  * Returns the environment variable name that overrides the global home
@@ -34,8 +34,12 @@ export function getRuntimeHomeEnvVar(runtime) {
 }
 /**
  * Returns the default global home directory path for the given runtime.
+ *
+ * Pass `homeDir` to resolve against a base other than the user's real home
+ * directory (useful for sandboxed installs and tests). Defaults to os.homedir().
  */
-export function getDefaultRuntimeHome(runtime) {
-    return DEFAULT_HOME_MAP[runtime] ?? path.join(os.homedir(), `.${runtime}`);
+export function getDefaultRuntimeHome(runtime, homeDir = os.homedir()) {
+    const subpath = HOME_SUBPATH_MAP[runtime] ?? [`.${runtime}`];
+    return path.join(homeDir, ...subpath);
 }
 //# sourceMappingURL=runtime-homes.js.map

package/dist/utils/runtime-homes.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-homes.js","sourceRoot":"","sources":["../../src/utils/runtime-homes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAG9B;;;GAGG;AACH,MAAM,WAAW,GAAwC;IACvD,MAAM,EAAE,mBAAmB;IAC3B,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,mBAAmB;IAC3B,QAAQ,EAAE,iBAAiB,EAAG,8BAA8B;IAC5D,EAAE,EAAE,SAAS;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,gBAAgB,GAAiC;IACrD,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC;IAC1C,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC;IACxC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC;IAC1C,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC;IAC1C,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC;IACxD,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC;CACnC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqB;IACxD,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqB;IACzD,OAAO,gBAAgB,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,IAAI,OAAO,EAAE,CAAC,CAAC;AAC7E,CAAC"}
+{"version":3,"file":"runtime-homes.js","sourceRoot":"","sources":["../../src/utils/runtime-homes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAG9B;;;GAGG;AACH,MAAM,WAAW,GAAwC;IACvD,MAAM,EAAE,mBAAmB;IAC3B,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,mBAAmB;IAC3B,QAAQ,EAAE,iBAAiB,EAAG,8BAA8B;IAC5D,EAAE,EAAE,SAAS;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,gBAAgB,GAAmC;IACvD,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,KAAK,EAAE,CAAC,QAAQ,CAAC;IACjB,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,QAAQ,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;IACjC,EAAE,EAAE,CAAC,KAAK,CAAC;CACZ,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqB;IACxD,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqB,EAAE,UAAkB,EAAE,CAAC,OAAO,EAAE;IACzF,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentex/agent",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "Programmatic execution of AI coding agents (Claude Code, Codex, OpenClaw)",
   "repository": {
     "type": "git",