docs: UseZombie v0.3.0 documentation site (M13_002)

.github/workflows/gitleaks.yml

@@ -0,0 +1,19 @@
+name: gitleaks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  gitleaks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

.github/workflows/lint.yml

@@ -0,0 +1,21 @@
+name: Lint
+
+on:
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: lint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - run: make lint

.node-version

@@ -0,0 +1 @@
+24

AGENTS.md

@@ -1,33 +1,54 @@
-> **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project.
-> For Mintlify product knowledge (components, configuration, writing standards),
-> install the Mintlify skill: `npx skills add https://mintlify.com/docs`
-
 # Documentation project instructions
 
 ## About this project
 
-- This is a documentation site built on [Mintlify](https://mintlify.com)
+- This is the UseZombie documentation site built on [Mintlify](https://mintlify.com)
 - Pages are MDX files with YAML frontmatter
 - Configuration lives in `docs.json`
-- Run `mint dev` to preview locally
+- Run `mint dev` to preview locally on port 3000
 - Run `mint broken-links` to check links
+- Deploys automatically on push to the default branch (Mintlify GitHub integration)
 
 ## Terminology
 
-{/* Add product-specific terms and preferred usage */}
-{/* Example: Use "workspace" not "project", "member" not "user" */}
+- Use "spec" not "specification" or "ticket"
+- Use "run" not "job" or "task"
+- Use "workspace" not "project"
+- Use "gate loop" not "CI pipeline" or "validation loop"
+- Use "scorecard" not "report" or "metrics"
+- Use "agent" not "bot" or "AI"
+- Use "PR" not "pull request" (except on first mention per page)
+- Use "zombiectl" in code formatting when referring to CLI commands
+- Use "zombied" in code formatting when referring to server processes
+- Use "Mission Control" for the web dashboard (app.usezombie.com)
 
 ## Style preferences
 
-{/* Add any project-specific style rules below */}
-
 - Use active voice and second person ("you")
 - Keep sentences concise — one idea per sentence
 - Use sentence case for headings
 - Bold for UI elements: Click **Settings**
 - Code formatting for file names, commands, paths, and code references
+- Mermaid for all sequence and architecture diagrams
+- Do not use time estimates or effort ratings in user-facing docs
+- Mark future features with `<Note>` callout: "This feature is coming soon."
 
 ## Content boundaries
 
-{/* Define what should and shouldn't be documented */}
-{/* Example: Don't document internal admin features */}
+- Do not document internal deployment playbooks (those live in the main repo)
+- Do not expose credential values, vault paths, or 1Password references
+- Do not document internal agent pipeline internals (NullClaw config details, executor RPC protocol) — keep operator docs at the operational level
+- Do not reference specific cloud provider pricing or account details
+
+## Design system colors
+
+{/* SYNC SOURCE: ~/Projects/usezombie/ui/packages/design-system/src/tokens.css
+     When touching colors in this repo (docs.json, logos, custom CSS), always
+     verify values against the canonical design-system tokens first.
+     Run: grep -E "^  --z-(orange|bg|text|green|cyan|red|amber)" ~/Projects/usezombie/ui/packages/design-system/src/tokens.css */}
+
+Primary brand color: `#d96b2b` (`--z-orange`). Use this for emphasis and CTAs.
+Primary bright/hover: `#e78a3c` (`--z-orange-bright`).
+Background dark: `#05080d` (`--z-bg-0`). Surface: `#0f1520` (`--z-surface-0`).
+Text primary: `#e8f2ff` (`--z-text-primary`). Text muted: `#8b97a8` (`--z-text-muted`).
+Status colors: green `#39ff85` (`--z-green`, done), cyan `#5ed4ec` (`--z-cyan`, running), red `#ff4d6a` (`--z-red`, failed), amber `#c99232` (`--z-amber`, queued).

Makefile

@@ -0,0 +1,8 @@
+.PHONY: dev lint
+
+dev:
+	npx mintlify dev
+
+lint:
+	npx mintlify validate
+	npx mintlify broken-links

api-reference/endpoint/agent-stream.mdx

@@ -0,0 +1,128 @@
+---
+title: Agent stream
+description: Stateless agent relay for spec init and impact preview.
+---
+
+## `POST /v1/agent/stream`
+
+Stateless relay between the CLI and the workspace's LLM provider. `zombied` adds the system prompt and API key, forwards to the provider, and streams the response back as SSE.
+
+The CLI manages conversation history and resends the full message array with each request. `zombied` holds no state between requests.
+
+### Request body
+
+```json
+{
+  "mode": "spec_init",
+  "messages": [
+    {
+      "role": "user",
+      "content": "Generate a spec template for: Add rate limiting per API key with Redis backend"
+    }
+  ],
+  "tools": [
+    {
+      "name": "read_file",
+      "description": "Read a file from the user's repo",
+      "input_schema": {
+        "type": "object",
+        "properties": { "path": { "type": "string" } },
+        "required": ["path"]
+      }
+    },
+    {
+      "name": "list_dir",
+      "description": "List directory contents",
+      "input_schema": {
+        "type": "object",
+        "properties": { "path": { "type": "string" } },
+        "required": ["path"]
+      }
+    },
+    {
+      "name": "glob",
+      "description": "Find files matching a glob pattern",
+      "input_schema": {
+        "type": "object",
+        "properties": { "pattern": { "type": "string" } },
+        "required": ["pattern"]
+      }
+    }
+  ]
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `mode` | string | yes | System prompt selector. One of: `spec_init`, `preview` |
+| `messages` | array | yes | Conversation history in Messages API format. CLI accumulates and resends with each request. |
+| `tools` | array | yes | Tool definitions. CLI sends read-only tools (read_file, list_dir, glob). |
+
+### Response
+
+`200 text/event-stream` — SSE stream with the following event types:
+
+**`tool_use`** — The model wants to call a tool. CLI should execute locally and send the result back.
+
+```
+event: tool_use
+data: {"id":"tu_01","name":"read_file","input":{"path":"go.mod"}}
+```
+
+**`text_delta`** — Streaming text from the model's response.
+
+```
+event: text_delta
+data: {"text":"# M5_001: Rate Limiting\n\n**Prototype:** v1.0.0\n"}
+```
+
+**`done`** — Stream complete. Includes usage and cost.
+
+```
+event: done
+data: {"usage":{"input_tokens":12450,"output_tokens":3200,"cost_usd":0.085,"provider":"anthropic","model":"claude-sonnet-4-6","round_trips":4}}
+```
+
+**`error`** — Provider error or timeout.
+
+```
+event: error
+data: {"message":"provider timeout after 30s"}
+```
+
+### Tool call round trip
+
+When the CLI receives a `tool_use` event:
+
+1. Execute the tool locally (read file from laptop, list directory, etc.)
+2. Append the assistant's `tool_use` message and the user's `tool_result` to the message history
+3. POST the updated messages to the same endpoint
+
+The loop continues until the model returns text (no more tool calls) and a `done` event.
+
+### Modes
+
+| Mode | System prompt behavior | Typical tool calls |
+|------|----------------------|-------------------|
+| `spec_init` | Explore the repo, detect language/ecosystem, generate a milestone spec | 3-5 (list root, read manifest, read Makefile, list src/) |
+| `preview` | Read the spec, explore the repo, predict which files will be touched | 4-8 (read spec, list directories, read key files, grep patterns) |
+
+### Provider resolution
+
+`zombied` resolves the LLM provider from workspace configuration. The CLI never specifies or sees the provider. Supported providers include Anthropic, OpenAI, Google, and user-supplied keys.
+
+### Security
+
+- Tool calls are executed by the CLI on the user's machine, not by `zombied`
+- The CLI validates all paths against the repo root before reading (prevents path traversal)
+- `zombied` has no filesystem awareness and never sees file contents directly
+- Files only leave the laptop one at a time when the model explicitly requests them
+
+### Errors
+
+| Status | Code | Meaning |
+|--------|------|---------|
+| 400 | `INVALID_MODE` | Unknown mode value |
+| 401 | `UNAUTHORIZED` | Missing or invalid auth token |
+| 403 | `FORBIDDEN` | Insufficient role for workspace |
+| 500 | — | SSE `event: error` emitted before stream closes |