@covibes/zeroshot 3.0.0 → 4.0.0

package/CHANGELOG.md

@@ -1,3 +1,79 @@
+# [4.0.0](https://github.com/covibes/zeroshot/compare/v3.1.0...v4.0.0) (2026-01-04)
+
+
+### Bug Fixes
+
+* adversarial tester condition and README accuracy ([c12109b](https://github.com/covibes/zeroshot/commit/c12109b5ee574301e472bd09ec7495f3a578dc36))
+* **ci:** use correct agent state in status-footer test ([c6f54a8](https://github.com/covibes/zeroshot/commit/c6f54a89d91a621a8d92c1a21dfa796743e38cd2))
+* **cli:** ensure PROCESS_SPAWNED sets EXECUTING_TASK state ([4c3cc9c](https://github.com/covibes/zeroshot/commit/4c3cc9c82b67513cf6ab5e5eca9de1b6d259a9d1))
+* **ledger:** prevent write-after-close race condition ([6b64fcf](https://github.com/covibes/zeroshot/commit/6b64fcfa37a4396591599774c788a022cdbfb1e9))
+* **release:** allow semantic-release to query remote tags ([0be475b](https://github.com/covibes/zeroshot/commit/0be475b264d400c6b504306e7c535b2736dfaaa1))
+* **release:** explicitly fetch tags for semantic-release ([cecf735](https://github.com/covibes/zeroshot/commit/cecf7358d9091992d4c7a1191f874588ba7a592d))
+* **tests:** ensure first-run tests are isolated from module cache ([e55dbe7](https://github.com/covibes/zeroshot/commit/e55dbe7255bab7cf3ec4ddefcc897ec71296a74a))
+* **tests:** move env var and module setup to before() hook ([cf787ff](https://github.com/covibes/zeroshot/commit/cf787ff7453d1a65cbaaf98655606ccb38dea967))
+* **tests:** use validateConfig for modelRules catch-all validation ([4092d78](https://github.com/covibes/zeroshot/commit/4092d78be5739f6a3ca4bc80b3dc25ea7c41f74d))
+
+
+### chore
+
+* bump version to 4.0.0 ([95844e8](https://github.com/covibes/zeroshot/commit/95844e8ffeee4d24dde56b084053d0cdcd30d3e9))
+
+
+### Features
+
+* **context:** enforce maximum informativeness, minimum verbosity ([f99a7b7](https://github.com/covibes/zeroshot/commit/f99a7b738214863744119a9b96a50590034299aa))
+* **prompts:** add universal language/task support with LLM antipattern detection ([906102b](https://github.com/covibes/zeroshot/commit/906102b654914ccd73ebb8abaa121304ee4f347e))
+
+
+### Performance Improvements
+
+* **ci:** reduce matrix from 6 jobs to 1 (save ~90% minutes) ([cad652d](https://github.com/covibes/zeroshot/commit/cad652d22fdc24cf10efabf04e13902529c05b98))
+* **validators:** remove relevance/notes fields to save tokens ([b775e5a](https://github.com/covibes/zeroshot/commit/b775e5a028475f2f11d3b87ec0202c4398100c1d))
+
+
+### BREAKING CHANGES
+
+* CREW_* env vars renamed to ZEROSHOT_*
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+* **prompts:** Validator prompts no longer include language-specific examples
+
+# [3.1.0](https://github.com/covibes/zeroshot/compare/v3.0.0...v3.1.0) (2026-01-03)
+
+
+### Bug Fixes
+
+* **attach:** detect cluster IDs without prefix by checking clusters.json ([a3f3b3a](https://github.com/covibes/zeroshot/commit/a3f3b3a1c3de47333297b98327f36aefb36cb958))
+* **cli:** use canonical AGENT_STATE constants for status footer ([ac53f83](https://github.com/covibes/zeroshot/commit/ac53f83b0af9a7f2de8264ca791457e4e0afca9a))
+* **footer:** show agents during evaluating_logic, building_context, executing_task ([f3c3484](https://github.com/covibes/zeroshot/commit/f3c348400d4b2e960410121cef0614dc583e7528))
+* handle Claude CLI lock contention in parallel validators ([b88d502](https://github.com/covibes/zeroshot/commit/b88d502699c8c0e628310a9b998c4a1f4cb26d1a))
+* **orchestrator:** add missing close() method for test cleanup ([a642886](https://github.com/covibes/zeroshot/commit/a6428867647de4d5b28c61163be87d711e001c7c))
+* **output:** broadcast text output, not just JSON ([adc8556](https://github.com/covibes/zeroshot/commit/adc8556a47e3d02ed7189d8290e9cf81a07c909c))
+* **output:** change from MINIMAL to INFORMATIVE output style ([3b87466](https://github.com/covibes/zeroshot/commit/3b87466eb0012f089edac2fb66a4d118a39e92e0))
+* **planner:** explicitly forbid Deferred and Why defer patterns ([0504b0a](https://github.com/covibes/zeroshot/commit/0504b0a5e4e4cd0c902989e29a3759fbc46aa534))
+* **planner:** forbid scope reduction in planner prompt ([a9dbfb2](https://github.com/covibes/zeroshot/commit/a9dbfb2bef67a14289af91b0cea77880fe3eff3f))
+* **planner:** prevent silent phase omission in scope reduction checks ([7e99787](https://github.com/covibes/zeroshot/commit/7e99787593cd970b45901f7cf1bf641bf4e5f772))
+* **status-footer:** cleanup footer on stop regardless of hidden state ([52fe9e9](https://github.com/covibes/zeroshot/commit/52fe9e9efeae5c768291a9a0810399bfdae03934))
+* **templates:** hardcode completion-detector model to haiku ([78b917e](https://github.com/covibes/zeroshot/commit/78b917e1c97697bf64d7a0897c2b68d8bb0bbaa3))
+* **tests:** set ZEROSHOT_WORKTREE env in git-safety-hook tests ([7399cfc](https://github.com/covibes/zeroshot/commit/7399cfca1d42f748314db355eb247e426fad97a2))
+* **tests:** skip isolation tests when Docker image unavailable ([142f43c](https://github.com/covibes/zeroshot/commit/142f43c6af6e209a95b286556d13bb594985e850))
+* **tests:** update settings test for maxModel rename and fix git hook case sensitivity ([6cbb654](https://github.com/covibes/zeroshot/commit/6cbb654fd2ef15fde9f1454d63cd6aae6807404b))
+* **tests:** update tests for maxModel cost ceiling rename ([45b4ac8](https://github.com/covibes/zeroshot/commit/45b4ac809c480205345be96249608ea2b284f50e))
+* **update-checker:** check npm write permissions before auto-update ([dd9efa8](https://github.com/covibes/zeroshot/commit/dd9efa83edeef812f6d0ad6142a8e8c7ec4006e6))
+* **watcher:** add global error handlers to prevent silent crashes ([cea4b57](https://github.com/covibes/zeroshot/commit/cea4b57fe7cfea899bf8981c2b0d200d1c0a9050))
+* **worker:** forbid scope reduction excuses in worker prompt ([c666847](https://github.com/covibes/zeroshot/commit/c6668473c7f2882482b0593950db780088721925))
+* **worktree:** inject cwd into dynamically spawned template agents ([4c3b916](https://github.com/covibes/zeroshot/commit/4c3b9162e5656133b01ccbf58c91782855669e33))
+
+
+### Features
+
+* **agents:** conditional git restriction based on isolation mode ([70eb368](https://github.com/covibes/zeroshot/commit/70eb3681c3d55747d72b491a4e85279b0e215ab5))
+* **orchestrator:** persist agent runtime states for accurate status display ([4205c7d](https://github.com/covibes/zeroshot/commit/4205c7d0234d3e34e0000ed15ac218c9edb7d048))
+* **validation:** enforce E2E verification with technical constraints ([f2a680a](https://github.com/covibes/zeroshot/commit/f2a680ada66e1485d174084d346c0ae9932ce2c9))
+* **worker:** add aggressive COMPLETION MINDSET to worker prompts ([0c6e37b](https://github.com/covibes/zeroshot/commit/0c6e37b4c0c58cab8b77b7ed1ba23ebb73f55d29))
+
 # [3.0.0](https://github.com/covibes/zeroshot/compare/v2.1.0...v3.0.0) (2025-12-29)
 
 

package/README.md

@@ -1,5 +1,7 @@
 # zeroshot CLI
 
+[![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)]()
@@ -32,19 +34,54 @@ Point at a GitHub issue, walk away, come back to working code.
 ### Demo
 
 ```bash
-zeroshot "Add rate limiting middleware: sliding window algorithm (not fixed window),
-per-IP tracking with in-memory store and automatic TTL cleanup to prevent memory leaks,
-configurable limits per endpoint. Return 429 Too Many Requests with Retry-After header
-(seconds until reset) and X-RateLimit-Remaining header on ALL responses.
-Must handle both IPv4 and IPv6, normalizing IPv6 to consistent format."
+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."
 ```
 
 <p align="center">
   <img src="./docs/assets/zeroshot-demo.gif" alt="Demo" width="700">
   <br>
-  <em>Sped up — original recording: 32 minutes</em>
+  <em>Sped up 100x — 90 minutes, $16, 5 iterations until validators approved</em>
 </p>
 
+**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.
+
+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.
+
+**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.
+
+---
+
+## When to Use Zeroshot
+
+**Zeroshot requires well-defined tasks with clear acceptance criteria.**
+
+| Scenario | Zeroshot? | Why |
+|----------|-----------|-----|
+| "Add rate limiting with sliding window, per-IP, 429 responses" | ✅ Yes | Clear requirements, validators can verify each one |
+| "Refactor auth to use JWT instead of sessions" | ✅ Yes | Known complexity, defined end state |
+| "Fix the bug where users can't login" | ✅ Yes | Known unknown - need to find cause, but success is clear |
+| "Fix all 2410 linting violations" | ✅ Yes | Long-running batch task, clear completion (0 violations) |
+| "Make the app faster" | ❌ No | Unknown unknowns - need exploration first |
+| "Improve the codebase" | ❌ No | No acceptance criteria to validate |
+| "Figure out why tests are flaky" | ❌ No | Exploratory - use single-agent Claude Code |
+
+**Known unknowns** (implementation details unclear) → Zeroshot handles this. The planner figures it out.
+
+**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"
+
+Crash recovery (`zeroshot resume`) means multi-hour tasks survive interruptions.
+
+**Rule of thumb:** If you can't describe what "done" looks like, zeroshot's validators can't verify it.
+
 ---
 
 ## Install
@@ -99,7 +136,8 @@ zeroshot purge                 # NUCLEAR: kill all + delete all
 
 ---
 
-## FAQ
+<details>
+<summary><strong>FAQ</strong></summary>
 
 **Q: Why Claude-only?**
 
@@ -119,12 +157,6 @@ Zeroshot fixes this with **isolated agents** where validators check work they di
 
 Yes, see CLAUDE.md. But most people never need to.
 
-**Q: Why does the CLI appear frozen?**
-
-Zeroshot agents use strict JSON schema outputs to ensure reliable parsing and hook execution. This is incompatible with live streaming - agents can't stream partial JSON.
-
-During heavy tasks (large refactors, complex analysis), the CLI may appear frozen for several minutes while the agent works. This is normal - the agent is actively running, just not streaming output.
-
 **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.
@@ -133,6 +165,8 @@ Same idea here: give zeroshot a well-defined task, get back a result. No example
 
 The multi-agent architecture handles planning, implementation, and validation internally. You provide a clear problem statement. Zeroshot handles the rest.
 
+</details>
+
 ---
 
 ## How It Works
@@ -145,9 +179,7 @@ Zeroshot is a **multi-agent coordination framework** with smart defaults.
 zeroshot 123  # Analyzes task → picks team → done
 ```
 
-The conductor classifies your task (complexity × type) and routes to a pre-built workflow.
-
-### Default Workflows (Out of the Box)
+The conductor classifies your task (complexity × type) and picks the right workflow:
 
 ```
                                 ┌─────────────────┐
@@ -187,7 +219,7 @@ The conductor classifies your task (complexity × type) and routes to a pre-buil
                                                   │      │   │ ✓ security (CRIT)    │
                                                   │      │   │ ✓ tester (CRIT)      │
                                                   │      │   │ ✓ adversarial        │
-                                                  │      │   │   (curl + browser)   │
+                                                  │      │   │   (real execution)   │
                                                   │      │   └──────────┬───────────┘
                                                   │      │       REJECT │ ALL OK
                                                   │      └──────────────┘     │
@@ -197,109 +229,28 @@ The conductor classifies your task (complexity × type) and routes to a pre-buil
      └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
-These are **templates**. The conductor picks based on what you're building.
-
 | Task                   | Complexity | Agents | Validators                                        |
 | ---------------------- | ---------- | ------ | ------------------------------------------------- |
 | Fix typo in README     | TRIVIAL    | 1      | None                                              |
 | Add dark mode toggle   | SIMPLE     | 2      | generic validator                                 |
-| Refactor auth system   | STANDARD   | 5      | requirements, code, adversarial                   |
+| Refactor auth system   | STANDARD   | 4      | requirements, code                                |
 | Implement payment flow | CRITICAL   | 7      | requirements, code, security, tester, adversarial |
 
-## End-to-End Flow
-
-**This is how zeroshot processes a task from start to finish:**
-
-```
-                              ╔═════════════════════════════════════════════════════╗
-                              ║            ZEROSHOT ORCHESTRATION ENGINE            ║
-                              ╚═════════════════════════════════════════════════════╝
-
-                                              ┌─────────────────┐
-                                              │   "Add auth     │
-                                              │   to the API"   │
-                                              └────────┬────────┘
-                                                       │
-                                                       ▼
-┌──────────────────────────────────────────────────────────────────────────────────────────────┐
-│                              CONDUCTOR (2D Classification)                                    │
-│  ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
-│  │  Junior (Haiku)                                     Senior (Sonnet)                     │ │
-│  │  ─────────────                                      ───────────────                     │ │
-│  │  Fast classification on 2 dimensions:        ───▶   Handles UNCERTAIN cases             │ │
-│  │  • Complexity: TRIVIAL | SIMPLE | STANDARD   (if    with deeper analysis                │ │
-│  │  • TaskType: INQUIRY | TASK | DEBUG          Junior                                     │ │
-│  │                                              unsure)                                    │ │
-│  └─────────────────────────────────────────────────────────────────────────────────────────┘ │
-└──────────────────────────────────────────────────────────────────────────────────────────────┘
-                                                       │
-                                                       │ Classification: STANDARD × TASK
-                                                       ▼
-                              ┌─────────────────────────────────────────┐
-                              │            CONFIG ROUTER                │
-                              │  ─────────────────────────────────────  │
-                              │  TRIVIAL        → single-worker         │
-                              │  SIMPLE         → worker-validator      │
-                              │  DEBUG (non-trivial) → debug-workflow   │
-                              │  STANDARD/CRITICAL  → full-workflow  ◀──│
-                              └─────────────────────────────────────────┘
-                                                       │
-                                                       │ Spawns full-workflow agents
-                                                       ▼
-┌──────────────────────────────────────────────────────────────────────────────────────────────┐
-│                                    FULL WORKFLOW                                             │
-│  ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
-│  │                                                                                         │ │
-│  │   ┌──────────────┐                                                                      │ │
-│  │   │   PLANNER    │  Creates implementation plan                                         │ │
-│  │   │ (opus/sonnet)│  • Analyzes requirements                                             │ │
-│  │   └──────┬───────┘  • Identifies files to change                                        │ │
-│  │          │          • Breaks into actionable steps                                      │ │
-│  │          │ PLAN_READY                                                                   │ │
-│  │          ▼                                                                              │ │
-│  │   ┌──────────────┐                                                                      │ │
-│  │   │    WORKER    │◀─────────────────────────────────────────────┐                       │ │
-│  │   │   (sonnet)   │  Implements the plan                         │                       │ │
-│  │   └──────┬───────┘  • Writes/modifies code                      │                       │ │
-│  │          │          • Handles rejections                        │                       │ │
-│  │          │ IMPLEMENTATION_READY                                 │                       │ │
-│  │          ▼                                                      │                       │ │
-│  │   ┌─────────────────────────────────────────────────────┐       │                       │ │
-│  │   │              VALIDATORS (parallel)                  │       │                       │ │
-│  │   │                                                     │       │                       │ │
-│  │   │  ┌────────────┐ ┌────────────┐ ┌─────────────────┐  │       │ REJECTED              │ │
-│  │   │  │Requirements│ │Code Review │ │  Adversarial    │  │       │                       │ │
-│  │   │  │  Validator │ │  (reviewer)│ │    Tester       │  │───────┘                       │ │
-│  │   │  │ (validator)│ │            │ │ EXECUTES tests  │  │                               │ │
-│  │   │  └────────────┘ └────────────┘ └─────────────────┘  │                               │ │
-│  │   │                                                     │                               │ │
-│  │   └──────────────────────┬──────────────────────────────┘                               │ │
-│  │                          │                                                              │ │
-│  │                          │ ALL APPROVED                                                 │ │
-│  │                          ▼                                                              │ │
-│  │                   ┌──────────────┐                                                      │ │
-│  │                   │   COMPLETE   │                                                      │ │
-│  │                   │  ──────────  │                                                      │ │
-│  │                   │  PR Created  │  (with --pr flag)                                    │ │
-│  │                   │  Auto-merged │  (with --merge flag)                                 │ │
-│  │                   └──────────────┘                                                      │ │
-│  │                                                                                         │ │
-│  └─────────────────────────────────────────────────────────────────────────────────────────┘ │
-└──────────────────────────────────────────────────────────────────────────────────────────────┘
-```
-
 ### Model Selection by Complexity
 
 | Complexity | Planner | Worker | Validators |
 | ---------- | ------- | ------ | ---------- |
 | TRIVIAL    | -       | haiku  | 0          |
 | SIMPLE     | -       | sonnet | 1 (sonnet) |
-| STANDARD   | sonnet  | sonnet | 3 (sonnet) |
+| STANDARD   | sonnet  | sonnet | 2 (sonnet) |
 | CRITICAL   | opus    | sonnet | 5 (sonnet) |
 
+Set model ceiling: `zeroshot settings set maxModel sonnet` (prevents opus)
+
 ---
 
-### Custom Workflows (Framework Mode)
+<details>
+<summary><strong>Custom Workflows (Framework Mode)</strong></summary>
 
 Zeroshot is **message-driven** - define any agent topology:
 
@@ -315,9 +266,46 @@ Zeroshot is **message-driven** - define any agent topology:
 - Ledger (SQLite, crash recovery)
 - Dynamic spawning (CLUSTER_OPERATIONS)
 
-See [CLAUDE.md](./CLAUDE.md) for custom cluster configs.
+#### Creating Custom Clusters with Claude Code
+
+**The easiest way to create a custom cluster: just ask Claude Code.**
+
+```bash
+# In your zeroshot repo
+claude
+```
+
+**Example prompt:**
+```
+Create a zeroshot cluster config for security-critical features:
 
-You don't configure defaults. But you **can** when needed.
+1. Implementation agent (sonnet) implements the feature
+2. FOUR parallel validators:
+   - Security validator: OWASP checks, SQL injection, XSS, CSRF
+   - Performance validator: No N+1 queries, proper indexing
+   - Privacy validator: GDPR compliance, data minimization
+   - Code reviewer: General code quality
+
+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)
+
+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)
+
+See [CLAUDE.md](./CLAUDE.md) for cluster config schema and examples.
+
+</details>
 
 ---
 
@@ -350,6 +338,62 @@ zeroshot 123 --docker
 
 Full isolation in a fresh container. Your workspace stays untouched. Good for risky experiments or parallel agents.
 
+### When to Use Which
+
+| Scenario | Recommended |
+| -------- | ----------- |
+| Quick trusted task | 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` |
+
+### Docker Credential Mounts
+
+When using `--docker`, zeroshot mounts credential directories so Claude can access tools like AWS, Azure, kubectl.
+
+**Default mounts**: `gh`, `git`, `ssh` (GitHub CLI, git config, SSH keys)
+
+**Available presets**: `gh`, `git`, `ssh`, `aws`, `azure`, `kube`, `terraform`, `gcloud`
+
+```bash
+# Configure via settings (persistent)
+zeroshot settings set dockerMounts '["gh", "git", "ssh", "aws", "azure"]'
+
+# View current config
+zeroshot settings get dockerMounts
+
+# Per-run override
+zeroshot run 123 --docker --mount ~/.aws:/root/.aws:ro
+
+# Disable all mounts
+zeroshot run 123 --docker --no-mounts
+
+# CI: env var override
+ZEROSHOT_DOCKER_MOUNTS='["aws","azure"]' zeroshot run 123 --docker
+```
+
+**Custom mounts** (mix presets with explicit paths):
+```bash
+zeroshot settings set dockerMounts '[
+  "gh",
+  "git",
+  {"host": "~/.myconfig", "container": "$HOME/.myconfig", "readonly": true}
+]'
+```
+
+**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:
+```bash
+zeroshot settings set dockerEnvPassthrough '["MY_API_KEY", "TF_VAR_*"]'
+```
+
 ---
 
 ## More
@@ -360,18 +404,20 @@ Full isolation in a fresh container. Your workspace stays untouched. Good for ri
 
 ---
 
-## Troubleshooting
+<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/)                        |
-| CLI frozen for minutes        | Normal - agents use JSON schema output, can't stream partial results |
 | `--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`                                   |
 
+</details>
+
 ---
 
 ## Contributing