Document Web client and sub-agent system

New docs:
- docs/WEBUI.md — kode serve: architecture, features (@ completion,
  sessions, streaming), WebSocket protocol, flags, implementation details
- docs/SUBAGENTS.md — task decomposition: architecture diagram, when to
  decompose, delegate_tasks tool schema, kode subagent CLI, output
  protocol, system prompt, security model, testing layers, E2E flow

Updated docs:
- README.md — link to WEBUI.md + SUBAGENTS.md, quick ref entries
- docs/CLI.md — serve + subagent in commands table
- docs/CONFIG.md — subagent config section with table
- docs/DEVELOPMENT.md — full source layout, test layers, key packages

Author: jkyberneees

README.md

@@ -84,6 +84,8 @@ kode run --learn "Set up a Go project with CI"
 | **Multi-Turn Sessions** | [docs/SESSIONS.md](docs/SESSIONS.md) — save, continue, list, trim, cleanup |
 | **Sandboxing** | [docs/SANDBOXING.md](docs/SANDBOXING.md) — Docker isolation, security, config |
 | **Security** | [docs/SECURITY.md](docs/SECURITY.md) — prompt injection, sandbox model |
+| **Web UI** | [docs/WEBUI.md](docs/WEBUI.md) — `kode serve`, WebSocket protocol, `@` resource completion |
+| **Sub-Agents** | [docs/SUBAGENTS.md](docs/SUBAGENTS.md) — task decomposition, parallel OS-process sub-agents |
 | **Skills** | [docs/CLI.md#skills](docs/CLI.md#skills) — learn, list, save, import, curate |
 | **Development** | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — building, testing, contributing |
 
@@ -105,6 +107,8 @@ kode skill view <name>                          # View a skill
 kode skill delete <name>                        # Delete a skill
 kode skill import <uri> [--basic --yes]         # Import skill from URI
 kode skill curate                               # Quality/overlap audit
+kode serve [--addr :8080] [--open]              # Web UI server
+kode subagent --goal <string> [flags]           # Run a focused sub-task (JSON stdout)
 kode init [--global] [--force]                  # Create config file
 kode version                                    # Print version
 

docs/CLI.md

@@ -19,6 +19,8 @@
 | `kode skill delete <name>` | Delete a skill |
 | `kode skill import <uri> [flags]` | Import a skill from file:// or https:// |
 | `kode skill curate` | Analyze skills for quality, staleness, trigger overlap |
+| `kode serve [--addr :8080] [--open]` | Web UI server with WebSocket streaming, `@` resource completion, session history |
+| `kode subagent --goal <string> [flags]` | Run a focused sub-task; outputs JSON on stdout. Spawned by `delegate_tasks` tool |
 | `kode init [--global] [--force]` | Create a config file template |
 | `kode version` | Print version and exit |
 

docs/CONFIG.md

@@ -110,6 +110,28 @@ The `skills` section controls the skill system:
 | `curation.staleness_days` | — | 90 | Days without use before flagging as stale |
 | `curation.auto_prune` | — | false | Auto-delete stale skills on curate (no prompt) |
 
+## Sub-agent configuration
+
+The `subagent` section controls task decomposition and parallel sub-agent execution (see [docs/SUBAGENTS.md](docs/SUBAGENTS.md)):
+
+```json
+{
+  "subagent": {
+    "max_concurrency": 3,
+    "timeout_seconds": 120,
+    "max_iterations": 15
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `max_concurrency` | 3 | Max sub-agents running in parallel (max 8) |
+| `timeout_seconds` | 120 | Default timeout per sub-agent (overridden by `--timeout`) |
+| `max_iterations` | 15 | Default max think→act cycles per sub-agent (overridden by `--max-iter`) |
+
+This section is optional. Omitted fields inherit sensible defaults.
+
 ## kode init
 
 Create a config file template:
@@ -142,6 +164,9 @@ KODE_SANDBOX=true kode run "run untrusted script"
 # Enable skill learning via env var
 KODE_SKILLS_LEARN=true kode run "set up CI"
 
+# Sub-agent config (project-level)
+echo '{"subagent": {"max_concurrency": 5, "timeout_seconds": 300}}' > ./kode.json
+
 # CLI flag always wins
 kode run --model gpt-4o --base-url https://api.openai.com/v1 "task"
 ```

docs/DEVELOPMENT.md

@@ -11,18 +11,89 @@
 go build -o kode ./cmd/kode
 ```
 
+## Source layout
+
+```
+kode.go                       Public API (Config, New, Run, Close)
+kode_test.go                  Config and model profile tests
+internal/
+  config/
+    loader.go                 Config file loading, env vars, priority merge
+    loader_test.go            Config loading tests
+  llm/
+    client.go                 OpenAI-compatible HTTP client
+    client_test.go            JSON marshaling + response parsing tests
+  loop/
+    loop.go                   ReAct engine (observe → think → act → repeat)
+    loop_test.go              Engine tests with mock server
+  session/
+    session.go                Session store (CRUD, trim, cleanup)
+    session_test.go           Session tests
+  render/
+    render.go                 Terminal output with model label and color
+  resource/
+    resource.go               @-reference resolver (files, sessions)
+    resource_test.go          Parse, resolve, search tests
+  ws/
+    ws.go                     RFC 6455 WebSocket framing (~200 LOC)
+    ws_test.go                Handshake, framing, ping/pong tests
+  tool/
+    registry.go               Thread-safe tool registry
+    registry_test.go          Registry tests
+cmd/kode/
+  main.go                     CLI entry point, flag parsing, commands, sandbox
+  main_test.go                CLI tests (flag parsing, version, init)
+  shell.go                    Built-in shell tool (local or docker exec)
+  shell_test.go               Shell + sandbox tests
+  serve.go                    Web UI server (HTTP + WebSocket)
+  subagent.go                 Sub-agent command (--goal, --context, --task, JSON stdout)
+  subagent_tool.go            delegate_tasks built-in tool
+  subagent_test.go            Contract tests (30 — flags, JSON, exit codes, tool schema)
+  subagent_contract_test.go   Contract tests (flag parsing, stdout protocol, exit codes)
+  subagent_e2e_test.go        E2E tests (13 — KODE_E2E=true, real subprocess spawning)
+  ui/
+    index.html                Single-page web UI (~770 LOC, vanilla JS + CSS)
+docs/                         Documentation
+  CLI.md                      CLI reference
+  CONFIG.md                   Configuration system
+  PROVIDERS.md                Models, profiles, thinking, context
+  SESSIONS.md                 Multi-turn sessions
+  WEBUI.md                    Web UI server + WebSocket protocol + @ completion
+  SUBAGENTS.md                Task decomposition + sub-agents + delegate_tasks tool
+  SECURITY.md                 Prompt injection, security model
+  SANDBOXING.md               Sandbox configuration
+  DEVELOPMENT.md              This file
+```
+
 ## Testing
 
 ```bash
-# All tests
-go test ./... -v -count=1
+# All tests (excluding E2E — those need KODE_E2E=true)
+go test ./... -count=1
 
 # Specific package
 go test ./internal/session/ -v
+
+# With race detector
+go test -race ./... -count=1
+
+# E2E tests (builds kode binary, tests real subprocess spawning)
+KODE_E2E=true go test -v -count=1 ./cmd/kode/ -run "TestE2E_"
+
+# Contract tests (sub-agent interface contract — binary must already be built)
+go test -v -count=1 ./cmd/kode/ -run "TestSubagent|TestDelegateTasks"
 ```
 
 Zero external test dependencies — tests use `httptest`, `testing`, and the standard library only.
 
+### Test layers
+
+| Layer | Runner | Tests | What's tested |
+|-------|--------|-------|---------------|
+| **Unit** | `go test ./...` | 190+ | Config, LLM client, sessions, renderer, tools, WS, resources |
+| **Contract** | `go test ./cmd/kode/` | 30 | Sub-agent flag parsing, JSON stdout, exit codes, tool schema, config |
+| **E2E** | `KODE_E2E=true go test -run "TestE2E_"` | 13 | Real subprocess spawning, tool→binary pipeline, concurrency, timeouts |
+
 ### Test coverage
 
 | Package | Tests | Focus |
@@ -33,45 +104,26 @@ Zero external test dependencies — tests use `httptest`, `testing`, and the sta
 | `internal/loop` | 7 | ReAct engine with httptest mock server |
 | `internal/session` | 19 | CRUD, trim, cleanup, list, latest, edge cases |
 | `internal/tool` | 7 | Registry CRUD, lookup, duplicate detection |
-| `cmd/kode` | 20+ | Flag parsing, init, version, sandbox setup, integration |
+| `internal/ws` | 8 | WebSocket upgrade, framing, ping/pong |
+| `internal/resource` | 12 | @-reference parsing, file resolution, session resolution, security |
+| `cmd/kode` | 60+ | Flag parsing, init, version, sandbox setup, subagent, serve, E2E |
 
-## Source layout
+## Key packages
 
-```
-kode.go               Public API (Config, New, Run, Close)
-kode_test.go          Config and model profile tests
-internal/
-  config/
-    loader.go         Config file loading, env vars, priority merge
-    loader_test.go    Config loading tests
-  llm/
-    client.go         OpenAI-compatible HTTP client
-    client_test.go    JSON marshaling + response parsing tests
-  loop/
-    loop.go           ReAct engine (observe → think → act → repeat)
-    loop_test.go      Engine tests with mock server
-  session/
-    session.go        Session store (CRUD, trim, cleanup)
-    session_test.go   Session tests
-  render/
-    render.go         Terminal output with model label and color
-  tool/
-    registry.go       Thread-safe tool registry
-    registry_test.go  Registry tests
-cmd/kode/
-  main.go             CLI entry point, flag parsing, commands, sandbox
-  main_test.go        CLI tests
-  shell.go            Built-in shell tool (local or docker exec)
-  shell_test.go       Shell + sandbox tests
-docs/                 Documentation
-  CLI.md              CLI reference
-  CONFIG.md           Configuration system
-  PROVIDERS.md        Models, profiles, thinking, context
-  SESSIONS.md         Multi-turn sessions
-  SECURITY.md         Prompt injection, security model
-  SANDBOXING.md       Sandbox configuration
-  DEVELOPMENT.md      This file
-```
+### Web UI (`cmd/kode/serve.go` + `internal/ws/ws.go` + `cmd/kode/ui/index.html`)
+
+- **serve.go**: HTTP server with embedded WebSocket handler, `@` resource API, session list API
+- **ws/ws.go**: Zero-dependency RFC 6455 WebSocket (~200 LOC). Handles upgrade, text frames, close, ping/pong
+- **ui/index.html**: Single-file SPA, ~770 LOC vanilla JS + CSS. Streaming, collapsible tool blocks, `@` autocomplete, session sidebar
+
+See [docs/WEBUI.md](docs/WEBUI.md) for the WebSocket protocol and full documentation.
+
+### Sub-agents (`cmd/kode/subagent.go` + `cmd/kode/subagent_tool.go`)
+
+- **subagent.go**: CLI handler for `kode subagent --goal <string>`. Parses flags, creates agent, runs with minimal system prompt, outputs JSON to stdout
+- **subagent_tool.go**: `delegate_tasks` built-in tool. Spawns real OS processes via `exec.Command` with temp files for task data
+
+See [docs/SUBAGENTS.md](docs/SUBAGENTS.md) for full documentation.
 
 ## Contributing