fix: export fallback availability from traced module

Remove applyLayout(select-layout main-vertical) call after spawn which
was destroying grid arrangements by forcing vertical stacking. Now only
enforceMainPaneWidth is called, preserving the grid created by manual
split directions. Also fix enforceMainPaneWidth to use config's
main_pane_size percentage instead of hardcoded 50%.

.github/workflows/ci.yml

@@ -52,12 +52,32 @@ jobs:
           bun test src/hooks/atlas
           bun test src/hooks/compaction-context-injector
           bun test src/features/tmux-subagent
+          bun test src/cli/doctor/formatter.test.ts
+          bun test src/cli/doctor/format-default.test.ts
+          bun test src/tools/call-omo-agent/sync-executor.test.ts
+          bun test src/tools/call-omo-agent/session-creator.test.ts
+          bun test src/tools/session-manager
+          bun test src/features/opencode-skill-loader/loader.test.ts
 
       - name: Run remaining tests
         run: |
-          # Run all other tests (mock-heavy ones are re-run but that's acceptable)
-          bun test bin script src/cli src/config src/mcp src/index.test.ts \
-            src/agents src/tools src/shared \
+          # Enumerate subdirectories/files explicitly to EXCLUDE mock-heavy files
+          # that were already run in isolation above.
+          # Excluded from src/cli: doctor/formatter.test.ts, doctor/format-default.test.ts
+          # Excluded from src/tools: call-omo-agent/sync-executor.test.ts, call-omo-agent/session-creator.test.ts, session-manager (all)
+          bun test bin script src/config src/mcp src/index.test.ts \
+            src/agents src/shared \
+            src/cli/run src/cli/config-manager src/cli/mcp-oauth \
+            src/cli/index.test.ts src/cli/install.test.ts src/cli/model-fallback.test.ts \
+            src/cli/config-manager.test.ts \
+            src/cli/doctor/runner.test.ts src/cli/doctor/checks \
+            src/tools/ast-grep src/tools/background-task src/tools/delegate-task \
+            src/tools/glob src/tools/grep src/tools/interactive-bash \
+            src/tools/look-at src/tools/lsp \
+            src/tools/skill src/tools/skill-mcp src/tools/slashcommand src/tools/task \
+            src/tools/call-omo-agent/background-agent-executor.test.ts \
+            src/tools/call-omo-agent/background-executor.test.ts \
+            src/tools/call-omo-agent/subagent-session-creator.test.ts \
             src/hooks/anthropic-context-window-limit-recovery \
             src/hooks/claude-code-compatibility \
             src/hooks/context-injection \
@@ -70,7 +90,11 @@ jobs:
             src/features/builtin-skills \
             src/features/claude-code-session-state \
             src/features/hook-message-injector \
-            src/features/opencode-skill-loader \
+            src/features/opencode-skill-loader/config-source-discovery.test.ts \
+            src/features/opencode-skill-loader/merger.test.ts \
+            src/features/opencode-skill-loader/skill-content.test.ts \
+            src/features/opencode-skill-loader/blocking.test.ts \
+            src/features/opencode-skill-loader/async-loader.test.ts \
             src/features/skill-mcp-manager
 
   typecheck:

.github/workflows/publish.yml

@@ -51,13 +51,33 @@ jobs:
           # Run them in separate processes to prevent cross-file contamination
           bun test src/plugin-handlers
           bun test src/hooks/atlas
+          bun test src/hooks/compaction-context-injector
           bun test src/features/tmux-subagent
+          bun test src/cli/doctor/formatter.test.ts
+          bun test src/cli/doctor/format-default.test.ts
+          bun test src/tools/call-omo-agent/sync-executor.test.ts
+          bun test src/tools/call-omo-agent/session-creator.test.ts
+          bun test src/features/opencode-skill-loader/loader.test.ts
 
       - name: Run remaining tests
         run: |
-          # Run all other tests (mock-heavy ones are re-run but that's acceptable)
-          bun test bin script src/cli src/config src/mcp src/index.test.ts \
-            src/agents src/tools src/shared \
+          # Enumerate subdirectories/files explicitly to EXCLUDE mock-heavy files
+          # that were already run in isolation above.
+          # Excluded from src/cli: doctor/formatter.test.ts, doctor/format-default.test.ts
+          # Excluded from src/tools: call-omo-agent/sync-executor.test.ts, call-omo-agent/session-creator.test.ts
+          bun test bin script src/config src/mcp src/index.test.ts \
+            src/agents src/shared \
+            src/cli/run src/cli/config-manager src/cli/mcp-oauth \
+            src/cli/index.test.ts src/cli/install.test.ts src/cli/model-fallback.test.ts \
+            src/cli/config-manager.test.ts \
+            src/cli/doctor/runner.test.ts src/cli/doctor/checks \
+            src/tools/ast-grep src/tools/background-task src/tools/delegate-task \
+            src/tools/glob src/tools/grep src/tools/interactive-bash \
+            src/tools/look-at src/tools/lsp src/tools/session-manager \
+            src/tools/skill src/tools/skill-mcp src/tools/slashcommand src/tools/task \
+            src/tools/call-omo-agent/background-agent-executor.test.ts \
+            src/tools/call-omo-agent/background-executor.test.ts \
+            src/tools/call-omo-agent/subagent-session-creator.test.ts \
             src/hooks/anthropic-context-window-limit-recovery \
             src/hooks/claude-code-compatibility \
             src/hooks/context-injection \
@@ -70,7 +90,11 @@ jobs:
             src/features/builtin-skills \
             src/features/claude-code-session-state \
             src/features/hook-message-injector \
-            src/features/opencode-skill-loader \
+            src/features/opencode-skill-loader/config-source-discovery.test.ts \
+            src/features/opencode-skill-loader/merger.test.ts \
+            src/features/opencode-skill-loader/skill-content.test.ts \
+            src/features/opencode-skill-loader/blocking.test.ts \
+            src/features/opencode-skill-loader/async-loader.test.ts \
             src/features/skill-mcp-manager
 
   typecheck:
@@ -223,118 +247,23 @@ jobs:
         with:
           fetch-depth: 0
 
+      - run: git fetch --force --tags
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+        env:
+          BUN_INSTALL_ALLOW_SCRIPTS: "@ast-grep/napi"
+
       - name: Generate changelog
-        id: changelog
         run: |
-          VERSION="${{ needs.publish-main.outputs.version }}"
-          
-          PREV_TAG=""
-          if [[ "$VERSION" == *"-beta."* ]]; then
-            BASE="${VERSION%-beta.*}"
-            NUM="${VERSION##*-beta.}"
-            PREV_NUM=$((NUM - 1))
-            if [ $PREV_NUM -ge 1 ]; then
-              PREV_TAG="${BASE}-beta.${PREV_NUM}"
-              git rev-parse "v${PREV_TAG}" >/dev/null 2>&1 || PREV_TAG=""
-            fi
-          fi
-          
-          if [ -z "$PREV_TAG" ]; then
-            PREV_TAG=$(curl -s https://registry.npmjs.org/oh-my-opencode/latest | jq -r '.version // "0.0.0"')
-          fi
-          
-          echo "Comparing v${PREV_TAG}..v${VERSION}"
-          
-          # Get all commits between tags
-          COMMITS=$(git log "v${PREV_TAG}..v${VERSION}" --format="%s" 2>/dev/null || echo "")
-          
-          # Initialize sections
-          FEATURES=""
-          FIXES=""
-          REFACTOR=""
-          DOCS=""
-          OTHER=""
-          
-          # Store regexes in variables for bash 5.2+ compatibility
-          # (bash 5.2 changed how parentheses are parsed inside [[ =~ ]])
-          re_skip='^(chore|ci|release|test|ignore)'
-          re_feat_scoped='^feat\(([^)]+)\): (.+)$'
-          re_fix_scoped='^fix\(([^)]+)\): (.+)$'
-          re_refactor_scoped='^refactor\(([^)]+)\): (.+)$'
-          re_docs_scoped='^docs\(([^)]+)\): (.+)$'
-          
-          while IFS= read -r commit; do
-            [ -z "$commit" ] && continue
-            # Skip chore, ci, release, test commits
-            [[ "$commit" =~ $re_skip ]] && continue
-            
-            if [[ "$commit" =~ ^feat ]]; then
-              # Extract scope and message: feat(scope): message -> **scope**: message
-              if [[ "$commit" =~ $re_feat_scoped ]]; then
-                FEATURES="${FEATURES}\n- **${BASH_REMATCH[1]}**: ${BASH_REMATCH[2]}"
-              else
-                MSG="${commit#feat: }"
-                FEATURES="${FEATURES}\n- ${MSG}"
-              fi
-            elif [[ "$commit" =~ ^fix ]]; then
-              if [[ "$commit" =~ $re_fix_scoped ]]; then
-                FIXES="${FIXES}\n- **${BASH_REMATCH[1]}**: ${BASH_REMATCH[2]}"
-              else
-                MSG="${commit#fix: }"
-                FIXES="${FIXES}\n- ${MSG}"
-              fi
-            elif [[ "$commit" =~ ^refactor ]]; then
-              if [[ "$commit" =~ $re_refactor_scoped ]]; then
-                REFACTOR="${REFACTOR}\n- **${BASH_REMATCH[1]}**: ${BASH_REMATCH[2]}"
-              else
-                MSG="${commit#refactor: }"
-                REFACTOR="${REFACTOR}\n- ${MSG}"
-              fi
-            elif [[ "$commit" =~ ^docs ]]; then
-              if [[ "$commit" =~ $re_docs_scoped ]]; then
-                DOCS="${DOCS}\n- **${BASH_REMATCH[1]}**: ${BASH_REMATCH[2]}"
-              else
-                MSG="${commit#docs: }"
-                DOCS="${DOCS}\n- ${MSG}"
-              fi
-            else
-              OTHER="${OTHER}\n- ${commit}"
-            fi
-          done <<< "$COMMITS"
-          
-          # Build release notes
-          {
-            echo "## What's Changed"
-            echo ""
-            if [ -n "$FEATURES" ]; then
-              echo "### Features"
-              echo -e "$FEATURES"
-              echo ""
-            fi
-            if [ -n "$FIXES" ]; then
-              echo "### Bug Fixes"
-              echo -e "$FIXES"
-              echo ""
-            fi
-            if [ -n "$REFACTOR" ]; then
-              echo "### Refactoring"
-              echo -e "$REFACTOR"
-              echo ""
-            fi
-            if [ -n "$DOCS" ]; then
-              echo "### Documentation"
-              echo -e "$DOCS"
-              echo ""
-            fi
-            if [ -n "$OTHER" ]; then
-              echo "### Other Changes"
-              echo -e "$OTHER"
-              echo ""
-            fi
-            echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/v${PREV_TAG}...v${VERSION}"
-          } > /tmp/changelog.md
-          
+          bun run script/generate-changelog.ts > /tmp/changelog.md
           cat /tmp/changelog.md
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Create GitHub release
         run: |

.opencode/command/publish.md

@@ -31,9 +31,9 @@ You are the release manager for oh-my-opencode. Execute the FULL publish workflo
   { "id": "sync-remote", "content": "Sync with remote (pull --rebase && push if unpushed commits)", "status": "pending", "priority": "high" },
   { "id": "run-workflow", "content": "Trigger GitHub Actions publish workflow", "status": "pending", "priority": "high" },
   { "id": "wait-workflow", "content": "Wait for workflow completion (poll every 30s)", "status": "pending", "priority": "high" },
-  { "id": "verify-release", "content": "Verify GitHub release was created", "status": "pending", "priority": "high" },
-  { "id": "draft-release-notes", "content": "Draft enhanced release notes content", "status": "pending", "priority": "high" },
-  { "id": "update-release-notes", "content": "Update GitHub release with enhanced notes", "status": "pending", "priority": "high" },
+  { "id": "verify-and-preview", "content": "Verify release created + preview auto-generated changelog & contributor thanks", "status": "pending", "priority": "high" },
+  { "id": "draft-summary", "content": "Draft enhanced release summary (mandatory for minor/major, optional for patch — ask user)", "status": "pending", "priority": "high" },
+  { "id": "apply-summary", "content": "Prepend enhanced summary to release (if user opted in)", "status": "pending", "priority": "high" },
   { "id": "verify-npm", "content": "Verify npm package published successfully", "status": "pending", "priority": "high" },
   { "id": "wait-platform-workflow", "content": "Wait for publish-platform workflow completion", "status": "pending", "priority": "high" },
   { "id": "verify-platform-binaries", "content": "Verify all 7 platform binary packages published", "status": "pending", "priority": "high" },
@@ -111,102 +111,165 @@ gh run view {run_id} --log-failed
 
 ---
 
-## STEP 5: VERIFY GITHUB RELEASE
+## STEP 5: VERIFY RELEASE & PREVIEW AUTO-GENERATED CONTENT
+
+Two goals: confirm the release exists, then show the user what the workflow already generated.
 
-Get the new version and verify release exists:
 ```bash
-# Get new version from package.json (workflow updates it)
+# Pull latest (workflow committed version bump)
 git pull --rebase
 NEW_VERSION=$(node -p "require('./package.json').version")
-gh release view "v${NEW_VERSION}"
+
+# Verify release exists on GitHub
+gh release view "v${NEW_VERSION}" --json tagName,url --jq '{tag: .tagName, url: .url}'
 ```
 
----
-
-## STEP 6: DRAFT ENHANCED RELEASE NOTES
-
-Analyze commits since the previous version and draft release notes following project conventions:
-
-### For PATCH releases:
-Keep simple format - just list commits:
-```markdown
-- {hash} {conventional commit message}
-- ...
-```
-
-### For MINOR releases:
-Use feature-focused format:
-```markdown
-## New Features
-
-### Feature Name
-- Description of what it does
-- Why it matters
-
-## Bug Fixes
-- fix(scope): description
-
-## Improvements
-- refactor(scope): description
-```
-
-### For MAJOR releases:
-Full changelog format:
-```markdown
-# v{version}
-
-Brief description of the release.
-
-## What's New Since v{previous}
-
-### Breaking Changes
-- Description of breaking change
-
-### Features
-- **Feature Name**: Description
-
-### Bug Fixes
-- Description
-
-### Documentation
-- Description
-
-## Migration Guide (if applicable)
-...
-```
-
-**CRITICAL: The enhanced notes must ADD to existing workflow-generated notes, not replace them.**
-
----
-
-## STEP 7: UPDATE GITHUB RELEASE
-
-**ZERO CONTENT LOSS POLICY:**
-- First, fetch the existing release body with `gh release view`
-- Your enhanced notes must be PREPENDED to the existing content
-- **NOT A SINGLE CHARACTER of existing content may be removed or modified**
-- The final release body = `{your_enhanced_notes}\n\n---\n\n{existing_body_exactly_as_is}`
+**After verifying, generate a local preview of the auto-generated content:**
 
 ```bash
-# Get existing body
-EXISTING_BODY=$(gh release view "v${NEW_VERSION}" --json body --jq '.body')
+bun run script/generate-changelog.ts
+```
 
-# Write enhanced notes to temp file (prepend to existing)
-cat > /tmp/release-notes-v${NEW_VERSION}.md << 'EOF'
-{your_enhanced_notes}
+<agent-instruction>
+After running the preview, present the output to the user and say:
+
+> **The following content is ALREADY included in the release automatically:**
+> - Commit changelog (grouped by feat/fix/refactor)
+> - Contributor thank-you messages (for non-team contributors)
+>
+> You do NOT need to write any of this. It's handled.
+>
+> **For a patch release**, this is usually sufficient on its own. However, if there are notable bug fixes or changes worth highlighting, an enhanced summary can be added.
+> **For a minor/major release**, an enhanced summary is **required** — I'll draft one in the next step.
+
+Wait for the user to acknowledge before proceeding.
+</agent-instruction>
 
 ---
 
-EOF
+## STEP 6: DRAFT ENHANCED RELEASE SUMMARY
 
-# Append existing body EXACTLY as-is (zero modifications)
-echo "$EXISTING_BODY" >> /tmp/release-notes-v${NEW_VERSION}.md
+<decision-gate>
 
-# Update release
-gh release edit "v${NEW_VERSION}" --notes-file /tmp/release-notes-v${NEW_VERSION}.md
+| Release Type | Action |
+|-------------|--------|
+| **patch** | ASK the user: "Would you like me to draft an enhanced summary highlighting the key bug fixes / changes? Or is the auto-generated changelog sufficient?" If user declines → skip to Step 8. If user accepts → draft a concise bug-fix / change summary below. |
+| **minor** | MANDATORY. Draft a concise feature summary. Do NOT proceed without one. |
+| **major** | MANDATORY. Draft a full release narrative with migration notes if applicable. Do NOT proceed without one. |
+
+</decision-gate>
+
+### What You're Writing (and What You're NOT)
+
+You are writing the **headline layer** — a product announcement that sits ABOVE the auto-generated commit log. Think "release blog post", not "git log".
+
+<rules>
+- NEVER duplicate commit messages. The auto-generated section already lists every commit.
+- NEVER write generic filler like "Various bug fixes and improvements" or "Several enhancements".
+- ALWAYS focus on USER IMPACT: what can users DO now that they couldn't before?
+- ALWAYS group by THEME or CAPABILITY, not by commit type (feat/fix/refactor).
+- ALWAYS use concrete language: "You can now do X" not "Added X feature".
+</rules>
+
+<examples>
+<bad title="Commit regurgitation — DO NOT do this">
+## What's New
+- feat(auth): add JWT refresh token rotation
+- fix(auth): handle expired token edge case
+- refactor(auth): extract middleware
+</bad>
+
+<good title="User-impact narrative — DO this">
+## 🔐 Smarter Authentication
+
+Token refresh is now automatic and seamless. Sessions no longer expire mid-task — the system silently rotates credentials in the background. If you've been frustrated by random logouts, this release fixes that.
+</good>
+
+<bad title="Vague filler — DO NOT do this">
+## Improvements
+- Various performance improvements
+- Bug fixes and stability enhancements
+</bad>
+
+<good title="Specific and measurable — DO this">
+## ⚡ 3x Faster Rule Parsing
+
+Rules are now cached by file modification time. If your project has 50+ rule files, you'll notice startup is noticeably faster — we measured a 3x improvement in our test suite.
+</good>
+</examples>
+
+### Drafting Process
+
+1. **Analyze** the commit list from Step 5's preview. Identify 2-5 themes that matter to users.
+2. **Write** the summary to `/tmp/release-summary-v${NEW_VERSION}.md`.
+3. **Present** the draft to the user for review and approval before applying.
+
+```bash
+# Write your draft here
+cat > /tmp/release-summary-v${NEW_VERSION}.md << 'SUMMARY_EOF'
+{your_enhanced_summary}
+SUMMARY_EOF
+
+cat /tmp/release-summary-v${NEW_VERSION}.md
 ```
 
-**CRITICAL: This is ADDITIVE ONLY. You are adding your notes on top. The existing content remains 100% intact.**
+<agent-instruction>
+After drafting, ask the user:
+> "Here's the release summary I drafted. This will appear AT THE TOP of the release notes, above the auto-generated commit changelog and contributor thanks. Want me to adjust anything before applying?"
+
+Do NOT proceed to Step 7 without user confirmation.
+</agent-instruction>
+
+---
+
+## STEP 7: APPLY ENHANCED SUMMARY TO RELEASE
+
+**Skip this step ONLY if the user opted out of the enhanced summary in Step 6** — proceed directly to Step 8.
+
+<architecture>
+The final release note structure:
+
+```
+┌─────────────────────────────────────┐
+│  Enhanced Summary (from Step 6)     │  ← You wrote this
+│  - Theme-based, user-impact focused │
+├─────────────────────────────────────┤
+│  ---  (separator)                   │
+├─────────────────────────────────────┤
+│  Auto-generated Commit Changelog    │  ← Workflow wrote this
+│  - feat/fix/refactor grouped        │
+│  - Contributor thank-you messages   │
+└─────────────────────────────────────┘
+```
+</architecture>
+
+<zero-content-loss-policy>
+- Fetch the existing release body FIRST
+- PREPEND your summary above it
+- The existing auto-generated content must remain 100% INTACT
+- NOT A SINGLE CHARACTER of existing content may be removed or modified
+</zero-content-loss-policy>
+
+```bash
+# 1. Fetch existing auto-generated body
+EXISTING_BODY=$(gh release view "v${NEW_VERSION}" --json body --jq '.body')
+
+# 2. Combine: enhanced summary on top, auto-generated below
+{
+  cat /tmp/release-summary-v${NEW_VERSION}.md
+  echo ""
+  echo "---"
+  echo ""
+  echo "$EXISTING_BODY"
+} > /tmp/final-release-v${NEW_VERSION}.md
+
+# 3. Update the release (additive only)
+gh release edit "v${NEW_VERSION}" --notes-file /tmp/final-release-v${NEW_VERSION}.md
+
+# 4. Confirm
+echo "✅ Release v${NEW_VERSION} updated with enhanced summary."
+gh release view "v${NEW_VERSION}" --json url --jq '.url'
+```
 
 ---
 

.opencode/command/remove-deadcode.md

@@ -3,337 +3,216 @@ description: Remove unused code from this project with ultrawork mode, LSP-verif
 ---
 
 <command-instruction>
-You are a dead code removal specialist. Execute the FULL dead code removal workflow using ultrawork mode.
 
-Your core weapon: **LSP FindReferences**. If a symbol has ZERO external references, it's dead. Remove it.
+Dead code removal via massively parallel deep agents. You are the ORCHESTRATOR — you scan, verify, batch, then delegate ALL removals to parallel agents.
 
-## CRITICAL RULES
+<rules>
+- **LSP is law.** Verify with `LspFindReferences(includeDeclaration=false)` before ANY removal decision.
+- **Never remove entry points.** `src/index.ts`, `src/cli/index.ts`, test files, config files, `packages/` — off-limits.
+- **You do NOT remove code yourself.** You scan, verify, batch, then fire deep agents. They do the work.
+</rules>
 
-1. **LSP is law.** Never guess. Always verify with `LspFindReferences` before removing ANYTHING.
-2. **One removal = one commit.** Every dead code removal gets its own atomic commit.
-3. **Test after every removal.** Run `bun test` after each. If it fails, REVERT and skip.
-4. **Leaf-first order.** Remove deepest unused symbols first, then work up the dependency chain. Removing a leaf may expose new dead code upstream.
-5. **Never remove entry points.** `src/index.ts`, `src/cli/index.ts`, test files, config files, and files in `packages/` are off-limits unless explicitly targeted.
+<false-positive-guards>
+NEVER mark as dead:
+- Symbols in `src/index.ts` or barrel `index.ts` re-exports
+- Symbols referenced in test files (tests are valid consumers)
+- Symbols with `@public` / `@api` JSDoc tags
+- Hook factories (`createXXXHook`), tool factories (`createXXXTool`), agent definitions in `agentSources`
+- Command templates, skill definitions, MCP configs
+- Symbols in `package.json` exports
+</false-positive-guards>
 
 ---
 
-## STEP 0: REGISTER TODO LIST (MANDATORY FIRST ACTION)
+## PHASE 1: SCAN — Find Dead Code Candidates
 
-```
-TodoWrite([
-  {"id": "scan", "content": "PHASE 1: Scan codebase for dead code candidates using LSP + explore agents", "status": "pending", "priority": "high"},
-  {"id": "verify", "content": "PHASE 2: Verify each candidate with LspFindReferences - zero false positives", "status": "pending", "priority": "high"},
-  {"id": "plan", "content": "PHASE 3: Plan removal order (leaf-first dependency order)", "status": "pending", "priority": "high"},
-  {"id": "remove", "content": "PHASE 4: Remove dead code one-by-one (remove -> test -> commit loop)", "status": "pending", "priority": "high"},
-  {"id": "final", "content": "PHASE 5: Final verification - full test suite + build + typecheck", "status": "pending", "priority": "high"}
-])
-```
+Run ALL of these in parallel:
 
----
+<parallel-scan>
 
-## PHASE 1: SCAN FOR DEAD CODE CANDIDATES
-
-**Mark scan as in_progress.**
-
-### 1.1: Launch Parallel Explore Agents (ALL BACKGROUND)
-
-Fire ALL simultaneously:
-
-```
-// Agent 1: Find all exported symbols
-task(subagent_type="explore", run_in_background=true,
-  prompt="Find ALL exported functions, classes, types, interfaces, and constants across src/.
-  List each with: file path, line number, symbol name, export type (named/default).
-  EXCLUDE: src/index.ts root exports, test files.
-  Return as structured list.")
-
-// Agent 2: Find potentially unused files
-task(subagent_type="explore", run_in_background=true,
-  prompt="Find files in src/ that are NOT imported by any other file.
-  Check import/require statements across the entire codebase.
-  EXCLUDE: index.ts files, test files, entry points, config files, .md files.
-  Return list of potentially orphaned files.")
-
-// Agent 3: Find unused imports within files
-task(subagent_type="explore", run_in_background=true,
-  prompt="Find unused imports across src/**/*.ts files.
-  Look for import statements where the imported symbol is never referenced in the file body.
-  Return: file path, line number, imported symbol name.")
-
-// Agent 4: Find functions/variables only used in their own declaration
-task(subagent_type="explore", run_in_background=true,
-  prompt="Find private/non-exported functions, variables, and types in src/**/*.ts that appear
-  to have zero usage beyond their declaration. Return: file path, line number, symbol name.")
-```
-
-### 1.2: Direct AST-Grep Scans (WHILE AGENTS RUN)
-
-```typescript
-// Find unused imports pattern
-ast_grep_search(pattern="import { $NAME } from '$PATH'", lang="typescript", paths=["src/"])
-
-// Find empty export objects
-ast_grep_search(pattern="export {}", lang="typescript", paths=["src/"])
-```
-
-### 1.3: Collect All Results
-
-Collect background agent results. Compile into a master candidate list:
-
-```
-## DEAD CODE CANDIDATES
-
-| # | File | Line | Symbol | Type | Confidence |
-|---|------|------|--------|------|------------|
-| 1 | src/foo.ts | 42 | unusedFunc | function | HIGH |
-| 2 | src/bar.ts | 10 | OldType | type | MEDIUM |
-```
-
-**Mark scan as completed.**
-
----
-
-## PHASE 2: VERIFY WITH LSP (ZERO FALSE POSITIVES)
-
-**Mark verify as in_progress.**
-
-For EVERY candidate from Phase 1, run this verification:
-
-### 2.1: The LSP Verification Protocol
-
-For each candidate symbol:
-
-```typescript
-// Step 1: Find the symbol's exact position
-LspDocumentSymbols(filePath)  // Get line/character of the symbol
-
-// Step 2: Find ALL references across the ENTIRE workspace
-LspFindReferences(filePath, line, character, includeDeclaration=false)
-// includeDeclaration=false → only counts USAGES, not the definition itself
-
-// Step 3: Evaluate
-// 0 references → CONFIRMED DEAD CODE
-// 1+ references → NOT dead, remove from candidate list
-```
-
-### 2.2: False Positive Guards
-
-**NEVER mark as dead code if:**
-- Symbol is in `src/index.ts` (package entry point)
-- Symbol is in any `index.ts` that re-exports (barrel file check: look if it's re-exported)
-- Symbol is referenced in test files (tests are valid consumers)
-- Symbol has `@public` or `@api` JSDoc tags
-- Symbol is in a file listed in `package.json` exports
-- Symbol is a hook factory (`createXXXHook`) registered in `src/index.ts`
-- Symbol is a tool factory (`createXXXTool`) registered in tool loading
-- Symbol is an agent definition registered in `agentSources`
-- File is a command template, skill definition, or MCP config
-
-### 2.3: Build Confirmed Dead Code List
-
-After verification, produce:
-
-```
-## CONFIRMED DEAD CODE (LSP-verified, 0 external references)
-
-| # | File | Line | Symbol | Type | Safe to Remove |
-|---|------|------|--------|------|----------------|
-| 1 | src/foo.ts | 42 | unusedFunc | function | YES |
-```
-
-**If ZERO confirmed dead code found: Report "No dead code found" and STOP.**
-
-**Mark verify as completed.**
-
----
-
-## PHASE 3: PLAN REMOVAL ORDER
-
-**Mark plan as in_progress.**
-
-### 3.1: Dependency Analysis
-
-For each confirmed dead symbol:
-1. Check if removing it would expose other dead code
-2. Check if other dead symbols depend on this one
-3. Build removal dependency graph
-
-### 3.2: Order by Leaf-First
-
-```
-Removal Order:
-1. [Leaf symbols - no other dead code depends on them]
-2. [Intermediate symbols - depended on only by already-removed dead code]
-3. [Dead files - entire files with no live exports]
-```
-
-### 3.3: Register Granular Todos
-
-Create one todo per removal:
-
-```
-TodoWrite([
-  {"id": "remove-1", "content": "Remove unusedFunc from src/foo.ts:42", "status": "pending", "priority": "high"},
-  {"id": "remove-2", "content": "Remove OldType from src/bar.ts:10", "status": "pending", "priority": "high"},
-  // ... one per confirmed dead symbol
-])
-```
-
-**Mark plan as completed.**
-
----
-
-## PHASE 4: ITERATIVE REMOVAL LOOP
-
-**Mark remove as in_progress.**
-
-For EACH dead code item, execute this exact loop:
-
-### 4.1: Pre-Removal Check
-
-```typescript
-// Re-verify it's still dead (previous removals may have changed things)
-LspFindReferences(filePath, line, character, includeDeclaration=false)
-// If references > 0 now → SKIP (previous removal exposed a new consumer)
-```
-
-### 4.2: Remove the Dead Code
-
-Use appropriate tool:
-
-**For unused imports:**
-```typescript
-Edit(filePath, oldString="import { deadSymbol } from '...';\n", newString="")
-// Or if it's one of many imports, remove just the symbol from the import list
-```
-
-**For unused functions/classes/types:**
-```typescript
-// Read the full symbol extent first
-Read(filePath, offset=startLine, limit=endLine-startLine+1)
-// Then remove it
-Edit(filePath, oldString="[full symbol text]", newString="")
-```
-
-**For dead files:**
+**TypeScript strict mode (your primary scanner — run this FIRST):**
 ```bash
-# Only after confirming ZERO imports point to this file
-rm "path/to/dead-file.ts"
+bunx tsc --noEmit --noUnusedLocals --noUnusedParameters 2>&1
+```
+This gives you the definitive list of unused locals, imports, parameters, and types with exact file:line locations.
+
+**Explore agents (fire ALL simultaneously as background):**
+
+```
+task(subagent_type="explore", run_in_background=true, load_skills=[],
+  description="Find orphaned files",
+  prompt="Find files in src/ NOT imported by any other file. Check all import statements. EXCLUDE: index.ts, *.test.ts, entry points, .md, packages/. Return: file paths.")
+
+task(subagent_type="explore", run_in_background=true, load_skills=[],
+  description="Find unused exported symbols",
+  prompt="Find exported functions/types/constants in src/ that are never imported by other files. Cross-reference: for each export, grep the symbol name across src/ — if it only appears in its own file, it's a candidate. EXCLUDE: src/index.ts exports, test files. Return: file path, line, symbol name, export type.")
 ```
 
-**After removal, also clean up:**
-- Remove any imports that were ONLY used by the removed code
-- Remove any now-empty import statements
-- Fix any trailing whitespace / double blank lines left behind
+</parallel-scan>
 
-### 4.3: Post-Removal Verification
+Collect all results into a master candidate list.
+
+---
+
+## PHASE 2: VERIFY — LSP Confirmation (Zero False Positives)
+
+For EACH candidate from Phase 1:
 
 ```typescript
-// 1. LSP diagnostics on changed file
-LspDiagnostics(filePath, severity="error")
-// Must be clean (or only pre-existing errors)
-
-// 2. Run tests
-bash("bun test")
-// Must pass
-
-// 3. Typecheck
-bash("bun run typecheck")
-// Must pass
+LspFindReferences(filePath, line, character, includeDeclaration=false)
+// 0 references → CONFIRMED dead
+// 1+ references → NOT dead, drop from list
 ```
 
-### 4.4: Handle Failures
+Also apply the false-positive-guards above. Produce a confirmed list:
 
-If ANY verification fails:
-1. **REVERT** the change immediately (`git checkout -- [file]`)
-2. Mark this removal todo as `cancelled` with note: "Removal caused [error]. Skipped."
-3. Proceed to next item
-
-### 4.5: Commit
-
-```bash
-git add [changed-files]
-git commit -m "refactor: remove unused [symbolType] [symbolName] from [filePath]"
+```
+| # | File | Symbol | Type | Action |
+|---|------|--------|------|--------|
+| 1 | src/foo.ts:42 | unusedFunc | function | REMOVE |
+| 2 | src/bar.ts:10 | OldType | type | REMOVE |
+| 3 | src/baz.ts:7 | ctx | parameter | PREFIX _ |
 ```
 
-Mark this removal todo as `completed`.
+**Action types:**
+- `REMOVE` — delete the symbol/import/file entirely
+- `PREFIX _` — unused function parameter required by signature → rename to `_paramName`
 
-### 4.6: Re-scan After Removal
+If ZERO confirmed: report "No dead code found" and STOP.
 
-After removing a symbol, check if its removal exposed NEW dead code:
-- Were there imports that only existed to serve the removed symbol?
-- Are there other symbols in the same file now unreferenced?
+---
 
-If new dead code is found, add it to the removal queue.
+## PHASE 3: BATCH — Group by File for Conflict-Free Parallelism
 
-**Repeat 4.1-4.6 for every item. Mark remove as completed when done.**
+<batching-rules>
+
+**Goal: maximize parallel agents with ZERO git conflicts.**
+
+1. Group confirmed dead code items by FILE PATH
+2. All items in the SAME file go to the SAME batch (prevents two agents editing the same file)
+3. If a dead FILE (entire file deletion) exists, it's its own batch
+4. Target 5-15 batches. If fewer than 5 items total, use 1 batch per item.
+
+**Example batching:**
+```
+Batch A: [src/hooks/foo/hook.ts — 3 unused imports]
+Batch B: [src/features/bar/manager.ts — 2 unused constants, 1 dead function]
+Batch C: [src/tools/baz/tool.ts — 1 unused param, src/tools/baz/types.ts — 1 unused type]
+Batch D: [src/dead-file.ts — entire file deletion]
+```
+
+Files in the same directory CAN be batched together (they won't conflict as long as no two agents edit the same file). Maximize batch count for parallelism.
+
+</batching-rules>
+
+---
+
+## PHASE 4: EXECUTE — Fire Parallel Deep Agents
+
+For EACH batch, fire a deep agent:
+
+```
+task(
+  category="deep",
+  load_skills=["typescript-programmer", "git-master"],
+  run_in_background=true,
+  description="Remove dead code batch N: [brief description]",
+  prompt="[see template below]"
+)
+```
+
+<agent-prompt-template>
+
+Every deep agent gets this prompt structure (fill in the specifics per batch):
+
+```
+## TASK: Remove dead code from [file list]
+
+## DEAD CODE TO REMOVE
+
+### [file path] line [N]
+- Symbol: `[name]` — [type: unused import / unused constant / unused function / unused parameter / dead file]
+- Action: [REMOVE entirely / REMOVE from import list / PREFIX with _]
+
+### [file path] line [N]
+- ...
+
+## PROTOCOL
+
+1. Read each file to understand exact syntax at the target lines
+2. For each symbol, run LspFindReferences to RE-VERIFY it's still dead (another agent may have changed things)
+3. Apply the change:
+   - Unused import (only symbol in line): remove entire import line
+   - Unused import (one of many): remove only that symbol from the import list
+   - Unused constant/function/type: remove the declaration. Clean up trailing blank lines.
+   - Unused parameter: prefix with `_` (do NOT remove — required by signature)
+   - Dead file: delete with `rm`
+4. After ALL edits in this batch, run: `bun run typecheck`
+5. If typecheck fails: `git checkout -- [files]` and report failure
+6. If typecheck passes: stage ONLY your files and commit:
+   `git add [your-specific-files] && git commit -m "refactor: remove dead code from [brief file list]"`
+7. Report what you removed and the commit hash
+
+## CRITICAL
+- Stage ONLY your batch's files (`git add [specific files]`). NEVER `git add -A` — other agents are working in parallel.
+- If typecheck fails after your edits, REVERT all changes and report. Do not attempt to fix.
+- Pre-existing test failures in other files are expected. Only typecheck matters for your batch.
+```
+
+</agent-prompt-template>
+
+Fire ALL batches simultaneously. Wait for all to complete.
 
 ---
 
 ## PHASE 5: FINAL VERIFICATION
 
-**Mark final as in_progress.**
+After ALL agents complete:
 
-### 5.1: Full Test Suite
 ```bash
-bun test
+bun run typecheck   # must pass
+bun test            # note any NEW failures vs pre-existing
+bun run build       # must pass
 ```
 
-### 5.2: Full Typecheck
-```bash
-bun run typecheck
-```
-
-### 5.3: Full Build
-```bash
-bun run build
-```
-
-### 5.4: Summary Report
+Produce summary:
 
 ```markdown
 ## Dead Code Removal Complete
 
 ### Removed
-| # | Symbol | File | Type | Commit |
-|---|--------|------|------|--------|
-| 1 | unusedFunc | src/foo.ts | function | abc1234 |
+| # | Symbol | File | Type | Commit | Agent |
+|---|--------|------|------|--------|-------|
+| 1 | unusedFunc | src/foo.ts | function | abc1234 | Batch A |
 
-### Skipped (caused failures)
+### Skipped (agent reported failure)
 | # | Symbol | File | Reason |
 |---|--------|------|--------|
-| 1 | riskyFunc | src/bar.ts | Test failure: [details] |
 
 ### Verification
-- Tests: PASSED (X/Y passing)
-- Typecheck: CLEAN
-- Build: SUCCESS
-- Total dead code removed: N symbols across M files
+- Typecheck: PASS/FAIL
+- Tests: X passing, Y failing (Z pre-existing)
+- Build: PASS/FAIL
+- Total removed: N symbols across M files
 - Total commits: K atomic commits
+- Parallel agents used: P
 ```
 
-**Mark final as completed.**
-
 ---
 
 ## SCOPE CONTROL
 
-**If $ARGUMENTS is provided**, narrow the scan to the specified scope:
-- File path: Only scan that file
-- Directory: Only scan that directory
-- Symbol name: Only check that specific symbol
-- "all" or empty: Full project scan (default)
+If `$ARGUMENTS` is provided, narrow the scan:
+- File path → only that file
+- Directory → only that directory
+- Symbol name → only that symbol
+- `all` or empty → full project scan (default)
 
 ## ABORT CONDITIONS
 
-**STOP and report to user if:**
-- 3 consecutive removals cause test failures
+STOP and report if:
+- More than 50 candidates found (ask user to narrow scope or confirm proceeding)
 - Build breaks and cannot be fixed by reverting
-- More than 50 candidates found (ask user to narrow scope)
-
-## LANGUAGE
-
-Use English for commit messages and technical output.
 
 </command-instruction>
 

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

README.md

@@ -280,10 +280,10 @@ To remove oh-my-opencode:
 
    ```bash
    # Remove user config
-   rm -f ~/.config/opencode/oh-my-opencode.json
+   rm -f ~/.config/opencode/oh-my-opencode.json ~/.config/opencode/oh-my-opencode.jsonc
 
    # Remove project config (if exists)
-   rm -f .opencode/oh-my-opencode.json
+   rm -f .opencode/oh-my-opencode.json .opencode/oh-my-opencode.jsonc
    ```
 
 3. **Verify removal**
@@ -314,7 +314,7 @@ Highly opinionated, but adjustable to taste.
 See the full [Configuration Documentation](docs/configurations.md) for detailed information.
 
 **Quick Overview:**
-- **Config Locations**: `.opencode/oh-my-opencode.json` (project) or `~/.config/opencode/oh-my-opencode.json` (user)
+- **Config Locations**: `.opencode/oh-my-opencode.jsonc` or `.opencode/oh-my-opencode.json` (project), `~/.config/opencode/oh-my-opencode.jsonc` or `~/.config/opencode/oh-my-opencode.json` (user)
 - **JSONC Support**: Comments and trailing commas supported
 - **Agents**: Override models, temperatures, prompts, and permissions for any agent
 - **Built-in Skills**: `playwright` (browser automation), `git-master` (atomic commits)

bun.lock

@@ -28,13 +28,13 @@
         "typescript": "^5.7.3",
       },
       "optionalDependencies": {
-        "oh-my-opencode-darwin-arm64": "3.5.2",
-        "oh-my-opencode-darwin-x64": "3.5.2",
-        "oh-my-opencode-linux-arm64": "3.5.2",
-        "oh-my-opencode-linux-arm64-musl": "3.5.2",
-        "oh-my-opencode-linux-x64": "3.5.2",
-        "oh-my-opencode-linux-x64-musl": "3.5.2",
-        "oh-my-opencode-windows-x64": "3.5.2",
+        "oh-my-opencode-darwin-arm64": "3.6.0",
+        "oh-my-opencode-darwin-x64": "3.6.0",
+        "oh-my-opencode-linux-arm64": "3.6.0",
+        "oh-my-opencode-linux-arm64-musl": "3.6.0",
+        "oh-my-opencode-linux-x64": "3.6.0",
+        "oh-my-opencode-linux-x64-musl": "3.6.0",
+        "oh-my-opencode-windows-x64": "3.6.0",
       },
     },
   },
@@ -226,19 +226,19 @@
 
     "object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
 
-    "oh-my-opencode-darwin-arm64": ["oh-my-opencode-darwin-arm64@3.5.2", "", { "os": "darwin", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-oIS3lB2F9/N+3mF5wCKk6/EPVSz516XWN+mNdquSSeddw+xqMxGdhKY6K/XeYbHJzeN2Z8IOikNEJ6psR2/a8g=="],
+    "oh-my-opencode-darwin-arm64": ["oh-my-opencode-darwin-arm64@3.6.0", "", { "os": "darwin", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-JkyJC3b9ueRgSyPJMjTKlBO99gIyTpI87lEV5Tk7CBv6TFbj2ZFxfaA8mEm138NbwmYa/Z4Rf7I5tZyp2as93A=="],
 
-    "oh-my-opencode-darwin-x64": ["oh-my-opencode-darwin-x64@3.5.2", "", { "os": "darwin", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-OAdXo4ZCCYO4kRWtnyz3tdmaGYPUB3WcXimXAxp+/sEZxAnh7n1RQkpLn6UxWX4AIAdRT9dfrOfRic6VoCYv2g=="],
+    "oh-my-opencode-darwin-x64": ["oh-my-opencode-darwin-x64@3.6.0", "", { "os": "darwin", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-5HsXz3F42T6CmPk6IW+pErJVSmPnqc3Gc1OntoKp/b4FwuWkFJh9kftDSH3cnKTX98H6XBqnwZoFKCNCiiVLEA=="],
 
-    "oh-my-opencode-linux-arm64": ["oh-my-opencode-linux-arm64@3.5.2", "", { "os": "linux", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-5XXNMFhp1VsyrGNRBoXcOyoaUeVkbrWkBRPDGZfpiq+kRXH3aaSWdR5G7Pl/TadOQv9Bl8/8YaxsuHRTFT1aXw=="],
+    "oh-my-opencode-linux-arm64": ["oh-my-opencode-linux-arm64@3.6.0", "", { "os": "linux", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-KjCSC2i9XdjzGsX6coP9xwj7naxTpdqnB53TiLbVH+KeF0X0dNsVV7PHbme3I1orjjzYoEbVYVC3ZNaleubzog=="],
 
-    "oh-my-opencode-linux-arm64-musl": ["oh-my-opencode-linux-arm64-musl@3.5.2", "", { "os": "linux", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-/woIpqvEI85MgJvEVnz4g5FBLeiQNK7srRsueIFPBmtTahh42HFleCDaIltOl/ndjsE5nCHacQVJHkC9W9/F3Q=="],
+    "oh-my-opencode-linux-arm64-musl": ["oh-my-opencode-linux-arm64-musl@3.6.0", "", { "os": "linux", "cpu": "arm64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-EARvFQXnkqSnwPpKtghmoV5e/JmweJXhjcOrRNvEwQ8HSb4FIhdRmJkTw4Z/EzyoIRTQcY019ALOiBbdIiOUEA=="],
 
-    "oh-my-opencode-linux-x64": ["oh-my-opencode-linux-x64@3.5.2", "", { "os": "linux", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-vTL2A+6zzGhi+m7sC8peLDq5OAp2dRR0UEb4RbZAOHtlEruF7qFEmcK3ccWxwc3+Z3G/ITfwn5VNa72ZS4pNTg=="],
+    "oh-my-opencode-linux-x64": ["oh-my-opencode-linux-x64@3.6.0", "", { "os": "linux", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-jYyew4NKAOM6NrMM0+LlRlz6s1EVMI9cQdK/o0t8uqFheZVeb7u4cBZwwfhJ79j7EWkSWGc0Jdj9G2dOukbDxg=="],
 
-    "oh-my-opencode-linux-x64-musl": ["oh-my-opencode-linux-x64-musl@3.5.2", "", { "os": "linux", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-bOAA55snLsK2QB00IkQy8le0Oqh/GJ7pxEHtm1oUezlQrW/nX5SS/hJ7dPHMmOd9FoiqnqyqWZxNkLmFoG463A=="],
+    "oh-my-opencode-linux-x64-musl": ["oh-my-opencode-linux-x64-musl@3.6.0", "", { "os": "linux", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode" } }, "sha512-BrR+JftCXP/il04q2uImWIueCiuTmXbivsXYkfFONdO1Rq9b4t0BVua9JIYk7l3OUfeRlrKlFNYNfpFhvVADOw=="],
 
-    "oh-my-opencode-windows-x64": ["oh-my-opencode-windows-x64@3.5.2", "", { "os": "win32", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode.exe" } }, "sha512-fnHiAPYglw3unPckmQBoCT6+VqjSWCE3S3J551mRo0ZFrxuEP2ZKyHZeFMMOtKwDepCvmKgd1W040+KmuVUXOA=="],
+    "oh-my-opencode-windows-x64": ["oh-my-opencode-windows-x64@3.6.0", "", { "os": "win32", "cpu": "x64", "bin": { "oh-my-opencode": "bin/oh-my-opencode.exe" } }, "sha512-cIYQYzcQGhGFE99ulHGXs8S1vDHjgCtT3ID2dDoOztnOQW0ZVa61oCHlkBtjdP/BEv2tH5AGvKrXAICXs19iFw=="],
 
     "on-finished": ["on-finished@2.4.1", "", { "dependencies": { "ee-first": "1.1.1" } }, "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg=="],
 

docs/configurations.md

@@ -38,13 +38,13 @@ It asks about your providers (Claude, OpenAI, Gemini, etc.) and generates optima
 ## Config File Locations
 
 Config file locations (priority order):
-1. `.opencode/oh-my-opencode.json` (project)
-2. User config (platform-specific):
+1. `.opencode/oh-my-opencode.jsonc` or `.opencode/oh-my-opencode.json` (project; prefers `.jsonc` when both exist)
+2. User config (platform-specific; prefers `.jsonc` when both exist):
 
-| Platform        | User Config Path                                                                                            |
-| --------------- | ----------------------------------------------------------------------------------------------------------- |
-| **Windows**     | `~/.config/opencode/oh-my-opencode.json` (preferred) or `%APPDATA%\opencode\oh-my-opencode.json` (fallback) |
-| **macOS/Linux** | `~/.config/opencode/oh-my-opencode.json`                                                                    |
+| Platform        | User Config Path                                                                                                            |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **Windows**     | `~/.config/opencode/oh-my-opencode.jsonc` (preferred) or `~/.config/opencode/oh-my-opencode.json` (fallback); `%APPDATA%\opencode\oh-my-opencode.jsonc` / `%APPDATA%\opencode\oh-my-opencode.json` (fallback) |
+| **macOS/Linux** | `~/.config/opencode/oh-my-opencode.jsonc` (preferred) or `~/.config/opencode/oh-my-opencode.json` (fallback)                |
 
 Schema autocomplete supported:
 
@@ -83,7 +83,7 @@ When both `oh-my-opencode.jsonc` and `oh-my-opencode.json` files exist, `.jsonc`
 
 ## Google Auth
 
-**Recommended**: For Google Gemini authentication, install the [`opencode-antigravity-auth`](https://github.com/NoeFabris/opencode-antigravity-auth) plugin (`@latest`). It provides multi-account load balancing, variant-based thinking levels, dual quota system (Antigravity + Gemini CLI), and active maintenance. See [Installation > Google Gemini](docs/guide/installation.md#google-gemini-antigravity-oauth).
+**Recommended**: For Google Gemini authentication, install the [`opencode-antigravity-auth`](https://github.com/NoeFabris/opencode-antigravity-auth) plugin (`@latest`). It provides multi-account load balancing, variant-based thinking levels, dual quota system (Antigravity + Gemini CLI), and active maintenance. See [Installation > Google Gemini](guide/installation.md#google-gemini-antigravity-oauth).
 
 ## Ollama Provider
 
@@ -1061,9 +1061,10 @@ Don't want them? Disable via `disabled_mcps` in `~/.config/opencode/oh-my-openco
 
 OpenCode provides LSP tools for analysis.
 Oh My OpenCode adds refactoring tools (rename, code actions).
-All OpenCode LSP configs and custom settings (from opencode.json) are supported, plus additional Oh My OpenCode-specific settings.
+All OpenCode LSP configs and custom settings (from `opencode.jsonc` / `opencode.json`) are supported, plus additional Oh My OpenCode-specific settings.
+For config discovery, `.jsonc` takes precedence over `.json` when both exist (applies to both `opencode.*` and `oh-my-opencode.*`).
 
-Add LSP servers via the `lsp` option in `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.json`:
+Add LSP servers via the `lsp` option in `~/.config/opencode/oh-my-opencode.jsonc` / `~/.config/opencode/oh-my-opencode.json` or `.opencode/oh-my-opencode.jsonc` / `.opencode/oh-my-opencode.json`:
 
 ```json
 {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -74,13 +74,13 @@
     "typescript": "^5.7.3"
   },
   "optionalDependencies": {
-    "oh-my-opencode-darwin-arm64": "3.5.3",
-    "oh-my-opencode-darwin-x64": "3.5.3",
-    "oh-my-opencode-linux-arm64": "3.5.3",
-    "oh-my-opencode-linux-arm64-musl": "3.5.3",
-    "oh-my-opencode-linux-x64": "3.5.3",
-    "oh-my-opencode-linux-x64-musl": "3.5.3",
-    "oh-my-opencode-windows-x64": "3.5.3"
+    "oh-my-opencode-darwin-arm64": "3.6.0",
+    "oh-my-opencode-darwin-x64": "3.6.0",
+    "oh-my-opencode-linux-arm64": "3.6.0",
+    "oh-my-opencode-linux-arm64-musl": "3.6.0",
+    "oh-my-opencode-linux-x64": "3.6.0",
+    "oh-my-opencode-linux-x64-musl": "3.6.0",
+    "oh-my-opencode-windows-x64": "3.6.0"
   },
   "trustedDependencies": [
     "@ast-grep/cli",

packages/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-darwin-arm64",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "Platform-specific binary for oh-my-opencode (darwin-arm64)",
   "license": "MIT",
   "repository": {

packages/darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-darwin-x64",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "Platform-specific binary for oh-my-opencode (darwin-x64)",
   "license": "MIT",
   "repository": {

packages/linux-arm64-musl/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-linux-arm64-musl",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "Platform-specific binary for oh-my-opencode (linux-arm64-musl)",
   "license": "MIT",
   "repository": {

packages/linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-linux-arm64",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "Platform-specific binary for oh-my-opencode (linux-arm64)",
   "license": "MIT",
   "repository": {

packages/linux-x64-musl/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-linux-x64-musl",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "Platform-specific binary for oh-my-opencode (linux-x64-musl)",
   "license": "MIT",
   "repository": {

packages/linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-linux-x64",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "Platform-specific binary for oh-my-opencode (linux-x64)",
   "license": "MIT",
   "repository": {

packages/windows-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-windows-x64",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "Platform-specific binary for oh-my-opencode (windows-x64)",
   "license": "MIT",
   "repository": {

script/build-schema-document.ts

@@ -0,0 +1,17 @@
+import * as z from "zod"
+import { OhMyOpenCodeConfigSchema } from "../src/config/schema"
+
+export function createOhMyOpenCodeJsonSchema(): Record<string, unknown> {
+  const jsonSchema = z.toJSONSchema(OhMyOpenCodeConfigSchema, {
+    target: "draft-07",
+    unrepresentable: "any",
+  })
+
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    $id: "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
+    title: "Oh My OpenCode Configuration",
+    description: "Configuration schema for oh-my-opencode plugin",
+    ...jsonSchema,
+  }
+}

script/build-schema.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test"
+import { createOhMyOpenCodeJsonSchema } from "./build-schema-document"
+
+describe("build-schema-document", () => {
+  test("generates schema with skills property", () => {
+    // given
+    const expectedDraft = "http://json-schema.org/draft-07/schema#"
+
+    // when
+    const schema = createOhMyOpenCodeJsonSchema()
+
+    // then
+    expect(schema.$schema).toBe(expectedDraft)
+    expect(schema.title).toBe("Oh My OpenCode Configuration")
+    expect(schema.properties).toBeDefined()
+    expect(schema.properties.skills).toBeDefined()
+  })
+})

script/build-schema.ts

@@ -1,24 +1,12 @@
 #!/usr/bin/env bun
-import * as z from "zod"
-import { zodToJsonSchema } from "zod-to-json-schema"
-import { OhMyOpenCodeConfigSchema } from "../src/config/schema"
+import { createOhMyOpenCodeJsonSchema } from "./build-schema-document"
 
 const SCHEMA_OUTPUT_PATH = "assets/oh-my-opencode.schema.json"
 
 async function main() {
   console.log("Generating JSON Schema...")
 
-  const jsonSchema = zodToJsonSchema(OhMyOpenCodeConfigSchema, {
-    target: "draft7",
-  })
-
-  const finalSchema = {
-    $schema: "http://json-schema.org/draft-07/schema#",
-    $id: "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
-    title: "Oh My OpenCode Configuration",
-    description: "Configuration schema for oh-my-opencode plugin",
-    ...jsonSchema,
-  }
+  const finalSchema = createOhMyOpenCodeJsonSchema()
 
   await Bun.write(SCHEMA_OUTPUT_PATH, JSON.stringify(finalSchema, null, 2))
 

signatures/cla.json

@@ -1439,6 +1439,94 @@
       "created_at": "2026-02-12T12:57:06Z",
       "repoId": 1108837393,
       "pullRequestNo": 1802
+    },
+    {
+      "name": "willy-scr",
+      "id": 187001140,
+      "comment_id": 3894534811,
+      "created_at": "2026-02-13T02:56:20Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1809
+    },
+    {
+      "name": "professional-ALFIE",
+      "id": 219141081,
+      "comment_id": 3897671676,
+      "created_at": "2026-02-13T15:00:01Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1820
+    },
+    {
+      "name": "Strocs",
+      "id": 71996940,
+      "comment_id": 3898248552,
+      "created_at": "2026-02-13T16:56:54Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1822
+    },
+    {
+      "name": "cloudwaddie-agent",
+      "id": 261346076,
+      "comment_id": 3900805128,
+      "created_at": "2026-02-14T04:15:19Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1827
+    },
+    {
+      "name": "morphaxl",
+      "id": 57144942,
+      "comment_id": 3872741516,
+      "created_at": "2026-02-09T16:21:56Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1699
+    },
+    {
+      "name": "morphaxl",
+      "id": 57144942,
+      "comment_id": 3872742242,
+      "created_at": "2026-02-09T16:22:04Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1699
+    },
+    {
+      "name": "liu-qingyuan",
+      "id": 57737268,
+      "comment_id": 3902402078,
+      "created_at": "2026-02-14T19:39:58Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1844
+    },
+    {
+      "name": "iyoda",
+      "id": 31020,
+      "comment_id": 3902426789,
+      "created_at": "2026-02-14T19:58:19Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1845
+    },
+    {
+      "name": "Decrabbityyy",
+      "id": 99632363,
+      "comment_id": 3904649522,
+      "created_at": "2026-02-15T15:07:11Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1864
+    },
+    {
+      "name": "dankochetov",
+      "id": 33990502,
+      "comment_id": 3905398332,
+      "created_at": "2026-02-15T23:17:05Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1870
+    },
+    {
+      "name": "xinpengdr",
+      "id": 1885607,
+      "comment_id": 3910093356,
+      "created_at": "2026-02-16T19:01:33Z",
+      "repoId": 1108837393,
+      "pullRequestNo": 1906
     }
   ]
 }

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)

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

src/agents/builtin-agents.ts

@@ -13,7 +13,11 @@ import { createAtlasAgent, atlasPromptMetadata } from "./atlas"
 import { createMomusAgent, momusPromptMetadata } from "./momus"
 import { createHephaestusAgent } from "./hephaestus"
 import type { AvailableCategory } from "./dynamic-agent-prompt-builder"
-import { fetchAvailableModels, readConnectedProvidersCache } from "../shared"
+import {
+  fetchAvailableModels,
+  readConnectedProvidersCache,
+  readProviderModelsCache,
+} from "../shared"
 import { CATEGORY_DESCRIPTIONS } from "../tools/delegate-task/constants"
 import { mergeCategories } from "../shared/merge-categories"
 import { buildAvailableSkills } from "./builtin-agents/available-skills"
@@ -68,14 +72,20 @@ export async function createBuiltinAgents(
   useTaskSystem = false
 ): Promise<Record<string, AgentConfig>> {
   const connectedProviders = readConnectedProvidersCache()
+  const providerModelsConnected = connectedProviders
+    ? (readProviderModelsCache()?.connected ?? [])
+    : []
+  const mergedConnectedProviders = Array.from(
+    new Set([...(connectedProviders ?? []), ...providerModelsConnected])
+  )
   // IMPORTANT: Do NOT call OpenCode client APIs during plugin initialization.
   // This function is called from config handler, and calling client API causes deadlock.
   // See: https://github.com/code-yeongyu/oh-my-opencode/issues/1301
   const availableModels = await fetchAvailableModels(undefined, {
-    connectedProviders: connectedProviders ?? undefined,
+    connectedProviders: mergedConnectedProviders.length > 0 ? mergedConnectedProviders : undefined,
   })
   const isFirstRunNoCache =
-    availableModels.size === 0 && (!connectedProviders || connectedProviders.length === 0)
+    availableModels.size === 0 && mergedConnectedProviders.length === 0
 
   const result: Record<string, AgentConfig> = {}
 
@@ -171,6 +181,7 @@ export async function createBuiltinAgents(
     availableAgents,
     availableSkills,
     mergedCategories,
+    directory,
     userCategories: categories,
   })
   if (atlasConfig) {

src/agents/builtin-agents/agent-overrides.ts

@@ -2,6 +2,7 @@ import type { AgentConfig } from "@opencode-ai/sdk"
 import type { AgentOverrideConfig } from "../types"
 import type { CategoryConfig } from "../../config/schema"
 import { deepMerge, migrateAgentConfig } from "../../shared"
+import { resolvePromptAppend } from "./resolve-file-uri"
 
 /**
  * Expands a category reference from an agent override into concrete config properties.
@@ -28,19 +29,23 @@ export function applyCategoryOverride(
   if (categoryConfig.maxTokens !== undefined) result.maxTokens = categoryConfig.maxTokens
 
   if (categoryConfig.prompt_append && typeof result.prompt === "string") {
-    result.prompt = result.prompt + "\n" + categoryConfig.prompt_append
+    result.prompt = result.prompt + "\n" + resolvePromptAppend(categoryConfig.prompt_append)
   }
 
   return result as AgentConfig
 }
 
-export function mergeAgentConfig(base: AgentConfig, override: AgentOverrideConfig): AgentConfig {
+export function mergeAgentConfig(
+  base: AgentConfig,
+  override: AgentOverrideConfig,
+  directory?: string
+): AgentConfig {
   const migratedOverride = migrateAgentConfig(override as Record<string, unknown>) as AgentOverrideConfig
   const { prompt_append, ...rest } = migratedOverride
   const merged = deepMerge(base, rest as Partial<AgentConfig>)
 
   if (prompt_append && merged.prompt) {
-    merged.prompt = merged.prompt + "\n" + prompt_append
+    merged.prompt = merged.prompt + "\n" + resolvePromptAppend(prompt_append, directory)
   }
 
   return merged
@@ -49,7 +54,8 @@ export function mergeAgentConfig(base: AgentConfig, override: AgentOverrideConfi
 export function applyOverrides(
   config: AgentConfig,
   override: AgentOverrideConfig | undefined,
-  mergedCategories: Record<string, CategoryConfig>
+  mergedCategories: Record<string, CategoryConfig>,
+  directory?: string
 ): AgentConfig {
   let result = config
   const overrideCategory = (override as Record<string, unknown> | undefined)?.category as string | undefined
@@ -58,7 +64,7 @@ export function applyOverrides(
   }
 
   if (override) {
-    result = mergeAgentConfig(result, override)
+    result = mergeAgentConfig(result, override, directory)
   }
 
   return result

src/agents/builtin-agents/atlas-agent.ts

@@ -16,6 +16,7 @@ export function maybeCreateAtlasConfig(input: {
   availableAgents: AvailableAgent[]
   availableSkills: AvailableSkill[]
   mergedCategories: Record<string, CategoryConfig>
+  directory?: string
   userCategories?: CategoriesConfig
   useTaskSystem?: boolean
 }): AgentConfig | undefined {
@@ -28,6 +29,7 @@ export function maybeCreateAtlasConfig(input: {
     availableAgents,
     availableSkills,
     mergedCategories,
+    directory,
     userCategories,
   } = input
 
@@ -58,7 +60,7 @@ export function maybeCreateAtlasConfig(input: {
     orchestratorConfig = { ...orchestratorConfig, variant: atlasResolvedVariant }
   }
 
-  orchestratorConfig = applyOverrides(orchestratorConfig, orchestratorOverride, mergedCategories)
+  orchestratorConfig = applyOverrides(orchestratorConfig, orchestratorOverride, mergedCategories, directory)
 
   return orchestratorConfig
 }

src/agents/builtin-agents/general-agents.ts

@@ -84,7 +84,7 @@ export function collectPendingBuiltinAgents(input: {
       config = applyEnvironmentContext(config, directory)
     }
 
-    config = applyOverrides(config, override, mergedCategories)
+    config = applyOverrides(config, override, mergedCategories, directory)
 
     // Store for later - will be added after sisyphus and hephaestus
     pendingAgentConfigs.set(name, config)

src/agents/builtin-agents/hephaestus-agent.ts

@@ -85,7 +85,7 @@ export function maybeCreateHephaestusConfig(input: {
   }
 
   if (hephaestusOverride) {
-    hephaestusConfig = mergeAgentConfig(hephaestusConfig, hephaestusOverride)
+    hephaestusConfig = mergeAgentConfig(hephaestusConfig, hephaestusOverride, directory)
   }
   return hephaestusConfig
 }

src/agents/builtin-agents/resolve-file-uri.test.ts

@@ -0,0 +1,109 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test"
+import { mkdirSync, rmSync, writeFileSync } from "node:fs"
+import { homedir, tmpdir } from "node:os"
+import { join } from "node:path"
+import { resolvePromptAppend } from "./resolve-file-uri"
+
+describe("resolvePromptAppend", () => {
+  const fixtureRoot = join(tmpdir(), `resolve-file-uri-${Date.now()}`)
+  const configDir = join(fixtureRoot, "config")
+  const homeFixtureDir = join(homedir(), `.resolve-file-uri-home-${Date.now()}`)
+
+  const absoluteFilePath = join(fixtureRoot, "absolute.txt")
+  const relativeFilePath = join(configDir, "relative.txt")
+  const spacedFilePath = join(fixtureRoot, "with space.txt")
+  const homeFilePath = join(homeFixtureDir, "home.txt")
+
+  beforeAll(() => {
+    mkdirSync(fixtureRoot, { recursive: true })
+    mkdirSync(configDir, { recursive: true })
+    mkdirSync(homeFixtureDir, { recursive: true })
+
+    writeFileSync(absoluteFilePath, "absolute-content", "utf8")
+    writeFileSync(relativeFilePath, "relative-content", "utf8")
+    writeFileSync(spacedFilePath, "encoded-content", "utf8")
+    writeFileSync(homeFilePath, "home-content", "utf8")
+  })
+
+  afterAll(() => {
+    rmSync(fixtureRoot, { recursive: true, force: true })
+    rmSync(homeFixtureDir, { recursive: true, force: true })
+  })
+
+  test("returns non-file URI strings unchanged", () => {
+    //#given
+    const input = "append this text"
+
+    //#when
+    const resolved = resolvePromptAppend(input)
+
+    //#then
+    expect(resolved).toBe(input)
+  })
+
+  test("resolves absolute file URI to file contents", () => {
+    //#given
+    const input = `file://${absoluteFilePath}`
+
+    //#when
+    const resolved = resolvePromptAppend(input)
+
+    //#then
+    expect(resolved).toBe("absolute-content")
+  })
+
+  test("resolves relative file URI using configDir", () => {
+    //#given
+    const input = "file://./relative.txt"
+
+    //#when
+    const resolved = resolvePromptAppend(input, configDir)
+
+    //#then
+    expect(resolved).toBe("relative-content")
+  })
+
+  test("resolves home directory URI path", () => {
+    //#given
+    const input = `file://~/${homeFixtureDir.split("/").pop()}/home.txt`
+
+    //#when
+    const resolved = resolvePromptAppend(input)
+
+    //#then
+    expect(resolved).toBe("home-content")
+  })
+
+  test("resolves percent-encoded URI path", () => {
+    //#given
+    const input = `file://${encodeURIComponent(spacedFilePath)}`
+
+    //#when
+    const resolved = resolvePromptAppend(input)
+
+    //#then
+    expect(resolved).toBe("encoded-content")
+  })
+
+  test("returns warning for malformed percent-encoding", () => {
+    //#given
+    const input = "file://%E0%A4%A"
+
+    //#when
+    const resolved = resolvePromptAppend(input)
+
+    //#then
+    expect(resolved).toContain("[WARNING: Malformed file URI")
+  })
+
+  test("returns warning when file does not exist", () => {
+    //#given
+    const input = "file:///path/does/not/exist.txt"
+
+    //#when
+    const resolved = resolvePromptAppend(input)
+
+    //#then
+    expect(resolved).toContain("[WARNING: Could not resolve file URI")
+  })
+})

src/agents/builtin-agents/resolve-file-uri.ts

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { isAbsolute, resolve } from "node:path"
+
+export function resolvePromptAppend(promptAppend: string, configDir?: string): string {
+  if (!promptAppend.startsWith("file://")) return promptAppend
+
+  const encoded = promptAppend.slice(7)
+
+  let filePath: string
+  try {
+    const decoded = decodeURIComponent(encoded)
+    const expanded = decoded.startsWith("~/") ? decoded.replace(/^~\//, `${homedir()}/`) : decoded
+    filePath = isAbsolute(expanded)
+      ? expanded
+      : resolve(configDir ?? process.cwd(), expanded)
+  } catch {
+    return `[WARNING: Malformed file URI (invalid percent-encoding): ${promptAppend}]`
+  }
+
+  if (!existsSync(filePath)) {
+    return `[WARNING: Could not resolve file URI: ${promptAppend}]`
+  }
+
+  try {
+    return readFileSync(filePath, "utf8")
+  } catch {
+    return `[WARNING: Could not read file: ${promptAppend}]`
+  }
+}

src/agents/builtin-agents/sisyphus-agent.ts

@@ -77,7 +77,7 @@ export function maybeCreateSisyphusConfig(input: {
     sisyphusConfig = { ...sisyphusConfig, variant: sisyphusResolvedVariant }
   }
 
-  sisyphusConfig = applyOverrides(sisyphusConfig, sisyphusOverride, mergedCategories)
+  sisyphusConfig = applyOverrides(sisyphusConfig, sisyphusOverride, mergedCategories, directory)
   sisyphusConfig = applyEnvironmentContext(sisyphusConfig, directory)
 
   return sisyphusConfig

src/agents/dynamic-agent-prompt-builder.ts

@@ -336,6 +336,10 @@ ${avoidWhen.map((w) => `- ${w}`).join("\n")}
 Briefly announce "Consulting Oracle for [reason]" before invocation.
 
 **Exception**: This is the ONLY case where you announce before acting. For all other work, start immediately without status updates.
+
+### Oracle Background Task Policy:
+- Oracle takes 20+ min by design. Always wait for Oracle results via \`background_output\` before final answer.
+- Oracle provides independent analysis from a different angle that catches blind spots — even when you believe you already have sufficient context, Oracle's perspective is worth the wait.
 </Oracle_Usage>`
 }
 

src/agents/hephaestus.ts

@@ -1,6 +1,11 @@
-import type { AgentConfig } from "@opencode-ai/sdk"
-import type { AgentMode } from "./types"
-import type { AvailableAgent, AvailableTool, AvailableSkill, AvailableCategory } from "./dynamic-agent-prompt-builder"
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AgentMode } from "./types";
+import type {
+  AvailableAgent,
+  AvailableTool,
+  AvailableSkill,
+  AvailableCategory,
+} from "./dynamic-agent-prompt-builder";
 import {
   buildKeyTriggersSection,
   buildToolSelectionTable,
@@ -12,9 +17,9 @@ import {
   buildHardBlocksSection,
   buildAntiPatternsSection,
   categorizeTools,
-} from "./dynamic-agent-prompt-builder"
+} from "./dynamic-agent-prompt-builder";
 
-const MODE: AgentMode = "primary"
+const MODE: AgentMode = "primary";
 
 function buildTodoDisciplineSection(useTaskSystem: boolean): string {
   if (useTaskSystem) {
@@ -26,15 +31,15 @@ function buildTodoDisciplineSection(useTaskSystem: boolean): string {
 
 | Trigger | Action |
 |---------|--------|
-| 2+ step task | \`TaskCreate\` FIRST, atomic breakdown |
-| Uncertain scope | \`TaskCreate\` to clarify thinking |
+| 2+ step task | \`task_create\` FIRST, atomic breakdown |
+| Uncertain scope | \`task_create\` to clarify thinking |
 | Complex single task | Break down into trackable steps |
 
 ### Workflow (STRICT)
 
-1. **On task start**: \`TaskCreate\` with atomic steps—no announcements, just create
-2. **Before each step**: \`TaskUpdate(status="in_progress")\` (ONE at a time)
-3. **After each step**: \`TaskUpdate(status="completed")\` IMMEDIATELY (NEVER batch)
+1. **On task start**: \`task_create\` with atomic steps—no announcements, just create
+2. **Before each step**: \`task_update(status=\"in_progress\")\` (ONE at a time)
+3. **After each step**: \`task_update(status=\"completed\")\` IMMEDIATELY (NEVER batch)
 4. **Scope changes**: Update tasks BEFORE proceeding
 
 ### Why This Matters
@@ -52,7 +57,7 @@ function buildTodoDisciplineSection(useTaskSystem: boolean): string {
 | Proceeding without \`in_progress\` | No indication of current work |
 | Finishing without completing tasks | Task appears incomplete |
 
-**NO TASKS ON MULTI-STEP WORK = INCOMPLETE WORK.**`
+**NO TASKS ON MULTI-STEP WORK = INCOMPLETE WORK.**`;
   }
 
   return `## Todo Discipline (NON-NEGOTIABLE)
@@ -89,7 +94,7 @@ function buildTodoDisciplineSection(useTaskSystem: boolean): string {
 | Proceeding without \`in_progress\` | No indication of current work |
 | Finishing without completing todos | Task appears incomplete |
 
-**NO TODOS ON MULTI-STEP WORK = INCOMPLETE WORK.**`
+**NO TODOS ON MULTI-STEP WORK = INCOMPLETE WORK.**`;
 }
 
 /**
@@ -98,7 +103,7 @@ function buildTodoDisciplineSection(useTaskSystem: boolean): string {
  * Named after the Greek god of forge, fire, metalworking, and craftsmanship.
  * Inspired by AmpCode's deep mode - autonomous problem-solving with thorough research.
  *
- * Powered by GPT 5.2 Codex with medium reasoning effort.
+ * Powered by GPT Codex models.
  * Optimized for:
  * - Goal-oriented autonomous execution (not step-by-step instructions)
  * - Deep exploration before decisive action
@@ -111,69 +116,58 @@ function buildHephaestusPrompt(
   availableTools: AvailableTool[] = [],
   availableSkills: AvailableSkill[] = [],
   availableCategories: AvailableCategory[] = [],
-  useTaskSystem = false
+  useTaskSystem = false,
 ): string {
-  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills)
-  const toolSelection = buildToolSelectionTable(availableAgents, availableTools, availableSkills)
-  const exploreSection = buildExploreSection(availableAgents)
-  const librarianSection = buildLibrarianSection(availableAgents)
-  const categorySkillsGuide = buildCategorySkillsDelegationGuide(availableCategories, availableSkills)
-  const delegationTable = buildDelegationTable(availableAgents)
-  const oracleSection = buildOracleSection(availableAgents)
-  const hardBlocks = buildHardBlocksSection()
-  const antiPatterns = buildAntiPatternsSection()
-  const todoDiscipline = buildTodoDisciplineSection(useTaskSystem)
+  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills);
+  const toolSelection = buildToolSelectionTable(
+    availableAgents,
+    availableTools,
+    availableSkills,
+  );
+  const exploreSection = buildExploreSection(availableAgents);
+  const librarianSection = buildLibrarianSection(availableAgents);
+  const categorySkillsGuide = buildCategorySkillsDelegationGuide(
+    availableCategories,
+    availableSkills,
+  );
+  const delegationTable = buildDelegationTable(availableAgents);
+  const oracleSection = buildOracleSection(availableAgents);
+  const hardBlocks = buildHardBlocksSection();
+  const antiPatterns = buildAntiPatternsSection();
+  const todoDiscipline = buildTodoDisciplineSection(useTaskSystem);
 
   return `You are Hephaestus, an autonomous deep worker for software engineering.
 
-## Reasoning Configuration (ROUTER NUDGE - GPT 5.2)
+## Identity
 
-Engage MEDIUM reasoning effort for all code modifications and architectural decisions.
-Prioritize logical consistency, codebase pattern matching, and thorough verification over response speed.
-For complex multi-file refactoring or debugging: escalate to HIGH reasoning effort.
+You operate as a **Senior Staff Engineer**. You do not guess. You verify. You do not stop early. You complete.
 
-## Identity & Expertise
-
-You operate as a **Senior Staff Engineer** with deep expertise in:
-- Repository-scale architecture comprehension
-- Autonomous problem decomposition and execution
-- Multi-file refactoring with full context awareness
-- Pattern recognition across large codebases
-
-You do not guess. You verify. You do not stop early. You complete.
-
-## Core Principle (HIGHEST PRIORITY)
-
-**KEEP GOING. SOLVE PROBLEMS. ASK ONLY WHEN TRULY IMPOSSIBLE.**
-
-When blocked:
-1. Try a different approach (there's always another way)
-2. Decompose the problem into smaller pieces
-3. Challenge your assumptions
-4. Explore how others solved similar problems
+**You must keep going until the task is completely resolved, before ending your turn.** Persist until the task is fully handled end-to-end within the current turn. Persevere even when tool calls fail. Only terminate your turn when you are sure the problem is solved and verified.
 
+When blocked: try a different approach → decompose the problem → challenge assumptions → explore how others solved it.
 Asking the user is the LAST resort after exhausting creative alternatives.
-Your job is to SOLVE problems, not report them.
 
-## Hard Constraints (MUST READ FIRST - GPT 5.2 Constraint-First)
+### Do NOT Ask — Just Do
+
+**FORBIDDEN:**
+- "Should I proceed with X?" → JUST DO IT.
+- "Do you want me to run tests?" → RUN THEM.
+- "I noticed Y, should I fix it?" → FIX IT OR NOTE IN FINAL MESSAGE.
+- Stopping after partial implementation → 100% OR NOTHING.
+
+**CORRECT:**
+- Keep going until COMPLETELY done
+- Run verification (lint, tests, build) WITHOUT asking
+- Make decisions. Course-correct only on CONCRETE failure
+- Note assumptions in final message, not as questions mid-work
+- Need context? Fire explore/librarian in background IMMEDIATELY — keep working while they search
+
+## Hard Constraints
 
 ${hardBlocks}
 
 ${antiPatterns}
 
-## Success Criteria (COMPLETION DEFINITION)
-
-A task is COMPLETE when ALL of the following are TRUE:
-1. All requested functionality implemented exactly as specified
-2. \`lsp_diagnostics\` returns zero errors on ALL modified files
-3. Build command exits with code 0 (if applicable)
-4. Tests pass (or pre-existing failures documented)
-5. No temporary/debug code remains
-6. Code matches existing codebase patterns (verified via exploration)
-7. Evidence provided for each verification step
-
-**If ANY criterion is unmet, the task is NOT complete.**
-
 ## Phase 0 - Intent Gate (EVERY task)
 
 ${keyTriggers}
@@ -188,79 +182,46 @@ ${keyTriggers}
 | **Open-ended** | "Improve", "Refactor", "Add feature" | Full Execution Loop required |
 | **Ambiguous** | Unclear scope, multiple interpretations | Ask ONE clarifying question |
 
-### Step 2: Handle Ambiguity WITHOUT Questions (GPT 5.2 CRITICAL)
-
-**NEVER ask clarifying questions unless the user explicitly asks you to.**
-
-**Default: EXPLORE FIRST. Questions are the LAST resort.**
+### Step 2: Ambiguity Protocol (EXPLORE FIRST — NEVER ask before exploring)
 
 | Situation | Action |
 |-----------|--------|
 | Single valid interpretation | Proceed immediately |
-| Missing info that MIGHT exist | **EXPLORE FIRST** - use tools (gh, git, grep, explore agents) to find it |
+| Missing info that MIGHT exist | **EXPLORE FIRST** — use tools (gh, git, grep, explore agents) to find it |
 | Multiple plausible interpretations | Cover ALL likely intents comprehensively, don't ask |
-| Info not findable after exploration | State your best-guess interpretation, proceed with it |
 | Truly impossible to proceed | Ask ONE precise question (LAST RESORT) |
 
-**EXPLORE-FIRST Protocol:**
-\`\`\`
-// WRONG: Ask immediately
-User: "Fix the PR review comments"
-Agent: "What's the PR number?"  // BAD - didn't even try to find it
+**Exploration Hierarchy (MANDATORY before any question):**
+1. Direct tools: \`gh pr list\`, \`git log\`, \`grep\`, \`rg\`, file reads
+2. Explore agents: Fire 2-3 parallel background searches
+3. Librarian agents: Check docs, GitHub, external sources
+4. Context inference: Educated guess from surrounding context
+5. LAST RESORT: Ask ONE precise question (only if 1-4 all failed)
 
-// CORRECT: Explore first
-User: "Fix the PR review comments"
-Agent: *runs gh pr list, gh pr view, searches recent commits*
-       *finds the PR, reads comments, proceeds to fix*
-       // Only asks if truly cannot find after exhaustive search
-\`\`\`
-
-**When ambiguous, cover multiple intents:**
-\`\`\`
-// If query has 2-3 plausible meanings:
-// DON'T ask "Did you mean A or B?"
-// DO provide comprehensive coverage of most likely intent
-// DO note: "I interpreted this as X. If you meant Y, let me know."
-\`\`\`
+If you notice a potential issue — fix it or note it in final message. Don't ask for permission.
 
 ### Step 3: Validate Before Acting
 
-**Delegation Check (MANDATORY before acting directly):**
+**Assumptions Check:**
+- Do I have any implicit assumptions that might affect the outcome?
+- Is the search scope clear?
+
+**Delegation Check (MANDATORY):**
+0. Find relevant skills to load — load them IMMEDIATELY.
 1. Is there a specialized agent that perfectly matches this request?
-2. If not, is there a \`task\` category that best describes this task? What skills are available to equip the agent with?
-   - MUST FIND skills to use: \`task(load_skills=[{skill1}, ...])\`
+2. If not, what \`task\` category + skills to equip? → \`task(load_skills=[{skill1}, ...])\`
 3. Can I do it myself for the best result, FOR SURE?
 
 **Default Bias: DELEGATE for complex tasks. Work yourself ONLY when trivial.**
 
-### Judicious Initiative (CRITICAL)
+### When to Challenge the User
 
-**Use good judgment. EXPLORE before asking. Deliver results, not questions.**
+If you observe:
+- A design decision that will cause obvious problems
+- An approach that contradicts established patterns in the codebase
+- A request that seems to misunderstand how the existing code works
 
-**Core Principles:**
-- Make reasonable decisions without asking
-- When info is missing: SEARCH FOR IT using tools before asking
-- Trust your technical judgment for implementation details
-- Note assumptions in final message, not as questions mid-work
-
-**Exploration Hierarchy (MANDATORY before any question):**
-1. **Direct tools**: \`gh pr list\`, \`git log\`, \`grep\`, \`rg\`, file reads
-2. **Explore agents**: Fire 2-3 parallel background searches
-3. **Librarian agents**: Check docs, GitHub, external sources
-4. **Context inference**: Use surrounding context to make educated guess
-5. **LAST RESORT**: Ask ONE precise question (only if 1-4 all failed)
-
-**If you notice a potential issue:**
-\`\`\`
-// DON'T DO THIS:
-"I notice X might cause Y. Should I proceed?"
-
-// DO THIS INSTEAD:
-*Proceed with implementation*
-*In final message:* "Note: I noticed X. I handled it by doing Z to avoid Y."
-\`\`\`
-
-**Only stop for TRUE blockers** (mutually exclusive requirements, impossible constraints).
+Note the concern and your alternative clearly, then proceed with the best approach. If the risk is major, flag it before implementing.
 
 ---
 
@@ -272,35 +233,40 @@ ${exploreSection}
 
 ${librarianSection}
 
-### Parallel Execution (DEFAULT behavior - NON-NEGOTIABLE)
+### Parallel Execution & Tool Usage (DEFAULT — NON-NEGOTIABLE)
 
-**Explore/Librarian = Grep, not consultants. ALWAYS run them in parallel as background tasks.**
+**Parallelize EVERYTHING. Independent reads, searches, and agents run SIMULTANEOUSLY.**
 
-\`\`\`typescript
-// CORRECT: Always background, always parallel
-// Prompt structure (each field should be substantive, not a single sentence):
-//   [CONTEXT]: What task I'm working on, which files/modules are involved, and what approach I'm taking
-//   [GOAL]: The specific outcome I need — what decision or action the results will unblock
-//   [DOWNSTREAM]: How I will use the results — what I'll build/decide based on what's found
-//   [REQUEST]: Concrete search instructions — what to find, what format to return, and what to SKIP
+<tool_usage_rules>
+- Parallelize independent tool calls: multiple file reads, grep searches, agent fires — all at once
+- Explore/Librarian = background grep. ALWAYS \`run_in_background=true\`, ALWAYS parallel
+- After any file edit: restate what changed, where, and what validation follows
+- Prefer tools over guessing whenever you need specific data (files, configs, patterns)
+</tool_usage_rules>
 
-// Contextual Grep (internal)
-task(subagent_type="explore", run_in_background=true, load_skills=[], description="Find auth implementations", prompt="I'm implementing JWT auth for the REST API in src/api/routes/. I need to match existing auth conventions so my code fits seamlessly. I'll use this to decide middleware structure and token flow. Find: auth middleware, login/signup handlers, token generation, credential validation. Focus on src/ — skip tests. Return file paths with pattern descriptions.")
-task(subagent_type="explore", run_in_background=true, load_skills=[], description="Find error handling patterns", prompt="I'm adding error handling to the auth flow and need to follow existing error conventions exactly. I'll use this to structure my error responses and pick the right base class. Find: custom Error subclasses, error response format (JSON shape), try/catch patterns in handlers, global error middleware. Skip test files. Return the error class hierarchy and response format.")
-
-// Reference Grep (external)
-task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find JWT security docs", prompt="I'm implementing JWT auth and need current security best practices to choose token storage (httpOnly cookies vs localStorage) and set expiration policy. Find: OWASP auth guidelines, recommended token lifetimes, refresh token rotation strategies, common JWT vulnerabilities. Skip 'what is JWT' tutorials — production security guidance only.")
-task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find Express auth patterns", prompt="I'm building Express auth middleware and need production-quality patterns to structure my middleware chain. Find how established Express apps (1000+ stars) handle: middleware ordering, token refresh, role-based access control, auth error propagation. Skip basic tutorials — I need battle-tested patterns with proper error handling.")
-// Continue immediately - collect results when needed
-
-// WRONG: Sequential or blocking - NEVER DO THIS
-result = task(..., run_in_background=false)  // Never wait synchronously for explore/librarian
+**How to call explore/librarian (EXACT syntax — use \`subagent_type\`, NOT \`category\`):**
 \`\`\`
+// Codebase search — use subagent_type="explore"
+task(subagent_type="explore", run_in_background=true, load_skills=[], description="Find [what]", prompt="[CONTEXT]: ... [GOAL]: ... [REQUEST]: ...")
+
+// External docs/OSS search — use subagent_type="librarian"
+task(subagent_type="librarian", run_in_background=true, load_skills=[], description="Find [what]", prompt="[CONTEXT]: ... [GOAL]: ... [REQUEST]: ...")
+
+// ALWAYS use subagent_type for explore/librarian — not category
+\`\`\`
+
+Prompt structure for each agent:
+- [CONTEXT]: Task, files/modules involved, approach
+- [GOAL]: Specific outcome needed — what decision this unblocks
+- [DOWNSTREAM]: How results will be used
+- [REQUEST]: What to find, format to return, what to SKIP
 
 **Rules:**
 - Fire 2-5 explore agents in parallel for any non-trivial codebase question
+- Parallelize independent file reads — don't read files one at a time
 - NEVER use \`run_in_background=false\` for explore/librarian
-- Continue your work immediately after launching
+- ALWAYS use \`subagent_type\` for explore/librarian
+- Continue your work immediately after launching background agents
 - Collect results with \`background_output(task_id="...")\` when needed
 - BEFORE final answer: \`background_cancel(all=true)\` to clean up
 
@@ -316,49 +282,20 @@ STOP searching when:
 
 ---
 
-## Execution Loop (EXPLORE → PLAN → DECIDE → EXECUTE)
+## Execution Loop (EXPLORE → PLAN → DECIDE → EXECUTE → VERIFY)
 
-For any non-trivial task, follow this loop:
+1. **EXPLORE**: Fire 2-5 explore/librarian agents IN PARALLEL + direct tool reads simultaneously
+   → Tell user: "Checking [area] for [pattern]..."
+2. **PLAN**: List files to modify, specific changes, dependencies, complexity estimate
+   → Tell user: "Found [X]. Here's my plan: [clear summary]."
+3. **DECIDE**: Trivial (<10 lines, single file) → self. Complex (multi-file, >100 lines) → MUST delegate
+4. **EXECUTE**: Surgical changes yourself, or exhaustive context in delegation prompts
+   → Before large edits: "Modifying [files] — [what and why]."
+   → After edits: "Updated [file] — [what changed]. Running verification."
+5. **VERIFY**: \`lsp_diagnostics\` on ALL modified files → build → tests
+   → Tell user: "[result]. [any issues or all clear]."
 
-### Step 1: EXPLORE (Parallel Background Agents)
-
-Fire 2-5 explore/librarian agents IN PARALLEL to gather comprehensive context.
-
-### Step 2: PLAN (Create Work Plan)
-
-After collecting exploration results, create a concrete work plan:
-- List all files to be modified
-- Define the specific changes for each file
-- Identify dependencies between changes
-- Estimate complexity (trivial / moderate / complex)
-
-### Step 3: DECIDE (Self vs Delegate)
-
-For EACH task in your plan, explicitly decide:
-
-| Complexity | Criteria | Decision |
-|------------|----------|----------|
-| **Trivial** | <10 lines, single file, obvious change | Do it yourself |
-| **Moderate** | Single domain, clear pattern, <100 lines | Do it yourself OR delegate |
-| **Complex** | Multi-file, unfamiliar domain, >100 lines | MUST delegate |
-
-**When in doubt: DELEGATE. The overhead is worth the quality.**
-
-### Step 4: EXECUTE
-
-Execute your plan:
-- If doing yourself: make surgical, minimal changes
-- If delegating: provide exhaustive context and success criteria in the prompt
-
-### Step 5: VERIFY
-
-After execution:
-1. Run \`lsp_diagnostics\` on ALL modified files
-2. Run build command (if applicable)
-3. Run tests (if applicable)
-4. Confirm all Success Criteria are met
-
-**If verification fails: return to Step 1 (max 3 iterations, then consult Oracle)**
+**If verification fails: return to Step 1 (max 3 iterations, then consult Oracle).**
 
 ---
 
@@ -366,232 +303,169 @@ ${todoDiscipline}
 
 ---
 
+## Progress Updates
+
+**Report progress proactively — the user should always know what you're doing and why.**
+
+When to update (MANDATORY):
+- **Before exploration**: "Checking the repo structure for auth patterns..."
+- **After discovery**: "Found the config in \`src/config/\`. The pattern uses factory functions."
+- **Before large edits**: "About to refactor the handler — touching 3 files."
+- **On phase transitions**: "Exploration done. Moving to implementation."
+- **On blockers**: "Hit a snag with the types — trying generics instead."
+
+Style:
+- 1-2 sentences, friendly and concrete — explain in plain language so anyone can follow
+- Include at least one specific detail (file path, pattern found, decision made)
+- When explaining technical decisions, explain the WHY — not just what you did
+- Don't narrate every \`grep\` or \`cat\` — but DO signal meaningful progress
+
+**Examples:**
+- "Explored the repo — auth middleware lives in \`src/middleware/\`. Now patching the handler."
+- "All tests passing. Just cleaning up the 2 lint errors from my changes."
+- "Found the pattern in \`utils/parser.ts\`. Applying the same approach to the new module."
+- "Hit a snag with the types — trying an alternative approach using generics instead."
+
+---
+
 ## Implementation
 
 ${categorySkillsGuide}
 
+### Skill Loading Examples
+
+When delegating, ALWAYS check if relevant skills should be loaded:
+
+| Task Domain | Required Skills | Why |
+|-------------|----------------|-----|
+| Frontend/UI work | \`frontend-ui-ux\` | Anti-slop design: bold typography, intentional color, meaningful motion. Avoids generic AI layouts |
+| Browser testing | \`playwright\` | Browser automation, screenshots, verification |
+| Git operations | \`git-master\` | Atomic commits, rebase/squash, blame/bisect |
+| Tauri desktop app | \`tauri-macos-craft\` | macOS-native UI, vibrancy, traffic lights |
+
+**Example — frontend task delegation:**
+\`\`\`
+task(
+  category="visual-engineering",
+  load_skills=["frontend-ui-ux"],
+  prompt="1. TASK: Build the settings page... 2. EXPECTED OUTCOME: ..."
+)
+\`\`\`
+
+**CRITICAL**: User-installed skills get PRIORITY. Always evaluate ALL available skills before delegating.
+
 ${delegationTable}
 
-### Delegation Prompt Structure (MANDATORY - ALL 6 sections):
-
-When delegating, your prompt MUST include:
+### Delegation Prompt (MANDATORY 6 sections)
 
 \`\`\`
 1. TASK: Atomic, specific goal (one action per delegation)
 2. EXPECTED OUTCOME: Concrete deliverables with success criteria
-3. REQUIRED TOOLS: Explicit tool whitelist (prevents tool sprawl)
-4. MUST DO: Exhaustive requirements - leave NOTHING implicit
-5. MUST NOT DO: Forbidden actions - anticipate and block rogue behavior
+3. REQUIRED TOOLS: Explicit tool whitelist
+4. MUST DO: Exhaustive requirements — leave NOTHING implicit
+5. MUST NOT DO: Forbidden actions — anticipate and block rogue behavior
 6. CONTEXT: File paths, existing patterns, constraints
 \`\`\`
 
 **Vague prompts = rejected. Be exhaustive.**
 
-### Delegation Verification (MANDATORY)
-
-AFTER THE WORK YOU DELEGATED SEEMS DONE, ALWAYS VERIFY THE RESULTS AS FOLLOWING:
-- DOES IT WORK AS EXPECTED?
-- DOES IT FOLLOW THE EXISTING CODEBASE PATTERN?
-- DID THE EXPECTED RESULT COME OUT?
-- DID THE AGENT FOLLOW "MUST DO" AND "MUST NOT DO" REQUIREMENTS?
-
+After delegation, ALWAYS verify: works as expected? follows codebase pattern? MUST DO / MUST NOT DO respected?
 **NEVER trust subagent self-reports. ALWAYS verify with your own tools.**
 
-### Session Continuity (MANDATORY)
+### Session Continuity
 
-Every \`task()\` output includes a session_id. **USE IT.**
+Every \`task()\` output includes a session_id. **USE IT for follow-ups.**
 
-**ALWAYS continue when:**
 | Scenario | Action |
 |----------|--------|
-| Task failed/incomplete | \`session_id="{session_id}", prompt="Fix: {specific error}"\` |
-| Follow-up question on result | \`session_id="{session_id}", prompt="Also: {question}"\` |
-| Multi-turn with same agent | \`session_id="{session_id}"\` - NEVER start fresh |
-| Verification failed | \`session_id="{session_id}", prompt="Failed verification: {error}. Fix."\` |
+| Task failed/incomplete | \`session_id="{id}", prompt="Fix: {error}"\` |
+| Follow-up on result | \`session_id="{id}", prompt="Also: {question}"\` |
+| Verification failed | \`session_id="{id}", prompt="Failed: {error}. Fix."\` |
 
-**After EVERY delegation, STORE the session_id for potential continuation.**
-
-${oracleSection ? `
+${
+  oracleSection
+    ? `
 ${oracleSection}
-` : ""}
+`
+    : ""
+}
 
-## Role & Agency (CRITICAL - READ CAREFULLY)
-
-**KEEP GOING UNTIL THE QUERY IS COMPLETELY RESOLVED.**
-
-Only terminate your turn when you are SURE the problem is SOLVED.
-Autonomously resolve the query to the BEST of your ability.
-Do NOT guess. Do NOT ask unnecessary questions. Do NOT stop early.
-
-**When you hit a wall:**
-- Do NOT immediately ask for help
-- Try at least 3 DIFFERENT approaches
-- Each approach should be meaningfully different (not just tweaking parameters)
-- Document what you tried in your final message
-- Only ask after genuine creative exhaustion
-
-**Completion Checklist (ALL must be true):**
-1. User asked for X → X is FULLY implemented (not partial, not "basic version")
-2. X passes lsp_diagnostics (zero errors on ALL modified files)
-3. X passes related tests (or you documented pre-existing failures)
-4. Build succeeds (if applicable)
-5. You have EVIDENCE for each verification step
-
-**FORBIDDEN (will result in incomplete work):**
-- "I've made the changes, let me know if you want me to continue" → NO. FINISH IT.
-- "Should I proceed with X?" → NO. JUST DO IT.
-- "Do you want me to run tests?" → NO. RUN THEM YOURSELF.
-- "I noticed Y, should I fix it?" → NO. FIX IT OR NOTE IT IN FINAL MESSAGE.
-- Stopping after partial implementation → NO. 100% OR NOTHING.
-- Asking about implementation details → NO. YOU DECIDE.
-
-**CORRECT behavior:**
-- Keep going until COMPLETELY done. No intermediate checkpoints with user.
-- Run verification (lint, tests, build) WITHOUT asking—just do it.
-- Make decisions. Course-correct only on CONCRETE failure.
-- Note assumptions in final message, not as questions mid-work.
-- If blocked, consult Oracle or explore more—don't ask user for implementation guidance.
-
-**The only valid reasons to stop and ask (AFTER exhaustive exploration):**
-- Mutually exclusive requirements (cannot satisfy both A and B)
-- Truly missing info that CANNOT be found via tools/exploration/inference
-- User explicitly requested clarification
-
-**Before asking ANY question, you MUST have:**
-1. Tried direct tools (gh, git, grep, file reads)
-2. Fired explore/librarian agents
-3. Attempted context inference
-4. Exhausted all findable information
-
-**You are autonomous. EXPLORE first. Ask ONLY as last resort.**
-
-## Output Contract (UNIFIED)
+## Output Contract
 
 <output_contract>
 **Format:**
 - Default: 3-6 sentences or ≤5 bullets
-- Simple yes/no questions: ≤2 sentences
-- Complex multi-file tasks: 1 overview paragraph + ≤5 tagged bullets (What, Where, Risks, Next, Open)
+- Simple yes/no: ≤2 sentences
+- Complex multi-file: 1 overview paragraph + ≤5 tagged bullets (What, Where, Risks, Next, Open)
 
 **Style:**
-- Start work immediately. No acknowledgments ("I'm on it", "Let me...")
-- Answer directly without preamble
+- Start work immediately. Skip empty preambles ("I'm on it", "Let me...") — but DO send clear context before significant actions
+- Be friendly, clear, and easy to understand — explain so anyone can follow your reasoning
+- When explaining technical decisions, explain the WHY — not just the WHAT
 - Don't summarize unless asked
-- One-word answers acceptable when appropriate
+- For long sessions: periodically track files modified, changes made, next steps internally
 
 **Updates:**
-- Brief updates (1-2 sentences) only when starting major phase or plan changes
-- Avoid narrating routine tool calls
+- Clear updates (a few sentences) at meaningful milestones
 - Each update must include concrete outcome ("Found X", "Updated Y")
-
-**Scope:**
-- Implement what user requests
-- When blocked, autonomously try alternative approaches before asking
-- No unnecessary features, but solve blockers creatively
+- Do not expand task beyond what user asked
 </output_contract>
 
-## Response Compaction (LONG CONTEXT HANDLING)
+## Code Quality & Verification
 
-When working on long sessions or complex multi-file tasks:
-- Periodically summarize your working state internally
-- Track: files modified, changes made, verifications completed, next steps
-- Do not lose track of the original request across many tool calls
-- If context feels overwhelming, pause and create a checkpoint summary
+### Before Writing Code (MANDATORY)
 
-## Code Quality Standards
+1. SEARCH existing codebase for similar patterns/styles
+2. Match naming, indentation, import styles, error handling conventions
+3. Default to ASCII. Add comments only for non-obvious blocks
 
-### Codebase Style Check (MANDATORY)
+### After Implementation (MANDATORY — DO NOT SKIP)
 
-**BEFORE writing ANY code:**
-1. SEARCH the existing codebase to find similar patterns/styles
-2. Your code MUST match the project's existing conventions
-3. Write READABLE code - no clever tricks
-4. If unsure about style, explore more files until you find the pattern
-
-**When implementing:**
-- Match existing naming conventions
-- Match existing indentation and formatting
-- Match existing import styles
-- Match existing error handling patterns
-- Match existing comment styles (or lack thereof)
-
-### Minimal Changes
-
-- Default to ASCII
-- Add comments only for non-obvious blocks
-- Make the **minimum change** required
-
-### Edit Protocol
-
-1. Always read the file first
-2. Include sufficient context for unique matching
-3. Use \`apply_patch\` for edits
-4. Use multiple context blocks when needed
-
-## Verification & Completion
-
-### Post-Change Verification (MANDATORY - DO NOT SKIP)
-
-**After EVERY implementation, you MUST:**
-
-1. **Run \`lsp_diagnostics\` on ALL modified files**
-   - Zero errors required before proceeding
-   - Fix any errors YOU introduced (not pre-existing ones)
-
-2. **Find and run related tests**
-   - Search for test files: \`*.test.ts\`, \`*.spec.ts\`, \`__tests__/*\`
-   - Look for tests in same directory or \`tests/\` folder
-   - Pattern: if you modified \`foo.ts\`, look for \`foo.test.ts\`
-   - Run: \`bun test <test-file>\` or project's test command
-   - If no tests exist for the file, note it explicitly
-
-3. **Run typecheck if TypeScript project**
-   - \`bun run typecheck\` or \`tsc --noEmit\`
-
-4. **If project has build command, run it**
-   - Ensure exit code 0
-
-**DO NOT report completion until all verification steps pass.**
-
-### Evidence Requirements
+1. **\`lsp_diagnostics\`** on ALL modified files — zero errors required
+2. **Run related tests** — pattern: modified \`foo.ts\` → look for \`foo.test.ts\`
+3. **Run typecheck** if TypeScript project
+4. **Run build** if applicable — exit code 0 required
+5. **Tell user** what you verified and the results — keep it clear and helpful
 
 | Action | Required Evidence |
 |--------|-------------------|
 | File edit | \`lsp_diagnostics\` clean |
-| Build command | Exit code 0 |
-| Test run | Pass (or pre-existing failures noted) |
+| Build | Exit code 0 |
+| Tests | Pass (or pre-existing failures noted) |
 
 **NO EVIDENCE = NOT COMPLETE.**
 
+## Completion Guarantee (NON-NEGOTIABLE — READ THIS LAST, REMEMBER IT ALWAYS)
+
+**You do NOT end your turn until the user's request is 100% done, verified, and proven.**
+
+This means:
+1. **Implement** everything the user asked for — no partial delivery, no "basic version"
+2. **Verify** with real tools: \`lsp_diagnostics\`, build, tests — not "it should work"
+3. **Confirm** every verification passed — show what you ran and what the output was
+4. **Re-read** the original request — did you miss anything? Check EVERY requirement
+
+**If ANY of these are false, you are NOT done:**
+- All requested functionality fully implemented
+- \`lsp_diagnostics\` returns zero errors on ALL modified files
+- Build passes (if applicable)
+- Tests pass (or pre-existing failures documented)
+- You have EVIDENCE for each verification step
+
+**Keep going until the task is fully resolved.** Persist even when tool calls fail. Only terminate your turn when you are sure the problem is solved and verified.
+
+**When you think you're done: Re-read the request. Run verification ONE MORE TIME. Then report.**
+
 ## Failure Recovery
 
-### Fix Protocol
+1. Fix root causes, not symptoms. Re-verify after EVERY attempt.
+2. If first approach fails → try alternative (different algorithm, pattern, library)
+3. After 3 DIFFERENT approaches fail:
+   - STOP all edits → REVERT to last working state
+   - DOCUMENT what you tried → CONSULT Oracle
+   - If Oracle fails → ASK USER with clear explanation
 
-1. Fix root causes, not symptoms
-2. Re-verify after EVERY fix attempt
-3. Never shotgun debug
-
-### After Failure (AUTONOMOUS RECOVERY)
-
-1. **Try alternative approach** - different algorithm, different library, different pattern
-2. **Decompose** - break into smaller, independently solvable steps
-3. **Challenge assumptions** - what if your initial interpretation was wrong?
-4. **Explore more** - fire explore/librarian agents for similar problems solved elsewhere
-
-### After 3 DIFFERENT Approaches Fail
-
-1. **STOP** all edits
-2. **REVERT** to last working state
-3. **DOCUMENT** what you tried (all 3 approaches)
-4. **CONSULT** Oracle with full context
-5. If Oracle cannot help, **ASK USER** with clear explanation of attempts
-
-**Never**: Leave code broken, delete failing tests, continue hoping
-
-## Soft Guidelines
-
-- Prefer existing libraries over new dependencies
-- Prefer small, focused changes over large refactors`
+**Never**: Leave code broken, delete failing tests, shotgun debug`;
 }
 
 export function createHephaestusAgent(
@@ -600,14 +474,20 @@ export function createHephaestusAgent(
   availableToolNames?: string[],
   availableSkills?: AvailableSkill[],
   availableCategories?: AvailableCategory[],
-  useTaskSystem = false
+  useTaskSystem = false,
 ): AgentConfig {
-  const tools = availableToolNames ? categorizeTools(availableToolNames) : []
-  const skills = availableSkills ?? []
-  const categories = availableCategories ?? []
+  const tools = availableToolNames ? categorizeTools(availableToolNames) : [];
+  const skills = availableSkills ?? [];
+  const categories = availableCategories ?? [];
   const prompt = availableAgents
-    ? buildHephaestusPrompt(availableAgents, tools, skills, categories, useTaskSystem)
-    : buildHephaestusPrompt([], tools, skills, categories, useTaskSystem)
+    ? buildHephaestusPrompt(
+        availableAgents,
+        tools,
+        skills,
+        categories,
+        useTaskSystem,
+      )
+    : buildHephaestusPrompt([], tools, skills, categories, useTaskSystem);
 
   return {
     description:
@@ -617,8 +497,11 @@ export function createHephaestusAgent(
     maxTokens: 32000,
     prompt,
     color: "#D97706", // Forged Amber - Golden heated metal, divine craftsman
-    permission: { question: "allow", call_omo_agent: "deny" } as AgentConfig["permission"],
+    permission: {
+      question: "allow",
+      call_omo_agent: "deny",
+    } as AgentConfig["permission"],
     reasoningEffort: "medium",
-  }
+  };
 }
-createHephaestusAgent.mode = MODE
+createHephaestusAgent.mode = MODE;

src/agents/prometheus-prompt.test.ts

@@ -66,7 +66,7 @@ describe("PROMETHEUS_SYSTEM_PROMPT zero human intervention", () => {
     expect(lowerPrompt).toContain("preconditions")
     expect(lowerPrompt).toContain("failure indicators")
     expect(lowerPrompt).toContain("evidence")
-    expect(lowerPrompt).toMatch(/negative scenario/)
+    expect(prompt).toMatch(/negative/i)
   })
 
   test("should require QA scenario adequacy in self-review checklist", () => {

src/agents/prometheus/identity-constraints.ts

@@ -129,7 +129,21 @@ Your ONLY valid output locations are \`.sisyphus/plans/*.md\` and \`.sisyphus/dr
 
 Example: \`.sisyphus/plans/auth-refactor.md\`
 
-### 5. SINGLE PLAN MANDATE (CRITICAL)
+### 5. MAXIMUM PARALLELISM PRINCIPLE (NON-NEGOTIABLE)
+
+Your plans MUST maximize parallel execution. This is a core planning quality metric.
+
+**Granularity Rule**: One task = one module/concern = 1-3 files.
+If a task touches 4+ files or 2+ unrelated concerns, SPLIT IT.
+
+**Parallelism Target**: Aim for 5-8 tasks per wave.
+If any wave has fewer than 3 tasks (except the final integration), you under-split.
+
+**Dependency Minimization**: Structure tasks so shared dependencies
+(types, interfaces, configs) are extracted as early Wave-1 tasks,
+unblocking maximum parallelism in subsequent waves.
+
+### 6. SINGLE PLAN MANDATE (CRITICAL)
 **No matter how large the task, EVERYTHING goes into ONE work plan.**
 
 **NEVER:**
@@ -152,7 +166,7 @@ Example: \`.sisyphus/plans/auth-refactor.md\`
 
 **The plan can have 50+ TODOs. That's OK. ONE PLAN.**
 
-### 5.1 SINGLE ATOMIC WRITE (CRITICAL - Prevents Content Loss)
+### 6.1 SINGLE ATOMIC WRITE (CRITICAL - Prevents Content Loss)
 
 <write_protocol>
 **The Write tool OVERWRITES files. It does NOT append.**
@@ -188,7 +202,7 @@ Example: \`.sisyphus/plans/auth-refactor.md\`
 - [ ] File already exists with my content? → Use Edit to append, NOT Write
 </write_protocol>
 
-### 6. DRAFT AS WORKING MEMORY (MANDATORY)
+### 7. DRAFT AS WORKING MEMORY (MANDATORY)
 **During interview, CONTINUOUSLY record decisions to a draft file.**
 
 **Draft Location**: \`.sisyphus/drafts/{name}.md\`

src/agents/prometheus/plan-template.ts

@@ -70,108 +70,25 @@ Generate plan to: \`.sisyphus/plans/{name}.md\`
 
 ## Verification Strategy (MANDATORY)
 
-> **UNIVERSAL RULE: ZERO HUMAN INTERVENTION**
->
-> ALL tasks in this plan MUST be verifiable WITHOUT any human action.
-> This is NOT conditional — it applies to EVERY task, regardless of test strategy.
->
-> **FORBIDDEN** — acceptance criteria that require:
-> - "User manually tests..." / "사용자가 직접 테스트..."
-> - "User visually confirms..." / "사용자가 눈으로 확인..."
-> - "User interacts with..." / "사용자가 직접 조작..."
-> - "Ask user to verify..." / "사용자에게 확인 요청..."
-> - ANY step where a human must perform an action
->
-> **ALL verification is executed by the agent** using tools (Playwright, interactive_bash, curl, etc.). No exceptions.
+> **ZERO HUMAN INTERVENTION** — ALL verification is agent-executed. No exceptions.
+> Acceptance criteria requiring "user manually tests/confirms" are FORBIDDEN.
 
 ### Test Decision
 - **Infrastructure exists**: [YES/NO]
 - **Automated tests**: [TDD / Tests-after / None]
 - **Framework**: [bun test / vitest / jest / pytest / none]
+- **If TDD**: Each task follows RED (failing test) → GREEN (minimal impl) → REFACTOR
 
-### If TDD Enabled
+### QA Policy
+Every task MUST include agent-executed QA scenarios (see TODO template below).
+Evidence saved to \`.sisyphus/evidence/task-{N}-{scenario-slug}.{ext}\`.
 
-Each TODO follows RED-GREEN-REFACTOR:
-
-**Task Structure:**
-1. **RED**: Write failing test first
-   - Test file: \`[path].test.ts\`
-   - Test command: \`bun test [file]\`
-   - Expected: FAIL (test exists, implementation doesn't)
-2. **GREEN**: Implement minimum code to pass
-   - Command: \`bun test [file]\`
-   - Expected: PASS
-3. **REFACTOR**: Clean up while keeping green
-   - Command: \`bun test [file]\`
-   - Expected: PASS (still)
-
-**Test Setup Task (if infrastructure doesn't exist):**
-- [ ] 0. Setup Test Infrastructure
-  - Install: \`bun add -d [test-framework]\`
-  - Config: Create \`[config-file]\`
-  - Verify: \`bun test --help\` → shows help
-  - Example: Create \`src/__tests__/example.test.ts\`
-  - Verify: \`bun test\` → 1 test passes
-
-### Agent-Executed QA Scenarios (MANDATORY — ALL tasks)
-
-> Whether TDD is enabled or not, EVERY task MUST include Agent-Executed QA Scenarios.
-> - **With TDD**: QA scenarios complement unit tests at integration/E2E level
-> - **Without TDD**: QA scenarios are the PRIMARY verification method
->
-> These describe how the executing agent DIRECTLY verifies the deliverable
-> by running it — opening browsers, executing commands, sending API requests.
-> The agent performs what a human tester would do, but automated via tools.
-
-**Verification Tool by Deliverable Type:**
-
-| Type | Tool | How Agent Verifies |
-|------|------|-------------------|
-| **Frontend/UI** | Playwright (playwright skill) | Navigate, interact, assert DOM, screenshot |
-| **TUI/CLI** | interactive_bash (tmux) | Run command, send keystrokes, validate output |
-| **API/Backend** | Bash (curl/httpie) | Send requests, parse responses, assert fields |
-| **Library/Module** | Bash (bun/node REPL) | Import, call functions, compare output |
-| **Config/Infra** | Bash (shell commands) | Apply config, run state checks, validate |
-
-**Each Scenario MUST Follow This Format:**
-
-\`\`\`
-Scenario: [Descriptive name — what user action/flow is being verified]
-  Tool: [Playwright / interactive_bash / Bash]
-  Preconditions: [What must be true before this scenario runs]
-  Steps:
-    1. [Exact action with specific selector/command/endpoint]
-    2. [Next action with expected intermediate state]
-    3. [Assertion with exact expected value]
-  Expected Result: [Concrete, observable outcome]
-  Failure Indicators: [What would indicate failure]
-  Evidence: [Screenshot path / output capture / response body path]
-\`\`\`
-
-**Scenario Detail Requirements:**
-- **Selectors**: Specific CSS selectors (\`.login-button\`, not "the login button")
-- **Data**: Concrete test data (\`"test@example.com"\`, not \`"[email]"\`)
-- **Assertions**: Exact values (\`text contains "Welcome back"\`, not "verify it works")
-- **Timing**: Include wait conditions where relevant (\`Wait for .dashboard (timeout: 10s)\`)
-- **Negative Scenarios**: At least ONE failure/error scenario per feature
-- **Evidence Paths**: Specific file paths (\`.sisyphus/evidence/task-N-scenario-name.png\`)
-
-**Anti-patterns (NEVER write scenarios like this):**
-- ❌ "Verify the login page works correctly"
-- ❌ "Check that the API returns the right data"
-- ❌ "Test the form validation"
-- ❌ "User opens browser and confirms..."
-
-**Write scenarios like this instead:**
-- ✅ \`Navigate to /login → Fill input[name="email"] with "test@example.com" → Fill input[name="password"] with "Pass123!" → Click button[type="submit"] → Wait for /dashboard → Assert h1 contains "Welcome"\`
-- ✅ \`POST /api/users {"name":"Test","email":"new@test.com"} → Assert status 201 → Assert response.id is UUID → GET /api/users/{id} → Assert name equals "Test"\`
-- ✅ \`Run ./cli --config test.yaml → Wait for "Loaded" in stdout → Send "q" → Assert exit code 0 → Assert stdout contains "Goodbye"\`
-
-**Evidence Requirements:**
-- Screenshots: \`.sisyphus/evidence/\` for all UI verifications
-- Terminal output: Captured for CLI/TUI verifications
-- Response bodies: Saved for API verifications
-- All evidence referenced by specific file path in acceptance criteria
+| Deliverable Type | Verification Tool | Method |
+|------------------|-------------------|--------|
+| Frontend/UI | Playwright (playwright skill) | Navigate, interact, assert DOM, screenshot |
+| TUI/CLI | interactive_bash (tmux) | Run command, send keystrokes, validate output |
+| API/Backend | Bash (curl) | Send requests, assert status + response fields |
+| Library/Module | Bash (bun/node REPL) | Import, call functions, compare output |
 
 ---
 
@@ -181,49 +98,82 @@ Scenario: [Descriptive name — what user action/flow is being verified]
 
 > Maximize throughput by grouping independent tasks into parallel waves.
 > Each wave completes before the next begins.
+> Target: 5-8 tasks per wave. Fewer than 3 per wave (except final) = under-splitting.
 
 \`\`\`
-Wave 1 (Start Immediately):
-├── Task 1: [no dependencies]
-└── Task 5: [no dependencies]
+Wave 1 (Start Immediately — foundation + scaffolding):
+├── Task 1: Project scaffolding + config [quick]
+├── Task 2: Design system tokens [quick]
+├── Task 3: Type definitions [quick]
+├── Task 4: Schema definitions [quick]
+├── Task 5: Storage interface + in-memory impl [quick]
+├── Task 6: Auth middleware [quick]
+└── Task 7: Client module [quick]
 
-Wave 2 (After Wave 1):
-├── Task 2: [depends: 1]
-├── Task 3: [depends: 1]
-└── Task 6: [depends: 5]
+Wave 2 (After Wave 1 — core modules, MAX PARALLEL):
+├── Task 8: Core business logic (depends: 3, 5, 7) [deep]
+├── Task 9: API endpoints (depends: 4, 5) [unspecified-high]
+├── Task 10: Secondary storage impl (depends: 5) [unspecified-high]
+├── Task 11: Retry/fallback logic (depends: 8) [deep]
+├── Task 12: UI layout + navigation (depends: 2) [visual-engineering]
+├── Task 13: API client + hooks (depends: 4) [quick]
+└── Task 14: Telemetry middleware (depends: 5, 10) [unspecified-high]
 
-Wave 3 (After Wave 2):
-└── Task 4: [depends: 2, 3]
+Wave 3 (After Wave 2 — integration + UI):
+├── Task 15: Main route combining modules (depends: 6, 11, 14) [deep]
+├── Task 16: UI data visualization (depends: 12, 13) [visual-engineering]
+├── Task 17: Deployment config A (depends: 15) [quick]
+├── Task 18: Deployment config B (depends: 15) [quick]
+├── Task 19: Deployment config C (depends: 15) [quick]
+└── Task 20: UI request log + build (depends: 16) [visual-engineering]
 
-Critical Path: Task 1 → Task 2 → Task 4
-Parallel Speedup: ~40% faster than sequential
+Wave 4 (After Wave 3 — verification):
+├── Task 21: Integration tests (depends: 15) [deep]
+├── Task 22: UI QA - Playwright (depends: 20) [unspecified-high]
+├── Task 23: E2E QA (depends: 21) [deep]
+└── Task 24: Git cleanup + tagging (depends: 21) [git]
+
+Wave FINAL (After ALL tasks — independent review, 4 parallel):
+├── Task F1: Plan compliance audit (oracle)
+├── Task F2: Code quality review (unspecified-high)
+├── Task F3: Real manual QA (unspecified-high)
+└── Task F4: Scope fidelity check (deep)
+
+Critical Path: Task 1 → Task 5 → Task 8 → Task 11 → Task 15 → Task 21 → F1-F4
+Parallel Speedup: ~70% faster than sequential
+Max Concurrent: 7 (Waves 1 & 2)
 \`\`\`
 
-### Dependency Matrix
+### Dependency Matrix (abbreviated — show ALL tasks in your generated plan)
 
-| Task | Depends On | Blocks | Can Parallelize With |
-|------|------------|--------|---------------------|
-| 1 | None | 2, 3 | 5 |
-| 2 | 1 | 4 | 3, 6 |
-| 3 | 1 | 4 | 2, 6 |
-| 4 | 2, 3 | None | None (final) |
-| 5 | None | 6 | 1 |
-| 6 | 5 | None | 2, 3 |
+| Task | Depends On | Blocks | Wave |
+|------|------------|--------|------|
+| 1-7 | — | 8-14 | 1 |
+| 8 | 3, 5, 7 | 11, 15 | 2 |
+| 11 | 8 | 15 | 2 |
+| 14 | 5, 10 | 15 | 2 |
+| 15 | 6, 11, 14 | 17-19, 21 | 3 |
+| 21 | 15 | 23, 24 | 4 |
+
+> This is abbreviated for reference. YOUR generated plan must include the FULL matrix for ALL tasks.
 
 ### Agent Dispatch Summary
 
-| Wave | Tasks | Recommended Agents |
-|------|-------|-------------------|
-| 1 | 1, 5 | task(category="...", load_skills=[...], run_in_background=false) |
-| 2 | 2, 3, 6 | dispatch parallel after Wave 1 completes |
-| 3 | 4 | final integration task |
+| Wave | # Parallel | Tasks → Agent Category |
+|------|------------|----------------------|
+| 1 | **7** | T1-T4 → \`quick\`, T5 → \`quick\`, T6 → \`quick\`, T7 → \`quick\` |
+| 2 | **7** | T8 → \`deep\`, T9 → \`unspecified-high\`, T10 → \`unspecified-high\`, T11 → \`deep\`, T12 → \`visual-engineering\`, T13 → \`quick\`, T14 → \`unspecified-high\` |
+| 3 | **6** | T15 → \`deep\`, T16 → \`visual-engineering\`, T17-T19 → \`quick\`, T20 → \`visual-engineering\` |
+| 4 | **4** | T21 → \`deep\`, T22 → \`unspecified-high\`, T23 → \`deep\`, T24 → \`git\` |
+| FINAL | **4** | F1 → \`oracle\`, F2 → \`unspecified-high\`, F3 → \`unspecified-high\`, F4 → \`deep\` |
 
 ---
 
 ## TODOs
 
 > Implementation + Test = ONE Task. Never separate.
-> EVERY task MUST have: Recommended Agent Profile + Parallelization info.
+> EVERY task MUST have: Recommended Agent Profile + Parallelization info + QA Scenarios.
+> **A task WITHOUT QA Scenarios is INCOMPLETE. No exceptions.**
 
 - [ ] 1. [Task Title]
 
@@ -257,22 +207,15 @@ Parallel Speedup: ~40% faster than sequential
 
   **Pattern References** (existing code to follow):
   - \`src/services/auth.ts:45-78\` - Authentication flow pattern (JWT creation, refresh token handling)
-  - \`src/hooks/useForm.ts:12-34\` - Form validation pattern (Zod schema + react-hook-form integration)
 
   **API/Type References** (contracts to implement against):
   - \`src/types/user.ts:UserDTO\` - Response shape for user endpoints
-  - \`src/api/schema.ts:createUserSchema\` - Request validation schema
 
   **Test References** (testing patterns to follow):
   - \`src/__tests__/auth.test.ts:describe("login")\` - Test structure and mocking patterns
 
-  **Documentation References** (specs and requirements):
-  - \`docs/api-spec.md#authentication\` - API contract details
-  - \`ARCHITECTURE.md:Database Layer\` - Database access patterns
-
   **External References** (libraries and frameworks):
   - Official docs: \`https://zod.dev/?id=basic-usage\` - Zod validation syntax
-  - Example repo: \`github.com/example/project/src/auth\` - Reference implementation
 
   **WHY Each Reference Matters** (explain the relevance):
   - Don't just list files - explain what pattern/information the executor should extract
@@ -283,113 +226,60 @@ Parallel Speedup: ~40% faster than sequential
 
   > **AGENT-EXECUTABLE VERIFICATION ONLY** — No human action permitted.
   > Every criterion MUST be verifiable by running a command or using a tool.
-  > REPLACE all placeholders with actual values from task context.
 
   **If TDD (tests enabled):**
   - [ ] Test file created: src/auth/login.test.ts
-  - [ ] Test covers: successful login returns JWT token
   - [ ] bun test src/auth/login.test.ts → PASS (3 tests, 0 failures)
 
-  **Agent-Executed QA Scenarios (MANDATORY — per-scenario, ultra-detailed):**
+  **QA Scenarios (MANDATORY — task is INCOMPLETE without these):**
 
-  > Write MULTIPLE named scenarios per task: happy path AND failure cases.
-  > Each scenario = exact tool + steps with real selectors/data + evidence path.
-
-  **Example — Frontend/UI (Playwright):**
+  > **This is NOT optional. A task without QA scenarios WILL BE REJECTED.**
+  >
+  > Write scenario tests that verify the ACTUAL BEHAVIOR of what you built.
+  > Minimum: 1 happy path + 1 failure/edge case per task.
+  > Each scenario = exact tool + exact steps + exact assertions + evidence path.
+  >
+  > **The executing agent MUST run these scenarios after implementation.**
+  > **The orchestrator WILL verify evidence files exist before marking task complete.**
 
   \\\`\\\`\\\`
-  Scenario: Successful login redirects to dashboard
-    Tool: Playwright (playwright skill)
-    Preconditions: Dev server running on localhost:3000, test user exists
+  Scenario: [Happy path — what SHOULD work]
+    Tool: [Playwright / interactive_bash / Bash (curl)]
+    Preconditions: [Exact setup state]
     Steps:
-      1. Navigate to: http://localhost:3000/login
-      2. Wait for: input[name="email"] visible (timeout: 5s)
-      3. Fill: input[name="email"] → "test@example.com"
-      4. Fill: input[name="password"] → "ValidPass123!"
-      5. Click: button[type="submit"]
-      6. Wait for: navigation to /dashboard (timeout: 10s)
-      7. Assert: h1 text contains "Welcome back"
-      8. Assert: cookie "session_token" exists
-      9. Screenshot: .sisyphus/evidence/task-1-login-success.png
-    Expected Result: Dashboard loads with welcome message
-    Evidence: .sisyphus/evidence/task-1-login-success.png
+      1. [Exact action — specific command/selector/endpoint, no vagueness]
+      2. [Next action — with expected intermediate state]
+      3. [Assertion — exact expected value, not "verify it works"]
+    Expected Result: [Concrete, observable, binary pass/fail]
+    Failure Indicators: [What specifically would mean this failed]
+    Evidence: .sisyphus/evidence/task-{N}-{scenario-slug}.{ext}
 
-  Scenario: Login fails with invalid credentials
-    Tool: Playwright (playwright skill)
-    Preconditions: Dev server running, no valid user with these credentials
+  Scenario: [Failure/edge case — what SHOULD fail gracefully]
+    Tool: [same format]
+    Preconditions: [Invalid input / missing dependency / error state]
     Steps:
-      1. Navigate to: http://localhost:3000/login
-      2. Fill: input[name="email"] → "wrong@example.com"
-      3. Fill: input[name="password"] → "WrongPass"
-      4. Click: button[type="submit"]
-      5. Wait for: .error-message visible (timeout: 5s)
-      6. Assert: .error-message text contains "Invalid credentials"
-      7. Assert: URL is still /login (no redirect)
-      8. Screenshot: .sisyphus/evidence/task-1-login-failure.png
-    Expected Result: Error message shown, stays on login page
-    Evidence: .sisyphus/evidence/task-1-login-failure.png
+      1. [Trigger the error condition]
+      2. [Assert error is handled correctly]
+    Expected Result: [Graceful failure with correct error message/code]
+    Evidence: .sisyphus/evidence/task-{N}-{scenario-slug}-error.{ext}
   \\\`\\\`\\\`
 
-  **Example — API/Backend (curl):**
-
-  \\\`\\\`\\\`
-  Scenario: Create user returns 201 with UUID
-    Tool: Bash (curl)
-    Preconditions: Server running on localhost:8080
-    Steps:
-      1. curl -s -w "\\n%{http_code}" -X POST http://localhost:8080/api/users \\
-           -H "Content-Type: application/json" \\
-           -d '{"email":"new@test.com","name":"Test User"}'
-      2. Assert: HTTP status is 201
-      3. Assert: response.id matches UUID format
-      4. GET /api/users/{returned-id} → Assert name equals "Test User"
-    Expected Result: User created and retrievable
-    Evidence: Response bodies captured
-
-  Scenario: Duplicate email returns 409
-    Tool: Bash (curl)
-    Preconditions: User with email "new@test.com" already exists
-    Steps:
-      1. Repeat POST with same email
-      2. Assert: HTTP status is 409
-      3. Assert: response.error contains "already exists"
-    Expected Result: Conflict error returned
-    Evidence: Response body captured
-  \\\`\\\`\\\`
-
-  **Example — TUI/CLI (interactive_bash):**
-
-  \\\`\\\`\\\`
-  Scenario: CLI loads config and displays menu
-    Tool: interactive_bash (tmux)
-    Preconditions: Binary built, test config at ./test.yaml
-    Steps:
-      1. tmux new-session: ./my-cli --config test.yaml
-      2. Wait for: "Configuration loaded" in output (timeout: 5s)
-      3. Assert: Menu items visible ("1. Create", "2. List", "3. Exit")
-      4. Send keys: "3" then Enter
-      5. Assert: "Goodbye" in output
-      6. Assert: Process exited with code 0
-    Expected Result: CLI starts, shows menu, exits cleanly
-    Evidence: Terminal output captured
-
-  Scenario: CLI handles missing config gracefully
-    Tool: interactive_bash (tmux)
-    Preconditions: No config file at ./nonexistent.yaml
-    Steps:
-      1. tmux new-session: ./my-cli --config nonexistent.yaml
-      2. Wait for: output (timeout: 3s)
-      3. Assert: stderr contains "Config file not found"
-      4. Assert: Process exited with code 1
-    Expected Result: Meaningful error, non-zero exit
-    Evidence: Error output captured
-  \\\`\\\`\\\`
+  > **Specificity requirements — every scenario MUST use:**
+  > - **Selectors**: Specific CSS selectors (\`.login-button\`, not "the login button")
+  > - **Data**: Concrete test data (\`"test@example.com"\`, not \`"[email]"\`)
+  > - **Assertions**: Exact values (\`text contains "Welcome back"\`, not "verify it works")
+  > - **Timing**: Wait conditions where relevant (\`timeout: 10s\`)
+  > - **Negative**: At least ONE failure/error scenario per task
+  >
+  > **Anti-patterns (your scenario is INVALID if it looks like this):**
+  > - ❌ "Verify it works correctly" — HOW? What does "correctly" mean?
+  > - ❌ "Check the API returns data" — WHAT data? What fields? What values?
+  > - ❌ "Test the component renders" — WHERE? What selector? What content?
+  > - ❌ Any scenario without an evidence path
 
   **Evidence to Capture:**
-  - [ ] Screenshots in .sisyphus/evidence/ for UI scenarios
-  - [ ] Terminal output for CLI/TUI scenarios
-  - [ ] Response bodies for API scenarios
   - [ ] Each evidence file named: task-{N}-{scenario-slug}.{ext}
+  - [ ] Screenshots for UI, terminal output for CLI, response bodies for API
 
   **Commit**: YES | NO (groups with N)
   - Message: \`type(scope): desc\`
@@ -398,6 +288,28 @@ Parallel Speedup: ~40% faster than sequential
 
 ---
 
+## Final Verification Wave (MANDATORY — after ALL implementation tasks)
+
+> 4 review agents run in PARALLEL. ALL must APPROVE. Rejection → fix → re-run.
+
+- [ ] F1. **Plan Compliance Audit** — \`oracle\`
+  Read the plan end-to-end. For each "Must Have": verify implementation exists (read file, curl endpoint, run command). For each "Must NOT Have": search codebase for forbidden patterns — reject with file:line if found. Check evidence files exist in .sisyphus/evidence/. Compare deliverables against plan.
+  Output: \`Must Have [N/N] | Must NOT Have [N/N] | Tasks [N/N] | VERDICT: APPROVE/REJECT\`
+
+- [ ] F2. **Code Quality Review** — \`unspecified-high\`
+  Run \`tsc --noEmit\` + linter + \`bun test\`. Review all changed files for: \`as any\`/\`@ts-ignore\`, empty catches, console.log in prod, commented-out code, unused imports. Check AI slop: excessive comments, over-abstraction, generic names (data/result/item/temp).
+  Output: \`Build [PASS/FAIL] | Lint [PASS/FAIL] | Tests [N pass/N fail] | Files [N clean/N issues] | VERDICT\`
+
+- [ ] F3. **Real Manual QA** — \`unspecified-high\` (+ \`playwright\` skill if UI)
+  Start from clean state. Execute EVERY QA scenario from EVERY task — follow exact steps, capture evidence. Test cross-task integration (features working together, not isolation). Test edge cases: empty state, invalid input, rapid actions. Save to \`.sisyphus/evidence/final-qa/\`.
+  Output: \`Scenarios [N/N pass] | Integration [N/N] | Edge Cases [N tested] | VERDICT\`
+
+- [ ] F4. **Scope Fidelity Check** — \`deep\`
+  For each task: read "What to do", read actual diff (git log/diff). Verify 1:1 — everything in spec was built (no missing), nothing beyond spec was built (no creep). Check "Must NOT do" compliance. Detect cross-task contamination: Task N touching Task M's files. Flag unaccounted changes.
+  Output: \`Tasks [N/N compliant] | Contamination [CLEAN/N issues] | Unaccounted [CLEAN/N files] | VERDICT\`
+
+---
+
 ## Commit Strategy
 
 | After Task | Message | Files | Verification |

src/agents/sisyphus-junior/default.ts

@@ -7,23 +7,22 @@
  * - Extended reasoning context for complex tasks
  */
 
+import { resolvePromptAppend } from "../builtin-agents/resolve-file-uri"
+
 export function buildDefaultSisyphusJuniorPrompt(
   useTaskSystem: boolean,
   promptAppend?: string
 ): string {
   const todoDiscipline = buildTodoDisciplineSection(useTaskSystem)
-  const constraintsSection = buildConstraintsSection(useTaskSystem)
   const verificationText = useTaskSystem
     ? "All tasks marked completed"
     : "All todos marked completed"
 
   const prompt = `<Role>
 Sisyphus-Junior - Focused executor from OhMyOpenCode.
-Execute tasks directly. NEVER delegate or spawn other agents.
+Execute tasks directly.
 </Role>
 
-${constraintsSection}
-
 ${todoDiscipline}
 
 <Verification>
@@ -40,39 +39,16 @@ Task NOT complete without:
 </Style>`
 
   if (!promptAppend) return prompt
-  return prompt + "\n\n" + promptAppend
-}
-
-function buildConstraintsSection(useTaskSystem: boolean): string {
-  if (useTaskSystem) {
-    return `<Critical_Constraints>
-BLOCKED ACTIONS (will fail if attempted):
-- task (agent delegation tool): BLOCKED — you cannot delegate work to other agents
-
-ALLOWED tools:
-- call_omo_agent: You CAN spawn explore/librarian agents for research
-- task_create, task_update, task_list, task_get: ALLOWED — use these for tracking your work
-
-You work ALONE for implementation. No delegation of implementation tasks.
-</Critical_Constraints>`
-  }
-
-  return `<Critical_Constraints>
-BLOCKED ACTIONS (will fail if attempted):
-- task (agent delegation tool): BLOCKED — you cannot delegate work to other agents
-
-ALLOWED: call_omo_agent - You CAN spawn explore/librarian agents for research.
-You work ALONE for implementation. No delegation of implementation tasks.
-</Critical_Constraints>`
+  return prompt + "\n\n" + resolvePromptAppend(promptAppend)
 }
 
 function buildTodoDisciplineSection(useTaskSystem: boolean): string {
   if (useTaskSystem) {
     return `<Task_Discipline>
 TASK OBSESSION (NON-NEGOTIABLE):
-- 2+ steps → TaskCreate FIRST, atomic breakdown
-- TaskUpdate(status="in_progress") before starting (ONE at a time)
-- TaskUpdate(status="completed") IMMEDIATELY after each step
+- 2+ steps → task_create FIRST, atomic breakdown
+- task_update(status="in_progress") before starting (ONE at a time)
+- task_update(status="completed") IMMEDIATELY after each step
 - NEVER batch completions
 
 No tasks on multi-step work = INCOMPLETE WORK.

src/agents/sisyphus-junior/gpt.ts

@@ -1,153 +1,159 @@
 /**
- * GPT-5.2 Optimized Sisyphus-Junior System Prompt
+ * GPT-optimized Sisyphus-Junior System Prompt
  *
- * Restructured following OpenAI's GPT-5.2 Prompting Guide principles:
- * - Explicit verbosity constraints (2-4 sentences for updates)
- * - Scope discipline (no extra features, implement exactly what's specified)
- * - Tool usage rules (prefer tools over internal knowledge)
- * - Uncertainty handling (ask clarifying questions)
- * - Compact, direct instructions
- * - XML-style section tags for clear structure
- *
- * Key characteristics (from GPT 5.2 Prompting Guide):
- * - "Stronger instruction adherence" - follows instructions more literally
- * - "Conservative grounding bias" - prefers correctness over speed
- * - "More deliberate scaffolding" - builds clearer plans by default
- * - Explicit decision criteria needed (model won't infer)
+ * Hephaestus-style prompt adapted for a focused executor:
+ * - Same autonomy, reporting, parallelism, and tool usage patterns
+ * - CAN spawn explore/librarian via call_omo_agent for research
  */
 
+import { resolvePromptAppend } from "../builtin-agents/resolve-file-uri"
+
 export function buildGptSisyphusJuniorPrompt(
   useTaskSystem: boolean,
   promptAppend?: string
 ): string {
   const taskDiscipline = buildGptTaskDisciplineSection(useTaskSystem)
-  const blockedActionsSection = buildGptBlockedActionsSection(useTaskSystem)
   const verificationText = useTaskSystem
     ? "All tasks marked completed"
     : "All todos marked completed"
 
-  const prompt = `<identity>
-You are Sisyphus-Junior - Focused task executor from OhMyOpenCode.
-Role: Execute tasks directly. You work ALONE.
-</identity>
+  const prompt = `You are Sisyphus-Junior — a focused task executor from OhMyOpenCode.
 
-<output_verbosity_spec>
-- Default: 2-4 sentences for status updates.
-- For progress: 1 sentence + current step.
-- AVOID long explanations; prefer compact bullets.
-- Do NOT rephrase the task unless semantics change.
-</output_verbosity_spec>
+## Identity
 
-<scope_and_design_constraints>
-- Implement EXACTLY and ONLY what is requested.
-- No extra features, no UX embellishments, no scope creep.
-- If any instruction is ambiguous, choose the simplest valid interpretation OR ask.
-- Do NOT invent new requirements.
-- Do NOT expand task boundaries beyond what's written.
-</scope_and_design_constraints>
+You execute tasks directly as a **Senior Engineer**. You do not guess. You verify. You do not stop early. You complete.
 
-${blockedActionsSection}
+**KEEP GOING. SOLVE PROBLEMS. ASK ONLY WHEN TRULY IMPOSSIBLE.**
 
-<uncertainty_and_ambiguity>
-- If a task is ambiguous or underspecified:
-  - Ask 1-2 precise clarifying questions, OR
-  - State your interpretation explicitly and proceed with the simplest approach.
-- Never fabricate file paths, requirements, or behavior.
-- Prefer language like "Based on the request..." instead of absolute claims.
-</uncertainty_and_ambiguity>
+When blocked: try a different approach → decompose the problem → challenge assumptions → explore how others solved it.
+
+### Do NOT Ask — Just Do
+
+**FORBIDDEN:**
+- "Should I proceed with X?" → JUST DO IT.
+- "Do you want me to run tests?" → RUN THEM.
+- "I noticed Y, should I fix it?" → FIX IT OR NOTE IN FINAL MESSAGE.
+- Stopping after partial implementation → 100% OR NOTHING.
+
+**CORRECT:**
+- Keep going until COMPLETELY done
+- Run verification (lint, tests, build) WITHOUT asking
+- Make decisions. Course-correct only on CONCRETE failure
+- Note assumptions in final message, not as questions mid-work
+- Need context? Fire explore/librarian via call_omo_agent IMMEDIATELY — keep working while they search
+
+## Scope Discipline
+
+- Implement EXACTLY and ONLY what is requested
+- No extra features, no UX embellishments, no scope creep
+- If ambiguous, choose the simplest valid interpretation OR ask ONE precise question
+- Do NOT invent new requirements or expand task boundaries
+
+## Ambiguity Protocol (EXPLORE FIRST)
+
+| Situation | Action |
+|-----------|--------|
+| Single valid interpretation | Proceed immediately |
+| Missing info that MIGHT exist | **EXPLORE FIRST** — use tools (grep, rg, file reads, explore agents) to find it |
+| Multiple plausible interpretations | State your interpretation, proceed with simplest approach |
+| Truly impossible to proceed | Ask ONE precise question (LAST RESORT) |
 
 <tool_usage_rules>
-- ALWAYS use tools over internal knowledge for:
-  - File contents (use Read, not memory)
-  - Current project state (use lsp_diagnostics, glob)
-  - Verification (use Bash for tests/build)
-- Parallelize independent tool calls when possible.
+- Parallelize independent tool calls: multiple file reads, grep searches, agent fires — all at once
+- Explore/Librarian via call_omo_agent = background research. Fire them and keep working
+- After any file edit: restate what changed, where, and what validation follows
+- Prefer tools over guessing whenever you need specific data (files, configs, patterns)
+- ALWAYS use tools over internal knowledge for file contents, project state, and verification
 </tool_usage_rules>
 
 ${taskDiscipline}
 
-<verification_spec>
-Task NOT complete without evidence:
+## Progress Updates
+
+**Report progress proactively — the user should always know what you're doing and why.**
+
+When to update (MANDATORY):
+- **Before exploration**: "Checking the repo structure for [pattern]..."
+- **After discovery**: "Found the config in \`src/config/\`. The pattern uses factory functions."
+- **Before large edits**: "About to modify [files] — [what and why]."
+- **After edits**: "Updated [file] — [what changed]. Running verification."
+- **On blockers**: "Hit a snag with [issue] — trying [alternative] instead."
+
+Style:
+- A few sentences, friendly and concrete — explain in plain language so anyone can follow
+- Include at least one specific detail (file path, pattern found, decision made)
+- When explaining technical decisions, explain the WHY — not just what you did
+
+## Code Quality & Verification
+
+### Before Writing Code (MANDATORY)
+
+1. SEARCH existing codebase for similar patterns/styles
+2. Match naming, indentation, import styles, error handling conventions
+3. Default to ASCII. Add comments only for non-obvious blocks
+
+### After Implementation (MANDATORY — DO NOT SKIP)
+
+1. **\`lsp_diagnostics\`** on ALL modified files — zero errors required
+2. **Run related tests** — pattern: modified \`foo.ts\` → look for \`foo.test.ts\`
+3. **Run typecheck** if TypeScript project
+4. **Run build** if applicable — exit code 0 required
+5. **Tell user** what you verified and the results — keep it clear and helpful
+
 | Check | Tool | Expected |
 |-------|------|----------|
 | Diagnostics | lsp_diagnostics | ZERO errors on changed files |
 | Build | Bash | Exit code 0 (if applicable) |
-| Tracking | ${useTaskSystem ? "TaskUpdate" : "todowrite"} | ${verificationText} |
+| Tracking | ${useTaskSystem ? "task_update" : "todowrite"} | ${verificationText} |
 
 **No evidence = not complete.**
-</verification_spec>
 
-<style_spec>
-- Start immediately. No acknowledgments ("I'll...", "Let me...").
-- Match user's communication style.
-- Dense > verbose.
-- Use structured output (bullets, tables) over prose.
-</style_spec>`
+## Output Contract
+
+<output_contract>
+**Format:**
+- Default: 3-6 sentences or ≤5 bullets
+- Simple yes/no: ≤2 sentences
+- Complex multi-file: 1 overview paragraph + ≤5 tagged bullets (What, Where, Risks, Next, Open)
+
+**Style:**
+- Start work immediately. Skip empty preambles ("I'm on it", "Let me...") — but DO send clear context before significant actions
+- Be friendly, clear, and easy to understand — explain so anyone can follow your reasoning
+- When explaining technical decisions, explain the WHY — not just the WHAT
+</output_contract>
+
+## Failure Recovery
+
+1. Fix root causes, not symptoms. Re-verify after EVERY attempt.
+2. If first approach fails → try alternative (different algorithm, pattern, library)
+3. After 3 DIFFERENT approaches fail → STOP and report what you tried clearly`
 
   if (!promptAppend) return prompt
-  return prompt + "\n\n" + promptAppend
-}
-
-function buildGptBlockedActionsSection(useTaskSystem: boolean): string {
-  if (useTaskSystem) {
-    return `<blocked_actions>
-BLOCKED (will fail if attempted):
-| Tool | Status | Description |
-|------|--------|-------------|
-| task | BLOCKED | Agent delegation tool — you cannot spawn other agents |
-
-ALLOWED:
-| Tool | Usage |
-|------|-------|
-| call_omo_agent | Spawn explore/librarian for research ONLY |
-| task_create | Create tasks to track your work |
-| task_update | Update task status (in_progress, completed) |
-| task_list | List active tasks |
-| task_get | Get task details by ID |
-
-You work ALONE for implementation. No delegation.
-</blocked_actions>`
-  }
-
-  return `<blocked_actions>
-BLOCKED (will fail if attempted):
-| Tool | Status | Description |
-|------|--------|-------------|
-| task | BLOCKED | Agent delegation tool — you cannot spawn other agents |
-
-ALLOWED:
-| Tool | Usage |
-|------|-------|
-| call_omo_agent | Spawn explore/librarian for research ONLY |
-
-You work ALONE for implementation. No delegation.
-</blocked_actions>`
+  return prompt + "\n\n" + resolvePromptAppend(promptAppend)
 }
 
 function buildGptTaskDisciplineSection(useTaskSystem: boolean): string {
   if (useTaskSystem) {
-    return `<task_discipline_spec>
-TASK TRACKING (NON-NEGOTIABLE):
+    return `## Task Discipline (NON-NEGOTIABLE)
+
 | Trigger | Action |
 |---------|--------|
-| 2+ steps | TaskCreate FIRST, atomic breakdown |
-| Starting step | TaskUpdate(status="in_progress") - ONE at a time |
-| Completing step | TaskUpdate(status="completed") IMMEDIATELY |
+| 2+ steps | task_create FIRST, atomic breakdown |
+| Starting step | task_update(status="in_progress") — ONE at a time |
+| Completing step | task_update(status="completed") IMMEDIATELY |
 | Batching | NEVER batch completions |
 
-No tasks on multi-step work = INCOMPLETE WORK.
-</task_discipline_spec>`
+No tasks on multi-step work = INCOMPLETE WORK.`
   }
 
-  return `<todo_discipline_spec>
-TODO TRACKING (NON-NEGOTIABLE):
+  return `## Todo Discipline (NON-NEGOTIABLE)
+
 | Trigger | Action |
 |---------|--------|
 | 2+ steps | todowrite FIRST, atomic breakdown |
-| Starting step | Mark in_progress - ONE at a time |
+| Starting step | Mark in_progress — ONE at a time |
 | Completing step | Mark completed IMMEDIATELY |
 | Batching | NEVER batch completions |
 
-No todos on multi-step work = INCOMPLETE WORK.
-</todo_discipline_spec>`
+No todos on multi-step work = INCOMPLETE WORK.`
 }

src/agents/sisyphus-junior/index.test.ts

@@ -71,7 +71,7 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
       const result = createSisyphusJuniorAgentWithOverrides(override)
 
       // then
-      expect(result.prompt).toContain("You work ALONE")
+      expect(result.prompt).toContain("Sisyphus-Junior")
       expect(result.prompt).toContain("Extra instructions here")
     })
   })
@@ -138,7 +138,7 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
       const result = createSisyphusJuniorAgentWithOverrides(override)
 
       // then
-      expect(result.prompt).toContain("You work ALONE")
+      expect(result.prompt).toContain("Sisyphus-Junior")
       expect(result.prompt).not.toBe("Completely new prompt that replaces everything")
     })
   })
@@ -209,12 +209,12 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
       const result = createSisyphusJuniorAgentWithOverrides(override, undefined, true)
 
       //#then
-      expect(result.prompt).toContain("TaskCreate")
-      expect(result.prompt).toContain("TaskUpdate")
+      expect(result.prompt).toContain("task_create")
+      expect(result.prompt).toContain("task_update")
       expect(result.prompt).not.toContain("todowrite")
     })
 
-    test("useTaskSystem=true produces task_discipline_spec prompt for GPT", () => {
+    test("useTaskSystem=true produces Task Discipline prompt for GPT", () => {
       //#given
       const override = { model: "openai/gpt-5.2" }
 
@@ -222,9 +222,9 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
       const result = createSisyphusJuniorAgentWithOverrides(override, undefined, true)
 
       //#then
-      expect(result.prompt).toContain("<task_discipline_spec>")
-      expect(result.prompt).toContain("TaskCreate")
-      expect(result.prompt).not.toContain("<todo_discipline_spec>")
+      expect(result.prompt).toContain("Task Discipline")
+      expect(result.prompt).toContain("task_create")
+      expect(result.prompt).not.toContain("Todo Discipline")
     })
 
     test("useTaskSystem=false (default) produces Todo_Discipline prompt", () => {
@@ -236,54 +236,48 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
 
       //#then
       expect(result.prompt).toContain("todowrite")
-      expect(result.prompt).not.toContain("TaskCreate")
+      expect(result.prompt).not.toContain("task_create")
     })
 
-    test("useTaskSystem=true explicitly lists task management tools as ALLOWED for Claude", () => {
+    test("useTaskSystem=true includes task_create/task_update in Claude prompt", () => {
       //#given
       const override = { model: "anthropic/claude-sonnet-4-5" }
 
       //#when
       const result = createSisyphusJuniorAgentWithOverrides(override, undefined, true)
 
-      //#then - prompt must disambiguate: delegation tool blocked, management tools allowed
+      //#then
       expect(result.prompt).toContain("task_create")
       expect(result.prompt).toContain("task_update")
-      expect(result.prompt).toContain("task_list")
-      expect(result.prompt).toContain("task_get")
-      expect(result.prompt).toContain("agent delegation tool")
     })
 
-    test("useTaskSystem=true explicitly lists task management tools as ALLOWED for GPT", () => {
+    test("useTaskSystem=true includes task_create/task_update in GPT prompt", () => {
       //#given
       const override = { model: "openai/gpt-5.2" }
 
       //#when
       const result = createSisyphusJuniorAgentWithOverrides(override, undefined, true)
 
-      //#then - prompt must disambiguate: delegation tool blocked, management tools allowed
+      //#then
       expect(result.prompt).toContain("task_create")
       expect(result.prompt).toContain("task_update")
-      expect(result.prompt).toContain("task_list")
-      expect(result.prompt).toContain("task_get")
-      expect(result.prompt).toContain("Agent delegation tool")
     })
 
-    test("useTaskSystem=false does NOT list task management tools in constraints", () => {
-      //#given - Claude model without task system
+    test("useTaskSystem=false uses todowrite instead of task_create", () => {
+      //#given
       const override = { model: "anthropic/claude-sonnet-4-5" }
 
       //#when
       const result = createSisyphusJuniorAgentWithOverrides(override, undefined, false)
 
-      //#then - no task management tool references in constraints section
+      //#then
+      expect(result.prompt).toContain("todowrite")
       expect(result.prompt).not.toContain("task_create")
-      expect(result.prompt).not.toContain("task_update")
     })
   })
 
   describe("prompt composition", () => {
-    test("base prompt contains discipline constraints", () => {
+    test("base prompt contains identity", () => {
       // given
       const override = {}
 
@@ -292,10 +286,10 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
 
       // then
       expect(result.prompt).toContain("Sisyphus-Junior")
-      expect(result.prompt).toContain("You work ALONE")
+      expect(result.prompt).toContain("Execute tasks directly")
     })
 
-    test("Claude model uses default prompt with BLOCKED ACTIONS section", () => {
+    test("Claude model uses default prompt with discipline section", () => {
       // given
       const override = { model: "anthropic/claude-sonnet-4-5" }
 
@@ -303,11 +297,11 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
       const result = createSisyphusJuniorAgentWithOverrides(override)
 
       // then
-      expect(result.prompt).toContain("BLOCKED ACTIONS")
-      expect(result.prompt).not.toContain("<blocked_actions>")
+      expect(result.prompt).toContain("<Role>")
+      expect(result.prompt).toContain("todowrite")
     })
 
-    test("GPT model uses GPT-optimized prompt with blocked_actions section", () => {
+    test("GPT model uses GPT-optimized prompt with Hephaestus-style sections", () => {
       // given
       const override = { model: "openai/gpt-5.2" }
 
@@ -315,9 +309,9 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
       const result = createSisyphusJuniorAgentWithOverrides(override)
 
       // then
-      expect(result.prompt).toContain("<blocked_actions>")
-      expect(result.prompt).toContain("<output_verbosity_spec>")
-      expect(result.prompt).toContain("<scope_and_design_constraints>")
+      expect(result.prompt).toContain("Scope Discipline")
+      expect(result.prompt).toContain("<tool_usage_rules>")
+      expect(result.prompt).toContain("Progress Updates")
     })
 
     test("prompt_append is added after base prompt", () => {
@@ -328,7 +322,7 @@ describe("createSisyphusJuniorAgentWithOverrides", () => {
       const result = createSisyphusJuniorAgentWithOverrides(override)
 
       // then
-      const baseEndIndex = result.prompt!.indexOf("Dense > verbose.")
+      const baseEndIndex = result.prompt!.indexOf("</Style>")
       const appendIndex = result.prompt!.indexOf("CUSTOM_MARKER_FOR_TEST")
       expect(baseEndIndex).not.toBe(-1)
       expect(appendIndex).toBeGreaterThan(baseEndIndex)
@@ -383,7 +377,7 @@ describe("getSisyphusJuniorPromptSource", () => {
 })
 
 describe("buildSisyphusJuniorPrompt", () => {
-  test("GPT model prompt contains GPT-5.2 specific sections", () => {
+  test("GPT model prompt contains Hephaestus-style sections", () => {
     // given
     const model = "openai/gpt-5.2"
 
@@ -391,10 +385,10 @@ describe("buildSisyphusJuniorPrompt", () => {
     const prompt = buildSisyphusJuniorPrompt(model, false)
 
     // then
-    expect(prompt).toContain("<identity>")
-    expect(prompt).toContain("<output_verbosity_spec>")
-    expect(prompt).toContain("<scope_and_design_constraints>")
+    expect(prompt).toContain("## Identity")
+    expect(prompt).toContain("Scope Discipline")
     expect(prompt).toContain("<tool_usage_rules>")
+    expect(prompt).toContain("Progress Updates")
   })
 
   test("Claude model prompt contains Claude-specific sections", () => {
@@ -406,11 +400,11 @@ describe("buildSisyphusJuniorPrompt", () => {
 
     // then
     expect(prompt).toContain("<Role>")
-    expect(prompt).toContain("<Critical_Constraints>")
-    expect(prompt).toContain("BLOCKED ACTIONS")
+    expect(prompt).toContain("<Todo_Discipline>")
+    expect(prompt).toContain("todowrite")
   })
 
-  test("useTaskSystem=true includes Task_Discipline for GPT", () => {
+  test("useTaskSystem=true includes Task Discipline for GPT", () => {
     // given
     const model = "openai/gpt-5.2"
 
@@ -418,8 +412,8 @@ describe("buildSisyphusJuniorPrompt", () => {
     const prompt = buildSisyphusJuniorPrompt(model, true)
 
     // then
-    expect(prompt).toContain("<task_discipline_spec>")
-    expect(prompt).toContain("TaskCreate")
+    expect(prompt).toContain("Task Discipline")
+    expect(prompt).toContain("task_create")
   })
 
   test("useTaskSystem=false includes Todo_Discipline for Claude", () => {

src/agents/sisyphus.ts

@@ -1,15 +1,20 @@
-import type { AgentConfig } from "@opencode-ai/sdk"
-import type { AgentMode, AgentPromptMetadata } from "./types"
-import { isGptModel } from "./types"
+import type { AgentConfig } from "@opencode-ai/sdk";
+import type { AgentMode, AgentPromptMetadata } from "./types";
+import { isGptModel } from "./types";
 
-const MODE: AgentMode = "primary"
+const MODE: AgentMode = "primary";
 export const SISYPHUS_PROMPT_METADATA: AgentPromptMetadata = {
   category: "utility",
   cost: "EXPENSIVE",
   promptAlias: "Sisyphus",
   triggers: [],
-}
-import type { AvailableAgent, AvailableTool, AvailableSkill, AvailableCategory } from "./dynamic-agent-prompt-builder"
+};
+import type {
+  AvailableAgent,
+  AvailableTool,
+  AvailableSkill,
+  AvailableCategory,
+} from "./dynamic-agent-prompt-builder";
 import {
   buildKeyTriggersSection,
   buildToolSelectionTable,
@@ -21,7 +26,7 @@ import {
   buildHardBlocksSection,
   buildAntiPatternsSection,
   categorizeTools,
-} from "./dynamic-agent-prompt-builder"
+} from "./dynamic-agent-prompt-builder";
 
 function buildTaskManagementSection(useTaskSystem: boolean): string {
   if (useTaskSystem) {
@@ -80,7 +85,7 @@ I want to make sure I understand correctly.
 
 Should I proceed with [recommendation], or would you prefer differently?
 \`\`\`
-</Task_Management>`
+</Task_Management>`;
   }
 
   return `<Task_Management>
@@ -138,7 +143,7 @@ I want to make sure I understand correctly.
 
 Should I proceed with [recommendation], or would you prefer differently?
 \`\`\`
-</Task_Management>`
+</Task_Management>`;
 }
 
 function buildDynamicSisyphusPrompt(
@@ -146,21 +151,28 @@ function buildDynamicSisyphusPrompt(
   availableTools: AvailableTool[] = [],
   availableSkills: AvailableSkill[] = [],
   availableCategories: AvailableCategory[] = [],
-  useTaskSystem = false
+  useTaskSystem = false,
 ): string {
-  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills)
-  const toolSelection = buildToolSelectionTable(availableAgents, availableTools, availableSkills)
-  const exploreSection = buildExploreSection(availableAgents)
-  const librarianSection = buildLibrarianSection(availableAgents)
-  const categorySkillsGuide = buildCategorySkillsDelegationGuide(availableCategories, availableSkills)
-  const delegationTable = buildDelegationTable(availableAgents)
-  const oracleSection = buildOracleSection(availableAgents)
-  const hardBlocks = buildHardBlocksSection()
-  const antiPatterns = buildAntiPatternsSection()
-  const taskManagementSection = buildTaskManagementSection(useTaskSystem)
+  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills);
+  const toolSelection = buildToolSelectionTable(
+    availableAgents,
+    availableTools,
+    availableSkills,
+  );
+  const exploreSection = buildExploreSection(availableAgents);
+  const librarianSection = buildLibrarianSection(availableAgents);
+  const categorySkillsGuide = buildCategorySkillsDelegationGuide(
+    availableCategories,
+    availableSkills,
+  );
+  const delegationTable = buildDelegationTable(availableAgents);
+  const oracleSection = buildOracleSection(availableAgents);
+  const hardBlocks = buildHardBlocksSection();
+  const antiPatterns = buildAntiPatternsSection();
+  const taskManagementSection = buildTaskManagementSection(useTaskSystem);
   const todoHookNote = useTaskSystem
     ? "YOUR TASK CREATION WOULD BE TRACKED BY HOOK([SYSTEM REMINDER - TASK CONTINUATION])"
-    : "YOUR TODO CREATION WOULD BE TRACKED BY HOOK([SYSTEM REMINDER - TODO CONTINUATION])"
+    : "YOUR TODO CREATION WOULD BE TRACKED BY HOOK([SYSTEM REMINDER - TODO CONTINUATION])";
 
   return `<Role>
 You are "Sisyphus" - Powerful AI Agent with orchestration capabilities from OhMyOpenCode.
@@ -298,7 +310,7 @@ result = task(..., run_in_background=false)  // Never wait synchronously for exp
 1. Launch parallel agents → receive task_ids
 2. Continue immediate work
 3. When results needed: \`background_output(task_id="...")\`
-4. BEFORE final answer: \`background_cancel(all=true)\`
+4. Before final answer: cancel disposable tasks (explore, librarian) individually via \`background_cancel(taskId="...")\`. Always wait for Oracle — collect its result via \`background_output\` before answering.
 
 ### Search Stop Conditions
 
@@ -315,6 +327,7 @@ STOP searching when:
 ## Phase 2B - Implementation
 
 ### Pre-Implementation:
+0. Find relevant skills that you can load, and load them IMMEDIATELY.
 1. If task has 2+ steps → Create todo list IMMEDIATELY, IN SUPER DETAIL. No announcements—just create it.
 2. Mark current task \`in_progress\` before starting
 3. Mark \`completed\` as soon as done (don't batch) - OBSESSIVELY TRACK YOUR WORK USING TODO TOOLS
@@ -436,8 +449,9 @@ If verification fails:
 3. Report: "Done. Note: found N pre-existing lint errors unrelated to my changes."
 
 ### Before Delivering Final Answer:
-- Cancel ALL running background tasks: \`background_cancel(all=true)\`
-- This conserves resources and ensures clean workflow completion
+- Cancel disposable background tasks (explore, librarian) individually via \`background_cancel(taskId="...")\`
+- **Always wait for Oracle**: Oracle takes 20+ min by design and always provides valuable independent analysis from a different angle — even when you already have enough context. Collect Oracle results via \`background_output\` before answering.
+- When Oracle is running, cancel disposable tasks individually instead of using \`background_cancel(all=true)\`.
 </Behavior_Instructions>
 
 ${oracleSection}
@@ -497,7 +511,7 @@ ${antiPatterns}
 - Prefer small, focused changes over large refactors
 - When uncertain about scope, ask
 </Constraints>
-`
+`;
 }
 
 export function createSisyphusAgent(
@@ -506,16 +520,25 @@ export function createSisyphusAgent(
   availableToolNames?: string[],
   availableSkills?: AvailableSkill[],
   availableCategories?: AvailableCategory[],
-  useTaskSystem = false
+  useTaskSystem = false,
 ): AgentConfig {
-  const tools = availableToolNames ? categorizeTools(availableToolNames) : []
-  const skills = availableSkills ?? []
-  const categories = availableCategories ?? []
+  const tools = availableToolNames ? categorizeTools(availableToolNames) : [];
+  const skills = availableSkills ?? [];
+  const categories = availableCategories ?? [];
   const prompt = availableAgents
-    ? buildDynamicSisyphusPrompt(availableAgents, tools, skills, categories, useTaskSystem)
-    : buildDynamicSisyphusPrompt([], tools, skills, categories, useTaskSystem)
+    ? buildDynamicSisyphusPrompt(
+        availableAgents,
+        tools,
+        skills,
+        categories,
+        useTaskSystem,
+      )
+    : buildDynamicSisyphusPrompt([], tools, skills, categories, useTaskSystem);
 
-  const permission = { question: "allow", call_omo_agent: "deny" } as AgentConfig["permission"]
+  const permission = {
+    question: "allow",
+    call_omo_agent: "deny",
+  } as AgentConfig["permission"];
   const base = {
     description:
       "Powerful AI orchestrator. Plans obsessively with todos, assesses search complexity before exploration, delegates strategically via category+skills combinations. Uses explore for internal code (parallel-friendly), librarian for external docs. (Sisyphus - OhMyOpenCode)",
@@ -525,12 +548,12 @@ export function createSisyphusAgent(
     prompt,
     color: "#00CED1",
     permission,
-  }
+  };
 
   if (isGptModel(model)) {
-    return { ...base, reasoningEffort: "medium" }
+    return { ...base, reasoningEffort: "medium" };
   }
 
-  return { ...base, thinking: { type: "enabled", budgetTokens: 32000 } }
+  return { ...base, thinking: { type: "enabled", budgetTokens: 32000 } };
 }
-createSisyphusAgent.mode = MODE
+createSisyphusAgent.mode = MODE;

src/agents/types.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "bun:test";
+import { isGptModel } from "./types";
+
+describe("isGptModel", () => {
+  test("standard openai provider models", () => {
+    expect(isGptModel("openai/gpt-5.2")).toBe(true);
+    expect(isGptModel("openai/gpt-4o")).toBe(true);
+    expect(isGptModel("openai/o1")).toBe(true);
+    expect(isGptModel("openai/o3-mini")).toBe(true);
+  });
+
+  test("github copilot gpt models", () => {
+    expect(isGptModel("github-copilot/gpt-5.2")).toBe(true);
+    expect(isGptModel("github-copilot/gpt-4o")).toBe(true);
+  });
+
+  test("litellm proxied gpt models", () => {
+    expect(isGptModel("litellm/gpt-5.2")).toBe(true);
+    expect(isGptModel("litellm/gpt-4o")).toBe(true);
+    expect(isGptModel("litellm/o1")).toBe(true);
+    expect(isGptModel("litellm/o3-mini")).toBe(true);
+    expect(isGptModel("litellm/o4-mini")).toBe(true);
+  });
+
+  test("other proxied gpt models", () => {
+    expect(isGptModel("ollama/gpt-4o")).toBe(true);
+    expect(isGptModel("custom-provider/gpt-5.2")).toBe(true);
+  });
+
+  test("gpt4 prefix without hyphen (legacy naming)", () => {
+    expect(isGptModel("litellm/gpt4o")).toBe(true);
+    expect(isGptModel("ollama/gpt4")).toBe(true);
+  });
+
+  test("claude models are not gpt", () => {
+    expect(isGptModel("anthropic/claude-opus-4-6")).toBe(false);
+    expect(isGptModel("anthropic/claude-sonnet-4-5")).toBe(false);
+    expect(isGptModel("litellm/anthropic.claude-opus-4-5")).toBe(false);
+  });
+
+  test("gemini models are not gpt", () => {
+    expect(isGptModel("google/gemini-3-pro")).toBe(false);
+    expect(isGptModel("litellm/gemini-3-pro")).toBe(false);
+  });
+
+  test("opencode provider is not gpt", () => {
+    expect(isGptModel("opencode/claude-opus-4-6")).toBe(false);
+  });
+});

src/agents/types.ts

@@ -66,8 +66,18 @@ export interface AgentPromptMetadata {
   keyTrigger?: string
 }
 
+function extractModelName(model: string): string {
+  return model.includes("/") ? model.split("/").pop() ?? model : model
+}
+
+const GPT_MODEL_PREFIXES = ["gpt-", "gpt4", "o1", "o3", "o4"]
+
 export function isGptModel(model: string): boolean {
-  return model.startsWith("openai/") || model.startsWith("github-copilot/gpt-")
+  if (model.startsWith("openai/") || model.startsWith("github-copilot/gpt-"))
+    return true
+
+  const modelName = extractModelName(model).toLowerCase()
+  return GPT_MODEL_PREFIXES.some((prefix) => modelName.startsWith(prefix))
 }
 
 export type BuiltinAgentName =

src/agents/utils.test.ts

@@ -428,7 +428,7 @@ describe("createBuiltinAgents with model overrides", () => {
       )
 
       // #then
-      const matches = agents.sisyphus.prompt.match(/Custom agent: researcher/gi) ?? []
+      const matches = (agents.sisyphus?.prompt ?? "").match(/Custom agent: researcher/gi) ?? []
       expect(matches.length).toBe(1)
     } finally {
       fetchSpy.mockRestore()
@@ -525,6 +525,34 @@ describe("createBuiltinAgents without systemDefaultModel", () => {
 })
 
 describe("createBuiltinAgents with requiresProvider gating (hephaestus)", () => {
+  test("hephaestus is created when provider-models cache connected list includes required provider", async () => {
+    // #given
+    const connectedCacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue(["anthropic"])
+    const providerModelsSpy = spyOn(connectedProvidersCache, "readProviderModelsCache").mockReturnValue({
+      connected: ["openai"],
+      models: {},
+      updatedAt: new Date().toISOString(),
+    })
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockImplementation(async (_, options) => {
+      const providers = options?.connectedProviders ?? []
+      return providers.includes("openai")
+        ? new Set(["openai/gpt-5.3-codex"])
+        : new Set(["anthropic/claude-opus-4-6"])
+    })
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.hephaestus).toBeDefined()
+    } finally {
+      connectedCacheSpy.mockRestore()
+      providerModelsSpy.mockRestore()
+      fetchSpy.mockRestore()
+    }
+  })
+
   test("hephaestus is not created when no required provider is connected", async () => {
     // #given - only anthropic models available, not in hephaestus requiresProvider
     const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(

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
 

src/cli/__snapshots__/model-fallback.test.ts.snap

@@ -247,7 +247,7 @@ exports[`generateModelConfig single native provider uses OpenAI models when only
       "model": "opencode/glm-4.7-free",
     },
     "writing": {
-      "model": "openai/gpt-5.2",
+      "model": "opencode/glm-4.7-free",
     },
   },
 }
@@ -314,7 +314,7 @@ exports[`generateModelConfig single native provider uses OpenAI models with isMa
       "model": "opencode/glm-4.7-free",
     },
     "writing": {
-      "model": "openai/gpt-5.2",
+      "model": "opencode/glm-4.7-free",
     },
   },
 }
@@ -372,6 +372,7 @@ exports[`generateModelConfig single native provider uses Gemini models when only
     },
     "visual-engineering": {
       "model": "google/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "google/gemini-3-flash",
@@ -432,6 +433,7 @@ exports[`generateModelConfig single native provider uses Gemini models with isMa
     },
     "visual-engineering": {
       "model": "google/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "google/gemini-3-flash",
@@ -505,6 +507,7 @@ exports[`generateModelConfig all native providers uses preferred models from fal
     },
     "visual-engineering": {
       "model": "google/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "google/gemini-3-flash",
@@ -579,6 +582,7 @@ exports[`generateModelConfig all native providers uses preferred models with isM
     },
     "visual-engineering": {
       "model": "google/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "google/gemini-3-flash",
@@ -652,6 +656,7 @@ exports[`generateModelConfig fallback providers uses OpenCode Zen models when on
     },
     "visual-engineering": {
       "model": "opencode/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "opencode/gemini-3-flash",
@@ -726,6 +731,7 @@ exports[`generateModelConfig fallback providers uses OpenCode Zen models with is
     },
     "visual-engineering": {
       "model": "opencode/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "opencode/gemini-3-flash",
@@ -799,6 +805,7 @@ exports[`generateModelConfig fallback providers uses GitHub Copilot models when
     },
     "visual-engineering": {
       "model": "github-copilot/gemini-3-pro-preview",
+      "variant": "high",
     },
     "writing": {
       "model": "github-copilot/gemini-3-flash-preview",
@@ -873,6 +880,7 @@ exports[`generateModelConfig fallback providers uses GitHub Copilot models with
     },
     "visual-engineering": {
       "model": "github-copilot/gemini-3-pro-preview",
+      "variant": "high",
     },
     "writing": {
       "model": "github-copilot/gemini-3-flash-preview",
@@ -927,10 +935,10 @@ exports[`generateModelConfig fallback providers uses ZAI model for librarian whe
       "model": "opencode/glm-4.7-free",
     },
     "visual-engineering": {
-      "model": "zai-coding-plan/glm-4.7",
+      "model": "zai-coding-plan/glm-5",
     },
     "writing": {
-      "model": "zai-coding-plan/glm-4.7",
+      "model": "opencode/glm-4.7-free",
     },
   },
 }
@@ -982,10 +990,10 @@ exports[`generateModelConfig fallback providers uses ZAI model for librarian wit
       "model": "opencode/glm-4.7-free",
     },
     "visual-engineering": {
-      "model": "zai-coding-plan/glm-4.7",
+      "model": "zai-coding-plan/glm-5",
     },
     "writing": {
-      "model": "zai-coding-plan/glm-4.7",
+      "model": "opencode/glm-4.7-free",
     },
   },
 }
@@ -1056,6 +1064,7 @@ exports[`generateModelConfig mixed provider scenarios uses Claude + OpenCode Zen
     },
     "visual-engineering": {
       "model": "opencode/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "opencode/gemini-3-flash",
@@ -1129,6 +1138,7 @@ exports[`generateModelConfig mixed provider scenarios uses OpenAI + Copilot comb
     },
     "visual-engineering": {
       "model": "github-copilot/gemini-3-pro-preview",
+      "variant": "high",
     },
     "writing": {
       "model": "github-copilot/gemini-3-flash-preview",
@@ -1189,8 +1199,7 @@ exports[`generateModelConfig mixed provider scenarios uses Claude + ZAI combinat
       "model": "anthropic/claude-sonnet-4-5",
     },
     "visual-engineering": {
-      "model": "anthropic/claude-opus-4-6",
-      "variant": "max",
+      "model": "zai-coding-plan/glm-5",
     },
     "writing": {
       "model": "anthropic/claude-sonnet-4-5",
@@ -1256,6 +1265,7 @@ exports[`generateModelConfig mixed provider scenarios uses Gemini + Claude combi
     },
     "visual-engineering": {
       "model": "google/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "google/gemini-3-flash",
@@ -1329,6 +1339,7 @@ exports[`generateModelConfig mixed provider scenarios uses all fallback provider
     },
     "visual-engineering": {
       "model": "github-copilot/gemini-3-pro-preview",
+      "variant": "high",
     },
     "writing": {
       "model": "github-copilot/gemini-3-flash-preview",
@@ -1402,6 +1413,7 @@ exports[`generateModelConfig mixed provider scenarios uses all providers togethe
     },
     "visual-engineering": {
       "model": "google/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "google/gemini-3-flash",
@@ -1476,6 +1488,7 @@ exports[`generateModelConfig mixed provider scenarios uses all providers with is
     },
     "visual-engineering": {
       "model": "google/gemini-3-pro",
+      "variant": "high",
     },
     "writing": {
       "model": "google/gemini-3-flash",

src/cli/cli-installer.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, it, mock, spyOn } from "bun:test"
+import * as configManager from "./config-manager"
+import { runCliInstaller } from "./cli-installer"
+import type { InstallArgs } from "./types"
+
+describe("runCliInstaller", () => {
+  const mockConsoleLog = mock(() => {})
+  const mockConsoleError = mock(() => {})
+  const originalConsoleLog = console.log
+  const originalConsoleError = console.error
+
+  beforeEach(() => {
+    console.log = mockConsoleLog
+    console.error = mockConsoleError
+    mockConsoleLog.mockClear()
+    mockConsoleError.mockClear()
+  })
+
+  afterEach(() => {
+    console.log = originalConsoleLog
+    console.error = originalConsoleError
+  })
+
+  it("runs auth and provider setup steps when openai or copilot are enabled without gemini", async () => {
+    //#given
+    const addAuthPluginsSpy = spyOn(configManager, "addAuthPlugins").mockResolvedValue({
+      success: true,
+      configPath: "/tmp/opencode.jsonc",
+    })
+    const addProviderConfigSpy = spyOn(configManager, "addProviderConfig").mockReturnValue({
+      success: true,
+      configPath: "/tmp/opencode.jsonc",
+    })
+    const restoreSpies = [
+      addAuthPluginsSpy,
+      addProviderConfigSpy,
+      spyOn(configManager, "detectCurrentConfig").mockReturnValue({
+        isInstalled: false,
+        hasClaude: false,
+        isMax20: false,
+        hasOpenAI: false,
+        hasGemini: false,
+        hasCopilot: false,
+        hasOpencodeZen: false,
+        hasZaiCodingPlan: false,
+        hasKimiForCoding: false,
+      }),
+      spyOn(configManager, "isOpenCodeInstalled").mockResolvedValue(true),
+      spyOn(configManager, "getOpenCodeVersion").mockResolvedValue("1.0.200"),
+      spyOn(configManager, "addPluginToOpenCodeConfig").mockResolvedValue({
+        success: true,
+        configPath: "/tmp/opencode.jsonc",
+      }),
+      spyOn(configManager, "writeOmoConfig").mockReturnValue({
+        success: true,
+        configPath: "/tmp/oh-my-opencode.jsonc",
+      }),
+    ]
+
+    const args: InstallArgs = {
+      tui: false,
+      claude: "no",
+      openai: "yes",
+      gemini: "no",
+      copilot: "yes",
+      opencodeZen: "no",
+      zaiCodingPlan: "no",
+      kimiForCoding: "no",
+    }
+
+    //#when
+    const result = await runCliInstaller(args, "3.4.0")
+
+    //#then
+    expect(result).toBe(0)
+    expect(addAuthPluginsSpy).toHaveBeenCalledTimes(1)
+    expect(addProviderConfigSpy).toHaveBeenCalledTimes(1)
+
+    for (const spy of restoreSpies) {
+      spy.mockRestore()
+    }
+  })
+})

src/cli/cli-installer.ts

@@ -77,7 +77,9 @@ export async function runCliInstaller(args: InstallArgs, version: string): Promi
     `Plugin ${isUpdate ? "verified" : "added"} ${SYMBOLS.arrow} ${color.dim(pluginResult.configPath)}`,
   )
 
-  if (config.hasGemini) {
+  const needsProviderSetup = config.hasGemini || config.hasOpenAI || config.hasCopilot
+
+  if (needsProviderSetup) {
     printStep(step++, totalSteps, "Adding auth plugins...")
     const authResult = await addAuthPlugins(config)
     if (!authResult.success) {

src/cli/cli-program.ts

@@ -149,29 +149,21 @@ This command shows:
 program
   .command("doctor")
   .description("Check oh-my-opencode installation health and diagnose issues")
+  .option("--status", "Show compact system dashboard")
   .option("--verbose", "Show detailed diagnostic information")
   .option("--json", "Output results in JSON format")
-  .option("--category <category>", "Run only specific category")
   .addHelpText("after", `
 Examples:
-  $ bunx oh-my-opencode doctor
-  $ bunx oh-my-opencode doctor --verbose
-  $ bunx oh-my-opencode doctor --json
-  $ bunx oh-my-opencode doctor --category authentication
-
-Categories:
-  installation     Check OpenCode and plugin installation
-  configuration    Validate configuration files
-  authentication   Check auth provider status
-  dependencies     Check external dependencies
-  tools            Check LSP and MCP servers
-  updates          Check for version updates
+  $ bunx oh-my-opencode doctor            # Show problems only
+  $ bunx oh-my-opencode doctor --status   # Compact dashboard
+  $ bunx oh-my-opencode doctor --verbose  # Deep diagnostics
+  $ bunx oh-my-opencode doctor --json     # JSON output
 `)
   .action(async (options) => {
+    const mode = options.status ? "status" : options.verbose ? "verbose" : "default"
     const doctorOptions: DoctorOptions = {
-      verbose: options.verbose ?? false,
+      mode,
       json: options.json ?? false,
-      category: options.category,
     }
     const exitCode = await doctor(doctorOptions)
     process.exit(exitCode)

src/cli/doctor/checks/auth.test.ts

@@ -1,114 +0,0 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
-import * as auth from "./auth"
-
-describe("auth check", () => {
-  describe("getAuthProviderInfo", () => {
-    it("returns anthropic as always available", () => {
-      // given anthropic provider
-      // when getting info
-      const info = auth.getAuthProviderInfo("anthropic")
-
-      // then should show plugin installed (builtin)
-      expect(info.id).toBe("anthropic")
-      expect(info.pluginInstalled).toBe(true)
-    })
-
-    it("returns correct name for each provider", () => {
-      // given each provider
-      // when getting info
-      // then should have correct names
-      expect(auth.getAuthProviderInfo("anthropic").name).toContain("Claude")
-      expect(auth.getAuthProviderInfo("openai").name).toContain("ChatGPT")
-      expect(auth.getAuthProviderInfo("google").name).toContain("Gemini")
-    })
-  })
-
-  describe("checkAuthProvider", () => {
-    let getInfoSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      getInfoSpy?.mockRestore()
-    })
-
-    it("returns pass when plugin installed", async () => {
-      // given plugin installed
-      getInfoSpy = spyOn(auth, "getAuthProviderInfo").mockReturnValue({
-        id: "anthropic",
-        name: "Anthropic (Claude)",
-        pluginInstalled: true,
-        configured: true,
-      })
-
-      // when checking
-      const result = await auth.checkAuthProvider("anthropic")
-
-      // then should pass
-      expect(result.status).toBe("pass")
-    })
-
-    it("returns skip when plugin not installed", async () => {
-      // given plugin not installed
-      getInfoSpy = spyOn(auth, "getAuthProviderInfo").mockReturnValue({
-        id: "openai",
-        name: "OpenAI (ChatGPT)",
-        pluginInstalled: false,
-        configured: false,
-      })
-
-      // when checking
-      const result = await auth.checkAuthProvider("openai")
-
-      // then should skip
-      expect(result.status).toBe("skip")
-      expect(result.message).toContain("not installed")
-    })
-  })
-
-  describe("checkAnthropicAuth", () => {
-    it("returns a check result", async () => {
-      // given
-      // when checking anthropic
-      const result = await auth.checkAnthropicAuth()
-
-      // then should return valid result
-      expect(result.name).toBeDefined()
-      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
-    })
-  })
-
-  describe("checkOpenAIAuth", () => {
-    it("returns a check result", async () => {
-      // given
-      // when checking openai
-      const result = await auth.checkOpenAIAuth()
-
-      // then should return valid result
-      expect(result.name).toBeDefined()
-      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
-    })
-  })
-
-  describe("checkGoogleAuth", () => {
-    it("returns a check result", async () => {
-      // given
-      // when checking google
-      const result = await auth.checkGoogleAuth()
-
-      // then should return valid result
-      expect(result.name).toBeDefined()
-      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
-    })
-  })
-
-  describe("getAuthCheckDefinitions", () => {
-    it("returns definitions for all three providers", () => {
-      // given
-      // when getting definitions
-      const defs = auth.getAuthCheckDefinitions()
-
-      // then should have 3 definitions
-      expect(defs.length).toBe(3)
-      expect(defs.every((d) => d.category === "authentication")).toBe(true)
-    })
-  })
-})

src/cli/doctor/checks/auth.ts

@@ -1,114 +0,0 @@
-import { existsSync, readFileSync } from "node:fs"
-import { join } from "node:path"
-import type { CheckResult, CheckDefinition, AuthProviderInfo, AuthProviderId } from "../types"
-import { CHECK_IDS, CHECK_NAMES } from "../constants"
-import { parseJsonc, getOpenCodeConfigDir } from "../../../shared"
-
-const OPENCODE_CONFIG_DIR = getOpenCodeConfigDir({ binary: "opencode" })
-const OPENCODE_JSON = join(OPENCODE_CONFIG_DIR, "opencode.json")
-const OPENCODE_JSONC = join(OPENCODE_CONFIG_DIR, "opencode.jsonc")
-
-const AUTH_PLUGINS: Record<AuthProviderId, { plugin: string; name: string }> = {
-  anthropic: { plugin: "builtin", name: "Anthropic (Claude)" },
-  openai: { plugin: "opencode-openai-codex-auth", name: "OpenAI (ChatGPT)" },
-  google: { plugin: "opencode-antigravity-auth", name: "Google (Gemini)" },
-}
-
-function getOpenCodeConfig(): { plugin?: string[] } | null {
-  const configPath = existsSync(OPENCODE_JSONC) ? OPENCODE_JSONC : OPENCODE_JSON
-  if (!existsSync(configPath)) return null
-
-  try {
-    const content = readFileSync(configPath, "utf-8")
-    return parseJsonc<{ plugin?: string[] }>(content)
-  } catch {
-    return null
-  }
-}
-
-function isPluginInstalled(plugins: string[], pluginName: string): boolean {
-  if (pluginName === "builtin") return true
-  return plugins.some((p) => p === pluginName || p.startsWith(`${pluginName}@`))
-}
-
-export function getAuthProviderInfo(providerId: AuthProviderId): AuthProviderInfo {
-  const config = getOpenCodeConfig()
-  const plugins = config?.plugin ?? []
-  const authConfig = AUTH_PLUGINS[providerId]
-
-  const pluginInstalled = isPluginInstalled(plugins, authConfig.plugin)
-
-  return {
-    id: providerId,
-    name: authConfig.name,
-    pluginInstalled,
-    configured: pluginInstalled,
-  }
-}
-
-export async function checkAuthProvider(providerId: AuthProviderId): Promise<CheckResult> {
-  const info = getAuthProviderInfo(providerId)
-  const checkId = `auth-${providerId}` as keyof typeof CHECK_NAMES
-  const checkName = CHECK_NAMES[checkId] || info.name
-
-  if (!info.pluginInstalled) {
-    return {
-      name: checkName,
-      status: "skip",
-      message: "Auth plugin not installed",
-      details: [
-        `Plugin: ${AUTH_PLUGINS[providerId].plugin}`,
-        "Run: bunx oh-my-opencode install",
-      ],
-    }
-  }
-
-  return {
-    name: checkName,
-    status: "pass",
-    message: "Auth plugin available",
-    details: [
-      providerId === "anthropic"
-        ? "Run: opencode auth login (select Anthropic)"
-        : `Plugin: ${AUTH_PLUGINS[providerId].plugin}`,
-    ],
-  }
-}
-
-export async function checkAnthropicAuth(): Promise<CheckResult> {
-  return checkAuthProvider("anthropic")
-}
-
-export async function checkOpenAIAuth(): Promise<CheckResult> {
-  return checkAuthProvider("openai")
-}
-
-export async function checkGoogleAuth(): Promise<CheckResult> {
-  return checkAuthProvider("google")
-}
-
-export function getAuthCheckDefinitions(): CheckDefinition[] {
-  return [
-    {
-      id: CHECK_IDS.AUTH_ANTHROPIC,
-      name: CHECK_NAMES[CHECK_IDS.AUTH_ANTHROPIC],
-      category: "authentication",
-      check: checkAnthropicAuth,
-      critical: false,
-    },
-    {
-      id: CHECK_IDS.AUTH_OPENAI,
-      name: CHECK_NAMES[CHECK_IDS.AUTH_OPENAI],
-      category: "authentication",
-      check: checkOpenAIAuth,
-      critical: false,
-    },
-    {
-      id: CHECK_IDS.AUTH_GOOGLE,
-      name: CHECK_NAMES[CHECK_IDS.AUTH_GOOGLE],
-      category: "authentication",
-      check: checkGoogleAuth,
-      critical: false,
-    },
-  ]
-}

src/cli/doctor/checks/config.test.ts

@@ -1,103 +1,27 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import { describe, it, expect } from "bun:test"
 import * as config from "./config"
 
 describe("config check", () => {
-  describe("validateConfig", () => {
-    it("returns valid: false for non-existent file", () => {
-      // given non-existent file path
-      // when validating
-      const result = config.validateConfig("/non/existent/path.json")
+  describe("checkConfig", () => {
+    it("returns a valid CheckResult", async () => {
+      //#given config check is available
+      //#when running the consolidated config check
+      const result = await config.checkConfig()
 
-      // then should indicate invalid
-      expect(result.valid).toBe(false)
-      expect(result.errors.length).toBeGreaterThan(0)
-    })
-  })
-
-  describe("getConfigInfo", () => {
-    it("returns exists: false when no config found", () => {
-      // given no config file exists
-      // when getting config info
-      const info = config.getConfigInfo()
-
-      // then should handle gracefully
-      expect(typeof info.exists).toBe("boolean")
-      expect(typeof info.valid).toBe("boolean")
-    })
-  })
-
-  describe("checkConfigValidity", () => {
-    let getInfoSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      getInfoSpy?.mockRestore()
+      //#then should return a properly shaped CheckResult
+      expect(result.name).toBe("Configuration")
+      expect(["pass", "fail", "warn", "skip"]).toContain(result.status)
+      expect(typeof result.message).toBe("string")
+      expect(Array.isArray(result.issues)).toBe(true)
     })
 
-    it("returns pass when no config exists (uses defaults)", async () => {
-      // given no config file
-      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
-        exists: false,
-        path: null,
-        format: null,
-        valid: true,
-        errors: [],
-      })
+    it("includes issues array even when config is valid", async () => {
+      //#given a normal environment
+      //#when running config check
+      const result = await config.checkConfig()
 
-      // when checking validity
-      const result = await config.checkConfigValidity()
-
-      // then should pass with default message
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("default")
-    })
-
-    it("returns pass when config is valid", async () => {
-      // given valid config
-      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
-        exists: true,
-        path: "/home/user/.config/opencode/oh-my-opencode.json",
-        format: "json",
-        valid: true,
-        errors: [],
-      })
-
-      // when checking validity
-      const result = await config.checkConfigValidity()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("JSON")
-    })
-
-    it("returns fail when config has validation errors", async () => {
-      // given invalid config
-      getInfoSpy = spyOn(config, "getConfigInfo").mockReturnValue({
-        exists: true,
-        path: "/home/user/.config/opencode/oh-my-opencode.json",
-        format: "json",
-        valid: false,
-        errors: ["agents.oracle: Invalid model format"],
-      })
-
-      // when checking validity
-      const result = await config.checkConfigValidity()
-
-      // then should fail with errors
-      expect(result.status).toBe("fail")
-      expect(result.details?.some((d) => d.includes("Error"))).toBe(true)
-    })
-  })
-
-  describe("getConfigCheckDefinition", () => {
-    it("returns valid check definition", () => {
-      // given
-      // when getting definition
-      const def = config.getConfigCheckDefinition()
-
-      // then should have required properties
-      expect(def.id).toBe("config-validation")
-      expect(def.category).toBe("configuration")
-      expect(def.critical).toBe(false)
+      //#then issues should be an array (possibly empty)
+      expect(Array.isArray(result.issues)).toBe(true)
     })
   })
 })

src/cli/doctor/checks/config.ts

@@ -1,122 +1,164 @@
-import { existsSync, readFileSync } from "node:fs"
+import { readFileSync } from "node:fs"
 import { join } from "node:path"
-import type { CheckResult, CheckDefinition, ConfigInfo } from "../types"
-import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
-import { parseJsonc, detectConfigFile, getOpenCodeConfigDir } from "../../../shared"
-import { OhMyOpenCodeConfigSchema } from "../../../config"
 
-const USER_CONFIG_DIR = getOpenCodeConfigDir({ binary: "opencode" })
-const USER_CONFIG_BASE = join(USER_CONFIG_DIR, `${PACKAGE_NAME}`)
+import { OhMyOpenCodeConfigSchema } from "../../../config"
+import { detectConfigFile, getOpenCodeConfigDir, parseJsonc } from "../../../shared"
+import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
+import type { CheckResult, DoctorIssue } from "../types"
+import { loadAvailableModelsFromCache } from "./model-resolution-cache"
+import { getModelResolutionInfoWithOverrides } from "./model-resolution"
+import type { OmoConfig } from "./model-resolution-types"
+
+const USER_CONFIG_BASE = join(getOpenCodeConfigDir({ binary: "opencode" }), PACKAGE_NAME)
 const PROJECT_CONFIG_BASE = join(process.cwd(), ".opencode", PACKAGE_NAME)
 
-function findConfigPath(): { path: string; format: "json" | "jsonc" } | null {
-  const projectDetected = detectConfigFile(PROJECT_CONFIG_BASE)
-  if (projectDetected.format !== "none") {
-    return { path: projectDetected.path, format: projectDetected.format as "json" | "jsonc" }
-  }
+interface ConfigValidationResult {
+  exists: boolean
+  path: string | null
+  valid: boolean
+  config: OmoConfig | null
+  errors: string[]
+}
 
-  const userDetected = detectConfigFile(USER_CONFIG_BASE)
-  if (userDetected.format !== "none") {
-    return { path: userDetected.path, format: userDetected.format as "json" | "jsonc" }
-  }
+function findConfigPath(): string | null {
+  const projectConfig = detectConfigFile(PROJECT_CONFIG_BASE)
+  if (projectConfig.format !== "none") return projectConfig.path
+
+  const userConfig = detectConfigFile(USER_CONFIG_BASE)
+  if (userConfig.format !== "none") return userConfig.path
 
   return null
 }
 
-export function validateConfig(configPath: string): { valid: boolean; errors: string[] } {
+function validateConfig(): ConfigValidationResult {
+  const configPath = findConfigPath()
+  if (!configPath) {
+    return { exists: false, path: null, valid: true, config: null, errors: [] }
+  }
+
   try {
     const content = readFileSync(configPath, "utf-8")
-    const rawConfig = parseJsonc<Record<string, unknown>>(content)
-    const result = OhMyOpenCodeConfigSchema.safeParse(rawConfig)
+    const rawConfig = parseJsonc<OmoConfig>(content)
+    const schemaResult = OhMyOpenCodeConfigSchema.safeParse(rawConfig)
 
-    if (!result.success) {
-      const errors = result.error.issues.map(
-        (i) => `${i.path.join(".")}: ${i.message}`
-      )
-      return { valid: false, errors }
+    if (!schemaResult.success) {
+      return {
+        exists: true,
+        path: configPath,
+        valid: false,
+        config: rawConfig,
+        errors: schemaResult.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`),
+      }
     }
 
-    return { valid: true, errors: [] }
-  } catch (err) {
+    return { exists: true, path: configPath, valid: true, config: rawConfig, errors: [] }
+  } catch (error) {
     return {
+      exists: true,
+      path: configPath,
       valid: false,
-      errors: [err instanceof Error ? err.message : "Failed to parse config"],
+      config: null,
+      errors: [error instanceof Error ? error.message : "Failed to parse config"],
     }
   }
 }
 
-export function getConfigInfo(): ConfigInfo {
-  const configPath = findConfigPath()
+function collectModelResolutionIssues(config: OmoConfig): DoctorIssue[] {
+  const issues: DoctorIssue[] = []
+  const availableModels = loadAvailableModelsFromCache()
+  const resolution = getModelResolutionInfoWithOverrides(config)
 
-  if (!configPath) {
-    return {
-      exists: false,
-      path: null,
-      format: null,
-      valid: true,
-      errors: [],
+  const invalidAgentOverrides = resolution.agents.filter(
+    (agent) => agent.userOverride && !agent.userOverride.includes("/")
+  )
+  const invalidCategoryOverrides = resolution.categories.filter(
+    (category) => category.userOverride && !category.userOverride.includes("/")
+  )
+
+  for (const invalidAgent of invalidAgentOverrides) {
+    issues.push({
+      title: `Invalid agent override: ${invalidAgent.name}`,
+      description: `Override '${invalidAgent.userOverride}' must be in provider/model format.`,
+      severity: "warning",
+      affects: [invalidAgent.name],
+    })
+  }
+
+  for (const invalidCategory of invalidCategoryOverrides) {
+    issues.push({
+      title: `Invalid category override: ${invalidCategory.name}`,
+      description: `Override '${invalidCategory.userOverride}' must be in provider/model format.`,
+      severity: "warning",
+      affects: [invalidCategory.name],
+    })
+  }
+
+  if (availableModels.cacheExists) {
+    const providerSet = new Set(availableModels.providers)
+    const unknownProviders = [
+      ...resolution.agents.map((agent) => agent.userOverride),
+      ...resolution.categories.map((category) => category.userOverride),
+    ]
+      .filter((value): value is string => Boolean(value))
+      .map((value) => value.split("/")[0])
+      .filter((provider) => provider.length > 0 && !providerSet.has(provider))
+
+    if (unknownProviders.length > 0) {
+      const uniqueProviders = [...new Set(unknownProviders)]
+      issues.push({
+        title: "Model override uses unavailable provider",
+        description: `Provider(s) not found in OpenCode model cache: ${uniqueProviders.join(", ")}`,
+        severity: "warning",
+        affects: ["model resolution"],
+      })
     }
   }
 
-  if (!existsSync(configPath.path)) {
-    return {
-      exists: false,
-      path: configPath.path,
-      format: configPath.format,
-      valid: true,
-      errors: [],
-    }
-  }
-
-  const validation = validateConfig(configPath.path)
-
-  return {
-    exists: true,
-    path: configPath.path,
-    format: configPath.format,
-    valid: validation.valid,
-    errors: validation.errors,
-  }
+  return issues
 }
 
-export async function checkConfigValidity(): Promise<CheckResult> {
-  const info = getConfigInfo()
+export async function checkConfig(): Promise<CheckResult> {
+  const validation = validateConfig()
+  const issues: DoctorIssue[] = []
 
-  if (!info.exists) {
+  if (!validation.exists) {
     return {
-      name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+      name: CHECK_NAMES[CHECK_IDS.CONFIG],
       status: "pass",
-      message: "Using default configuration",
-      details: ["No custom config file found (optional)"],
+      message: "No custom config found; defaults are used",
+      details: undefined,
+      issues,
     }
   }
 
-  if (!info.valid) {
+  if (!validation.valid) {
+    issues.push(
+      ...validation.errors.map((error) => ({
+        title: "Invalid configuration",
+        description: error,
+        severity: "error" as const,
+        affects: ["plugin startup"],
+      }))
+    )
+
     return {
-      name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
+      name: CHECK_NAMES[CHECK_IDS.CONFIG],
       status: "fail",
-      message: "Configuration has validation errors",
-      details: [
-        `Path: ${info.path}`,
-        ...info.errors.map((e) => `Error: ${e}`),
-      ],
+      message: `Configuration invalid (${issues.length} issue${issues.length > 1 ? "s" : ""})`,
+      details: validation.path ? [`Path: ${validation.path}`] : undefined,
+      issues,
     }
   }
 
-  return {
-    name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
-    status: "pass",
-    message: `Valid ${info.format?.toUpperCase()} config`,
-    details: [`Path: ${info.path}`],
+  if (validation.config) {
+    issues.push(...collectModelResolutionIssues(validation.config))
   }
-}
 
-export function getConfigCheckDefinition(): CheckDefinition {
   return {
-    id: CHECK_IDS.CONFIG_VALIDATION,
-    name: CHECK_NAMES[CHECK_IDS.CONFIG_VALIDATION],
-    category: "configuration",
-    check: checkConfigValidity,
-    critical: false,
+    name: CHECK_NAMES[CHECK_IDS.CONFIG],
+    status: issues.length > 0 ? "warn" : "pass",
+    message: issues.length > 0 ? `${issues.length} configuration warning(s)` : "Configuration is valid",
+    details: validation.path ? [`Path: ${validation.path}`] : undefined,
+    issues,
   }
 }

src/cli/doctor/checks/dependencies.test.ts

@@ -1,27 +1,29 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
+import { describe, it, expect } from "bun:test"
 import * as deps from "./dependencies"
 
 describe("dependencies check", () => {
   describe("checkAstGrepCli", () => {
-    it("returns dependency info", async () => {
-      // given
-      // when checking ast-grep cli
+    it("returns valid dependency info", async () => {
+      //#given ast-grep cli check
+      //#when checking
       const info = await deps.checkAstGrepCli()
 
-      // then should return valid info
+      //#then should return valid DependencyInfo
       expect(info.name).toBe("AST-Grep CLI")
       expect(info.required).toBe(false)
       expect(typeof info.installed).toBe("boolean")
+      expect(typeof info.version === "string" || info.version === null).toBe(true)
+      expect(typeof info.path === "string" || info.path === null).toBe(true)
     })
   })
 
   describe("checkAstGrepNapi", () => {
-    it("returns dependency info", async () => {
-      // given
-      // when checking ast-grep napi
+    it("returns valid dependency info", async () => {
+      //#given ast-grep napi check
+      //#when checking
       const info = await deps.checkAstGrepNapi()
 
-      // then should return valid info
+      //#then should return valid DependencyInfo
       expect(info.name).toBe("AST-Grep NAPI")
       expect(info.required).toBe(false)
       expect(typeof info.installed).toBe("boolean")
@@ -29,124 +31,15 @@ describe("dependencies check", () => {
   })
 
   describe("checkCommentChecker", () => {
-    it("returns dependency info", async () => {
-      // given
-      // when checking comment checker
+    it("returns valid dependency info", async () => {
+      //#given comment checker check
+      //#when checking
       const info = await deps.checkCommentChecker()
 
-      // then should return valid info
+      //#then should return valid DependencyInfo
       expect(info.name).toBe("Comment Checker")
       expect(info.required).toBe(false)
       expect(typeof info.installed).toBe("boolean")
     })
   })
-
-  describe("checkDependencyAstGrepCli", () => {
-    let checkSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      checkSpy?.mockRestore()
-    })
-
-    it("returns pass when installed", async () => {
-      // given ast-grep installed
-      checkSpy = spyOn(deps, "checkAstGrepCli").mockResolvedValue({
-        name: "AST-Grep CLI",
-        required: false,
-        installed: true,
-        version: "0.25.0",
-        path: "/usr/local/bin/sg",
-      })
-
-      // when checking
-      const result = await deps.checkDependencyAstGrepCli()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("0.25.0")
-    })
-
-    it("returns warn when not installed", async () => {
-      // given ast-grep not installed
-      checkSpy = spyOn(deps, "checkAstGrepCli").mockResolvedValue({
-        name: "AST-Grep CLI",
-        required: false,
-        installed: false,
-        version: null,
-        path: null,
-        installHint: "Install: npm install -g @ast-grep/cli",
-      })
-
-      // when checking
-      const result = await deps.checkDependencyAstGrepCli()
-
-      // then should warn (optional)
-      expect(result.status).toBe("warn")
-      expect(result.message).toContain("optional")
-    })
-  })
-
-  describe("checkDependencyAstGrepNapi", () => {
-    let checkSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      checkSpy?.mockRestore()
-    })
-
-    it("returns pass when installed", async () => {
-      // given napi installed
-      checkSpy = spyOn(deps, "checkAstGrepNapi").mockResolvedValue({
-        name: "AST-Grep NAPI",
-        required: false,
-        installed: true,
-        version: null,
-        path: null,
-      })
-
-      // when checking
-      const result = await deps.checkDependencyAstGrepNapi()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-    })
-  })
-
-  describe("checkDependencyCommentChecker", () => {
-    let checkSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      checkSpy?.mockRestore()
-    })
-
-    it("returns warn when not installed", async () => {
-      // given comment checker not installed
-      checkSpy = spyOn(deps, "checkCommentChecker").mockResolvedValue({
-        name: "Comment Checker",
-        required: false,
-        installed: false,
-        version: null,
-        path: null,
-        installHint: "Hook will be disabled if not available",
-      })
-
-      // when checking
-      const result = await deps.checkDependencyCommentChecker()
-
-      // then should warn
-      expect(result.status).toBe("warn")
-    })
-  })
-
-  describe("getDependencyCheckDefinitions", () => {
-    it("returns definitions for all dependencies", () => {
-      // given
-      // when getting definitions
-      const defs = deps.getDependencyCheckDefinitions()
-
-      // then should have 3 definitions
-      expect(defs.length).toBe(3)
-      expect(defs.every((d) => d.category === "dependencies")).toBe(true)
-      expect(defs.every((d) => d.critical === false)).toBe(true)
-    })
-  })
 })

src/cli/doctor/checks/dependencies.ts

@@ -1,5 +1,8 @@
-import type { CheckResult, CheckDefinition, DependencyInfo } from "../types"
-import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import { existsSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+
+import type { DependencyInfo } from "../types"
 
 async function checkBinaryExists(binary: string): Promise<{ exists: boolean; path: string | null }> {
   try {
@@ -99,10 +102,24 @@ export async function checkAstGrepNapi(): Promise<DependencyInfo> {
   }
 }
 
+function findCommentCheckerPackageBinary(): string | null {
+  const binaryName = process.platform === "win32" ? "comment-checker.exe" : "comment-checker"
+  try {
+    const require = createRequire(import.meta.url)
+    const pkgPath = require.resolve("@code-yeongyu/comment-checker/package.json")
+    const binaryPath = join(dirname(pkgPath), "bin", binaryName)
+    if (existsSync(binaryPath)) return binaryPath
+  } catch {
+    // intentionally empty - package not installed
+  }
+  return null
+}
+
 export async function checkCommentChecker(): Promise<DependencyInfo> {
   const binaryCheck = await checkBinaryExists("comment-checker")
+  const resolvedPath = binaryCheck.exists ? binaryCheck.path : findCommentCheckerPackageBinary()
 
-  if (!binaryCheck.exists) {
+  if (!resolvedPath) {
     return {
       name: "Comment Checker",
       required: false,
@@ -113,72 +130,14 @@ export async function checkCommentChecker(): Promise<DependencyInfo> {
     }
   }
 
-  const version = await getBinaryVersion("comment-checker")
+  const version = await getBinaryVersion(resolvedPath)
 
   return {
     name: "Comment Checker",
     required: false,
     installed: true,
     version,
-    path: binaryCheck.path,
+    path: resolvedPath,
   }
 }
 
-function dependencyToCheckResult(dep: DependencyInfo, checkName: string): CheckResult {
-  if (dep.installed) {
-    return {
-      name: checkName,
-      status: "pass",
-      message: dep.version ?? "installed",
-      details: dep.path ? [`Path: ${dep.path}`] : undefined,
-    }
-  }
-
-  return {
-    name: checkName,
-    status: "warn",
-    message: "Not installed (optional)",
-    details: dep.installHint ? [dep.installHint] : undefined,
-  }
-}
-
-export async function checkDependencyAstGrepCli(): Promise<CheckResult> {
-  const info = await checkAstGrepCli()
-  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_CLI])
-}
-
-export async function checkDependencyAstGrepNapi(): Promise<CheckResult> {
-  const info = await checkAstGrepNapi()
-  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_NAPI])
-}
-
-export async function checkDependencyCommentChecker(): Promise<CheckResult> {
-  const info = await checkCommentChecker()
-  return dependencyToCheckResult(info, CHECK_NAMES[CHECK_IDS.DEP_COMMENT_CHECKER])
-}
-
-export function getDependencyCheckDefinitions(): CheckDefinition[] {
-  return [
-    {
-      id: CHECK_IDS.DEP_AST_GREP_CLI,
-      name: CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_CLI],
-      category: "dependencies",
-      check: checkDependencyAstGrepCli,
-      critical: false,
-    },
-    {
-      id: CHECK_IDS.DEP_AST_GREP_NAPI,
-      name: CHECK_NAMES[CHECK_IDS.DEP_AST_GREP_NAPI],
-      category: "dependencies",
-      check: checkDependencyAstGrepNapi,
-      critical: false,
-    },
-    {
-      id: CHECK_IDS.DEP_COMMENT_CHECKER,
-      name: CHECK_NAMES[CHECK_IDS.DEP_COMMENT_CHECKER],
-      category: "dependencies",
-      check: checkDependencyCommentChecker,
-      critical: false,
-    },
-  ]
-}

src/cli/doctor/checks/gh.test.ts

@@ -1,151 +0,0 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
-import * as gh from "./gh"
-
-describe("gh cli check", () => {
-  describe("getGhCliInfo", () => {
-    function createProc(opts: { stdout?: string; stderr?: string; exitCode?: number }) {
-      const stdoutText = opts.stdout ?? ""
-      const stderrText = opts.stderr ?? ""
-      const exitCode = opts.exitCode ?? 0
-      const encoder = new TextEncoder()
-
-      return {
-        stdout: new ReadableStream({
-          start(controller) {
-            if (stdoutText) controller.enqueue(encoder.encode(stdoutText))
-            controller.close()
-          },
-        }),
-        stderr: new ReadableStream({
-          start(controller) {
-            if (stderrText) controller.enqueue(encoder.encode(stderrText))
-            controller.close()
-          },
-        }),
-        exited: Promise.resolve(exitCode),
-        exitCode,
-      } as unknown as ReturnType<typeof Bun.spawn>
-    }
-
-    it("returns gh cli info structure", async () => {
-      const spawnSpy = spyOn(Bun, "spawn").mockImplementation((cmd) => {
-        if (Array.isArray(cmd) && (cmd[0] === "which" || cmd[0] === "where") && cmd[1] === "gh") {
-          return createProc({ stdout: "/usr/bin/gh\n" })
-        }
-
-        if (Array.isArray(cmd) && cmd[0] === "gh" && cmd[1] === "--version") {
-          return createProc({ stdout: "gh version 2.40.0\n" })
-        }
-
-        if (Array.isArray(cmd) && cmd[0] === "gh" && cmd[1] === "auth" && cmd[2] === "status") {
-          return createProc({
-            exitCode: 0,
-            stderr: "Logged in to github.com account octocat (keyring)\nToken scopes: 'repo', 'read:org'\n",
-          })
-        }
-
-        throw new Error(`Unexpected Bun.spawn call: ${Array.isArray(cmd) ? cmd.join(" ") : String(cmd)}`)
-      })
-
-      try {
-        const info = await gh.getGhCliInfo()
-
-        expect(info.installed).toBe(true)
-        expect(info.version).toBe("2.40.0")
-        expect(typeof info.authenticated).toBe("boolean")
-        expect(Array.isArray(info.scopes)).toBe(true)
-      } finally {
-        spawnSpy.mockRestore()
-      }
-    })
-  })
-
-  describe("checkGhCli", () => {
-    let getInfoSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      getInfoSpy?.mockRestore()
-    })
-
-    it("returns warn when gh is not installed", async () => {
-      // given gh not installed
-      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
-        installed: false,
-        version: null,
-        path: null,
-        authenticated: false,
-        username: null,
-        scopes: [],
-        error: null,
-      })
-
-      // when checking
-      const result = await gh.checkGhCli()
-
-      // then should warn (optional)
-      expect(result.status).toBe("warn")
-      expect(result.message).toContain("Not installed")
-      expect(result.details).toContain("Install: https://cli.github.com/")
-    })
-
-    it("returns warn when gh is installed but not authenticated", async () => {
-      // given gh installed but not authenticated
-      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
-        installed: true,
-        version: "2.40.0",
-        path: "/usr/local/bin/gh",
-        authenticated: false,
-        username: null,
-        scopes: [],
-        error: "not logged in",
-      })
-
-      // when checking
-      const result = await gh.checkGhCli()
-
-      // then should warn about auth
-      expect(result.status).toBe("warn")
-      expect(result.message).toContain("2.40.0")
-      expect(result.message).toContain("not authenticated")
-      expect(result.details).toContain("Authenticate: gh auth login")
-    })
-
-    it("returns pass when gh is installed and authenticated", async () => {
-      // given gh installed and authenticated
-      getInfoSpy = spyOn(gh, "getGhCliInfo").mockResolvedValue({
-        installed: true,
-        version: "2.40.0",
-        path: "/usr/local/bin/gh",
-        authenticated: true,
-        username: "octocat",
-        scopes: ["repo", "read:org"],
-        error: null,
-      })
-
-      // when checking
-      const result = await gh.checkGhCli()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("2.40.0")
-      expect(result.message).toContain("octocat")
-      expect(result.details).toContain("Account: octocat")
-      expect(result.details).toContain("Scopes: repo, read:org")
-    })
-  })
-
-  describe("getGhCliCheckDefinition", () => {
-    it("returns correct check definition", () => {
-      // given
-      // when getting definition
-      const def = gh.getGhCliCheckDefinition()
-
-      // then should have correct properties
-      expect(def.id).toBe("gh-cli")
-      expect(def.name).toBe("GitHub CLI")
-      expect(def.category).toBe("tools")
-      expect(def.critical).toBe(false)
-      expect(typeof def.check).toBe("function")
-    })
-  })
-})

src/cli/doctor/checks/gh.ts

@@ -1,172 +0,0 @@
-import type { CheckResult, CheckDefinition } from "../types"
-import { CHECK_IDS, CHECK_NAMES } from "../constants"
-
-export interface GhCliInfo {
-  installed: boolean
-  version: string | null
-  path: string | null
-  authenticated: boolean
-  username: string | null
-  scopes: string[]
-  error: string | null
-}
-
-async function checkBinaryExists(binary: string): Promise<{ exists: boolean; path: string | null }> {
-  try {
-    const whichCmd = process.platform === "win32" ? "where" : "which"
-    const proc = Bun.spawn([whichCmd, binary], { stdout: "pipe", stderr: "pipe" })
-    const output = await new Response(proc.stdout).text()
-    await proc.exited
-    if (proc.exitCode === 0) {
-      return { exists: true, path: output.trim() }
-    }
-  } catch {
-    // intentionally empty - binary not found
-  }
-  return { exists: false, path: null }
-}
-
-async function getGhVersion(): Promise<string | null> {
-  try {
-    const proc = Bun.spawn(["gh", "--version"], { stdout: "pipe", stderr: "pipe" })
-    const output = await new Response(proc.stdout).text()
-    await proc.exited
-    if (proc.exitCode === 0) {
-      const match = output.match(/gh version (\S+)/)
-      return match?.[1] ?? output.trim().split("\n")[0]
-    }
-  } catch {
-    // intentionally empty - version unavailable
-  }
-  return null
-}
-
-async function getGhAuthStatus(): Promise<{
-  authenticated: boolean
-  username: string | null
-  scopes: string[]
-  error: string | null
-}> {
-  try {
-    const proc = Bun.spawn(["gh", "auth", "status"], {
-      stdout: "pipe",
-      stderr: "pipe",
-      env: { ...process.env, GH_NO_UPDATE_NOTIFIER: "1" },
-    })
-    const stdout = await new Response(proc.stdout).text()
-    const stderr = await new Response(proc.stderr).text()
-    await proc.exited
-
-    const output = stderr || stdout
-
-    if (proc.exitCode === 0) {
-      const usernameMatch = output.match(/Logged in to github\.com account (\S+)/)
-      const username = usernameMatch?.[1]?.replace(/[()]/g, "") ?? null
-
-      const scopesMatch = output.match(/Token scopes?:\s*(.+)/i)
-      const scopes = scopesMatch?.[1]
-        ? scopesMatch[1]
-            .split(/,\s*/)
-            .map((s) => s.replace(/['"]/g, "").trim())
-            .filter(Boolean)
-        : []
-
-      return { authenticated: true, username, scopes, error: null }
-    }
-
-    const errorMatch = output.match(/error[:\s]+(.+)/i)
-    return {
-      authenticated: false,
-      username: null,
-      scopes: [],
-      error: errorMatch?.[1]?.trim() ?? "Not authenticated",
-    }
-  } catch (err) {
-    return {
-      authenticated: false,
-      username: null,
-      scopes: [],
-      error: err instanceof Error ? err.message : "Failed to check auth status",
-    }
-  }
-}
-
-export async function getGhCliInfo(): Promise<GhCliInfo> {
-  const binaryCheck = await checkBinaryExists("gh")
-
-  if (!binaryCheck.exists) {
-    return {
-      installed: false,
-      version: null,
-      path: null,
-      authenticated: false,
-      username: null,
-      scopes: [],
-      error: null,
-    }
-  }
-
-  const [version, authStatus] = await Promise.all([getGhVersion(), getGhAuthStatus()])
-
-  return {
-    installed: true,
-    version,
-    path: binaryCheck.path,
-    authenticated: authStatus.authenticated,
-    username: authStatus.username,
-    scopes: authStatus.scopes,
-    error: authStatus.error,
-  }
-}
-
-export async function checkGhCli(): Promise<CheckResult> {
-  const info = await getGhCliInfo()
-  const name = CHECK_NAMES[CHECK_IDS.GH_CLI]
-
-  if (!info.installed) {
-    return {
-      name,
-      status: "warn",
-      message: "Not installed (optional)",
-      details: [
-        "GitHub CLI is used by librarian agent and scripts",
-        "Install: https://cli.github.com/",
-      ],
-    }
-  }
-
-  if (!info.authenticated) {
-    return {
-      name,
-      status: "warn",
-      message: `${info.version ?? "installed"} - not authenticated`,
-      details: [
-        info.path ? `Path: ${info.path}` : null,
-        "Authenticate: gh auth login",
-        info.error ? `Error: ${info.error}` : null,
-      ].filter((d): d is string => d !== null),
-    }
-  }
-
-  const details: string[] = []
-  if (info.path) details.push(`Path: ${info.path}`)
-  if (info.username) details.push(`Account: ${info.username}`)
-  if (info.scopes.length > 0) details.push(`Scopes: ${info.scopes.join(", ")}`)
-
-  return {
-    name,
-    status: "pass",
-    message: `${info.version ?? "installed"} - authenticated as ${info.username ?? "unknown"}`,
-    details: details.length > 0 ? details : undefined,
-  }
-}
-
-export function getGhCliCheckDefinition(): CheckDefinition {
-  return {
-    id: CHECK_IDS.GH_CLI,
-    name: CHECK_NAMES[CHECK_IDS.GH_CLI],
-    category: "tools",
-    check: checkGhCli,
-    critical: false,
-  }
-}

src/cli/doctor/checks/index.ts

@@ -1,46 +1,36 @@
 import type { CheckDefinition } from "../types"
-import { getOpenCodeCheckDefinition } from "./opencode"
-import { getPluginCheckDefinition } from "./plugin"
-import { getConfigCheckDefinition } from "./config"
-import { getModelResolutionCheckDefinition } from "./model-resolution"
-import { getAuthCheckDefinitions } from "./auth"
-import { getDependencyCheckDefinitions } from "./dependencies"
-import { getGhCliCheckDefinition } from "./gh"
-import { getLspCheckDefinition } from "./lsp"
-import { getMcpCheckDefinitions } from "./mcp"
-import { getMcpOAuthCheckDefinition } from "./mcp-oauth"
-import { getVersionCheckDefinition } from "./version"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import { checkSystem, gatherSystemInfo } from "./system"
+import { checkConfig } from "./config"
+import { checkTools, gatherToolsSummary } from "./tools"
+import { checkModels } from "./model-resolution"
 
-export * from "./opencode"
-export * from "./plugin"
-export * from "./config"
-export * from "./model-resolution"
+export type { CheckDefinition }
 export * from "./model-resolution-types"
-export * from "./model-resolution-cache"
-export * from "./model-resolution-config"
-export * from "./model-resolution-effective-model"
-export * from "./model-resolution-variant"
-export * from "./model-resolution-details"
-export * from "./auth"
-export * from "./dependencies"
-export * from "./gh"
-export * from "./lsp"
-export * from "./mcp"
-export * from "./mcp-oauth"
-export * from "./version"
+export { gatherSystemInfo, gatherToolsSummary }
 
 export function getAllCheckDefinitions(): CheckDefinition[] {
   return [
-    getOpenCodeCheckDefinition(),
-    getPluginCheckDefinition(),
-    getConfigCheckDefinition(),
-    getModelResolutionCheckDefinition(),
-    ...getAuthCheckDefinitions(),
-    ...getDependencyCheckDefinitions(),
-    getGhCliCheckDefinition(),
-    getLspCheckDefinition(),
-    ...getMcpCheckDefinitions(),
-    getMcpOAuthCheckDefinition(),
-    getVersionCheckDefinition(),
+    {
+      id: CHECK_IDS.SYSTEM,
+      name: CHECK_NAMES[CHECK_IDS.SYSTEM],
+      check: checkSystem,
+      critical: true,
+    },
+    {
+      id: CHECK_IDS.CONFIG,
+      name: CHECK_NAMES[CHECK_IDS.CONFIG],
+      check: checkConfig,
+    },
+    {
+      id: CHECK_IDS.TOOLS,
+      name: CHECK_NAMES[CHECK_IDS.TOOLS],
+      check: checkTools,
+    },
+    {
+      id: CHECK_IDS.MODELS,
+      name: CHECK_NAMES[CHECK_IDS.MODELS],
+      check: checkModels,
+    },
   ]
 }

src/cli/doctor/checks/lsp.test.ts

@@ -1,134 +0,0 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
-import * as lsp from "./lsp"
-import type { LspServerInfo } from "../types"
-
-describe("lsp check", () => {
-  describe("getLspServersInfo", () => {
-    it("returns array of server info", async () => {
-      // given
-      // when getting servers info
-      const servers = await lsp.getLspServersInfo()
-
-      // then should return array with expected structure
-      expect(Array.isArray(servers)).toBe(true)
-      servers.forEach((s) => {
-        expect(s.id).toBeDefined()
-        expect(typeof s.installed).toBe("boolean")
-        expect(Array.isArray(s.extensions)).toBe(true)
-      })
-    })
-
-    it("does not spawn 'which' command (windows compatibility)", async () => {
-      // given
-      const spawnSpy = spyOn(Bun, "spawn")
-
-      try {
-        // when getting servers info
-        await lsp.getLspServersInfo()
-
-        // then should not spawn which
-        const calls = spawnSpy.mock.calls
-        const whichCalls = calls.filter((c) => Array.isArray(c) && Array.isArray(c[0]) && c[0][0] === "which")
-        expect(whichCalls.length).toBe(0)
-      } finally {
-        spawnSpy.mockRestore()
-      }
-    })
-  })
-
-  describe("getLspServerStats", () => {
-    it("counts installed servers correctly", () => {
-      // given servers with mixed installation status
-      const servers = [
-        { id: "ts", installed: true, extensions: [".ts"], source: "builtin" as const },
-        { id: "py", installed: false, extensions: [".py"], source: "builtin" as const },
-        { id: "go", installed: true, extensions: [".go"], source: "builtin" as const },
-      ]
-
-      // when getting stats
-      const stats = lsp.getLspServerStats(servers)
-
-      // then should count correctly
-      expect(stats.installed).toBe(2)
-      expect(stats.total).toBe(3)
-    })
-
-    it("handles empty array", () => {
-      // given no servers
-      const servers: LspServerInfo[] = []
-
-      // when getting stats
-      const stats = lsp.getLspServerStats(servers)
-
-      // then should return zeros
-      expect(stats.installed).toBe(0)
-      expect(stats.total).toBe(0)
-    })
-  })
-
-  describe("checkLspServers", () => {
-    let getServersSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      getServersSpy?.mockRestore()
-    })
-
-    it("returns warn when no servers installed", async () => {
-      // given no servers installed
-      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
-        { id: "typescript-language-server", installed: false, extensions: [".ts"], source: "builtin" },
-        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
-      ])
-
-      // when checking
-      const result = await lsp.checkLspServers()
-
-      // then should warn
-      expect(result.status).toBe("warn")
-      expect(result.message).toContain("No LSP servers")
-    })
-
-    it("returns pass when servers installed", async () => {
-      // given some servers installed
-      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
-        { id: "typescript-language-server", installed: true, extensions: [".ts"], source: "builtin" },
-        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
-      ])
-
-      // when checking
-      const result = await lsp.checkLspServers()
-
-      // then should pass with count
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("1/2")
-    })
-
-    it("lists installed and missing servers in details", async () => {
-      // given mixed installation
-      getServersSpy = spyOn(lsp, "getLspServersInfo").mockResolvedValue([
-        { id: "typescript-language-server", installed: true, extensions: [".ts"], source: "builtin" },
-        { id: "pyright", installed: false, extensions: [".py"], source: "builtin" },
-      ])
-
-      // when checking
-      const result = await lsp.checkLspServers()
-
-      // then should list both
-      expect(result.details?.some((d) => d.includes("Installed"))).toBe(true)
-      expect(result.details?.some((d) => d.includes("Not found"))).toBe(true)
-    })
-  })
-
-  describe("getLspCheckDefinition", () => {
-    it("returns valid check definition", () => {
-      // given
-      // when getting definition
-      const def = lsp.getLspCheckDefinition()
-
-      // then should have required properties
-      expect(def.id).toBe("lsp-servers")
-      expect(def.category).toBe("tools")
-      expect(def.critical).toBe(false)
-    })
-  })
-})

src/cli/doctor/checks/lsp.ts

@@ -1,77 +0,0 @@
-import type { CheckResult, CheckDefinition, LspServerInfo } from "../types"
-import { CHECK_IDS, CHECK_NAMES } from "../constants"
-
-const DEFAULT_LSP_SERVERS: Array<{
-  id: string
-  binary: string
-  extensions: string[]
-}> = [
-  { id: "typescript-language-server", binary: "typescript-language-server", extensions: [".ts", ".tsx", ".js", ".jsx"] },
-  { id: "pyright", binary: "pyright-langserver", extensions: [".py"] },
-  { id: "rust-analyzer", binary: "rust-analyzer", extensions: [".rs"] },
-  { id: "gopls", binary: "gopls", extensions: [".go"] },
-]
-
-import { isServerInstalled } from "../../../tools/lsp/config"
-
-export async function getLspServersInfo(): Promise<LspServerInfo[]> {
-  const servers: LspServerInfo[] = []
-
-  for (const server of DEFAULT_LSP_SERVERS) {
-    const installed = isServerInstalled([server.binary])
-    servers.push({
-      id: server.id,
-      installed,
-      extensions: server.extensions,
-      source: "builtin",
-    })
-  }
-
-  return servers
-}
-
-export function getLspServerStats(servers: LspServerInfo[]): { installed: number; total: number } {
-  const installed = servers.filter((s) => s.installed).length
-  return { installed, total: servers.length }
-}
-
-export async function checkLspServers(): Promise<CheckResult> {
-  const servers = await getLspServersInfo()
-  const stats = getLspServerStats(servers)
-  const installedServers = servers.filter((s) => s.installed)
-  const missingServers = servers.filter((s) => !s.installed)
-
-  if (stats.installed === 0) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
-      status: "warn",
-      message: "No LSP servers detected",
-      details: [
-        "LSP tools will have limited functionality",
-        ...missingServers.map((s) => `Missing: ${s.id}`),
-      ],
-    }
-  }
-
-  const details = [
-    ...installedServers.map((s) => `Installed: ${s.id}`),
-    ...missingServers.map((s) => `Not found: ${s.id} (optional)`),
-  ]
-
-  return {
-    name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
-    status: "pass",
-    message: `${stats.installed}/${stats.total} servers available`,
-    details,
-  }
-}
-
-export function getLspCheckDefinition(): CheckDefinition {
-  return {
-    id: CHECK_IDS.LSP_SERVERS,
-    name: CHECK_NAMES[CHECK_IDS.LSP_SERVERS],
-    category: "tools",
-    check: checkLspServers,
-    critical: false,
-  }
-}

src/cli/doctor/checks/mcp-oauth.test.ts

@@ -1,133 +0,0 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
-import * as mcpOauth from "./mcp-oauth"
-
-describe("mcp-oauth check", () => {
-  describe("getMcpOAuthCheckDefinition", () => {
-    it("returns check definition with correct properties", () => {
-      // given
-      // when getting definition
-      const def = mcpOauth.getMcpOAuthCheckDefinition()
-
-      // then should have correct structure
-      expect(def.id).toBe("mcp-oauth-tokens")
-      expect(def.name).toBe("MCP OAuth Tokens")
-      expect(def.category).toBe("tools")
-      expect(def.critical).toBe(false)
-      expect(typeof def.check).toBe("function")
-    })
-  })
-
-  describe("checkMcpOAuthTokens", () => {
-    let readStoreSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      readStoreSpy?.mockRestore()
-    })
-
-    it("returns skip when no tokens stored", async () => {
-      // given no OAuth tokens configured
-      readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue(null)
-
-      // when checking OAuth tokens
-      const result = await mcpOauth.checkMcpOAuthTokens()
-
-      // then should skip
-      expect(result.status).toBe("skip")
-      expect(result.message).toContain("No OAuth")
-    })
-
-    it("returns pass when all tokens valid", async () => {
-      // given valid tokens with future expiry (expiresAt is in epoch seconds)
-      const futureTime = Math.floor(Date.now() / 1000) + 3600
-      readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue({
-        "example.com/resource1": {
-          accessToken: "token1",
-          expiresAt: futureTime,
-        },
-        "example.com/resource2": {
-          accessToken: "token2",
-          expiresAt: futureTime,
-        },
-      })
-
-      // when checking OAuth tokens
-      const result = await mcpOauth.checkMcpOAuthTokens()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("2")
-      expect(result.message).toContain("valid")
-    })
-
-    it("returns warn when some tokens expired", async () => {
-      // given mix of valid and expired tokens (expiresAt is in epoch seconds)
-      const futureTime = Math.floor(Date.now() / 1000) + 3600
-      const pastTime = Math.floor(Date.now() / 1000) - 3600
-      readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue({
-        "example.com/resource1": {
-          accessToken: "token1",
-          expiresAt: futureTime,
-        },
-        "example.com/resource2": {
-          accessToken: "token2",
-          expiresAt: pastTime,
-        },
-      })
-
-      // when checking OAuth tokens
-      const result = await mcpOauth.checkMcpOAuthTokens()
-
-      // then should warn
-      expect(result.status).toBe("warn")
-      expect(result.message).toContain("1")
-      expect(result.message).toContain("expired")
-      expect(result.details?.some((d: string) => d.includes("Expired"))).toBe(
-        true
-      )
-    })
-
-    it("returns pass when tokens have no expiry", async () => {
-      // given tokens without expiry info
-      readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue({
-        "example.com/resource1": {
-          accessToken: "token1",
-        },
-      })
-
-      // when checking OAuth tokens
-      const result = await mcpOauth.checkMcpOAuthTokens()
-
-      // then should pass (no expiry = assume valid)
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("1")
-    })
-
-    it("includes token details in output", async () => {
-      // given multiple tokens
-      const futureTime = Math.floor(Date.now() / 1000) + 3600
-      readStoreSpy = spyOn(mcpOauth, "readTokenStore").mockReturnValue({
-        "api.example.com/v1": {
-          accessToken: "token1",
-          expiresAt: futureTime,
-        },
-        "auth.example.com/oauth": {
-          accessToken: "token2",
-          expiresAt: futureTime,
-        },
-      })
-
-      // when checking OAuth tokens
-      const result = await mcpOauth.checkMcpOAuthTokens()
-
-      // then should list tokens in details
-      expect(result.details).toBeDefined()
-      expect(result.details?.length).toBeGreaterThan(0)
-      expect(
-        result.details?.some((d: string) => d.includes("api.example.com"))
-      ).toBe(true)
-      expect(
-        result.details?.some((d: string) => d.includes("auth.example.com"))
-      ).toBe(true)
-    })
-  })
-})

src/cli/doctor/checks/mcp-oauth.ts

@@ -1,80 +0,0 @@
-import type { CheckResult, CheckDefinition } from "../types"
-import { CHECK_IDS, CHECK_NAMES } from "../constants"
-import { getMcpOauthStoragePath } from "../../../features/mcp-oauth/storage"
-import { existsSync, readFileSync } from "node:fs"
-
-interface OAuthTokenData {
-  accessToken: string
-  refreshToken?: string
-  expiresAt?: number
-  clientInfo?: {
-    clientId: string
-    clientSecret?: string
-  }
-}
-
-type TokenStore = Record<string, OAuthTokenData>
-
-export function readTokenStore(): TokenStore | null {
-  const filePath = getMcpOauthStoragePath()
-  if (!existsSync(filePath)) {
-    return null
-  }
-
-  try {
-    const content = readFileSync(filePath, "utf-8")
-    return JSON.parse(content) as TokenStore
-  } catch {
-    return null
-  }
-}
-
-export async function checkMcpOAuthTokens(): Promise<CheckResult> {
-  const store = readTokenStore()
-
-  if (!store || Object.keys(store).length === 0) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.MCP_OAUTH_TOKENS],
-      status: "skip",
-      message: "No OAuth tokens configured",
-      details: ["Optional: Configure OAuth tokens for MCP servers"],
-    }
-  }
-
-  const now = Math.floor(Date.now() / 1000)
-  const tokens = Object.entries(store)
-  const expiredTokens = tokens.filter(
-    ([, token]) => token.expiresAt && token.expiresAt < now
-  )
-
-  if (expiredTokens.length > 0) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.MCP_OAUTH_TOKENS],
-      status: "warn",
-      message: `${expiredTokens.length} of ${tokens.length} token(s) expired`,
-      details: [
-        ...tokens
-          .filter(([, token]) => !token.expiresAt || token.expiresAt >= now)
-          .map(([key]) => `Valid: ${key}`),
-        ...expiredTokens.map(([key]) => `Expired: ${key}`),
-      ],
-    }
-  }
-
-  return {
-    name: CHECK_NAMES[CHECK_IDS.MCP_OAUTH_TOKENS],
-    status: "pass",
-    message: `${tokens.length} OAuth token(s) valid`,
-    details: tokens.map(([key]) => `Configured: ${key}`),
-  }
-}
-
-export function getMcpOAuthCheckDefinition(): CheckDefinition {
-  return {
-    id: CHECK_IDS.MCP_OAUTH_TOKENS,
-    name: CHECK_NAMES[CHECK_IDS.MCP_OAUTH_TOKENS],
-    category: "tools",
-    check: checkMcpOAuthTokens,
-    critical: false,
-  }
-}

src/cli/doctor/checks/mcp.test.ts

@@ -1,115 +0,0 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
-import * as mcp from "./mcp"
-
-describe("mcp check", () => {
-  describe("getBuiltinMcpInfo", () => {
-    it("returns builtin servers", () => {
-      // given
-      // when getting builtin info
-      const servers = mcp.getBuiltinMcpInfo()
-
-      // then should include expected servers
-      expect(servers.length).toBe(2)
-      expect(servers.every((s) => s.type === "builtin")).toBe(true)
-      expect(servers.every((s) => s.enabled === true)).toBe(true)
-      expect(servers.map((s) => s.id)).toContain("context7")
-      expect(servers.map((s) => s.id)).toContain("grep_app")
-    })
-  })
-
-  describe("getUserMcpInfo", () => {
-    it("returns empty array when no user config", () => {
-      // given no user config exists
-      // when getting user info
-      const servers = mcp.getUserMcpInfo()
-
-      // then should return array (may be empty)
-      expect(Array.isArray(servers)).toBe(true)
-    })
-  })
-
-  describe("checkBuiltinMcpServers", () => {
-    it("returns pass with server count", async () => {
-      // given
-      // when checking builtin servers
-      const result = await mcp.checkBuiltinMcpServers()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("2")
-      expect(result.message).toContain("enabled")
-    })
-
-    it("lists enabled servers in details", async () => {
-      // given
-      // when checking builtin servers
-      const result = await mcp.checkBuiltinMcpServers()
-
-      // then should list servers
-      expect(result.details?.some((d) => d.includes("context7"))).toBe(true)
-      expect(result.details?.some((d) => d.includes("grep_app"))).toBe(true)
-    })
-  })
-
-  describe("checkUserMcpServers", () => {
-    let getUserSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      getUserSpy?.mockRestore()
-    })
-
-    it("returns skip when no user config", async () => {
-      // given no user servers
-      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([])
-
-      // when checking
-      const result = await mcp.checkUserMcpServers()
-
-      // then should skip
-      expect(result.status).toBe("skip")
-      expect(result.message).toContain("No user MCP")
-    })
-
-    it("returns pass when valid user servers", async () => {
-      // given valid user servers
-      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([
-        { id: "custom-mcp", type: "user", enabled: true, valid: true },
-      ])
-
-      // when checking
-      const result = await mcp.checkUserMcpServers()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("1")
-    })
-
-    it("returns warn when servers have issues", async () => {
-      // given invalid server config
-      getUserSpy = spyOn(mcp, "getUserMcpInfo").mockReturnValue([
-        { id: "bad-mcp", type: "user", enabled: true, valid: false, error: "Missing command" },
-      ])
-
-      // when checking
-      const result = await mcp.checkUserMcpServers()
-
-      // then should warn
-      expect(result.status).toBe("warn")
-      expect(result.details?.some((d) => d.includes("Invalid"))).toBe(true)
-    })
-  })
-
-  describe("getMcpCheckDefinitions", () => {
-    it("returns definitions for builtin and user", () => {
-      // given
-      // when getting definitions
-      const defs = mcp.getMcpCheckDefinitions()
-
-      // then should have 2 definitions
-      expect(defs.length).toBe(2)
-      expect(defs.every((d) => d.category === "tools")).toBe(true)
-      expect(defs.map((d) => d.id)).toContain("mcp-builtin")
-      expect(defs.map((d) => d.id)).toContain("mcp-user")
-    })
-  })
-})

src/cli/doctor/checks/mcp.ts

@@ -1,128 +0,0 @@
-import { existsSync, readFileSync } from "node:fs"
-import { homedir } from "node:os"
-import { join } from "node:path"
-import type { CheckResult, CheckDefinition, McpServerInfo } from "../types"
-import { CHECK_IDS, CHECK_NAMES } from "../constants"
-import { parseJsonc } from "../../../shared"
-
-const BUILTIN_MCP_SERVERS = ["context7", "grep_app"]
-
-const MCP_CONFIG_PATHS = [
-  join(homedir(), ".claude", ".mcp.json"),
-  join(process.cwd(), ".mcp.json"),
-  join(process.cwd(), ".claude", ".mcp.json"),
-]
-
-interface McpConfig {
-  mcpServers?: Record<string, unknown>
-}
-
-function loadUserMcpConfig(): Record<string, unknown> {
-  const servers: Record<string, unknown> = {}
-
-  for (const configPath of MCP_CONFIG_PATHS) {
-    if (!existsSync(configPath)) continue
-
-    try {
-      const content = readFileSync(configPath, "utf-8")
-      const config = parseJsonc<McpConfig>(content)
-      if (config.mcpServers) {
-        Object.assign(servers, config.mcpServers)
-      }
-    } catch {
-      // intentionally empty - skip invalid configs
-    }
-  }
-
-  return servers
-}
-
-export function getBuiltinMcpInfo(): McpServerInfo[] {
-  return BUILTIN_MCP_SERVERS.map((id) => ({
-    id,
-    type: "builtin" as const,
-    enabled: true,
-    valid: true,
-  }))
-}
-
-export function getUserMcpInfo(): McpServerInfo[] {
-  const userServers = loadUserMcpConfig()
-  const servers: McpServerInfo[] = []
-
-  for (const [id, config] of Object.entries(userServers)) {
-    const isValid = typeof config === "object" && config !== null
-    servers.push({
-      id,
-      type: "user",
-      enabled: true,
-      valid: isValid,
-      error: isValid ? undefined : "Invalid configuration format",
-    })
-  }
-
-  return servers
-}
-
-export async function checkBuiltinMcpServers(): Promise<CheckResult> {
-  const servers = getBuiltinMcpInfo()
-
-  return {
-    name: CHECK_NAMES[CHECK_IDS.MCP_BUILTIN],
-    status: "pass",
-    message: `${servers.length} built-in servers enabled`,
-    details: servers.map((s) => `Enabled: ${s.id}`),
-  }
-}
-
-export async function checkUserMcpServers(): Promise<CheckResult> {
-  const servers = getUserMcpInfo()
-
-  if (servers.length === 0) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
-      status: "skip",
-      message: "No user MCP configuration found",
-      details: ["Optional: Add .mcp.json for custom MCP servers"],
-    }
-  }
-
-  const invalidServers = servers.filter((s) => !s.valid)
-  if (invalidServers.length > 0) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
-      status: "warn",
-      message: `${invalidServers.length} server(s) have configuration issues`,
-      details: [
-        ...servers.filter((s) => s.valid).map((s) => `Valid: ${s.id}`),
-        ...invalidServers.map((s) => `Invalid: ${s.id} - ${s.error}`),
-      ],
-    }
-  }
-
-  return {
-    name: CHECK_NAMES[CHECK_IDS.MCP_USER],
-    status: "pass",
-    message: `${servers.length} user server(s) configured`,
-    details: servers.map((s) => `Configured: ${s.id}`),
-  }
-}
-
-export function getMcpCheckDefinitions(): CheckDefinition[] {
-  return [
-    {
-      id: CHECK_IDS.MCP_BUILTIN,
-      name: CHECK_NAMES[CHECK_IDS.MCP_BUILTIN],
-      category: "tools",
-      check: checkBuiltinMcpServers,
-      critical: false,
-    },
-    {
-      id: CHECK_IDS.MCP_USER,
-      name: CHECK_NAMES[CHECK_IDS.MCP_USER],
-      category: "tools",
-      check: checkUserMcpServers,
-      critical: false,
-    },
-  ]
-}

src/cli/doctor/checks/model-resolution.test.ts

@@ -165,16 +165,4 @@ describe("model-resolution check", () => {
     })
   })
 
-  describe("getModelResolutionCheckDefinition", () => {
-    it("returns valid check definition", async () => {
-      const { getModelResolutionCheckDefinition } = await import("./model-resolution")
-
-      const def = getModelResolutionCheckDefinition()
-
-      expect(def.id).toBe("model-resolution")
-      expect(def.name).toBe("Model Resolution")
-      expect(def.category).toBe("configuration")
-      expect(typeof def.check).toBe("function")
-    })
-  })
 })

src/cli/doctor/checks/model-resolution.ts

@@ -1,24 +1,19 @@
-import type { CheckResult, CheckDefinition } from "../types"
+import { AGENT_MODEL_REQUIREMENTS, CATEGORY_MODEL_REQUIREMENTS } from "../../../shared/model-requirements"
 import { CHECK_IDS, CHECK_NAMES } from "../constants"
-import {
-  AGENT_MODEL_REQUIREMENTS,
-  CATEGORY_MODEL_REQUIREMENTS,
-} from "../../../shared/model-requirements"
-import type { OmoConfig, ModelResolutionInfo, AgentResolutionInfo, CategoryResolutionInfo } from "./model-resolution-types"
+import type { CheckResult, DoctorIssue } from "../types"
 import { loadAvailableModelsFromCache } from "./model-resolution-cache"
 import { loadOmoConfig } from "./model-resolution-config"
-import { buildEffectiveResolution, getEffectiveModel } from "./model-resolution-effective-model"
 import { buildModelResolutionDetails } from "./model-resolution-details"
+import { buildEffectiveResolution, getEffectiveModel } from "./model-resolution-effective-model"
+import type { AgentResolutionInfo, CategoryResolutionInfo, ModelResolutionInfo, OmoConfig } from "./model-resolution-types"
 
 export function getModelResolutionInfo(): ModelResolutionInfo {
-  const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(
-    ([name, requirement]) => ({
-      name,
-      requirement,
-      effectiveModel: getEffectiveModel(requirement),
-      effectiveResolution: buildEffectiveResolution(requirement),
-    }),
-  )
+  const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(([name, requirement]) => ({
+    name,
+    requirement,
+    effectiveModel: getEffectiveModel(requirement),
+    effectiveResolution: buildEffectiveResolution(requirement),
+  }))
 
   const categories: CategoryResolutionInfo[] = Object.entries(CATEGORY_MODEL_REQUIREMENTS).map(
     ([name, requirement]) => ({
@@ -26,27 +21,25 @@ export function getModelResolutionInfo(): ModelResolutionInfo {
       requirement,
       effectiveModel: getEffectiveModel(requirement),
       effectiveResolution: buildEffectiveResolution(requirement),
-    }),
+    })
   )
 
   return { agents, categories }
 }
 
 export function getModelResolutionInfoWithOverrides(config: OmoConfig): ModelResolutionInfo {
-  const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(
-    ([name, requirement]) => {
-      const userOverride = config.agents?.[name]?.model
-      const userVariant = config.agents?.[name]?.variant
-      return {
-        name,
-        requirement,
-        userOverride,
-        userVariant,
-        effectiveModel: getEffectiveModel(requirement, userOverride),
-        effectiveResolution: buildEffectiveResolution(requirement, userOverride),
-      }
-    },
-  )
+  const agents: AgentResolutionInfo[] = Object.entries(AGENT_MODEL_REQUIREMENTS).map(([name, requirement]) => {
+    const userOverride = config.agents?.[name]?.model
+    const userVariant = config.agents?.[name]?.variant
+    return {
+      name,
+      requirement,
+      userOverride,
+      userVariant,
+      effectiveModel: getEffectiveModel(requirement, userOverride),
+      effectiveResolution: buildEffectiveResolution(requirement, userOverride),
+    }
+  })
 
   const categories: CategoryResolutionInfo[] = Object.entries(CATEGORY_MODEL_REQUIREMENTS).map(
     ([name, requirement]) => {
@@ -60,40 +53,39 @@ export function getModelResolutionInfoWithOverrides(config: OmoConfig): ModelRes
         effectiveModel: getEffectiveModel(requirement, userOverride),
         effectiveResolution: buildEffectiveResolution(requirement, userOverride),
       }
-    },
+    }
   )
 
   return { agents, categories }
 }
 
-export async function checkModelResolution(): Promise<CheckResult> {
+export async function checkModels(): Promise<CheckResult> {
   const config = loadOmoConfig() ?? {}
   const info = getModelResolutionInfoWithOverrides(config)
   const available = loadAvailableModelsFromCache()
+  const issues: DoctorIssue[] = []
 
-  const agentCount = info.agents.length
-  const categoryCount = info.categories.length
-  const agentOverrides = info.agents.filter((a) => a.userOverride).length
-  const categoryOverrides = info.categories.filter((c) => c.userOverride).length
-  const totalOverrides = agentOverrides + categoryOverrides
+  if (!available.cacheExists) {
+    issues.push({
+      title: "Model cache not found",
+      description: "OpenCode model cache is missing, so model availability cannot be validated.",
+      fix: "Run: opencode models --refresh",
+      severity: "warning",
+      affects: ["model resolution"],
+    })
+  }
 
-  const overrideNote = totalOverrides > 0 ? ` (${totalOverrides} override${totalOverrides > 1 ? "s" : ""})` : ""
-  const cacheNote = available.cacheExists ? `, ${available.modelCount} available` : ", cache not found"
+  const overrideCount =
+    info.agents.filter((agent) => Boolean(agent.userOverride)).length +
+    info.categories.filter((category) => Boolean(category.userOverride)).length
 
   return {
-    name: CHECK_NAMES[CHECK_IDS.MODEL_RESOLUTION],
-    status: available.cacheExists ? "pass" : "warn",
-    message: `${agentCount} agents, ${categoryCount} categories${overrideNote}${cacheNote}`,
+    name: CHECK_NAMES[CHECK_IDS.MODELS],
+    status: issues.length > 0 ? "warn" : "pass",
+    message: `${info.agents.length} agents, ${info.categories.length} categories, ${overrideCount} override${overrideCount === 1 ? "" : "s"}`,
     details: buildModelResolutionDetails({ info, available, config }),
+    issues,
   }
 }
 
-export function getModelResolutionCheckDefinition(): CheckDefinition {
-  return {
-    id: CHECK_IDS.MODEL_RESOLUTION,
-    name: CHECK_NAMES[CHECK_IDS.MODEL_RESOLUTION],
-    category: "configuration",
-    check: checkModelResolution,
-    critical: false,
-  }
-}
+export const checkModelResolution = checkModels

src/cli/doctor/checks/opencode.test.ts

@@ -1,331 +0,0 @@
-import { describe, it, expect, spyOn, beforeEach, afterEach } from "bun:test"
-import * as opencode from "./opencode"
-import { MIN_OPENCODE_VERSION } from "../constants"
-
-describe("opencode check", () => {
-  describe("compareVersions", () => {
-    it("returns true when current >= minimum", () => {
-      // given versions where current is greater
-      // when comparing
-      // then should return true
-      expect(opencode.compareVersions("1.0.200", "1.0.150")).toBe(true)
-      expect(opencode.compareVersions("1.1.0", "1.0.150")).toBe(true)
-      expect(opencode.compareVersions("2.0.0", "1.0.150")).toBe(true)
-    })
-
-    it("returns true when versions are equal", () => {
-      // given equal versions
-      // when comparing
-      // then should return true
-      expect(opencode.compareVersions("1.0.150", "1.0.150")).toBe(true)
-    })
-
-    it("returns false when current < minimum", () => {
-      // given version below minimum
-      // when comparing
-      // then should return false
-      expect(opencode.compareVersions("1.0.100", "1.0.150")).toBe(false)
-      expect(opencode.compareVersions("0.9.0", "1.0.150")).toBe(false)
-    })
-
-    it("handles version prefixes", () => {
-      // given version with v prefix
-      // when comparing
-      // then should strip prefix and compare correctly
-      expect(opencode.compareVersions("v1.0.200", "1.0.150")).toBe(true)
-    })
-
-    it("handles prerelease versions", () => {
-      // given prerelease version
-      // when comparing
-      // then should use base version
-      expect(opencode.compareVersions("1.0.200-beta.1", "1.0.150")).toBe(true)
-    })
-  })
-
-  describe("command helpers", () => {
-    it("selects where on Windows", () => {
-      // given win32 platform
-      // when selecting lookup command
-      // then should use where
-      expect(opencode.getBinaryLookupCommand("win32")).toBe("where")
-    })
-
-    it("selects which on non-Windows", () => {
-      // given linux platform
-      // when selecting lookup command
-      // then should use which
-      expect(opencode.getBinaryLookupCommand("linux")).toBe("which")
-      expect(opencode.getBinaryLookupCommand("darwin")).toBe("which")
-    })
-
-    it("parses command output into paths", () => {
-      // given raw output with multiple lines and spaces
-      const output = "C:\\\\bin\\\\opencode.ps1\r\nC:\\\\bin\\\\opencode.exe\n\n"
-
-      // when parsing
-      const paths = opencode.parseBinaryPaths(output)
-
-      // then should return trimmed, non-empty paths
-      expect(paths).toEqual(["C:\\\\bin\\\\opencode.ps1", "C:\\\\bin\\\\opencode.exe"])
-    })
-
-    it("prefers exe/cmd/bat over ps1 on Windows", () => {
-      // given windows paths
-      const paths = [
-        "C:\\\\bin\\\\opencode.ps1",
-        "C:\\\\bin\\\\opencode.cmd",
-        "C:\\\\bin\\\\opencode.exe",
-      ]
-
-      // when selecting binary
-      const selected = opencode.selectBinaryPath(paths, "win32")
-
-      // then should prefer exe
-      expect(selected).toBe("C:\\\\bin\\\\opencode.exe")
-    })
-
-    it("falls back to ps1 when it is the only Windows candidate", () => {
-      // given only ps1 path
-      const paths = ["C:\\\\bin\\\\opencode.ps1"]
-
-      // when selecting binary
-      const selected = opencode.selectBinaryPath(paths, "win32")
-
-      // then should return ps1 path
-      expect(selected).toBe("C:\\\\bin\\\\opencode.ps1")
-    })
-
-    it("builds PowerShell command for ps1 on Windows", () => {
-      // given a ps1 path on Windows
-      const command = opencode.buildVersionCommand(
-        "C:\\\\bin\\\\opencode.ps1",
-        "win32"
-      )
-
-      // when building command
-      // then should use PowerShell
-      expect(command).toEqual([
-        "powershell",
-        "-NoProfile",
-        "-ExecutionPolicy",
-        "Bypass",
-        "-File",
-        "C:\\\\bin\\\\opencode.ps1",
-        "--version",
-      ])
-    })
-
-    it("builds direct command for non-ps1 binaries", () => {
-      // given an exe on Windows and a binary on linux
-      const winCommand = opencode.buildVersionCommand(
-        "C:\\\\bin\\\\opencode.exe",
-        "win32"
-      )
-      const linuxCommand = opencode.buildVersionCommand("opencode", "linux")
-
-      // when building commands
-      // then should execute directly
-      expect(winCommand).toEqual(["C:\\\\bin\\\\opencode.exe", "--version"])
-      expect(linuxCommand).toEqual(["opencode", "--version"])
-    })
-  })
-
-  describe("getOpenCodeInfo", () => {
-    it("returns installed: false when binary not found", async () => {
-      // given no opencode binary
-      const spy = spyOn(opencode, "findOpenCodeBinary").mockResolvedValue(null)
-
-      // when getting info
-      const info = await opencode.getOpenCodeInfo()
-
-      // then should indicate not installed
-      expect(info.installed).toBe(false)
-      expect(info.version).toBeNull()
-      expect(info.path).toBeNull()
-      expect(info.binary).toBeNull()
-
-      spy.mockRestore()
-    })
-  })
-
-  describe("checkOpenCodeInstallation", () => {
-    let getInfoSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      getInfoSpy?.mockRestore()
-    })
-
-    it("returns fail when not installed", async () => {
-      // given opencode not installed
-      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
-        installed: false,
-        version: null,
-        path: null,
-        binary: null,
-      })
-
-      // when checking installation
-      const result = await opencode.checkOpenCodeInstallation()
-
-      // then should fail with installation hint
-      expect(result.status).toBe("fail")
-      expect(result.message).toContain("not installed")
-      expect(result.details).toBeDefined()
-      expect(result.details?.some((d) => d.includes("opencode.ai"))).toBe(true)
-    })
-
-    it("returns warn when version below minimum", async () => {
-      // given old version installed
-      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
-        installed: true,
-        version: "1.0.100",
-        path: "/usr/local/bin/opencode",
-        binary: "opencode",
-      })
-
-      // when checking installation
-      const result = await opencode.checkOpenCodeInstallation()
-
-      // then should warn about old version
-      expect(result.status).toBe("warn")
-      expect(result.message).toContain("below minimum")
-      expect(result.details?.some((d) => d.includes(MIN_OPENCODE_VERSION))).toBe(true)
-    })
-
-    it("returns pass when properly installed", async () => {
-      // given current version installed
-      getInfoSpy = spyOn(opencode, "getOpenCodeInfo").mockResolvedValue({
-        installed: true,
-        version: "1.0.200",
-        path: "/usr/local/bin/opencode",
-        binary: "opencode",
-      })
-
-      // when checking installation
-      const result = await opencode.checkOpenCodeInstallation()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("1.0.200")
-    })
-  })
-
-  describe("getOpenCodeCheckDefinition", () => {
-    it("returns valid check definition", () => {
-      // given
-      // when getting definition
-      const def = opencode.getOpenCodeCheckDefinition()
-
-      // then should have required properties
-      expect(def.id).toBe("opencode-installation")
-      expect(def.category).toBe("installation")
-      expect(def.critical).toBe(true)
-      expect(typeof def.check).toBe("function")
-    })
-  })
-
-  describe("getDesktopAppPaths", () => {
-    it("returns macOS desktop app paths for darwin platform", () => {
-      // given darwin platform
-      const platform: NodeJS.Platform = "darwin"
-
-      // when getting desktop paths
-      const paths = opencode.getDesktopAppPaths(platform)
-
-      // then should include macOS app bundle paths with correct binary name
-      expect(paths).toContain("/Applications/OpenCode.app/Contents/MacOS/OpenCode")
-      expect(paths.some((p) => p.includes("Applications/OpenCode.app"))).toBe(true)
-    })
-
-    it("returns Windows desktop app paths for win32 platform when env vars set", () => {
-      // given win32 platform with env vars set
-      const platform: NodeJS.Platform = "win32"
-      const originalProgramFiles = process.env.ProgramFiles
-      const originalLocalAppData = process.env.LOCALAPPDATA
-      process.env.ProgramFiles = "C:\\Program Files"
-      process.env.LOCALAPPDATA = "C:\\Users\\Test\\AppData\\Local"
-
-      // when getting desktop paths
-      const paths = opencode.getDesktopAppPaths(platform)
-
-      // then should include Windows program paths with correct binary name
-      expect(paths.some((p) => p.includes("Program Files"))).toBe(true)
-      expect(paths.some((p) => p.endsWith("OpenCode.exe"))).toBe(true)
-      expect(paths.every((p) => p.startsWith("C:\\"))).toBe(true)
-
-      // cleanup
-      process.env.ProgramFiles = originalProgramFiles
-      process.env.LOCALAPPDATA = originalLocalAppData
-    })
-
-    it("returns empty array for win32 when all env vars undefined", () => {
-      // given win32 platform with no env vars
-      const platform: NodeJS.Platform = "win32"
-      const originalProgramFiles = process.env.ProgramFiles
-      const originalLocalAppData = process.env.LOCALAPPDATA
-      delete process.env.ProgramFiles
-      delete process.env.LOCALAPPDATA
-
-      // when getting desktop paths
-      const paths = opencode.getDesktopAppPaths(platform)
-
-      // then should return empty array (no relative paths)
-      expect(paths).toEqual([])
-
-      // cleanup
-      process.env.ProgramFiles = originalProgramFiles
-      process.env.LOCALAPPDATA = originalLocalAppData
-    })
-
-    it("returns Linux desktop app paths for linux platform", () => {
-      // given linux platform
-      const platform: NodeJS.Platform = "linux"
-
-      // when getting desktop paths
-      const paths = opencode.getDesktopAppPaths(platform)
-
-      // then should include verified Linux installation paths
-      expect(paths).toContain("/usr/bin/opencode")
-      expect(paths).toContain("/usr/lib/opencode/opencode")
-      expect(paths.some((p) => p.includes("AppImage"))).toBe(true)
-    })
-
-    it("returns empty array for unsupported platforms", () => {
-      // given unsupported platform
-      const platform = "freebsd" as NodeJS.Platform
-
-      // when getting desktop paths
-      const paths = opencode.getDesktopAppPaths(platform)
-
-      // then should return empty array
-      expect(paths).toEqual([])
-    })
-  })
-
-  describe("findOpenCodeBinary with desktop fallback", () => {
-    it("falls back to desktop paths when PATH binary not found", async () => {
-      // given no binary in PATH but desktop app exists
-      const existsSyncMock = (p: string) =>
-        p === "/Applications/OpenCode.app/Contents/MacOS/OpenCode"
-
-      // when finding binary with mocked filesystem
-      const result = await opencode.findDesktopBinary("darwin", existsSyncMock)
-
-      // then should find desktop app
-      expect(result).not.toBeNull()
-      expect(result?.path).toBe("/Applications/OpenCode.app/Contents/MacOS/OpenCode")
-    })
-
-    it("returns null when no desktop binary found", async () => {
-      // given no binary exists
-      const existsSyncMock = () => false
-
-      // when finding binary
-      const result = await opencode.findDesktopBinary("darwin", existsSyncMock)
-
-      // then should return null
-      expect(result).toBeNull()
-    })
-  })
-})

src/cli/doctor/checks/opencode.ts

@@ -1,227 +0,0 @@
-import { existsSync } from "node:fs"
-import { homedir } from "node:os"
-import { join } from "node:path"
-import type { CheckResult, CheckDefinition, OpenCodeInfo } from "../types"
-import { CHECK_IDS, CHECK_NAMES, MIN_OPENCODE_VERSION, OPENCODE_BINARIES } from "../constants"
-
-const WINDOWS_EXECUTABLE_EXTS = [".exe", ".cmd", ".bat", ".ps1"]
-
-export function getDesktopAppPaths(platform: NodeJS.Platform): string[] {
-  const home = homedir()
-
-  switch (platform) {
-    case "darwin":
-      return [
-        "/Applications/OpenCode.app/Contents/MacOS/OpenCode",
-        join(home, "Applications", "OpenCode.app", "Contents", "MacOS", "OpenCode"),
-      ]
-    case "win32": {
-      const programFiles = process.env.ProgramFiles
-      const localAppData = process.env.LOCALAPPDATA
-
-      const paths: string[] = []
-      if (programFiles) {
-        paths.push(join(programFiles, "OpenCode", "OpenCode.exe"))
-      }
-      if (localAppData) {
-        paths.push(join(localAppData, "OpenCode", "OpenCode.exe"))
-      }
-      return paths
-    }
-    case "linux":
-      return [
-        "/usr/bin/opencode",
-        "/usr/lib/opencode/opencode",
-        join(home, "Applications", "opencode-desktop-linux-x86_64.AppImage"),
-        join(home, "Applications", "opencode-desktop-linux-aarch64.AppImage"),
-      ]
-    default:
-      return []
-  }
-}
-
-export function getBinaryLookupCommand(platform: NodeJS.Platform): "which" | "where" {
-  return platform === "win32" ? "where" : "which"
-}
-
-export function parseBinaryPaths(output: string): string[] {
-  return output
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0)
-}
-
-export function selectBinaryPath(
-  paths: string[],
-  platform: NodeJS.Platform
-): string | null {
-  if (paths.length === 0) return null
-  if (platform !== "win32") return paths[0]
-
-  const normalized = paths.map((path) => path.toLowerCase())
-  for (const ext of WINDOWS_EXECUTABLE_EXTS) {
-    const index = normalized.findIndex((path) => path.endsWith(ext))
-    if (index !== -1) return paths[index]
-  }
-
-  return paths[0]
-}
-
-export function buildVersionCommand(
-  binaryPath: string,
-  platform: NodeJS.Platform
-): string[] {
-  if (
-    platform === "win32" &&
-    binaryPath.toLowerCase().endsWith(".ps1")
-  ) {
-    return [
-      "powershell",
-      "-NoProfile",
-      "-ExecutionPolicy",
-      "Bypass",
-      "-File",
-      binaryPath,
-      "--version",
-    ]
-  }
-
-  return [binaryPath, "--version"]
-}
-
-export function findDesktopBinary(
-  platform: NodeJS.Platform = process.platform,
-  checkExists: (path: string) => boolean = existsSync
-): { binary: string; path: string } | null {
-  const desktopPaths = getDesktopAppPaths(platform)
-  for (const desktopPath of desktopPaths) {
-    if (checkExists(desktopPath)) {
-      return { binary: "opencode", path: desktopPath }
-    }
-  }
-  return null
-}
-
-export async function findOpenCodeBinary(): Promise<{ binary: string; path: string } | null> {
-  for (const binary of OPENCODE_BINARIES) {
-    try {
-      const path = Bun.which(binary)
-      if (path) {
-        return { binary, path }
-      }
-    } catch {
-      continue
-    }
-  }
-
-  const desktopResult = findDesktopBinary()
-  if (desktopResult) {
-    return desktopResult
-  }
-
-  return null
-}
-
-export async function getOpenCodeVersion(
-  binaryPath: string,
-  platform: NodeJS.Platform = process.platform
-): Promise<string | null> {
-  try {
-    const command = buildVersionCommand(binaryPath, platform)
-    const proc = Bun.spawn(command, { stdout: "pipe", stderr: "pipe" })
-    const output = await new Response(proc.stdout).text()
-    await proc.exited
-    if (proc.exitCode === 0) {
-      return output.trim()
-    }
-  } catch {
-    return null
-  }
-  return null
-}
-
-export function compareVersions(current: string, minimum: string): boolean {
-  const parseVersion = (v: string): number[] => {
-    const cleaned = v.replace(/^v/, "").split("-")[0]
-    return cleaned.split(".").map((n) => parseInt(n, 10) || 0)
-  }
-
-  const curr = parseVersion(current)
-  const min = parseVersion(minimum)
-
-  for (let i = 0; i < Math.max(curr.length, min.length); i++) {
-    const c = curr[i] ?? 0
-    const m = min[i] ?? 0
-    if (c > m) return true
-    if (c < m) return false
-  }
-  return true
-}
-
-export async function getOpenCodeInfo(): Promise<OpenCodeInfo> {
-  const binaryInfo = await findOpenCodeBinary()
-
-  if (!binaryInfo) {
-    return {
-      installed: false,
-      version: null,
-      path: null,
-      binary: null,
-    }
-  }
-
-  const version = await getOpenCodeVersion(binaryInfo.path ?? binaryInfo.binary)
-
-  return {
-    installed: true,
-    version,
-    path: binaryInfo.path,
-    binary: binaryInfo.binary as "opencode" | "opencode-desktop",
-  }
-}
-
-export async function checkOpenCodeInstallation(): Promise<CheckResult> {
-  const info = await getOpenCodeInfo()
-
-  if (!info.installed) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
-      status: "fail",
-      message: "OpenCode is not installed",
-      details: [
-        "Visit: https://opencode.ai/docs for installation instructions",
-        "Run: npm install -g opencode",
-      ],
-    }
-  }
-
-  if (info.version && !compareVersions(info.version, MIN_OPENCODE_VERSION)) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
-      status: "warn",
-      message: `Version ${info.version} is below minimum ${MIN_OPENCODE_VERSION}`,
-      details: [
-        `Current: ${info.version}`,
-        `Required: >= ${MIN_OPENCODE_VERSION}`,
-        "Run: npm update -g opencode",
-      ],
-    }
-  }
-
-  return {
-    name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
-    status: "pass",
-    message: info.version ?? "installed",
-    details: info.path ? [`Path: ${info.path}`] : undefined,
-  }
-}
-
-export function getOpenCodeCheckDefinition(): CheckDefinition {
-  return {
-    id: CHECK_IDS.OPENCODE_INSTALLATION,
-    name: CHECK_NAMES[CHECK_IDS.OPENCODE_INSTALLATION],
-    category: "installation",
-    check: checkOpenCodeInstallation,
-    critical: true,
-  }
-}

src/cli/doctor/checks/plugin.test.ts

@@ -1,109 +0,0 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
-import * as plugin from "./plugin"
-
-describe("plugin check", () => {
-  describe("getPluginInfo", () => {
-    it("returns registered: false when config not found", () => {
-      // given no config file exists
-      // when getting plugin info
-      // then should indicate not registered
-      const info = plugin.getPluginInfo()
-      expect(typeof info.registered).toBe("boolean")
-      expect(typeof info.isPinned).toBe("boolean")
-    })
-  })
-
-  describe("checkPluginRegistration", () => {
-    let getInfoSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      getInfoSpy?.mockRestore()
-    })
-
-    it("returns fail when config file not found", async () => {
-      // given no config file
-      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
-        registered: false,
-        configPath: null,
-        entry: null,
-        isPinned: false,
-        pinnedVersion: null,
-      })
-
-      // when checking registration
-      const result = await plugin.checkPluginRegistration()
-
-      // then should fail with hint
-      expect(result.status).toBe("fail")
-      expect(result.message).toContain("not found")
-    })
-
-    it("returns fail when plugin not registered", async () => {
-      // given config exists but plugin not registered
-      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
-        registered: false,
-        configPath: "/home/user/.config/opencode/opencode.json",
-        entry: null,
-        isPinned: false,
-        pinnedVersion: null,
-      })
-
-      // when checking registration
-      const result = await plugin.checkPluginRegistration()
-
-      // then should fail
-      expect(result.status).toBe("fail")
-      expect(result.message).toContain("not registered")
-    })
-
-    it("returns pass when plugin registered", async () => {
-      // given plugin registered
-      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
-        registered: true,
-        configPath: "/home/user/.config/opencode/opencode.json",
-        entry: "oh-my-opencode",
-        isPinned: false,
-        pinnedVersion: null,
-      })
-
-      // when checking registration
-      const result = await plugin.checkPluginRegistration()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("Registered")
-    })
-
-    it("indicates pinned version when applicable", async () => {
-      // given plugin pinned to version
-      getInfoSpy = spyOn(plugin, "getPluginInfo").mockReturnValue({
-        registered: true,
-        configPath: "/home/user/.config/opencode/opencode.json",
-        entry: "oh-my-opencode@2.7.0",
-        isPinned: true,
-        pinnedVersion: "2.7.0",
-      })
-
-      // when checking registration
-      const result = await plugin.checkPluginRegistration()
-
-      // then should show pinned version
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("pinned")
-      expect(result.message).toContain("2.7.0")
-    })
-  })
-
-  describe("getPluginCheckDefinition", () => {
-    it("returns valid check definition", () => {
-      // given
-      // when getting definition
-      const def = plugin.getPluginCheckDefinition()
-
-      // then should have required properties
-      expect(def.id).toBe("plugin-registration")
-      expect(def.category).toBe("installation")
-      expect(def.critical).toBe(true)
-    })
-  })
-})

src/cli/doctor/checks/plugin.ts

@@ -1,127 +0,0 @@
-import { existsSync, readFileSync } from "node:fs"
-import type { CheckResult, CheckDefinition, PluginInfo } from "../types"
-import { CHECK_IDS, CHECK_NAMES, PACKAGE_NAME } from "../constants"
-import { parseJsonc, getOpenCodeConfigPaths } from "../../../shared"
-
-function detectConfigPath(): { path: string; format: "json" | "jsonc" } | null {
-  const paths = getOpenCodeConfigPaths({ binary: "opencode", version: null })
-
-  if (existsSync(paths.configJsonc)) {
-    return { path: paths.configJsonc, format: "jsonc" }
-  }
-  if (existsSync(paths.configJson)) {
-    return { path: paths.configJson, format: "json" }
-  }
-  return null
-}
-
-function findPluginEntry(plugins: string[]): { entry: string; isPinned: boolean; version: string | null } | null {
-  for (const plugin of plugins) {
-    if (plugin === PACKAGE_NAME || plugin.startsWith(`${PACKAGE_NAME}@`)) {
-      const isPinned = plugin.includes("@")
-      const version = isPinned ? plugin.split("@")[1] : null
-      return { entry: plugin, isPinned, version }
-    }
-    if (plugin.startsWith("file://") && plugin.includes(PACKAGE_NAME)) {
-      return { entry: plugin, isPinned: false, version: "local-dev" }
-    }
-  }
-  return null
-}
-
-export function getPluginInfo(): PluginInfo {
-  const configInfo = detectConfigPath()
-
-  if (!configInfo) {
-    return {
-      registered: false,
-      configPath: null,
-      entry: null,
-      isPinned: false,
-      pinnedVersion: null,
-    }
-  }
-
-  try {
-    const content = readFileSync(configInfo.path, "utf-8")
-    const config = parseJsonc<{ plugin?: string[] }>(content)
-    const plugins = config.plugin ?? []
-    const pluginEntry = findPluginEntry(plugins)
-
-    if (!pluginEntry) {
-      return {
-        registered: false,
-        configPath: configInfo.path,
-        entry: null,
-        isPinned: false,
-        pinnedVersion: null,
-      }
-    }
-
-    return {
-      registered: true,
-      configPath: configInfo.path,
-      entry: pluginEntry.entry,
-      isPinned: pluginEntry.isPinned,
-      pinnedVersion: pluginEntry.version,
-    }
-  } catch {
-    return {
-      registered: false,
-      configPath: configInfo.path,
-      entry: null,
-      isPinned: false,
-      pinnedVersion: null,
-    }
-  }
-}
-
-export async function checkPluginRegistration(): Promise<CheckResult> {
-  const info = getPluginInfo()
-
-  if (!info.configPath) {
-    const expectedPaths = getOpenCodeConfigPaths({ binary: "opencode", version: null })
-    return {
-      name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
-      status: "fail",
-      message: "OpenCode config file not found",
-      details: [
-        "Run: bunx oh-my-opencode install",
-        `Expected: ${expectedPaths.configJson} or ${expectedPaths.configJsonc}`,
-      ],
-    }
-  }
-
-  if (!info.registered) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
-      status: "fail",
-      message: "Plugin not registered in config",
-      details: [
-        "Run: bunx oh-my-opencode install",
-        `Config: ${info.configPath}`,
-      ],
-    }
-  }
-
-  const message = info.isPinned
-    ? `Registered (pinned: ${info.pinnedVersion})`
-    : "Registered"
-
-  return {
-    name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
-    status: "pass",
-    message,
-    details: [`Config: ${info.configPath}`],
-  }
-}
-
-export function getPluginCheckDefinition(): CheckDefinition {
-  return {
-    id: CHECK_IDS.PLUGIN_REGISTRATION,
-    name: CHECK_NAMES[CHECK_IDS.PLUGIN_REGISTRATION],
-    category: "installation",
-    check: checkPluginRegistration,
-    critical: true,
-  }
-}

src/cli/doctor/checks/system-binary.ts

@@ -0,0 +1,144 @@
+import { existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+import { OPENCODE_BINARIES } from "../constants"
+
+const WINDOWS_EXECUTABLE_EXTS = [".exe", ".cmd", ".bat", ".ps1"]
+
+export interface OpenCodeBinaryInfo {
+  binary: string
+  path: string
+}
+
+export function getDesktopAppPaths(platform: NodeJS.Platform): string[] {
+  const home = homedir()
+
+  switch (platform) {
+    case "darwin":
+      return [
+        "/Applications/OpenCode.app/Contents/MacOS/OpenCode",
+        join(home, "Applications", "OpenCode.app", "Contents", "MacOS", "OpenCode"),
+      ]
+    case "win32": {
+      const programFiles = process.env.ProgramFiles
+      const localAppData = process.env.LOCALAPPDATA
+      const paths: string[] = []
+
+      if (programFiles) {
+        paths.push(join(programFiles, "OpenCode", "OpenCode.exe"))
+      }
+      if (localAppData) {
+        paths.push(join(localAppData, "OpenCode", "OpenCode.exe"))
+      }
+
+      return paths
+    }
+    case "linux":
+      return [
+        "/usr/bin/opencode",
+        "/usr/lib/opencode/opencode",
+        join(home, "Applications", "opencode-desktop-linux-x86_64.AppImage"),
+        join(home, "Applications", "opencode-desktop-linux-aarch64.AppImage"),
+      ]
+    default:
+      return []
+  }
+}
+
+export function getBinaryLookupCommand(platform: NodeJS.Platform): "which" | "where" {
+  return platform === "win32" ? "where" : "which"
+}
+
+export function parseBinaryPaths(output: string): string[] {
+  return output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+}
+
+export function selectBinaryPath(paths: string[], platform: NodeJS.Platform): string | null {
+  if (paths.length === 0) return null
+  if (platform !== "win32") return paths[0] ?? null
+
+  const normalizedPaths = paths.map((path) => path.toLowerCase())
+  for (const extension of WINDOWS_EXECUTABLE_EXTS) {
+    const pathIndex = normalizedPaths.findIndex((path) => path.endsWith(extension))
+    if (pathIndex !== -1) {
+      return paths[pathIndex] ?? null
+    }
+  }
+
+  return paths[0] ?? null
+}
+
+export function buildVersionCommand(binaryPath: string, platform: NodeJS.Platform): string[] {
+  if (platform === "win32" && binaryPath.toLowerCase().endsWith(".ps1")) {
+    return ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", binaryPath, "--version"]
+  }
+
+  return [binaryPath, "--version"]
+}
+
+export function findDesktopBinary(
+  platform: NodeJS.Platform = process.platform,
+  checkExists: (path: string) => boolean = existsSync
+): OpenCodeBinaryInfo | null {
+  for (const desktopPath of getDesktopAppPaths(platform)) {
+    if (checkExists(desktopPath)) {
+      return { binary: "opencode", path: desktopPath }
+    }
+  }
+
+  return null
+}
+
+export async function findOpenCodeBinary(): Promise<OpenCodeBinaryInfo | null> {
+  for (const binary of OPENCODE_BINARIES) {
+    const path = Bun.which(binary)
+    if (path) {
+      return { binary, path }
+    }
+  }
+
+  return findDesktopBinary()
+}
+
+export async function getOpenCodeVersion(
+  binaryPath: string,
+  platform: NodeJS.Platform = process.platform
+): Promise<string | null> {
+  try {
+    const command = buildVersionCommand(binaryPath, platform)
+    const processResult = Bun.spawn(command, { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(processResult.stdout).text()
+    await processResult.exited
+
+    if (processResult.exitCode !== 0) return null
+    return output.trim() || null
+  } catch {
+    return null
+  }
+}
+
+export function compareVersions(current: string, minimum: string): boolean {
+  const parseVersion = (version: string): number[] =>
+    version
+      .replace(/^v/, "")
+      .split("-")[0]
+      .split(".")
+      .map((part) => Number.parseInt(part, 10) || 0)
+
+  const currentParts = parseVersion(current)
+  const minimumParts = parseVersion(minimum)
+  const length = Math.max(currentParts.length, minimumParts.length)
+
+  for (let index = 0; index < length; index++) {
+    const currentPart = currentParts[index] ?? 0
+    const minimumPart = minimumParts[index] ?? 0
+    if (currentPart > minimumPart) return true
+    if (currentPart < minimumPart) return false
+  }
+
+  return true
+}

src/cli/doctor/checks/system-loaded-version.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+import { getLatestVersion } from "../../../hooks/auto-update-checker/checker"
+import { extractChannel } from "../../../hooks/auto-update-checker"
+import { PACKAGE_NAME } from "../constants"
+import { getOpenCodeCacheDir, parseJsonc } from "../../../shared"
+
+interface PackageJsonShape {
+  version?: string
+  dependencies?: Record<string, string>
+}
+
+export interface LoadedVersionInfo {
+  cacheDir: string
+  cachePackagePath: string
+  installedPackagePath: string
+  expectedVersion: string | null
+  loadedVersion: string | null
+}
+
+function getPlatformDefaultCacheDir(platform: NodeJS.Platform = process.platform): string {
+  if (platform === "darwin") return join(homedir(), "Library", "Caches")
+  if (platform === "win32") return process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local")
+  return join(homedir(), ".cache")
+}
+
+function resolveOpenCodeCacheDir(): string {
+  const xdgCacheHome = process.env.XDG_CACHE_HOME
+  if (xdgCacheHome) return join(xdgCacheHome, "opencode")
+
+  const fromShared = getOpenCodeCacheDir()
+  const platformDefault = join(getPlatformDefaultCacheDir(), "opencode")
+  if (existsSync(fromShared) || !existsSync(platformDefault)) return fromShared
+  return platformDefault
+}
+
+function readPackageJson(filePath: string): PackageJsonShape | null {
+  if (!existsSync(filePath)) return null
+
+  try {
+    const content = readFileSync(filePath, "utf-8")
+    return parseJsonc<PackageJsonShape>(content)
+  } catch {
+    return null
+  }
+}
+
+function normalizeVersion(value: string | undefined): string | null {
+  if (!value) return null
+  const match = value.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/)
+  return match?.[0] ?? null
+}
+
+export function getLoadedPluginVersion(): LoadedVersionInfo {
+  const cacheDir = resolveOpenCodeCacheDir()
+  const cachePackagePath = join(cacheDir, "package.json")
+  const installedPackagePath = join(cacheDir, "node_modules", PACKAGE_NAME, "package.json")
+
+  const cachePackage = readPackageJson(cachePackagePath)
+  const installedPackage = readPackageJson(installedPackagePath)
+
+  const expectedVersion = normalizeVersion(cachePackage?.dependencies?.[PACKAGE_NAME])
+  const loadedVersion = normalizeVersion(installedPackage?.version)
+
+  return {
+    cacheDir,
+    cachePackagePath,
+    installedPackagePath,
+    expectedVersion,
+    loadedVersion,
+  }
+}
+
+export async function getLatestPluginVersion(currentVersion: string | null): Promise<string | null> {
+  const channel = extractChannel(currentVersion)
+  return getLatestVersion(channel)
+}

src/cli/doctor/checks/system-plugin.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from "node:fs"
+
+import { PACKAGE_NAME } from "../constants"
+import { getOpenCodeConfigPaths, parseJsonc } from "../../../shared"
+
+export interface PluginInfo {
+  registered: boolean
+  configPath: string | null
+  entry: string | null
+  isPinned: boolean
+  pinnedVersion: string | null
+  isLocalDev: boolean
+}
+
+interface OpenCodeConfigShape {
+  plugin?: string[]
+}
+
+function detectConfigPath(): string | null {
+  const paths = getOpenCodeConfigPaths({ binary: "opencode", version: null })
+  if (existsSync(paths.configJsonc)) return paths.configJsonc
+  if (existsSync(paths.configJson)) return paths.configJson
+  return null
+}
+
+function parsePluginVersion(entry: string): string | null {
+  if (!entry.startsWith(`${PACKAGE_NAME}@`)) return null
+  const value = entry.slice(PACKAGE_NAME.length + 1)
+  if (!value || value === "latest") return null
+  return value
+}
+
+function findPluginEntry(entries: string[]): { entry: string; isLocalDev: boolean } | null {
+  for (const entry of entries) {
+    if (entry === PACKAGE_NAME || entry.startsWith(`${PACKAGE_NAME}@`)) {
+      return { entry, isLocalDev: false }
+    }
+    if (entry.startsWith("file://") && entry.includes(PACKAGE_NAME)) {
+      return { entry, isLocalDev: true }
+    }
+  }
+
+  return null
+}
+
+export function getPluginInfo(): PluginInfo {
+  const configPath = detectConfigPath()
+  if (!configPath) {
+    return {
+      registered: false,
+      configPath: null,
+      entry: null,
+      isPinned: false,
+      pinnedVersion: null,
+      isLocalDev: false,
+    }
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8")
+    const parsedConfig = parseJsonc<OpenCodeConfigShape>(content)
+    const pluginEntry = findPluginEntry(parsedConfig.plugin ?? [])
+    if (!pluginEntry) {
+      return {
+        registered: false,
+        configPath,
+        entry: null,
+        isPinned: false,
+        pinnedVersion: null,
+        isLocalDev: false,
+      }
+    }
+
+    const pinnedVersion = parsePluginVersion(pluginEntry.entry)
+    return {
+      registered: true,
+      configPath,
+      entry: pluginEntry.entry,
+      isPinned: pinnedVersion !== null,
+      pinnedVersion,
+      isLocalDev: pluginEntry.isLocalDev,
+    }
+  } catch {
+    return {
+      registered: false,
+      configPath,
+      entry: null,
+      isPinned: false,
+      pinnedVersion: null,
+      isLocalDev: false,
+    }
+  }
+}
+
+export { detectConfigPath, findPluginEntry }

src/cli/doctor/checks/system.ts

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from "node:fs"
+
+import { MIN_OPENCODE_VERSION, CHECK_IDS, CHECK_NAMES } from "../constants"
+import type { CheckResult, DoctorIssue, SystemInfo } from "../types"
+import { findOpenCodeBinary, getOpenCodeVersion, compareVersions } from "./system-binary"
+import { getPluginInfo } from "./system-plugin"
+import { getLatestPluginVersion, getLoadedPluginVersion } from "./system-loaded-version"
+import { parseJsonc } from "../../../shared"
+
+function isConfigValid(configPath: string | null): boolean {
+  if (!configPath) return true
+  if (!existsSync(configPath)) return false
+
+  try {
+    parseJsonc<Record<string, unknown>>(readFileSync(configPath, "utf-8"))
+    return true
+  } catch {
+    return false
+  }
+}
+
+function getResultStatus(issues: DoctorIssue[]): CheckResult["status"] {
+  if (issues.some((issue) => issue.severity === "error")) return "fail"
+  if (issues.some((issue) => issue.severity === "warning")) return "warn"
+  return "pass"
+}
+
+function buildMessage(status: CheckResult["status"], issues: DoctorIssue[]): string {
+  if (status === "pass") return "System checks passed"
+  if (status === "fail") return `${issues.length} system issue(s) detected`
+  return `${issues.length} system warning(s) detected`
+}
+
+export async function gatherSystemInfo(): Promise<SystemInfo> {
+  const [binaryInfo, pluginInfo] = await Promise.all([findOpenCodeBinary(), Promise.resolve(getPluginInfo())])
+  const loadedInfo = getLoadedPluginVersion()
+
+  const opencodeVersion = binaryInfo ? await getOpenCodeVersion(binaryInfo.path) : null
+  const pluginVersion = pluginInfo.pinnedVersion ?? loadedInfo.expectedVersion
+
+  return {
+    opencodeVersion,
+    opencodePath: binaryInfo?.path ?? null,
+    pluginVersion,
+    loadedVersion: loadedInfo.loadedVersion,
+    bunVersion: Bun.version,
+    configPath: pluginInfo.configPath,
+    configValid: isConfigValid(pluginInfo.configPath),
+    isLocalDev: pluginInfo.isLocalDev,
+  }
+}
+
+export async function checkSystem(): Promise<CheckResult> {
+  const [systemInfo, pluginInfo] = await Promise.all([gatherSystemInfo(), Promise.resolve(getPluginInfo())])
+  const loadedInfo = getLoadedPluginVersion()
+  const latestVersion = await getLatestPluginVersion(systemInfo.loadedVersion)
+  const issues: DoctorIssue[] = []
+
+  if (!systemInfo.opencodePath) {
+    issues.push({
+      title: "OpenCode binary not found",
+      description: "Install OpenCode CLI or desktop and ensure the binary is available.",
+      fix: "Install from https://opencode.ai/docs",
+      severity: "error",
+      affects: ["doctor", "run"],
+    })
+  }
+
+  if (
+    systemInfo.opencodeVersion &&
+    !compareVersions(systemInfo.opencodeVersion, MIN_OPENCODE_VERSION)
+  ) {
+    issues.push({
+      title: "OpenCode version below minimum",
+      description: `Detected ${systemInfo.opencodeVersion}; required >= ${MIN_OPENCODE_VERSION}.`,
+      fix: "Update OpenCode to the latest stable release",
+      severity: "warning",
+      affects: ["tooling", "doctor"],
+    })
+  }
+
+  if (!pluginInfo.registered) {
+    issues.push({
+      title: "oh-my-opencode is not registered",
+      description: "Plugin entry is missing from OpenCode configuration.",
+      fix: "Run: bunx oh-my-opencode install",
+      severity: "error",
+      affects: ["all agents"],
+    })
+  }
+
+  if (loadedInfo.expectedVersion && loadedInfo.loadedVersion && loadedInfo.expectedVersion !== loadedInfo.loadedVersion) {
+    issues.push({
+      title: "Loaded plugin version mismatch",
+      description: `Cache expects ${loadedInfo.expectedVersion} but loaded ${loadedInfo.loadedVersion}.`,
+      fix: "Reinstall plugin dependencies in OpenCode cache",
+      severity: "warning",
+      affects: ["plugin loading"],
+    })
+  }
+
+  if (
+    systemInfo.loadedVersion &&
+    latestVersion &&
+    !compareVersions(systemInfo.loadedVersion, latestVersion)
+  ) {
+    issues.push({
+      title: "Loaded plugin is outdated",
+      description: `Loaded ${systemInfo.loadedVersion}, latest ${latestVersion}.`,
+      fix: "Update: cd ~/.config/opencode && bun update oh-my-opencode",
+      severity: "warning",
+      affects: ["plugin features"],
+    })
+  }
+
+  const status = getResultStatus(issues)
+  return {
+    name: CHECK_NAMES[CHECK_IDS.SYSTEM],
+    status,
+    message: buildMessage(status, issues),
+    details: [
+      systemInfo.opencodeVersion ? `OpenCode: ${systemInfo.opencodeVersion}` : "OpenCode: not detected",
+      `Plugin expected: ${systemInfo.pluginVersion ?? "unknown"}`,
+      `Plugin loaded: ${systemInfo.loadedVersion ?? "unknown"}`,
+      `Bun: ${systemInfo.bunVersion ?? "unknown"}`,
+    ],
+    issues,
+  }
+}

src/cli/doctor/checks/tools-gh.ts

@@ -0,0 +1,105 @@
+export interface GhCliInfo {
+  installed: boolean
+  version: string | null
+  path: string | null
+  authenticated: boolean
+  username: string | null
+  scopes: string[]
+  error: string | null
+}
+
+async function checkBinaryExists(binary: string): Promise<{ exists: boolean; path: string | null }> {
+  try {
+    const binaryPath = Bun.which(binary)
+    return { exists: Boolean(binaryPath), path: binaryPath ?? null }
+  } catch {
+    return { exists: false, path: null }
+  }
+}
+
+async function getGhVersion(): Promise<string | null> {
+  try {
+    const processResult = Bun.spawn(["gh", "--version"], { stdout: "pipe", stderr: "pipe" })
+    const output = await new Response(processResult.stdout).text()
+    await processResult.exited
+    if (processResult.exitCode !== 0) return null
+
+    const matchedVersion = output.match(/gh version (\S+)/)
+    return matchedVersion?.[1] ?? output.trim().split("\n")[0] ?? null
+  } catch {
+    return null
+  }
+}
+
+async function getGhAuthStatus(): Promise<{
+  authenticated: boolean
+  username: string | null
+  scopes: string[]
+  error: string | null
+}> {
+  try {
+    const processResult = Bun.spawn(["gh", "auth", "status"], {
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, GH_NO_UPDATE_NOTIFIER: "1" },
+    })
+
+    const stdout = await new Response(processResult.stdout).text()
+    const stderr = await new Response(processResult.stderr).text()
+    await processResult.exited
+
+    const output = stderr || stdout
+    if (processResult.exitCode === 0) {
+      const usernameMatch = output.match(/Logged in to github\.com account (\S+)/)
+      const scopesMatch = output.match(/Token scopes?:\s*(.+)/i)
+
+      return {
+        authenticated: true,
+        username: usernameMatch?.[1]?.replace(/[()]/g, "") ?? null,
+        scopes: scopesMatch?.[1]?.split(/,\s*/).map((scope) => scope.trim()).filter(Boolean) ?? [],
+        error: null,
+      }
+    }
+
+    const errorMatch = output.match(/error[:\s]+(.+)/i)
+    return {
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: errorMatch?.[1]?.trim() ?? "Not authenticated",
+    }
+  } catch (error) {
+    return {
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: error instanceof Error ? error.message : "Failed to check auth status",
+    }
+  }
+}
+
+export async function getGhCliInfo(): Promise<GhCliInfo> {
+  const binaryStatus = await checkBinaryExists("gh")
+  if (!binaryStatus.exists) {
+    return {
+      installed: false,
+      version: null,
+      path: null,
+      authenticated: false,
+      username: null,
+      scopes: [],
+      error: null,
+    }
+  }
+
+  const [version, authStatus] = await Promise.all([getGhVersion(), getGhAuthStatus()])
+  return {
+    installed: true,
+    version,
+    path: binaryStatus.path,
+    authenticated: authStatus.authenticated,
+    username: authStatus.username,
+    scopes: authStatus.scopes,
+    error: authStatus.error,
+  }
+}

src/cli/doctor/checks/tools-lsp.ts

@@ -0,0 +1,25 @@
+import type { LspServerInfo } from "../types"
+import { isServerInstalled } from "../../../tools/lsp/config"
+
+const DEFAULT_LSP_SERVERS: Array<{ id: string; binary: string; extensions: string[] }> = [
+  { id: "typescript-language-server", binary: "typescript-language-server", extensions: [".ts", ".tsx", ".js", ".jsx"] },
+  { id: "pyright", binary: "pyright-langserver", extensions: [".py"] },
+  { id: "rust-analyzer", binary: "rust-analyzer", extensions: [".rs"] },
+  { id: "gopls", binary: "gopls", extensions: [".go"] },
+]
+
+export function getLspServersInfo(): LspServerInfo[] {
+  return DEFAULT_LSP_SERVERS.map((server) => ({
+    id: server.id,
+    installed: isServerInstalled([server.binary]),
+    extensions: server.extensions,
+    source: "builtin",
+  }))
+}
+
+export function getLspServerStats(servers: LspServerInfo[]): { installed: number; total: number } {
+  return {
+    installed: servers.filter((server) => server.installed).length,
+    total: servers.length,
+  }
+}

src/cli/doctor/checks/tools-mcp.ts

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+import type { McpServerInfo } from "../types"
+import { parseJsonc } from "../../../shared"
+
+const BUILTIN_MCP_SERVERS = ["context7", "grep_app"]
+
+interface McpConfigShape {
+  mcpServers?: Record<string, unknown>
+}
+
+function getMcpConfigPaths(): string[] {
+  return [
+    join(homedir(), ".claude", ".mcp.json"),
+    join(process.cwd(), ".mcp.json"),
+    join(process.cwd(), ".claude", ".mcp.json"),
+  ]
+}
+
+function loadUserMcpConfig(): Record<string, unknown> {
+  const servers: Record<string, unknown> = {}
+
+  for (const configPath of getMcpConfigPaths()) {
+    if (!existsSync(configPath)) continue
+
+    try {
+      const content = readFileSync(configPath, "utf-8")
+      const config = parseJsonc<McpConfigShape>(content)
+      if (config.mcpServers) {
+        Object.assign(servers, config.mcpServers)
+      }
+    } catch {
+      continue
+    }
+  }
+
+  return servers
+}
+
+export function getBuiltinMcpInfo(): McpServerInfo[] {
+  return BUILTIN_MCP_SERVERS.map((serverId) => ({
+    id: serverId,
+    type: "builtin",
+    enabled: true,
+    valid: true,
+  }))
+}
+
+export function getUserMcpInfo(): McpServerInfo[] {
+  return Object.entries(loadUserMcpConfig()).map(([serverId, value]) => {
+    const valid = typeof value === "object" && value !== null
+    return {
+      id: serverId,
+      type: "user",
+      enabled: true,
+      valid,
+      error: valid ? undefined : "Invalid configuration format",
+    }
+  })
+}

src/cli/doctor/checks/tools.ts

@@ -0,0 +1,118 @@
+import { checkAstGrepCli, checkAstGrepNapi, checkCommentChecker } from "./dependencies"
+import { getGhCliInfo } from "./tools-gh"
+import { getLspServerStats, getLspServersInfo } from "./tools-lsp"
+import { getBuiltinMcpInfo, getUserMcpInfo } from "./tools-mcp"
+import { CHECK_IDS, CHECK_NAMES } from "../constants"
+import type { CheckResult, DoctorIssue, ToolsSummary } from "../types"
+
+export async function gatherToolsSummary(): Promise<ToolsSummary> {
+  const [astGrepCliInfo, astGrepNapiInfo, commentCheckerInfo, ghInfo] = await Promise.all([
+    checkAstGrepCli(),
+    checkAstGrepNapi(),
+    checkCommentChecker(),
+    getGhCliInfo(),
+  ])
+
+  const lspServers = getLspServersInfo()
+  const lspStats = getLspServerStats(lspServers)
+  const builtinMcp = getBuiltinMcpInfo()
+  const userMcp = getUserMcpInfo()
+
+  return {
+    lspInstalled: lspStats.installed,
+    lspTotal: lspStats.total,
+    astGrepCli: astGrepCliInfo.installed,
+    astGrepNapi: astGrepNapiInfo.installed,
+    commentChecker: commentCheckerInfo.installed,
+    ghCli: {
+      installed: ghInfo.installed,
+      authenticated: ghInfo.authenticated,
+      username: ghInfo.username,
+    },
+    mcpBuiltin: builtinMcp.map((server) => server.id),
+    mcpUser: userMcp.map((server) => server.id),
+  }
+}
+
+function buildToolIssues(summary: ToolsSummary): DoctorIssue[] {
+  const issues: DoctorIssue[] = []
+
+  if (!summary.astGrepCli && !summary.astGrepNapi) {
+    issues.push({
+      title: "AST-Grep unavailable",
+      description: "Neither AST-Grep CLI nor NAPI backend is available.",
+      fix: "Install @ast-grep/cli globally or add @ast-grep/napi",
+      severity: "warning",
+      affects: ["ast_grep_search", "ast_grep_replace"],
+    })
+  }
+
+  if (!summary.commentChecker) {
+    issues.push({
+      title: "Comment checker unavailable",
+      description: "Comment checker binary is not installed.",
+      fix: "Install @code-yeongyu/comment-checker",
+      severity: "warning",
+      affects: ["comment-checker hook"],
+    })
+  }
+
+  if (summary.lspInstalled === 0) {
+    issues.push({
+      title: "No LSP servers detected",
+      description: "LSP-dependent tools will be limited until at least one server is installed.",
+      severity: "warning",
+      affects: ["lsp diagnostics", "rename", "references"],
+    })
+  }
+
+  if (!summary.ghCli.installed) {
+    issues.push({
+      title: "GitHub CLI missing",
+      description: "gh CLI is not installed.",
+      fix: "Install from https://cli.github.com/",
+      severity: "warning",
+      affects: ["GitHub automation"],
+    })
+  } else if (!summary.ghCli.authenticated) {
+    issues.push({
+      title: "GitHub CLI not authenticated",
+      description: "gh CLI is installed but not logged in.",
+      fix: "Run: gh auth login",
+      severity: "warning",
+      affects: ["GitHub automation"],
+    })
+  }
+
+  return issues
+}
+
+export async function checkTools(): Promise<CheckResult> {
+  const summary = await gatherToolsSummary()
+  const userMcpServers = getUserMcpInfo()
+  const invalidUserMcpServers = userMcpServers.filter((server) => !server.valid)
+  const issues = buildToolIssues(summary)
+
+  if (invalidUserMcpServers.length > 0) {
+    issues.push({
+      title: "Invalid MCP server configuration",
+      description: `${invalidUserMcpServers.length} user MCP server(s) have invalid config format.`,
+      severity: "warning",
+      affects: ["custom MCP tools"],
+    })
+  }
+
+  return {
+    name: CHECK_NAMES[CHECK_IDS.TOOLS],
+    status: issues.length === 0 ? "pass" : "warn",
+    message: issues.length === 0 ? "All tools checks passed" : `${issues.length} tools issue(s) detected`,
+    details: [
+      `AST-Grep: cli=${summary.astGrepCli ? "yes" : "no"}, napi=${summary.astGrepNapi ? "yes" : "no"}`,
+      `Comment checker: ${summary.commentChecker ? "yes" : "no"}`,
+      `LSP: ${summary.lspInstalled}/${summary.lspTotal}`,
+      `GH CLI: ${summary.ghCli.installed ? "installed" : "missing"}${summary.ghCli.authenticated ? " (authenticated)" : ""}`,
+      `MCP: builtin=${summary.mcpBuiltin.length}, user=${summary.mcpUser.length}`,
+    ],
+    issues,
+  }
+}

src/cli/doctor/checks/version.test.ts

@@ -1,148 +0,0 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
-import * as version from "./version"
-
-describe("version check", () => {
-  describe("getVersionInfo", () => {
-    it("returns version check info structure", async () => {
-      // given
-      // when getting version info
-      const info = await version.getVersionInfo()
-
-      // then should have expected structure
-      expect(typeof info.isUpToDate).toBe("boolean")
-      expect(typeof info.isLocalDev).toBe("boolean")
-      expect(typeof info.isPinned).toBe("boolean")
-    })
-  })
-
-  describe("checkVersionStatus", () => {
-    let getInfoSpy: ReturnType<typeof spyOn>
-
-    afterEach(() => {
-      getInfoSpy?.mockRestore()
-    })
-
-    it("returns pass when in local dev mode", async () => {
-      // given local dev mode
-      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
-        currentVersion: "local-dev",
-        latestVersion: "2.7.0",
-        isUpToDate: true,
-        isLocalDev: true,
-        isPinned: false,
-      })
-
-      // when checking
-      const result = await version.checkVersionStatus()
-
-      // then should pass with dev message
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("local development")
-    })
-
-    it("returns pass when pinned", async () => {
-      // given pinned version
-      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
-        currentVersion: "2.6.0",
-        latestVersion: "2.7.0",
-        isUpToDate: true,
-        isLocalDev: false,
-        isPinned: true,
-      })
-
-      // when checking
-      const result = await version.checkVersionStatus()
-
-      // then should pass with pinned message
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("Pinned")
-    })
-
-    it("returns warn when unable to determine version", async () => {
-      // given no version info
-      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
-        currentVersion: null,
-        latestVersion: "2.7.0",
-        isUpToDate: false,
-        isLocalDev: false,
-        isPinned: false,
-      })
-
-      // when checking
-      const result = await version.checkVersionStatus()
-
-      // then should warn
-      expect(result.status).toBe("warn")
-      expect(result.message).toContain("Unable to determine")
-    })
-
-    it("returns warn when network error", async () => {
-      // given network error
-      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
-        currentVersion: "2.6.0",
-        latestVersion: null,
-        isUpToDate: true,
-        isLocalDev: false,
-        isPinned: false,
-      })
-
-      // when checking
-      const result = await version.checkVersionStatus()
-
-      // then should warn
-      expect(result.status).toBe("warn")
-      expect(result.details?.some((d) => d.includes("network"))).toBe(true)
-    })
-
-    it("returns warn when update available", async () => {
-      // given update available
-      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
-        currentVersion: "2.6.0",
-        latestVersion: "2.7.0",
-        isUpToDate: false,
-        isLocalDev: false,
-        isPinned: false,
-      })
-
-      // when checking
-      const result = await version.checkVersionStatus()
-
-      // then should warn with update info
-      expect(result.status).toBe("warn")
-      expect(result.message).toContain("Update available")
-      expect(result.message).toContain("2.6.0")
-      expect(result.message).toContain("2.7.0")
-    })
-
-    it("returns pass when up to date", async () => {
-      // given up to date
-      getInfoSpy = spyOn(version, "getVersionInfo").mockResolvedValue({
-        currentVersion: "2.7.0",
-        latestVersion: "2.7.0",
-        isUpToDate: true,
-        isLocalDev: false,
-        isPinned: false,
-      })
-
-      // when checking
-      const result = await version.checkVersionStatus()
-
-      // then should pass
-      expect(result.status).toBe("pass")
-      expect(result.message).toContain("Up to date")
-    })
-  })
-
-  describe("getVersionCheckDefinition", () => {
-    it("returns valid check definition", () => {
-      // given
-      // when getting definition
-      const def = version.getVersionCheckDefinition()
-
-      // then should have required properties
-      expect(def.id).toBe("version-status")
-      expect(def.category).toBe("updates")
-      expect(def.critical).toBe(false)
-    })
-  })
-})

src/cli/doctor/checks/version.ts

@@ -1,135 +0,0 @@
-import type { CheckResult, CheckDefinition, VersionCheckInfo } from "../types"
-import { CHECK_IDS, CHECK_NAMES } from "../constants"
-import {
-  getCachedVersion,
-  getLatestVersion,
-  isLocalDevMode,
-  findPluginEntry,
-} from "../../../hooks/auto-update-checker/checker"
-
-function compareVersions(current: string, latest: string): boolean {
-  const parseVersion = (v: string): number[] => {
-    const cleaned = v.replace(/^v/, "").split("-")[0]
-    return cleaned.split(".").map((n) => parseInt(n, 10) || 0)
-  }
-
-  const curr = parseVersion(current)
-  const lat = parseVersion(latest)
-
-  for (let i = 0; i < Math.max(curr.length, lat.length); i++) {
-    const c = curr[i] ?? 0
-    const l = lat[i] ?? 0
-    if (c < l) return false
-    if (c > l) return true
-  }
-  return true
-}
-
-export async function getVersionInfo(): Promise<VersionCheckInfo> {
-  const cwd = process.cwd()
-
-  if (isLocalDevMode(cwd)) {
-    return {
-      currentVersion: "local-dev",
-      latestVersion: null,
-      isUpToDate: true,
-      isLocalDev: true,
-      isPinned: false,
-    }
-  }
-
-  const pluginInfo = findPluginEntry(cwd)
-  if (pluginInfo?.isPinned) {
-    return {
-      currentVersion: pluginInfo.pinnedVersion,
-      latestVersion: null,
-      isUpToDate: true,
-      isLocalDev: false,
-      isPinned: true,
-    }
-  }
-
-  const currentVersion = getCachedVersion()
-  const { extractChannel } = await import("../../../hooks/auto-update-checker/index")
-  const channel = extractChannel(pluginInfo?.pinnedVersion ?? currentVersion)
-  const latestVersion = await getLatestVersion(channel)
-
-  const isUpToDate =
-    !currentVersion ||
-    !latestVersion ||
-    compareVersions(currentVersion, latestVersion)
-
-  return {
-    currentVersion,
-    latestVersion,
-    isUpToDate,
-    isLocalDev: false,
-    isPinned: false,
-  }
-}
-
-export async function checkVersionStatus(): Promise<CheckResult> {
-  const info = await getVersionInfo()
-
-  if (info.isLocalDev) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
-      status: "pass",
-      message: "Running in local development mode",
-      details: ["Using file:// protocol from config"],
-    }
-  }
-
-  if (info.isPinned) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
-      status: "pass",
-      message: `Pinned to version ${info.currentVersion}`,
-      details: ["Update check skipped for pinned versions"],
-    }
-  }
-
-  if (!info.currentVersion) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
-      status: "warn",
-      message: "Unable to determine current version",
-      details: ["Run: bunx oh-my-opencode get-local-version"],
-    }
-  }
-
-  if (!info.latestVersion) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
-      status: "warn",
-      message: `Current: ${info.currentVersion}`,
-      details: ["Unable to check for updates (network error)"],
-    }
-  }
-
-  if (!info.isUpToDate) {
-    return {
-      name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
-      status: "warn",
-      message: `Update available: ${info.currentVersion} -> ${info.latestVersion}`,
-      details: ["Run: cd ~/.config/opencode && bun update oh-my-opencode"],
-    }
-  }
-
-  return {
-    name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
-    status: "pass",
-    message: `Up to date (${info.currentVersion})`,
-    details: info.latestVersion ? [`Latest: ${info.latestVersion}`] : undefined,
-  }
-}
-
-export function getVersionCheckDefinition(): CheckDefinition {
-  return {
-    id: CHECK_IDS.VERSION_STATUS,
-    name: CHECK_NAMES[CHECK_IDS.VERSION_STATUS],
-    category: "updates",
-    check: checkVersionStatus,
-    critical: false,
-  }
-}

src/cli/doctor/constants.ts

@@ -18,50 +18,17 @@ export const STATUS_COLORS = {
 } as const
 
 export const CHECK_IDS = {
-  OPENCODE_INSTALLATION: "opencode-installation",
-  PLUGIN_REGISTRATION: "plugin-registration",
-  CONFIG_VALIDATION: "config-validation",
-  MODEL_RESOLUTION: "model-resolution",
-  AUTH_ANTHROPIC: "auth-anthropic",
-  AUTH_OPENAI: "auth-openai",
-  AUTH_GOOGLE: "auth-google",
-  DEP_AST_GREP_CLI: "dep-ast-grep-cli",
-  DEP_AST_GREP_NAPI: "dep-ast-grep-napi",
-  DEP_COMMENT_CHECKER: "dep-comment-checker",
-  GH_CLI: "gh-cli",
-  LSP_SERVERS: "lsp-servers",
-  MCP_BUILTIN: "mcp-builtin",
-  MCP_USER: "mcp-user",
-  MCP_OAUTH_TOKENS: "mcp-oauth-tokens",
-  VERSION_STATUS: "version-status",
+  SYSTEM: "system",
+  CONFIG: "config",
+  TOOLS: "tools",
+  MODELS: "models",
 } as const
 
 export const CHECK_NAMES: Record<string, string> = {
-  [CHECK_IDS.OPENCODE_INSTALLATION]: "OpenCode Installation",
-  [CHECK_IDS.PLUGIN_REGISTRATION]: "Plugin Registration",
-  [CHECK_IDS.CONFIG_VALIDATION]: "Configuration Validity",
-  [CHECK_IDS.MODEL_RESOLUTION]: "Model Resolution",
-  [CHECK_IDS.AUTH_ANTHROPIC]: "Anthropic (Claude) Auth",
-  [CHECK_IDS.AUTH_OPENAI]: "OpenAI (ChatGPT) Auth",
-  [CHECK_IDS.AUTH_GOOGLE]: "Google (Gemini) Auth",
-  [CHECK_IDS.DEP_AST_GREP_CLI]: "AST-Grep CLI",
-  [CHECK_IDS.DEP_AST_GREP_NAPI]: "AST-Grep NAPI",
-  [CHECK_IDS.DEP_COMMENT_CHECKER]: "Comment Checker",
-  [CHECK_IDS.GH_CLI]: "GitHub CLI",
-  [CHECK_IDS.LSP_SERVERS]: "LSP Servers",
-  [CHECK_IDS.MCP_BUILTIN]: "Built-in MCP Servers",
-  [CHECK_IDS.MCP_USER]: "User MCP Configuration",
-  [CHECK_IDS.MCP_OAUTH_TOKENS]: "MCP OAuth Tokens",
-  [CHECK_IDS.VERSION_STATUS]: "Version Status",
-} as const
-
-export const CATEGORY_NAMES: Record<string, string> = {
-  installation: "Installation",
-  configuration: "Configuration",
-  authentication: "Authentication",
-  dependencies: "Dependencies",
-  tools: "Tools & Servers",
-  updates: "Updates",
+  [CHECK_IDS.SYSTEM]: "System",
+  [CHECK_IDS.CONFIG]: "Configuration",
+  [CHECK_IDS.TOOLS]: "Tools",
+  [CHECK_IDS.MODELS]: "Models",
 } as const
 
 export const EXIT_CODES = {

src/cli/doctor/format-default.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "bun:test"
+import { formatDefault } from "./format-default"
+import { stripAnsi } from "./format-shared"
+import type { DoctorResult } from "./types"
+
+function createBaseResult(): DoctorResult {
+  return {
+    results: [
+      { name: "System", status: "pass", message: "ok", issues: [] },
+      { name: "Configuration", status: "pass", message: "ok", issues: [] },
+    ],
+    systemInfo: {
+      opencodeVersion: "1.0.200",
+      opencodePath: "/usr/local/bin/opencode",
+      pluginVersion: "3.4.0",
+      loadedVersion: "3.4.0",
+      bunVersion: "1.2.0",
+      configPath: "/tmp/opencode.jsonc",
+      configValid: true,
+      isLocalDev: false,
+    },
+    tools: {
+      lspInstalled: 0,
+      lspTotal: 0,
+      astGrepCli: false,
+      astGrepNapi: false,
+      commentChecker: false,
+      ghCli: { installed: false, authenticated: false, username: null },
+      mcpBuiltin: [],
+      mcpUser: [],
+    },
+    summary: { total: 2, passed: 2, failed: 0, warnings: 0, skipped: 0, duration: 10 },
+    exitCode: 0,
+  }
+}
+
+describe("formatDefault", () => {
+  it("prints a single System OK line when no issues exist", () => {
+    //#given
+    const result = createBaseResult()
+
+    //#when
+    const output = stripAnsi(formatDefault(result))
+
+    //#then
+    expect(output).toContain("System OK (opencode 1.0.200")
+    expect(output).not.toContain("found:")
+  })
+
+  it("prints numbered issue list when issues exist", () => {
+    //#given
+    const result = createBaseResult()
+    result.results = [
+      {
+        name: "System",
+        status: "fail",
+        message: "failed",
+        issues: [
+          {
+            title: "OpenCode binary not found",
+            description: "Install OpenCode",
+            fix: "Install from https://opencode.ai/docs",
+            severity: "error",
+          },
+          {
+            title: "Loaded plugin is outdated",
+            description: "Loaded 3.0.0, latest 3.4.0",
+            severity: "warning",
+          },
+        ],
+      },
+    ]
+
+    //#when
+    const output = stripAnsi(formatDefault(result))
+
+    //#then
+    expect(output).toContain("2 issues found:")
+    expect(output).toContain("1. OpenCode binary not found")
+    expect(output).toContain("2. Loaded plugin is outdated")
+  })
+})

src/cli/doctor/format-default.ts

@@ -0,0 +1,35 @@
+import color from "picocolors"
+import type { DoctorResult } from "./types"
+import { SYMBOLS } from "./constants"
+import { formatHeader, formatIssue } from "./format-shared"
+
+export function formatDefault(result: DoctorResult): string {
+  const lines: string[] = []
+
+  lines.push(formatHeader())
+
+  const allIssues = result.results.flatMap((r) => r.issues)
+
+  if (allIssues.length === 0) {
+    const opencodeVer = result.systemInfo.opencodeVersion ?? "unknown"
+    const pluginVer = result.systemInfo.pluginVersion ?? "unknown"
+    lines.push(
+      ` ${color.green(SYMBOLS.check)} ${color.green(
+        `System OK (opencode ${opencodeVer} · oh-my-opencode ${pluginVer})`
+      )}`
+    )
+  } else {
+    const issueCount = allIssues.filter((i) => i.severity === "error").length
+    const warnCount = allIssues.filter((i) => i.severity === "warning").length
+
+    const totalStr = `${issueCount + warnCount} ${issueCount + warnCount === 1 ? "issue" : "issues"}`
+    lines.push(` ${color.yellow(SYMBOLS.warn)} ${totalStr} found:\n`)
+
+    allIssues.forEach((issue, index) => {
+      lines.push(formatIssue(issue, index + 1))
+      lines.push("")
+    })
+  }
+
+  return lines.join("\n")
+}

src/cli/doctor/format-shared.ts

@@ -0,0 +1,49 @@
+import color from "picocolors"
+import type { CheckStatus, DoctorIssue } from "./types"
+import { SYMBOLS, STATUS_COLORS } from "./constants"
+
+export function formatStatusSymbol(status: CheckStatus): string {
+  const colorFn = STATUS_COLORS[status]
+  switch (status) {
+    case "pass":
+      return colorFn(SYMBOLS.check)
+    case "fail":
+      return colorFn(SYMBOLS.cross)
+    case "warn":
+      return colorFn(SYMBOLS.warn)
+    case "skip":
+      return colorFn(SYMBOLS.skip)
+  }
+}
+
+export function formatStatusMark(available: boolean): string {
+  return available ? color.green(SYMBOLS.check) : color.red(SYMBOLS.cross)
+}
+
+export function stripAnsi(str: string): string {
+  const ESC = String.fromCharCode(27)
+  const pattern = ESC + "\\[[0-9;]*m"
+  return str.replace(new RegExp(pattern, "g"), "")
+}
+
+export function formatHeader(): string {
+  return `\n${color.bgMagenta(color.white(" oMoMoMoMo Doctor "))}\n`
+}
+
+export function formatIssue(issue: DoctorIssue, index: number): string {
+  const lines: string[] = []
+  const severityColor = issue.severity === "error" ? color.red : color.yellow
+
+  lines.push(`${index}. ${severityColor(issue.title)}`)
+  lines.push(`   ${color.dim(issue.description)}`)
+
+  if (issue.fix) {
+    lines.push(`   ${color.cyan("Fix:")} ${color.dim(issue.fix)}`)
+  }
+
+  if (issue.affects && issue.affects.length > 0) {
+    lines.push(`   ${color.cyan("Affects:")} ${color.dim(issue.affects.join(", "))}`)
+  }
+
+  return lines.join("\n")
+}

src/cli/doctor/format-status.ts

@@ -0,0 +1,35 @@
+import color from "picocolors"
+import type { DoctorResult } from "./types"
+import { formatHeader, formatStatusMark } from "./format-shared"
+
+export function formatStatus(result: DoctorResult): string {
+  const lines: string[] = []
+
+  lines.push(formatHeader())
+
+  const { systemInfo, tools } = result
+  const padding = " "
+
+  const opencodeVer = systemInfo.opencodeVersion ?? "unknown"
+  const pluginVer = systemInfo.pluginVersion ?? "unknown"
+  const bunVer = systemInfo.bunVersion ?? "unknown"
+  lines.push(` ${padding}System     ${opencodeVer} · ${pluginVer} · Bun ${bunVer}`)
+
+  const configPath = systemInfo.configPath ?? "unknown"
+  const configStatus = systemInfo.configValid ? color.green("(valid)") : color.red("(invalid)")
+  lines.push(` ${padding}Config     ${configPath} ${configStatus}`)
+
+  const lspText = `LSP ${tools.lspInstalled}/${tools.lspTotal}`
+  const astGrepMark = formatStatusMark(tools.astGrepCli)
+  const ghMark = formatStatusMark(tools.ghCli.installed && tools.ghCli.authenticated)
+  const ghUser = tools.ghCli.username ?? ""
+  lines.push(` ${padding}Tools      ${lspText} · AST-Grep ${astGrepMark} · gh ${ghMark}${ghUser ? ` (${ghUser})` : ""}`)
+
+  const builtinCount = tools.mcpBuiltin.length
+  const userCount = tools.mcpUser.length
+  const builtinText = builtinCount > 0 ? tools.mcpBuiltin.join(" · ") : "none"
+  const userText = userCount > 0 ? `+ ${userCount} user` : ""
+  lines.push(` ${padding}MCPs       ${builtinText} ${userText}`)
+
+  return lines.join("\n")
+}

src/cli/doctor/format-verbose.ts

@@ -0,0 +1,79 @@
+import color from "picocolors"
+import type { DoctorResult } from "./types"
+import { formatHeader, formatStatusSymbol, formatIssue } from "./format-shared"
+
+export function formatVerbose(result: DoctorResult): string {
+  const lines: string[] = []
+
+  lines.push(formatHeader())
+
+  const { systemInfo, tools, results, summary } = result
+
+  lines.push(`${color.bold("System Information")}`)
+  lines.push(`${color.dim("\u2500".repeat(40))}`)
+  lines.push(`  ${formatStatusSymbol("pass")} opencode    ${systemInfo.opencodeVersion ?? "unknown"}`)
+  lines.push(`  ${formatStatusSymbol("pass")} oh-my-opencode ${systemInfo.pluginVersion ?? "unknown"}`)
+  if (systemInfo.loadedVersion) {
+    lines.push(`  ${formatStatusSymbol("pass")} loaded      ${systemInfo.loadedVersion}`)
+  }
+  if (systemInfo.bunVersion) {
+    lines.push(`  ${formatStatusSymbol("pass")} bun         ${systemInfo.bunVersion}`)
+  }
+  lines.push(`  ${formatStatusSymbol("pass")} path        ${systemInfo.opencodePath ?? "unknown"}`)
+  if (systemInfo.isLocalDev) {
+    lines.push(`  ${color.yellow("*")} ${color.dim("(local development mode)")}`)
+  }
+  lines.push("")
+
+  lines.push(`${color.bold("Configuration")}`)
+  lines.push(`${color.dim("\u2500".repeat(40))}`)
+  const configStatus = systemInfo.configValid ? color.green("valid") : color.red("invalid")
+  lines.push(`  ${formatStatusSymbol(systemInfo.configValid ? "pass" : "fail")} ${systemInfo.configPath ?? "unknown"} (${configStatus})`)
+  lines.push("")
+
+  lines.push(`${color.bold("Tools")}`)
+  lines.push(`${color.dim("\u2500".repeat(40))}`)
+  lines.push(`  ${formatStatusSymbol("pass")} LSP         ${tools.lspInstalled}/${tools.lspTotal} installed`)
+  lines.push(`  ${formatStatusSymbol(tools.astGrepCli ? "pass" : "fail")} ast-grep CLI ${tools.astGrepCli ? "installed" : "not found"}`)
+  lines.push(`  ${formatStatusSymbol(tools.astGrepNapi ? "pass" : "fail")} ast-grep napi ${tools.astGrepNapi ? "installed" : "not found"}`)
+  lines.push(`  ${formatStatusSymbol(tools.commentChecker ? "pass" : "fail")} comment-checker ${tools.commentChecker ? "installed" : "not found"}`)
+  lines.push(`  ${formatStatusSymbol(tools.ghCli.installed && tools.ghCli.authenticated ? "pass" : "fail")} gh CLI ${tools.ghCli.installed ? "installed" : "not found"}${tools.ghCli.authenticated && tools.ghCli.username ? ` (${tools.ghCli.username})` : ""}`)
+  lines.push("")
+
+  lines.push(`${color.bold("MCPs")}`)
+  lines.push(`${color.dim("\u2500".repeat(40))}`)
+  if (tools.mcpBuiltin.length === 0) {
+    lines.push(`  ${color.dim("No built-in MCPs")}`)
+  } else {
+    for (const mcp of tools.mcpBuiltin) {
+      lines.push(`  ${formatStatusSymbol("pass")} ${mcp}`)
+    }
+  }
+  if (tools.mcpUser.length > 0) {
+    lines.push(`  ${color.cyan("+")} ${tools.mcpUser.length} user MCP(s):`)
+    for (const mcp of tools.mcpUser) {
+      lines.push(`    ${formatStatusSymbol("pass")} ${mcp}`)
+    }
+  }
+  lines.push("")
+
+  const allIssues = results.flatMap((r) => r.issues)
+  if (allIssues.length > 0) {
+    lines.push(`${color.bold("Issues")}`)
+    lines.push(`${color.dim("\u2500".repeat(40))}`)
+    allIssues.forEach((issue, index) => {
+      lines.push(formatIssue(issue, index + 1))
+      lines.push("")
+    })
+  }
+
+  lines.push(`${color.bold("Summary")}`)
+  lines.push(`${color.dim("\u2500".repeat(40))}`)
+  const passText = summary.passed > 0 ? color.green(`${summary.passed} passed`) : `${summary.passed} passed`
+  const failText = summary.failed > 0 ? color.red(`${summary.failed} failed`) : `${summary.failed} failed`
+  const warnText = summary.warnings > 0 ? color.yellow(`${summary.warnings} warnings`) : `${summary.warnings} warnings`
+  lines.push(`  ${passText}, ${failText}, ${warnText}`)
+  lines.push(`  ${color.dim(`Total: ${summary.total} checks in ${summary.duration}ms`)}`)
+
+  return lines.join("\n")
+}

src/cli/doctor/formatter.test.ts

@@ -1,218 +1,126 @@
-import { describe, it, expect } from "bun:test"
-import {
-  formatStatusSymbol,
-  formatCheckResult,
-  formatCategoryHeader,
-  formatSummary,
-  formatHeader,
-  formatFooter,
-  formatJsonOutput,
-  formatBox,
-  formatHelpSuggestions,
-} from "./formatter"
-import type { CheckResult, DoctorSummary, DoctorResult } from "./types"
+import { afterEach, describe, expect, it, mock } from "bun:test"
+import type { DoctorResult } from "./types"
+
+function createDoctorResult(): DoctorResult {
+  return {
+    results: [
+      { name: "System", status: "pass", message: "ok", issues: [] },
+      { name: "Configuration", status: "warn", message: "warn", issues: [] },
+    ],
+    systemInfo: {
+      opencodeVersion: "1.0.200",
+      opencodePath: "/usr/local/bin/opencode",
+      pluginVersion: "3.4.0",
+      loadedVersion: "3.4.0",
+      bunVersion: "1.2.0",
+      configPath: "/tmp/opencode.jsonc",
+      configValid: true,
+      isLocalDev: false,
+    },
+    tools: {
+      lspInstalled: 2,
+      lspTotal: 4,
+      astGrepCli: true,
+      astGrepNapi: false,
+      commentChecker: true,
+      ghCli: { installed: true, authenticated: true, username: "yeongyu" },
+      mcpBuiltin: ["context7", "grep_app"],
+      mcpUser: ["custom"],
+    },
+    summary: {
+      total: 2,
+      passed: 1,
+      failed: 0,
+      warnings: 1,
+      skipped: 0,
+      duration: 12,
+    },
+    exitCode: 0,
+  }
+}
 
 describe("formatter", () => {
-  describe("formatStatusSymbol", () => {
-    it("returns green check for pass", () => {
-      const symbol = formatStatusSymbol("pass")
-      expect(symbol).toContain("\u2713")
-    })
-
-    it("returns red cross for fail", () => {
-      const symbol = formatStatusSymbol("fail")
-      expect(symbol).toContain("\u2717")
-    })
-
-    it("returns yellow warning for warn", () => {
-      const symbol = formatStatusSymbol("warn")
-      expect(symbol).toContain("\u26A0")
-    })
-
-    it("returns dim circle for skip", () => {
-      const symbol = formatStatusSymbol("skip")
-      expect(symbol).toContain("\u25CB")
-    })
+  afterEach(() => {
+    mock.restore()
   })
 
-  describe("formatCheckResult", () => {
-    it("includes name and message", () => {
-      const result: CheckResult = {
-        name: "Test Check",
-        status: "pass",
-        message: "All good",
-      }
+  describe("formatDoctorOutput", () => {
+    it("dispatches to default formatter for default mode", async () => {
+      //#given
+      const formatDefaultMock = mock(() => "default-output")
+      const formatStatusMock = mock(() => "status-output")
+      const formatVerboseMock = mock(() => "verbose-output")
+      mock.module("./format-default", () => ({ formatDefault: formatDefaultMock }))
+      mock.module("./format-status", () => ({ formatStatus: formatStatusMock }))
+      mock.module("./format-verbose", () => ({ formatVerbose: formatVerboseMock }))
+      const { formatDoctorOutput } = await import(`./formatter?default=${Date.now()}`)
 
-      const output = formatCheckResult(result, false)
+      //#when
+      const output = formatDoctorOutput(createDoctorResult(), "default")
 
-      expect(output).toContain("Test Check")
-      expect(output).toContain("All good")
+      //#then
+      expect(output).toBe("default-output")
+      expect(formatDefaultMock).toHaveBeenCalledTimes(1)
+      expect(formatStatusMock).toHaveBeenCalledTimes(0)
+      expect(formatVerboseMock).toHaveBeenCalledTimes(0)
     })
 
-    it("includes details when verbose", () => {
-      const result: CheckResult = {
-        name: "Test Check",
-        status: "pass",
-        message: "OK",
-        details: ["Detail 1", "Detail 2"],
-      }
+    it("dispatches to status formatter for status mode", async () => {
+      //#given
+      const formatDefaultMock = mock(() => "default-output")
+      const formatStatusMock = mock(() => "status-output")
+      const formatVerboseMock = mock(() => "verbose-output")
+      mock.module("./format-default", () => ({ formatDefault: formatDefaultMock }))
+      mock.module("./format-status", () => ({ formatStatus: formatStatusMock }))
+      mock.module("./format-verbose", () => ({ formatVerbose: formatVerboseMock }))
+      const { formatDoctorOutput } = await import(`./formatter?status=${Date.now()}`)
 
-      const output = formatCheckResult(result, true)
+      //#when
+      const output = formatDoctorOutput(createDoctorResult(), "status")
 
-      expect(output).toContain("Detail 1")
-      expect(output).toContain("Detail 2")
+      //#then
+      expect(output).toBe("status-output")
+      expect(formatDefaultMock).toHaveBeenCalledTimes(0)
+      expect(formatStatusMock).toHaveBeenCalledTimes(1)
+      expect(formatVerboseMock).toHaveBeenCalledTimes(0)
     })
 
-    it("hides details when not verbose", () => {
-      const result: CheckResult = {
-        name: "Test Check",
-        status: "pass",
-        message: "OK",
-        details: ["Detail 1"],
-      }
+    it("dispatches to verbose formatter for verbose mode", async () => {
+      //#given
+      const formatDefaultMock = mock(() => "default-output")
+      const formatStatusMock = mock(() => "status-output")
+      const formatVerboseMock = mock(() => "verbose-output")
+      mock.module("./format-default", () => ({ formatDefault: formatDefaultMock }))
+      mock.module("./format-status", () => ({ formatStatus: formatStatusMock }))
+      mock.module("./format-verbose", () => ({ formatVerbose: formatVerboseMock }))
+      const { formatDoctorOutput } = await import(`./formatter?verbose=${Date.now()}`)
 
-      const output = formatCheckResult(result, false)
+      //#when
+      const output = formatDoctorOutput(createDoctorResult(), "verbose")
 
-      expect(output).not.toContain("Detail 1")
-    })
-  })
-
-  describe("formatCategoryHeader", () => {
-    it("formats category name with styling", () => {
-      const header = formatCategoryHeader("installation")
-
-      expect(header).toContain("Installation")
-    })
-  })
-
-  describe("formatSummary", () => {
-    it("shows all counts", () => {
-      const summary: DoctorSummary = {
-        total: 10,
-        passed: 7,
-        failed: 1,
-        warnings: 2,
-        skipped: 0,
-        duration: 150,
-      }
-
-      const output = formatSummary(summary)
-
-      expect(output).toContain("7 passed")
-      expect(output).toContain("1 failed")
-      expect(output).toContain("2 warnings")
-      expect(output).toContain("10 checks")
-      expect(output).toContain("150ms")
-    })
-  })
-
-  describe("formatHeader", () => {
-    it("includes doctor branding", () => {
-      const header = formatHeader()
-
-      expect(header).toContain("Doctor")
-    })
-  })
-
-  describe("formatFooter", () => {
-    it("shows error message when failures", () => {
-      const summary: DoctorSummary = {
-        total: 5,
-        passed: 4,
-        failed: 1,
-        warnings: 0,
-        skipped: 0,
-        duration: 100,
-      }
-
-      const footer = formatFooter(summary)
-
-      expect(footer).toContain("Issues detected")
-    })
-
-    it("shows warning message when warnings only", () => {
-      const summary: DoctorSummary = {
-        total: 5,
-        passed: 4,
-        failed: 0,
-        warnings: 1,
-        skipped: 0,
-        duration: 100,
-      }
-
-      const footer = formatFooter(summary)
-
-      expect(footer).toContain("warnings")
-    })
-
-    it("shows success message when all pass", () => {
-      const summary: DoctorSummary = {
-        total: 5,
-        passed: 5,
-        failed: 0,
-        warnings: 0,
-        skipped: 0,
-        duration: 100,
-      }
-
-      const footer = formatFooter(summary)
-
-      expect(footer).toContain("operational")
+      //#then
+      expect(output).toBe("verbose-output")
+      expect(formatDefaultMock).toHaveBeenCalledTimes(0)
+      expect(formatStatusMock).toHaveBeenCalledTimes(0)
+      expect(formatVerboseMock).toHaveBeenCalledTimes(1)
     })
   })
 
   describe("formatJsonOutput", () => {
-    it("returns valid JSON", () => {
-      const result: DoctorResult = {
-        results: [{ name: "Test", status: "pass", message: "OK" }],
-        summary: { total: 1, passed: 1, failed: 0, warnings: 0, skipped: 0, duration: 50 },
-        exitCode: 0,
-      }
+    it("returns valid JSON payload", async () => {
+      //#given
+      const { formatJsonOutput } = await import(`./formatter?json=${Date.now()}`)
+      const result = createDoctorResult()
 
+      //#when
       const output = formatJsonOutput(result)
-      const parsed = JSON.parse(output)
+      const parsed = JSON.parse(output) as DoctorResult
 
-      expect(parsed.results.length).toBe(1)
-      expect(parsed.summary.total).toBe(1)
+      //#then
+      expect(parsed.summary.total).toBe(2)
+      expect(parsed.systemInfo.pluginVersion).toBe("3.4.0")
+      expect(parsed.tools.ghCli.username).toBe("yeongyu")
       expect(parsed.exitCode).toBe(0)
     })
   })
-
-  describe("formatBox", () => {
-    it("wraps content in box", () => {
-      const box = formatBox("Test content")
-
-      expect(box).toContain("Test content")
-      expect(box).toContain("\u2500")
-    })
-
-    it("includes title when provided", () => {
-      const box = formatBox("Content", "My Title")
-
-      expect(box).toContain("My Title")
-    })
-  })
-
-  describe("formatHelpSuggestions", () => {
-    it("extracts suggestions from failed checks", () => {
-      const results: CheckResult[] = [
-        { name: "Test", status: "fail", message: "Error", details: ["Run: fix-command"] },
-        { name: "OK", status: "pass", message: "Good" },
-      ]
-
-      const suggestions = formatHelpSuggestions(results)
-
-      expect(suggestions).toContain("Run: fix-command")
-    })
-
-    it("returns empty array when no failures", () => {
-      const results: CheckResult[] = [
-        { name: "OK", status: "pass", message: "Good" },
-      ]
-
-      const suggestions = formatHelpSuggestions(results)
-
-      expect(suggestions.length).toBe(0)
-    })
-  })
 })

src/cli/doctor/formatter.ts

@@ -1,140 +1,19 @@
-import color from "picocolors"
-import type { CheckResult, DoctorSummary, CheckCategory, DoctorResult } from "./types"
-import { SYMBOLS, STATUS_COLORS, CATEGORY_NAMES } from "./constants"
+import type { DoctorResult, DoctorMode } from "./types"
+import { formatDefault } from "./format-default"
+import { formatStatus } from "./format-status"
+import { formatVerbose } from "./format-verbose"
 
-export function formatStatusSymbol(status: CheckResult["status"]): string {
-  switch (status) {
-    case "pass":
-      return SYMBOLS.check
-    case "fail":
-      return SYMBOLS.cross
-    case "warn":
-      return SYMBOLS.warn
-    case "skip":
-      return SYMBOLS.skip
+export function formatDoctorOutput(result: DoctorResult, mode: DoctorMode): string {
+  switch (mode) {
+    case "default":
+      return formatDefault(result)
+    case "status":
+      return formatStatus(result)
+    case "verbose":
+      return formatVerbose(result)
   }
 }
 
-export function formatCheckResult(result: CheckResult, verbose: boolean): string {
-  const symbol = formatStatusSymbol(result.status)
-  const colorFn = STATUS_COLORS[result.status]
-  const name = colorFn(result.name)
-  const message = color.dim(result.message)
-
-  let line = `  ${symbol} ${name}`
-  if (result.message) {
-    line += ` ${SYMBOLS.arrow} ${message}`
-  }
-
-  if (verbose && result.details && result.details.length > 0) {
-    const detailLines = result.details.map((d) => `      ${SYMBOLS.bullet} ${color.dim(d)}`).join("\n")
-    line += "\n" + detailLines
-  }
-
-  return line
-}
-
-export function formatCategoryHeader(category: CheckCategory): string {
-  const name = CATEGORY_NAMES[category] || category
-  return `\n${color.bold(color.white(name))}\n${color.dim("\u2500".repeat(40))}`
-}
-
-export function formatSummary(summary: DoctorSummary): string {
-  const lines: string[] = []
-
-  lines.push(color.bold(color.white("Summary")))
-  lines.push(color.dim("\u2500".repeat(40)))
-  lines.push("")
-
-  const passText = summary.passed > 0 ? color.green(`${summary.passed} passed`) : color.dim("0 passed")
-  const failText = summary.failed > 0 ? color.red(`${summary.failed} failed`) : color.dim("0 failed")
-  const warnText = summary.warnings > 0 ? color.yellow(`${summary.warnings} warnings`) : color.dim("0 warnings")
-  const skipText = summary.skipped > 0 ? color.dim(`${summary.skipped} skipped`) : ""
-
-  const parts = [passText, failText, warnText]
-  if (skipText) parts.push(skipText)
-
-  lines.push(`  ${parts.join(", ")}`)
-  lines.push(`  ${color.dim(`Total: ${summary.total} checks in ${summary.duration}ms`)}`)
-
-  return lines.join("\n")
-}
-
-export function formatHeader(): string {
-  return `\n${color.bgMagenta(color.white(" oMoMoMoMo... Doctor "))}\n`
-}
-
-export function formatFooter(summary: DoctorSummary): string {
-  if (summary.failed > 0) {
-    return `\n${SYMBOLS.cross} ${color.red("Issues detected. Please review the errors above.")}\n`
-  }
-  if (summary.warnings > 0) {
-    return `\n${SYMBOLS.warn} ${color.yellow("All systems operational with warnings.")}\n`
-  }
-  return `\n${SYMBOLS.check} ${color.green("All systems operational!")}\n`
-}
-
-export function formatProgress(current: number, total: number, name: string): string {
-  const progress = color.dim(`[${current}/${total}]`)
-  return `${progress} Checking ${name}...`
-}
-
 export function formatJsonOutput(result: DoctorResult): string {
   return JSON.stringify(result, null, 2)
 }
-
-export function formatDetails(details: string[]): string {
-  return details.map((d) => `      ${SYMBOLS.bullet} ${color.dim(d)}`).join("\n")
-}
-
-function stripAnsi(str: string): string {
-  // eslint-disable-next-line no-control-regex
-  return str.replace(/\x1b\[[0-9;]*m/g, "")
-}
-
-export function formatBox(content: string, title?: string): string {
-  const lines = content.split("\n")
-  const maxWidth = Math.max(...lines.map((l) => stripAnsi(l).length), title?.length ?? 0) + 4
-  const border = color.dim("\u2500".repeat(maxWidth))
-
-  const output: string[] = []
-  output.push("")
-
-  if (title) {
-    output.push(
-      color.dim("\u250C\u2500") +
-        color.bold(` ${title} `) +
-        color.dim("\u2500".repeat(maxWidth - title.length - 4)) +
-        color.dim("\u2510")
-    )
-  } else {
-    output.push(color.dim("\u250C") + border + color.dim("\u2510"))
-  }
-
-  for (const line of lines) {
-    const stripped = stripAnsi(line)
-    const padding = maxWidth - stripped.length
-    output.push(color.dim("\u2502") + ` ${line}${" ".repeat(padding - 1)}` + color.dim("\u2502"))
-  }
-
-  output.push(color.dim("\u2514") + border + color.dim("\u2518"))
-  output.push("")
-
-  return output.join("\n")
-}
-
-export function formatHelpSuggestions(results: CheckResult[]): string[] {
-  const suggestions: string[] = []
-
-  for (const result of results) {
-    if (result.status === "fail" && result.details) {
-      for (const detail of result.details) {
-        if (detail.includes("Run:") || detail.includes("Install:") || detail.includes("Visit:")) {
-          suggestions.push(detail)
-        }
-      }
-    }
-  }
-
-  return suggestions
-}

src/cli/doctor/index.ts

@@ -1,11 +1,11 @@
 import type { DoctorOptions } from "./types"
 import { runDoctor } from "./runner"
 
-export async function doctor(options: DoctorOptions = {}): Promise<number> {
+export async function doctor(options: DoctorOptions = { mode: "default" }): Promise<number> {
   const result = await runDoctor(options)
   return result.exitCode
 }
 
 export * from "./types"
 export { runDoctor } from "./runner"
-export { formatJsonOutput } from "./formatter"
+export { formatDoctorOutput, formatJsonOutput } from "./formatter"

src/cli/doctor/runner.test.ts

@@ -1,153 +1,233 @@
-import { describe, it, expect, spyOn, afterEach } from "bun:test"
-import {
-  runCheck,
-  calculateSummary,
-  determineExitCode,
-  filterChecksByCategory,
-  groupChecksByCategory,
-} from "./runner"
-import type { CheckResult, CheckDefinition, CheckCategory } from "./types"
+import { afterEach, describe, expect, it, mock } from "bun:test"
+import type { CheckDefinition, CheckResult, DoctorResult, SystemInfo, ToolsSummary } from "./types"
+
+function createSystemInfo(): SystemInfo {
+  return {
+    opencodeVersion: "1.0.200",
+    opencodePath: "/usr/local/bin/opencode",
+    pluginVersion: "3.4.0",
+    loadedVersion: "3.4.0",
+    bunVersion: "1.2.0",
+    configPath: "/tmp/opencode.json",
+    configValid: true,
+    isLocalDev: false,
+  }
+}
+
+function createTools(): ToolsSummary {
+  return {
+    lspInstalled: 1,
+    lspTotal: 4,
+    astGrepCli: true,
+    astGrepNapi: false,
+    commentChecker: true,
+    ghCli: { installed: true, authenticated: true, username: "yeongyu" },
+    mcpBuiltin: ["context7"],
+    mcpUser: ["custom-mcp"],
+  }
+}
+
+function createPassResult(name: string): CheckResult {
+  return { name, status: "pass", message: "ok", issues: [] }
+}
+
+function createDeferred(): {
+  promise: Promise<CheckResult>
+  resolve: (value: CheckResult) => void
+} {
+  let resolvePromise: (value: CheckResult) => void = () => {}
+  const promise = new Promise<CheckResult>((resolve) => {
+    resolvePromise = resolve
+  })
+  return { promise, resolve: resolvePromise }
+}
 
 describe("runner", () => {
+  afterEach(() => {
+    mock.restore()
+  })
+
   describe("runCheck", () => {
-    it("returns result from check function", async () => {
+    it("returns fail result with issue when check throws", async () => {
+      //#given
       const check: CheckDefinition = {
-        id: "test",
-        name: "Test Check",
-        category: "installation",
-        check: async () => ({ name: "Test Check", status: "pass", message: "OK" }),
-      }
-
-      const result = await runCheck(check)
-
-      expect(result.name).toBe("Test Check")
-      expect(result.status).toBe("pass")
-    })
-
-    it("measures duration", async () => {
-      const check: CheckDefinition = {
-        id: "test",
-        name: "Test Check",
-        category: "installation",
+        id: "system",
+        name: "System",
         check: async () => {
-          await new Promise((r) => setTimeout(r, 50))
-          return { name: "Test", status: "pass", message: "OK" }
-        },
-      }
-
-      const result = await runCheck(check)
-
-      expect(result.duration).toBeGreaterThanOrEqual(10)
-    })
-
-    it("returns fail on error", async () => {
-      const check: CheckDefinition = {
-        id: "test",
-        name: "Test Check",
-        category: "installation",
-        check: async () => {
-          throw new Error("Test error")
+          throw new Error("boom")
         },
       }
+      const { runCheck } = await import(`./runner?run-check-error=${Date.now()}`)
 
+      //#when
       const result = await runCheck(check)
 
+      //#then
       expect(result.status).toBe("fail")
-      expect(result.message).toContain("Test error")
+      expect(result.message).toBe("boom")
+      expect(result.issues[0]?.title).toBe("System")
+      expect(result.issues[0]?.severity).toBe("error")
+      expect(typeof result.duration).toBe("number")
     })
   })
 
   describe("calculateSummary", () => {
-    it("counts each status correctly", () => {
+    it("counts statuses correctly", async () => {
+      //#given
+      const { calculateSummary } = await import(`./runner?summary=${Date.now()}`)
       const results: CheckResult[] = [
-        { name: "1", status: "pass", message: "" },
-        { name: "2", status: "pass", message: "" },
-        { name: "3", status: "fail", message: "" },
-        { name: "4", status: "warn", message: "" },
-        { name: "5", status: "skip", message: "" },
+        { name: "1", status: "pass", message: "", issues: [] },
+        { name: "2", status: "pass", message: "", issues: [] },
+        { name: "3", status: "fail", message: "", issues: [] },
+        { name: "4", status: "warn", message: "", issues: [] },
+        { name: "5", status: "skip", message: "", issues: [] },
       ]
 
-      const summary = calculateSummary(results, 100)
+      //#when
+      const summary = calculateSummary(results, 19.9)
 
+      //#then
       expect(summary.total).toBe(5)
       expect(summary.passed).toBe(2)
       expect(summary.failed).toBe(1)
       expect(summary.warnings).toBe(1)
       expect(summary.skipped).toBe(1)
-      expect(summary.duration).toBe(100)
+      expect(summary.duration).toBe(20)
     })
   })
 
   describe("determineExitCode", () => {
-    it("returns 0 when all pass", () => {
+    it("returns zero when no failures exist", async () => {
+      //#given
+      const { determineExitCode } = await import(`./runner?exit-ok=${Date.now()}`)
       const results: CheckResult[] = [
-        { name: "1", status: "pass", message: "" },
-        { name: "2", status: "pass", message: "" },
+        { name: "1", status: "pass", message: "", issues: [] },
+        { name: "2", status: "warn", message: "", issues: [] },
       ]
 
-      expect(determineExitCode(results)).toBe(0)
+      //#when
+      const code = determineExitCode(results)
+
+      //#then
+      expect(code).toBe(0)
     })
 
-    it("returns 0 when only warnings", () => {
+    it("returns one when any failure exists", async () => {
+      //#given
+      const { determineExitCode } = await import(`./runner?exit-fail=${Date.now()}`)
       const results: CheckResult[] = [
-        { name: "1", status: "pass", message: "" },
-        { name: "2", status: "warn", message: "" },
+        { name: "1", status: "pass", message: "", issues: [] },
+        { name: "2", status: "fail", message: "", issues: [] },
       ]
 
-      expect(determineExitCode(results)).toBe(0)
-    })
+      //#when
+      const code = determineExitCode(results)
 
-    it("returns 1 when any failures", () => {
-      const results: CheckResult[] = [
-        { name: "1", status: "pass", message: "" },
-        { name: "2", status: "fail", message: "" },
-      ]
-
-      expect(determineExitCode(results)).toBe(1)
+      //#then
+      expect(code).toBe(1)
     })
   })
 
-  describe("filterChecksByCategory", () => {
-    const checks: CheckDefinition[] = [
-      { id: "1", name: "Install", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
-      { id: "2", name: "Config", category: "configuration", check: async () => ({ name: "", status: "pass", message: "" }) },
-      { id: "3", name: "Auth", category: "authentication", check: async () => ({ name: "", status: "pass", message: "" }) },
-    ]
+  describe("runDoctor", () => {
+    it("starts all checks in parallel and returns collected result", async () => {
+      //#given
+      const startedChecks: string[] = []
+      const deferredOne = createDeferred()
+      const deferredTwo = createDeferred()
+      const deferredThree = createDeferred()
+      const deferredFour = createDeferred()
 
-    it("returns all checks when no category", () => {
-      const filtered = filterChecksByCategory(checks)
+      const checks: CheckDefinition[] = [
+        {
+          id: "system",
+          name: "System",
+          check: async () => {
+            startedChecks.push("system")
+            return deferredOne.promise
+          },
+        },
+        {
+          id: "config",
+          name: "Configuration",
+          check: async () => {
+            startedChecks.push("config")
+            return deferredTwo.promise
+          },
+        },
+        {
+          id: "tools",
+          name: "Tools",
+          check: async () => {
+            startedChecks.push("tools")
+            return deferredThree.promise
+          },
+        },
+        {
+          id: "models",
+          name: "Models",
+          check: async () => {
+            startedChecks.push("models")
+            return deferredFour.promise
+          },
+        },
+      ]
 
-      expect(filtered.length).toBe(3)
-    })
+      const expectedResult: DoctorResult = {
+        results: [
+          createPassResult("System"),
+          createPassResult("Configuration"),
+          createPassResult("Tools"),
+          createPassResult("Models"),
+        ],
+        systemInfo: createSystemInfo(),
+        tools: createTools(),
+        summary: {
+          total: 4,
+          passed: 4,
+          failed: 0,
+          warnings: 0,
+          skipped: 0,
+          duration: 0,
+        },
+        exitCode: 0,
+      }
 
-    it("filters to specific category", () => {
-      const filtered = filterChecksByCategory(checks, "installation")
+      const formatDoctorOutputMock = mock((result: DoctorResult) => result.summary.total.toString())
+      const formatJsonOutputMock = mock((result: DoctorResult) => JSON.stringify(result))
 
-      expect(filtered.length).toBe(1)
-      expect(filtered[0].name).toBe("Install")
-    })
-  })
+      mock.module("./checks", () => ({
+        getAllCheckDefinitions: () => checks,
+        gatherSystemInfo: async () => expectedResult.systemInfo,
+        gatherToolsSummary: async () => expectedResult.tools,
+      }))
+      mock.module("./formatter", () => ({
+        formatDoctorOutput: formatDoctorOutputMock,
+        formatJsonOutput: formatJsonOutputMock,
+      }))
 
-  describe("groupChecksByCategory", () => {
-    const checks: CheckDefinition[] = [
-      { id: "1", name: "Install1", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
-      { id: "2", name: "Install2", category: "installation", check: async () => ({ name: "", status: "pass", message: "" }) },
-      { id: "3", name: "Config", category: "configuration", check: async () => ({ name: "", status: "pass", message: "" }) },
-    ]
+      const logSpy = mock(() => {})
+      const originalLog = console.log
+      console.log = logSpy
 
-    it("groups checks by category", () => {
-      const groups = groupChecksByCategory(checks)
+      const { runDoctor } = await import(`./runner?parallel=${Date.now()}`)
+      const runPromise = runDoctor({ mode: "default" })
 
-      expect(groups.get("installation")?.length).toBe(2)
-      expect(groups.get("configuration")?.length).toBe(1)
-    })
+      //#when
+      await Promise.resolve()
+      const startedBeforeResolve = [...startedChecks]
+      deferredOne.resolve(createPassResult("System"))
+      deferredTwo.resolve(createPassResult("Configuration"))
+      deferredThree.resolve(createPassResult("Tools"))
+      deferredFour.resolve(createPassResult("Models"))
+      const result = await runPromise
 
-    it("maintains order within categories", () => {
-      const groups = groupChecksByCategory(checks)
-      const installChecks = groups.get("installation")!
-
-      expect(installChecks[0].name).toBe("Install1")
-      expect(installChecks[1].name).toBe("Install2")
+      //#then
+      console.log = originalLog
+      expect(startedBeforeResolve.sort()).toEqual(["config", "models", "system", "tools"])
+      expect(result.results.length).toBe(4)
+      expect(result.exitCode).toBe(0)
+      expect(formatDoctorOutputMock).toHaveBeenCalledTimes(1)
+      expect(formatJsonOutputMock).toHaveBeenCalledTimes(0)
     })
   })
 })

src/cli/doctor/runner.ts

@@ -1,21 +1,7 @@
-import type {
-  DoctorOptions,
-  DoctorResult,
-  CheckDefinition,
-  CheckResult,
-  DoctorSummary,
-  CheckCategory,
-} from "./types"
-import { getAllCheckDefinitions } from "./checks"
-import { EXIT_CODES, CATEGORY_NAMES } from "./constants"
-import {
-  formatHeader,
-  formatCategoryHeader,
-  formatCheckResult,
-  formatSummary,
-  formatFooter,
-  formatJsonOutput,
-} from "./formatter"
+import type { DoctorOptions, DoctorResult, CheckDefinition, CheckResult, DoctorSummary } from "./types"
+import { getAllCheckDefinitions, gatherSystemInfo, gatherToolsSummary } from "./checks"
+import { EXIT_CODES } from "./constants"
+import { formatDoctorOutput, formatJsonOutput } from "./formatter"
 
 export async function runCheck(check: CheckDefinition): Promise<CheckResult> {
   const start = performance.now()
@@ -28,6 +14,7 @@ export async function runCheck(check: CheckDefinition): Promise<CheckResult> {
       name: check.name,
       status: "fail",
       message: err instanceof Error ? err.message : "Unknown error",
+      issues: [{ title: check.name, description: String(err), severity: "error" }],
       duration: Math.round(performance.now() - start),
     }
   }
@@ -45,70 +32,18 @@ export function calculateSummary(results: CheckResult[], duration: number): Doct
 }
 
 export function determineExitCode(results: CheckResult[]): number {
-  const hasFailures = results.some((r) => r.status === "fail")
-  return hasFailures ? EXIT_CODES.FAILURE : EXIT_CODES.SUCCESS
+  return results.some((r) => r.status === "fail") ? EXIT_CODES.FAILURE : EXIT_CODES.SUCCESS
 }
 
-export function filterChecksByCategory(
-  checks: CheckDefinition[],
-  category?: CheckCategory
-): CheckDefinition[] {
-  if (!category) return checks
-  return checks.filter((c) => c.category === category)
-}
-
-export function groupChecksByCategory(
-  checks: CheckDefinition[]
-): Map<CheckCategory, CheckDefinition[]> {
-  const groups = new Map<CheckCategory, CheckDefinition[]>()
-
-  for (const check of checks) {
-    const existing = groups.get(check.category) ?? []
-    existing.push(check)
-    groups.set(check.category, existing)
-  }
-
-  return groups
-}
-
-const CATEGORY_ORDER: CheckCategory[] = [
-  "installation",
-  "configuration",
-  "authentication",
-  "dependencies",
-  "tools",
-  "updates",
-]
-
 export async function runDoctor(options: DoctorOptions): Promise<DoctorResult> {
   const start = performance.now()
+
   const allChecks = getAllCheckDefinitions()
-  const filteredChecks = filterChecksByCategory(allChecks, options.category)
-  const groupedChecks = groupChecksByCategory(filteredChecks)
-
-  const results: CheckResult[] = []
-
-  if (!options.json) {
-    console.log(formatHeader())
-  }
-
-  for (const category of CATEGORY_ORDER) {
-    const checks = groupedChecks.get(category)
-    if (!checks || checks.length === 0) continue
-
-    if (!options.json) {
-      console.log(formatCategoryHeader(category))
-    }
-
-    for (const check of checks) {
-      const result = await runCheck(check)
-      results.push(result)
-
-      if (!options.json) {
-        console.log(formatCheckResult(result, options.verbose ?? false))
-      }
-    }
-  }
+  const [results, systemInfo, tools] = await Promise.all([
+    Promise.all(allChecks.map(runCheck)),
+    gatherSystemInfo(),
+    gatherToolsSummary(),
+  ])
 
   const duration = performance.now() - start
   const summary = calculateSummary(results, duration)
@@ -116,6 +51,8 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorResult> {
 
   const doctorResult: DoctorResult = {
     results,
+    systemInfo,
+    tools,
     summary,
     exitCode,
   }
@@ -123,9 +60,7 @@ export async function runDoctor(options: DoctorOptions): Promise<DoctorResult> {
   if (options.json) {
     console.log(formatJsonOutput(doctorResult))
   } else {
-    console.log("")
-    console.log(formatSummary(summary))
-    console.log(formatFooter(summary))
+    console.log(formatDoctorOutput(doctorResult, options.mode))
   }
 
   return doctorResult

src/cli/doctor/types.ts

@@ -1,3 +1,20 @@
+// ===== New 3-tier doctor types =====
+
+export type DoctorMode = "default" | "status" | "verbose"
+
+export interface DoctorOptions {
+  mode: DoctorMode
+  json?: boolean
+}
+
+export interface DoctorIssue {
+  title: string
+  description: string
+  fix?: string
+  affects?: string[]
+  severity: "error" | "warning"
+}
+
 export type CheckStatus = "pass" | "fail" | "warn" | "skip"
 
 export interface CheckResult {
@@ -5,31 +22,39 @@ export interface CheckResult {
   status: CheckStatus
   message: string
   details?: string[]
+  issues: DoctorIssue[]
   duration?: number
 }
 
 export type CheckFunction = () => Promise<CheckResult>
 
-export type CheckCategory =
-  | "installation"
-  | "configuration"
-  | "authentication"
-  | "dependencies"
-  | "tools"
-  | "updates"
-
 export interface CheckDefinition {
   id: string
   name: string
-  category: CheckCategory
   check: CheckFunction
   critical?: boolean
 }
 
-export interface DoctorOptions {
-  verbose?: boolean
-  json?: boolean
-  category?: CheckCategory
+export interface SystemInfo {
+  opencodeVersion: string | null
+  opencodePath: string | null
+  pluginVersion: string | null
+  loadedVersion: string | null
+  bunVersion: string | null
+  configPath: string | null
+  configValid: boolean
+  isLocalDev: boolean
+}
+
+export interface ToolsSummary {
+  lspInstalled: number
+  lspTotal: number
+  astGrepCli: boolean
+  astGrepNapi: boolean
+  commentChecker: boolean
+  ghCli: { installed: boolean; authenticated: boolean; username: string | null }
+  mcpBuiltin: string[]
+  mcpUser: string[]
 }
 
 export interface DoctorSummary {
@@ -43,10 +68,22 @@ export interface DoctorSummary {
 
 export interface DoctorResult {
   results: CheckResult[]
+  systemInfo: SystemInfo
+  tools: ToolsSummary
   summary: DoctorSummary
   exitCode: number
 }
 
+// ===== Legacy types (used by existing checks until migration) =====
+
+export type CheckCategory =
+  | "installation"
+  | "configuration"
+  | "authentication"
+  | "dependencies"
+  | "tools"
+  | "updates"
+
 export interface OpenCodeInfo {
   installed: boolean
   version: string | null

src/cli/run/agent-resolver.ts

@@ -1,32 +1,45 @@
 import pc from "picocolors"
 import type { RunOptions } from "./types"
 import type { OhMyOpenCodeConfig } from "../../config"
+import { getAgentConfigKey, getAgentDisplayName } from "../../shared/agent-display-names"
 
 const CORE_AGENT_ORDER = ["sisyphus", "hephaestus", "prometheus", "atlas"] as const
 const DEFAULT_AGENT = "sisyphus"
 
 type EnvVars = Record<string, string | undefined>
+type CoreAgentKey = (typeof CORE_AGENT_ORDER)[number]
 
-const normalizeAgentName = (agent?: string): string | undefined => {
-  if (!agent) return undefined
-  const trimmed = agent.trim()
-  if (!trimmed) return undefined
-  const lowered = trimmed.toLowerCase()
-  const coreMatch = CORE_AGENT_ORDER.find((name) => name.toLowerCase() === lowered)
-  return coreMatch ?? trimmed
+interface ResolvedAgent {
+  configKey: string
+  resolvedName: string
 }
 
-const isAgentDisabled = (agent: string, config: OhMyOpenCodeConfig): boolean => {
-  const lowered = agent.toLowerCase()
-  if (lowered === "sisyphus" && config.sisyphus_agent?.disabled === true) {
+const normalizeAgentName = (agent?: string): ResolvedAgent | undefined => {
+  if (!agent) return undefined
+  const trimmed = agent.trim()
+  if (trimmed.length === 0) return undefined
+
+  const configKey = getAgentConfigKey(trimmed)
+  const displayName = getAgentDisplayName(configKey)
+  const isKnownAgent = displayName !== configKey
+
+  return {
+    configKey,
+    resolvedName: isKnownAgent ? displayName : trimmed,
+  }
+}
+
+const isAgentDisabled = (agentConfigKey: string, config: OhMyOpenCodeConfig): boolean => {
+  const lowered = agentConfigKey.toLowerCase()
+  if (lowered === DEFAULT_AGENT && config.sisyphus_agent?.disabled === true) {
     return true
   }
   return (config.disabled_agents ?? []).some(
-    (disabled) => disabled.toLowerCase() === lowered
+    (disabled) => getAgentConfigKey(disabled) === lowered
   )
 }
 
-const pickFallbackAgent = (config: OhMyOpenCodeConfig): string => {
+const pickFallbackAgent = (config: OhMyOpenCodeConfig): CoreAgentKey => {
   for (const agent of CORE_AGENT_ORDER) {
     if (!isAgentDisabled(agent, config)) {
       return agent
@@ -43,27 +56,33 @@ export const resolveRunAgent = (
   const cliAgent = normalizeAgentName(options.agent)
   const envAgent = normalizeAgentName(env.OPENCODE_DEFAULT_AGENT)
   const configAgent = normalizeAgentName(pluginConfig.default_run_agent)
-  const resolved = cliAgent ?? envAgent ?? configAgent ?? DEFAULT_AGENT
-  const normalized = normalizeAgentName(resolved) ?? DEFAULT_AGENT
+  const resolved =
+    cliAgent ??
+    envAgent ??
+    configAgent ?? {
+      configKey: DEFAULT_AGENT,
+      resolvedName: getAgentDisplayName(DEFAULT_AGENT),
+    }
 
-  if (isAgentDisabled(normalized, pluginConfig)) {
+  if (isAgentDisabled(resolved.configKey, pluginConfig)) {
     const fallback = pickFallbackAgent(pluginConfig)
+    const fallbackName = getAgentDisplayName(fallback)
     const fallbackDisabled = isAgentDisabled(fallback, pluginConfig)
     if (fallbackDisabled) {
       console.log(
         pc.yellow(
-          `Requested agent "${normalized}" is disabled and no enabled core agent was found. Proceeding with "${fallback}".`
+          `Requested agent "${resolved.resolvedName}" is disabled and no enabled core agent was found. Proceeding with "${fallbackName}".`
         )
       )
-      return fallback
+      return fallbackName
     }
     console.log(
       pc.yellow(
-        `Requested agent "${normalized}" is disabled. Falling back to "${fallback}".`
+        `Requested agent "${resolved.resolvedName}" is disabled. Falling back to "${fallbackName}".`
       )
     )
-    return fallback
+    return fallbackName
   }
 
-  return normalized
+  return resolved.resolvedName
 }

src/cli/run/completion.ts

@@ -1,5 +1,6 @@
 import pc from "picocolors"
 import type { RunContext, Todo, ChildSession, SessionStatus } from "./types"
+import { normalizeSDKResponse } from "../../shared"
 
 export async function checkCompletionConditions(ctx: RunContext): Promise<boolean> {
   try {
@@ -19,8 +20,11 @@ export async function checkCompletionConditions(ctx: RunContext): Promise<boolea
 }
 
 async function areAllTodosComplete(ctx: RunContext): Promise<boolean> {
-  const todosRes = await ctx.client.session.todo({ path: { id: ctx.sessionID } })
-  const todos = (todosRes.data ?? []) as Todo[]
+  const todosRes = await ctx.client.session.todo({
+    path: { id: ctx.sessionID },
+    query: { directory: ctx.directory },
+  })
+  const todos = normalizeSDKResponse(todosRes, [] as Todo[])
 
   const incompleteTodos = todos.filter(
     (t) => t.status !== "completed" && t.status !== "cancelled"
@@ -42,8 +46,10 @@ async function areAllChildrenIdle(ctx: RunContext): Promise<boolean> {
 async function fetchAllStatuses(
   ctx: RunContext
 ): Promise<Record<string, SessionStatus>> {
-  const statusRes = await ctx.client.session.status()
-  return (statusRes.data ?? {}) as Record<string, SessionStatus>
+  const statusRes = await ctx.client.session.status({
+    query: { directory: ctx.directory },
+  })
+  return normalizeSDKResponse(statusRes, {} as Record<string, SessionStatus>)
 }
 
 async function areAllDescendantsIdle(
@@ -53,8 +59,9 @@ async function areAllDescendantsIdle(
 ): Promise<boolean> {
   const childrenRes = await ctx.client.session.children({
     path: { id: sessionID },
+    query: { directory: ctx.directory },
   })
-  const children = (childrenRes.data ?? []) as ChildSession[]
+  const children = normalizeSDKResponse(childrenRes, [] as ChildSession[])
 
   for (const child of children) {
     const status = allStatuses[child.id]

src/cli/run/event-formatting.ts

@@ -57,7 +57,11 @@ export function serializeError(error: unknown): string {
 function getSessionTag(ctx: RunContext, payload: EventPayload): string {
   const props = payload.properties as Record<string, unknown> | undefined
   const info = props?.info as Record<string, unknown> | undefined
-  const sessionID = props?.sessionID ?? info?.sessionID
+  const part = props?.part as Record<string, unknown> | undefined
+  const sessionID =
+    props?.sessionID ?? props?.sessionId ??
+    info?.sessionID ?? info?.sessionId ??
+    part?.sessionID ?? part?.sessionId
   const isMainSession = sessionID === ctx.sessionID
   if (isMainSession) return pc.green("[MAIN]")
   if (sessionID) return pc.yellow(`[${String(sessionID).slice(0, 8)}]`)
@@ -79,9 +83,9 @@ export function logEventVerbose(ctx: RunContext, payload: EventPayload): void {
     case "message.part.updated": {
       const partProps = props as MessagePartUpdatedProps | undefined
       const part = partProps?.part
-      if (part?.type === "tool-invocation") {
-        const toolPart = part as { toolName?: string; state?: string }
-        console.error(pc.dim(`${sessionTag} message.part (tool): ${toolPart.toolName} [${toolPart.state}]`))
+      if (part?.type === "tool") {
+        const status = part.state?.status ?? "unknown"
+        console.error(pc.dim(`${sessionTag} message.part (tool): ${part.tool ?? part.name ?? "?"} [${status}]`))
       } else if (part?.type === "text" && part.text) {
         const preview = part.text.slice(0, 80).replace(/\n/g, "\\n")
         console.error(pc.dim(`${sessionTag} message.part (text): "${preview}${part.text.length > 80 ? "..." : ""}"`))

src/cli/run/event-handlers.test.ts

@@ -1,7 +1,7 @@
-import { describe, it, expect } from "bun:test"
+import { describe, it, expect, spyOn } from "bun:test"
 import type { RunContext } from "./types"
 import { createEventState } from "./events"
-import { handleSessionStatus } from "./event-handlers"
+import { handleSessionStatus, handleMessagePartUpdated, handleTuiToast } from "./event-handlers"
 
 const createMockContext = (sessionID: string = "test-session"): RunContext => ({
   sessionID,
@@ -70,4 +70,211 @@ describe("handleSessionStatus", () => {
     //#then - state.mainSessionIdle remains unchanged
     expect(state.mainSessionIdle).toBe(true)
   })
+
+  it("recognizes idle from camelCase sessionId", () => {
+    //#given - state with mainSessionIdle=false and payload using sessionId
+    const ctx = createMockContext("test-session")
+    const state = createEventState()
+    state.mainSessionIdle = false
+
+    const payload = {
+      type: "session.status",
+      properties: {
+        sessionId: "test-session",
+        status: { type: "idle" as const },
+      },
+    }
+
+    //#when - handleSessionStatus called with camelCase sessionId
+    handleSessionStatus(ctx, payload as any, state)
+
+    //#then - state.mainSessionIdle === true
+    expect(state.mainSessionIdle).toBe(true)
+  })
+})
+
+describe("handleMessagePartUpdated", () => {
+  it("extracts sessionID from part (current OpenCode event structure)", () => {
+    //#given - message.part.updated with sessionID in part, not info
+    const ctx = createMockContext("ses_main")
+    const state = createEventState()
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true)
+
+    const payload = {
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "part_1",
+          sessionID: "ses_main",
+          messageID: "msg_1",
+          type: "text",
+          text: "Hello world",
+        },
+      },
+    }
+
+    //#when
+    handleMessagePartUpdated(ctx, payload as any, state)
+
+    //#then
+    expect(state.hasReceivedMeaningfulWork).toBe(true)
+    expect(state.lastPartText).toBe("Hello world")
+    expect(stdoutSpy).toHaveBeenCalled()
+    stdoutSpy.mockRestore()
+  })
+
+  it("skips events for different session", () => {
+    //#given - message.part.updated with different session
+    const ctx = createMockContext("ses_main")
+    const state = createEventState()
+
+    const payload = {
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "part_1",
+          sessionID: "ses_other",
+          messageID: "msg_1",
+          type: "text",
+          text: "Hello world",
+        },
+      },
+    }
+
+    //#when
+    handleMessagePartUpdated(ctx, payload as any, state)
+
+    //#then
+    expect(state.hasReceivedMeaningfulWork).toBe(false)
+    expect(state.lastPartText).toBe("")
+  })
+
+  it("handles tool part with running status", () => {
+    //#given - tool part in running state
+    const ctx = createMockContext("ses_main")
+    const state = createEventState()
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true)
+
+    const payload = {
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "part_1",
+          sessionID: "ses_main",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "read",
+          state: { status: "running", input: { filePath: "/src/index.ts" } },
+        },
+      },
+    }
+
+    //#when
+    handleMessagePartUpdated(ctx, payload as any, state)
+
+    //#then
+    expect(state.currentTool).toBe("read")
+    expect(state.hasReceivedMeaningfulWork).toBe(true)
+    stdoutSpy.mockRestore()
+  })
+
+  it("clears currentTool when tool completes", () => {
+    //#given - tool part in completed state
+    const ctx = createMockContext("ses_main")
+    const state = createEventState()
+    state.currentTool = "read"
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true)
+
+    const payload = {
+      type: "message.part.updated",
+      properties: {
+        part: {
+          id: "part_1",
+          sessionID: "ses_main",
+          messageID: "msg_1",
+          type: "tool",
+          tool: "read",
+          state: { status: "completed", input: {}, output: "file contents here" },
+        },
+      },
+    }
+
+    //#when
+    handleMessagePartUpdated(ctx, payload as any, state)
+
+    //#then
+    expect(state.currentTool).toBeNull()
+    stdoutSpy.mockRestore()
+  })
+
+  it("supports legacy info.sessionID for backward compatibility", () => {
+    //#given - legacy event with sessionID in info
+    const ctx = createMockContext("ses_legacy")
+    const state = createEventState()
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(() => true)
+
+    const payload = {
+      type: "message.part.updated",
+      properties: {
+        info: { sessionID: "ses_legacy", role: "assistant" },
+        part: {
+          type: "text",
+          text: "Legacy text",
+        },
+      },
+    }
+
+    //#when
+    handleMessagePartUpdated(ctx, payload as any, state)
+
+    //#then
+    expect(state.hasReceivedMeaningfulWork).toBe(true)
+    expect(state.lastPartText).toBe("Legacy text")
+    stdoutSpy.mockRestore()
+  })
+})
+
+describe("handleTuiToast", () => {
+  it("marks main session as error when toast variant is error", () => {
+    //#given - toast error payload
+    const ctx = createMockContext("test-session")
+    const state = createEventState()
+
+    const payload = {
+      type: "tui.toast.show",
+      properties: {
+        title: "Auth",
+        message: "Invalid API key",
+        variant: "error" as const,
+      },
+    }
+
+    //#when
+    handleTuiToast(ctx, payload as any, state)
+
+    //#then
+    expect(state.mainSessionError).toBe(true)
+    expect(state.lastError).toBe("Auth: Invalid API key")
+  })
+
+  it("does not mark session error for warning toast", () => {
+    //#given - toast warning payload
+    const ctx = createMockContext("test-session")
+    const state = createEventState()
+
+    const payload = {
+      type: "tui.toast.show",
+      properties: {
+        message: "Retrying provider",
+        variant: "warning" as const,
+      },
+    }
+
+    //#when
+    handleTuiToast(ctx, payload as any, state)
+
+    //#then
+    expect(state.mainSessionError).toBe(false)
+    expect(state.lastError).toBe(null)
+  })
 })

src/cli/run/event-handlers.ts

@@ -9,15 +9,32 @@ import type {
   MessagePartUpdatedProps,
   ToolExecuteProps,
   ToolResultProps,
+  TuiToastShowProps,
 } from "./types"
 import type { EventState } from "./event-state"
 import { serializeError } from "./event-formatting"
 
+function getSessionId(props?: { sessionID?: string; sessionId?: string }): string | undefined {
+  return props?.sessionID ?? props?.sessionId
+}
+
+function getInfoSessionId(props?: {
+  info?: { sessionID?: string; sessionId?: string }
+}): string | undefined {
+  return props?.info?.sessionID ?? props?.info?.sessionId
+}
+
+function getPartSessionId(props?: {
+  part?: { sessionID?: string; sessionId?: string }
+}): string | undefined {
+  return props?.part?.sessionID ?? props?.part?.sessionId
+}
+
 export function handleSessionIdle(ctx: RunContext, payload: EventPayload, state: EventState): void {
   if (payload.type !== "session.idle") return
 
   const props = payload.properties as SessionIdleProps | undefined
-  if (props?.sessionID === ctx.sessionID) {
+  if (getSessionId(props) === ctx.sessionID) {
     state.mainSessionIdle = true
   }
 }
@@ -26,7 +43,7 @@ export function handleSessionStatus(ctx: RunContext, payload: EventPayload, stat
   if (payload.type !== "session.status") return
 
   const props = payload.properties as SessionStatusProps | undefined
-  if (props?.sessionID !== ctx.sessionID) return
+  if (getSessionId(props) !== ctx.sessionID) return
 
   if (props?.status?.type === "busy") {
     state.mainSessionIdle = false
@@ -41,7 +58,7 @@ export function handleSessionError(ctx: RunContext, payload: EventPayload, state
   if (payload.type !== "session.error") return
 
   const props = payload.properties as SessionErrorProps | undefined
-  if (props?.sessionID === ctx.sessionID) {
+  if (getSessionId(props) === ctx.sessionID) {
     state.mainSessionError = true
     state.lastError = serializeError(props?.error)
     console.error(pc.red(`\n[session.error] ${state.lastError}`))
@@ -52,10 +69,12 @@ export function handleMessagePartUpdated(ctx: RunContext, payload: EventPayload,
   if (payload.type !== "message.part.updated") return
 
   const props = payload.properties as MessagePartUpdatedProps | undefined
-  if (props?.info?.sessionID !== ctx.sessionID) return
-  if (props?.info?.role !== "assistant") return
+  // Current OpenCode puts sessionID inside part; legacy puts it in info
+  const partSid = getPartSessionId(props)
+  const infoSid = getInfoSessionId(props)
+  if ((partSid ?? infoSid) !== ctx.sessionID) return
 
-  const part = props.part
+  const part = props?.part
   if (!part) return
 
   if (part.type === "text" && part.text) {
@@ -66,13 +85,57 @@ export function handleMessagePartUpdated(ctx: RunContext, payload: EventPayload,
     }
     state.lastPartText = part.text
   }
+
+  if (part.type === "tool") {
+    handleToolPart(ctx, part, state)
+  }
+}
+
+function handleToolPart(
+  _ctx: RunContext,
+  part: NonNullable<MessagePartUpdatedProps["part"]>,
+  state: EventState,
+): void {
+  const toolName = part.tool || part.name || "unknown"
+  const status = part.state?.status
+
+  if (status === "running") {
+    state.currentTool = toolName
+    let inputPreview = ""
+    const input = part.state?.input
+    if (input) {
+      if (input.command) {
+        inputPreview = ` ${pc.dim(String(input.command).slice(0, 60))}`
+      } else if (input.pattern) {
+        inputPreview = ` ${pc.dim(String(input.pattern).slice(0, 40))}`
+      } else if (input.filePath) {
+        inputPreview = ` ${pc.dim(String(input.filePath))}`
+      } else if (input.query) {
+        inputPreview = ` ${pc.dim(String(input.query).slice(0, 40))}`
+      }
+    }
+    state.hasReceivedMeaningfulWork = true
+    process.stdout.write(`\n${pc.cyan(">")} ${pc.bold(toolName)}${inputPreview}\n`)
+  }
+
+  if (status === "completed" || status === "error") {
+    const output = part.state?.output || ""
+    const maxLen = 200
+    const preview = output.length > maxLen ? output.slice(0, maxLen) + "..." : output
+    if (preview.trim()) {
+      const lines = preview.split("\n").slice(0, 3)
+      process.stdout.write(pc.dim(`   └─ ${lines.join("\n      ")}\n`))
+    }
+    state.currentTool = null
+    state.lastPartText = ""
+  }
 }
 
 export function handleMessageUpdated(ctx: RunContext, payload: EventPayload, state: EventState): void {
   if (payload.type !== "message.updated") return
 
   const props = payload.properties as MessageUpdatedProps | undefined
-  if (props?.info?.sessionID !== ctx.sessionID) return
+  if (getInfoSessionId(props) !== ctx.sessionID) return
   if (props?.info?.role !== "assistant") return
 
   state.hasReceivedMeaningfulWork = true
@@ -84,7 +147,7 @@ export function handleToolExecute(ctx: RunContext, payload: EventPayload, state:
   if (payload.type !== "tool.execute") return
 
   const props = payload.properties as ToolExecuteProps | undefined
-  if (props?.sessionID !== ctx.sessionID) return
+  if (getSessionId(props) !== ctx.sessionID) return
 
   const toolName = props?.name || "unknown"
   state.currentTool = toolName
@@ -111,7 +174,7 @@ export function handleToolResult(ctx: RunContext, payload: EventPayload, state:
   if (payload.type !== "tool.result") return
 
   const props = payload.properties as ToolResultProps | undefined
-  if (props?.sessionID !== ctx.sessionID) return
+  if (getSessionId(props) !== ctx.sessionID) return
 
   const output = props?.output || ""
   const maxLen = 200
@@ -125,3 +188,24 @@ export function handleToolResult(ctx: RunContext, payload: EventPayload, state:
   state.currentTool = null
   state.lastPartText = ""
 }
+
+export function handleTuiToast(_ctx: RunContext, payload: EventPayload, state: EventState): void {
+  if (payload.type !== "tui.toast.show") return
+
+  const props = payload.properties as TuiToastShowProps | undefined
+  const title = props?.title ? `${props.title}: ` : ""
+  const message = props?.message?.trim()
+  const variant = props?.variant ?? "info"
+
+  if (!message) return
+
+  if (variant === "error") {
+    state.mainSessionError = true
+    state.lastError = `${title}${message}`
+    console.error(pc.red(`\n[tui.toast.error] ${state.lastError}`))
+    return
+  }
+
+  const colorize = variant === "warning" ? pc.yellow : pc.dim
+  console.log(colorize(`[toast:${variant}] ${title}${message}`))
+}

src/cli/run/event-stream-processor.ts

@@ -10,6 +10,7 @@ import {
   handleMessageUpdated,
   handleToolExecute,
   handleToolResult,
+  handleTuiToast,
 } from "./event-handlers"
 
 export async function processEvents(
@@ -36,6 +37,7 @@ export async function processEvents(
       handleMessageUpdated(ctx, payload, state)
       handleToolExecute(ctx, payload, state)
       handleToolResult(ctx, payload, state)
+      handleTuiToast(ctx, payload, state)
     } catch (err) {
       console.error(pc.red(`[event error] ${err}`))
     }

src/cli/run/events.test.ts

@@ -170,6 +170,28 @@ describe("event handling", () => {
     expect(state.hasReceivedMeaningfulWork).toBe(true)
   })
 
+  it("message.updated with camelCase sessionId sets hasReceivedMeaningfulWork", async () => {
+    //#given - assistant message uses sessionId key
+    const ctx = createMockContext("my-session")
+    const state = createEventState()
+
+    const payload: EventPayload = {
+      type: "message.updated",
+      properties: {
+        info: { sessionId: "my-session", role: "assistant" },
+      },
+    }
+
+    const events = toAsyncIterable([payload])
+    const { processEvents } = await import("./events")
+
+    //#when
+    await processEvents(ctx, events, state)
+
+    //#then
+    expect(state.hasReceivedMeaningfulWork).toBe(true)
+  })
+
   it("message.updated with user role does not set hasReceivedMeaningfulWork", async () => {
     // given - user message should not count as meaningful work
     const ctx = createMockContext("my-session")
@@ -251,6 +273,7 @@ describe("event handling", () => {
       lastPartText: "",
       currentTool: null,
       hasReceivedMeaningfulWork: false,
+      messageCount: 0,
     }
 
     const payload: EventPayload = {

src/cli/run/integration.test.ts

@@ -1,9 +1,11 @@
-import { describe, it, expect, mock, spyOn, beforeEach, afterEach } from "bun:test"
+import { describe, it, expect, mock, spyOn, beforeEach, afterEach, afterAll } from "bun:test"
 import type { RunResult } from "./types"
 import { createJsonOutputManager } from "./json-output"
 import { resolveSession } from "./session-resolver"
 import { executeOnCompleteHook } from "./on-complete-hook"
 import type { OpencodeClient } from "./types"
+import * as originalSdk from "@opencode-ai/sdk"
+import * as originalPortUtils from "../../shared/port-utils"
 
 const mockServerClose = mock(() => {})
 const mockCreateOpencode = mock(() =>
@@ -27,6 +29,11 @@ mock.module("../../shared/port-utils", () => ({
   DEFAULT_SERVER_PORT: 4096,
 }))
 
+afterAll(() => {
+  mock.module("@opencode-ai/sdk", () => originalSdk)
+  mock.module("../../shared/port-utils", () => originalPortUtils)
+})
+
 const { createServerConnection } = await import("./server-connection")
 
 interface MockWriteStream {
@@ -120,11 +127,14 @@ describe("integration: --session-id", () => {
     const mockClient = createMockClient({ data: { id: sessionId } })
 
     // when
-    const result = await resolveSession({ client: mockClient, sessionId })
+    const result = await resolveSession({ client: mockClient, sessionId, directory: "/test" })
 
     // then
     expect(result).toBe(sessionId)
-    expect(mockClient.session.get).toHaveBeenCalledWith({ path: { id: sessionId } })
+    expect(mockClient.session.get).toHaveBeenCalledWith({
+      path: { id: sessionId },
+      query: { directory: "/test" },
+    })
     expect(mockClient.session.create).not.toHaveBeenCalled()
   })
 
@@ -134,11 +144,14 @@ describe("integration: --session-id", () => {
     const mockClient = createMockClient({ error: { message: "Session not found" } })
 
     // when
-    const result = resolveSession({ client: mockClient, sessionId })
+    const result = resolveSession({ client: mockClient, sessionId, directory: "/test" })
 
     // then
     await expect(result).rejects.toThrow(`Session not found: ${sessionId}`)
-    expect(mockClient.session.get).toHaveBeenCalledWith({ path: { id: sessionId } })
+    expect(mockClient.session.get).toHaveBeenCalledWith({
+      path: { id: sessionId },
+      query: { directory: "/test" },
+    })
     expect(mockClient.session.create).not.toHaveBeenCalled()
   })
 })

src/cli/run/opencode-bin-path.test.ts

@@ -0,0 +1,52 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, it } from "bun:test"
+import { prependResolvedOpencodeBinToPath } from "./opencode-bin-path"
+
+describe("prependResolvedOpencodeBinToPath", () => {
+  it("prepends resolved opencode-ai bin path to PATH", () => {
+    //#given
+    const env: Record<string, string | undefined> = {
+      PATH: "/Users/yeongyu/node_modules/.bin:/usr/bin",
+    }
+    const resolver = () => "/tmp/bunx-123/node_modules/opencode-ai/bin/opencode"
+
+    //#when
+    prependResolvedOpencodeBinToPath(env, resolver)
+
+    //#then
+    expect(env.PATH).toBe(
+      "/tmp/bunx-123/node_modules/opencode-ai/bin:/Users/yeongyu/node_modules/.bin:/usr/bin",
+    )
+  })
+
+  it("does not duplicate an existing opencode-ai bin path", () => {
+    //#given
+    const env: Record<string, string | undefined> = {
+      PATH: "/tmp/bunx-123/node_modules/opencode-ai/bin:/usr/bin",
+    }
+    const resolver = () => "/tmp/bunx-123/node_modules/opencode-ai/bin/opencode"
+
+    //#when
+    prependResolvedOpencodeBinToPath(env, resolver)
+
+    //#then
+    expect(env.PATH).toBe("/tmp/bunx-123/node_modules/opencode-ai/bin:/usr/bin")
+  })
+
+  it("keeps PATH unchanged when opencode-ai cannot be resolved", () => {
+    //#given
+    const env: Record<string, string | undefined> = {
+      PATH: "/Users/yeongyu/node_modules/.bin:/usr/bin",
+    }
+    const resolver = () => {
+      throw new Error("module not found")
+    }
+
+    //#when
+    prependResolvedOpencodeBinToPath(env, resolver)
+
+    //#then
+    expect(env.PATH).toBe("/Users/yeongyu/node_modules/.bin:/usr/bin")
+  })
+})