docs: update AGENTS guidance

src/AGENTS.md

@@ -1,10 +1,10 @@
 # src/ — Plugin Source
 
-**Generated:** 2026-05-15
+**Generated:** 2026-05-18
 
 ## OVERVIEW
 
-Entry `index.ts` orchestrates a 7-step initialization. Total: 1340 source files + 701 tests across the directories below. Cross-cutting helpers live in `shared/`; module boundaries are established by 122 barrel `index.ts` files.
+Entry `index.ts` orchestrates a 7-step initialization. Total: 1351 source files + 722 tests across the directories below. Cross-cutting helpers live in `shared/`; module boundaries are established by 122 barrel `index.ts` files.
 
 ## KEY FILES
 
@@ -88,19 +88,19 @@ Total: 54 base, 61 with team-mode. Each tier produces an object whose values are
 
 | Subdir | Files (.ts) | LOC | Purpose | Has AGENTS.md |
 |--------|-------------|-----|---------|---------------|
-| `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 | — |
+| `agents/` | 104 | ~20k | 11 agent factories + dynamic prompt builder | yes (+ atlas, hephaestus, prometheus, sisyphus, sisyphus-junior, builtin-agents) |
+| `hooks/` | 596 | ~78k | ~52 lifecycle hooks across 58 dirs | yes (+ atlas, anthropic-context-window-limit-recovery, auto-update-checker, claude-code-hooks, comment-checker, compaction-context-injector, keyword-detector, ralph-loop, rules-injector, runtime-fallback, session-recovery, todo-continuation-enforcer) |
+| `tools/` | 317 | ~45k | 16 tool dirs producing 20–39 tools | yes (+ ast-grep, background-task, call-omo-agent, delegate-task, hashline-edit, look-at, lsp, skill) |
+| `features/` | 404 | ~71k | 20 feature modules (team-mode, background-agent, boulder-state, etc.) | yes (+ 11 sub-AGENTS.md including builtin-skills, team-mode, background-agent, claude-code-*) |
+| `shared/` | 290 | ~33k | Cross-cutting utilities, barrel-exported | yes |
+| `cli/` | 158 | ~18k | Commander.js CLI: install, run, doctor, mcp-oauth, boulder | yes (+ config-manager, doctor, run) |
+| `plugin/` | 58 | ~12k | 10 OpenCode hook handlers + hook composition | yes |
+| `config/` | 41 | ~2k | 30 Zod v4 schema files | yes |
+| `plugin-handlers/` | 27 | ~6k | 6-phase config loading pipeline | yes |
+| `openclaw/` | 26 | ~3k | Bidirectional Discord/Telegram/HTTP integration | yes |
+| `__tests__/` | 22 | ~300 | Plugin-level integration tests + perf fixtures | — |
+| `mcp/` | 7 | ~200 | 3 built-in remote MCPs | yes |
+| `testing/` | 3 | ~225 | Test utilities | — |
 
 ## NOTES
 

src/agents/atlas/AGENTS.md

@@ -0,0 +1,55 @@
+---
+name: atlas-agent
+description: Developer reference for the Atlas todo-list orchestrator agent -- model variants, prompt sections, and routing.
+---
+
+# src/agents/atlas/ -- Todo-List Orchestrator
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+17 files. Atlas agent -- todo-list orchestrator that delegates via `task()` to complete every checkbox in a plan until fully done. Mode `primary`. Color `#10B981`.
+
+## FILES
+
+| File | Purpose |
+|------|---------|
+| `agent.ts` | `createAtlasAgent()` factory, model-variant routing, `OrchestratorContext` |
+| `index.ts` | Barrel exports |
+| `default.ts` | Default/Claude prompt variant |
+| `gemini.ts` | Gemini-optimized prompt variant |
+| `gpt.ts` | GPT-optimized prompt variant |
+| `kimi.ts` | Kimi K2.x prompt variant |
+| `opus-4-7.ts` | Claude Opus 4.7 prompt variant |
+| `default-prompt-sections.ts` | Default prompt section definitions |
+| `gemini-prompt-sections.ts` | Gemini prompt section definitions |
+| `gpt-prompt-sections.ts` | GPT prompt section definitions |
+| `kimi-prompt-sections.ts` | Kimi prompt section definitions |
+| `opus-4-7-prompt-sections.ts` | Opus 4.7 prompt section definitions |
+| `prompt-section-builder.ts` | Composes category, agent, skills, and decision matrix sections |
+| `shared-prompt.ts` | Shared prompt content: delegation system, parallel rules, auto-continue, notepad protocol, post-delegation rule, boulder completion |
+| `atlas-prompt.test.ts` | Prompt composition tests |
+| `prompt-checkbox-enforcement.test.ts` | Checkbox enforcement behavior tests |
+| `prompt-routing.test.ts` | Model-variant routing tests |
+
+## MODEL VARIANT ROUTING
+
+Parent `agent.ts` selects variant by model name:
+- `isGptModel()` -> `gpt.ts`
+- `isGeminiModel()` -> `gemini.ts`
+- `isKimiK2Model()` -> `kimi.ts`
+- `isClaudeOpus47Model()` -> `opus-4-7.ts`
+- Default -> `default.ts` (Claude 4.6 family)
+
+## KEY BEHAVIORS
+
+- Mode: `primary` (respects UI model selection)
+- Temperature: 0.1
+- Default model: `claude-sonnet-4-6`
+- Denied tools: `task`, `call_omo_agent` (Atlas delegates; it does not run subagents directly)
+- Checkbox enforcement in prompts (per `prompt-checkbox-enforcement.test.ts`)
+- Auto-continue: never asks user for approval between plan steps
+- Parallel fan-out by default; sequential only for named blocking dependencies
+- Post-delegation rule: edit plan checkbox, read plan to confirm, then dispatch next task
+- Registered via `createAtlasAgent` in `src/agents/builtin-agents/atlas-agent.ts`

src/agents/builtin-agents/AGENTS.md

@@ -0,0 +1,33 @@
+---
+name: builtin-agents-factory-layer
+description: Conditional factory wrappers that apply overrides, model resolution, skill filtering, and provider gating to the 11 agent definitions.
+---
+
+# src/agents/builtin-agents/ -- Conditional Factory Layer
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+Conditional factory layer beneath the 11 raw `createXXXAgent` factories in `src/agents/`. Each `maybeCreateXXXConfig` wrapper decides whether an agent registers, resolves its model via the 4-step pipeline, applies user overrides, filters skills, and returns the final `AgentConfig` -- or `undefined` if the agent is disabled or requirements are not met. Outputs feed `createPluginInterface`.
+
+## FILE CATALOG
+
+| File | Purpose |
+|------|---------|
+| `agent-overrides.ts` | Applies user overrides: category expansion, `deepMerge` of model/temp/prompt/permissions, `file://` prompt resolution |
+| `model-resolution.ts` | 4-step pipeline wrapper: `resolveModelPipeline` (override → category → provider fallback → system default) + `getFirstFallbackModel` |
+| `resolve-file-uri.ts` | Converts `file://` paths to absolute paths, bounds them to project root, reads content for prompt append |
+| `resolve-file-uri.test.ts` | Tests for URI decoding, path expansion, project-root bounds, missing-file handling |
+| `environment-context.ts` | Appends `createEnvContext()` block to agent prompt unless `disableOmoEnv` is set |
+| `available-skills.ts` | `buildAvailableSkills` -- merges builtin skills with discovered user skills, filters disabled |
+| `available-skills.test.ts` | Tests for builtin + discovered skill merging and disabled filtering |
+| `sisyphus-agent.ts` | `maybeCreateSisyphusConfig` -- checks disabled list, model requirements, applies overrides + frontier tool schema guard + GPT patch guard |
+| `sisyphus-agent.test.ts` | Tests for disabled-agent filtering, model resolution, override application, first-run fallback behavior |
+| `hephaestus-agent.ts` | `maybeCreateHephaestusConfig` -- provider gating (`requiresProvider`), category override support, variant defaulting to medium |
+| `atlas-agent.ts` | `maybeCreateAtlasConfig` -- UI-selected model respect, variant resolution |
+| `general-agents.ts` | `collectPendingBuiltinAgents` -- handles all non-special-cased agents (skips sisyphus/hephaestus/atlas/sisyphus-junior), bulk model resolution and override application |
+
+## PIPELINE FIT
+
+Phase 3 of `plugin-handlers/config-handler.ts` invokes these factories. The resulting `AgentConfig` array feeds `createPluginInterface`. Returns `undefined` for disabled agents or unmet model requirements.

src/agents/sisyphus-junior/AGENTS.md

@@ -0,0 +1,50 @@
+---
+name: sisyphus-junior-agent
+description: Developer reference for the Sisyphus-Junior category-spawned executor agent -- model variants and discipline.
+---
+
+# src/agents/sisyphus-junior/ -- Category-Spawned Executor
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+10 files. Sisyphus-Junior is a focused task executor spawned by `delegate-task` when category routing requires it. Runs in subagent mode with its own fallback chain. Does not delegate further; executes directly.
+
+## FILES
+
+| File | Purpose |
+|------|---------|
+| `agent.ts` | `createSisyphusJuniorAgentWithOverrides()` factory, model-variant routing, `SISYPHUS_JUNIOR_DEFAULTS` |
+| `index.ts` | Barrel exports |
+| `default.ts` | Base/Claude prompt: todo discipline, verification, termination rules |
+| `gemini.ts` | Gemini-optimized prompt variant |
+| `gpt.ts` | Base GPT prompt variant |
+| `gpt-5-3-codex.ts` | GPT-5.3 Codex prompt variant |
+| `gpt-5-4.ts` | GPT-5.4-native prompt variant |
+| `gpt-5-5.ts` | GPT-5.5-native prompt variant |
+| `kimi-k2-6.ts` | Kimi K2.6 prompt variant |
+| `index.test.ts` | Unit tests |
+
+## VARIANT SELECTION
+
+Parent `agent.ts` selects prompt variant by model name:
+- Contains "kimi-k2" -> `kimi-k2-6.ts`
+- Contains "gpt-5.5" -> `gpt-5-5.ts`
+- Contains "gpt-5.4" -> `gpt-5-4.ts`
+- Contains "gpt-5.3-codex" -> `gpt-5-3-codex.ts`
+- Contains "gpt" -> `gpt.ts`
+- Contains "gemini" -> `gemini.ts`
+- Default -> `default.ts` (Claude, GLM, etc.)
+
+## KEY BEHAVIORS
+
+- Mode: `subagent` (uses own fallback chain, ignores UI selection)
+- Default model: `claude-sonnet-4-6`
+- Default temperature: `0.1` (`SISYPHUS_JUNIOR_DEFAULTS`)
+- Fallback chain: kimi-k2.6 -> gpt-5.5 medium -> minimax-m2.7 -> big-pickle
+- Blocked tools: `task` (all models); `apply_patch` also blocked for GPT models
+- `call_omo_agent` explicitly allowed so subagents can spawn explore/librarian
+- Max tokens: 64000
+- Thinking enabled for non-GPT/non-GLM models (budgetTokens: 32000)
+- Reasoning effort "medium" for GPT models

src/features/builtin-commands/AGENTS.md

@@ -0,0 +1,43 @@
+# src/features/builtin-commands/ -- Built-in Slash Commands
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+Registry of built-in commands shipped inside the plugin. Each command is a template literal with title, description, and instructions. Registered via `createBuiltinCommandDefinitions()` factory in `commands.ts`. Loaded by `claude-code-command-loader`.
+
+## FILE CATALOG
+
+| File | Purpose |
+|------|---------|
+| `commands.ts` | `createBuiltinCommandDefinitions()` factory + `loadBuiltinCommands()` filter |
+| `index.ts` | Barrel exports |
+| `types.ts` | `BuiltinCommandName` union type + `BuiltinCommandConfig` |
+| `templates/` | One `.ts` file per command |
+
+## TEMPLATES
+
+| Command | Source File | Notes |
+|---------|-------------|-------|
+| `init-deep` | `templates/init-deep.ts` | Hierarchical AGENTS.md generator |
+| `ralph-loop` | `templates/ralph-loop.ts` | Self-referential dev loop |
+| `ulw-loop` | `templates/ralph-loop.ts` | Ultrawork loop variant |
+| `cancel-ralph` | `templates/ralph-loop.ts` | Loop cancellation |
+| `refactor` | `templates/refactor.ts` | LSP + AST-grep refactoring |
+| `start-work` | `templates/start-work.ts` | Prometheus plan executor |
+| `stop-continuation` | `templates/stop-continuation.ts` | Kill all continuations |
+| `handoff` | `templates/handoff.ts` | Session context summary |
+| `remove-ai-slops` | `templates/remove-ai-slops.ts` | AI code smell cleanup |
+| `hyperplan` | `templates/hyperplan.ts` | Adversarial team-mode planning |
+
+## STRUCTURE
+
+Each template exports a string constant containing the command's system prompt. `commands.ts` wraps it in `<command-instruction>` XML and injects `$ARGUMENTS`, `$SESSION_ID`, and `$TIMESTAMP` where needed. Some commands append a team-mode addendum when `teamModeEnabled` is true.
+
+## LOADING
+
+Phase 6 of config loading (`command-config-handler.ts`) merges built-ins with user-installed commands from `.opencode/commands/` and Claude Code plugins. `disabled_commands` in config filters out specific built-ins by name. The `autoSlashCommand` hook in `src/hooks/` executes these on user input.
+
+## TESTS
+
+Co-located `.test.ts` files in `templates/` cover `ralph-loop` and `stop-continuation` logic.

src/features/claude-code-agent-loader/AGENTS.md

@@ -0,0 +1,46 @@
+# src/features/claude-code-agent-loader/ -- Claude Code Agent Compatibility Layer
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+Sibling to `claude-code-mcp-loader`. Loads Claude Code agent definitions from `.opencode/agents/`, `~/.claude/agents/`, and inline `opencode.json` config, then translates them to OpenCode `AgentConfig`. 12 files.
+
+## LOAD PIPELINE
+
+```
+loadUserAgents() / loadProjectAgents() / loadOpencodeGlobalAgents() / loadOpencodeProjectAgents()
+  -> loader.ts: discover .md files in agents/ directories
+  -> agent-definitions-loader.ts: parse YAML frontmatter + body, load from explicit paths
+  -> json-agent-loader.ts: parse .json / .jsonc agent definitions
+  -> opencode-config-agents-reader.ts: read inline agents from opencode.json
+  -> claude-model-mapper.ts: translate "sonnet" / "opus" / "haiku" -> OpenCode provider/model IDs
+  -> return Record<string, ClaudeCodeAgentConfig>
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Barrel: all exports |
+| `loader.ts` | `loadUserAgents()`, `loadProjectAgents()`, `loadOpencode*Agents()` main entry |
+| `agent-definitions-loader.ts` | `parseMarkdownAgentFile()`, `loadAgentDefinitions()` |
+| `json-agent-loader.ts` | `parseJsonAgentFile()` -- JSON/JSONC agent definitions |
+| `claude-model-mapper.ts` | Claude aliases -> OpenCode `providerID/modelID` |
+| `opencode-config-agents-reader.ts` | Reads inline `agents` and `agent_definitions` from `opencode.json` |
+| `types.ts` | `ClaudeCodeAgentConfig`, `AgentScope`, `LoadedAgent` |
+
+## INTEGRATION
+
+Phase 3 of config loading (`src/plugin-handlers/agent-config-handler.ts`) calls this loader to populate the agent registry before the plugin interface is built.
+
+## COMPANION LOADERS
+
+- **`claude-code-plugin-loader`**: full plugins with commands, skills, hooks, MCPs
+- **`claude-code-mcp-loader`**: Tier 2 MCPs from `.mcp.json`
+
+## RELATED
+
+- Phase 3 integration: `src/plugin-handlers/agent-config-handler.ts`
+- Plugin loader: `src/features/claude-code-plugin-loader/`
+- MCP loader: `src/features/claude-code-mcp-loader/`

src/hooks/auto-update-checker/AGENTS.md

@@ -0,0 +1,51 @@
+# src/hooks/auto-update-checker/ -- npm Update Detection
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+27 files. Session Tier hook on `session.created`. Checks the npm registry for newer plugin versions, compares against the installed version, and surfaces update availability via startup toasts. Caches results to avoid repeated registry fetches. Throttled per channel (`latest`, `next`, `beta`). Skips CLI run mode and subagent sessions.
+
+## FILE CATALOG
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Barrel exports: hook factory, checker, cache invalidation, channel helpers |
+| `hook.ts` | `createAutoUpdateCheckerHook()` -- event handler, orchestrates startup toasts and background check |
+| `checker.ts` | Barrel for `checker/` subdir -- version resolution, local dev detection, package entry finding |
+| `cache.ts` | `invalidatePackage()` -- removes package from bun.lock, node_modules, and specifier cache |
+| `version-channel.ts` | `extractChannel()` -- resolves dist-tags and prerelease versions to npm channels |
+| `types.ts` | `UpdateCheckResult`, `AutoUpdateCheckerOptions`, `NpmDistTags` |
+| `constants.ts` | Registry URL, timeouts, cache paths, accepted package names |
+
+## SUBDIRECTORIES
+
+- `checker/` -- 11 files. Core version checking logic: `check-for-update.ts`, `latest-version.ts`, `local-dev-version.ts`, `plugin-entry.ts`, `cached-version.ts`, `pinned-version-updater.ts`, `sync-package-json.ts`, plus helpers.
+- `hook/` -- 9 files. Startup UX: `background-update-check.ts`, `deferred-startup-check.ts`, `startup-toasts.ts`, `update-toasts.ts`, `spinner-toast.ts`, `config-errors-toast.ts`, `connected-providers-status.ts`, `model-capabilities-status.ts`, `model-cache-warning.ts`.
+
+## CACHE
+
+File-based deduplication via `VERSION_FILE` in the OpenCode cache directory (`getOpenCodeCacheDir()`). Prevents excessive npm registry calls. `invalidatePackage()` forces a fresh check by purging the package from Bun's lockfile, node_modules, and specifier cache.
+
+## VERSION CHANNELS
+
+`extractChannel()` maps:
+- Dist-tags (`next`, `beta`) → channel name directly
+- Prerelease versions (`1.0.0-beta.1`) → channel from prerelease prefix (`alpha`, `beta`, `rc`, `canary`, `next`)
+- Stable versions → `latest`
+
+## INTEGRATION
+
+Registered in `create-session-hooks.ts` as `autoUpdateChecker`. Part of the Session Tier hook composition.
+
+## RELATED
+
+Three `zauc-mocks-*` directories in `src/hooks/` exist specifically to test this hook with mocked dependencies:
+- `zauc-mocks-cache/` -- tests cache invalidation paths
+- `zauc-mocks-hook/` -- tests hook orchestration with mocked submodules
+- `zauc-mocks-bg/` -- tests background check scheduling
+
+## CROSS-REFERENCES
+
+- Parent: [`src/hooks/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/hooks/AGENTS.md) -- Session Tier hook list
+- [`src/cli/AGENTS.md`](file:///Users/yeongyu/local-workspaces/omo/src/cli/AGENTS.md) -- CLI uses the same npm dist-tag helpers

src/hooks/compaction-context-injector/AGENTS.md

@@ -0,0 +1,45 @@
+# src/hooks/compaction-context-injector/ -- Post-Compaction Context Recovery
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+Continuation Tier hook. Fires on `session.compacted` to re-inject critical context lost during context-window compaction. Prevents the agent from losing its bearings after OpenCode trims session history.
+
+## TIER + EVENT
+
+- **Tier:** Continuation
+- **Event:** `session.compacted` (primary), `session.idle`, `session.deleted`, `message.updated`, `message.part.delta`, `message.part.updated`
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `hook.ts` | `createCompactionContextInjector()` -- composes capture, restore, inject, event |
+| `recovery.ts` | `createRecoveryLogic()` -- rebuilds agent/model/tools after compaction |
+| `tail-monitor.ts` | Tracks assistant output to detect no-text tails |
+| `session-prompt-config-resolver.ts` | Walks session messages to resolve current agent/model/tools |
+| `validated-model.ts` | `validateCheckpointModel()` -- model validation |
+| `session-id.ts` | `resolveSessionID()`, `isCompactionAgent()` |
+| `recovery-prompt-config.ts` | `createExpectedRecoveryPromptConfig()`, `isPromptConfigRecovered()` |
+| `constants.ts` | `RECOVERY_COOLDOWN_MS`, `NO_TEXT_TAIL_THRESHOLD`, `RECENT_COMPACTION_WINDOW_MS` |
+| `types.ts` | `CompactionContextInjector` interface |
+| `compaction-context-prompt.ts` | `COMPACTION_CONTEXT_PROMPT` -- 8-section summary template |
+| `index.ts` / `index.test.ts` | Barrel export + tests |
+| `recovery.test.ts` / `session-prompt-config-resolver.test.ts` | Unit tests |
+
+## HOW IT WORKS
+
+1. **Capture:** Before compaction, saves agent/model/tools checkpoint via `setCompactionAgentConfigCheckpoint()`
+2. **Inject:** Returns `COMPACTION_CONTEXT_PROMPT` with active delegated session history
+3. **Recover:** On `session.compacted`, dispatches internal prompt to restore checkpointed config
+4. **Tail monitor:** Detects consecutive assistant messages with no text output; triggers recovery if recent compaction
+
+## INTEGRATION
+
+Registered in `create-continuation-hooks.ts` as `compactionContextInjector`.
+
+## DISTINCTION
+
+- **`compactionTodoPreserver`:** Preserves todos only (sibling Continuation hook)
+- **`anthropicContextWindowLimitRecovery`:** Prevents the limit preemptively (Session Tier)

src/tools/ast-grep/AGENTS.md

@@ -0,0 +1,54 @@
+# src/tools/ast-grep/ -- AST-Aware Search and Rewrite
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+Two always-on tools: `ast_grep_search` (find AST patterns) and `ast_grep_replace` (rewrite AST patterns). 25 languages supported via `@ast-grep/napi` as primary backend with fallback to `sg` CLI.
+
+Pattern syntax uses AST meta-variables, not regex. `$VAR` matches one AST node. `$$$` matches zero or more nodes. `$$$VAR` captures a named list. Patterns must be complete, parseable source code.
+
+`ast_grep_replace` defaults to dry-run. Pass `dryRun=false` to apply changes.
+
+## FILE CATALOG
+
+| File | Role |
+|------|------|
+| `tools.ts` | `createAstGrepTools` factory -- returns Record with 2 tool entries |
+| `cli.ts` | `runSg` -- spawns sg process, handles two-pass rewrite |
+| `cli-binary-path-resolution.ts` | Async init wrapper with singleton promise dedup |
+| `sg-cli-path.ts` | Resolve sg via node_modules, platform subpackages, Homebrew, or cache |
+| `downloader.ts` | Auto-download from GitHub releases if missing |
+| `environment-check.ts` | Verify CLI + NAPI availability at startup |
+| `language-support.ts` | 25 CLI languages + 5 NAPI languages + extension map |
+| `pattern-hints.ts` | Detect regex misuse and language-specific mistakes |
+| `result-formatter.ts` | Format matches with file:line:column for LLM |
+| `sg-compact-json-output.ts` | Parse `sg --json=compact` into `SgResult` |
+| `tool-descriptions.ts` | Tool description constants |
+| `process-output-timeout.ts` | 300s timeout wrapper for spawn |
+| `types.ts` | `CliMatch`, `SgResult`, `AnalyzeResult`, etc. |
+| `constants.ts` | Re-exports from language-support, environment-check, sg-cli-path |
+| `index.ts` | Barrel |
+
+## KEY BEHAVIORS
+
+- Dual binary detection: NAPI primary, CLI fallback
+- Fallback chain: node_modules → platform subpackage → Homebrew → cached download
+- Dry-run protection: `ast_grep_replace` defaults to preview; pass `dryRun=false` to apply
+- Two-pass rewrite: when rewrite + apply both requested, cli.ts runs `--json=compact` first, then `--update-all`
+- Output limits: 1MB max output or 500 matches, whichever comes first
+- Timeout: 300s cap via `process-output-timeout.ts`; kills process and returns truncated result
+
+## LANGUAGES
+
+25 CLI languages: bash, c, cpp, csharp, css, elixir, go, haskell, html, java, javascript, json, kotlin, lua, nix, php, python, ruby, rust, scala, solidity, swift, typescript, tsx, yaml.
+
+5 NAPI languages (native bindings): html, javascript, tsx, css, typescript.
+
+## PATTERN HINTS
+
+When a search returns zero matches, `pattern-hints.ts` scans for regex-style misuse (`|`, `.*`, `\w`, `[a-z]`) and returns a corrective hint redirecting to ast-grep meta-variable syntax. Also catches language-specific mistakes like trailing colons in Python def/class patterns or incomplete function signatures in JS/Go/Rust.
+
+## RELATED
+
+Doctor check at `src/cli/doctor/checks/tools.ts` verifies both NAPI and CLI availability.

src/tools/look-at/AGENTS.md

@@ -0,0 +1,52 @@
+# src/tools/look-at/ -- Image and PDF Analysis Tool
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+14 files. The `look_at` tool delegates image, PDF, and diagram analysis to the `multimodal-looker` subagent. Conditional gate: tool is only registered when `multimodal-looker` is not in `disabled_agents`. Default subagent model: gpt-5.5 medium. This is a summary extractor, not a precise reader.
+
+## EXECUTION FLOW
+
+1. **Args** (`look-at-arguments.ts`) -- normalize `file_path`/`image_data` aliases, validate one-of requirement, reject remote URLs
+2. **Prep** (`look-at-input-preparer.ts`) -- resolve path, detect MIME from extension or Base64 header, convert unsupported images to JPEG
+3. **Spawn** (`look-at-session-runner.ts`) -- create child session with `multimodal-looker` agent, attach file as message part, disable `task`/`call_omo_agent`/`look_at` to prevent recursion
+4. **Poll** (`session-poller.ts`) -- wait until idle (1s interval, 120s timeout)
+5. **Extract** (`assistant-message-extractor.ts`) -- pull latest assistant text from session messages
+6. **Return** -- summary text back to caller
+
+## FILE CATALOG
+
+| File | Responsibility |
+|------|----------------|
+| `tools.ts` | `createLookAt()` factory -- tool schema + entry point |
+| `look-at-arguments.ts` | Zod arg schema, normalize aliases, validate inputs |
+| `look-at-input-preparer.ts` | Build `LookAtFilePart` from path or base64; trigger conversion if needed |
+| `look-at-prompt.ts` | System prompt for the multimodal session |
+| `look-at-session-runner.ts` | Orchestrate child session creation, prompt dispatch, message fetch |
+| `session-poller.ts` | Poll session status until idle |
+| `assistant-message-extractor.ts` | Extract latest assistant text from raw session messages |
+| `image-converter.ts` | Convert HEIC/WebP/RAW/PSD to JPEG via sips or ImageMagick |
+| `mime-type-inference.ts` | Detect MIME from file extension or Base64 header |
+| `missing-file-error.ts` | Clear `ENOENT` error message when file is missing |
+| `multimodal-agent-metadata.ts` | Resolve actual model for multimodal-looker from config or dynamic pipeline |
+| `multimodal-fallback-chain.ts` | Build vision-capable fallback chain: kimi-k2.6, glm-4.6v, gpt-5-nano |
+| `constants.ts` | `MULTIMODAL_LOOKER_AGENT`, `LOOK_AT_DESCRIPTION` |
+| `types.ts` | `LookAtArgs` interface |
+
+## GATE
+
+Conditional. Tool is registered only when `multimodal-looker` is absent from `disabled_agents`.
+
+## USE CASE
+
+PDFs, screenshots, diagrams -- quick summary extraction. NOT for visual precision, aesthetic evaluation, or exact accuracy. Use the Read tool for those cases instead.
+
+## DISTINCTION
+
+This is the TOOL that DELEGATES TO the `multimodal-looker` AGENT. The agent lives in `src/agents/builtin-agents/multimodal-looker.ts`; this tool is the invocation harness.
+
+## NOTES
+
+- Temporary converted images are cleaned up in `finally` blocks
+- The subagent has `read` tool disabled by default (`READ_ENABLED = false`); the file is passed as an attachment

src/tools/skill/AGENTS.md

@@ -0,0 +1,48 @@
+# src/tools/skill/ -- Skill and Command Loader Tool
+
+**Generated:** 2026-05-18
+
+## OVERVIEW
+
+The `skill` tool. Dual purpose: (1) load a skill by name to inject its SKILL.md content into context, (2) invoke a slash command by name (omit leading slash). Skills may spin up embedded MCP servers on demand. Commands route through the autoSlashCommand hook.
+
+## FILE CATALOG
+
+| File | Purpose |
+|------|---------|
+| `tools.ts` | `createSkillTool` factory -- resolves name, loads body, returns formatted output |
+| `skill-body.ts` | Extracts `<skill-instruction>` block or full SKILL.md template |
+| `skill-matcher.ts` | Exact match, short-name fallback, partial-match suggestions |
+| `scope-priority.ts` | 4-scope priority: project (4) > user (3) > opencode (2) > builtin/plugin (1) |
+| `native-skills.ts` | Merges `PluginInput.skills` entries into discovered skill list |
+| `description-formatter.ts` | Builds LLM-visible `<available_items>` listing with scope tags |
+| `mcp-capability-formatter.ts` | Lists skill-embedded MCP tools/resources/prompts for `skill_mcp` calls |
+| `session-skill-cache.ts` | Dedupes repeated skill loads per session via `seenSessionIDs` |
+| `types.ts` | `SkillArgs`, `SkillInfo`, `SkillLoadOptions` |
+| `constants.ts` | Tool name and description prefix |
+| `index.ts` | Barrel exports |
+
+## EXECUTION FLOW
+
+```
+skill(name="git-master")
+  -> matchSkillByName()    # exact, then short-name
+  -> ask(permission)       # host skill permission gate
+  -> extractSkillBody()    # load SKILL.md content
+  -> formatMcpCapabilities()  # if skill has mcpConfig
+  -> return "## Skill: ..." + body + MCP info
+```
+
+## SCOPE PRIORITY
+
+Project configs override user configs, which override opencode builtins. `sortByScopePriority` applies to both skills and slash commands in the `<available_items>` listing.
+
+## TEST MOCKS
+
+`zauc-mocks-skill-tools/` -- `mock.module()` setup for skill tool tests. Loads alphabetically before consuming tests via the `zauc-` prefix sort-order hack.
+
+## INTEGRATION
+
+- Discovery: `opencode-skill-loader` feature module scans `.opencode/skills/`, `~/.config/opencode/skills/`, and built-in paths
+- MCP spawn: `skill-mcp-manager` feature module starts embedded MCP servers per session on demand
+- Commands: `slashcommand/` module feeds discovered commands into the tool description