@agentworkforce/cli 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -14,6 +14,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Persona source config supports `defaultCreateTarget` for the implicit create target.
 - `--version`/`-v` now prints the CLI package version.
 
+## [0.10.0] - 2026-05-08
+
+### Released
+
+- v0.10.0
+
 ## [0.8.0] - 2026-05-07
 
 ### Added

package/README.md

@@ -515,6 +515,10 @@ library has no `extends`.
   },
   "env": { … },                // union, local wins per key
   "mcpServers": { … },         // union by server name, local wins per key
+  "mount": {                   // Relayfile file scope; pattern arrays append
+    "ignoredPatterns": ["…"],
+    "readonlyPatterns": ["…"]
+  },
   "permissions": {             // allow/deny union (dedup), mode replaces
     "allow": ["…"], "deny": ["…"], "mode": "default"
   },
@@ -617,6 +621,9 @@ Use this when you are not extending an existing persona:
     "deny": ["Bash(npm publish *)"],
     "mode": "default"
   },
+  "mount": {
+    "readonlyPatterns": ["*"]
+  },
   "tiers": {
     "best": {
       "harness": "codex",
@@ -729,12 +736,39 @@ either a literal string or an env reference. Two forms:
 Secrets therefore stay in your shell/keychain, not in files on disk — local
 persona JSON remains commit-safe as long as you only use references.
 
+## Relayfile mount rules
+
+Interactive `claude` and `opencode` sessions run inside a Relayfile mount by
+default. File visibility and writability are controlled by the persona's
+`mount` block plus project-level dotfiles:
+
+```jsonc
+{
+  "mount": {
+    "ignoredPatterns": ["secrets/**", ".env*"],
+    "readonlyPatterns": [
+      "*",
+      "!docs/",
+      "!docs/**"
+    ]
+  }
+}
+```
+
+- `ignoredPatterns` are omitted from the mount entirely.
+- `readonlyPatterns` are copied into the mount but edits do not sync back.
+- Patterns use gitignore semantics, so later `!` negations can reopen paths.
+- Persona patterns append to inherited persona patterns. At launch, the CLI
+  also merges project-root `.agentignore`, `.agentreadonly`,
+  `.<personaId>.agentignore`, and `.<personaId>.agentreadonly`.
+
 ## Permissions
 
 A persona can declare which tool calls the harness should auto-approve, block,
 or gate via a permission mode. Skip the approval prompts for trusted tools
 (e.g. a persona's own MCP server); keep them on for anything you want to
-eyeball.
+eyeball. File visibility and writability are not defined here; use Relayfile
+mount rules (`.agentignore` / `.agentreadonly`) for that.
 
 ```jsonc
 {
@@ -747,9 +781,8 @@ eyeball.
 ```
 
 - **Tool patterns** are passed through verbatim; use the harness's native
-  grammar. For Claude Code: `Bash(<pattern>)`, `Edit(<glob>)`,
-  `mcp__<server>` (all tools from that server), `mcp__<server>__<tool>`
-  (specific tool).
+  grammar. For Claude Code: `Bash(<pattern>)`, `mcp__<server>` (all tools
+  from that server), `mcp__<server>__<tool>` (specific tool).
 - **Harness support today:** only `claude` is wired (flags: `--allowedTools`,
   `--disallowedTools`, `--permission-mode`). codex and opencode emit a
   warning and fall back to their defaults when `permissions` is set.
@@ -922,13 +955,23 @@ stage dir conflicts with something else (network filesystem, read-only
 
 By default, claude and opencode interactive sessions run inside a
 [`@relayfile/local-mount`](https://www.npmjs.com/package/@relayfile/local-mount)
-symlink mount that hides repo-level harness configuration from the session
-and routes skill-install writes into the sandbox — so the model sees
-persona context + user-level context, and nothing the repo itself declares.
-Codex sessions never mount (no harness-side support).
+mount that hides repo-level harness configuration from the session, applies
+the persona `mount` block plus Relayfile `.agentignore` / `.agentreadonly`
+rules, and routes skill-install writes into the sandbox — so the model sees
+persona context + user-level context, and only the project files the mount
+exposes. Codex sessions never mount (no harness-side support).
 
 `--install-in-repo` opts out and runs against the real cwd.
 
+The CLI reads these files from the project root before creating the mount:
+
+| File | Effect |
+| --- | --- |
+| `.agentignore` | Hide matching files for every persona. |
+| `.agentreadonly` | Copy matching files into the mount as read-only and skip syncing their edits back. |
+| `.<personaId>.agentignore` | Hide matching files only for that persona. |
+| `.<personaId>.agentreadonly` | Make matching files read-only only for that persona. |
+
 **What's hidden (gitignore semantics, at any depth):**
 
 For claude:

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { type Harness } from '@agentworkforce/workload-router';
+import { type Harness, type PersonaMount, type PersonaSelection, type SidecarMdMode } from '@agentworkforce/workload-router';
 export declare const CLI_VERSION: string;
 export declare const CREATE_SELECTOR = "persona-maker@best";
 /**
@@ -40,7 +40,7 @@ export declare function assertSafeRelativePath(relPath: string): void;
  * Applied by `@relayfile/local-mount` with gitignore semantics, so bare names
  * match at any depth in the project tree (e.g. `.claude` hides both
  * `./.claude/` and `./packages/foo/.claude/`). */
-export declare const CLEAN_IGNORED_PATTERNS: readonly ["CLAUDE.md", "CLAUDE.local.md", ".claude", ".mcp.json"];
+export declare const CLEAN_IGNORED_PATTERNS: readonly ["CLAUDE.md", "CLAUDE.local.md", ".claude", ".mcp.json", "AGENTS.md"];
 /**
  * Skill-install artifacts that should never be copied into the mount nor
  * synced back to the real repo. Applied to non-claude interactive sessions
@@ -51,7 +51,18 @@ export declare const CLEAN_IGNORED_PATTERNS: readonly ["CLAUDE.md", "CLAUDE.loca
  * Claude sessions use `installRoot` for out-of-repo staging instead, so
  * these patterns don't apply there.
  */
-export declare const SKILL_INSTALL_IGNORED_PATTERNS: readonly [".agents", ".claude/skills", ".factory/skills", ".kiro/skills", "skills", ".opencode", ".skills", "prpm.lock", "skills-lock.json"];
+export declare const SKILL_INSTALL_IGNORED_PATTERNS: readonly [".agents", ".claude/skills", ".factory/skills", ".kiro/skills", "skills", ".opencode", ".skills", "prpm.lock", "skills-lock.json", "AGENTS.md"];
+export interface RelayfileMountPatterns {
+    ignoredPatterns: string[];
+    readonlyPatterns: string[];
+}
+export declare function buildRelayfileMountPatterns(input: {
+    projectDir: string;
+    personaId: string;
+    harness: Harness;
+    mount?: PersonaMount;
+    configFilePaths?: readonly string[];
+}): RelayfileMountPatterns;
 /**
  * Build the block appended to `<mount>/.git/info/exclude` so untracked-and-
  * hidden files (e.g. `.claude/skills/` materialized by skill installs, or
@@ -78,6 +89,37 @@ export declare function buildMountGitExcludeBlock(patterns: readonly string[]):
  * writes here are sandboxed and never leak to the user's main checkout.
  */
 export declare function configureGitForMount(mountDir: string, patterns: readonly string[]): void;
+/**
+ * Persona-supplied sidecar markdown materialized into a sandbox mount.
+ * Pure data carrier — `runInteractive` translates it into the on-disk
+ * write inside `onBeforeLaunch` (mount path) and warns/skips when the
+ * harness has no mount (codex / `--install-in-repo`).
+ */
+export interface ResolvedSidecar {
+    /** Filename inside the mount: `CLAUDE.md` (claude) or `AGENTS.md` (opencode). */
+    mountFile: 'CLAUDE.md' | 'AGENTS.md';
+    /** Persona-author content. Already inlined for built-ins; read from disk for local. */
+    personaContent: string;
+    mode: SidecarMdMode;
+}
+/**
+ * Resolve the sidecar for a given selection + harness, returning the
+ * persona-author content the runtime should materialize into the mount.
+ * Returns `{}` when no sidecar applies (no path/content set, or harness
+ * doesn't support sidecar files at all). Read errors surface as a warning
+ * string so the caller can drop the sidecar gracefully rather than
+ * failing the whole session.
+ */
+export declare function loadSidecarForSelection(selection: PersonaSelection): {
+    sidecar?: ResolvedSidecar;
+    warning?: string;
+};
+/**
+ * Compute the bytes to write into the mount for a sidecar. In `extend`
+ * mode, prepends the user's real-cwd file (if any) joined to the persona
+ * content with `\n\n---\n\n`. Pure — exposed for unit tests.
+ */
+export declare function buildSidecarBody(sidecar: ResolvedSidecar, realCwdDir: string): string;
 /**
  * Decide whether to run the interactive session inside a
  * `@relayfile/local-mount` sandbox.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgBA,OAAO,EAOL,KAAK,OAAO,EAMb,MAAM,iCAAiC,CAAC;AA8IzC,eAAO,MAAM,WAAW,QAAuB,CAAC;AAChD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAgDpD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AA6ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,mEAKzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,8IAajC,CAAC;AAEX;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AAwmBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CA+B5E;AAolBD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6D1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAwBA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CA4DA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAgBA,OAAO,EAQL,KAAK,OAAO,EAEZ,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAIrB,KAAK,aAAa,EACnB,MAAM,iCAAiC,CAAC;AA8IzC,eAAO,MAAM,WAAW,QAAuB,CAAC;AAChD,eAAO,MAAM,eAAe,uBAAuB,CAAC;AAgDpD;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAExF;AAyJD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAe5D;AAED;;;kDAGkD;AAClD,eAAO,MAAM,sBAAsB,gFAUzB,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,2JAiBjC,CAAC;AAEX,MAAM,WAAW,sBAAsB;IACrC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,GAAG,sBAAsB,CAqBzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAU7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAuCxF;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,SAAS,EAAE,WAAW,GAAG,WAAW,CAAC;IACrC,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,aAAa,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,gBAAgB,GAC1B;IAAE,OAAO,CAAC,EAAE,eAAe,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAqDjD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,MAAM,GACjB,MAAM,CAkBR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,aAAa,UAAQ,GACpB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAKvB;AA8nBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CA+B5E;AAkmBD,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA6D1C;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACvD,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAwBA;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG;IACxD,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CA4DA"}

package/dist/cli.js

@@ -5,9 +5,9 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync,
 import { constants, homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { HARNESS_VALUES, PERSONA_TAGS, PERSONA_TIERS, personaCatalog, routingProfiles, useSelection } from '@agentworkforce/workload-router';
+import { HARNESS_VALUES, PERSONA_TAGS, PERSONA_TIERS, personaCatalog, resolveSidecar, routingProfiles, useSelection } from '@agentworkforce/workload-router';
 import { buildInteractiveSpec, detectHarnesses, formatDropWarnings, MissingPersonaInputError, renderPersonaInputs, resolvePersonaInputs, resolveMcpServersLenient, resolveStringMapLenient } from '@agentworkforce/harness-kit';
-import { launchOnMount } from '@relayfile/local-mount';
+import { launchOnMount, readAgentDotfiles } from '@relayfile/local-mount';
 import ora from 'ora';
 import { buildPersonaSourceDirectories, defaultCwdPersonaDir, loadLocalPersonas, loadPersonaSourceConfig, normalizePersonaDir, savePersonaSourceConfig } from './local-personas.js';
 import { installPersonas } from './persona-install.js';
@@ -187,6 +187,7 @@ function buildSelection(spec, tier, kind) {
         ...rawRuntime,
         systemPrompt: resolveSystemPromptPlaceholders(rawRuntime.systemPrompt, rawRuntime.harness)
     };
+    const sidecar = resolveSidecar(spec, tier);
     return {
         personaId: spec.id,
         tier,
@@ -196,7 +197,18 @@ function buildSelection(spec, tier, kind) {
         ...(spec.inputs ? { inputs: spec.inputs } : {}),
         ...(spec.env ? { env: spec.env } : {}),
         ...(spec.mcpServers ? { mcpServers: spec.mcpServers } : {}),
-        ...(spec.permissions ? { permissions: spec.permissions } : {})
+        ...(spec.permissions ? { permissions: spec.permissions } : {}),
+        ...(spec.mount ? { mount: spec.mount } : {}),
+        ...(sidecar.claudeMd ? { claudeMd: sidecar.claudeMd } : {}),
+        ...(sidecar.claudeMdContent ? { claudeMdContent: sidecar.claudeMdContent } : {}),
+        ...(sidecar.claudeMd || sidecar.claudeMdContent
+            ? { claudeMdMode: sidecar.claudeMdMode }
+            : {}),
+        ...(sidecar.agentsMd ? { agentsMd: sidecar.agentsMd } : {}),
+        ...(sidecar.agentsMdContent ? { agentsMdContent: sidecar.agentsMdContent } : {}),
+        ...(sidecar.agentsMd || sidecar.agentsMdContent
+            ? { agentsMdMode: sidecar.agentsMdMode }
+            : {})
     };
 }
 function emitDropWarnings(lines) {
@@ -368,7 +380,12 @@ export const CLEAN_IGNORED_PATTERNS = [
     'CLAUDE.md',
     'CLAUDE.local.md',
     '.claude',
-    '.mcp.json'
+    '.mcp.json',
+    // Per-persona AGENTS.md sidecars get materialized into the mount when
+    // running under opencode; without this the user's real-cwd AGENTS.md
+    // would copy in (masking the persona content) and writes from
+    // onBeforeLaunch would sync back out.
+    'AGENTS.md'
 ];
 /**
  * Skill-install artifacts that should never be copied into the mount nor
@@ -392,8 +409,32 @@ export const SKILL_INSTALL_IGNORED_PATTERNS = [
     '.skills',
     // provider lockfiles written at the repo root
     'prpm.lock',
-    'skills-lock.json'
+    'skills-lock.json',
+    // Per-persona AGENTS.md sidecars (opencode harness) get materialized
+    // into the mount; hide so the real-cwd AGENTS.md isn't copied in and
+    // the persona-written copy doesn't sync back out.
+    'AGENTS.md'
 ];
+export function buildRelayfileMountPatterns(input) {
+    const dotfiles = readAgentDotfiles(input.projectDir, {
+        agentName: input.personaId
+    });
+    const builtInIgnored = input.harness === 'claude'
+        ? CLEAN_IGNORED_PATTERNS
+        : SKILL_INSTALL_IGNORED_PATTERNS;
+    return {
+        ignoredPatterns: [
+            ...dotfiles.ignoredPatterns,
+            ...(input.mount?.ignoredPatterns ?? []),
+            ...builtInIgnored,
+            ...(input.configFilePaths ?? [])
+        ],
+        readonlyPatterns: [
+            ...dotfiles.readonlyPatterns,
+            ...(input.mount?.readonlyPatterns ?? [])
+        ]
+    };
+}
 /**
  * Build the block appended to `<mount>/.git/info/exclude` so untracked-and-
  * hidden files (e.g. `.claude/skills/` materialized by skill installs, or
@@ -465,6 +506,96 @@ export function configureGitForMount(mountDir, patterns) {
         }
     }
 }
+/**
+ * Resolve the sidecar for a given selection + harness, returning the
+ * persona-author content the runtime should materialize into the mount.
+ * Returns `{}` when no sidecar applies (no path/content set, or harness
+ * doesn't support sidecar files at all). Read errors surface as a warning
+ * string so the caller can drop the sidecar gracefully rather than
+ * failing the whole session.
+ */
+export function loadSidecarForSelection(selection) {
+    const harness = selection.runtime.harness;
+    if (harness !== 'claude' && harness !== 'opencode')
+        return {};
+    if (harness === 'claude') {
+        if (selection.claudeMdContent) {
+            return {
+                sidecar: {
+                    mountFile: 'CLAUDE.md',
+                    personaContent: selection.claudeMdContent,
+                    mode: selection.claudeMdMode ?? 'overwrite'
+                }
+            };
+        }
+        if (selection.claudeMd) {
+            try {
+                const content = readFileSync(selection.claudeMd, 'utf8');
+                return {
+                    sidecar: {
+                        mountFile: 'CLAUDE.md',
+                        personaContent: content,
+                        mode: selection.claudeMdMode ?? 'overwrite'
+                    }
+                };
+            }
+            catch (err) {
+                return { warning: `claudeMd: could not read ${selection.claudeMd}: ${err.message}` };
+            }
+        }
+        return {};
+    }
+    if (selection.agentsMdContent) {
+        return {
+            sidecar: {
+                mountFile: 'AGENTS.md',
+                personaContent: selection.agentsMdContent,
+                mode: selection.agentsMdMode ?? 'overwrite'
+            }
+        };
+    }
+    if (selection.agentsMd) {
+        try {
+            const content = readFileSync(selection.agentsMd, 'utf8');
+            return {
+                sidecar: {
+                    mountFile: 'AGENTS.md',
+                    personaContent: content,
+                    mode: selection.agentsMdMode ?? 'overwrite'
+                }
+            };
+        }
+        catch (err) {
+            return { warning: `agentsMd: could not read ${selection.agentsMd}: ${err.message}` };
+        }
+    }
+    return {};
+}
+/**
+ * Compute the bytes to write into the mount for a sidecar. In `extend`
+ * mode, prepends the user's real-cwd file (if any) joined to the persona
+ * content with `\n\n---\n\n`. Pure — exposed for unit tests.
+ */
+export function buildSidecarBody(sidecar, realCwdDir) {
+    if (sidecar.mode === 'extend') {
+        const realPath = join(realCwdDir, sidecar.mountFile);
+        try {
+            const realContent = readFileSync(realPath, 'utf8');
+            return `${realContent}\n\n---\n\n${sidecar.personaContent}`;
+        }
+        catch (err) {
+            // Only "missing path" errors degrade to overwrite. Real I/O
+            // problems (EACCES, EISDIR, …) propagate so callers see them
+            // instead of silently dropping the user's CLAUDE.md/AGENTS.md.
+            const code = err.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                return sidecar.personaContent;
+            }
+            throw err;
+        }
+    }
+    return sidecar.personaContent;
+}
 /**
  * Decide whether to run the interactive session inside a
  * `@relayfile/local-mount` sandbox.
@@ -500,6 +631,21 @@ async function runInteractive(selection, options = {}) {
     // below). The --install-in-repo flag forces legacy in-repo installs
     // across the board.
     const useClean = decideCleanMode(runtime.harness, options.installInRepo === true).useClean;
+    // Per-persona CLAUDE.md / AGENTS.md: load the author content if any. The
+    // file is materialized into the mount inside onBeforeLaunch (claude/
+    // opencode default). Without a mount (codex, --install-in-repo) we
+    // skip-and-warn — writing into the real cwd would pollute the user's
+    // repo and is explicitly out of scope.
+    const sidecarLookup = loadSidecarForSelection(effectiveSelection);
+    if (sidecarLookup.warning) {
+        process.stderr.write(`warning: ${sidecarLookup.warning}\n`);
+    }
+    const resolvedSidecar = useClean ? sidecarLookup.sidecar : undefined;
+    if (sidecarLookup.sidecar && !useClean) {
+        process.stderr.write(`warning: persona declares ${sidecarLookup.sidecar.mountFile} but no sandbox mount is available (` +
+            `${runtime.harness === 'codex' ? 'codex harness has no mount' : '--install-in-repo disengages the mount'})` +
+            `; skipping sidecar materialization to avoid writing into your repo.\n`);
+    }
     // A session dir is needed whenever we either (a) stage skills out-of-repo
     // via claude's installRoot, or (b) open a mount. Both engage for claude/
     // opencode by default; --install-in-repo disengages both.
@@ -608,9 +754,6 @@ async function runInteractive(selection, options = {}) {
     // copied in from the real repo nor synced back on exit.
     if (useClean && sessionRoot) {
         const mountDir = sessionMountDir(sessionRoot);
-        const ignoredPatterns = runtime.harness === 'claude'
-            ? [...CLEAN_IGNORED_PATTERNS]
-            : [...SKILL_INSTALL_IGNORED_PATTERNS];
         // Anything we materialize into the mount via onBeforeLaunch must be
         // hidden from the mount-mirror in both directions: without this, any
         // opencode.json already present in the real repo would be copied into
@@ -618,9 +761,13 @@ async function runInteractive(selection, options = {}) {
         // fresh write from onBeforeLaunch would sync back out on exit and
         // pollute the user's working tree. Added dynamically so this stays
         // generic for any future configFile producer.
-        for (const file of spec.configFiles) {
-            ignoredPatterns.push(file.path);
-        }
+        const { ignoredPatterns, readonlyPatterns } = buildRelayfileMountPatterns({
+            projectDir: process.cwd(),
+            personaId,
+            harness: runtime.harness,
+            mount: effectiveSelection.mount,
+            configFilePaths: spec.configFiles.map((file) => file.path)
+        });
         process.stderr.write(`• sandbox mount → ${mountDir}\n`);
         // Three-stage SIGINT handler layered on top of launchOnMount's own signal
         // forwarding. launchOnMount catches the first SIGINT to kill the child
@@ -696,6 +843,7 @@ async function runInteractive(selection, options = {}) {
                 // `git push` to persist work — local-only commits evaporate with
                 // the session.
                 includeGit: true,
+                readonlyPatterns,
                 // Second Ctrl-C aborts this signal → local-mount skips autosync's
                 // draining reconcile and returns the partial syncBack count. Cleanup
                 // still runs, so there's no leaked mount dir.
@@ -745,6 +893,10 @@ async function runInteractive(selection, options = {}) {
                         mkdirSync(dirname(target), { recursive: true });
                         writeFileSync(target, file.contents, 'utf8');
                     }
+                    if (resolvedSidecar) {
+                        const body = buildSidecarBody(resolvedSidecar, process.cwd());
+                        writeFileSync(join(dir, resolvedSidecar.mountFile), body, 'utf8');
+                    }
                 }
             });
             return result.exitCode;
@@ -1454,6 +1606,20 @@ function formatPersonaShow(spec, source, tiers, tierNote) {
             lines.push(`  deny:  ${perms.deny.join(', ')}`);
     }
     lines.push('');
+    lines.push('MOUNT');
+    const mount = spec.mount;
+    if (!mount || (!mount.ignoredPatterns?.length && !mount.readonlyPatterns?.length)) {
+        lines.push('  (none)');
+    }
+    else {
+        if (mount.ignoredPatterns?.length) {
+            lines.push(`  ignored:  ${mount.ignoredPatterns.join(', ')}`);
+        }
+        if (mount.readonlyPatterns?.length) {
+            lines.push(`  readonly: ${mount.readonlyPatterns.join(', ')}`);
+        }
+    }
+    lines.push('');
     lines.push('ENV');
     const envKeys = Object.keys(spec.env ?? {});
     if (envKeys.length === 0) {