chore(v0.2.2): wrap up — README, CHANGELOG, version, gitignore, CLAUDE.md

- README: full rewrite for v0.2.2 — supercar-themed lead paragraph, local LLM
  section with igllama usage, session summary example, tests badge (195/195),
  Showcase link in docs section, igllama in inspiration table
- CHANGELOG: add [0.2.2] entry covering all changes in this release
- build.zig.zon: bump version 0.2.1 → 0.2.2
- src/main.zig: bump VERSION constant and test 0.2.1 → 0.2.2
- .gitignore: add .powerglide/ (runtime session dir written by powerglide run)
- CLAUDE.md: add igllama section, current version note, update roadmap to
  include items 8-10 (igllama, session summary, showcase)

195/195 tests passing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: bkataru

.gitignore

@@ -43,3 +43,6 @@ revert_*.py
 test_*.zig
 test_env
 test_arraylist
+
+# Runtime session data written by powerglide run/agent
+.powerglide/

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to the **powerglide** project will be documented in this file.
 
+## [0.2.2] - 2026-03-04
+
+### Added
+- **Session summary output** — `powerglide run` now emits a structured completion block showing steps taken, elapsed time, agent/model name, and `<POWERGLIDE_DONE>` or `<POWERGLIDE_ERROR>` terminal signal
+- **igllama port scanning** — `powerglide doctor` scans `:8090–8099` instead of hardcoded `:8090`; reports all running igllama instances
+- **`json_mode` on `OpenAIClient`** — sets `response_format: {"type":"json_object"}` for constrained JSON generation on igllama and other local endpoints
+- **Showcase page** — `website/content/showcase.smd` with 4 case studies: codebase exploration (0.8B), targeted query (4B), tool calling triage + json_mode, session summary output; performance table; dogfooding verdict
+- **Showcase nav link** — added to both `page.shtml` and `home.shtml` nav bars with amber highlight
+- **Tests badge** in README (195/195)
+
+### Fixed
+- **`Loop step count increments` test** — now uses `/tmp/test_loop_step_count.json` instead of default `.powerglide/session.json`; previously picked up real session state from dogfooding runs and failed
+- **README** — updated to v0.2.2 with local LLM section, session summary example, igllama integration, Showcase link, and tests badge
+
 ## [0.2.1] - 2026-03-04
 
 ### Added

CLAUDE.md

@@ -41,12 +41,27 @@ cp -r zig-out/docs/. ../docs/
 - `src/mcp/tool_bridge.zig` — converts `McpTool` → `Tool`, prefixed `mcp_{server}_{tool}`
 - Config key: `mcp_servers` array in `~/.config/powerglide/config.json`
 
+## igllama / Local LLM
+
+- `local` agent → `Qwen3.5-0.8B-Q8_0.gguf` on `http://127.0.0.1:8090/v1`
+- `local4b` agent → `Qwen3.5-4B-Q8_0.gguf` on `http://127.0.0.1:8091/v1`
+- Start with: `igllama api <model.gguf> --port <N> --no-think`
+- `OpenAIClient.json_mode = true` → forces `response_format: {"type":"json_object"}` for constrained output
+- Doctor scans `:8090–8099` automatically
+
+## Current Version
+
+`0.2.2` — 195/195 tests passing, 0 leaks.
+
 ## Roadmap
 
 1. ✅ Zig 0.15.2 compatibility
 2. ✅ Multi-agent swarm implementation
 3. ✅ Ralph Loop integration
-4. ✅ Technical overhaul of website & prose
+4. ✅ Technical overhaul of website & prose (supercar theme)
 5. ✅ Refactored velocity to multiplier model
 6. ✅ TUI implementation (vxfw multi-agent dashboard)
 7. ✅ MCP integration (`src/mcp/` — server, client, tool_bridge)
+8. ✅ igllama integration — local Qwen3.5 agents, json_mode, port scanning
+9. ✅ Session summary output on `powerglide run` completion
+10. ✅ Showcase page — dogfooding case studies with 0.8B and 4B models

README.md

@@ -6,6 +6,7 @@
 
 [![Zig](https://img.shields.io/badge/Zig-0.15.2-F7A41D?logo=zig&logoColor=white)](https://ziglang.org/)
 [![Build](https://github.com/bkataru/powerglide/actions/workflows/ci.yml/badge.svg)](https://github.com/bkataru/powerglide/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-195%2F195-brightgreen)](https://github.com/bkataru/powerglide)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 [![GitHub Stars](https://img.shields.io/github/stars/bkataru/powerglide?style=social)](https://github.com/bkataru/powerglide)
 
@@ -17,9 +18,9 @@
 
 ## What is powerglide?
 
-**powerglide** is a high-performance CLI coding agent runtime built in [Zig 0.15.2](https://ziglang.org/). It provides a robust, fault-tolerant execution layer for LLM swarms, designed specifically for autonomous coding tasks that require high throughput and verifiable correctness.
+Like a finely tuned transmission at full throttle, **powerglide** swerves through your codebase with precision, force, and grace. It is the layer between you and a swarm of LLM-driven engineers working in parallel — written in [Zig 0.15.2](https://ziglang.org/), compiled to a single static binary with zero runtime dependencies, and built around one non-negotiable constraint: the agent loop must be reliable enough to run unattended.
 
-Unlike open-ended agent loops that can drift or hang, powerglide is built around the **Ralph Loop** — an explicit 11-state machine that ensures every step is auditable, every tool call is isolated in its own PTY, and every session terminates with a clear protocol signal.
+The foundation is the **Ralph Loop** — an explicit 11-state machine that sequences every agent action from task intake through tool execution to verified completion. No implicit flow, no silent exits. Every session terminates with `<POWERGLIDE_DONE>` or `<POWERGLIDE_ERROR>`. The loop drives the model; the model does not drive the loop.
 
 ```bash
 $ powerglide run --agent hephaestus --velocity 2.0 "refactor the auth module to use the new session manager"
@@ -29,11 +30,13 @@ $ powerglide run --agent hephaestus --velocity 2.0 "refactor the auth module to
 
 ## Core Pillars
 
-- **The Ralph Loop** 🔄 — An explicit state machine (`idle → load_tasks → pick_task → thinking → tool_call → executing → observing → verify → commit → done`) that sequences cognition and action. No silent failures, no implicit transitions.
-- **Velocity Control** 🚀 — Precision control over agent throughput. Velocity is a floating-point multiplier (f64) on a 1000ms base delay (`delay_ms = 1000 / velocity`). Default is `1.0` (1000ms). Speed up (`--velocity 2.0` = 500ms) or slow down (`--velocity 0.5` = 2000ms) as needed.
-- **Reliable PTYs** 💻 — Every tool execution happens in a real pseudoterminal. Exit codes are captured via `waitpid` with a `/proc` fallback, ensuring that `zig build` or `pytest` results are 100% reliable.
-- **Rogue Agent Prevention** 🛡️ — Defense in depth with step limits, heartbeat monitoring, circuit breakers for repeat tool calls, and budget tracking. Rogue agents are killed before they can damage your codebase.
-- **Multi-Model Routing** 🤖 — Native support for Anthropic (Claude), OpenAI, and any OpenAI-compatible endpoint. Automatic fallback chains ensure that rate limits don't stop your workflow.
+- **The Ralph Loop** 🔄 — Explicit 11-state machine: `idle → load_tasks → pick_task → thinking → tool_call → executing → observing → verify → commit → done`. Every step is auditable; every session ends with a deterministic terminal signal.
+- **Velocity Control** 🚀 — Precision control over agent throughput. `delay_ms = 1000 / velocity`. Speed up (`--velocity 2.0` = 500ms/step) or slow down (`--velocity 0.5` = 2000ms/step) without restarting the session. Agents can self-throttle mid-run.
+- **Reliable PTYs** 💻 — Every tool runs in a real pseudoterminal. Exit codes captured via `waitpid` with WNOHANG polling and a `/proc/<pid>/status` fallback — so `zig build`, `pytest`, and `bash` all deliver trustable results to the VERIFY state.
+- **Rogue Agent Prevention** 🛡️ — Step limits, heartbeat monitoring (30s), circuit breakers for repeated tool calls, and budget tracking. Stuck agents are killed before they accumulate diverged work.
+- **Multi-Model Routing** 🤖 — Anthropic (Claude), OpenAI, and any OpenAI-compatible endpoint (Ollama, [igllama](https://github.com/bkataru/igllama), NVIDIA NIM, Together AI). Fallback chains keep sessions alive through provider outages.
+- **MCP Integration** 🔌 — Run as an MCP server (`powerglide mcp`) or connect to external MCP servers as a client. External tools get prefixed names and become first-class tools in the registry.
+- **Local LLM Support** 🏠 — Pre-configured `local` and `local4b` agents route to igllama on `:8090`/`:8091`. No API keys required for exploration and triage workflows.
 
 ---
 
@@ -47,136 +50,152 @@ $ powerglide run --agent hephaestus --velocity 2.0 "refactor the auth module to
 
 ![Swarm Architecture](docs/svg/swarm-arch.svg)
 
+### The Ralph Loop
+
+![Ralph Loop](docs/svg/ralph-loop.svg)
+
 ---
 
 ## Quick Start
 
 ### Prerequisites
 
-- [Zig 0.15.2](https://ziglang.org/download/) — `mise install zig@0.15.2` or from official binaries.
-- An API key for your provider (set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`).
+- [Zig 0.15.2](https://ziglang.org/download/) — `mise install zig@0.15.2` or official binaries
+- An API key for your provider (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`), **or** run [igllama](https://github.com/bkataru/igllama) locally for a fully offline stack
 
 ### Build
 
 ```bash
 git clone https://github.com/bkataru/powerglide
 cd powerglide
 zig build
+# Binary at ./zig-out/bin/powerglide
 ```
 
-The static binary is located at `./zig-out/bin/powerglide`.
-
 ### Run
 
 ```bash
-# Verify system health and API keys
+# Verify setup — scans :8090-8099 for local igllama instances
 ./zig-out/bin/powerglide doctor
 
-# Launch a new agent session
+# Run a session (cloud)
 ./zig-out/bin/powerglide run "implement a binary search tree in Zig"
 
+# Run fully locally with Qwen3.5-4B via igllama
+igllama api Qwen3.5-4B-Q8_0.gguf --port 8091 --no-think &
+./zig-out/bin/powerglide run --agent local4b "describe the orchestrator module"
+
 # Run at double speed
 ./zig-out/bin/powerglide run --velocity 2.0 "add comprehensive unit tests"
 
-# Open the multi-agent TUI dashboard
+# Open multi-agent TUI dashboard
 ./zig-out/bin/powerglide tui
 ```
 
+Every completed session emits a structured summary:
+
+```
+─────────────────────────────────────────
+  Session complete  [done]
+  Steps:    9
+  Elapsed:  3.4s
+  Agent:    local4b  (Qwen3.5-4B-Q8_0.gguf)
+  Signal:   <POWERGLIDE_DONE>
+─────────────────────────────────────────
+```
+
 ---
 
 ## CLI Reference
 
 | Command | Purpose |
 |---------|---------|
 | `run` | Launch a coding agent session |
-| `session` | Manage sessions (list, resume, show, delete) |
-| `agent` | Manage agent configurations (hephaestus, artistry, deep) |
+| `session` | Manage sessions — list, show, resume, delete, export |
+| `agent` | Manage agent configs — list, add, remove, show |
 | `swarm` | Orchestrate parallel worker swarms |
 | `config` | View and modify global configuration |
-| `tools` | List and test available MCP-style tools |
-| `tui` | Launch the multi-panel dashboard |
+| `tools` | List and test available tools |
+| `mcp` | Start powerglide as an MCP server |
+| `tui` | Launch the multi-panel vxfw dashboard |
 | `doctor` | Run system health checks |
+| `version` | Show version |
 
 ---
 
 ## MCP Integration
 
-powerglide speaks [Model Context Protocol](https://modelcontextprotocol.io/) natively — both as a server and as a client.
+powerglide speaks [Model Context Protocol](https://modelcontextprotocol.io/) natively — as both server and client.
 
 ### As an MCP Server
 
-Run powerglide as an MCP server to expose its tools to any MCP-compatible client (Claude Desktop, another powerglide instance, or any JSON-RPC 2.0 client over stdin/stdout):
-
 ```bash
 powerglide mcp
 ```
 
-The server advertises all registered tools via `tools/list` and handles `tools/call` requests. Protocol sequence:
-1. Client sends `initialize` — server responds with `protocolVersion: "2024-11-05"` and `capabilities.tools`
-2. Client sends `tools/list` — server returns the full tool registry as MCP tool descriptors
-3. Client sends `tools/call` — server executes the tool and returns `content: [{type: "text", text: "..."}]`
+Exposes all registered tools via JSON-RPC 2.0 over stdin/stdout. Any MCP-compatible client (Claude Desktop, another powerglide instance) can call powerglide tools.
 
 ### As an MCP Client
 
-Connect powerglide to external MCP servers to bring their tools into its registry as first-class powerglide tools. Add `mcp_servers` to your config:
+Add `mcp_servers` to `~/.config/powerglide/config.json`:
 
 ```json
 {
   "mcp_servers": [
     {
       "name": "filesystem",
       "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
-    },
-    {
-      "name": "github",
-      "command": ["npx", "-y", "@modelcontextprotocol/server-github"]
     }
   ]
 }
 ```
 
-External tools are registered with prefixed names (`mcp_filesystem_read_file`, `mcp_github_search_repositories`) and become indistinguishable from built-in tools to the agent loop.
+External tools register as `mcp_filesystem_read_file` etc. and are indistinguishable from built-in tools to the agent loop.
 
 ---
 
-## The Ralph Loop
+## Local LLM Dogfooding
 
-Every powerglide agent session is driven by the **Ralph Loop** — an explicit state machine that enforces a strict sequence from task intake through tool execution to completion.
+powerglide ships with igllama integration for fully local inference. See the **[Showcase](https://bkataru.github.io/powerglide/showcase/)** for case studies with Qwen3.5 0.8B and 4B models — including tool calling triage, session summary analysis, and the honest performance table.
 
-![Ralph Loop](docs/svg/ralph-loop.svg)
+```bash
+# Start igllama (Zig-based Ollama alternative)
+igllama api Qwen3.5-0.8B-Q8_0.gguf --port 8090 --no-think &
+igllama api Qwen3.5-4B-Q8_0.gguf  --port 8091 --no-think &
+
+# Doctor detects both automatically
+powerglide doctor
+# OK   igllama: running on :8090 (local agent available)
+# OK   igllama: running on :8091 (local agent available)
+```
 
 ---
 
 ## Inspiration
 
-powerglide is inspired by the best ideas from the AI coding agent ecosystem:
+powerglide synthesizes the strongest ideas from the AI coding agent ecosystem:
 
-| Project | Inspiration |
-|---------|------------|
-| [oh-my-pi](https://github.com/can1357/oh-my-pi) | Multi-agent harness patterns, agent orchestration |
-| [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) | Ralph Wiggum loop, autonomous agent control |
-| [ralph](https://github.com/snarktank/ralph) | Ralph loop state machine, explicit done signals |
-| [The Ralph Playbook](https://github.com/ghuntley/how-to-ralph-wiggum) | Ralph Wiggum methodology, autonomous loops |
-| [gastown](https://github.com/steveyegge/gastown) | Multi-agent workspace isolation, task queues |
+| Project | What We Took |
+|---------|--------------|
+| [oh-my-pi](https://github.com/can1357/oh-my-pi) | Multi-agent harness: N workers, one orchestrator, file-based coordination |
+| [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) | Autonomous coding agents as invocable CLI subprocesses |
+| [ralph](https://github.com/snarktank/ralph) | The Ralph Loop pattern: explicit states, explicit done signal |
+| [gastown](https://github.com/steveyegge/gastown) | Per-worker workspace isolation, no write conflicts |
+| [opencode](https://github.com/anomalyco/opencode) | CLI structure and multi-model routing with fallback chains |
 | [loki](https://github.com/Dark-Alex-17/loki) | Tool registry, provider abstraction, session persistence |
 | [plandex](https://github.com/plandex-ai/plandex) | Plan+execute pattern, diff-based application |
-| [opencode](https://github.com/anomalyco/opencode) | CLI UX, multi-model routing |
-| [aichat](https://github.com/sigoden/aichat) | SSE streaming, config schema |
-| [goose](https://github.com/block/goose) | Agent extensibility, MCP integration |
-| [crush](https://github.com/charmbracelet/crush) | Terminal UX, TUI design |
-| [mem0](https://github.com/mem0ai/mem0) | Persistent memory layer for AI agents |
-| [pi-mono](https://github.com/badlogic/pi-mono) | Multi-agent coordination patterns |
-| [forge code](https://forgecode.dev) | Agentic coding workflow design |
+| [goose](https://github.com/block/goose) | MCP integration, agent extensibility |
+| [crush](https://github.com/charmbracelet/crush) | Terminal UX sensibility, vxfw-based TUI |
+| [mem0](https://github.com/mem0ai/mem0) | Persistent memory layer design |
+| [igllama](https://github.com/bkataru/igllama) | Local GGUF inference, OpenAI-compatible API for Qwen3.5 |
 
 ---
 
-## For AI Agents
-
-Powerglide is designed to be wielded by other agents. See [AGENTS.md](AGENTS.md) for the protocol specification and integration guide.
-
 ## Documentation
 
-Full documentation is available at [bkataru.github.io/powerglide](https://bkataru.github.io/powerglide).
+Full docs at **[bkataru.github.io/powerglide](https://bkataru.github.io/powerglide)** — including [Architecture](https://bkataru.github.io/powerglide/architecture/), [CLI Reference](https://bkataru.github.io/powerglide/cli-reference/), [Configuration](https://bkataru.github.io/powerglide/configuration/), and the [Showcase](https://bkataru.github.io/powerglide/showcase/).
+
+For AI agents working with powerglide programmatically, see [AGENTS.md](AGENTS.md).
 
 ## License
 

build.zig.zon

@@ -9,7 +9,7 @@
     .name = .powerglide,
     // This is a [Semantic Version](https://semver.org/).
     // In a future version of Zig it will be used for package deduplication.
-    .version = "0.2.1",
+    .version = "0.2.2",
     // Together with name, this represents a globally unique package
     // identifier. This field is generated by the Zig toolchain when the
     // package is first created, and then *never changes*. This allows

src/main.zig

@@ -5,7 +5,7 @@ const clap = @import("clap");
 const pg_lib = @import("powerglide");
 const tui_app = pg_lib.tui;
 
-const VERSION = "0.2.1";
+const VERSION = "0.2.2";
 const ConfigDir = ".config/powerglide";
 
 /// Main entry point
@@ -1244,7 +1244,7 @@ fn checkConfigDir(writer: anytype) !void {
 }
 
 test "VERSION constant is defined" {
-    try std.testing.expectEqualStrings("0.2.1", VERSION);
+    try std.testing.expectEqualStrings("0.2.2", VERSION);
 }
 
 test "VERSION matches expected format" {