refactor(claude-md): split shared base into module fragments, inject name at runtime

Move every agent-specific instruction out of the shared container/CLAUDE.md
so the base is genuinely universal. Persona/identity now comes from the
system-prompt addendum (buildSystemPromptAddendum now takes assistantName
and prepends "# You are {name}"). Per-module instructions live alongside
each MCP tool source:

  container/agent-runner/src/mcp-tools/core.instructions.md
  container/agent-runner/src/mcp-tools/scheduling.instructions.md
  container/agent-runner/src/mcp-tools/self-mod.instructions.md

composeGroupClaudeMd() scans that directory and emits `module-<name>.md`
fragments as symlinks to /app/src/mcp-tools/<name>.instructions.md (valid
via the existing RO source mount). Skill fragments renamed to
`skill-<name>.md` for naming consistency with `module-*` and `mcp-*`.

Mount tightening so composer-managed files can't be clobbered by agent
writes: nested RO mounts for /workspace/agent/CLAUDE.md and
/workspace/agent/.claude-fragments/. CLAUDE.local.md (per-group memory)
stays RW as the only writable CLAUDE.md-family file.

.gitignore: ignore CLAUDE.local.md, .claude-shared.md, .claude-fragments/
everywhere, and simplify groups/ rules to ignore the whole tree (per-
installation state, not tracked).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitignore

@@ -11,14 +11,14 @@ store/
 data/
 logs/
 
-# Groups - only track base structure and specific CLAUDE.md files
+# Groups - per-installation state, not tracked
 groups/*
-!groups/main/
+
-!groups/global/
+# Composer-managed CLAUDE.md artifacts (regenerated every spawn) and
-groups/main/*
+# per-group memory (CLAUDE.local.md) must never be committed.
-groups/global/*
+**/CLAUDE.local.md
-!groups/main/CLAUDE.md
+**/.claude-shared.md
-!groups/global/CLAUDE.md
+**/.claude-fragments/
 
 # Secrets
 *.keys.json

container/CLAUDE.md

@@ -1,166 +1,27 @@
-# Main
+<!--
+Shared base instructions loaded by every NanoClaw agent. Mounted RO at
+/app/CLAUDE.md, imported via the `.claude-shared.md` symlink from each
+group's composed CLAUDE.md.
 
-You are Main, a personal assistant. You help with tasks, answer questions, and can schedule reminders.
+Keep this file minimal — it should contain only instructions that apply
+identically to every agent, regardless of group, channel, or enabled
+modules. Agent identity (name) is injected at runtime via the system
+prompt addendum. Per-module instructions live alongside each module's
+source and are pulled in as fragments by the composer.
+-->
 
-## What You Can Do
+You are a NanoClaw agent. Your name, destinations, and message-sending rules are provided in the runtime system prompt at the top of each turn.
-
-- Answer questions and have conversations
-- Search the web and fetch content from URLs
-- **Browse the web** with `agent-browser` — open pages, click, fill forms, take screenshots, extract data (run `agent-browser open <url>` to start, then `agent-browser snapshot -i` to see interactive elements)
-- Read and write files in your workspace
-- Run bash commands in your sandbox
-- Schedule tasks to run later or on a recurring basis
-- Send messages back to the chat
 
 ## Communication
 
-Be concise — every message costs the reader's attention.
+Be concise — every message costs the reader's attention. Prefer outcomes over play-by-play; when the work is done, the final message should be about the result, not a transcript of what you did.
 
-### Destinations
+## Workspace
 
-Each turn, your system prompt lists the destinations available to you. If you only have one destination, just write your response directly — it goes there automatically. If you have multiple, wrap each message in a `<message to="name">...</message>` block:
+Files you create are saved in `/workspace/agent/`. Use this for notes, research, or anything that should persist across turns in this group.
 
-```
+The file `CLAUDE.local.md` in your workspace is your per-group memory. Unlike the composed `CLAUDE.md` next to it (which is regenerated on every spawn and read-only), `CLAUDE.local.md` is writable and persists. Record things there that you'll want to remember in future sessions — user preferences, project context, recurring facts. Keep entries short and structured.
-<message to="family">On my way home, 15 minutes</message>
-<message to="worker-1">kick off the pipeline</message>
-```
 
-Inbound messages are labeled with `from="name"` so you can tell which destination they came from and reply using that same name.
+## Conversation history
 
-### Mid-turn updates
+The `conversations/` folder in your workspace holds searchable transcripts of past sessions with this group. Use it to recall prior context when a request references something that happened before. For structured long-lived data, prefer dedicated files (`customers.md`, `preferences.md`, etc.); split any file over ~500 lines into a folder with an index.
-
-Use the `mcp__nanoclaw__send_message` tool to send a message mid-work (before your final output). If you have one destination, `to` is optional; with multiple, specify it. Pace your updates to the length of the work:
-
-- **Short work (a few seconds, ≤2 quick tool calls):** Don't narrate. Just do it and put the result in your final response.
-- **Longer work (many tool calls, web searches, installs, sub-agents):** Send a short acknowledgment right away ("On it — checking the logs now") so the user knows you got the message.
-- **Long-running work (many minutes, multi-step tasks):** Send periodic updates at natural milestones, and especially **before** slow operations like spinning up an explore sub-agent, downloading large files, or installing packages.
-
-**Never narrate micro-steps.** "I'm going to read the file now… okay, I'm reading it… now I'm parsing it…" is noise. Updates should mark meaningful transitions, not every tool call.
-
-**Outcomes, not play-by-play.** When the work is done, the final message should be about the result, not a transcript of what you did.
-
-### Internal thoughts
-
-Wrap reasoning in `<internal>...</internal>` tags to mark it as scratchpad — logged but not sent. With multiple destinations, any text outside of `<message>` blocks is also treated as scratchpad. With a single destination, only explicit `<internal>` tags are scratchpad; the rest of your response is sent.
-
-```
-<internal>Compiled all three reports, ready to summarize.</internal>
-
-Here are the key findings from the research…
-```
-
-### Sub-agents and teammates
-
-When working as a sub-agent or teammate, only use `send_message` if instructed to by the main agent.
-
-## Your Workspace
-
-Files you create are saved in `/workspace/group/`. Use this for notes, research, or anything that should persist.
-
-## Memory
-
-The `conversations/` folder contains searchable history of past conversations. Use this to recall context from previous sessions.
-
-When you learn something important:
-- Create files for structured data (e.g., `customers.md`, `preferences.md`)
-- Split files larger than 500 lines into folders
-- Keep an index in your memory for the files you create
-
-## Message Formatting
-
-Format messages based on the channel you're responding to. Check your group folder name:
-
-### Slack channels (folder starts with `slack_`)
-
-Use Slack mrkdwn syntax. Run `/slack-formatting` for the full reference. Key rules:
-- `*bold*` (single asterisks)
-- `_italic_` (underscores)
-- `<https://url|link text>` for links (NOT `[text](url)`)
-- `•` bullets (no numbered lists)
-- `:emoji:` shortcodes
-- `>` for block quotes
-- No `##` headings — use `*Bold text*` instead
-
-### WhatsApp/Telegram channels (folder starts with `whatsapp_` or `telegram_`)
-
-- `*bold*` (single asterisks, NEVER **double**)
-- `_italic_` (underscores)
-- `•` bullet points
-- ` ``` ` code blocks
-
-No `##` headings. No `[links](url)`. No `**double stars**`.
-
-### Discord channels (folder starts with `discord_`)
-
-Standard Markdown works: `**bold**`, `*italic*`, `[links](url)`, `# headings`.
-
----
-
-## Installing Packages & Tools
-
-Your container is ephemeral — anything installed via `apt-get` or `pnpm install -g` is lost on restart. To install packages that persist, use the self-modification tools:
-
-1. **`install_packages`** — request system (apt) or global npm packages. Requires admin approval.
-2. **`request_rebuild`** — rebuild your container image so approved packages are baked in. Always call this after `install_packages` to apply the changes.
-
-Example flow:
-```
-install_packages({ apt: ["ffmpeg"], npm: ["@xenova/transformers"], reason: "Audio transcription" })
-# → Admin gets an approval card → approves
-request_rebuild({ reason: "Apply ffmpeg + transformers" })
-# → Admin approves → image rebuilt with the packages
-```
-
-**When to use this vs workspace pnpm install:**
-- `pnpm install` in `/workspace/agent/` persists on disk (it's mounted) but isn't on the global PATH — use it for project-level dependencies
-- `install_packages` is for system tools (ffmpeg, imagemagick) and global npm packages that need to be on PATH
-
-### MCP Servers
-
-Use **`add_mcp_server`** to add an MCP server to your configuration, then **`request_rebuild`** to apply. Browse available servers at https://mcp.so — it's a curated directory of high-quality MCP servers. Most Node.js servers run via `pnpm dlx`, e.g.:
-
-```
-add_mcp_server({ name: "memory", command: "pnpm", args: ["dlx", "@modelcontextprotocol/server-memory"] })
-request_rebuild({ reason: "Add memory MCP server" })
-```
-
-## Task Scripts
-
-For any recurring task, use `schedule_task`. This is the scheduling path — tasks persist across sessions and restarts, and support the pre-task `script` hook described below. Other scheduling tools you might discover (e.g. `CronCreate`, `ScheduleWakeup`) are session-scoped SDK builtins and won't behave the way NanoClaw users expect, so stick with `schedule_task`.
-
-To inspect or change existing tasks, use `list_tasks` (returns one row per series with the stable id) and `update_task` / `cancel_task` / `pause_task` / `resume_task`. Prefer `update_task` over cancel + reschedule — it preserves the series id the user already knows.
-
-Frequent agent invocations — especially multiple times a day — consume API credits and can risk account restrictions. If a simple check can determine whether action is needed, add a `script` — it runs first, and the agent is only called when the check passes. This keeps invocations to a minimum.
-
-### How it works
-
-1. You provide a bash `script` alongside the `prompt` when scheduling
-2. When the task fires, the script runs first (30-second timeout)
-3. Script prints JSON to stdout: `{ "wakeAgent": true/false, "data": {...} }`
-4. If `wakeAgent: false` — nothing happens, task waits for next run
-5. If `wakeAgent: true` — you wake up and receive the script's data + prompt
-
-### Always test your script first
-
-Before scheduling, run the script in your sandbox to verify it works:
-
-```bash
-bash -c 'node --input-type=module -e "
-  const r = await fetch(\"https://api.github.com/repos/owner/repo/pulls?state=open\");
-  const prs = await r.json();
-  console.log(JSON.stringify({ wakeAgent: prs.length > 0, data: prs.slice(0, 5) }));
-"'
-```
-
-### When NOT to use scripts
-
-If a task requires your judgment every time (daily briefings, reminders, reports), skip the script — just use a regular prompt.
-
-### Frequent task guidance
-
-If a user wants tasks running more than ~2x daily and a script can't reduce agent wake-ups:
-
-- Explain that each wake-up uses API credits and risks rate limits
-- Suggest restructuring with a script that checks the condition first
-- If the user needs an LLM to evaluate data, suggest using an API key with direct Anthropic API calls inside the script
-- Help the user find the minimum viable frequency

container/agent-runner/src/destinations.ts

@@ -72,8 +72,26 @@ export function findByRouting(
   return row ? rowToEntry(row) : undefined;
 }
 
-/** Generate the system-prompt addendum describing destinations and syntax. */
+/**
-export function buildSystemPromptAddendum(): string {
+ * Generate the system-prompt addendum: agent identity + destination map.
+ *
+ * Identity is injected here (not in the shared CLAUDE.md) because it's
+ * per-agent-group and changes when the operator renames an agent, while
+ * the shared base is identical across all agents.
+ */
+export function buildSystemPromptAddendum(assistantName?: string): string {
+  const sections: string[] = [];
+
+  if (assistantName) {
+    sections.push(['# You are ' + assistantName, '', `Your name is **${assistantName}**. Use it when the channel asks who you are, when introducing yourself, and when signing any message that explicitly calls for a signature.`].join('\n'));
+  }
+
+  sections.push(buildDestinationsSection());
+
+  return sections.join('\n\n');
+}
+
+function buildDestinationsSection(): string {
   const all = getAllDestinations();
 
   if (all.length === 0) {

container/agent-runner/src/index.ts

@@ -45,12 +45,13 @@ async function main(): Promise<void> {
 
   log(`Starting v2 agent-runner (provider: ${providerName})`);
 
-  // Destinations addendum is the only runtime-generated context we inject.
+  // Runtime-generated system-prompt addendum: agent identity (name) plus
-  // Agent instructions are loaded by Claude Code from /workspace/agent/CLAUDE.md
+  // the live destinations map. Everything else (capabilities, per-module
-  // (host-composed at spawn, imports /app/CLAUDE.md and fragments) plus
+  // instructions, per-channel formatting) is loaded by Claude Code from
-  // /workspace/agent/CLAUDE.local.md (agent memory) — no need to read them
+  // /workspace/agent/CLAUDE.md — the composed entry imports the shared
-  // manually.
+  // base (/app/CLAUDE.md) and each enabled module's fragment. Per-group
-  const instructions = buildSystemPromptAddendum();
+  // memory lives in /workspace/agent/CLAUDE.local.md (auto-loaded).
+  const instructions = buildSystemPromptAddendum(config.assistantName || undefined);
 
   // Discover additional directories mounted at /workspace/extra/*
   const additionalDirectories: string[] = [];

container/agent-runner/src/mcp-tools/core.instructions.md

@@ -0,0 +1,19 @@
+## Sending messages
+
+Your final response is delivered via the `## Sending messages` rules in your runtime system prompt (single-destination: just write; multi-destination: use `<message to="name">...</message>` blocks). See that section for the current destination list.
+
+### Mid-turn updates (`send_message`)
+
+Use the `mcp__nanoclaw__send_message` tool to send a message while you're still working (before your final output). If you have one destination, `to` is optional; with multiple, specify it. Pace your updates to the length of the work:
+
+- **Short turn (≤2 quick tool calls):** Don't narrate. Output any response.
+- **Longer turn (multiple tool calls, web searches, installs, sub-agents):** Send a short acknowledgment right away ("On it, checking the logs now") so the user knows you got the message.
+- **Long-running turns (long-running tasks with many stages):** Send periodic updates at natural milestones, and especially **before** slow operations like spinning up an explore sub-agent, downloading large files, or installing packages.
+
+**Never narrate micro-steps.** "I'm going to read the file now… okay, I'm reading it… now I'm parsing it…" is noise. Updates should mark meaningful transitions, not every tool call.
+
+**Outcomes, not play-by-play.** When the turn is done, the final message should be about the result, not a transcript of what you did.
+
+### Internal thoughts
+
+Wrap reasoning in `<internal>...</internal>` tags to mark it as scratchpad — logged but not sent.

container/agent-runner/src/mcp-tools/scheduling.instructions.md

@@ -0,0 +1,40 @@
+## Task scheduling (`schedule_task`)
+
+For any recurring task, use `schedule_task`. This is the scheduling path — tasks persist across sessions and restarts, and support the pre-task `script` hook described below.
+
+To inspect or change existing tasks, use `list_tasks` (returns one row per series with the stable id) and `update_task` / `cancel_task` / `pause_task` / `resume_task`. Prefer `update_task` over cancel + reschedule.
+
+Frequent recurring scheduled tasks — more than a few times a day — consume API credits and can risk account restrictions. You can add a `script` that runs first, and you will only be called when the check passes.
+
+### How it works
+
+1. Provide a bash `script` alongside the `prompt` when scheduling
+2. When the task fires, the script runs first
+3. Script returns: `{ "wakeAgent": true/false, "data": {...} }`
+4. If `wakeAgent: false` — nothing happens, task waits for next run
+5. If `wakeAgent: true` — claude receives the script's data + prompt and handles
+
+### Always test your script first
+
+Before scheduling, run the script directly to verify it works:
+
+```bash
+bash -c 'node --input-type=module -e "
+  const r = await fetch(\"https://api.github.com/repos/owner/repo/pulls?state=open\");
+  const prs = await r.json();
+  console.log(JSON.stringify({ wakeAgent: prs.length > 0, data: prs.slice(0, 5) }));
+"'
+```
+
+### When NOT to use scripts
+
+If a task requires your judgment every time (daily briefings, reminders, reports), skip the script — just use a regular prompt. Do not attempt to do things like sentiment analysis or advanced nlp in scripts.
+
+### Frequent task guidance
+
+If a user wants a task to run more than a few times a day and a script can't be used:
+
+- Explain that each time the task fires it uses API credits and risks rate limits
+- Suggest adjusting the task requirements in a way that will allow you to use a script
+- If the user needs an LLM to evaluate data, suggest using an API key with direct Anthropic API calls inside the script
+- Help the user find the minimum viable frequency

container/agent-runner/src/mcp-tools/self-mod.instructions.md

@@ -0,0 +1,25 @@
+## Installing packages & tools
+
+To install packages that persist, use the self-modification tools:
+
+**`install_packages`** — request system (apt) or global npm packages. Requires admin approval.
+
+Example flow:
+```
+install_packages({ apt: ["ffmpeg"], npm: ["@xenova/transformers"], reason: "Audio transcription" })
+# → Admin gets an approval card → approves
+```
+
+**When to use this vs workspace `pnpm install`:**
+- `pnpm install` if you only need it temporarily to do one task. Will not be available in subsequent truns.
+- `install_packages` persists for all future turns. Use especially if the user specifically asks you to add a capability
+
+### MCP servers (`add_mcp_server`)
+
+Use **`add_mcp_server`** to add an MCP server to your configuration. Browse available servers at https://mcp.so — it's a curated directory of high-quality MCP servers. Most Node.js servers run via `pnpm dlx`, e.g.:
+
+```
+add_mcp_server({ name: "memory", command: "pnpm", args: ["dlx", "@modelcontextprotocol/server-memory"] })
+```
+
+Do not ask the user to give you credentials. Credentials are managed by the user in the OneCLI agent vault. Add a "placeholder" string instead of the credential, and ask the user to add the credential to the vault. You can make a test request before the secret is added and the vault proxy will respond with the local url of the vault dashboard on the user's machine and a link to a form for adding that specific credential.

src/claude-md-compose.ts

@@ -26,6 +26,11 @@ import type { AgentGroup } from './types.js';
 // dance instead of existsSync), valid inside the container via RO mounts.
 const SHARED_CLAUDE_MD_CONTAINER_PATH = '/app/CLAUDE.md';
 const SHARED_SKILLS_CONTAINER_BASE = '/app/skills';
+const SHARED_MCP_TOOLS_CONTAINER_BASE = '/app/src/mcp-tools';
+
+// Host-side source paths used to discover fragment sources at compose time.
+// Resolved at call time (process.cwd() = project root) so tests can swap cwd.
+const MCP_TOOLS_HOST_SUBPATH = path.join('container', 'agent-runner', 'src', 'mcp-tools');
 
 const COMPOSED_HEADER = '<!-- Composed at spawn — do not edit. Edit CLAUDE.local.md for per-group content. -->';
 
@@ -59,7 +64,7 @@ export function composeGroupClaudeMd(group: AgentGroup): void {
     for (const skillName of fs.readdirSync(skillsHostDir)) {
       const hostFragment = path.join(skillsHostDir, skillName, 'instructions.md');
       if (fs.existsSync(hostFragment)) {
-        desired.set(`${skillName}.md`, {
+        desired.set(`skill-${skillName}.md`, {
           type: 'symlink',
           content: `${SHARED_SKILLS_CONTAINER_BASE}/${skillName}/instructions.md`,
         });
@@ -67,7 +72,25 @@ export function composeGroupClaudeMd(group: AgentGroup): void {
     }
   }
 
-  // MCP server fragments — inline instructions from container.json.
+  // Built-in module fragments — every MCP tool source file that ships a
+  // sibling `<name>.instructions.md`. These describe how the agent should
+  // use that module's MCP tools (schedule_task, install_packages, etc.).
+  // Always included — these are built-in, not toggleable.
+  const mcpToolsHostDir = path.join(process.cwd(), MCP_TOOLS_HOST_SUBPATH);
+  if (fs.existsSync(mcpToolsHostDir)) {
+    for (const entry of fs.readdirSync(mcpToolsHostDir)) {
+      const match = entry.match(/^(.+)\.instructions\.md$/);
+      if (!match) continue;
+      const moduleName = match[1];
+      desired.set(`module-${moduleName}.md`, {
+        type: 'symlink',
+        content: `${SHARED_MCP_TOOLS_CONTAINER_BASE}/${entry}`,
+      });
+    }
+  }
+
+  // MCP server fragments — inline instructions from container.json for
+  // user-added external MCP servers.
   for (const [name, mcp] of Object.entries(config.mcpServers)) {
     if (mcp.instructions) {
       desired.set(`mcp-${name}.md`, {

src/config.ts

@@ -5,13 +5,7 @@ import { readEnvFile } from './env.js';
 import { isValidTimezone } from './timezone.js';
 
 // Read config values from .env (falls back to process.env).
-const envConfig = readEnvFile([
+const envConfig = readEnvFile(['ASSISTANT_NAME', 'ASSISTANT_HAS_OWN_NUMBER', 'ONECLI_URL', 'ONECLI_API_KEY', 'TZ']);
-  'ASSISTANT_NAME',
-  'ASSISTANT_HAS_OWN_NUMBER',
-  'ONECLI_URL',
-  'ONECLI_API_KEY',
-  'TZ',
-]);
 
 export const ASSISTANT_NAME = process.env.ASSISTANT_NAME || envConfig.ASSISTANT_NAME || 'Andy';
 export const ASSISTANT_HAS_OWN_NUMBER =

src/container-runner.ts

@@ -215,7 +215,7 @@ function buildMounts(
   // Session folder at /workspace (contains inbound.db, outbound.db, outbox/, .claude/)
   mounts.push({ hostPath: sessDir, containerPath: '/workspace', readonly: false });
 
-  // Agent group folder at /workspace/agent (RW for working files + CLAUDE.md)
+  // Agent group folder at /workspace/agent (RW for working files + CLAUDE.local.md)
   mounts.push({ hostPath: groupDir, containerPath: '/workspace/agent', readonly: false });
 
   // container.json — nested RO mount on top of RW group dir so the agent
@@ -225,6 +225,22 @@ function buildMounts(
     mounts.push({ hostPath: containerJsonPath, containerPath: '/workspace/agent/container.json', readonly: true });
   }
 
+  // Composer-managed CLAUDE.md artifacts — nested RO mounts. These are
+  // regenerated from the shared base + fragments on every spawn; any
+  // agent-side writes would be clobbered, so enforce read-only. Only
+  // CLAUDE.local.md (per-group memory) remains RW via the group-dir mount.
+  // `.claude-shared.md` is a symlink whose target (`/app/CLAUDE.md`) is
+  // already RO-mounted, so writes through it fail regardless — no need for
+  // a nested mount there.
+  const composedClaudeMd = path.join(groupDir, 'CLAUDE.md');
+  if (fs.existsSync(composedClaudeMd)) {
+    mounts.push({ hostPath: composedClaudeMd, containerPath: '/workspace/agent/CLAUDE.md', readonly: true });
+  }
+  const fragmentsDir = path.join(groupDir, '.claude-fragments');
+  if (fs.existsSync(fragmentsDir)) {
+    mounts.push({ hostPath: fragmentsDir, containerPath: '/workspace/agent/.claude-fragments', readonly: true });
+  }
+
   // Global memory directory — always read-only.
   const globalDir = path.join(GROUPS_DIR, 'global');
   if (fs.existsSync(globalDir)) {