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>

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.
-  // Agent instructions are loaded by Claude Code from /workspace/agent/CLAUDE.md
-  // (host-composed at spawn, imports /app/CLAUDE.md and fragments) plus
-  // /workspace/agent/CLAUDE.local.md (agent memory) — no need to read them
-  // manually.
-  const instructions = buildSystemPromptAddendum();
+  // Runtime-generated system-prompt addendum: agent identity (name) plus
+  // the live destinations map. Everything else (capabilities, per-module
+  // instructions, per-channel formatting) is loaded by Claude Code from
+  // /workspace/agent/CLAUDE.md — the composed entry imports the shared
+  // base (/app/CLAUDE.md) and each enabled module's fragment. Per-group
+  // 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.