docs: regenerate all 13 AGENTS.md files from deep codebase exploration

2026-02-16 15:26:53 +09:00
parent c2012c6027
commit cfb8164d9a
11 changed files with 182 additions and 308 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,8 +1,8 @@
 # PROJECT KNOWLEDGE BASE

-**Generated:** 2026-02-10T14:44:00+09:00
-**Commit:** b538806d
-**Branch:** dev
+**Generated:** 2026-02-16T14:58:00+09:00
+**Commit:** 28cd34c3
+**Branch:** fuck-v1.2

 ---

@@ -102,32 +102,32 @@ Oh-My-OpenCode is a **plugin for OpenCode**. You will frequently need to examine

 ## OVERVIEW

-OpenCode plugin (v3.4.0): multi-model agent orchestration with 11 specialized agents (Claude Opus 4.6, GPT-5.3 Codex, Gemini 3 Flash, GLM-4.7, Grok). 41 lifecycle hooks across 7 event types, 25+ tools (LSP, AST-Grep, delegation, task management), full Claude Code compatibility layer. "oh-my-zsh" for OpenCode.
+OpenCode plugin (oh-my-opencode): multi-model agent orchestration with 11 specialized agents, 41 lifecycle hooks across 7 event types, 26 tools (LSP, AST-Grep, delegation, task management), full Claude Code compatibility layer, 4-scope skill loading, background agent concurrency, tmux integration, and 3-tier MCP system. "oh-my-zsh" for OpenCode.

 ## STRUCTURE

 ```
 oh-my-opencode/
 ├── src/
-│   ├── agents/              # 11 AI agents - see src/agents/AGENTS.md
-│   ├── hooks/               # 41 lifecycle hooks - see src/hooks/AGENTS.md
-│   ├── tools/               # 25+ tools - see src/tools/AGENTS.md
-│   ├── features/            # Background agents, skills, CC compat - see src/features/AGENTS.md
-│   ├── shared/              # 84 cross-cutting utilities - see src/shared/AGENTS.md
-│   ├── cli/                 # CLI installer, doctor - see src/cli/AGENTS.md
-│   ├── mcp/                 # Built-in MCPs - see src/mcp/AGENTS.md
-│   ├── config/              # Zod schema - see src/config/AGENTS.md
-│   ├── plugin-handlers/     # Config loading - see src/plugin-handlers/AGENTS.md
+│   ├── agents/              # 11 AI agents — see src/agents/AGENTS.md
+│   ├── hooks/               # 41 lifecycle hooks — see src/hooks/AGENTS.md
+│   ├── tools/               # 26 tools — see src/tools/AGENTS.md
+│   ├── features/            # Background agents, skills, CC compat — see src/features/AGENTS.md
+│   ├── shared/              # Cross-cutting utilities — see src/shared/AGENTS.md
+│   ├── cli/                 # CLI installer, doctor — see src/cli/AGENTS.md
+│   ├── mcp/                 # Built-in MCPs — see src/mcp/AGENTS.md
+│   ├── config/              # Zod schema — see src/config/AGENTS.md
+│   ├── plugin-handlers/     # Config loading pipeline — see src/plugin-handlers/AGENTS.md
 │   ├── plugin/              # Plugin interface composition (21 files)
-│   ├── index.ts             # Main plugin entry (88 lines)
+│   ├── index.ts             # Main plugin entry (106 lines)
 │   ├── create-hooks.ts      # Hook creation coordination (62 lines)
 │   ├── create-managers.ts   # Manager initialization (80 lines)
 │   ├── create-tools.ts      # Tool registry composition (54 lines)
 │   ├── plugin-interface.ts  # Plugin interface assembly (66 lines)
-│   ├── plugin-config.ts     # Config loading orchestration
-│   └── plugin-state.ts      # Model cache state
+│   ├── plugin-config.ts     # Config loading orchestration (180 lines)
+│   └── plugin-state.ts      # Model cache state (12 lines)
 ├── script/                  # build-schema.ts, build-binaries.ts, publish.ts, generate-changelog.ts
-├── packages/                # 7 platform-specific binary packages
+├── packages/                # 11 platform-specific binary packages
 └── dist/                    # Build output (ESM + .d.ts)
 ```

@@ -143,7 +143,7 @@ OhMyOpenCodePlugin(ctx)
  6. createManagers(ctx, config, tmux, cache)  → TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler
  7. createTools(ctx, config, managers)         → filteredTools, mergedSkills, availableSkills, availableCategories
  8. createHooks(ctx, config, backgroundMgr)   → 41 hooks (core + continuation + skill)
-  9. createPluginInterface(...)                 → tool, chat.params, chat.message, event, tool.execute.before/after
+  9. createPluginInterface(...)                 → 7 OpenCode hook handlers
 10. Return plugin with experimental.session.compacting
 ```

@@ -159,7 +159,7 @@ OhMyOpenCodePlugin(ctx)
 | Add command | `src/features/builtin-commands/` | Add template + register in commands.ts |
 | Config schema | `src/config/schema/` | 21 schema component files, run `bun run build:schema` |
 | Plugin config | `src/plugin-handlers/config-handler.ts` | JSONC loading, merging, migration |
-| Background agents | `src/features/background-agent/` | manager.ts (1646 lines) |
+| Background agents | `src/features/background-agent/` | manager.ts (1701 lines) |
 | Orchestrator | `src/hooks/atlas/` | Main orchestration hook (1976 lines) |
 | Delegation | `src/tools/delegate-task/` | Category routing (constants.ts 569 lines) |
 | Task system | `src/features/claude-tasks/` | Task schema, storage, todo sync |
@@ -174,7 +174,7 @@ OhMyOpenCodePlugin(ctx)

 **Rules:**
 - NEVER write implementation before test
- NEVER delete failing tests - fix the code
+- NEVER delete failing tests — fix the code
 - Test file: `*.test.ts` alongside source (176 test files)
 - BDD comments: `//#given`, `//#when`, `//#then`

@@ -185,7 +185,7 @@ OhMyOpenCodePlugin(ctx)
 - **Build**: `bun build` (ESM) + `tsc --emitDeclarationOnly`
 - **Exports**: Barrel pattern via index.ts
 - **Naming**: kebab-case dirs, `createXXXHook`/`createXXXTool` factories
- **Testing**: BDD comments, 176 test files, 117k+ lines TypeScript
+- **Testing**: BDD comments, 176 test files, 1130 TypeScript files
 - **Temperature**: 0.1 for code agents, max 0.3
 - **Modular architecture**: 200 LOC hard limit per file (prompt strings exempt)

@@ -193,24 +193,24 @@ OhMyOpenCodePlugin(ctx)

 | Category | Forbidden |
 |----------|-----------|
-| Package Manager | npm, yarn - Bun exclusively |
-| Types | @types/node - use bun-types |
-| File Ops | mkdir/touch/rm/cp/mv in code - use bash tool |
-| Publishing | Direct `bun publish` - GitHub Actions only |
-| Versioning | Local version bump - CI manages |
+| Package Manager | npm, yarn — Bun exclusively |
+| Types | @types/node — use bun-types |
+| File Ops | mkdir/touch/rm/cp/mv in code — use bash tool |
+| Publishing | Direct `bun publish` — GitHub Actions only |
+| Versioning | Local version bump — CI manages |
 | Type Safety | `as any`, `@ts-ignore`, `@ts-expect-error` |
 | Error Handling | Empty catch blocks |
 | Testing | Deleting failing tests, writing implementation before test |
-| Agent Calls | Sequential - use `task` parallel |
-| Hook Logic | Heavy PreToolUse - slows every call |
+| Agent Calls | Sequential — use `task` parallel |
+| Hook Logic | Heavy PreToolUse — slows every call |
 | Commits | Giant (3+ files), separate test from impl |
 | Temperature | >0.3 for code agents |
-| Trust | Agent self-reports - ALWAYS verify |
+| Trust | Agent self-reports — ALWAYS verify |
 | Git | `git add -i`, `git rebase -i` (no interactive input) |
 | Git | Skip hooks (--no-verify), force push without request |
-| Bash | `sleep N` - use conditional waits |
-| Bash | `cd dir && cmd` - use workdir parameter |
-| Files | Catch-all utils.ts/helpers.ts - name by purpose |
+| Bash | `sleep N` — use conditional waits |
+| Bash | `cd dir && cmd` — use workdir parameter |
+| Files | Catch-all utils.ts/helpers.ts — name by purpose |

 ## AGENT MODELS

@@ -230,7 +230,7 @@ OhMyOpenCodePlugin(ctx)

 ## OPENCODE PLUGIN API

-Plugin SDK from `@opencode-ai/plugin` (v1.1.19). Plugin = `async (PluginInput) => Hooks`.
+Plugin SDK from `@opencode-ai/plugin`. Plugin = `async (PluginInput) => Hooks`.

 | Hook | Purpose |
 |------|---------|
@@ -283,7 +283,7 @@ bun run build:schema   # Regenerate JSON schema

 | File | Lines | Description |
 |------|-------|-------------|
-| `src/features/background-agent/manager.ts` | 1646 | Task lifecycle, concurrency |
+| `src/features/background-agent/manager.ts` | 1701 | Task lifecycle, concurrency |
 | `src/hooks/anthropic-context-window-limit-recovery/` | 2232 | Multi-strategy context recovery |
 | `src/hooks/claude-code-hooks/` | 2110 | Claude Code settings.json compat |
 | `src/hooks/todo-continuation-enforcer/` | 2061 | Core boulder mechanism |
@@ -293,7 +293,7 @@ bun run build:schema   # Regenerate JSON schema
 | `src/hooks/rules-injector/` | 1604 | Conditional rules injection |
 | `src/hooks/think-mode/` | 1365 | Model/variant switching |
 | `src/hooks/session-recovery/` | 1279 | Auto error recovery |
-| `src/features/builtin-skills/skills/git-master.ts` | 1111 | Git master skill |
+| `src/features/builtin-skills/skills/git-master.ts` | 1112 | Git master skill |
 | `src/tools/delegate-task/constants.ts` | 569 | Category routing configs |

 ## MCP ARCHITECTURE
@@ -313,7 +313,7 @@ Three-tier system:
 ## NOTES

 - **OpenCode**: Requires >= 1.0.150
- **1069 TypeScript files**, 176 test files, 117k+ lines
+- **1130 TypeScript files**, 176 test files, 127k+ lines
 - **Flaky tests**: ralph-loop (CI timeout), session-state (parallel pollution)
 - **Trusted deps**: @ast-grep/cli, @ast-grep/napi, @code-yeongyu/comment-checker
 - **No linter/formatter**: No ESLint, Prettier, or Biome configured
--- a/src/AGENTS.md
+++ b/src/AGENTS.md
@@ -5,25 +5,26 @@
 Main plugin entry point and orchestration layer. Plugin initialization, hook registration, tool composition, and lifecycle management.

 ## STRUCTURE
+
 ```
 src/
-├── index.ts                          # Main plugin entry (88 lines) — OhMyOpenCodePlugin factory
+├── index.ts                          # Main plugin entry (106 lines) — OhMyOpenCodePlugin factory
 ├── create-hooks.ts                   # Hook coordination: core, continuation, skill (62 lines)
 ├── create-managers.ts                # Manager initialization: Tmux, Background, SkillMcp, Config (80 lines)
 ├── create-tools.ts                   # Tool registry + skill context composition (54 lines)
 ├── plugin-interface.ts               # Plugin interface assembly — 7 OpenCode hooks (66 lines)
-├── plugin-config.ts                  # Config loading orchestration (user + project merge)
-├── plugin-state.ts                   # Model cache state (context limits, anthropic 1M flag)
-├── agents/                           # 11 AI agents (32 files) - see agents/AGENTS.md
-├── cli/                              # CLI installer, doctor (107+ files) - see cli/AGENTS.md
-├── config/                           # Zod schema (21 component files) - see config/AGENTS.md
-├── features/                         # Background agents, skills, commands (18 dirs) - see features/AGENTS.md
-├── hooks/                            # 41 lifecycle hooks (36 dirs) - see hooks/AGENTS.md
-├── mcp/                              # Built-in MCPs (6 files) - see mcp/AGENTS.md
+├── plugin-config.ts                  # Config loading orchestration (user + project merge, 180 lines)
+├── plugin-state.ts                   # Model cache state (context limits, anthropic 1M flag, 12 lines)
+├── agents/                           # 11 AI agents (32 files) — see agents/AGENTS.md
+├── cli/                              # CLI installer, doctor (107+ files) — see cli/AGENTS.md
+├── config/                           # Zod schema (21 component files) — see config/AGENTS.md
+├── features/                         # Background agents, skills, commands (18 dirs) — see features/AGENTS.md
+├── hooks/                            # 41 lifecycle hooks (36 dirs) — see hooks/AGENTS.md
+├── mcp/                              # Built-in MCPs (6 files) — see mcp/AGENTS.md
 ├── plugin/                           # Plugin interface composition (21 files)
-├── plugin-handlers/                  # Config loading, plan inheritance (15 files) - see plugin-handlers/AGENTS.md
-├── shared/                           # Cross-cutting utilities (84 files) - see shared/AGENTS.md
-└── tools/                            # 25+ tools (14 dirs) - see tools/AGENTS.md
+├── plugin-handlers/                  # Config loading, plan inheritance (15 files) — see plugin-handlers/AGENTS.md
+├── shared/                           # Cross-cutting utilities (96 files) — see shared/AGENTS.md
+└── tools/                            # 26 tools (14 dirs) — see tools/AGENTS.md
 ```

 ## PLUGIN INITIALIZATION (10 steps)
--- a/src/agents/AGENTS.md
+++ b/src/agents/AGENTS.md
@@ -7,36 +7,22 @@
 ## STRUCTURE
 ```
 agents/
-├── sisyphus.ts                 # Main orchestrator (530 lines)
-├── hephaestus.ts               # Autonomous deep worker (624 lines)
-├── oracle.ts                   # Strategic advisor (170 lines)
-├── librarian.ts                # Multi-repo research (328 lines)
-├── explore.ts                  # Fast codebase grep (124 lines)
-├── multimodal-looker.ts        # Media analyzer (58 lines)
+├── sisyphus.ts                 # Main orchestrator (559 lines)
+├── hephaestus.ts               # Autonomous deep worker (651 lines)
+├── oracle.ts                   # Strategic advisor (171 lines)
+├── librarian.ts                # Multi-repo research (329 lines)
+├── explore.ts                  # Fast codebase grep (125 lines)
+├── multimodal-looker.ts        # Media analyzer (59 lines)
 ├── metis.ts                    # Pre-planning analysis (347 lines)
 ├── momus.ts                    # Plan validator (244 lines)
-├── atlas/                      # Master orchestrator
-│   ├── agent.ts                # Atlas factory
-│   ├── default.ts              # Claude-optimized prompt
-│   ├── gpt.ts                  # GPT-optimized prompt
-│   └── utils.ts
-├── prometheus/                 # Planning agent
-│   ├── index.ts
-│   ├── system-prompt.ts        # 6-section prompt assembly
-│   ├── plan-template.ts        # Work plan structure (423 lines)
-│   ├── interview-mode.ts       # Interview flow (335 lines)
-│   ├── plan-generation.ts
-│   ├── high-accuracy-mode.ts
-│   ├── identity-constraints.ts # Identity rules (301 lines)
-│   └── behavioral-summary.ts
-├── sisyphus-junior/            # Delegated task executor
-│   ├── agent.ts
-│   ├── default.ts              # Claude prompt
-│   └── gpt.ts                  # GPT prompt
-├── dynamic-agent-prompt-builder.ts  # Dynamic prompt generation (431 lines)
-├── builtin-agents/             # Agent registry (8 files)
+├── atlas/                      # Master orchestrator (agent.ts + default.ts + gpt.ts)
+├── prometheus/                 # Planning agent (8 files, plan-template 423 lines)
+├── sisyphus-junior/            # Delegated task executor (agent.ts + default.ts + gpt.ts)
+├── dynamic-agent-prompt-builder.ts  # Dynamic prompt generation (433 lines)
+├── builtin-agents/             # Agent registry + model resolution
+├── agent-builder.ts            # Agent construction with category merging (51 lines)
 ├── utils.ts                    # Agent creation, model fallback resolution (571 lines)
-├── types.ts                    # AgentModelConfig, AgentPromptMetadata
+├── types.ts                    # AgentModelConfig, AgentPromptMetadata (106 lines)
 └── index.ts                    # Exports
 ```

@@ -78,6 +64,12 @@ agents/
 | Momus | 32k budget tokens | reasoningEffort: "medium" |
 | Sisyphus-Junior | 32k budget tokens | reasoningEffort: "medium" |

+## KEY PROMPT PATTERNS
+
+- **Sisyphus/Hephaestus**: Dynamic prompts via `dynamic-agent-prompt-builder.ts` injecting available tools/skills/categories
+- **Atlas, Sisyphus-Junior**: Model-specific prompts (Claude vs GPT variants)
+- **Prometheus**: 6-section modular prompt (identity → interview → plan-generation → high-accuracy → template → behavioral)
+
 ## HOW TO ADD

 1. Create `src/agents/my-agent.ts` exporting factory + metadata
@@ -85,13 +77,6 @@ agents/
 3. Update `AgentNameSchema` in `src/config/schema/agent-names.ts`
 4. Register in `src/plugin-handlers/agent-config-handler.ts`

-## KEY PATTERNS
-
- **Factory**: `createXXXAgent(model): AgentConfig`
- **Metadata**: `XXX_PROMPT_METADATA` with category, cost, triggers
- **Model-specific prompts**: Atlas, Sisyphus-Junior have GPT vs Claude variants
- **Dynamic prompts**: Sisyphus, Hephaestus use `dynamic-agent-prompt-builder.ts` to inject available tools/skills/categories
-
 ## ANTI-PATTERNS

 - **Trust agent self-reports**: NEVER — always verify outputs
--- a/src/cli/AGENTS.md
+++ b/src/cli/AGENTS.md
@@ -2,9 +2,7 @@

 ## OVERVIEW

-CLI entry: `bunx oh-my-opencode`. 107+ files with Commander.js + @clack/prompts TUI.
-
-**Commands**: install, run, doctor, get-local-version, mcp-oauth
+CLI entry: `bunx oh-my-opencode`. 107+ files with Commander.js + @clack/prompts TUI. 5 commands: install, run, doctor, get-local-version, mcp-oauth.

 ## STRUCTURE
 ```
@@ -14,20 +12,22 @@ cli/
 ├── install.ts               # TTY routing (TUI or CLI installer)
 ├── cli-installer.ts         # Non-interactive installer (164 lines)
 ├── tui-installer.ts         # Interactive TUI with @clack/prompts (140 lines)
-├── config-manager/          # 17 config utilities
+├── config-manager/          # 20 config utilities
 │   ├── add-plugin-to-opencode-config.ts  # Plugin registration
-│   ├── add-provider-config.ts            # Provider setup
-│   ├── detect-current-config.ts          # Project vs user config
+│   ├── add-provider-config.ts            # Provider setup (Google/Antigravity)
+│   ├── detect-current-config.ts          # Installed providers detection
 │   ├── write-omo-config.ts               # JSONC writing
-│   └── ...
-├── doctor/                  # 14 health checks
-│   ├── runner.ts            # Check orchestration
-│   ├── formatter.ts         # Colored output
-│   └── checks/              # 29 files: auth, config, dependencies, gh, lsp, mcp, opencode, plugin, version, model-resolution (6 sub-checks)
+│   ├── generate-omo-config.ts            # Config generation
+│   ├── jsonc-provider-editor.ts          # JSONC editing
+│   └── ...                               # 14 more utilities
+├── doctor/                  # 4 check categories, 21 check files
+│   ├── runner.ts            # Parallel check execution + result aggregation
+│   ├── formatter.ts         # Colored output (default/status/verbose/JSON)
+│   └── checks/              # system (4), config (1), tools (4), models (6 sub-checks)
 ├── run/                     # Session launcher (24 files)
 │   ├── runner.ts            # Run orchestration (126 lines)
-│   ├── agent-resolver.ts    # Agent selection: flag → env → config → fallback
-│   ├── session-resolver.ts  # Session creation or resume
+│   ├── agent-resolver.ts    # Agent: flag → env → config → Sisyphus
+│   ├── session-resolver.ts  # Session create or resume with retries
 │   ├── event-handlers.ts    # Event processing (125 lines)
 │   ├── completion.ts        # Completion detection
 │   └── poll-for-completion.ts # Polling with timeout
@@ -43,20 +43,17 @@ cli/
 |---------|---------|-----------|
 | `install` | Interactive setup | Provider selection → config generation → plugin registration |
 | `run` | Session launcher | Agent: flag → env → config → Sisyphus. Enforces todo completion. |
-| `doctor` | 14 health checks | installation, config, auth, deps, tools, updates |
+| `doctor` | 4-category health checks | system, config, tools, models (6 sub-checks) |
 | `get-local-version` | Version check | Detects installed, compares with npm latest |
 | `mcp-oauth` | OAuth tokens | login (PKCE flow), logout, status |

-## DOCTOR CHECK CATEGORIES
+## RUN SESSION LIFECYCLE

-| Category | Checks |
-|----------|--------|
-| installation | opencode, plugin |
-| configuration | config validity, Zod, model-resolution (6 sub-checks) |
-| authentication | anthropic, openai, google |
-| dependencies | ast-grep, comment-checker, gh-cli |
-| tools | LSP, MCP, MCP-OAuth |
-| updates | version comparison |
+1. Load config, resolve agent (CLI > env > config > Sisyphus)
+2. Create server connection (port/attach), setup cleanup/signal handlers
+3. Resolve session (create new or resume with retries)
+4. Send prompt, start event processing, poll for completion
+5. Execute on-complete hook, output JSON if requested, cleanup

 ## HOW TO ADD CHECK

--- a/src/features/AGENTS.md
+++ b/src/features/AGENTS.md
@@ -7,16 +7,17 @@
 ## STRUCTURE
 ```
 features/
-├── background-agent/           # Task lifecycle, concurrency (50 files, 8330 LOC)
-│   ├── manager.ts              # Main task orchestration (1646 lines)
-│   ├── concurrency.ts          # Parallel execution limits per provider/model
-│   └── spawner/                # Task spawning utilities (8 files)
+├── background-agent/           # Task lifecycle, concurrency (56 files, 1701-line manager)
+│   ├── manager.ts              # Main task orchestration (1701 lines)
+│   ├── concurrency.ts          # Parallel execution limits per provider/model (137 lines)
+│   ├── task-history.ts         # Task execution history per parent session (76 lines)
+│   └── spawner/                # Task spawning: factory, starter, resumer, tmux (8 files)
 ├── tmux-subagent/              # Tmux integration (28 files, 3303 LOC)
 │   └── manager.ts              # Pane management, grid planning (350 lines)
 ├── opencode-skill-loader/      # YAML frontmatter skill loading (28 files, 2967 LOC)
 │   ├── loader.ts               # Skill discovery (4 scopes)
-│   ├── skill-directory-loader.ts # Recursive directory scanning
-│   ├── skill-discovery.ts      # getAllSkills() with caching
+│   ├── skill-directory-loader.ts # Recursive directory scanning (maxDepth=2)
+│   ├── skill-discovery.ts      # getAllSkills() with caching + provider gating
 │   └── merger/                 # Skill merging with scope priority
 ├── mcp-oauth/                  # OAuth 2.0 flow for MCP (18 files, 2164 LOC)
 │   ├── provider.ts             # McpOAuthProvider class
@@ -25,10 +26,10 @@ features/
 ├── skill-mcp-manager/          # MCP client lifecycle per session (12 files, 1769 LOC)
 │   └── manager.ts              # SkillMcpManager class (150 lines)
 ├── builtin-skills/             # 5 built-in skills (10 files, 1921 LOC)
-│   └── skills/                 # git-master (1111), playwright, dev-browser, frontend-ui-ux
-├── builtin-commands/           # 6 command templates (11 files, 1511 LOC)
-│   └── templates/              # refactor, ralph-loop, init-deep, handoff, start-work, stop-continuation
-├── claude-tasks/               # Task schema + storage (7 files, 1165 LOC)
+│   └── skills/                 # git-master (1112), playwright (313), dev-browser (222), frontend-ui-ux (80)
+├── builtin-commands/           # 7 command templates (11 files, 1511 LOC)
+│   └── templates/              # refactor (620), init-deep (306), handoff (178), start-work, ralph-loop, stop-continuation
+├── claude-tasks/               # Task schema + storage (7 files) — see AGENTS.md
 ├── context-injector/           # AGENTS.md, README.md, rules injection (6 files, 809 LOC)
 ├── claude-code-plugin-loader/  # Plugin discovery from .opencode/plugins/ (10 files)
 ├── claude-code-mcp-loader/     # .mcp.json with ${VAR} expansion (6 files)
@@ -44,7 +45,10 @@ features/
 ## KEY PATTERNS

 **Background Agent Lifecycle:**
-Task creation → Queue → Concurrency check → Execute → Monitor/Poll → Notification → Cleanup
+pending → running → completed/error/cancelled/interrupt
+- Concurrency: Per provider/model limits (default: 5), queue-based FIFO
+- Events: session.idle + session.error drive completion detection
+- Key methods: `launch()`, `resume()`, `cancelTask()`, `getTask()`, `getAllDescendantTasks()`

 **Skill Loading Pipeline (4-scope priority):**
 opencode-project (`.opencode/skills/`) > opencode (`~/.config/opencode/skills/`) > project (`.claude/skills/`) > user (`~/.claude/skills/`)
--- a/src/features/claude-tasks/AGENTS.md
+++ b/src/features/claude-tasks/AGENTS.md
@@ -2,7 +2,7 @@

 ## OVERVIEW

-Claude Code compatible task schema and storage. Core task management with file-based persistence and atomic writes.
+Claude Code compatible task schema and storage. Core task management with file-based persistence, atomic writes, and OpenCode todo sync.

 ## STRUCTURE
 ```
@@ -50,39 +50,16 @@ interface Task {

 ## TODO SYNC

-Automatic bidirectional synchronization between tasks and OpenCode's todo system.
-
-| Function | Purpose |
-|----------|---------|
-| `syncTaskToTodo(task)` | Convert Task to TodoInfo, returns `null` for deleted tasks |
-| `syncTaskTodoUpdate(ctx, task, sessionID, writer?)` | Fetch current todos, update specific task, write back |
-| `syncAllTasksToTodos(ctx, tasks, sessionID?)` | Bulk sync multiple tasks to todos |
-
-### Status Mapping
+Automatic bidirectional sync between tasks and OpenCode's todo system.

 | Task Status | Todo Status |
 |-------------|-------------|
 | `pending` | `pending` |
 | `in_progress` | `in_progress` |
 | `completed` | `completed` |
-| `deleted` | `null` (removed from todos) |
+| `deleted` | `null` (removed) |

-### Field Mapping
-
-| Task Field | Todo Field |
-|------------|------------|
-| `task.id` | `todo.id` |
-| `task.subject` | `todo.content` |
-| `task.status` (mapped) | `todo.status` |
-| `task.metadata.priority` | `todo.priority` |
-
-Priority values: `"low"`, `"medium"`, `"high"`
-
-### Automatic Sync Triggers
-
-Sync occurs automatically on:
- `task_create` — new task added to todos
- `task_update` — task changes reflected in todos
+Sync triggers: `task_create`, `task_update`.

 ## ANTI-PATTERNS

--- a/src/hooks/AGENTS.md
+++ b/src/hooks/AGENTS.md
@@ -8,18 +8,18 @@
 ```
 hooks/
 ├── agent-usage-reminder/         # Specialized agent hints (109 lines)
-├── anthropic-context-window-limit-recovery/ # Auto-summarize on limit (2232 lines)
+├── anthropic-context-window-limit-recovery/ # Auto-summarize on limit (2232 lines, 29 files)
 ├── anthropic-effort/             # Effort=max for Opus max variant (56 lines)
-├── atlas/                        # Main orchestration hook (1976 lines)
+├── atlas/                        # Main orchestration hook (1976 lines, 17 files)
 ├── auto-slash-command/           # Detects /command patterns (1134 lines)
-├── auto-update-checker/          # Plugin update check (1140 lines)
+├── auto-update-checker/          # Plugin update check (1140 lines, 20 files)
 ├── background-notification/      # OS notifications (33 lines)
 ├── category-skill-reminder/      # Category+skill delegation reminders (597 lines)
-├── claude-code-hooks/            # settings.json compat (2110 lines) - see AGENTS.md
+├── claude-code-hooks/            # settings.json compat (2110 lines) — see AGENTS.md
 ├── comment-checker/              # Prevents AI slop comments (710 lines)
 ├── compaction-context-injector/  # Injects context on compaction (128 lines)
 ├── compaction-todo-preserver/    # Preserves todos during compaction (203 lines)
-├── context-window-monitor.ts     # Reminds of headroom at 70% (99 lines)
+├── context-window-monitor.ts     # Reminds of headroom at 70% (100 lines)
 ├── delegate-task-retry/          # Retries failed delegations (266 lines)
 ├── directory-agents-injector/    # Auto-injects AGENTS.md (195 lines)
 ├── directory-readme-injector/    # Auto-injects README.md (190 lines)
@@ -34,7 +34,7 @@ hooks/
 ├── ralph-loop/                   # Self-referential dev loop (1687 lines)
 ├── rules-injector/               # Conditional .sisyphus/rules injection (1604 lines)
 ├── session-notification.ts       # OS idle notifications (108 lines)
-├── session-recovery/             # Auto-recovers from crashes (1279 lines)
+├── session-recovery/             # Auto-recovers from crashes (1279 lines, 14 files)
 ├── sisyphus-junior-notepad/      # Junior notepad directive (76 lines)
 ├── start-work/                   # Sisyphus work session starter (648 lines)
 ├── stop-continuation-guard/      # Guards stop continuation (214 lines)
@@ -57,10 +57,10 @@ hooks/
 | UserPromptSubmit | `chat.message` | Yes | 4 |
 | ChatParams | `chat.params` | No | 2 |
 | PreToolUse | `tool.execute.before` | Yes | 13 |
-| PostToolUse | `tool.execute.after` | No | 18 |
+| PostToolUse | `tool.execute.after` | No | 15 |
 | SessionEvent | `event` | No | 17 |
 | MessagesTransform | `experimental.chat.messages.transform` | No | 1 |
-| Compaction | `onSummarize` | No | 1 |
+| Compaction | `onSummarize` | No | 2 |

 ## BLOCKING HOOKS (8)

@@ -78,7 +78,7 @@ hooks/
 ## EXECUTION ORDER

 **UserPromptSubmit**: keywordDetector → claudeCodeHooks → autoSlashCommand → startWork
-**PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → atlasHook
+**PreToolUse**: subagentQuestionBlocker → questionLabelTruncator → claudeCodeHooks → nonInteractiveEnv → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → prometheusMdOnly → sisyphusJuniorNotepad → writeExistingFileGuard → tasksToDoWriteDisabler → atlasHook
 **PostToolUse**: claudeCodeHooks → toolOutputTruncator → contextWindowMonitor → commentChecker → directoryAgentsInjector → directoryReadmeInjector → rulesInjector → emptyTaskResponseDetector → agentUsageReminder → interactiveBashSession → editErrorRecovery → delegateTaskRetry → atlasHook → taskResumeInfo → taskReminder

 ## HOW TO ADD
--- a/src/hooks/claude-code-hooks/AGENTS.md
+++ b/src/hooks/claude-code-hooks/AGENTS.md
@@ -2,7 +2,7 @@

 ## OVERVIEW

-Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands.
+Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode events to execute external scripts/commands defined in settings.json.

 **Config Sources** (priority): `.claude/settings.local.json` > `.claude/settings.json` (project) > `~/.claude/settings.json` (global)

@@ -10,21 +10,26 @@ Full Claude Code `settings.json` hook compatibility layer. Intercepts OpenCode e
 ```
 claude-code-hooks/
 ├── index.ts              # Barrel export
-├── claude-code-hooks-hook.ts  # Main factory
-├── config.ts             # Claude settings.json loader
-├── config-loader.ts      # Extended plugin config
-├── pre-tool-use.ts       # PreToolUse hook executor
-├── post-tool-use.ts      # PostToolUse hook executor
-├── user-prompt-submit.ts # UserPromptSubmit executor
-├── stop.ts               # Stop hook executor
-├── pre-compact.ts        # PreCompact executor
-├── transcript.ts         # Tool use recording
-├── tool-input-cache.ts   # Pre→post input caching
+├── claude-code-hooks-hook.ts  # Main factory (22 lines)
+├── config.ts             # Claude settings.json loader (105 lines)
+├── config-loader.ts      # Extended plugin config (107 lines)
+├── pre-tool-use.ts       # PreToolUse hook executor (173 lines)
+├── post-tool-use.ts      # PostToolUse hook executor (200 lines)
+├── user-prompt-submit.ts # UserPromptSubmit executor (125 lines)
+├── stop.ts               # Stop hook executor (122 lines)
+├── pre-compact.ts        # PreCompact executor (110 lines)
+├── transcript.ts         # Tool use recording (235 lines)
+├── tool-input-cache.ts   # Pre→post input caching (51 lines)
 ├── todo.ts               # Todo integration
-├── session-hook-state.ts # Active state tracking
-├── types.ts              # Hook & IO type definitions
-├── plugin-config.ts      # Default config constants
+├── session-hook-state.ts # Active state tracking (11 lines)
+├── types.ts              # Hook & IO type definitions (204 lines)
+├── plugin-config.ts      # Default config constants (12 lines)
 └── handlers/             # Event handlers (5 files)
+    ├── pre-compact-handler.ts
+    ├── tool-execute-before-handler.ts
+    ├── tool-execute-after-handler.ts
+    ├── chat-message-handler.ts
+    └── session-event-handler.ts
 ```

 ## HOOK LIFECYCLE
--- a/src/plugin-handlers/AGENTS.md
+++ b/src/plugin-handlers/AGENTS.md
@@ -2,7 +2,7 @@

 ## OVERVIEW

-Configuration orchestration layer. Runs once at plugin init — transforms raw OpenCode config into resolved agent/tool/permission structures.
+Configuration orchestration layer. Runs once at plugin init — transforms raw OpenCode config into resolved agent/tool/permission structures via 6-phase sequential loading.

 ## STRUCTURE
 ```
--- a/src/shared/AGENTS.md
+++ b/src/shared/AGENTS.md
@@ -2,21 +2,21 @@

 ## OVERVIEW

-84 cross-cutting utilities across 6 subdirectories. Import via barrel: `import { log, deepMerge } from "../../shared"`
+96 cross-cutting utilities across 4 subdirectories. Import via barrel: `import { log, deepMerge } from "../../shared"`

 ## STRUCTURE
 ```
 shared/
 ├── logger.ts                  # File logging (/tmp/oh-my-opencode.log) — 62 imports
-├── dynamic-truncator.ts       # Token-aware context window management (201 lines)
-├── model-resolver.ts          # 3-step resolution (Override → Fallback → Default)
-├── model-availability.ts      # Provider model fetching & fuzzy matching (358 lines)
-├── model-requirements.ts      # Agent/category fallback chains (160 lines)
-├── model-resolution-pipeline.ts # Pipeline orchestration (175 lines)
+├── dynamic-truncator.ts       # Token-aware context window management (202 lines)
+├── model-resolver.ts          # 3-step resolution entry point (65 lines)
+├── model-availability.ts      # Provider model fetching & fuzzy matching (359 lines)
+├── model-requirements.ts      # Agent/category fallback chains (161 lines) — 11 imports
+├── model-resolution-pipeline.ts # Pipeline orchestration (176 lines)
 ├── model-resolution-types.ts  # Resolution request/provenance types
 ├── model-sanitizer.ts         # Model name sanitization
 ├── model-name-matcher.ts      # Model name matching (91 lines)
-├── model-suggestion-retry.ts  # Suggest models on failure (129 lines)
+├── model-suggestion-retry.ts  # Suggest models on failure (144 lines)
 ├── model-cache-availability.ts # Cache availability checking
 ├── fallback-model-availability.ts # Fallback model logic (67 lines)
 ├── available-models-fetcher.ts # Fetch models from providers (114 lines)
@@ -27,42 +27,34 @@ shared/
 ├── session-utils.ts           # Session cursor, orchestrator detection
 ├── session-cursor.ts          # Message cursor tracking (85 lines)
 ├── session-injected-paths.ts  # Injected file path tracking
-├── permission-compat.ts       # Tool restriction enforcement (86 lines)
+├── permission-compat.ts       # Tool restriction enforcement (87 lines) — 9 imports
 ├── agent-tool-restrictions.ts # Tool restriction definitions
 ├── agent-variant.ts           # Agent variant from config (91 lines)
 ├── agent-display-names.ts     # Agent display name mapping
 ├── first-message-variant.ts   # First message variant types
 ├── opencode-config-dir.ts     # ~/.config/opencode resolution (138 lines)
 ├── claude-config-dir.ts       # ~/.claude resolution
-├── data-path.ts               # XDG-compliant storage (47 lines)
+├── data-path.ts               # XDG-compliant storage (47 lines) — 11 imports
 ├── jsonc-parser.ts            # JSONC with comment support (66 lines)
 ├── frontmatter.ts             # YAML frontmatter extraction (31 lines) — 10 imports
 ├── deep-merge.ts              # Recursive merge (proto-pollution safe, MAX_DEPTH=50)
 ├── shell-env.ts               # Cross-platform shell environment (111 lines)
-├── opencode-version.ts        # Semantic version comparison (74 lines)
+├── opencode-version.ts        # Semantic version comparison (80 lines)
 ├── external-plugin-detector.ts # Plugin conflict detection (137 lines)
-├── opencode-server-auth.ts    # Authentication utilities (69 lines)
+├── opencode-server-auth.ts    # Authentication utilities (190 lines)
 ├── safe-create-hook.ts        # Hook error wrapper (24 lines)
 ├── pattern-matcher.ts         # Pattern matching (40 lines)
-├── file-utils.ts              # File operations (40 lines) — 9 imports
+├── file-utils.ts              # File operations (34 lines) — 9 imports
 ├── file-reference-resolver.ts # File reference resolution (85 lines)
 ├── snake-case.ts              # Case conversion (44 lines)
 ├── tool-name.ts               # Tool naming conventions
-├── truncate-description.ts    # Description truncation
 ├── port-utils.ts              # Port management (48 lines)
 ├── zip-extractor.ts           # ZIP extraction (83 lines)
 ├── binary-downloader.ts       # Binary download (60 lines)
-├── skill-path-resolver.ts     # Skill path resolution
-├── hook-disabled.ts           # Hook disable checking
-├── config-errors.ts           # Config error types
-├── disabled-tools.ts          # Disabled tools tracking
-├── record-type-guard.ts       # Record type guard
-├── open-code-client-accessors.ts # Client accessor utilities
-├── open-code-client-shapes.ts # Client shape types
 ├── command-executor/          # Shell execution (6 files, 213 lines)
 ├── git-worktree/              # Git status/diff parsing (8 files, 311 lines)
 ├── migration/                 # Legacy config migration (5 files, 341 lines)
-│   ├── config-migration.ts    # Migration orchestration (126 lines)
+│   ├── config-migration.ts    # Migration orchestration (133 lines)
 │   ├── agent-names.ts         # Agent name mapping (70 lines)
 │   ├── hook-names.ts          # Hook name mapping (36 lines)
 │   └── model-versions.ts      # Model version migration (49 lines)
@@ -86,9 +78,9 @@ shared/
 ## KEY PATTERNS

 **3-Step Model Resolution** (Override → Fallback → Default):
-```typescript
-resolveModelWithFallback({ userModel, fallbackChain, availableModels })
-```
+1. **Override**: UI-selected or user-configured model
+2. **Fallback**: Provider/model chain with availability checking
+3. **Default**: System fallback when no matches found

 **System Directive Filtering**:
 ```typescript
--- a/src/tools/AGENTS.md
+++ b/src/tools/AGENTS.md
@@ -2,19 +2,19 @@

 ## OVERVIEW

-24 tools across 14 directories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent).
+26 tools across 14 directories. Two patterns: Direct ToolDefinition (static) and Factory Function (context-dependent).

 ## STRUCTURE
 ```
 tools/
 ├── delegate-task/    # Category routing (constants.ts 569 lines, tools.ts 213 lines)
-├── task/             # 4 individual tools: create, list, get, update (task-create.ts, task-list.ts, task-get.ts, task-update.ts)
+├── task/             # 4 tools: create, list, get, update (task-create.ts, task-list.ts, task-get.ts, task-update.ts)
 ├── lsp/              # 6 LSP tools: goto_definition, find_references, symbols, diagnostics, prepare_rename, rename
 ├── ast-grep/         # 2 tools: search, replace (25 languages)
-├── grep/             # Custom grep (60s timeout, 10MB limit)
-├── glob/             # File search (60s timeout, 100 file limit)
-├── session-manager/  # 4 tools: list, read, search, info (151 lines)
-├── call-omo-agent/   # Direct agent invocation (57 lines)
+├── grep/             # Content search (60s timeout, 10MB limit)
+├── glob/             # File pattern matching (60s timeout, 100 file limit)
+├── session-manager/  # 4 tools: list, read, search, info
+├── call-omo-agent/   # Direct agent invocation (explore/librarian)
 ├── background-task/  # background_output, background_cancel
 ├── interactive-bash/ # Tmux session management (135 lines)
 ├── look-at/          # Multimodal PDF/image analysis (156 lines)
@@ -27,13 +27,14 @@ tools/

 | Tool | Category | Pattern | Key Logic |
 |------|----------|---------|-----------|
-| `task_create` | Task | Factory | Create task with auto-generated T-{uuid} ID, threadID recording |
-| `task_list` | Task | Factory | List active tasks with summary (excludes completed/deleted) |
-| `task_get` | Task | Factory | Retrieve full task object by ID |
-| `task_update` | Task | Factory | Update task fields, supports addBlocks/addBlockedBy for dependencies |
+| `task_create` | Task | Factory | Auto-generated T-{uuid} ID, threadID recording, dependency management |
+| `task_list` | Task | Factory | Active tasks with summary (excludes completed/deleted), filters unresolved blockers |
+| `task_get` | Task | Factory | Full task object by ID |
+| `task_update` | Task | Factory | Status/field updates, additive addBlocks/addBlockedBy for dependencies |
+| `task` | Delegation | Factory | Category routing with skill injection, background execution |
 | `call_omo_agent` | Agent | Factory | Direct explore/librarian invocation |
-| `background_output` | Background | Factory | Retrieve background task result |
-| `background_cancel` | Background | Factory | Cancel running background tasks |
+| `background_output` | Background | Factory | Retrieve background task result (block, timeout, full_session) |
+| `background_cancel` | Background | Factory | Cancel running/all background tasks |
 | `lsp_goto_definition` | LSP | Direct | Jump to symbol definition |
 | `lsp_find_references` | LSP | Direct | Find all usages across workspace |
 | `lsp_symbols` | LSP | Direct | Document or workspace symbol search |
@@ -41,121 +42,33 @@ tools/
 | `lsp_prepare_rename` | LSP | Direct | Validate rename is possible |
 | `lsp_rename` | LSP | Direct | Rename symbol across workspace |
 | `ast_grep_search` | Search | Factory | AST-aware code search (25 languages) |
-| `ast_grep_replace` | Search | Factory | AST-aware code replacement |
+| `ast_grep_replace` | Search | Factory | AST-aware code replacement (dry-run default) |
 | `grep` | Search | Factory | Regex content search with safety limits |
 | `glob` | Search | Factory | File pattern matching |
 | `session_list` | Session | Factory | List all sessions |
-| `session_read` | Session | Factory | Read session messages |
+| `session_read` | Session | Factory | Read session messages with filters |
 | `session_search` | Session | Factory | Search across sessions |
 | `session_info` | Session | Factory | Session metadata and stats |
 | `interactive_bash` | System | Direct | Tmux session management |
-| `look_at` | System | Factory | Multimodal PDF/image analysis |
-| `skill` | Skill | Factory | Execute skill with MCP capabilities |
-| `skill_mcp` | Skill | Factory | Call MCP tools/resources/prompts |
-| `slashcommand` | Command | Factory | Slash command dispatch |
-
-## TASK TOOLS
-
-Task management system with auto-generated T-{uuid} IDs, dependency tracking, and OpenCode Todo API sync.
-
-### task_create
-
-Create a new task with auto-generated ID and threadID recording.
-
-**Args:**
-| Arg | Type | Required | Description |
-|-----|------|----------|-------------|
-| `subject` | string | Yes | Task subject/title |
-| `description` | string | No | Task description |
-| `activeForm` | string | No | Active form (present continuous) |
-| `metadata` | Record<string, unknown> | No | Task metadata |
-| `blockedBy` | string[] | No | Task IDs that must complete before this task |
-| `blocks` | string[] | No | Task IDs this task blocks |
-| `repoURL` | string | No | Repository URL |
-| `parentID` | string | No | Parent task ID |
-
-**Example:**
-```typescript
-task_create({
-  subject: "Implement user authentication",
-  description: "Add JWT-based auth to API endpoints",
-  blockedBy: ["T-abc123"] // Wait for database migration
-})
-```
-
-**Returns:** `{ task: { id, subject } }`
-
-### task_list
-
-List all active tasks with summary information.
-
-**Args:** None
-
-**Returns:** Array of task summaries with id, subject, status, owner, blockedBy. Excludes completed and deleted tasks. The blockedBy field is filtered to only include unresolved (non-completed) blockers.
-
-**Example:**
-```typescript
-task_list() // Returns all active tasks
-```
-
-**Response includes reminder:** "1 task = 1 task. Maximize parallel execution by running independent tasks (tasks with empty blockedBy) concurrently."
-
-### task_get
-
-Retrieve a full task object by ID.
-
-**Args:**
-| Arg | Type | Required | Description |
-|-----|------|----------|-------------|
-| `id` | string | Yes | Task ID (format: T-{uuid}) |
-
-**Example:**
-```typescript
-task_get({ id: "T-2a200c59-1a36-4dad-a9c3-3064d180f694" })
-```
-
-**Returns:** `{ task: TaskObject | null }` with all fields: id, subject, description, status, activeForm, blocks, blockedBy, owner, metadata, repoURL, parentID, threadID.
-
-### task_update
-
-Update an existing task with new values. Supports additive updates for dependencies.
-
-**Args:**
-| Arg | Type | Required | Description |
-|-----|------|----------|-------------|
-| `id` | string | Yes | Task ID to update |
-| `subject` | string | No | New subject |
-| `description` | string | No | New description |
-| `status` | "pending" \| "in_progress" \| "completed" \| "deleted" | No | Task status |
-| `activeForm` | string | No | Active form (present continuous) |
-| `owner` | string | No | Task owner (agent name) |
-| `addBlocks` | string[] | No | Task IDs to add to blocks (additive) |
-| `addBlockedBy` | string[] | No | Task IDs to add to blockedBy (additive) |
-| `metadata` | Record<string, unknown> | No | Metadata to merge (set key to null to delete) |
-
-**Example:**
-```typescript
-task_update({
-  id: "T-2a200c59-1a36-4dad-a9c3-3064d180f694",
-  status: "completed"
-})
-
-// Add dependencies
-task_update({
-  id: "T-2a200c59-1a36-4dad-a9c3-3064d180f694",
-  addBlockedBy: ["T-other-task"]
-})
-```
-
-**Returns:** `{ task: TaskObject }` with full updated task.
-
-**Dependency Management:** Use `addBlockedBy` to declare dependencies on other tasks. Properly managed dependencies enable maximum parallel execution.
+| `look_at` | System | Factory | Multimodal PDF/image analysis via dedicated agent |
+| `skill` | Skill | Factory | Load skill instructions with MCP support |
+| `skill_mcp` | Skill | Factory | Call MCP tools/resources/prompts from skill-embedded servers |
+| `slashcommand` | Command | Factory | Slash command dispatch with argument substitution |

 ## DELEGATION SYSTEM (delegate-task)

-8 built-in categories: `visual-engineering`, `ultrabrain`, `deep`, `artistry`, `quick`, `unspecified-low`, `unspecified-high`, `writing`
+8 built-in categories with domain-optimized models:

-Each category defines: model, variant, temperature, max tokens, thinking/reasoning config, prompt append, stability flag.
+| Category | Model | Domain |
+|----------|-------|--------|
+| `visual-engineering` | gemini-3-pro | UI/UX, design, styling |
+| `ultrabrain` | gpt-5.3-codex xhigh | Deep logic, architecture |
+| `deep` | gpt-5.3-codex medium | Autonomous problem-solving |
+| `artistry` | gemini-3-pro high | Creative, unconventional |
+| `quick` | claude-haiku-4-5 | Trivial tasks |
+| `unspecified-low` | claude-sonnet-4-5 | Moderate effort |
+| `unspecified-high` | claude-opus-4-6 max | High effort |
+| `writing` | kimi-k2p5 | Documentation, prose |

 ## HOW TO ADD