docs(agents): refresh AGENTS.md hierarchy via /init-deep

Updated root + 14 core subdirectory AGENTS.md files to reflect current state (commit 2892ca4a on dev). Added 4 new AGENTS.md files for gap directories: hooks/comment-checker (AI slop blocker), features/claude- code-plugin-loader (CC compat layer), features/claude-code-mcp-loader (tier 2 MCP loader), cli/doctor (health diagnostics with 25 check files).
2026-04-18 01:21:20 +09:00
parent 2892ca4adf
commit 5759a9c503
19 changed files with 316 additions and 16 deletions
@@ -1,6 +1,6 @@
 # src/cli/ — CLI: install, run, doctor, mcp-oauth

-**Generated:** 2026-04-11
+**Generated:** 2026-04-18

 ## OVERVIEW

@@ -0,0 +1,82 @@
+# src/cli/doctor/ — Health Diagnostics (25 Check Files)
+
+**Generated:** 2026-04-18
+
+## OVERVIEW
+
+`bunx oh-my-opencode doctor` — parallel diagnostic checks across 4 categories (System, Config, Tools, Models). Catches broken installs, config typos, missing dependencies, provider misconfigurations before they become runtime errors.
+
+## COMMAND FLAGS
+
+```bash
+bunx oh-my-opencode doctor              # Full diagnostics (all 4 categories)
+bunx oh-my-opencode doctor --status     # Compact dashboard (status only)
+bunx oh-my-opencode doctor --verbose    # Deep details (model resolution traces)
+bunx oh-my-opencode doctor --json       # Machine-readable output
+```
+
+## CHECK CATEGORIES
+
+| Category | File | Validates |
+|----------|------|-----------|
+| **SYSTEM** | `checks/system.ts` | OpenCode binary found + version ≥1.0.150, plugin registered in opencode.json, loaded plugin version matches installed |
+| **CONFIG** | `checks/config.ts` | JSONC validity, Zod schema passes, no unknown keys, model override syntax correct |
+| **TOOLS** | `checks/tools.ts` | AST-Grep CLI + NAPI, comment-checker binary, LSP servers reachable, GitHub CLI auth, built-in MCP reachability |
+| **MODELS** | `checks/model-resolution.ts` | models.json cache exists, per-agent fallback resolution, category overrides valid, provider availability |
+
+## SUPPORTING CHECK FILES (25 total)
+
+```
+checks/
+├── index.ts                               # Registration
+├── system.ts                              # Main System aggregator
+├── system-binary.ts                       # OpenCode binary discovery (PATH + desktop app)
+├── system-plugin.ts                       # opencode.json plugin entry detection
+├── system-loaded-version.ts               # Cache vs npm latest
+├── config.ts                              # Main Config aggregator
+├── tools.ts                               # Main Tools aggregator
+├── dependencies.ts                        # AST-Grep CLI/NAPI + comment-checker presence
+├── tools-gh.ts                            # gh cli install + auth status
+├── tools-lsp.ts                           # LSP server enumeration
+├── tools-mcp.ts                           # Built-in + user MCP reachability
+├── model-resolution.ts                    # Main Models aggregator
+├── model-resolution-cache.ts              # models.json presence + freshness
+├── model-resolution-config.ts             # oh-my-opencode.jsonc parse
+├── model-resolution-effective-model.ts    # Per-agent fallback chain trace
+├── model-resolution-variant.ts            # Model variant (max, high, medium) handling
+├── model-resolution-details.ts            # Verbose output formatter
+└── model-resolution-types.ts              # Shared types
+```
+
+## EXECUTION FLOW
+
+```
+doctor command
+  → runner.ts: parallel check execution with 30s per-check timeout
+  → checks/index.ts registers all 4 category checks
+  → each check returns: { status: "ok" | "warn" | "error", detail: string }
+  → formatter.ts: render to stdout (text/status/json)
+  → exit code: 0 (all ok) | 1 (errors) | 2 (warnings only)
+```
+
+## KEY FILES
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | CLI command entry, flag parsing |
+| `runner.ts` | Parallel `Promise.allSettled()` orchestration, 30s timeout per check |
+| `formatter.ts` | Pretty printing: colored status, hierarchical output |
+| `types.ts` | `DoctorCheck`, `CheckResult`, `DoctorReport` types |
+
+## HOW TO ADD A CHECK
+
+1. Create `src/cli/doctor/checks/{name}.ts` exporting check function matching `DoctorCheck`
+2. Register in `checks/index.ts`
+3. Category-level aggregator (system/config/tools/model-resolution) invokes it
+4. Return `{ status, detail }` — no throws, all errors caught by runner
+
+## EXIT CODES
+
+- `0`: All checks passed (or only info messages)
+- `1`: One or more errors — plugin will likely not work
+- `2`: Warnings only — plugin works with degraded features