@covibes/zeroshot 5.2.1 → 5.4.0

package/README.md

@@ -1,187 +1,229 @@
 # zeroshot CLI
 
+> **🎉 New Release:** Now supports **Codex** and **Gemini** CLI in addition to Claude! Use any provider or mix them in multi-agent workflows. See [Providers](#providers) for details.
+
+<!-- install-placeholder -->
+<p align="center">
+  <code>npm install -g @covibes/zeroshot</code>
+</p>
+
+<p align="center">
+  <img src="./docs/assets/zeroshot-demo.gif" alt="Demo" width="700">
+  <br>
+  <em>Demo (100x speed, 90-minute run, 5 iterations to approval)</em>
+</p>
+
 [![CI](https://github.com/covibes/zeroshot/actions/workflows/ci.yml/badge.svg)](https://github.com/covibes/zeroshot/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/@covibes/zeroshot.svg)](https://www.npmjs.com/package/@covibes/zeroshot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org/)
-[![Platform: Linux | macOS](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-blue.svg)]()
+![Platform: Linux | macOS](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-blue.svg)
+
+<!-- discord-placeholder -->
 
-> **2024** was the year of LLMs. **2025** was the year of agents. **2026** is the year of agent clusters.
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/PdZ3UEXB)
 
-**Autonomous engineering teams for Claude Code.**
+Zeroshot is an open-source AI coding agent orchestration CLI that runs multi-agent workflows to autonomously implement, review, test, and verify code changes.
 
-## Install
+It runs a **planner**, an **implementer**, and independent **validators** in isolated environments, looping until changes are **verified** or **rejected** with actionable, reproducible failures.
 
-**Platforms**: Linux, macOS
+Built for tasks where correctness matters more than speed.
+
+## How It Works
+
+- Plan: translate a task into concrete acceptance criteria
+- Implement: make changes in an isolated workspace (local, worktree, or Docker)
+- Validate: run automated checks with independent validators
+- Iterate: repeat until verified, or return actionable failures
+- Resume: crash-safe state persisted for recovery
+
+## Quick Start
 
 ```bash
-npm install -g @covibes/zeroshot
+zeroshot run 123                    # GitHub issue number
+zeroshot run feature.md             # Markdown file
+zeroshot run "Add dark mode"        # Inline text
 ```
 
-**Requires**: Node 18+, [Claude Code CLI](https://claude.com/product/claude-code), [GitHub CLI](https://cli.github.com/)
+Or describe a complex task inline:
 
 ```bash
-npm i -g @anthropic-ai/claude-code && claude auth login
-gh auth login
+zeroshot run "Add optimistic locking with automatic retry: when updating a user,
+retry with exponential backoff up to 3 times, merge non-conflicting field changes,
+and surface conflicts with details. Handle the ABA problem where version goes A->B->A."
 ```
 
----
+## Why Not Just Use a Single AI Agent?
+
+| Approach                   | Writes Code | Runs Tests | Blind Validation | Iterates Until Verified |
+| -------------------------- | ----------- | ---------- | ---------------- | ----------------------- |
+| Chat-based assistant       | ✅          | ⚠️         | ❌               | ❌                      |
+| Single coding agent        | ✅          | ⚠️         | ❌               | ⚠️                      |
+| **Zeroshot (multi-agent)** | ✅          | ✅         | ✅               | ✅                      |
 
-You know the problem. Your AI agent:
+## Use Cases
 
-- Says "tests pass" (never ran them)
-- Says "done!" (nothing works)
-- Implements 60% of what you asked
-- Ignores your coding guidelines
-- Introduces antipatterns like a junior dev
-- Gets sloppy on long tasks
+- Autonomous AI code refactoring
+- AI-powered pull request automation
+- Automated bug fixing with validation
+- Multi-agent code generation for software engineering
+- Agentic coding workflows with blind validation
 
-**AI is extremely capable. But not when one agent does everything in one session.**
+## Who Is This For?
 
-Context degrades. Attention drifts. Shortcuts get taken.
+- Senior engineers who care about correctness and reproducibility
+- Teams automating PR workflows and code review gates
+- Infra/platform teams standardizing agentic workflows
+- Open-source maintainers working through issue backlogs
+- AI power users who want verification, not vibes
 
-Zeroshot fixes this with **multiple isolated agents** that check each other's work. The validator didn't write the code, so it can't lie about tests. Fail? Fix and retry until it works.
+## Install and Requirements
+
+**Platforms**: Linux, macOS (Windows WSL not yet supported)
 
 ```bash
-zeroshot 123
+npm install -g @covibes/zeroshot
 ```
 
-Point at a GitHub issue, walk away, come back to working code.
-
-### Demo
+**Requires**: Node 18+, at least one provider CLI (Claude Code, Codex, Gemini, Opencode).
 
 ```bash
-zeroshot "Add optimistic locking with automatic retry: when updating a user,
-detect if another request modified it first using version numbers,
-automatically retry with exponential backoff up to 3 times,
-merge non-conflicting field changes, surface true conflicts to the caller
-with details of what conflicted. Handle the ABA problem where version goes A->B->A."
+# Install one or more providers
+npm i -g @anthropic-ai/claude-code
+npm i -g @openai/codex
+npm i -g @google/gemini-cli
+# Opencode: see https://opencode.ai
+
+# Authenticate with the provider CLI
+claude login        # Claude
+codex login         # Codex
+gemini auth login   # Gemini
+opencode auth login # Opencode
+
+# GitHub auth (for issue numbers)
+gh auth login
 ```
 
-<p align="center">
-  <img src="./docs/assets/zeroshot-demo.gif" alt="Demo" width="700">
-  <br>
-  <em>Sped up 100x — 90 minutes, 5 iterations until validators approved</em>
-</p>
+## Providers
 
-**The full fix cycle.** Initial implementation passed basic tests but validators caught edge cases: race conditions in concurrent updates, ABA problem not fully handled, retry backoff timing issues. Each rejection triggered fixes until all 48 tests passed with 91%+ coverage.
+Zeroshot shells out to provider CLIs. Pick a default and override per run:
 
-A single agent would say "done!" after the first implementation. Here, the adversarial tester actually *runs* concurrent requests, times the retry backoff, and verifies conflict detection works under load.
+```bash
+zeroshot providers
+zeroshot providers set-default codex
+zeroshot run 123 --provider gemini
+```
 
-**This is what production-grade looks like.** Not "tests pass" — validators reject until it actually works. 5 iterations, each one fixing real bugs the previous attempt missed.
+See `docs/providers.md` for setup, model levels, and Docker mounts.
 
----
+## Why Multiple Agents?
 
-## When to Use Zeroshot
+Single-agent sessions degrade. Context gets buried under thousands of tokens. The model optimizes for "done" over "correct."
 
-**Zeroshot requires well-defined tasks with clear acceptance criteria.**
+Zeroshot fixes this with isolated agents that check each other's work. Validators can't lie about code they didn't write. Fail the check? Fix and retry until it actually works.
 
-| Scenario | Use? | Why |
-|----------|:----:|-----|
-| Add rate limiting (sliding window, per-IP, 429) | ✅ | Clear requirements |
-| Refactor auth to JWT | ✅ | Defined end state |
-| Fix login bug | ✅ | Success is measurable |
-| Fix 2410 lint violations | ✅ | Clear completion criteria |
-| Make the app faster | ❌ | Needs exploration first |
-| Improve the codebase | ❌ | No acceptance criteria |
-| Figure out flaky tests | ❌ | Exploratory |
+## What Makes It Different
 
-**Known unknowns** (implementation details unclear) → Zeroshot handles this. The planner figures it out.
+- **Blind validation** - Validators never see the worker's context or code history
+- **Repeatable workflows** - Task complexity determines agent count and model selection
+- **Accept/reject loop** - Rejections include actionable findings, not vague complaints
+- **Crash recovery** - All state persisted to SQLite; resume anytime
+- **Isolation modes** - None, git worktree, or Docker container
+- **Cost control** - Model ceilings prevent runaway API spend
 
-**Unknown unknowns** (don't know what you'll discover) → Use single-agent Claude Code for exploration first, then come back with a well-defined task.
-
-**Long-running batch tasks** → Zeroshot excels here. Run overnight with `-d` (daemon mode):
-- "Fix all 2410 semantic linting violations"
-- "Add TypeScript types to all 47 untyped files"
-- "Migrate all API calls from v1 to v2"
+## When to Use Zeroshot
 
-Crash recovery (`zeroshot resume`) means multi-hour tasks survive interruptions.
+Zeroshot performs best when tasks have clear acceptance criteria.
 
-**Rule of thumb:** If you can't describe what "done" looks like, zeroshot's validators can't verify it.
+| Scenario                                        | Use | Why                       |
+| ----------------------------------------------- | --- | ------------------------- |
+| Add rate limiting (sliding window, per-IP, 429) | Yes | Clear requirements        |
+| Refactor auth to JWT                            | Yes | Defined end state         |
+| Fix login bug                                   | Yes | Success is measurable     |
+| Fix 2410 lint violations                        | Yes | Clear completion criteria |
+| Make the app faster                             | No  | Needs exploration first   |
+| Improve the codebase                            | No  | No acceptance criteria    |
+| Figure out flaky tests                          | No  | Exploratory               |
 
----
+Rule of thumb: if you cannot describe what "done" means, validators cannot verify it.
 
-## Commands
+## Command Overview
 
 ```bash
-zeroshot run 123               # Run on GitHub issue
-zeroshot run "Add dark mode"   # Run from description
+# Run
+zeroshot run 123                      # GitHub issue
+zeroshot run feature.md               # Markdown file
+zeroshot run "Add dark mode"          # Inline text
 
-# Automation levels (cascading: --ship → --pr → --worktree)
-zeroshot run 123 --docker      # Docker isolation (full container)
-zeroshot run 123 --worktree    # Git worktree isolation (lightweight)
-zeroshot run 123 --pr          # Worktree + PR (human reviews)
-zeroshot run 123 --ship        # Worktree + PR + auto-merge (full automation)
+# Isolation
+zeroshot run 123 --worktree       # git worktree
+zeroshot run 123 --docker         # container
+
+# Automation (--ship implies --pr implies --worktree)
+zeroshot run 123 --pr             # worktree + create PR
+zeroshot run 123 --ship           # PR + auto-merge on approval
 
 # Background mode
-zeroshot run 123 -d            # Detached/daemon
-zeroshot run 123 --ship -d     # Full automation, background
+zeroshot run 123 -d
+zeroshot run 123 --ship -d
 
 # Control
-zeroshot list                  # See all running (--json for scripting)
-zeroshot status <id>           # Cluster status (--json for scripting)
-zeroshot logs <id> -f          # Follow output
-zeroshot resume <id>           # Continue after crash
-zeroshot kill <id>             # Stop
-zeroshot watch                 # TUI dashboard
+zeroshot list
+zeroshot status <id>
+zeroshot logs <id> -f
+zeroshot resume <id>
+zeroshot stop <id>
+zeroshot kill <id>
+zeroshot watch
+
+# Providers
+zeroshot providers
+zeroshot providers set-default codex
 
 # Agent library
-zeroshot agents list           # View available agents
-zeroshot agents show <name>    # Agent details
+zeroshot agents list
+zeroshot agents show <name>
 
 # Maintenance
-zeroshot clean                 # Remove old records
-zeroshot purge                 # NUCLEAR: kill all + delete all
+zeroshot clean
+zeroshot purge
 ```
 
----
-
-<details>
-<summary><strong>FAQ</strong></summary>
-
-**Q: Why Claude-only (for now)?**
-
-Claude Code is the most capable agentic coding tool available. We wrap it directly - same tools, same reliability, no custom implementations to break.
+## Multi-Platform Issue Support
 
-Multi-model support (Codex CLI, Gemini CLI) is planned - see [#19](https://github.com/covibes/zeroshot/issues/19).
+Zeroshot works with **GitHub, GitLab, Jira, and Azure DevOps**. Just paste the issue URL or key.
+When working in a git repository, zeroshot automatically detects the issue provider from your git remote URL. No configuration needed!
 
-**Q: Why do single-agent coding sessions get sloppy?**
-
-Three failure modes compound when one agent does everything in one session:
-
-- **Context Dilution**: Your initial guidelines compete with thousands of tokens of code, errors, and edits. Instructions from 50 messages ago get buried.
-- **Success Bias**: LLMs optimize for "Task Complete" - even if that means skipping steps to get there.
-- **Error Snowball**: When fixing mistakes repeatedly, the context fills with broken code. The model starts copying its own bad patterns.
-
-Zeroshot fixes this with **isolated agents** where validators check work they didn't write - no self-grading, no shortcuts.
-
-**Q: Can I customize the team?**
-
-Yes, see CLAUDE.md. But most people never need to.
-
-**Q: Why is it called "zeroshot"?**
-
-In machine learning, "zero-shot" means solving tasks the model has never seen before - using only the task description, no prior examples needed.
-
-Same idea here: give zeroshot a well-defined task, get back a result. No examples. No iterative feedback. No hand-holding.
+```bash
+# GitHub
+zeroshot run 123
+zeroshot run https://github.com/org/repo/issues/123
 
-The multi-agent architecture handles planning, implementation, and validation internally. You provide a clear problem statement. Zeroshot handles the rest.
+# GitLab (cloud and self-hosted)
+zeroshot run https://gitlab.com/org/repo/-/issues/456
+zeroshot run https://gitlab.mycompany.com/org/repo/-/issues/789
 
-</details>
+# Jira
+zeroshot run PROJ-789
+zeroshot run https://company.atlassian.net/browse/PROJ-789
 
----
+# Azure DevOps
+zeroshot run https://dev.azure.com/org/project/_workitems/edit/999
+```
 
-## How It Works
+**Requires**: CLI tools ([`gh`](https://cli.github.com/), [`glab`](https://gitlab.com/gitlab-org/cli), [`jira`](https://github.com/go-jira/jira), or [`az`](https://docs.microsoft.com/cli/azure/)) for the platform you use. See [issue-providers README](src/issue-providers/README.md) for setup and self-hosted instances.
 
-Zeroshot is a **multi-agent coordination framework** with smart defaults.
+**Important for `--pr` mode**: Run zeroshot from the target repository directory. PRs are created on the git remote of your current directory. If you run from a different repo, zeroshot will warn you and skip the "Closes #X" reference (the PR is still created, but won't auto-close the issue).
 
-### Zero Config
+## Architecture
 
-```bash
-zeroshot 123  # Analyzes task → picks team → done
-```
+Zeroshot is a message-driven coordination layer with smart defaults.
 
-The conductor classifies your task (complexity × type) and picks the right workflow:
+- The conductor classifies tasks by complexity and type.
+- A workflow template selects agents and validators.
+- Agents publish results to a SQLite ledger.
+- Validators approve or reject with specific findings.
+- Rejections route back to the worker for fixes.
 
 ```
                                 ┌─────────────────┐
@@ -200,7 +242,7 @@ The conductor classifies your task (complexity × type) and picks the right work
      ┌───────────┐                ┌───────────┐                ┌───────────┐
      │  TRIVIAL  │                │  SIMPLE   │                │ STANDARD+ │
      │  1 agent  │──────────▶     │  worker   │                │ planner   │
-     │  (haiku)  │  COMPLETE      │ + 1 valid.│                │ + worker  │
+     │ (level1)  │  COMPLETE      │ + 1 valid.│                │ + worker  │
      │ no valid. │                └─────┬─────┘                │ + 3-5 val.│
      └───────────┘                      │                      └─────┬─────┘
                                         ▼                            │
@@ -231,35 +273,36 @@ The conductor classifies your task (complexity × type) and picks the right work
      └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
+### Complexity Model
+
 | Task                   | Complexity | Agents | Validators                                        |
 | ---------------------- | ---------- | ------ | ------------------------------------------------- |
 | Fix typo in README     | TRIVIAL    | 1      | None                                              |
-| Add dark mode toggle   | SIMPLE     | 2      | generic validator                                 |
-| Refactor auth system   | STANDARD   | 4      | requirements, code                                |
-| Implement payment flow | CRITICAL   | 7      | requirements, code, security, tester, adversarial |
+| Add dark mode toggle   | SIMPLE     | 2      | Generic validator                                 |
+| Refactor auth system   | STANDARD   | 4      | Requirements, code                                |
+| Implement payment flow | CRITICAL   | 7      | Requirements, code, security, tester, adversarial |
 
 ### Model Selection by Complexity
 
 | Complexity | Planner | Worker | Validators |
 | ---------- | ------- | ------ | ---------- |
-| TRIVIAL    | -       | haiku  | 0          |
-| SIMPLE     | -       | sonnet | 1 (sonnet) |
-| STANDARD   | sonnet  | sonnet | 2 (sonnet) |
-| CRITICAL   | opus    | sonnet | 5 (sonnet) |
-
-Set model ceiling: `zeroshot settings set maxModel sonnet` (prevents opus)
+| TRIVIAL    | -       | level1 | -          |
+| SIMPLE     | -       | level2 | 1 (level2) |
+| STANDARD   | level2  | level2 | 2 (level2) |
+| CRITICAL   | level3  | level2 | 5 (level2) |
 
----
+Levels map to provider-specific models. Configure with `zeroshot providers setup <provider>` or
+`settings.providerSettings`. (Legacy `maxModel` applies to Claude only.)
 
 <details>
 <summary><strong>Custom Workflows (Framework Mode)</strong></summary>
 
-Zeroshot is **message-driven** - define any agent topology:
+Zeroshot is message-driven, so you can define any agent topology.
 
-- **Expert panels**: Parallel specialists → aggregator → decision
-- **Staged gates**: Sequential validators, each with veto power
-- **Hierarchical**: Supervisor dynamically spawns workers
-- **Dynamic**: Conductor adds agents mid-execution
+- Expert panels: parallel specialists -> aggregator -> decision
+- Staged gates: sequential validators, each with veto power
+- Hierarchical: supervisor dynamically spawns workers
+- Dynamic: conductor adds agents mid-execution
 
 **Coordination primitives:**
 
@@ -268,20 +311,14 @@ Zeroshot is **message-driven** - define any agent topology:
 - Ledger (SQLite, crash recovery)
 - Dynamic spawning (CLUSTER_OPERATIONS)
 
-#### Creating Custom Clusters with Claude Code
+#### Creating Custom Clusters with a Provider CLI
 
-**The easiest way to create a custom cluster: just ask Claude Code.**
+Start your provider CLI and describe your cluster:
 
-```bash
-# In your zeroshot repo
-claude
-```
-
-**Example prompt:**
 ```
 Create a zeroshot cluster config for security-critical features:
 
-1. Implementation agent (sonnet) implements the feature
+1. Implementation agent (level2) implements the feature
 2. FOUR parallel validators:
    - Security validator: OWASP checks, SQL injection, XSS, CSRF
    - Performance validator: No N+1 queries, proper indexing
@@ -290,76 +327,64 @@ Create a zeroshot cluster config for security-critical features:
 
 3. ALL validators must approve before merge
 4. If ANY validator rejects, implementation agent fixes and resubmits
-5. Use opus for security validator (highest stakes)
+5. Use level3 for security validator (highest stakes)
 
 Look at cluster-templates/base-templates/full-workflow.json
 and create a similar cluster. Save to cluster-templates/security-review.json
 ```
 
-Claude Code will read existing templates, create valid JSON config, and iterate until it works.
-
-**Built-in validation catches failures before running:**
-- Never start (no bootstrap trigger)
-- Never complete (no path to completion)
-- Loop infinitely (circular dependencies)
-- Deadlock (impossible consensus)
-- Type mismatches (boolean → string in JSON)
+Built-in validation checks for missing triggers, deadlocks, and invalid type wiring before running.
 
-See [CLAUDE.md](./CLAUDE.md) for cluster config schema and examples.
+See [CLAUDE.md](./CLAUDE.md) for the cluster schema and examples.
 
 </details>
 
----
-
 ## Crash Recovery
 
-Everything saves to SQLite. If your 2-hour run crashes at 1:59:
+All state is persisted in the SQLite ledger. You can resume at any time:
 
 ```bash
 zeroshot resume cluster-bold-panther
-# Continues from exact point
 ```
 
----
-
 ## Isolation Modes
 
 ### Git Worktree (Default for --pr/--ship)
 
 ```bash
-zeroshot 123 --worktree
+zeroshot run 123 --worktree
 ```
 
-Lightweight isolation using git worktree. Creates a separate working directory with its own branch. Fast (<1s setup), no Docker required. Auto-enabled with `--pr` and `--ship`.
+Lightweight isolation using git worktree. Creates a separate working directory with its own branch. Auto-enabled with `--pr` and `--ship`.
 
 ### Docker Container
 
 ```bash
-zeroshot 123 --docker
+zeroshot run 123 --docker
 ```
 
-Full isolation in a fresh container. Your workspace stays untouched. Good for risky experiments or parallel agents.
+Full isolation in a fresh container. Your workspace stays untouched. Useful for risky experiments or parallel runs.
 
 ### When to Use Which
 
-| Scenario | Recommended |
-| -------- | ----------- |
-| Quick task, review changes yourself | No isolation (default) |
-| PR workflow, code review | `--worktree` or `--pr` |
-| Risky experiment, might break things | `--docker` |
-| Running multiple tasks in parallel | `--docker` |
-| Full automation, no review needed | `--ship` |
+| Scenario                             | Recommended            |
+| ------------------------------------ | ---------------------- |
+| Quick task, review changes yourself  | No isolation (default) |
+| PR workflow, code review             | `--worktree` or `--pr` |
+| Risky experiment, might break things | `--docker`             |
+| Running multiple tasks in parallel   | `--docker`             |
+| Full automation, no review needed    | `--ship`               |
 
-**Default mode:** Agents are instructed to only modify files (no git commit/push). You review and commit yourself.
+**Default behavior:** Agents modify files only; they do not commit or push unless using an isolation mode that explicitly allows it.
 
 <details>
 <summary><strong>Docker Credential Mounts</strong></summary>
 
-When using `--docker`, zeroshot mounts credential directories so Claude can access tools like AWS, Azure, kubectl.
+When using `--docker`, zeroshot mounts credential directories so agents can access provider CLIs and tools like AWS, Azure, and kubectl.
 
 **Default mounts**: `gh`, `git`, `ssh` (GitHub CLI, git config, SSH keys)
 
-**Available presets**: `gh`, `git`, `ssh`, `aws`, `azure`, `kube`, `terraform`, `gcloud`
+**Available presets**: `gh`, `git`, `ssh`, `aws`, `azure`, `kube`, `terraform`, `gcloud`, `claude`, `codex`, `gemini`
 
 ```bash
 # Configure via settings (persistent)
@@ -371,6 +396,10 @@ zeroshot settings get dockerMounts
 # Per-run override
 zeroshot run 123 --docker --mount ~/.aws:/root/.aws:ro
 
+# Provider credentials
+zeroshot run 123 --docker --mount ~/.config/codex:/home/node/.config/codex:ro
+zeroshot run 123 --docker --mount ~/.config/gemini:/home/node/.config/gemini:ro
+
 # Disable all mounts
 zeroshot run 123 --docker --no-mounts
 
@@ -378,7 +407,10 @@ zeroshot run 123 --docker --no-mounts
 ZEROSHOT_DOCKER_MOUNTS='["aws","azure"]' zeroshot run 123 --docker
 ```
 
+See `docs/providers.md` for provider CLI setup and mount details.
+
 **Custom mounts** (mix presets with explicit paths):
+
 ```bash
 zeroshot settings set dockerMounts '[
   "gh",
@@ -388,57 +420,56 @@ zeroshot settings set dockerMounts '[
 ```
 
 **Container home**: Presets use `$HOME` placeholder. Default: `/root`. Override with:
+
 ```bash
 zeroshot settings set dockerContainerHome '/home/node'
 # Or per-run:
 zeroshot run 123 --docker --container-home /home/node
 ```
 
-**Env var passthrough**: Presets auto-pass related env vars (e.g., `aws` → `AWS_REGION`, `AWS_PROFILE`). Add custom:
+**Env var passthrough**: Presets auto-pass related env vars (for example, `aws` -> `AWS_REGION`, `AWS_PROFILE`). Add custom:
+
 ```bash
 zeroshot settings set dockerEnvPassthrough '["MY_API_KEY", "TF_VAR_*"]'
 ```
 
 </details>
 
----
-
-## More
+## Resources
 
-- **Debug**: `sqlite3 ~/.zeroshot/cluster-abc.db "SELECT * FROM messages;"`
-- **Export**: `zeroshot export <id> --format markdown`
-- **Architecture**: See [CLAUDE.md](./CLAUDE.md)
-
----
+- [CLAUDE.md](./CLAUDE.md) - Architecture, cluster config schema, agent primitives
+- `docs/providers.md` - Provider setup, model levels, and Docker mounts
+- [Discord](https://discord.gg/PdZ3UEXB) - Support and community
+- `zeroshot export <id>` - Export conversation to markdown
+- `sqlite3 ~/.zeroshot/*.db` - Direct ledger access for debugging
 
 <details>
 <summary><strong>Troubleshooting</strong></summary>
 
-| Issue                         | Fix                                                                  |
-| ----------------------------- | -------------------------------------------------------------------- |
-| `claude: command not found`   | `npm i -g @anthropic-ai/claude-code && claude auth login`            |
-| `gh: command not found`       | [Install GitHub CLI](https://cli.github.com/)                        |
-| `--docker` fails              | Docker must be running: `docker ps` to verify                        |
-| Cluster stuck                 | `zeroshot resume <id>` to continue with guidance                     |
-| Agent keeps failing           | Check `zeroshot logs <id>` for actual error                          |
-| `zeroshot: command not found` | `npm install -g @covibes/zeroshot`                                   |
+| Issue                         | Fix                                                                                       |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| `claude: command not found`   | `npm i -g @anthropic-ai/claude-code && claude auth login`                                 |
+| `codex: command not found`    | `npm i -g @openai/codex && codex login`                                                   |
+| `gemini: command not found`   | `npm i -g @google/gemini-cli && gemini auth login`                                        |
+| `gh: command not found`       | [Install GitHub CLI](https://cli.github.com/)                                             |
+| `--docker` fails              | Docker must be running: `docker ps` to verify                                             |
+| Cluster stuck                 | `zeroshot resume <id>` to continue                                                        |
+| Agent keeps failing           | Check `zeroshot logs <id>` for actual error                                               |
+| `zeroshot: command not found` | `npm install -g @covibes/zeroshot`                                                        |
+| Agents misbehave              | `/analyze-cluster-postmortem <id>` in Claude Code (creates issue if fix is generalizable) |
 
 </details>
 
----
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
-Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before participating.
 
 For security issues, see [SECURITY.md](SECURITY.md).
 
 ---
 
-MIT — [Covibes](https://github.com/covibes)
+MIT - [Covibes](https://github.com/covibes)
 
 Built on [Claude Code](https://claude.com/product/claude-code) by Anthropic.
-
-