diff --git a/AGENTS.md b/AGENTS.md
index 817cf72a0..e6d3134da 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,10 +1,10 @@
 # oh-my-opencode — OpenCode Plugin
 
-**Generated:** 2026-05-08 | **Commit:** cd31d2a1a | **Branch:** dev
+**Generated:** 2026-05-14 | **Commit:** 5ffbe0e24 | **Branch:** dev | **Release:** v4.1.1
 
 ## OVERVIEW
 
-OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 52–59 lifecycle hooks (base / +team-mode) across 57 dirs, 20–39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), and Claude Code compatibility. **1967 TypeScript files (1304 source + 663 test), 278k LOC, 120 barrel `index.ts` files.** Entry: `src/index.ts` → 7-step init.
+OpenCode plugin (npm: `oh-my-opencode`, dual-published as `oh-my-openagent` during the rename transition) extending OpenCode with 11 agents, 54–61 lifecycle hooks (base / +team-mode) across 58 dirs, 20–39 tools (gated by config flags including team-mode), 3-tier MCP system (built-in + .mcp.json + skill-embedded), Hashline LINE#ID edit tool, IntentGate keyword detector, Team Mode (parallel multi-agent coordination, OFF by default), Boulder feature (boulder-state work tracking + cli/boulder subcommand), configurable agent ordering, and Claude Code compatibility. **`src/` contains 2034 TypeScript files (1337 source + 697 test), ~292k LOC, 122 barrel `index.ts` files.** Entry: `src/index.ts` → 7-step init.
 
 ## STRUCTURE
 
@@ -18,27 +18,30 @@ oh-my-opencode/
 │   ├── create-tools.ts       # ToolRegistry composition
 │   ├── create-hooks.ts       # 5-tier hook composition
 │   ├── agents/               # 11 agents (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior)
-│   ├── hooks/                # ~50 lifecycle hooks across 57 dirs
+│   ├── hooks/                # ~52 lifecycle hooks across 58 dirs (incl. 5 zauc-mocks + 1 shared)
 │   ├── tools/                # 16 tool dirs; produces 20–39 tools (config-gated)
-│   ├── features/             # 20 feature modules (incl. team-mode, background-agent, skill-mcp-manager, openclaw, etc.)
-│   ├── shared/               # 258 utility files; logger → /tmp/oh-my-opencode.log
-│   ├── config/               # Zod v4 schema system (32 schema files)
-│   ├── cli/                  # CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version
+│   ├── features/             # 20 feature modules (incl. team-mode, background-agent, skill-mcp-manager, openclaw, boulder-state, etc.)
+│   ├── shared/               # 278 utility files (170 non-test); logger → /tmp/oh-my-opencode.log
+│   ├── config/               # Zod v4 schema system (30 schema files)
+│   ├── cli/                  # CLI: install, run, doctor, mcp-oauth, refresh-model-capabilities, get-local-version, boulder
 │   ├── mcp/                  # 3 built-in remote MCPs (websearch, context7, grep_app)
 │   ├── plugin/               # 10 OpenCode hook handlers + 5-tier hook composition
 │   ├── plugin-handlers/      # 6-phase config loading pipeline
 │   ├── openclaw/             # Bidirectional external integration (Discord/Telegram/HTTP/shell + reply listener daemon)
+│   ├── generated/            # model-capabilities.generated.json (refreshed via build:model-capabilities)
 │   └── testing/              # Test utilities
 ├── web/                      # Marketing site (Next.js 15 + Cloudflare Workers, deployed to ohmyopenagent.com via opennextjs-cloudflare). Independent package with own bun.lock — see web/AGENTS.md
 ├── packages/                 # 11 platform-specific compiled binary packages (darwin/linux/windows, AVX2 + baseline)
 ├── bin/                      # Platform-detection JS shim (oh-my-opencode + oh-my-openagent)
 ├── script/                   # Build/publish automation (singular, not scripts/)
-├── docs/                     # User-facing docs (guide/, reference/, examples/, legal/, manifesto.md, superpowers/)
+├── docs/                     # User-facing docs (guide/, reference/, examples/, legal/, manifesto.md, superpowers/, troubleshooting/)
 ├── assets/                   # oh-my-opencode.schema.json (auto-generated from Zod)
 ├── signatures/               # CLA signature registry (cla.json)
 ├── postinstall.mjs           # Verifies platform binary + OpenCode version
 ├── test-setup.ts             # Bun test preload (resets state between tests)
 ├── bun-test.d.ts             # Custom bun:test type augmentations
+├── .opencode/                # Project-scope skills + commands (skills/, command/) + background-tasks state
+├── .agents/                  # Mirrored project-scope skills + commands (recent migration target)
 ├── .sisyphus/                # AI agent workspace (run-continuation/, plans/, tasks/, notepads/)
 └── .local-ignore/            # Dev-only test fixtures + PR worktrees
 ```
@@ -166,7 +169,7 @@ Schema autocomplete: `"$schema": "https://raw.githubusercontent.com/code-yeongyu
 
 - **Canonical agent order:** Sisyphus → Hephaestus → Prometheus → Atlas. Enforced by `installAgentSortShim()` (patches `Array.prototype.toSorted`/`.sort` narrowly when the array contains ≥2 canonical core agents). See [`src/plugin-handlers/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/plugin-handlers/AGENTS.md) for the full history of why this exists.
 - **Hashline edit + read pairing:** Every `Read` tool output is tagged with `LINE#ID` content hashes; `hashline_edit` validates the hash before applying. Stale hash → reject.
-- **5-tier hook composition:** Session (24) + ToolGuard (14) + Transform (5) + Continuation (7) + Skill (2) = 52 base. With `team_mode.enabled`: +1 ToolGuard (`team-tool-gating`), +2 Transform (`team-mode-status-injector`, `team-mailbox-injector`), +4 direct event handlers in `src/plugin/event.ts` (`team-session-events/*`) = 59 total. Composed by `createCoreHooks()` + `createContinuationHooks()` + `createSkillHooks()`.
+- **5-tier hook composition:** Session (24) + ToolGuard (16) + Transform (5) + Continuation (7) + Skill (2) = 54 base. With `team_mode.enabled`: +1 ToolGuard (`team-tool-gating`), +2 Transform (`team-mode-status-injector`, `team-mailbox-injector`), +4 direct event handlers in `src/plugin/event.ts` (`team-session-events/*`) = 61 total. Composed by `createCoreHooks()` + `createContinuationHooks()` + `createSkillHooks()`.
 - **Per-session MCP isolation:** Tier-3 MCP clients keyed by `${sessionID}:${skillName}:${serverName}` so the same skill in two sessions does not share state.
 - **Two fallback systems:** `model-fallback` (proactive, chat.params) vs `runtime-fallback` (reactive, session.error). They operate independently — no direct integration.
 - **OpenClaw bidirectional:** Outbound dispatchers fire on session events; inbound daemon polls Discord/Telegram and `send-keys` replies into the tracked tmux pane.
@@ -244,7 +247,7 @@ bunx oh-my-opencode mcp-oauth login <server-url>  # Tier-3 MCP OAuth (PKCE + DCR
 - **Config migration:** idempotent via `_migrations` tracking, atomic writes with timestamped backups.
 - **Build:** `bun build` (ESM) + `tsc --emitDeclarationOnly`, externals: `@ast-grep/napi`, `zod`.
 - **CI test isolation:** `script/run-ci-tests.ts` auto-isolates files using `mock.module()` (plus `src/openclaw/__tests__/reply-listener-discord.test.ts`) — they run in separate processes.
-- **120 barrel `index.ts` files** establish module boundaries.
+- **122 barrel `index.ts` files** establish module boundaries.
 - **Architecture rules** enforced via `.sisyphus/rules/modular-code-enforcement.md` (when present in workspace).
 - **Windows builds:** run on `windows-latest` (not cross-compiled) to avoid Bun segfaults.
 - **Platform binaries:** detect AVX2 + libc family at runtime, fallback to baseline if needed.
diff --git a/src/AGENTS.md b/src/AGENTS.md
index 8c3c6c14c..31f6bff39 100644
--- a/src/AGENTS.md
+++ b/src/AGENTS.md
@@ -1,10 +1,10 @@
 # src/ — Plugin Source
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
-Entry `index.ts` orchestrates a 7-step initialization. Total: 1304 source files + 663 tests across the directories below. Cross-cutting helpers live in `shared/`; module boundaries are established by 120 barrel `index.ts` files.
+Entry `index.ts` orchestrates a 7-step initialization. Total: 1337 source files + 697 tests across the directories below. Cross-cutting helpers live in `shared/`; module boundaries are established by 122 barrel `index.ts` files.
 
 ## KEY FILES
 
@@ -63,12 +63,12 @@ createHooks()
   │   │                             prometheusMdOnly, sisyphusJuniorNotepad, noSisyphusGpt,
   │   │                             noHephaestusNonGpt, questionLabelTruncator, taskResumeInfo,
   │   │                             anthropicEffort, runtimeFallback, legacyPluginToast
-  │   ├─ createToolGuardHooks()   # 14 [+1 with team-mode]: commentChecker, toolOutputTruncator,
+  │   ├─ createToolGuardHooks()   # 16 [+1 with team-mode]: commentChecker, toolOutputTruncator,
   │   │                             directoryAgentsInjector, directoryReadmeInjector,
   │   │                             emptyTaskResponseDetector, rulesInjector, tasksTodowriteDisabler,
   │   │                             writeExistingFileGuard, bashFileReadGuard, hashlineReadEnhancer,
   │   │                             jsonErrorRecovery, readImageResizer, todoDescriptionOverride,
-  │   │                             webfetchRedirectGuard [+ teamToolGating]
+  │   │                             webfetchRedirectGuard, fsyncSkipWarning [+ teamToolGating]
   │   └─ createTransformHooks()   # 5 [+2 with team-mode]: claudeCodeHooks, keywordDetector,
   │                                  contextInjectorMessagesTransform, thinkingBlockValidator,
   │                                  toolPairValidator [+ teamModeStatusInjector, teamMailboxInjector]
@@ -82,23 +82,23 @@ createHooks()
     team-member-error-handler, team-member-status-handler
 ```
 
-Total: 52 base, 59 with team-mode. Each tier produces an object whose values are `(input, output) => void` handlers; the matching OpenCode handler invokes them in registration order via `safeHook()` wrappers.
+Total: 54 base, 61 with team-mode. Each tier produces an object whose values are `(input, output) => void` handlers; the matching OpenCode handler invokes them in registration order via `safeHook()` wrappers.
 
 ## SUBSYSTEM INVENTORY
 
 | Subdir | Files (.ts) | LOC | Purpose | Has AGENTS.md |
 |--------|-------------|-----|---------|---------------|
-| `agents/` | 96 | 19,042 | 11 agent factories + dynamic prompt builder | yes |
-| `hooks/` | 570 | 73,515 | ~50 lifecycle hooks across 57 dirs | yes |
-| `tools/` | 306 | 43,348 | 16 tool dirs producing 20–39 tools | yes |
-| `features/` | 389 | 68,410 | 20 feature modules (team-mode, background-agent, etc.) | yes |
-| `shared/` | 258 | 30,416 | Cross-cutting utilities, barrel-exported | yes |
-| `cli/` | 150 | 16,975 | Commander.js CLI: install, run, doctor, mcp-oauth | yes |
-| `plugin/` | 55 | 11,756 | 10 OpenCode hook handlers + hook composition | yes |
-| `config/` | 41 | 2,282 | 32 Zod v4 schema files | yes |
-| `plugin-handlers/` | 27 | 5,791 | 6-phase config loading pipeline | yes |
-| `openclaw/` | 26 | 3,291 | Bidirectional Discord/Telegram/HTTP integration | yes |
-| `__tests__/` | 22 | 274 | Plugin-level integration tests + perf fixtures | — |
+| `agents/` | 102 | 19,660 | 11 agent factories + dynamic prompt builder | yes |
+| `hooks/` | 581 | 78,030 | ~52 lifecycle hooks across 58 dirs | yes |
+| `tools/` | 314 | 44,768 | 16 tool dirs producing 20–39 tools | yes |
+| `features/` | 400 | 70,934 | 20 feature modules (team-mode, background-agent, boulder-state, etc.) | yes |
+| `shared/` | 278 | 32,847 | Cross-cutting utilities, barrel-exported | yes |
+| `cli/` | 158 | 17,812 | Commander.js CLI: install, run, doctor, mcp-oauth, boulder | yes |
+| `plugin/` | 56 | 12,390 | 10 OpenCode hook handlers + hook composition | yes |
+| `config/` | 41 | 2,340 | 30 Zod v4 schema files | yes |
+| `plugin-handlers/` | 27 | 5,841 | 6-phase config loading pipeline | yes |
+| `openclaw/` | 26 | 3,293 | Bidirectional Discord/Telegram/HTTP integration | yes |
+| `__tests__/` | 22 | 275 | Plugin-level integration tests + perf fixtures | — |
 | `mcp/` | 7 | 205 | 3 built-in remote MCPs | yes |
 | `testing/` | 2 | 225 | Test utilities | — |
 
diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md
index 3e3a04db8..747f3e489 100644
--- a/src/agents/AGENTS.md
+++ b/src/agents/AGENTS.md
@@ -5,7 +5,7 @@ description: Developer reference for all 11 Oh My OpenAgent agent definitions, f
 
 # src/agents/ — 11 Agent Definitions
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/agents/hephaestus/AGENTS.md b/src/agents/hephaestus/AGENTS.md
index 7c3686f03..fad6db3fa 100644
--- a/src/agents/hephaestus/AGENTS.md
+++ b/src/agents/hephaestus/AGENTS.md
@@ -5,7 +5,7 @@ description: Developer reference for the Hephaestus autonomous deep worker agent
 
 # src/agents/hephaestus/ -- Autonomous Deep Worker
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/agents/prometheus/AGENTS.md b/src/agents/prometheus/AGENTS.md
index 73cdd6f69..c99769122 100644
--- a/src/agents/prometheus/AGENTS.md
+++ b/src/agents/prometheus/AGENTS.md
@@ -5,7 +5,7 @@ description: Developer reference for the Prometheus strategic planner agent —
 
 # src/agents/prometheus/ -- Strategic Planner
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/agents/sisyphus/AGENTS.md b/src/agents/sisyphus/AGENTS.md
index 050f2c429..86d6de617 100644
--- a/src/agents/sisyphus/AGENTS.md
+++ b/src/agents/sisyphus/AGENTS.md
@@ -5,7 +5,7 @@ description: Developer reference for Sisyphus orchestrator model-specific prompt
 
 # src/agents/sisyphus/ -- Orchestrator Variants
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md
index cc6b62929..2c018bdfc 100644
--- a/src/cli/AGENTS.md
+++ b/src/cli/AGENTS.md
@@ -1,10 +1,10 @@
-# src/cli/ — CLI: install, run, doctor, mcp-oauth
+# src/cli/ — CLI: install, run, doctor, mcp-oauth, boulder
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
-Commander.js CLI with 6 commands. Entry: `index.ts` → `runCli()` in `cli-program.ts`.
+Commander.js CLI with 7 commands. Entry: `index.ts` → `runCli()` in `cli-program.ts`.
 
 ## COMMANDS
 
@@ -16,6 +16,7 @@ Commander.js CLI with 6 commands. Entry: `index.ts` → `runCli()` in `cli-progr
 | `get-local-version` | Version detection | Installed vs npm latest |
 | `mcp-oauth` | OAuth token management | login (PKCE), logout, status |
 | `refresh-model-capabilities` | Refresh models.dev cache | Model capabilities refresh |
+| `boulder` | Boulder state inspector | Format work-state + tasks from `.sisyphus/boulder-state/` |
 
 ## STRUCTURE
 
diff --git a/src/cli/config-manager/AGENTS.md b/src/cli/config-manager/AGENTS.md
index 77491f846..cf45a3b7e 100644
--- a/src/cli/config-manager/AGENTS.md
+++ b/src/cli/config-manager/AGENTS.md
@@ -1,6 +1,6 @@
 # src/cli/config-manager/ — CLI Installation Utilities
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/cli/doctor/AGENTS.md b/src/cli/doctor/AGENTS.md
index 5d7f1bd98..57cb16d66 100644
--- a/src/cli/doctor/AGENTS.md
+++ b/src/cli/doctor/AGENTS.md
@@ -1,6 +1,6 @@
 # src/cli/doctor/ — Health Diagnostics (25 Check Files)
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/cli/run/AGENTS.md b/src/cli/run/AGENTS.md
index 679b6cef5..fb4411d7d 100644
--- a/src/cli/run/AGENTS.md
+++ b/src/cli/run/AGENTS.md
@@ -1,6 +1,6 @@
 # src/cli/run/ — Non-Interactive Session Launcher
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md
index 9e4179d2a..9f03f9aab 100644
--- a/src/config/AGENTS.md
+++ b/src/config/AGENTS.md
@@ -1,6 +1,6 @@
 # src/config/ — Zod v4 Schema System
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md
index 5f8ac8195..238435802 100644
--- a/src/features/AGENTS.md
+++ b/src/features/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/ — 20 Feature Modules
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
@@ -10,9 +10,9 @@ Standalone feature modules wired into `plugin/` layer. Each is self-contained wi
 
 | Module | Files | Complexity | Purpose |
 |--------|-------|------------|---------|
-| **background-agent** | 47 | HIGH | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker |
-| **opencode-skill-loader** | 33 | HIGH | YAML frontmatter skill discovery from 4 scopes (project > opencode > user > global) |
-| **tmux-subagent** | 34 | HIGH | Tmux pane management, grid planning, session orchestration via `runTmuxCommand` |
+| **background-agent** | 57 | HIGH | Task lifecycle, concurrency (5/key), 3s polling, spawner pattern, circuit breaker, archive fallback |
+| **opencode-skill-loader** | 30 | HIGH | YAML frontmatter skill discovery from 4 scopes (project > opencode > user > global) |
+| **tmux-subagent** | 32 | HIGH | Tmux pane management, grid planning, session orchestration via `runTmuxCommand` |
 | **team-mode** | 24 dirs / 100+ files | HIGH | Parallel multi-agent coordination — 12 `team_*` tools, mailbox, tasklist, worktrees, optional tmux layout |
 | **mcp-oauth** | 18 | HIGH | OAuth 2.0 + PKCE + DCR (RFC 7591) + step-up auth for MCP servers |
 | **skill-mcp-manager** | 18 | HIGH | Tier-3 MCP client lifecycle per session (stdio + HTTP + OAuth) |
diff --git a/src/features/background-agent/AGENTS.md b/src/features/background-agent/AGENTS.md
index b44c83085..7eb458a96 100644
--- a/src/features/background-agent/AGENTS.md
+++ b/src/features/background-agent/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/background-agent/ — Core Orchestration Engine
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/boulder-state/AGENTS.md b/src/features/boulder-state/AGENTS.md
new file mode 100644
index 000000000..888455b41
--- /dev/null
+++ b/src/features/boulder-state/AGENTS.md
@@ -0,0 +1,79 @@
+# src/features/boulder-state/ — Active Work Plan Tracker
+
+**Generated:** 2026-05-14
+
+## OVERVIEW
+
+10 files (~1k LOC excl. tests). Tracks Sisyphus's "boulder" — the active work plan being rolled across sessions, worktrees, and subagent task delegations. Named after the Sisyphus myth: the boulder must keep rolling until the plan is complete.
+
+Inspected interactively via `bunx oh-my-opencode boulder` (see [`src/cli/boulder/`](file:///Users/yeongyu/local-workspaces/omo/src/cli/boulder/)).
+
+## SCHEMA (v2)
+
+```typescript
+interface BoulderState {
+  schema_version?: 2
+  active_work_id?: string
+  works?: Record<string, BoulderWorkState>
+  active_plan: string                            // absolute path to active .md plan
+  started_at: string                             // ISO timestamp
+  ended_at?: string
+  elapsed_ms?: number
+  status?: "active" | "completed" | "paused" | "abandoned"
+  session_ids: string[]                          // every session that has rolled the boulder
+  session_origins?: Record<string, "direct" | "appended">
+  plan_name: string                              // filename of active_plan
+  agent?: string                                 // resume agent (atlas | sisyphus | ...)
+  worktree_path?: string                         // git worktree root
+  task_sessions?: Record<string, TaskSessionState>  // reusable subagent sessions per top-level task
+}
+```
+
+## FILES
+
+| File | Purpose |
+|------|---------|
+| `types.ts` | `BoulderState`, `BoulderWorkState`, `TaskSessionState`, status enums |
+| `storage.ts` | Atomic CRUD on `.sisyphus/boulder-state.json`. Writes via temp file + rename; file lock per work_id |
+| `constants.ts` | Path resolution + schema version constant |
+| `top-level-task.ts` | Helpers to identify the current top-level plan task and resolve its reusable subagent session |
+| `format-duration.ts` | `formatDurationHuman(ms)` — "1h 23m 5s" formatting for boulder duration |
+| `index.ts` | Barrel exports |
+
+## LIFECYCLE
+
+```
+session.startWork(plan)
+  → BoulderState created with active_plan, started_at, plan_name
+  → atlas-hook reads BoulderState on session.idle for boulder continuation
+  → ralph-loop reads task_sessions to resume subagent work
+session.idle (incomplete plan)
+  → todoContinuationEnforcer + atlasHook inspect state
+  → Inject CONTINUATION_PROMPT or BOULDER_COMPLETE_PROMPT
+session.completed
+  → BoulderState status="completed", ended_at, elapsed_ms recorded
+```
+
+## INTEGRATION POINTS
+
+| Where | What |
+|-------|------|
+| [`src/cli/boulder/`](file:///Users/yeongyu/local-workspaces/omo/src/cli/boulder/) | CLI inspector formats this state |
+| [`src/hooks/atlas/`](file:///Users/yeongyu/local-workspaces/omo/src/hooks/atlas/) | Reads work state, drives boulder-complete and parallel-delegation prompts |
+| [`src/hooks/ralph-loop/`](file:///Users/yeongyu/local-workspaces/omo/src/hooks/ralph-loop/) | Resumes subagent task sessions via `task_sessions` |
+| [`src/hooks/start-work/`](file:///Users/yeongyu/local-workspaces/omo/src/hooks/start-work/) | Creates the BoulderState on `/start-work` invocation |
+| [`src/hooks/todo-continuation-enforcer/`](file:///Users/yeongyu/local-workspaces/omo/src/hooks/todo-continuation-enforcer/) | Session-idle continuation when boulder incomplete |
+
+## STORAGE
+
+```
+<worktree-root>/.sisyphus/boulder-state.json   # gitignored; one file per worktree
+```
+
+Atomic writes: temp file → fsync (where supported) → rename. File lock prevents concurrent corruption. Schema migrations between versions handled inline in `storage.ts`.
+
+## NOTES
+
+- **task_sessions reuse**: same subagent session is reused across iterations for the same top-level task to preserve context.
+- **Multi-work**: `works` map allows tracking multiple concurrent plans; `active_work_id` selects the current one.
+- **Worktree-scoped**: state lives in the worktree, not user-global; ensures parallel work plans across worktrees stay isolated.
diff --git a/src/features/builtin-skills/AGENTS.md b/src/features/builtin-skills/AGENTS.md
index f6cc54f90..0c5d43908 100644
--- a/src/features/builtin-skills/AGENTS.md
+++ b/src/features/builtin-skills/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/builtin-skills/ — 10 Built-in Skill Files
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/claude-code-mcp-loader/AGENTS.md b/src/features/claude-code-mcp-loader/AGENTS.md
index 44597951a..08706ca49 100644
--- a/src/features/claude-code-mcp-loader/AGENTS.md
+++ b/src/features/claude-code-mcp-loader/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/claude-code-mcp-loader/ — Tier 2 MCP Loader (.mcp.json)
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/claude-code-plugin-loader/AGENTS.md b/src/features/claude-code-plugin-loader/AGENTS.md
index ead7ab78d..bf8c4d5e4 100644
--- a/src/features/claude-code-plugin-loader/AGENTS.md
+++ b/src/features/claude-code-plugin-loader/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/claude-code-plugin-loader/ — Unified Claude Code Plugin Loader
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/claude-tasks/AGENTS.md b/src/features/claude-tasks/AGENTS.md
index 6d83d97ad..00f3c64be 100644
--- a/src/features/claude-tasks/AGENTS.md
+++ b/src/features/claude-tasks/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/claude-tasks/ — Task Schema + Storage
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/mcp-oauth/AGENTS.md b/src/features/mcp-oauth/AGENTS.md
index c2d9c458c..e878677b1 100644
--- a/src/features/mcp-oauth/AGENTS.md
+++ b/src/features/mcp-oauth/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/mcp-oauth/ — OAuth 2.0 + PKCE + DCR for MCP Servers
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/opencode-skill-loader/AGENTS.md b/src/features/opencode-skill-loader/AGENTS.md
index b9eb1dbb1..af5e89779 100644
--- a/src/features/opencode-skill-loader/AGENTS.md
+++ b/src/features/opencode-skill-loader/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/opencode-skill-loader/ — 4-Scope Skill Discovery
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/skill-mcp-manager/AGENTS.md b/src/features/skill-mcp-manager/AGENTS.md
index 076a1d7d5..3732fa884 100644
--- a/src/features/skill-mcp-manager/AGENTS.md
+++ b/src/features/skill-mcp-manager/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/skill-mcp-manager/ — Skill-Embedded MCP Client Lifecycle
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/team-mode/AGENTS.md b/src/features/team-mode/AGENTS.md
index 1d6a0fedb..b0eb15dfa 100644
--- a/src/features/team-mode/AGENTS.md
+++ b/src/features/team-mode/AGENTS.md
@@ -1,6 +1,6 @@
 # team-mode — Parallel Multi-Agent Coordination
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/features/tmux-subagent/AGENTS.md b/src/features/tmux-subagent/AGENTS.md
index 261a32b8f..7b27435ae 100644
--- a/src/features/tmux-subagent/AGENTS.md
+++ b/src/features/tmux-subagent/AGENTS.md
@@ -1,6 +1,6 @@
 # src/features/tmux-subagent/ — Tmux Pane Management
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md
index 2d83851a1..f4f648d44 100644
--- a/src/hooks/AGENTS.md
+++ b/src/hooks/AGENTS.md
@@ -1,25 +1,25 @@
-# src/hooks/ — ~50 Lifecycle Hooks Across 57 Dirs
+# src/hooks/ — ~52 Lifecycle Hooks Across 58 Dirs
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
-50 hooks (7 of the 57 dirs are `zauc-mocks-*` test scaffolds + 1 `shared/`). 5-tier composition wired in `src/plugin/hooks/`. All hooks follow `createXXXHook(deps) → HookFunction` factory pattern.
+52 hooks (5 of the 58 dirs are `zauc-mocks-*` test scaffolds + 1 `shared/`). 5-tier composition wired in `src/plugin/hooks/`. All hooks follow `createXXXHook(deps) → HookFunction` factory pattern.
 
 ## TIER COMPOSITION
 
 | Tier | Composer | Base | With team-mode | Where |
 |------|----------|------|----------------|-------|
 | **Session** | `create-session-hooks.ts` | 24 | 24 | OpenCode session lifecycle + chat.params + chat.message |
-| **Tool Guard** | `create-tool-guard-hooks.ts` | 14 | 15 | Pre/post tool execution (+1: `team-tool-gating`) |
+| **Tool Guard** | `create-tool-guard-hooks.ts` | 16 | 17 | Pre/post tool execution (+1: `team-tool-gating`) |
 | **Transform** | `create-transform-hooks.ts` | 5 | 7 | `experimental.chat.messages.transform` (+2: `team-mode-status-injector`, `team-mailbox-injector`) |
 | **Continuation** | `create-continuation-hooks.ts` | 7 | 7 | Boulder/atlas/compaction/notification |
 | **Skill** | `create-skill-hooks.ts` | 2 | 2 | Skill awareness (categorySkillReminder, autoSlashCommand) |
 | **Direct event handlers** | `src/plugin/event.ts` | 0 | +4 | `team-session-events/` sub-files: `team-idle-wake-hint`, `team-lead-orphan-handler`, `team-member-error-handler`, `team-member-status-handler` |
 
-Total exposed hooks: **52 base, 59 with team-mode** (counts the 4 team-session-events handlers individually).
+Total exposed hooks: **54 base, 61 with team-mode** (counts the 4 team-session-events handlers individually).
 
-Hook name allowlist for `disabled_hooks`: 53 enum values in [`src/config/schema/hooks.ts`](file:///Users/yeongyu/local-workspaces/omo/src/config/schema/hooks.ts) `HookNameSchema`. Team-session-event sub-hooks are not individually listed in the schema — they activate together with `team_mode.enabled`.
+Hook name allowlist for `disabled_hooks`: all configurable hook names enumerated in [`src/config/schema/hooks.ts`](file:///Users/yeongyu/local-workspaces/omo/src/config/schema/hooks.ts) `HookNameSchema`. Team-session-event sub-hooks are not individually listed in the schema — they activate together with `team_mode.enabled`.
 
 ### Tier 1: Session Hooks (24)
 
@@ -50,7 +50,7 @@ Hook name allowlist for `disabled_hooks`: 53 enum values in [`src/config/schema/
 | `runtimeFallback` | event | Reactive auto-switch on API provider errors |
 | `legacyPluginToast` | chat.message | Show toast when legacy plugin name detected |
 
-### Tier 2: Tool Guard Hooks (14)
+### Tier 2: Tool Guard Hooks (16)
 
 | Hook | Event | Purpose |
 |------|-------|---------|
@@ -68,6 +68,7 @@ Hook name allowlist for `disabled_hooks`: 53 enum values in [`src/config/schema/
 | `webfetchRedirectGuard` | tool.execute.before | Guard webfetch redirect behavior |
 | `hashlineReadEnhancer` | tool.execute.after | Tag every Read output with `LINE#ID` content hashes |
 | `jsonErrorRecovery` | tool.execute.after | Detect JSON parse errors, inject correction reminder |
+| `fsyncSkipWarning` | tool.execute.after | Warn when fsync is skipped for atomic writes |
 
 ### Tier 3: Transform Hooks (5)
 
@@ -117,8 +118,8 @@ The 4 `team-session-events/` handlers live in `src/hooks/team-session-events/` (
 ```
 hooks/
 ├── shared/                                  # Cross-hook helpers (timing, prompt builders, etc.)
-├── (50 hook directories — see tier tables above)
-├── zauc-mocks-bg, zauc-mocks-cache, …       # Test mocks (NOT hooks; named for sort-order isolation)
+├── (52 hook directories — see tier tables above)
+├── zauc-mocks-{bg,cache,hook,ws}, zauc-sync-mocks  # 5 test mocks (NOT hooks; named for sort-order isolation)
 └── (each hook dir)/
     ├── index.ts        # createXXXHook factory + barrel
     ├── *.ts            # implementation
diff --git a/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md b/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md
index 415834f19..42ecddc41 100644
--- a/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md
+++ b/src/hooks/anthropic-context-window-limit-recovery/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/anthropic-context-window-limit-recovery/ — Multi-Strategy Context Recovery
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/atlas/AGENTS.md b/src/hooks/atlas/AGENTS.md
index b34072214..9769e1167 100644
--- a/src/hooks/atlas/AGENTS.md
+++ b/src/hooks/atlas/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/atlas/ — Master Boulder Orchestrator
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/claude-code-hooks/AGENTS.md b/src/hooks/claude-code-hooks/AGENTS.md
index 041c3f095..b1fd4ceb0 100644
--- a/src/hooks/claude-code-hooks/AGENTS.md
+++ b/src/hooks/claude-code-hooks/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/claude-code-hooks/ — Claude Code Compatibility
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/comment-checker/AGENTS.md b/src/hooks/comment-checker/AGENTS.md
index 108024765..9d983835f 100644
--- a/src/hooks/comment-checker/AGENTS.md
+++ b/src/hooks/comment-checker/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/comment-checker/ — AI Slop Comment Blocker
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/keyword-detector/AGENTS.md b/src/hooks/keyword-detector/AGENTS.md
index 15883ec42..4a0f2a2af 100644
--- a/src/hooks/keyword-detector/AGENTS.md
+++ b/src/hooks/keyword-detector/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/keyword-detector/ — Mode Keyword Injection
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/ralph-loop/AGENTS.md b/src/hooks/ralph-loop/AGENTS.md
index b288649d3..c44c60b1b 100644
--- a/src/hooks/ralph-loop/AGENTS.md
+++ b/src/hooks/ralph-loop/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/ralph-loop/ — Self-Referential Dev Loop
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/rules-injector/AGENTS.md b/src/hooks/rules-injector/AGENTS.md
index c9c7a446a..6fb6eecee 100644
--- a/src/hooks/rules-injector/AGENTS.md
+++ b/src/hooks/rules-injector/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/rules-injector/ — Conditional Rules Injection
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/runtime-fallback/AGENTS.md b/src/hooks/runtime-fallback/AGENTS.md
index 150d222e7..bae40f4dd 100644
--- a/src/hooks/runtime-fallback/AGENTS.md
+++ b/src/hooks/runtime-fallback/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/runtime-fallback/ — Reactive Provider Error Recovery
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/session-recovery/AGENTS.md b/src/hooks/session-recovery/AGENTS.md
index ee2b81ceb..574e6fe6c 100644
--- a/src/hooks/session-recovery/AGENTS.md
+++ b/src/hooks/session-recovery/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/session-recovery/ — Auto Session Error Recovery
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/hooks/todo-continuation-enforcer/AGENTS.md b/src/hooks/todo-continuation-enforcer/AGENTS.md
index a14de425e..8cc80c78b 100644
--- a/src/hooks/todo-continuation-enforcer/AGENTS.md
+++ b/src/hooks/todo-continuation-enforcer/AGENTS.md
@@ -1,6 +1,6 @@
 # src/hooks/todo-continuation-enforcer/ — Boulder Continuation Mechanism
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/mcp/AGENTS.md b/src/mcp/AGENTS.md
index 73829ece7..50cdfc677 100644
--- a/src/mcp/AGENTS.md
+++ b/src/mcp/AGENTS.md
@@ -1,6 +1,6 @@
 # src/mcp/ — 3 Built-in Remote MCPs
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/openclaw/AGENTS.md b/src/openclaw/AGENTS.md
index 1060e548e..f0cae5379 100644
--- a/src/openclaw/AGENTS.md
+++ b/src/openclaw/AGENTS.md
@@ -1,6 +1,6 @@
 # src/openclaw/ — Bidirectional External Integration
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/plugin-handlers/AGENTS.md b/src/plugin-handlers/AGENTS.md
index d378f9391..5ad342bdf 100644
--- a/src/plugin-handlers/AGENTS.md
+++ b/src/plugin-handlers/AGENTS.md
@@ -1,6 +1,6 @@
 # src/plugin-handlers/ — 6-Phase Config Loading Pipeline
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## CRITICAL: AGENT ORDERING
 
diff --git a/src/plugin/AGENTS.md b/src/plugin/AGENTS.md
index 78cb31dcb..f86311e80 100644
--- a/src/plugin/AGENTS.md
+++ b/src/plugin/AGENTS.md
@@ -1,6 +1,6 @@
 # src/plugin/ — 10 OpenCode Hook Handlers + Hook Composition
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
@@ -27,10 +27,10 @@ Core glue layer. Files assemble the 10 OpenCode hook handlers and compose the 5-
 | File | Tier | Count |
 |------|------|-------|
 | `create-session-hooks.ts` | Session | 24 |
-| `create-tool-guard-hooks.ts` | Tool Guard | 14 |
+| `create-tool-guard-hooks.ts` | Tool Guard | 16 |
 | `create-transform-hooks.ts` | Transform | 5 |
 | `create-skill-hooks.ts` | Skill | 2 |
-| `create-core-hooks.ts` | Aggregator | Session + Guard + Transform = 43 |
+| `create-core-hooks.ts` | Aggregator | Session + Guard + Transform = 45 |
 
 `createContinuationHooks()` (7) lives in `src/create-hooks.ts` next to `createCoreHooks()` and `createSkillHooks()`.
 
diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md
index 9bbaf66e0..64a370dbb 100644
--- a/src/shared/AGENTS.md
+++ b/src/shared/AGENTS.md
@@ -1,10 +1,10 @@
-# src/shared/ — 100+ Utility Files
+# src/shared/ — 278 Utility Files (170 non-test)
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
-Cross-cutting utilities used throughout the plugin. Barrel-exported from `index.ts`. Logger writes to `/tmp/oh-my-opencode.log`.
+Cross-cutting utilities used throughout the plugin. Barrel-exported from `index.ts`. Logger writes to `/tmp/oh-my-opencode.log`. Includes runtime shims for `Bun.file`, `Bun.write`, `Bun.hash`, `Bun.which`, `Bun.spawn` to support non-Bun runtimes (Electron-hosted OpenCode).
 
 ## CATEGORY MAP
 
diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md
index 7290cefd7..d61fac4d4 100644
--- a/src/tools/AGENTS.md
+++ b/src/tools/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/ — 20–39 Tools Across 16 Directories
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/tools/background-task/AGENTS.md b/src/tools/background-task/AGENTS.md
index 03fa6e974..0abe70378 100644
--- a/src/tools/background-task/AGENTS.md
+++ b/src/tools/background-task/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/background-task/ — Background Task Tool Wrappers
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/tools/call-omo-agent/AGENTS.md b/src/tools/call-omo-agent/AGENTS.md
index 35ec04140..25cf5cd85 100644
--- a/src/tools/call-omo-agent/AGENTS.md
+++ b/src/tools/call-omo-agent/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/call-omo-agent/ — Direct Agent Invocation Tool
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/tools/delegate-task/AGENTS.md b/src/tools/delegate-task/AGENTS.md
index 2880e9951..558ea7539 100644
--- a/src/tools/delegate-task/AGENTS.md
+++ b/src/tools/delegate-task/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/delegate-task/ — Task Delegation Engine
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/tools/hashline-edit/AGENTS.md b/src/tools/hashline-edit/AGENTS.md
index a35ac452e..677e7c229 100644
--- a/src/tools/hashline-edit/AGENTS.md
+++ b/src/tools/hashline-edit/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/hashline-edit/ — Hash-Anchored File Edit Tool
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/src/tools/lsp/AGENTS.md b/src/tools/lsp/AGENTS.md
index 13a2ce341..7fad4c244 100644
--- a/src/tools/lsp/AGENTS.md
+++ b/src/tools/lsp/AGENTS.md
@@ -1,6 +1,6 @@
 # src/tools/lsp/ — LSP Tool Implementations
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW
 
diff --git a/web/AGENTS.md b/web/AGENTS.md
index 054804afc..2342a4b3e 100644
--- a/web/AGENTS.md
+++ b/web/AGENTS.md
@@ -1,6 +1,6 @@
 # web/ — Marketing Site (Next.js + Cloudflare Workers)
 
-**Generated:** 2026-05-08
+**Generated:** 2026-05-14
 
 ## OVERVIEW