agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/data/skills/ops/docs-generator/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: docs-generator
+description: 'WHAT — Generate or update documentation from code: README.md from repo structure, CHANGELOG.md
+  from git history, API reference from OpenAPI/GraphQL schemas, and AGENTS.md starters for new projects.'
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - docs
+  - readme
+  - changelog
+  - api-reference
+  - agents
+---
+# Docs Generator (WHAT)
+
+Generate or refresh documentation from the actual code, schema, and git history.
+Never invent — always derive from evidence in the repo.
+
+## When to use
+
+- README is missing, stale, or doesn't reflect the current stack
+- CHANGELOG needs to be generated from merged PRs or git log
+- API spec (OpenAPI/GraphQL) exists but human-readable docs don't
+- New repo needs an AGENTS.md to onboard AI assistants
+
+## Out of scope
+
+- Does NOT write code — documentation only
+- Does NOT commit or push — delegate to **`github-cli-workflow`**
+- Does NOT update external systems (Confluence, Notion) — use their respective skills
+
+## Workflow
+
+### README.md generation
+
+1. Inspect repo: `package.json` / `pyproject.toml` / `Cargo.toml` for name, description, stack
+2. Read `Makefile` / `justfile` / `package.json scripts` for commands
+3. Read `.github/workflows/` for CI structure
+4. Draft README with: Purpose, Stack, Prerequisites, Quick Start, Development, Testing, Contributing
+5. Apply **`output-handshake`** before writing
+
+### CHANGELOG.md generation
+
+```bash
+# Conventional commits format
+git log --oneline --no-merges --pretty="format:%h %s" $(git describe --tags --abbrev=0)..HEAD
+
+# Group by type: feat / fix / docs / chore / refactor / perf / test
+# Format: ## [Unreleased] with subsections per type
+```
+
+Draft changelog section and ask user to confirm version before finalizing.
+
+### API reference generation
+
+- OpenAPI spec → readable endpoint table with params, responses, auth
+- GraphQL schema → type reference with fields and descriptions
+- Always note the spec version and date in the generated doc
+
+### AGENTS.md starter
+
+Use the template from `~/.local/share//skills-catalog.yaml` patterns:
+
+- Purpose and stack
+- Repository inspection order
+- What AI assistants may and must not do
+- Key commands (build, test, lint)
+- Links to key docs
+
+## Inline Documentation (why, not what) — per `addyosmani/agent-skills` `documentation-and-adrs` 2026-08-12 diff `docs/research/diff-394-documentation-and-adrs.md`
+
+Comment the *why*, not the *what*:
+
+```typescript
+// BAD: Restates the code
+// Increment counter by 1
+counter += 1;
+
+// GOOD: Explains non-obvious intent
+// Rate limit uses a sliding window — reset counter at window boundary,
+// not on a fixed schedule, to prevent burst attacks at window edges
+if (now - windowStart > WINDOW_SIZE_MS) {
+  counter = 0;
+  windowStart = now;
+}
+```
+
+* **When NOT to comment:** self-explanatory code (`calculateTotal` reduce), week-old `TODO`s (do it now), commented-out code (delete — git has history).
+* **Document Known Gotchas inline** where they matter:
+```typescript
+/**
+ * IMPORTANT: Must be called before first render — after hydration causes FOUC
+ * (theme context not available during SSR). See ADR-003.
+ */
+export function initializeTheme(theme: Theme): void { ... }
+```
+
+**Do not invent docs from thin air** — derive from code/specs/git history (this skill) vs ADR *why* (via `adr` skill). `personas/` (HOW agent thinks) vs `skills/` (HOW task executes) preserved — see `docs/CONCEPTS.md`.
+
+## Verification (after documenting)
+
+* [ ] ADRs exist for all significant decisions, README covers quick start/commands/architecture (link ADRs), API docs have types, gotchas inline, no commented-out code, `CLAUDE.md`/`AGENTS.md` current.
+* Rationalizations table — "code is self-documenting" (reality: code shows what, not why/alternatives), "docs when API stabilizes" (doc is first test of design), "ADRs are overhead" (10-min ADR prevents 2-hour debate).
+
+## Anti-patterns
+
+- Do not guess stack or commands — read from actual config files
+- Do not generate CHANGELOG from unstaged changes
+- Do not overwrite existing README without showing diff first
+
+## Delegates to
+
+| Need | Skill |
+|------|-------|
+| Push and create PR with generated docs | **`github-cli-workflow`** |
+| Confirm output destination | **`output-handshake`** |
+| Repo discovery | **`assistant`** |

agent_toolkit/data/skills/ops/llm-cost-advisor/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: llm-cost-advisor
+description: WHAT — Recommend the most cost-effective LLM provider for a given task type. Shows estimated
+  cost per run across available providers and integrates with devcompanion llm-status to show what is
+  actually available.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - llm
+  - cost
+  - provider
+  - optimization
+---
+# LLM Cost Advisor (WHAT)
+
+Recommend the right provider for the task at hand — balancing quality, cost, and privacy.
+
+## When to use
+
+- User asks "which model should I use for X?"
+- Before scheduling expensive loops (pr-babysitter, ci-sweeper)
+- When dev-companion jobs are unexpectedly expensive
+- When choosing between local and cloud providers for sensitive work
+
+## Out of scope
+
+- Does NOT configure providers — that's done via env vars and `loadenv`
+- Does NOT run LLM calls — it advises, the runner executes
+
+## Workflow
+
+**Step 1 — Check available providers:**
+
+```bash
+devcompanion llm-status
+```
+
+**Step 2 — Classify the task:**
+
+| Task type | Recommended tier | Why |
+|-----------|-----------------|-----|
+| Interactive code review, planning, debugging | Claude Sonnet / GPT-4o | Reasoning quality matters |
+| Batch labeling, summarization, triage | Claude Haiku / GPT-4o-mini | High volume, lower stakes |
+| Private/sensitive codebase work | Ollama or OpenCode | Stays local, zero cost |
+| Loop L1 (observation only) | Haiku / GPT-4o-mini | Low stakes, runs daily |
+| Loop L2 (PR creation) | Sonnet | Creates external artifacts |
+| Loop L3 (unattended) | Sonnet + verifier | Autonomous — quality critical |
+
+**Step 3 — Show cost estimate:**
+
+| Provider | Model | Est. per run | Monthly (1/day) | Monthly (96/day) |
+|----------|-------|-------------|-----------------|-----------------|
+| Anthropic | claude-3-5-sonnet | ~$0.05 | ~$1.50 | ~$144 |
+| Anthropic | claude-3-haiku | ~$0.005 | ~$0.15 | ~$14.40 |
+| OpenAI | gpt-4o | ~$0.04 | ~$1.20 | ~$115 |
+| OpenAI | gpt-4o-mini | ~$0.003 | ~$0.09 | ~$8.64 |
+| Ollama | (local) | $0 | $0 | $0 |
+| OpenCode | (local) | $0 | $0 | $0 |
+
+*Estimates based on ~2K input + ~1K output tokens per typical run.*
+
+**Step 4 — Recommend with reasoning:**
+
+Give a clear recommendation: "For daily CNA issue triage (L1, observation only), use
+claude-3-haiku — ~$0.15/month vs $1.50/month for Sonnet, with no quality difference
+for labeling and summarization tasks."
+
+## Budget gate reminder
+
+If the user is setting up loops, remind them to add `limits.max_cost_usd` to their job
+definitions to enable the runner's hard budget enforcement:
+
+```json
+"limits": {
+  "timeout_sec": 300,
+  "max_cost_usd": 0.50
+}
+```
+
+## Anti-patterns
+
+- Do not recommend cloud providers for repos marked confidential — suggest Ollama/OpenCode
+- Do not recommend Haiku for L3 unattended loops — quality failures cascade
+- Do not skip the `llm-status` check — recommend only available providers

agent_toolkit/data/skills/ops/swarm/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: swarm
+description: Launch an Agent Toolkit swarm from a natural language request using agent-toolkit swarm CLI
+  with Herdr/tmux eager windows and file handoffs.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - swarm
+  - herdr
+  - tmux
+  - orchestration
+  - multi-agent
+---
+# Swarm
+
+Launch a production Agent Toolkit swarm from any natural language request via the `agent-toolkit swarm` CLI. Herdr is the default UI for an excellent interactive experience; tmux is the isolated fallback.
+
+## When to use
+
+- User says "launch a swarm", "start a swarm", "swarm this task", or describes parallel/team work that benefits from multiple agents.
+- Any task that mentions swarm, pair/team/full, Herdr, tmux, or worktree-per-writer.
+- User wants to reuse an existing swarm run for a new request (same windows, new handoff).
+
+## Prerequisites
+
+- `agent-toolkit` installed and on PATH (`agent-toolkit swarm doctor` should pass).
+- For Herdr: `herdr` CLI installed (`herdr --version`); Herdr daemon running.
+- For tmux: `tmux` installed; isolated socket is `agent-toolkit-swarm-<run-id>`.
+- Run inside a Git repo (or pass `--workspace /path/to/repo`).
+- Optional: `~/.config/agent-toolkit/swarm.yaml` for model-profile mapping (`economy` → `opencode/mimo-v2.5-free`, `balanced` → provider default).
+
+## Workflow
+
+### 1. Inspect intent
+
+Extract from the user prompt:
+- **Task**: free-form objective (if missing, start swarm ready for interactive input).
+- **Recipe**: `pair` (2 roles: implementer→reviewer, fast), `team` (implementer→reviewer→integrator), `full` (large, 5+ roles). Default `pair` unless task needs more.
+- **Runner**: `opencode` (default, free models) or `claude` (Anthropic). Respect `--runner` if user names it.
+- **Model profile**: `economy` (`opencode/mimo-v2.5-free`) or `balanced` (provider default). Default `balanced`.
+- **UI**: `herdr` (default) or `tmux` (isolated). Respect `--ui` if given.
+
+### 2. Check health
+
+```bash
+agent-toolkit swarm doctor
+agent-toolkit swarm recipes
+```
+
+If doctor fails, report diagnostics and fix `herdr`/`tmux`/runner availability before launching.
+
+### 3. Launch
+
+Always use the CLI; never fabricate `state.json` or backend state.
+
+```bash
+# Herdr (preferred) — eager windows, shell-aware (detects $SHELL/zsh), attach by default
+agent-toolkit swarm start --recipe pair --ui herdr --runner opencode --model-profile balanced --attach "task"
+
+# Tmux (fallback) — isolated socket
+agent-toolkit swarm start --recipe team --ui tmux --runner claude --model-profile economy --attach "task"
+
+# Headless / no prompt — starts swarm ready, no initial task
+agent-toolkit swarm start --recipe pair --ui herdr --runner opencode --model-profile balanced --attach
+
+# Reuse same run/windows for a new request
+agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact "artifacts/new-task.md" --run-id <run-id>
+```
+
+Flags: `--json` for machine output, `--no-attach` for CI/script mode, `--workspace / -C <path>` to target a different repo.
+
+Eager UX (automatic):
+- Every role gets a window/tab immediately with `Waiting for handoff: <pred> -> <role> | role: <role> | run: <run_id>` and `agent_waiting` trace.
+- Implementer is focused on start; agents start lazily on handoff/file trigger.
+- Shell is detected (`$SHELL` → `pwd.getpwuid` → `/usr/bin/zsh` fallback); commands run as `<shell> -lc`.
+
+### 4. Monitor and handoff
+
+```bash
+agent-toolkit swarm status --run-id <run-id>
+agent-toolkit swarm handoffs --run-id <run-id>
+agent-toolkit swarm logs --run-id <run-id> --follow
+agent-toolkit swarm task next --role reviewer --run-id <run-id>
+agent-toolkit swarm task complete --run-id <run-id> --task-id <id>
+agent-toolkit swarm attach --run-id <run-id>
+```
+
+File handoff: `artifacts/` → `handoff create --type artifact --from X --to Y --artifact <path>`. When `handoff create` targets an `active` handoff's `to == from_role`, that handoff auto-completes (`auto:true`) and the next agent is provisioned with its worktree/tab.
+
+### 5. Reuse windows
+
+Same run can handle sequential requests: send a new artifact handoff to the implementer; the chain re-triggers. Only create a new run when isolated branch/worktree is needed.
+
+## Boundaries
+
+- Never write ` .agent-toolkit/swarm/runs/<run-id>/state.json` or `herdr`/`tmux` state by hand; the CLI owns it.
+- For large outputs, keep details in the skill; do not dump full `state.json` in chat unless asked.
+
+## Delegates to
+
+| Need | Skill |
+|------|-------|
+| Push and create PR with swarm output | `github-cli-workflow` |
+| Confirm output destination | `output-handshake` |
+| Repo discovery | `assistant` |

agent_toolkit/data/skills/ops/swarm-handoff/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: swarm-handoff
+description: Create artifact/commit file handoffs for Agent Toolkit swarms with worktree-per-writer, branch,
+  and promotion integration.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - swarm
+  - handoff
+  - worktree
+  - artifact
+  - promotion
+---
+# Swarm Handoff
+
+Create correct file handoffs between swarm roles so work moves via **Git + filesystem**, not chat copy. Every writer gets an isolated worktree/branch; the filesystem `state.json` is authoritative.
+
+## When to use
+
+- The swarm needs to move work: implementer → reviewer → integrator (or any `from -> to`).
+- User asks to "hand off", "delegate", "send artifact", or "promote".
+- After `swarm-observer` diagnoses a stuck `active` handoff.
+
+## Prerequisites
+
+- Run exists: `.agent-toolkit/swarm/runs/<run-id>/state.json`.
+- Artifact file lives under the repo (prefer `artifacts/`). For `commit` type, commit/branch must exist locally.
+- Know `from` and `to` roles from the recipe (`pair`: implementer→reviewer; `team`: implementer→reviewer→integrator).
+
+## Workflow
+
+### 1. Prepare the artifact (file handoff is preferred)
+
+```bash
+# Artifact — by convention in artifacts/
+mkdir -p artifacts
+cat > artifacts/<name>.md <<'EOF'
+# Context for <to>
+- What was implemented and why
+- Files changed and how to verify
+- Risks / open questions
+EOF
+git add artifacts/<name>.md  # optional, but keeps history
+
+# Commit handoff — use when work is already committed
+git log --oneline -n 5
+git branch --show-current
+```
+
+### 2. Create the handoff (CLI owns state)
+
+```bash
+# Artifact handoff — triggers auto-provision of <to>'s worktree/tab + agent
+agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/cna-ideas.md --run-id <run-id>
+
+# Commit handoff
+agent-toolkit swarm handoff create --type commit --from reviewer --to integrator --commit <sha> --branch <branch> --run-id <run-id>
+
+# Auto behavior:
+# - If an active handoff exists where to == from_role, it auto-completes (auto:true) and trace records handoff_completed.
+# - Next role gets eager window (Waiting for handoff: <from> -> <to>) replaced by real prompt: export AGENT_TOOLKIT_SWARM_RUN_ID/RUN_DIR/REPO SWARMFORGE_ROLE + cd worktree && exec <runner> "$(cat prompt)"
+```
+
+Verify:
+
+```bash
+agent-toolkit swarm handoffs --run-id <run-id> --json | jq '.[] | {id,from,to,status,artifact,commit,auto}'
+agent-toolkit swarm status --run-id <run-id> --json | jq '.trace | last'
+# Expect: handoff create logs, worktree path, and runner exec with $(cat prompt)
+```
+
+### 3. Worktree-per-writer notes
+
+- Writer roles get an isolated Git worktree (`git worktree add <path> <branch>`). The prompt is `export AGENT_TOOLKIT_SWARM_RUN_ID/... && cd <worktree> && <runner>`.
+- Backend-neutral: `store.py` + `config.py` resolve repo root via `git rev-parse --git-common-dir` (handles `.git` file in worktrees). Do not bypass with manual `state.json` edits.
+- Shell for `pane run` / `tmux` exec uses `_user_shell()` (`$SHELL`/`/usr/bin/zsh` fallback) as `<shell> -lc`.
+
+### 4. Promote after verification
+
+```bash
+# After reviewer/integrator approves
+agent-toolkit swarm promote --run-id <run-id> --handoff-id <id>
+# or for the latest completed artifact:
+agent-toolkit swarm promote --run-id <run-id>
+
+# Then delegate push/PR
+# (use github-cli-workflow skill for branch push + draft PR)
+```
+
+### 5. Reuse pattern
+
+Same run can be reused for sequential requests — just create a new `implementer -> reviewer` artifact handoff on the same `run-id`. Eager windows stay; only the chain retriggers. Create a new run only for isolated branching.
+
+## Boundaries
+
+- Never copy artifact content via chat `echo` — use the file path in `--artifact`.
+- Never write `state.json` directly; always via `handoff create` / `task complete`.
+- For `commit` type, always pass `--commit` and `--branch`; the store validates `validate_commit_exists`.
+- Keep `artifacts/` in Git so `herdr`/`tmux` runners can read it from their worktree.
+
+## Delegates to
+
+| Need | Skill |
+|------|-------|
+| Launch the swarm before handoffs | `swarm` |
+| Diagnose stuck or orphaned handoffs | `swarm-observer` |
+| Verify code before promotion | `code-reviewer`, `security-reviewer`, `tdd-guide` |
+| Push branch and create PR | `github-cli-workflow` |
+| Generate docs from handoff output | `output-handshake`, `docs-generator` |

agent_toolkit/data/skills/ops/swarm-observer/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: swarm-observer
+description: Observe, diagnose, and recover Agent Toolkit swarm runs via status, handoffs, logs, and attach
+  with worktree and shell awareness.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.0'
+  tags:
+  - swarm
+  - observer
+  - herdr
+  - tmux
+  - handoff
+  - worktree
+---
+# Swarm Observer
+
+Monitor any `agent-toolkit swarm` run, diagnose stuck handoffs or backend drift, and recover without losing windows. Works for both **Herdr** (tabs) and **tmux** (isolated socket `agent-toolkit-swarm-<run-id>`). Integrates with swarm's eager-window model (every role starts as `Waiting for handoff: <pred> -> <role>` with `agent_waiting` trace).
+
+## When to use
+
+- A swarm was launched and the user asks "is it done?", "what's the status?", "show logs", or "attach".
+- A handoff has been `active` for >5m (`955be6f6e2c...` pattern) or `worktree_failed`.
+- Herdr shows extra workspaces (`w7-wA`) for `headless` runs — the `get_backend("headless")` fallback case.
+- User wants to reuse the same run for a new request and needs to know if windows are still alive.
+
+## Prerequisites
+
+- Run lives under `.agent-toolkit/swarm/runs/<run-id>/state.json` (filesystem is authoritative).
+- Know `run-id` (`20260807T...-xxxxxx`) from `swarm start --json` or `swarm list --json`.
+- Shell is detected (`_user_shell()`: `$SHELL` → `pwd.getpwuid` → `/usr/bin/zsh` fallback, executed as `<shell> -lc`).
+
+## Workflow
+
+### 1. List and pick the run
+
+```bash
+agent-toolkit swarm list --json | jq
+agent-toolkit swarm status --run-id <run-id>
+agent-toolkit swarm status --run-id <run-id> --json | jq '.handoffs,.worktrees,.trace'
+```
+
+### 2. Inspect handoffs and trace
+
+```bash
+agent-toolkit swarm handoffs --run-id <run-id>
+agent-toolkit swarm handoffs --run-id <run-id> --json | jq '.[] | {id,from,to,status,artifact,auto}'
+# Active that should have auto-completed:
+#   where to==from_role and handoff create --to == that role -> auto:true
+```
+
+Trace keys to watch: `agent_waiting`, `handoff_completed auto:true`, `worktree_failed`, `headless_fallback`.
+
+### 3. Tail logs and attach
+
+```bash
+agent-toolkit swarm logs --run-id <run-id> --follow
+agent-toolkit swarm logs --run-id <run-id> --role reviewer --follow
+agent-toolkit swarm attach --run-id <run-id>          # herdr: workspace focus; tmux: attach -L agent-toolkit-swarm-<run-id>
+herdr workspace list --json 2>&1 | jq '.[] | {id,name,status}'
+tmux -L agent-toolkit-swarm-<run-id> capture-pane -t <window> -p | tail -n 80
+```
+
+### 4. Diagnose
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Waiting for handoff: a -> b | role: b` stuck >5m | `active` handoff never `task complete` | `agent-toolkit swarm task next --role b --run-id <run-id>` then `task complete --task-id <id>` or `handoff create --from a --to b ...` which auto-completes `active where to==a` |
+| `worktree_failed` | `find_repo_root` failed (`git rev-parse --git-common-dir` on `.git` file) | Re-run `handoff create` — fixed via `AGENT_TOOLKIT_SWARM_RUN_ID` export + path extract |
+| Extra Herdr workspaces `w7-wA` with `headless` | `get_backend("headless")` returned `HerdrBackend` | Patch `backends/__init__.py` to return headless/noop backend; then `herdr workspace delete <id>` for orphans |
+| Shell shows `bash` while user uses `zsh` | Hardcoded `bash -lc` | Fixed via `_user_shell()` / `_shell_base()` — verify `ps -o comm= -p <pid>` shows `zsh` |
+
+### 5. Recover or reuse
+
+```bash
+# Complete stuck handoff and provision next role (worktree/tab + agent start)
+agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/fix.md --run-id <run-id>
+
+# Reuse same windows for a new request (no new run needed)
+agent-toolkit swarm handoff create --type artifact --from implementer --to reviewer --artifact artifacts/new-task.md --run-id <run-id>
+# Chain re-triggers: implementer -> reviewer -> integrator via file handoffs
+
+# Only create a new run when isolated branch is required
+agent-toolkit swarm start --recipe pair --ui herdr --runner opencode --model-profile balanced --attach "new isolated task"
+```
+
+## Boundaries
+
+- Never edit `.agent-toolkit/swarm/runs/<run-id>/state.json` by hand; use `handoff create` / `task complete` / `promote`.
+- Never create new Herdr workspaces for `headless` — fix the backend fallback instead.
+- For tmux, always use isolated socket `-L agent-toolkit-swarm-<run-id>`; never the default server.
+
+## Delegates to
+
+| Need | Skill/Command |
+|------|---------------|
+| Show failure snippet before fixing | `swarm-handoff` |
+| Recreate worktree | `agent-toolkit swarm handoff create` (auto-provisions) |
+| Review code produced by swarm | `code-reviewer`, `security-reviewer` |
+| Create PR after promotion | `github-cli-workflow` |

agent_toolkit/data/skills/ops/triage/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: triage
+description: Workstation health triage — validate tooling, directory layout, and run doctor with remediation
+  suggestions.
+origin:
+  type: first-party
+metadata:
+  author: ulises-jeremias
+  version: '1.1'
+---
+# Workstation Triage ()
+
+Use when the user reports workstation issues, install problems, tool failures, or needs a health check before starting work.
+
+## Prerequisites
+
+Run this skill on the **local workstation** where the user is experiencing issues. Do not run it on a remote server unless the user confirms the remote has the setup.
+
+Verify `doctor` is installed:
+
+```bash
+command -v doctor
+```
+
+If missing, install via chezmoi (`chezmoi apply`) or direct installation.
+
+## Output modes
+
+Use the mode that matches the user's need:
+
+| Mode | Command | When to use |
+|------|---------|-------------|
+| **Colored** (default) | `doctor` | Interactive terminal session — human-readable colored output |
+| **Markdown** | `doctor --issue` | GitHub issues, Slack threads, tickets — paste-ready block |
+| **JSON** | `doctor --json` | Automation scripts, CI parsing — single-line machine-readable |
+
+### Markdown output (`--issue`)
+
+Always use `doctor --issue` (not the default) when the output will be shared in:
+- GitHub issues or PR comments
+- Slack messages
+- Support tickets
+- Any written async communication
+
+### JSON output (`--json`)
+
+Use `doctor --json` only when:
+- A script or automation pipeline needs to parse the result
+- You need a single-line summary for programmatic handling
+- Requires `python3` in PATH
+
+## Profile and check groups
+
+The doctor's behavior is controlled by `~/.config//profile.env`. Checks can be selectively enabled/disabled via environment variables:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `DOTS_WORKSTATION_DOCTOR_GROUP_CORE` | `true` | Core tools: `git`, `curl`, `wget`, `jq`, `rg`, `fd`, `zsh`, `gh` |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_NODE` | `true` | Node.js: `fnm`, `node` |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_PYTHON` | `true` | Python: `uv`, `python3` |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_DOCKER` | `true` | Docker: `docker` |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_AI` | `true` | LLM API key presence flags (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) |
+| `DOTS_WORKSTATION_DOCTOR_GROUP_SKILLS_PRODUCTIVITY` | `false` | Optional productivity tool group |
+| `DOTS_WORKSTATION_DOCTOR_SKILL_JIRA` | `false` | JIRA skill integration check |
+| `DOTS_WORKSTATION_DOCTOR_SKILL_CONFLUENCE` | `false` | Confluence skill integration check |
+
+> **Note:** Profile variables are read from `~/.config//profile.env`. If the file is missing, defaults apply.
+
+## Directory checks
+
+The doctor validates the presence and structure of:
+- `~/.local/share//prompts`
+- `~/.local/share//skills`
+- `~/.local/share//templates`
+- `~/.local/share//mcp/github`
+- `~/.local/share//mcp/clickup`
+- `~/.local/share//mcp/notion`
+- `~/.local/share//mcp/slack`
+
+## Remediation guidance
+
+Propose fixes in order of lowest risk first:
+
+1. **Missing directories** → run `chezmoi apply` to bootstrap the full installation
+2. **Missing commands** → use the respective skill's installation instructions (e.g., `uv` via `curl -LsSf https://astral.sh/uv/install.sh`)
+3. **Auth failures** → run `gh auth login`, `clickup auth login`, or `glab auth login` as appropriate
+4. **Profile/group mismatches** → edit `~/.config//profile.env` and run `chezmoi apply`
+5. **API key missing** → guide user to set the appropriate env var in their shell profile
+
+## Common issues
+
+### doctor exits 1 (NON-COMPLIANT)
+
+Run with `--issue` to get the full markdown checklist. Address failures in this order:
+1. Install any missing core commands
+2. Run `chezmoi apply` to restore directory structure
+3. Re-authenticate CLIs (`gh`, `clickup`, `glab`)
+4. Verify `~/.config//profile.env` matches the intended profile
+
+### doctor --json requires python3
+
+If `python3` is not available, fall back to `doctor --issue` and parse the markdown manually.
+
+### doctor: Missing dependency: easyoptions.sh
+
+The `easyoptions.sh` library is missing from `~/.local/lib/`. Re-run `chezmoi apply` to restore it, or check if the installation is incomplete.
+
+## Skill boundaries
+
+- This skill **does not fix issues automatically** — it diagnoses and proposes remediation steps.
+- This skill **does not modify** `profile.env` or authentication state — user must approve and execute fixes.
+- For **chezmoi-managed configuration issues**, pair with the **`dev-companion`** or direct chezmoi guidance.
+- For **CI/build failures** on a project repo, use **`build-error-resolver`** instead of this skill.
+
+## References
+
+- `doctor --help` — full option list
+- `~/.config//profile.env` — check group configuration
+- `~/.local/lib//easy-options/easyoptions.sh` — dependency library