docs: update for Docker-first deployment and dual license (#28)

* docs: update for Docker-first deployment and dual license

- Add Quick Start section to root README with docker run command
- Restructure docs/README.md: pre-built image first, build from source as alternative
- Update SDK README with gateway quick start and absolute GitHub links
- Update gateway README to mention both pre-built and source options
- Rename "Local Development" to "Building from Source" in docker-deployment.md
- Fix license references: dual-licensed (AGPL-3.0 or commercial)
- Update package.json license fields to "SEE LICENSE IN LICENSE"

* docs: add OpenAPI docs endpoint and scripts

- Update api-reference.md to reference /docs (Scalar UI) and /openapi.yaml
- Add openapi:generate and openapi:check scripts to CONTRIBUTING.md

* fix(test): make health route tests deterministic

Replace setTimeout with polling pattern that waits until spawn is
called before emitting mock events. Fixes flaky CI failures where
events fired before listeners were attached.

* fix(test): add timeout safeguard to afterSpawnCalled helper

Makes test failures clearer by throwing explicit error after ~1 second
instead of waiting for vitest's 10-second timeout.

Author: matthew-petty

CONTRIBUTING.md

@@ -6,9 +6,11 @@ We're eager for collaborators! This project is in early stages and there's plent
 
 ```bash
 bun install
-bun run dev      # Start gateway with hot reload
-bun run test     # Run tests
-bun run lint     # Lint check
+bun run dev              # Start gateway with hot reload
+bun run test             # Run tests
+bun run lint             # Lint check
+bun run openapi:generate # Regenerate OpenAPI spec
+bun run openapi:check    # Verify spec is up to date
 ```
 
 ## Pre-commit Hooks

README.md

@@ -40,6 +40,19 @@ Koine turns Claude Code into a programmable inference layer. Use it to:
 - **Run on internal networks** — VPN or Docker networks are ideal for service-to-service communication
 - **Authenticate all requests** — the gateway requires an API key separate from Claude authentication
 
+## Quick Start
+
+```bash
+docker run -d -p 3100:3100 \
+  -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
+  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  ghcr.io/pattern-zones-co/koine:latest
+
+curl http://localhost:3100/health
+```
+
+See [Docker Deployment](docs/docker-deployment.md) for version pinning, docker-compose setup, and production configuration.
+
 ## Documentation
 
 | Guide | Description |
@@ -61,7 +74,7 @@ Koine turns Claude Code into a programmable inference layer. Use it to:
 
 ## License
 
-See [LICENSE](LICENSE) for details (AGPL-3.0).
+Dual-licensed under AGPL-3.0 or commercial license. See [LICENSE](LICENSE) for details.
 
 ## Contributing
 

docs/README.md

@@ -11,20 +11,29 @@
 
 ## Getting Started
 
+```bash
+docker run -d -p 3100:3100 \
+  -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
+  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  ghcr.io/pattern-zones-co/koine:latest
+
+curl http://localhost:3100/health
+```
+
+See [Docker Deployment](docker-deployment.md) for docker-compose setup, version pinning, and production configuration.
+
+### From Source
+
+Alternatively, clone and build from source:
+
 ```bash
 git clone https://github.com/pattern-zones-co/koine.git
 cd koine
 
 cp .env.example .env
 # Edit .env with your keys
 
-docker compose up -d koine
-```
-
-Verify it's running:
-
-```bash
-curl http://localhost:3100/health
+docker compose up -d
 ```
 
 ### Usage

docs/api-reference.md

@@ -1,6 +1,6 @@
 # API Reference
 
-> **TODO**: Generate OpenAPI spec from Zod schemas. See [#17](https://github.com/pattern-zones-co/koine/issues/17).
+The gateway provides interactive API documentation at [`/docs`](http://localhost:3100/docs) powered by [Scalar](https://scalar.com/). The raw OpenAPI 3.1 specification is available at [`/openapi.yaml`](http://localhost:3100/openapi.yaml).
 
 ## Authentication
 
@@ -16,6 +16,8 @@ curl -H "Authorization: Bearer $CLAUDE_CODE_GATEWAY_API_KEY" \
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/health` | Health check (no auth) |
+| GET | `/docs` | Interactive API docs (no auth) |
+| GET | `/openapi.yaml` | OpenAPI spec (no auth) |
 | POST | `/generate-text` | Generate text |
 | POST | `/generate-object` | Extract structured JSON |
 | POST | `/stream` | Stream via SSE |

docs/docker-deployment.md

@@ -32,15 +32,15 @@ Available version formats:
 - `1` - Latest minor/patch of major version
 - `latest` - Most recent release (default)
 
-## Local Development
+## Building from Source
 
 Build from source using the dev profile:
 
 ```bash
 docker compose --profile dev up --build
 ```
 
-This uses `koine-dev` service which builds locally from the Dockerfile.
+This uses the `koine-dev` service which builds locally from the Dockerfile. See [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup.
 
 ## Configuration
 

packages/gateway/README.md

@@ -2,20 +2,19 @@
 
 HTTP gateway that exposes [Claude Code CLI](https://github.com/anthropics/claude-code) as a REST API.
 
-This package is not published to npm. Deploy via Docker from the [repository root](../../README.md).
+This package is not published to npm. Deploy via Docker (pre-built or from source).
 
-## Deployment
+## Quick Start
 
 ```bash
-git clone https://github.com/pattern-zones-co/koine.git
-cd koine
-
-cp .env.example .env
-# Edit .env with your keys
-
-docker compose up -d koine
+docker run -d -p 3100:3100 \
+  -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
+  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  ghcr.io/pattern-zones-co/koine:latest
 ```
 
+See [Docker Deployment](../../docs/docker-deployment.md) for docker-compose setup, version pinning, and production configuration.
+
 ## Documentation
 
 - [Getting Started](../../docs/README.md)

packages/gateway/__tests__/routes/health.test.ts

@@ -11,6 +11,24 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import healthRouter from "../../src/routes/health.js";
 import { createMockChildProcess } from "../helpers.js";
 
+/** Schedule callback after spawn is called (non-blocking) */
+function afterSpawnCalled(
+	mockSpawn: ReturnType<typeof vi.fn>,
+	callback: () => void,
+): void {
+	let iterations = 0;
+	const check = () => {
+		if (mockSpawn.mock.calls.length > 0) {
+			callback();
+		} else if (iterations++ < 1000) {
+			setTimeout(check, 1);
+		} else {
+			throw new Error("Timeout waiting for spawn to be called");
+		}
+	};
+	check();
+}
+
 // Mock node:child_process
 vi.mock("node:child_process", () => ({
 	spawn: vi.fn(),
@@ -42,11 +60,11 @@ describe("Health Route", () => {
 			const app = createTestApp();
 			const responsePromise = request(app).get("/health");
 
-			// Simulate successful claude --version
-			setTimeout(() => {
+			// Simulate successful claude --version after spawn is called
+			afterSpawnCalled(mockSpawn, () => {
 				mockProc.exitCode = 0;
 				mockProc.emit("close", 0, null);
-			}, 10);
+			});
 
 			const res = await responsePromise;
 
@@ -65,11 +83,11 @@ describe("Health Route", () => {
 			const app = createTestApp();
 			const responsePromise = request(app).get("/health");
 
-			// Simulate failed claude --version
-			setTimeout(() => {
+			// Simulate failed claude --version after spawn is called
+			afterSpawnCalled(mockSpawn, () => {
 				mockProc.exitCode = 1;
 				mockProc.emit("close", 1, null);
-			}, 10);
+			});
 
 			const res = await responsePromise;
 
@@ -88,10 +106,10 @@ describe("Health Route", () => {
 			const app = createTestApp();
 			const responsePromise = request(app).get("/health");
 
-			// Simulate spawn error (e.g., command not found)
-			setTimeout(() => {
+			// Simulate spawn error (e.g., command not found) after spawn is called
+			afterSpawnCalled(mockSpawn, () => {
 				mockProc.emit("error", new Error("ENOENT"));
-			}, 10);
+			});
 
 			const res = await responsePromise;
 
@@ -107,10 +125,10 @@ describe("Health Route", () => {
 			const responsePromise = request(app).get("/health");
 
 			// Simulate successful response so the request completes
-			setTimeout(() => {
+			afterSpawnCalled(mockSpawn, () => {
 				mockProc.exitCode = 0;
 				mockProc.emit("close", 0, null);
-			}, 10);
+			});
 
 			await responsePromise;
 
@@ -155,10 +173,10 @@ describe("Health Route", () => {
 			const responsePromise = request(app).get("/health");
 
 			// CLI completes successfully - this should cancel the 5s timeout
-			setTimeout(() => {
+			afterSpawnCalled(mockSpawn, () => {
 				mockProc.exitCode = 0;
 				mockProc.emit("close", 0, null);
-			}, 10);
+			});
 
 			const res = await responsePromise;
 

packages/gateway/package.json

@@ -49,17 +49,7 @@
 		"node": "22.21.1",
 		"bun": "1.3.3"
 	},
-	"keywords": [
-		"claude",
-		"claude-code",
-		"anthropic",
-		"ai",
-		"gateway",
-		"api"
-	],
-	"license": "AGPL-3.0",
-	"files": [
-		"dist",
-		"README.md"
-	]
+	"keywords": ["claude", "claude-code", "anthropic", "ai", "gateway", "api"],
+	"license": "SEE LICENSE IN LICENSE",
+	"files": ["dist", "README.md"]
 }

packages/sdks/typescript/README.md

@@ -1,6 +1,17 @@
 # @patternzones/koine-sdk
 
-TypeScript SDK for [Koine](../../../README.md) — the HTTP gateway for Claude Code CLI.
+TypeScript SDK for [Koine](https://github.com/pattern-zones-co/koine) — the HTTP gateway for Claude Code CLI.
+
+## Running the Gateway
+
+```bash
+docker run -d -p 3100:3100 \
+  -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
+  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  ghcr.io/pattern-zones-co/koine:latest
+```
+
+See [Docker Deployment](https://github.com/pattern-zones-co/koine/blob/main/docs/docker-deployment.md) for version pinning and production setup.
 
 ## Installation
 
@@ -57,7 +68,7 @@ console.log(result.text);
 
 ## Documentation
 
-See the [SDK Guide](../../../docs/sdk-guide.md) for:
+See the [SDK Guide](https://github.com/pattern-zones-co/koine/blob/main/docs/sdk-guide.md) for:
 
 - Configuration options
 - Streaming examples
@@ -67,4 +78,4 @@ See the [SDK Guide](../../../docs/sdk-guide.md) for:
 
 ## License
 
-[AGPL-3.0](../../../LICENSE)
+Dual-licensed under [AGPL-3.0 or commercial license](https://github.com/pattern-zones-co/koine/blob/main/LICENSE).

packages/sdks/typescript/package.json

@@ -42,17 +42,7 @@
 		"node": "22.21.1",
 		"bun": "1.3.3"
 	},
-	"keywords": [
-		"claude",
-		"claude-code",
-		"anthropic",
-		"ai",
-		"sdk",
-		"gateway"
-	],
-	"license": "AGPL-3.0",
-	"files": [
-		"dist",
-		"README.md"
-	]
+	"keywords": ["claude", "claude-code", "anthropic", "ai", "sdk", "gateway"],
+	"license": "SEE LICENSE IN LICENSE",
+	"files": ["dist", "README.md"]
 }