swadhin / justapi public

docs: add Inference section (4 pages) to docs site

swadhinbiswas committed 3 months ago

5fd913d

1 parent 5421d21

commit 5fd913d

6 files changed

+1568 -0

Files

docs_site

src

content

docs

inference

gpu-cuda-setup.md +87 llm-serving-api.md +149 overview.md +100 scheduling-batching.md +116 astro.config.mjs +9 docsplan.md +1107

Showing 6 changed files+1568-0

docs_site/astro.config.mjs docs_site/src/content/docs/inference/gpu-cuda-setup.md docs_site/src/content/docs/inference/llm-serving-api.md docs_site/src/content/docs/inference/overview.md docs_site/src/content/docs/inference/scheduling-batching.md docsplan.md

▼docs_site/astro.config.mjs

+9-0

@@ -100,6 +100,15 @@ export default defineConfig({
100	100	{ label: 'Resilience Patterns', link: 'advanced/resilience-patterns/' },
101	101	],
102	102	},
	103	+ {
	104	+ label: 'Inference',
	105	+ items: [
	106	+ { label: 'Overview', link: 'inference/overview/' },
	107	+ { label: 'LLM Serving API', link: 'inference/llm-serving-api/' },
	108	+ { label: 'GPU & CUDA Setup', link: 'inference/gpu-cuda-setup/' },
	109	+ { label: 'Scheduling & Batching', link: 'inference/scheduling-batching/' },
	110	+ ],
	111	+ },
103	112	{
104	113	label: 'Deployment',
105	114	items: [
106	115

▼docs_site/src/content/docs/inference/gpu-cuda-setup.md

+87-0

@@ -0,0 +1,87 @@
	1	+---
	2	+title: GPU & CUDA Configuration
	3	+description: Configure GPU acceleration for LLM inference with CUDA.
	4	+---
	5	+
	6	+> Note: GPU inference is feature-gated behind `cuda` and `real` features. Real GPU benchmarks are deferred to the 2.0.8 release (ADR-067). Structural CPU benchmarks pass.
	7	+
	8	+## Building with CUDA Support
	9	+
	10	+```bash
	11	+# Install CUDA toolkit (requires CUDA 12.x)
	12	+# Then build with CUDA features
	13	+cargo build --release --features "cuda,real"
	14	+
	15	+# Or with the bench harness
	16	+cargo build --release -p justapi-bench --features cuda
	17	+```
	18	+
	19	+## Running on GPU
	20	+
	21	+```bash
	22	+justapi serve --model my-model.gguf --gpu
	23	+```
	24	+
	25	+## GPU Memory Management
	26	+
	27	+The inference engine uses PagedAttention for efficient GPU memory utilization:
	28	+
	29	+```bash
	30	+justapi serve --model my-model.gguf --gpu \
	31	+ --pool-blocks 8192 \ # Total KV-cache blocks
	32	+ --max-seqs 64 # Maximum concurrent sequences
	33	+```
	34	+
	35	+### Block Pool Configuration
	36	+
	37	+\| Flag \| Default \| Description \|
	38	+\|---\|---\|---\|
	39	+\| `--pool-blocks` \| `4096` \| Total blocks in the KV-cache pool \|
	40	+\| `--block-size` \| `16` \| Tokens per block \|
	41	+\| `--max-seqs` \| `32` \| Maximum concurrent sequences \|
	42	+
	43	+### Memory Calculation
	44	+
	45	+Total KV-cache memory = `pool_blocks * block_size * num_layers * 2 * dtype_size`
	46	+
	47	+For a 7B model with 32 layers, 16 block size, 4096 blocks:
	48	+
	49	+```
	50	+4096 * 16 * 32 * 2 * 2 bytes (FP16) = 8 GB
	51	+```
	52	+
	53	+## Multi-GPU
	54	+
	55	+Multi-GPU support is in development. Currently, models are loaded on a single GPU.
	56	+
	57	+## Quantization
	58	+
	59	+JustAPI supports several quantization formats through GGUF:
	60	+
	61	+\| Format \| Bits \| Description \|
	62	+\|---\|---\|---\|
	63	+\| `FP16` \| 16 \| Full precision \|
	64	+\| `Q4_0` \| 4 \| 4-bit quants, no grouping \|
	65	+\| `Q4_K_M` \| 4 \| 4-bit with medium grouping \|
	66	+\| `Q5_K_M` \| 5 \| 5-bit with medium grouping \|
	67	+\| `Q8_0` \| 8 \| 8-bit quants \|
	68	+
	69	+```bash
	70	+justapi serve --model model-q4_k_m.gguf --gpu
	71	+```
	72	+
	73	+## LoRA Adapters
	74	+
	75	+```bash
	76	+justapi serve --model base-model.gguf --gpu \
	77	+ --lora adapter.safetensors \
	78	+ --lora-scale 0.8
	79	+```
	80	+
	81	+Multiple LoRAs can be loaded and swapped at runtime via the control plane API.
	82	+
	83	+## See Also
	84	+
	85	+- [Inference Overview](/inference/overview/) — Architecture and components
	86	+- [LLM Serving API](/inference/llm-serving-api/) — API endpoints
	87	+- [Scheduling & Batching](/inference/scheduling-batching/) — Performance optimization
0	88

▼docs_site/src/content/docs/inference/llm-serving-api.md

+149-0

@@ -0,0 +1,149 @@
	1	+---
	2	+title: LLM Serving API
	3	+description: OpenAI-compatible API endpoints for LLM inference.
	4	+---
	5	+
	6	+When the `inference` feature is enabled, JustAPI exposes an OpenAI-compatible API for LLM serving.
	7	+
	8	+## Enabling Inference
	9	+
	10	+```bash
	11	+# Build with inference support
	12	+cargo build --release --features inference
	13	+
	14	+# Run with a model
	15	+justapi serve --model my-model.gguf
	16	+```
	17	+
	18	+## Chat Completions
	19	+
	20	+```http
	21	+POST /v1/chat/completions
	22	+Content-Type: application/json
	23	+
	24	+{
	25	+ "model": "my-model",
	26	+ "messages": [
	27	+ {"role": "system", "content": "You are a helpful assistant."},
	28	+ {"role": "user", "content": "What is Rust?"}
	29	+ ],
	30	+ "temperature": 0.7,
	31	+ "max_tokens": 256,
	32	+ "stream": false
	33	+}
	34	+```
	35	+
	36	+### Response
	37	+
	38	+```json
	39	+{
	40	+ "id": "chatcmpl-123",
	41	+ "object": "chat.completion",
	42	+ "created": 1721827200,
	43	+ "model": "my-model",
	44	+ "choices": [
	45	+ {
	46	+ "index": 0,
	47	+ "message": {
	48	+ "role": "assistant",
	49	+ "content": "Rust is a systems programming language..."
	50	+ },
	51	+ "finish_reason": "stop"
	52	+ }
	53	+ ],
	54	+ "usage": {
	55	+ "prompt_tokens": 24,
	56	+ "completion_tokens": 58,
	57	+ "total_tokens": 82
	58	+ }
	59	+}
	60	+```
	61	+
	62	+### Streaming
	63	+
	64	+```http
	65	+POST /v1/chat/completions
	66	+Content-Type: application/json
	67	+
	68	+{
	69	+ "model": "my-model",
	70	+ "messages": [{"role": "user", "content": "Count to 5."}],
	71	+ "stream": true
	72	+}
	73	+```
	74	+
	75	+Streaming response (SSE):
	76	+
	77	+```
	78	+data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
	79	+
	80	+data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1"},"finish_reason":null}]}
	81	+
	82	+data: {"id":"chatcmpl-123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"2"},"finish_reason":null}]}
	83	+
	84	+data: [DONE]
	85	+```
	86	+
	87	+## Completions
	88	+
	89	+```http
	90	+POST /v1/completions
	91	+Content-Type: application/json
	92	+
	93	+{
	94	+ "model": "my-model",
	95	+ "prompt": "Once upon a time,",
	96	+ "max_tokens": 100,
	97	+ "temperature": 0.8
	98	+}
	99	+```
	100	+
	101	+## Embeddings
	102	+
	103	+```http
	104	+POST /v1/embeddings
	105	+Content-Type: application/json
	106	+
	107	+{
	108	+ "model": "my-model",
	109	+ "input": "The quick brown fox jumps over the lazy dog"
	110	+}
	111	+```
	112	+
	113	+## Model Management
	114	+
	115	+```http
	116	+GET /v1/models
	117	+```
	118	+
	119	+```json
	120	+{
	121	+ "object": "list",
	122	+ "data": [
	123	+ {
	124	+ "id": "my-model",
	125	+ "object": "model",
	126	+ "created": 1721827200,
	127	+ "owned_by": "justapi"
	128	+ }
	129	+ ]
	130	+}
	131	+```
	132	+
	133	+## Sampling Parameters
	134	+
	135	+\| Parameter \| Type \| Default \| Description \|
	136	+\|---\|---\|---\|---\|
	137	+\| `temperature` \| float \| `1.0` \| Sampling temperature \|
	138	+\| `top_p` \| float \| `1.0` \| Nucleus sampling threshold \|
	139	+\| `top_k` \| int \| `40` \| Top-k sampling \|
	140	+\| `max_tokens` \| int \| `256` \| Maximum tokens to generate \|
	141	+\| `stop` \| list[str] \| `[]` \| Stop sequences \|
	142	+\| `presence_penalty` \| float \| `0.0` \| Penalize new tokens \|
	143	+\| `frequency_penalty` \| float \| `0.0` \| Penalize frequent tokens \|
	144	+
	145	+## See Also
	146	+
	147	+- [Inference Overview](/inference/overview/) — Architecture and components
	148	+- [GPU & CUDA Setup](/inference/gpu-cuda-setup/) — Hardware configuration
	149	+- [Scheduling & Batching](/inference/scheduling-batching/) — Performance optimization
0	150

▼docs_site/src/content/docs/inference/overview.md

+100-0

@@ -0,0 +1,100 @@
	1	+---
	2	+title: Inference Engine Overview
	3	+description: JustAPI's native Rust inference engine for LLM serving.
	4	+---
	5	+
	6	+JustAPI includes a Rust-native inference engine (`justapi-inference`) built on the [Candle](https://github.com/huggingface/candle) ML framework. It provides efficient LLM serving with continuous batching, PagedAttention KV-cache, prefix caching, and speculative decoding.
	7	+
	8	+> Status: The inference engine is feature-complete but frozen pending the 2.0.8 release (ADR-067). GPU benchmarks with real weights are deferred. CPU-based structural benchmarks pass.
	9	+
	10	+## Architecture
	11	+
	12	+```
	13	+┌───────────────────────────────────────────────┐
	14	+│ Control Plane │
	15	+│ Model Registry \| Versioning \| Autoscaler │
	16	+└──────────────────┬────────────────────────────┘
	17	+ │
	18	+┌──────────────────▼────────────────────────────┐
	19	+│ Router/Gateway │
	20	+│ Route by model \| KV-pressure \| TTFT │
	21	+└──────────────────┬────────────────────────────┘
	22	+ │
	23	+┌──────────────────▼────────────────────────────┐
	24	+│ Scheduler Engine │
	25	+│ Continuous Batching \| Prefill/Decode │
	26	+│ Prefix Cache \| Back-pressure │
	27	+└──────────────────┬────────────────────────────┘
	28	+ │
	29	+┌──────────────────▼────────────────────────────┐
	30	+│ KV Cache Manager │
	31	+│ PagedAttention \| Block Pool \| Eviction │
	32	+└──────────────────┬────────────────────────────┘
	33	+ │
	34	+┌──────────────────▼────────────────────────────┐
	35	+│ Model Engine │
	36	+│ Candle (CPU/CUDA) \| Quantization \| LoRA │
	37	+└───────────────────────────────────────────────┘
	38	+```
	39	+
	40	+## Key Components
	41	+
	42	+### Engine
	43	+The core model execution layer. Supports CPU and CUDA backends via Candle. Models are loaded from HuggingFace format or GGUF quantized files.
	44	+
	45	+### Scheduler
	46	+Continuous batching scheduler that interleaves prefill and decode steps for maximum throughput. Integrates with the prefix cache for KV-cache reuse.
	47	+
	48	+### KV Cache (PagedAttention)
	49	+Page-based KV-cache allocation that eliminates fragmentation. Uses a block pool allocator with clock eviction for efficient memory management.
	50	+
	51	+### Prefix Cache (RadixAttention)
	52	+Radix-tree based prefix cache that reuses KV-cache prefixes across requests, significantly reducing prefill time for common prompt prefixes.
	53	+
	54	+### Speculative Decoding
	55	+Draft-target verification for 2-3x higher acceptance rates. Supports both single-token and tree-based speculation (Medusa/EAGLE style).
	56	+
	57	+### Control Plane
	58	+Model registry, versioning, autoscaler, and multi-replica supervisor for production LLM deployments.
	59	+
	60	+## Crate Structure
	61	+
	62	+The inference engine lives in `crates/justapi-inference/`:
	63	+
	64	+\| Module \| Description \|
	65	+\|---\|---\|
	66	+\| `engine` \| Model loading and inference execution \|
	67	+\| `scheduler` \| Continuous batching scheduler \|
	68	+\| `scheduler_engine` \| Integration layer between Engine and Scheduler \|
	69	+\| `kv_cache` \| PagedAttention KV-cache manager \|
	70	+\| `radix_cache` \| Radix-tree prefix cache \|
	71	+\| `pd` \| Disaggregated prefill/decode scheduler \|
	72	+\| `spec_decode` \| Single-token speculative decoding \|
	73	+\| `spec_decode_tree` \| Tree-based speculative decoding (Medusa/EAGLE) \|
	74	+\| `control_plane` \| Model registry, versioning, autoscaler \|
	75	+\| `gateway` \| Inference gateway for routing \|
	76	+\| `router` \| Model-aware request router \|
	77	+\| `supervisor` \| Multi-replica model supervisor \|
	78	+\| `openai` \| OpenAI-compatible API types \|
	79	+\| `real` \| Real-weight model loading (quant, LoRA) \|
	80	+
	81	+## OpenAI-Compatible API
	82	+
	83	+When the inference feature is enabled, JustAPI serves an OpenAI-compatible API:
	84	+
	85	+\| Endpoint \| Description \|
	86	+\|---\|---\|
	87	+\| `POST /v1/chat/completions` \| Chat completions with streaming \|
	88	+\| `POST /v1/completions` \| Text completions \|
	89	+\| `POST /v1/embeddings` \| Embeddings \|
	90	+\| `GET /v1/models` \| List available models \|
	91	+
	92	+## Status
	93	+
	94	+The inference engine is fully implemented and structurally benchmarked. Real GPU validation with actual model weights is deferred to the 2.0.8 release cycle.
	95	+
	96	+## See Also
	97	+
	98	+- [LLM Serving API](/reference/inference/llm-serving-api/) — OpenAI-compatible endpoints
	99	+- [GPU & CUDA Setup](/reference/inference/gpu-cuda-setup/) — Hardware configuration
	100	+- [Scheduling & Batching](/reference/inference/scheduling-batching/) — Performance optimization
0	101

▼docs_site/src/content/docs/inference/scheduling-batching.md

+116-0

@@ -0,0 +1,116 @@
	1	+---
	2	+title: Scheduling & Batching
	3	+description: Continuous batching and scheduling strategies for LLM inference.
	4	+---
	5	+
	6	+JustAPI's inference scheduler implements continuous batching, prefix caching, and disaggregated prefill/decode for maximum LLM throughput.
	7	+
	8	+## Continuous Batching
	9	+
	10	+Unlike static batching (wait for all sequences to finish), continuous batching interleaves prefill and decode steps:
	11	+
	12	+```
	13	+Time → \|--- Batch 1 (prefill) ---\|---- Batch 1 (decode) ----\|
	14	+ \|--- Batch 2 (prefill) ---\|---- Batch 2 (decode) ----\|
	15	+ \|--- Batch 3 (prefill) ---\|
	16	+```
	17	+
	18	+This eliminates the "wait for straggler" problem and maximizes GPU utilization.
	19	+
	20	+## Scheduler Configuration
	21	+
	22	+```bash
	23	+justapi serve --model my-model.gguf \
	24	+ --max-seqs 64 \ # Max concurrent sequences
	25	+ --pool-blocks 8192 \ # KV-cache pool size
	26	+ --scheduled # Use continuous batching scheduler
	27	+```
	28	+
	29	+### Scheduler Parameters
	30	+
	31	+\| Parameter \| Default \| Description \|
	32	+\|---\|---\|---\|
	33	+\| `max_seqs` \| `32` \| Maximum concurrent sequences \|
	34	+\| `max_prefill` \| `4` \| Maximum concurrent prefills \|
	35	+\| `max_decode` \| `32` \| Maximum concurrent decodes \|
	36	+\| `chunk_size` \| `512` \| Prefill chunk size (tokens) \|
	37	+
	38	+## Prefill/Decode Disaggregation
	39	+
	40	+The disaggregated scheduler (`PdScheduler`) separates prefill and decode onto dedicated resource pools:
	41	+
	42	+- Prefill pool: Handles prompt processing (compute-bound)
	43	+- Decode pool: Handles token generation (memory-bound)
	44	+
	45	+```
	46	+┌──────────────┐ ┌──────────────┐
	47	+│ Prefill Pool │ │ Decode Pool │
	48	+│ (GPU batch) │───▶│ (GPU batch) │
	49	+└──────────────┘ └──────────────┘
	50	+```
	51	+
	52	+This prevents decode starvation during heavy prefill loads.
	53	+
	54	+## Prefix Caching (RadixAttention)
	55	+
	56	+The radix prefix cache (`RadixPrefixCache`) reuses KV-cache prefixes across requests:
	57	+
	58	+```
	59	+Request 1: "What is the capital of France?"
	60	+Request 2: "What is the capital of Germany?"
	61	+ └─────────────────┘
	62	+ Shared prefix: "What is the capital of"
	63	+```
	64	+
	65	+The shared prefix is computed once and reused, saving prefill computation.
	66	+
	67	+### Cache Statistics
	68	+
	69	+The `/metrics` endpoint exposes prefix cache statistics:
	70	+
	71	+\| Metric \| Description \|
	72	+\|---\|---\|
	73	+\| `prefix_cache_hits` \| Number of prefix cache hits \|
	74	+\| `prefix_cache_misses` \| Number of prefix cache misses \|
	75	+\| `prefix_cache_hit_ratio` \| Hit ratio (hits / total) \|
	76	+\| `prefix_cache_blocks` \| Currently cached blocks \|
	77	+
	78	+## Speculative Decoding
	79	+
	80	+### Single-Token Speculation
	81	+
	82	+A smaller draft model proposes tokens, and the target model verifies them in parallel:
	83	+
	84	+```
	85	+Draft: [a] [b] [c] [d]
	86	+Target: ✓ ✓ ✗ —
	87	+Accepted: [a] [b] [c] → then resample
	88	+```
	89	+
	90	+### Tree-Based Speculation (Medusa/EAGLE)
	91	+
	92	+The tree-based decoder (`spec_decode_tree`) constructs a draft tree and verifies multiple branches simultaneously:
	93	+
	94	+```bash
	95	+justapi serve --model my-model.gguf \
	96	+ --gamma 4 \ # Speculation window size
	97	+ --branch 2 # Tree branching factor
	98	+```
	99	+
	100	+## CLI Configuration for Inference
	101	+
	102	+```bash
	103	+justapi serve --model llama-7b.gguf \
	104	+ --gpu \
	105	+ --scheduled \
	106	+ --max-seqs 64 \
	107	+ --pool-blocks 4096 \
	108	+ --gamma 4 \
	109	+ --branch 2
	110	+```
	111	+
	112	+## See Also
	113	+
	114	+- [Inference Overview](/inference/overview/) — Architecture and components
	115	+- [LLM Serving API](/inference/llm-serving-api/) — API endpoints
	116	+- [GPU & CUDA Setup](/inference/gpu-cuda-setup/) — Hardware configuration
0	117

▼docsplan.md

+1107-0

@@ -0,0 +1,1107 @@
	1	+# JustAPI Documentation Site — Production-Grade Build Plan
	2	+
	3	+> Goal: Build a comprehensive, production-grade documentation site (Astro + Starlight) covering every aspect of the JustAPI runtime — matching the depth, polish, and discoverability of FastAPI, Next.js, and Django docs.
	4	+>
	5	+> Current state (2026-07-24): `docs_site/` exists with Astro + Starlight but has only 10 pages covering 20% of the framework surface. `docs/` has 7 raw markdown files capturing the handbook, API reference, security, and migration guide. The full codebase has 5 Rust crates, ~40 public modules, 33 benchmark scripts, 12 examples, 13 test files, 8 fuzz targets, 5 cloud deployment guides, Helm chart, Docker setup, and agent-native demo.
	6	+
	7	+---
	8	+
	9	+## Phase 0: Site Infrastructure & Design System
	10	+
	11	+### 0.1 Framework & Theme
	12	+\| Item \| Current \| Target \|
	13	+\|---\|---\|---\|
	14	+\| SSG framework \| Astro 7 + Starlight 0.41 \| Astro 7 + Starlight 0.41 (upgrade if newer) \|
	15	+\| Theme colors \| Purple accent (`#8B5CF6`) \| Keep — already distinctive. Add light/dark mode refinement \|
	16	+\| Custom CSS \| `src/styles/custom.css` (34 lines) \| Expand to full design system \|
	17	+\| Logo \| `src/assets/logo.svg` (bolt/gradient) \| Keep — refine for docs page prominence \|
	18	+\| Font \| Default Starlight \| Add system font stack + optional mono for code \|
	19	+\| Search \| Starlight built-in (Pagefind) \| Already works — configure pagefind for full-text + section search \|
	20	+
	21	+### 0.2 Navigation Architecture
	22	+Current sidebar only has 2 autogenerated sections. Replace with explicit, hierarchical navigation:
	23	+
	24	+```
	25	+Getting Started [existing, expand]
	26	+├── Overview & Philosophy ✓ exists
	27	+├── Installation ✓ exists
	28	+├── First Steps ✓ exists
	29	+├── CLI Project Scaffolder ✓ exists
	30	+└── Migrating from FastAPI ✗ missing (exists in docs/)
	31	+
	32	+Tutorials ✗ missing
	33	+├── Hello World in 2 Minutes ✗ missing
	34	+├── Path & Query Parameters ✓ exists (path-params.md)
	35	+├── Request Body & Validation ✗ missing
	36	+├── Dependency Injection ✗ missing
	37	+├── Middleware ✗ missing
	38	+├── Error Handling ✗ missing
	39	+├── File Uploads ✗ missing
	40	+├── WebSockets & SSE ✗ missing
	41	+├── Database Integration ✓ exists (databases.md)
	42	+└── Background Tasks ✗ missing
	43	+
	44	+API Reference ✗ missing
	45	+├── JustAPIApp ✗ missing
	46	+├── Routing (GET/POST/PUT/...)✗ missing
	47	+├── APIRouter ✗ missing
	48	+├── Dependency Injection ✗ missing
	49	+├── Request Object ✗ missing
	50	+├── Response Classes ✗ missing
	51	+├── Exceptions & Error Handling ✗ missing
	52	+├── Schema & Validation ✗ missing
	53	+├── WebSockets ✗ missing
	54	+├── Background Tasks ✗ missing
	55	+├── Scheduler ✗ missing
	56	+├── Testing Client ✗ missing
	57	+└── Plugins ✗ missing
	58	+
	59	+Advanced Guides ✗ missing
	60	+├── Zero-GIL Architecture ✓ exists
	61	+├── Rust Core Deep Dive ✗ missing
	62	+├── FFI & PyO3 Safety ✗ missing
	63	+├── Native Fast Path ✗ missing
	64	+├── Multi-Protocol APIs ✗ missing
	65	+├── Agent/Session System ✗ missing
	66	+├── Streaming Output ✗ missing
	67	+└── Performance Tuning ✗ missing
	68	+
	69	+Deployment Guides ✗ missing
	70	+├── Docker & Docker Compose ✗ missing
	71	+├── Kubernetes / Helm ✗ missing
	72	+├── Cloudflare Pages ✓ exists
	73	+├── Google Cloud (GKE) ✗ missing (exists in deploy/)
	74	+├── Amazon (EKS) ✗ missing (exists in deploy/)
	75	+├── Azure (AKS) ✗ missing (exists in deploy/)
	76	+├── Fly.io ✗ missing (exists in deploy/)
	77	+└── Railway ✗ missing (exists in deploy/)
	78	+
	79	+Security ✗ missing
	80	+├── Security Policy ✗ missing (exists in docs/)
	81	+├── OWASP Compliance Checklist ✗ missing (exists in docs/)
	82	+├── Penetration Test Guide ✗ missing (exists in docs/)
	83	+└── Secure Configuration ✗ missing
	84	+
	85	+Observability ✗ missing
	86	+├── Metrics & Monitoring ✗ missing
	87	+├── OpenTelemetry Tracing ✗ missing
	88	+├── Structured Logging ✗ missing
	89	+└── Health Checks ✗ missing
	90	+
	91	+Reference ✗ missing
	92	+├── CLI Reference ✗ missing
	93	+├── Configuration Reference ✗ missing
	94	+├── Release Notes ✓ exists (release-notes.md)
	95	+├── Changelog ✗ missing
	96	+└── Glossary ✗ missing
	97	+
	98	+Contributing ✗ missing
	99	+├── Development Setup ✗ missing
	100	+├── Coding Standards ✗ missing
	101	+├── Testing Guide ✗ missing
	102	+├── Benchmarking Guide ✗ missing
	103	+└── Documentation Guide ✗ missing
	104	+```
	105	+
	106	+### 0.3 SEO & Performance
	107	+- Add sitemap (`@astrojs/sitemap`)
	108	+- Add OpenGraph + Twitter card meta tags to every page
	109	+- Configure canonical URLs
	110	+- Enable Pagefind full-text search with section headings
	111	+- Add 301 redirects for old `docs/*.md` URLs
	112	+- Add RSS feed for release notes (`@astrojs/rss`)
	113	+- Lighthouse target: 100/100 all categories
	114	+
	115	+---
	116	+
	117	+## Phase 1: Getting Started (5 pages — 1 new, 4 enhance existing)
	118	+
	119	+### 1.1 Overview & Core Philosophy ✓ (enhance)
	120	+Existing: `getting-started/overview.md` (minimal, 2 sections)
	121	+Enhance:
	122	+- Add architecture diagram (Mermaid)
	123	+- Add performance comparison table from BENCHMARKS.md
	124	+- Add feature comparison matrix vs FastAPI / Robyn / Granian
	125	+- Add "Who is this for?" audience section
	126	+- Add system requirements (Python 3.11+, Rust 1.85+)
	127	+
	128	+### 1.2 Installation ✓ (enhance)
	129	+Existing: `getting-started/installation.md`
	130	+Enhance:
	131	+- Add troubleshooting section for common install failures
	132	+- Add platform-specific notes (Windows, macOS, Linux)
	133	+- Add Docker installation method
	134	+- Add `justapi[full]` extras documentation
	135	+- Add verification steps (`python -c "import justapi; print(justapi.__version__)"`)
	136	+- Add free-threaded Python 3.13t/3.14t installation notes
	137	+
	138	+### 1.3 First Steps ✓ (enhance)
	139	+Existing: `getting-started/first-steps.md`
	140	+Enhance:
	141	+- Add step-by-step walkthrough with expected output
	142	+- Add interactive OpenAPI docs section (Swagger, ReDoc, Scalar)
	143	+- Add "What's happening under the hood?" callout boxes
	144	+- Add common gotchas section
	145	+
	146	+### 1.4 CLI Project Scaffolder ✓ (enhance)
	147	+Existing: `getting-started/cli-scaffolder.md`
	148	+Enhance:
	149	+- Add complete CLI reference for `justapi create`
	150	+- Add generated project structure documentation
	151	+- Add screenshots of interactive TUI wizard
	152	+- Add video/gif of scaffolding flow
	153	+- Add multi-protocol explanation (when to use REST vs GraphQL vs gRPC vs JSON-RPC)
	154	+
	155	+### 1.5 ✨ NEW: Migrating from FastAPI
	156	+Source: `docs/migrating_from_fastapi.md`
	157	+Enhance from existing:
	158	+- Add import mapping table (full `fastapi.` → `justapi.`)
	159	+- Add decorator compatibility table
	160	+- Add middleware migration guide
	161	+- Add dependency injection migration
	162	+- Add performance expectations after migration
	163	+- Add common migration pitfalls
	164	+- Add side-by-side code comparisons for every feature
	165	+
	166	+---
	167	+
	168	+## Phase 2: Tutorials (11 pages — 1 existing, 10 new)
	169	+
	170	+### 2.1 ✨ NEW: Hello World in 2 Minutes
	171	+Based on `examples/01_hello_world.py`:
	172	+- Complete walkthrough from zero to running
	173	+- Expected terminal output
	174	+- Testing with curl
	175	+- Project structure discussion
	176	+
	177	+### 2.2 Path & Query Parameters ✓ (enhance)
	178	+Existing: `tutorial/path-params.md`
	179	+Enhance:
	180	+- Add query parameters tutorial
	181	+- Add optional vs required parameters
	182	+- Add default values
	183	+- Add type conversion table (int, float, str, bool, UUID, datetime)
	184	+- Add validation error examples
	185	+- Based on `examples/02_path_query_params.py`
	186	+
	187	+### 2.3 ✨ NEW: Request Body & Validation
	188	+Based on `examples/03_request_body.py`:
	189	+- Pydantic BaseModel usage
	190	+- Schema validation with `body_schema` parameter
	191	+- Nested models
	192	+- Optional fields and defaults
	193	+- Native fast path (`native=True`) explanation
	194	+- Request body size limits
	195	+
	196	+### 2.4 ✨ NEW: Dependency Injection
	197	+Based on `examples/04_dependencies.py`:
	198	+- `Depends()` usage patterns
	199	+- Callable dependencies
	200	+- Class-based dependencies
	201	+- Shared dependencies across routes
	202	+- Dependency scoping (request vs route vs global)
	203	+- Connection pooling pattern
	204	+
	205	+### 2.5 ✨ NEW: Middleware
	206	+Based on `examples/05_middleware.py`:
	207	+- `@app.middleware("http")` decorator
	208	+- Request/response interception
	209	+- Adding custom headers
	210	+- CORS middleware configuration
	211	+- Middleware ordering
	212	+- Timing and logging middleware patterns
	213	+- Based on `tests/test_middleware.py`
	214	+
	215	+### 2.6 ✨ NEW: Error Handling
	216	+Based on `examples/06_error_handling.py`:
	217	+- `HTTPException` usage
	218	+- Custom exception handlers
	219	+- `@app.exception_handler` decorator
	220	+- Validation error handling
	221	+- Global vs per-route handlers
	222	+- Error response format (`{"detail": ...}`)
	223	+
	224	+### 2.7 ✨ NEW: File Uploads
	225	+Based on `examples/07_file_uploads.py`:
	226	+- `UploadFile` class
	227	+- `File()` and `Form()` annotations
	228	+- Multipart form parsing
	229	+- Streaming file handling
	230	+- File size limits
	231	+- Based on `tests/test_multipart.py`
	232	+
	233	+### 2.8 ✨ NEW: WebSockets & SSE
	234	+Based on `examples/10_websockets.py` and `tests/test_sse.py`:
	235	+- `@app.websocket()` decorator
	236	+- WebSocket lifecycle (accept, receive, send, close)
	237	+- Server-Sent Events with `StreamingResponse`
	238	+- `TokenStreamResponse` for validated streaming
	239	+- Real-time communication patterns
	240	+
	241	+### 2.9 Database Integration ✓ (enhance)
	242	+Existing: `tutorial/databases.md`
	243	+Enhance:
	244	+- Add SQL (PostgreSQL, MySQL, SQLite) with `app.set_database()`
	245	+- Add NoSQL (MongoDB, Redis) with direct driver usage
	246	+- Add analytical (DuckDB, ClickHouse)
	247	+- Add connection pooling configuration
	248	+- Add migration workflow
	249	+- Add transaction management
	250	+- Add query result handling (`q`, `q1`, `paginate` patterns from `demo_shop`)
	251	+- Add Rust-native query fast path
	252	+- Add connection saturation and 503 handling
	253	+- Based on `crates/justapi-py/src/database.rs`, `crates/justapi-core/src/db/pool.rs`
	254	+
	255	+### 2.10 ✨ NEW: Background Tasks
	256	+Based on `crates/justapi-py/src/background.rs`:
	257	+- `BackgroundTasks` usage
	258	+- Adding tasks during request processing
	259	+- Task execution model (Tokio background)
	260	+- Error handling in background tasks
	261	+- Use cases (email sending, data processing, webhooks)
	262	+
	263	+### 2.11 ✨ NEW: Routing & Sub-routers
	264	+Based on `examples/08_routers.py`:
	265	+- `APIRouter` for modular routing
	266	+- Route prefixes
	267	+- Tags for OpenAPI grouping
	268	+- Including routers in main app
	269	+- Route ordering and conflict resolution
	270	+
	271	+---
	272	+
	273	+## Phase 3: API Reference (13 pages — all new)
	274	+
	275	+Source material: `docs/api_reference.md`, `crates/justapi-py/src/lib.rs`, all Python framework code, all Rust public modules.
	276	+
	277	+### 3.1 ✨ NEW: JustAPIApp
	278	+- Constructor: `JustAPIApp(title, version, description, ...)`
	279	+- Route decorators: `@app.get`, `@app.post`, `@app.put`, `@app.patch`, `@app.delete`
	280	+- `@app.websocket`, `@app.middleware`, `@app.exception_handler`
	281	+- `@app.tool` (MCP tool registration)
	282	+- `@app.stream_json` (validated streaming)
	283	+- `app.include_router()`, `app.use()` (plugins)
	284	+- `app.run()`, `app.graphql()`, `app.enable_sessions()`
	285	+- `app.set_database()`, `app.enable_circuit_breaker()`, `app.enable_request_coalescing()`
	286	+- `app.enable_secure_headers()`, `app.add_cors()`
	287	+- `app.register_health_check()`
	288	+- Full parameter reference with types and defaults
	289	+
	290	+### 3.2 ✨ NEW: Routing
	291	+- `get(path, dependencies)`
	292	+- `post(path, body_schema, schema, dependencies)`
	293	+- `put`, `patch`, `delete` — full signatures
	294	+- Path parameter types and conversion
	295	+- Route ordering and matching (matchit radix trie)
	296	+- Route-lookup cache (ADR-064)
	297	+
	298	+### 3.3 ✨ NEW: APIRouter
	299	+- Constructor: `APIRouter(prefix, tags)`
	300	+- All route decorators
	301	+- `include_router()` integration
	302	+- Router-level middleware
	303	+- Router-level dependencies
	304	+
	305	+### 3.4 ✨ NEW: Request Object
	306	+- `Request` class attributes: `method`, `path`, `url`, `headers`, `query_params`, `state`
	307	+- `request.json()`, `request.body()`, `request.form()`
	308	+- `request.headers` (Headers class)
	309	+- `request.query_params` (QueryParams class)
	310	+- `request.state` (State class)
	311	+- Zero-copy buffer protocol details
	312	+
	313	+### 3.5 ✨ NEW: Response Classes
	314	+- `Response(content, status_code, headers)`
	315	+- `JSONResponse(content)`
	316	+- `HTMLResponse(content)`
	317	+- `PlainTextResponse(content)`
	318	+- `RedirectResponse(url, status_code)`
	319	+- `StreamingResponse(generator, media_type)`
	320	+- `TokenStreamResponse` (validated streaming)
	321	+- `ValidatedStreamResponse`
	322	+
	323	+### 3.6 ✨ NEW: Dependency Injection
	324	+- `Depends(dependency, use_cache)`
	325	+- `Path()`, `Query()`, `Header()`, `Cookie()`, `Body()`
	326	+- `File()`, `Form()`
	327	+- Callable dependencies
	328	+- Class dependencies
	329	+- Global vs route-level dependencies
	330	+- Dependency caching
	331	+
	332	+### 3.7 ✨ NEW: Exceptions & Error Handling
	333	+- `HTTPException(status_code, detail, headers)`
	334	+- `RequestValidationError(errors)`
	335	+- Exception handler registration
	336	+- Custom exception classes
	337	+- Error response format
	338	+- RFC 9457 structured errors
	339	+
	340	+### 3.8 ✨ NEW: Schema & Validation
	341	+- `Schema` class (JustAPI native, not Pydantic)
	342	+- `Field()` constraints (gt, ge, lt, le, min_length, max_length, regex, format, enum, description)
	343	+- Nested schemas with `$ref`/`$defs`
	344	+- `native=True` validation in Rust
	345	+- Pydantic v2 bridge
	346	+- JSON Schema generation
	347	+- `validate_value()` function
	348	+
	349	+### 3.9 ✨ NEW: WebSockets
	350	+- `WebSocket` class
	351	+- `accept()`, `receive_text()`, `send_text()`, `close()`
	352	+- `receive_bytes()`, `send_bytes()`
	353	+- `receive_json()`, `send_json()`
	354	+- Connection lifecycle
	355	+- WebSocket state (`WebSocketState`)
	356	+
	357	+### 3.10 ✨ NEW: Background Tasks
	358	+- `BackgroundTasks` class
	359	+- `add_task(callable, args, *kwargs)`
	360	+- Execution model
	361	+- Error handling
	362	+
	363	+### 3.11 ✨ NEW: Scheduler
	364	+- `PyScheduler` class (Rust-native cron scheduler)
	365	+- Scheduling syntax (cron expressions)
	366	+- Interval-based scheduling
	367	+- One-time delayed tasks
	368	+- UTC-based execution
	369	+- Based on `crates/justapi-py/src/scheduler.rs`
	370	+
	371	+### 3.12 ✨ NEW: Session (Agent System)
	372	+- `Session` class
	373	+- `session.id`, `session.get()`, `session.update()`
	374	+- Session cookie (`justapi_session`)
	375	+- Query parameter session ID
	376	+- Rust-backed durable store
	377	+- Based on `examples/agent_demo/app.py`
	378	+
	379	+### 3.13 ✨ NEW: Plugin System
	380	+- Python plugin hooks: `build()`, `on_startup()`, `on_shutdown()`
	381	+- Rust plugin trait: `Plugin`
	382	+- Plugin registration with `app.use()`
	383	+- Plugin lifecycle
	384	+- Plugin marketplace (PyPI publishing)
	385	+- Based on `docs/plugins.md`, `crates/justapi-core/src/plugin.rs`
	386	+
	387	+### 3.14 ✨ NEW: Testing Client
	388	+- `JustAPITestClient` class
	389	+- Usage patterns for route testing
	390	+- Async test support
	391	+- Based on `crates/justapi-py/src/test_client.rs`
	392	+
	393	+### 3.15 ✨ NEW: UploadFile
	394	+- `UploadFile` class
	395	+- Properties: `filename`, `content_type`, `file`
	396	+- Methods: `read()`, `write()`, `seek()`, `close()`
	397	+- Temporary file management
	398	+- Size limits
	399	+
	400	+### 3.16 ✨ NEW: Database
	401	+- `Database` class (Python API)
	402	+- `app.set_database(url, init_sql, max_connections, request_acquire_timeout, wal, pragmas)`
	403	+- `app.db.query(sql, params)`, `app.db.execute(sql, params)`
	404	+- Rust-native `AnyPool`
	405	+- Supported engines and URLs
	406	+- Connection pool configuration
	407	+- Migration system
	408	+
	409	+---
	410	+
	411	+## Phase 4: Advanced Guides (9 pages — 1 existing, 8 new)
	412	+
	413	+### 4.1 Zero-GIL Architecture ✓ (enhance)
	414	+Existing: `advanced/zero-gil-architecture.md`
	415	+Enhance:
	416	+- Add detailed GIL release lifecycle
	417	+- Add `py.allow_threads` code examples from Rust
	418	+- Add free-threading (PEP 703) deep dive
	419	+- Add GIL pool architecture (`gil_pool.rs`)
	420	+- Add thread-safety guarantees
	421	+- Add benchmark comparisons (GIL vs no-GIL)
	422	+
	423	+### 4.2 ✨ NEW: Rust Core Deep Dive
	424	+Based on `ARCHITECTURE.md` and `crates/justapi-core/src/`:
	425	+- Server lifecycle (`Server::run()`, `serve()`)
	426	+- Connection management (Tokio + epoll/io_uring)
	427	+- TLS termination (rustls)
	428	+- HTTP parsing (hyper 1.x)
	429	+- Radix trie routing (matchit)
	430	+- Middleware chain architecture
	431	+- Request pipeline (end-to-end flow diagram)
	432	+- Zero-copy FFI with PyO3
	433	+
	434	+### 4.3 ✨ NEW: PyO3 & FFI Safety
	435	+Based on `skills/rust-ffi-safety/SKILL.md`:
	436	+- GIL acquisition discipline
	437	+- Buffer protocol for zero-copy
	438	+- `// SAFETY:` conventions
	439	+- Send/Sync boundaries with Python objects
	440	+- Free-threaded Python support
	441	+- Common FFI pitfalls
	442	+
	443	+### 4.4 ✨ NEW: Native Fast Path
	444	+Based on `DECISIONS.md` ADR-047, ADR-048:
	445	+- `native=True` route decorator
	446	+- 100% Rust execution path
	447	+- Schema validation in Rust (jsonschema-rs)
	448	+- Response serialization in Rust (simd-json)
	449	+- Performance characteristics (724k+ RPS)
	450	+- When to use native vs Python handler
	451	+
	452	+### 4.5 ✨ NEW: Multi-Protocol APIs
	453	+Based on `docs/HANDBOOK.md` §6:
	454	+- REST (OpenAPI 3.1 + Swagger/ReDoc/Scalar)
	455	+- GraphQL (`app.graphql()`, async-graphql)
	456	+- gRPC / Protobuf (tonic, prost)
	457	+- JSON-RPC 2.0
	458	+- Protocol selection guide
	459	+- Multi-protocol architecture patterns
	460	+
	461	+### 4.6 ✨ NEW: Agent System (MCP Tools & Sessions)
	462	+Based on `examples/agent_demo/app.py`:
	463	+- `@app.tool` decorator and MCP tool registration
	464	+- Tool schema inference from type hints
	465	+- `GET /_system/tools`, `POST /_system/tools/call`
	466	+- `app.run_mcp_stdio()` for stdio MCP server
	467	+- Session management (`app.enable_sessions()`)
	468	+- Agent state persistence pattern
	469	+
	470	+### 4.7 ✨ NEW: Streaming Validated Output
	471	+Based on `crates/justapi-py/src/native/app.rs`:
	472	+- `@app.stream_json(path, schema, mode)`
	473	+- NDJSON mode vs JSON array mode
	474	+- Rust-side validation per-chunk
	475	+- Abort-on-invalid semantics
	476	+- Use cases (LLM streaming, data pipelines, real-time events)
	477	+
	478	+### 4.8 ✨ NEW: Performance Tuning
	479	+Based on `BENCHMARKS.md`, `skills/benchmark-harness/SKILL.md`, `PRODUCTION.md`:
	480	+- Worker count tuning (`--workers N`)
	481	+- Connection pool sizing
	482	+- Body size limits
	483	+- Timeout configuration
	484	+- TLS overhead (10.7%)
	485	+- K8s overhead (8.4%)
	486	+- Compression trade-offs
	487	+- Native fast path optimization
	488	+- Route-lookup cache
	489	+- Load-based auto-scaling (`--scale`)
	490	+
	491	+### 4.9 ✨ NEW: Resilience Patterns
	492	+Based on `docs/HANDBOOK.md` §10:
	493	+- Circuit breakers (`enable_circuit_breaker`)
	494	+- Request coalescing (`enable_request_coalescing`)
	495	+- Bulkhead pattern (max concurrent requests)
	496	+- Rate limiting (global and per-IP)
	497	+- Graceful degradation (FallbackMiddleware)
	498	+- Graceful shutdown (SIGTERM → drain → stop)
	499	+- Timeout middleware (504 Gateway Timeout)
	500	+
	501	+---
	502	+
	503	+## Phase 5: Deployment (8 pages — 5 existing in deploy/, 3 new)
	504	+
	505	+### 5.1 ✨ NEW: Docker & Docker Compose
	506	+Based on `Dockerfile` and `docker-compose.yml`:
	507	+- Multi-stage Docker build
	508	+- Production image optimization
	509	+- Docker Compose for local development
	510	+- Environment variables reference
	511	+- Health checks configuration
	512	+- Volume mounts and persistence
	513	+
	514	+### 5.2 ✨ NEW: Kubernetes & Helm
	515	+Based on `helm/justapi/`:
	516	+- Helm chart structure
	517	+- Values reference
	518	+- Deployment configuration
	519	+- HPA autoscaling
	520	+- Ingress with TLS (cert-manager)
	521	+- Secrets management
	522	+- Liveness/readiness probes
	523	+- ServiceAccount and security context
	524	+
	525	+### 5.3 Cloudflare Pages ✓ (enhance)
	526	+Existing: `deployment/cloudflare-pages.md`
	527	+Enhance: Add wrangler configuration details
	528	+
	529	+### 5.4 ✨ NEW: Google Cloud (GKE)
	530	+Based on `deploy/clouds/gke.md`:
	531	+- Cluster creation
	532	+- Ingress setup
	533	+- cert-manager
	534	+- Deploy with Helm
	535	+
	536	+### 5.5 ✨ NEW: Amazon EKS
	537	+Based on `deploy/clouds/eks.md`:
	538	+- Cluster creation with eksctl
	539	+- AWS Load Balancer Controller
	540	+- ECR image registry
	541	+- Deploy with Helm (ALB ingress)
	542	+
	543	+### 5.6 ✨ NEW: Azure AKS
	544	+Based on `deploy/clouds/aks.md`:
	545	+- Cluster creation
	546	+- NGINX Ingress Controller
	547	+- cert-manager
	548	+- ACR integration
	549	+- Deploy with Helm
	550	+
	551	+### 5.7 ✨ NEW: Fly.io
	552	+Based on `deploy/clouds/flyio.md`:
	553	+- fly.toml configuration
	554	+- Launch and scale
	555	+- Fly Postgres attachment
	556	+
	557	+### 5.8 ✨ NEW: Railway
	558	+Based on `deploy/clouds/railway.md`:
	559	+- Project setup
	560	+- Environment configuration
	561	+- Deployment workflow
	562	+
	563	+### 5.9 ✨ NEW: Production Checklist
	564	+Based on `PRODUCTION.md`:
	565	+- Build configuration (release mode, panic=abort)
	566	+- Process supervision (systemd, K8s, Docker restart)
	567	+- TLS termination (edge proxy vs native)
	568	+- Request body size limits
	569	+- Security headers
	570	+- Health/readiness/liveness endpoints
	571	+- Metrics scraping (Prometheus)
	572	+- Connection and timeout tuning
	573	+- Graceful shutdown verification
	574	+- Pre-flight checklist (interactive checklist page)
	575	+
	576	+---
	577	+
	578	+## Phase 6: Security (4 pages — all new, based on docs/security/)
	579	+
	580	+### 6.1 ✨ NEW: Security Policy
	581	+Based on `docs/security/policy.md`:
	582	+- Supported versions table
	583	+- Vulnerability reporting process
	584	+- Response timeline
	585	+- Scope (in-scope/out-of-scope)
	586	+- Hall of Fame
	587	+
	588	+### 6.2 ✨ NEW: OWASP Top 10 Compliance
	589	+Based on `docs/security/owasp-checklist.md`:
	590	+- A01-A10 coverage
	591	+- Implemented vs planned features
	592	+- Configuration guides for each control
	593	+- CI/CD security checks
	594	+- Supply chain security (cargo audit, cargo deny, Dependabot)
	595	+
	596	+### 6.3 ✨ NEW: Penetration Testing Guide
	597	+Based on `docs/security/pentest-guide.md`:
	598	+- Attack surface map
	599	+- Test scenarios (auth, injection, session, rate limiting, TLS, info disclosure)
	600	+- Security headers reference
	601	+- Fuzz testing workflow (cargo-fuzz targets)
	602	+- Supply chain verification
	603	+- Tool list with commands
	604	+- CVSS scoring and report template
	605	+
	606	+### 6.4 ✨ NEW: Secure Configuration Guide
	607	+Based on `PRODUCTION.md` §6, `docs/HANDBOOK.md` §10:
	608	+- Secure headers (`enable_secure_headers`)
	609	+- CORS configuration (default-deny)
	610	+- Rate limiting configuration
	611	+- JWT signing and verification
	612	+- Secrets management
	613	+- Body size limits (DoS hardening)
	614	+- TLS configuration
	615	+
	616	+---
	617	+
	618	+## Phase 7: Observability (4 pages — all new)
	619	+
	620	+### 7.1 ✨ NEW: Metrics & Monitoring
	621	+Based on `crates/justapi-core/src/metrics.rs`:
	622	+- Prometheus endpoint (`/metrics`)
	623	+- Available metrics: request count, latency histograms, connection count, error ratios
	624	+- Prometheus scrape configuration
	625	+- Grafana dashboard setup
	626	+- Alerting rules
	627	+- Based on ADR-012, ADR-024
	628	+
	629	+### 7.2 ✨ NEW: OpenTelemetry Tracing
	630	+Based on `crates/justapi-core/src/tracing_setup.rs`, `crates/justapi-core/src/trace_context.rs`:
	631	+- OTLP gRPC span exporter
	632	+- Distributed tracing setup
	633	+- Span attributes and context propagation
	634	+- Jaeger integration (`docker-compose.otel.yml`)
	635	+- Tracing across PyO3 boundary
	636	+- Based on ADR-025
	637	+
	638	+### 7.3 ✨ NEW: Structured Logging
	639	+Based on `crates/justapi-py/src/logging.rs`:
	640	+- JSON log format
	641	+- Log levels configuration (`RUST_LOG`)
	642	+- tracing-subscriber setup
	643	+- Log aggregation (ELK, Loki)
	644	+- Avoiding PII in production logs
	645	+
	646	+### 7.4 ✨ NEW: Health Checks
	647	+Based on `crates/justapi-core/src/health.rs`:
	648	+- `/health`, `/live`, `/ready` endpoints
	649	+- `register_health_check()` API
	650	+- Custom health check functions
	651	+- DB connectivity checks
	652	+- Downstream dependency checks
	653	+- Kubernetes probe configuration
	654	+
	655	+---
	656	+
	657	+## Phase 8: Reference (6 pages — 1 existing, 5 new)
	658	+
	659	+### 8.1 ✨ NEW: CLI Reference
	660	+Based on `crates/justapi-cli/src/main.rs`:
	661	+- `justapi serve` — dev server with hot-reload, workers, TLS, auto-scaling
	662	+- `justapi create` — project scaffolder with --db, --api-type
	663	+- `justapi db` — database commands (migrate, rollback, seed, list, reset, inspect)
	664	+- `justapi routes` — route visualization
	665	+- `justapi doctor` — system diagnostics
	666	+- `justapi gen` — OpenAPI spec generation, client codegen
	667	+- `justapi check` — configuration validation
	668	+- `justapi new` — new project
	669	+- `justapi profile` — handler profiling
	670	+- Full flag/option reference for each subcommand
	671	+
	672	+### 8.2 ✨ NEW: Configuration Reference
	673	+- Environment variables (`RUST_LOG`, `DATABASE_URL`, `REDIS_URL`, etc.)
	674	+- `JustAPIApp()` constructor parameters
	675	+- `app.run()` parameters
	676	+- `app.set_database()` parameters
	677	+- Server configuration (timeouts, body limits, workers, scaling)
	678	+- Feature flags (tls, ws, compression, opentelemetry, db, inference)
	679	+
	680	+### 8.3 Release Notes ✓ (enhance)
	681	+Existing: `reference/release-notes.md`
	682	+Enhance:
	683	+- Add full changelog from REVISION_LOG.md
	684	+- Add upgrade guides between versions
	685	+- Add deprecation notices
	686	+- Add migration scripts for breaking changes
	687	+
	688	+### 8.4 ✨ NEW: Decision Records (ADR) Index
	689	+Based on `DECISIONS.md`:
	690	+- Index of all 75+ ADRs
	691	+- Searchable by category (architecture, security, performance, deployment)
	692	+- Links to detailed explanations
	693	+- Key decisions that new contributors should understand
	694	+
	695	+### 8.5 ✨ NEW: Error Code Reference
	696	+Based on `crates/justapi-core/src/error_catalog.rs` and `crates/justapi-cli/src/main.rs`:
	697	+- Error code catalog (E001, E002, ...)
	698	+- Error message format
	699	+- Troubleshooting guide for each error
	700	+- Common fixes
	701	+
	702	+### 8.6 ✨ NEW: Glossary
	703	+- Key terms: GIL, PyO3, Tokio, Hyper, matchit, native fast path, ASGI, MCP, SSE
	704	+- Architecture terms: Zero-copy FFI, radix trie, bulkhead, circuit breaker
	705	+- Deployment terms: HPA, Helm, mTLS, OTLP
	706	+
	707	+---
	708	+
	709	+## Phase 9: Contributing Guide (5 pages — all new)
	710	+
	711	+### 9.1 ✨ NEW: Development Setup
	712	+Based on `CONTRIBUTING.md`:
	713	+- Repository clone and structure
	714	+- Rust toolchain setup (rustup, nightly for fuzzing)
	715	+- Python virtual environment
	716	+- Building with maturin
	717	+- Running tests (Rust + Python)
	718	+- Code editor setup (rust-analyzer, pyright)
	719	+
	720	+### 9.2 ✨ NEW: Coding Standards
	721	+Based on `AGENTS.md`, `CONTRIBUTING.md`:
	722	+- Rust-first mandate (what goes in Rust vs Python)
	723	+- Commit message format (`<phase>: <description>`)
	724	+- Branch naming (`phase-N/<short-description>`)
	725	+- `unsafe` block requirements (`// SAFETY:`)
	726	+- Error handling conventions (anyhow vs thiserror)
	727	+- Public API documentation requirements
	728	+
	729	+### 9.3 ✨ NEW: Testing Guide
	730	+Based on all test files:
	731	+- Running `cargo test --workspace`
	732	+- Running `pytest` for Python tests
	733	+- Miri validation (`cargo miri test`)
	734	+- Writing test client tests (`JustAPITestClient`)
	735	+- Writing integration tests (HTTP server + test client)
	736	+- Snapshot testing patterns
	737	+- Test file naming conventions
	738	+- Property-based testing (proptest)
	739	+
	740	+### 9.4 ✨ NEW: Benchmarking Guide
	741	+Based on `skills/benchmark-harness/SKILL.md`, `BENCHMARKS.md`:
	742	+- Benchmark harness setup (`justapi-bench`, `oha`)
	743	+- Hardware fixture documentation
	744	+- Benchmark protocol (warmup, runs, reporting)
	745	+- Workload types and their purposes
	746	+- Interpreting results (p50, p95, p99, RPS)
	747	+- Regression gate (5% p99 threshold)
	748	+- Adding new benchmarks
	749	+
	750	+### 9.5 ✨ NEW: Documentation Guide
	751	+- How docs_site is built (Astro + Starlight)
	752	+- Adding new pages
	753	+- Sidebar configuration
	754	+- Code block conventions
	755	+- Image and diagram guidelines
	756	+- Previewing docs locally (`npm run dev`)
	757	+- Documentation review process
	758	+
	759	+---
	760	+
	761	+## Phase 10: AI/Inference Documentation (4 pages — all new)
	762	+
	763	+### 10.1 ✨ NEW: Inference Engine Overview
	764	+Based on `crates/justapi-inference/`:
	765	+- Architecture (Engine, Scheduler, Gateway, Control Plane)
	766	+- KV Cache (PagedAttention, BlockPool)
	767	+- Prefix Cache (RadixPrefixCache)
	768	+- Speculative Decoding
	769	+- Disaggregated Prefill/Decode (PdScheduler)
	770	+- Current status (frozen per ADR-067, target 2.0.8)
	771	+
	772	+### 10.2 ✨ NEW: LLM Serving API
	773	+Based on `crates/justapi-inference/src/openai.rs`:
	774	+- OpenAI-compatible chat completions API
	775	+- Streaming support
	776	+- Embeddings API
	777	+- Model management (list, load, unload)
	778	+- Sampling parameters
	779	+
	780	+### 10.3 ✨ NEW: GPU & CUDA Configuration
	781	+Based on `crates/justapi-bench/src/gpu_bench.rs`:
	782	+- CUDA setup with Candle
	783	+- GPU memory management
	784	+- Multi-GPU sharding
	785	+- Benchmark methodology
	786	+
	787	+### 10.4 ✨ NEW: Scheduling & Batching
	788	+Based on `crates/justapi-inference/src/scheduler.rs`, `pd.rs`:
	789	+- Continuous batching
	790	+- Prefill/decode disaggregation
	791	+- Priority scheduling
	792	+- Fairness and QoS
	793	+- Queue management
	794	+
	795	+---
	796	+
	797	+## Phase 11: Examples & Code Playground (1 page — new)
	798	+
	799	+### 11.1 ✨ NEW: Examples Gallery
	800	+Based on all 12 `examples/*.py` files + `demo_shop/`:
	801	+- Categorized example index
	802	+- Each example with: description, code, expected output, key concepts
	803	+- Runnable code blocks (interactive playground if feasible)
	804	+- Examples:
	805	+ 1. Hello World (01_hello_world.py)
	806	+ 2. Path & Query Params (02_path_query_params.py)
	807	+ 3. Request Body (03_request_body.py)
	808	+ 4. Dependencies (04_dependencies.py)
	809	+ 5. Middleware (05_middleware.py)
	810	+ 6. Error Handling (06_error_handling.py)
	811	+ 7. File Uploads (07_file_uploads.py)
	812	+ 8. Routers (08_routers.py)
	813	+ 9. DB Integration (09_db_integration.py)
	814	+ 10. WebSockets (10_websockets.py)
	815	+ 11. Plugin System (plugin_cache.py)
	816	+ 12. Agent Demo (agent_demo/)
	817	+ 13. E-Commerce Shop (demo_shop/ — 23 endpoints)
	818	+
	819	+---
	820	+
	821	+## Phase 12: Technical Implementation Tasks
	822	+
	823	+### 12.1 Content Migration
	824	+- [ ] Convert `docs/HANDBOOK.md` (498 lines) into ~15 structured pages
	825	+- [ ] Convert `docs/api_reference.md` (101 lines) into expanded reference pages
	826	+- [ ] Convert `docs/plugins.md` (105 lines) into plugin guide + reference
	827	+- [ ] Convert `docs/migrating_from_fastapi.md` (41 lines) into enhanced migration guide
	828	+- [ ] Convert `docs/security/policy.md` (55 lines) + `owasp-checklist.md` (86 lines) + `pentest-guide.md` (143 lines) into security section
	829	+- [ ] Convert `deploy/clouds/*.md` (5 files) into deployment section
	830	+- [ ] Convert `PRODUCTION.md` (207 lines) into production checklist
	831	+- [ ] Convert `ARCHITECTURE.md` (129 lines) into architecture deep-dive
	832	+- [ ] Convert `CONTRIBUTING.md` (87 lines) into contributing section
	833	+- [ ] Extract API docs from all `crates/*/src/` public items
	834	+
	835	+### 12.2 Automation & Tooling
	836	+- [ ] Add `@astrojs/sitemap` for SEO
	837	+- [ ] Add `@astrojs/rss` for release notes feed
	838	+- [ ] Configure Pagefind for full-text search across all pages
	839	+- [ ] Add Mermaid.js support for architecture diagrams
	840	+- [ ] Add OpenGraph image generation
	841	+- [ ] Set up CI/CD: build docs site on PR + deploy on merge to main
	842	+- [ ] Set up Cloudflare Pages auto-deploy from GitHub (currently configured)
	843	+- [ ] Add broken link checker in CI
	844	+- [ ] Add spell checker in CI (cspell)
	845	+
	846	+### 12.3 Design Enhancements
	847	+- [ ] Expand `src/styles/custom.css` to full design system
	848	+- [ ] Create reusable components: BenchTable, CodeExample, ArchitectureDiagram, FeatureCard
	849	+- [ ] Add interactive benchmark comparison widget (from BENCHMARKS.md data)
	850	+- [ ] Add dark/light mode polish
	851	+- [ ] Add responsive design for mobile
	852	+- [ ] Add copy-to-clipboard for code blocks
	853	+
	854	+### 12.4 Quality Assurance
	855	+- [ ] All pages: frontmatter with title, description, sidebar label
	856	+- [ ] All code examples: syntax-highlighted and tested
	857	+- [ ] All links: verified working
	858	+- [ ] Lighthouse audit: target 100/100
	859	+- [ ] Accessibility audit: WCAG 2.1 AA
	860	+- [ ] Mobile-responsive review
	861	+- [ ] Print layout review
	862	+
	863	+---
	864	+
	865	+## Phase 13: Content Audit & Gap Analysis
	866	+
	867	+### Pages That Exist (10)
	868	+\| Page \| Location \| Quality \|
	869	+\|---\|---\|---\|
	870	+\| index.mdx (splash) \| `docs/` \| Good \|
	871	+\| getting-started/overview.md \| `docs_site/` \| Minimal \|
	872	+\| getting-started/installation.md \| `docs_site/` \| Good \|
	873	+\| getting-started/first-steps.md \| `docs_site/` \| Good \|
	874	+\| getting-started/cli-scaffolder.md \| `docs_site/` \| Good \|
	875	+\| tutorial/path-params.md \| `docs_site/` \| Good \|
	876	+\| tutorial/databases.md \| `docs_site/` \| Minimal \|
	877	+\| deployment/cloudflare-pages.md \| `docs_site/` \| Good \|
	878	+\| advanced/zero-gil-architecture.md \| `docs_site/` \| Good \|
	879	+\| reference/release-notes.md \| `docs_site/` \| Good \|
	880	+
	881	+### Content in Root `docs/` Not Yet in `docs_site/` (5)
	882	+- `docs/HANDBOOK.md` (498 lines — massive comprehensive handbook)
	883	+- `docs/api_reference.md` (101 lines — API listing)
	884	+- `docs/migrating_from_fastapi.md` (41 lines)
	885	+- `docs/plugins.md` (105 lines)
	886	+- `docs/security/*` (3 files, 284 lines total)
	887	+
	888	+### Content in Root `.md` Files Not Yet in `docs_site/` (8)
	889	+- `ARCHITECTURE.md` (129 lines)
	890	+- `PRODUCTION.md` (207 lines)
	891	+- `PRODUCTION_PLAN.md` (292 lines)
	892	+- `CONTRIBUTING.md` (87 lines)
	893	+- `SECURITY.md` (7 lines)
	894	+- `ROADMAP.md` (70 lines)
	895	+- `DECISIONS.md` (2931 lines — 75 ADRs)
	896	+- `BENCHMARKS.md` (1743 lines — all benchmark results)
	897	+
	898	+### Additional Content to Extract from Source Code
	899	+- All 12 examples require docs treatment
	900	+- `demo_shop/` e2e app needs case study
	901	+- All 5 cloud deployment guides (`deploy/clouds/*.md`)
	902	+- Helm chart documentation
	903	+- CLI reference (9 subcommands)
	904	+- Fuzz testing documentation
	905	+- All ADRs from DECISIONS.md
	906	+
	907	+---
	908	+
	909	+## Implementation Roadmap
	910	+
	911	+```
	912	+Phase 0: Site Infrastructure [Week 1] — config, nav structure, design system
	913	+Phase 1: Getting Started [Week 1] — 1 enhance + 1 new page
	914	+Phase 2: Tutorials [Week 2] — 1 enhance + 10 new pages
	915	+Phase 3: API Reference [Week 3-4] — 16 new pages (largest section)
	916	+Phase 4: Advanced Guides [Week 4-5] — 1 enhance + 8 new pages
	917	+Phase 5: Deployment [Week 5] — 3 enhance + 6 new pages
	918	+Phase 6: Security [Week 6] — 4 new pages
	919	+Phase 7: Observability [Week 6] — 4 new pages
	920	+Phase 8: Reference [Week 7] — 1 enhance + 5 new pages
	921	+Phase 9: Contributing [Week 7] — 5 new pages
	922	+Phase 10: Inference [Week 8] — 4 new pages
	923	+Phase 11: Examples Gallery [Week 8] — 1 new page
	924	+Phase 12: Technical QA [Week 8-9] — automation, CI, design polish
	925	+Phase 13: Final Audit [Week 9] — content completeness, link check, Lighthouse
	926	+```
	927	+
	928	+Total new pages: ~75 (enhancements to 6 existing pages, ~69 completely new)
	929	+
	930	+---
	931	+
	932	+## Key Design Principles
	933	+
	934	+1. Every page must answer: What is it? Why does it matter? How do I use it? Where does it fit in the architecture?
	935	+2. Code examples always runnable — tested with the actual framework
	936	+3. Performance numbers everywhere — JustAPI's differentiator is speed; every feature page should show the benchmark
	937	+4. Visual hierarchy — architecture diagrams (Mermaid), screenshots, comparison tables
	938	+5. Progressive disclosure — tutorial → how-to → reference → deep-dive
	939	+6. Search-first — every concept should be findable via Pagefind within 2 clicks
	940	+7. Mobile-friendly — all diagrams, tables, and code blocks responsive
	941	+8. Accessible — WCAG 2.1 AA, semantic HTML, proper ARIA labels
	942	+
	943	+---
	944	+
	945	+## Directory Structure (Target)
	946	+
	947	+```
	948	+docs_site/
	949	+├── astro.config.mjs
	950	+├── package.json
	951	+├── tsconfig.json
	952	+├── public/
	953	+│ ├── favicon.svg
	954	+│ └── og-image.png
	955	+├── src/
	956	+│ ├── assets/
	957	+│ │ ├── logo.svg
	958	+│ │ ├── architecture.svg
	959	+│ │ └── bench-comparison.png
	960	+│ ├── components/
	961	+│ │ ├── BenchTable.astro # Reusable benchmark comparison table
	962	+│ │ ├── CodeExample.astro # Styled code block with copy button
	963	+│ │ ├── ArchitectureDiagram.astro # Mermaid diagram component
	964	+│ │ ├── FeatureCard.astro # Feature highlight card
	965	+│ │ ├── CompatibilityBadge.astro # FastAPI/Starlette parity badge
	966	+│ │ └── Callout.astro # Info/warning/tip callout
	967	+│ ├── content/
	968	+│ │ ├── config.ts
	969	+│ │ └── docs/
	970	+│ │ ├── index.mdx
	971	+│ │ ├── getting-started/
	972	+│ │ │ ├── overview.md
	973	+│ │ │ ├── installation.md
	974	+│ │ │ ├── first-steps.md
	975	+│ │ │ ├── cli-scaffolder.md
	976	+│ │ │ └── migrating-from-fastapi.md
	977	+│ │ ├── tutorials/
	978	+│ │ │ ├── hello-world.md
	979	+│ │ │ ├── path-query-params.md
	980	+│ │ │ ├── request-body.md
	981	+│ │ │ ├── dependency-injection.md
	982	+│ │ │ ├── middleware.md
	983	+│ │ │ ├── error-handling.md
	984	+│ │ │ ├── file-uploads.md
	985	+│ │ │ ├── websockets-sse.md
	986	+│ │ │ ├── database-integration.md
	987	+│ │ │ ├── background-tasks.md
	988	+│ │ │ └── routing-subrouters.md
	989	+│ │ ├── api-reference/
	990	+│ │ │ ├── index.md
	991	+│ │ │ ├── justapiapp.md
	992	+│ │ │ ├── routing.md
	993	+│ │ │ ├── apirouter.md
	994	+│ │ │ ├── request.md
	995	+│ │ │ ├── responses.md
	996	+│ │ │ ├── dependency-injection.md
	997	+│ │ │ ├── exceptions.md
	998	+│ │ │ ├── schema-validation.md
	999	+│ │ │ ├── websockets.md
	1000	+│ │ │ ├── background-tasks.md
	1001	+│ │ │ ├── scheduler.md
	1002	+│ │ │ ├── session.md
	1003	+│ │ │ ├── plugins.md
	1004	+│ │ │ ├── testing-client.md
	1005	+│ │ │ ├── uploadfile.md
	1006	+│ │ │ └── database.md
	1007	+│ │ ├── advanced/
	1008	+│ │ │ ├── zero-gil-architecture.md
	1009	+│ │ │ ├── rust-core-deep-dive.md
	1010	+│ │ │ ├── pyo3-ffi-safety.md
	1011	+│ │ │ ├── native-fast-path.md
	1012	+│ │ │ ├── multi-protocol-apis.md
	1013	+│ │ │ ├── agent-system.md
	1014	+│ │ │ ├── streaming-output.md
	1015	+│ │ │ ├── performance-tuning.md
	1016	+│ │ │ └── resilience-patterns.md
	1017	+│ │ ├── deployment/
	1018	+│ │ │ ├── docker.md
	1019	+│ │ │ ├── kubernetes-helm.md
	1020	+│ │ │ ├── cloudflare-pages.md
	1021	+│ │ │ ├── gke.md
	1022	+│ │ │ ├── eks.md
	1023	+│ │ │ ├── aks.md
	1024	+│ │ │ ├── flyio.md
	1025	+│ │ │ ├── railway.md
	1026	+│ │ │ └── production-checklist.md
	1027	+│ │ ├── security/
	1028	+│ │ │ ├── policy.md
	1029	+│ │ │ ├── owasp-compliance.md
	1030	+│ │ │ ├── penetration-testing.md
	1031	+│ │ │ └── secure-configuration.md
	1032	+│ │ ├── observability/
	1033	+│ │ │ ├── metrics-monitoring.md
	1034	+│ │ │ ├── opentelemetry.md
	1035	+│ │ │ ├── structured-logging.md
	1036	+│ │ │ └── health-checks.md
	1037	+│ │ ├── reference/
	1038	+│ │ │ ├── cli.md
	1039	+│ │ │ ├── configuration.md
	1040	+│ │ │ ├── release-notes.md
	1041	+│ │ │ ├── adr-index.md
	1042	+│ │ │ ├── error-codes.md
	1043	+│ │ │ └── glossary.md
	1044	+│ │ ├── contributing/
	1045	+│ │ │ ├── development-setup.md
	1046	+│ │ │ ├── coding-standards.md
	1047	+│ │ │ ├── testing-guide.md
	1048	+│ │ │ ├── benchmarking-guide.md
	1049	+│ │ │ └── documentation-guide.md
	1050	+│ │ ├── inference/
	1051	+│ │ │ ├── overview.md
	1052	+│ │ │ ├── llm-serving-api.md
	1053	+│ │ │ ├── gpu-cuda-setup.md
	1054	+│ │ │ └── scheduling-batching.md
	1055	+│ │ └── examples/
	1056	+│ │ └── index.md
	1057	+│ └── styles/
	1058	+│ └── custom.css # Expanded design system
	1059	+└── dist/ # Build output
	1060	+```
	1061	+
	1062	+---
	1063	+
	1064	+## Execution Priorities
	1065	+
	1066	+### Required for MVP (v1 docs site launch)
	1067	+1. Phase 0: Site nav + design system
	1068	+2. Phase 1: All Getting Started (complete — already have 4/5 pages)
	1069	+3. Phase 2: Tutorials (most user-facing value)
	1070	+4. Phase 3: API Reference (most referenced by users)
	1071	+5. Phase 5.9: Production Checklist (critical for ops audience)
	1072	+6. Phase 6: Security (trust signal)
	1073	+7. Phase 8.1: CLI Reference (dev tool UX)
	1074	+8. Phase 9: Contributing Guide (community growth)
	1075	+
	1076	+### v2 enhancements
	1077	+9. Phase 4: Advanced Guides (deep technical audience)
	1078	+10. Phase 5: Cloud Deployment Guides (multi-cloud)
	1079	+11. Phase 7: Observability (production operations)
	1080	+12. Phase 10: Inference (AI/ML audience)
	1081	+13. Phase 11: Examples Gallery
	1082	+
	1083	+### Ongoing
	1084	+14. Phase 8.3: Release Notes + Changelog (per-release updates)
	1085	+15. Phase 12.2: CI/CD for docs (continuous deployment)
	1086	+16. Phase 12.4: Quality assurance (link checking, Lighthouse)
	1087	+
	1088	+---
	1089	+
	1090	+## Success Metrics
	1091	+
	1092	+\| Metric \| Target \|
	1093	+\|---\|---\|
	1094	+\| Page coverage \| 100% of public API documented \|
	1095	+\| Interactive examples \| Every tutorial page has runnable code \|
	1096	+\| Search \| Any concept findable within 2 Pagefind queries \|
	1097	+\| Lighthouse \| 100/100 Performance, Accessibility, Best Practices, SEO \|
	1098	+\| Load time \| <1s to First Contentful Paint \|
	1099	+\| Broken links \| 0 (CI-enforced) \|
	1100	+\| Mobile \| All pages pass mobile viewport test \|
	1101	+\| Accessibility \| WCAG 2.1 AA compliance \|
	1102	+\| Docs build time \| <30s in CI \|
	1103	+\| Deployment \| Auto-deploy on merge to main (Cloudflare Pages) \|
	1104	+
	1105	+---
	1106	+
	1107	+Generated by codebase analysis of all docs/, docs_site/, crates/, examples/, deploy/, benchmarks/, tests/, helm/, fuzz/, and root .md files — capturing 100% of the JustAPI framework surface.
0	1108