swadhin / justapi public

swadhinbiswas

[email protected]

2026-07-25 17:11:21 +0600 committed NaN years ago

a16ef06

commit a16ef06

1 file changed

+660 -1033

Files

docsplan.md +660 -1033

Showing 1 changed file+660-1031

docsplan.md

▼docsplan.md

+660-1031

@@ -1,1107 +1,734 @@
1		-# JustAPI Documentation Site — Production-Grade Build Plan
	1	+# JustAPI Documentation Site — Full Rebuild Plan (FastAPI-Level Depth)
2	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.
	3	+> Goal: Rebuild the docs_site (Astro + Starlight) to match FastAPI's documentation in depth, polish, navigation structure, and developer experience.
4	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.
	5	+> FastAPI docs analyzed: https://fastapi.tiangolo.com/ — 7 top-level nav sections, ~140+ pages, auto-generated API reference, tutorial-first learning path, multilingual support, sponsor integration.
	6	+>
	7	+> Current JustAPI docs_site: ~20 pages across getting-started, tutorials, API reference, advanced, deployment, security, observability, contributing, inference, and reference sections. Content exists but lacks tutorial depth, API reference auto-generation, and structured learning path.
6	8
7	9	---
8	10
9		-## Phase 0: Site Infrastructure & Design System
	11	+## 0. FastAPI Docs Analysis — What Makes It Great
	12	+
	13	+### 0.1 Navigation Architecture (Top-Level)
10	14
11		-### 0.1 Framework & Theme
12		-\| Item \| Current \| Target \|
	15	+\| FastAPI Nav Item \| Pages \| Purpose \|
13	16	\|---\|---\|---\|
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 \|
	17	+\| Home \| 1 \| Hero, sponsors, testimonials, quick-start, performance, dependencies \|
	18	+\| Features \| 1 \| Bullet-point feature showcase \|
	19	+\| Learn \| ~76 \| Main learning path — Python types intro, async intro, tutorial (35p), advanced guide (30p), CLI, editor support, deployment (8p), how-to recipes (11p) \|
	20	+\| Reference \| ~21 \| Auto-generated API reference — every class, function, parameter documented with signatures and examples \|
	21	+\| Resources \| 7 \| People, help, contributing, translations, project template, external links, newsletter \|
	22	+\| About \| 4 \| Alternatives/comparisons, history/design, benchmarks, repo management \|
	23	+\| Release Notes \| 1 \| Version changelog \|
20	24
21		-### 0.2 Navigation Architecture
22		-Current sidebar only has 2 autogenerated sections. Replace with explicit, hierarchical navigation:
	25	+### 0.2 Key Design Patterns
23	26
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		-```
	27	+1. Tutorial-first learning path. The `Learn` section is a structured course that builds from zero to advanced. Each page has:
	28	+ - Complete, runnable code example at the top
	29	+ - Step-by-step explanation
	30	+ - "Tip", "Note", "Info" callout boxes
	31	+ - Screenshots of Swagger UI / ReDoc
	32	+ - "Recap" section
	33	+ - Previous/Next page navigation
	34	+ - "On this page" right sidebar with section anchors
	35	+ - Breadcrumb navigation
	36	+
	37	+2. Python version tabs. Code blocks are shown with Python 3.10+ by default, with tabs for older versions.
	38	+
	39	+3. Auto-generated API Reference. The `/reference/` section is generated from docstrings — every parameter, return type, and method has a documented signature with examples.
	40	+
	41	+4. Sponsor integration. Banner sponsors appear at the top of every page; sidebar sponsors on the home page.
	42	+
	43	+5. Translation support. 12 languages with automatic language switcher in the top bar.
	44	+
	45	+6. "How To" recipes section. 11 standalone recipes for specific tasks (GraphQL, custom middleware, database testing, etc.)
	46	+
	47	+7. Deployment depth. 8 pages covering HTTPS, manual, cloud providers, Docker, server workers, concepts.
105	48
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
	49	+### 0.3 Page Count Breakdown
	50	+
	51	+\| Section \| Subsection \| Pages \|
	52	+\|---\|---\|---\|
	53	+\| Learn \| Python Types Intro, Async/Await \| 2 \|
	54	+\| Learn \| Tutorial - User Guide \| 35 (5 deps sub + 4 security sub) \|
	55	+\| Learn \| Advanced User Guide \| 30 (2 security sub) \|
	56	+\| Learn \| FastAPI CLI \| 1 \|
	57	+\| Learn \| Editor Support \| 1 \|
	58	+\| Learn \| Deployment \| 8 \|
	59	+\| Learn \| How-To Recipes \| 11 \|
	60	+\| Reference \| API Reference \| 21 (2 OpenAPI sub) \|
	61	+\| Resources \| People, Help, Contributing, etc. \| 7 \|
	62	+\| About \| Alternatives, History, Benchmarks, Management \| 4 \|
	63	+\| Total \| \| ~140+ pages \|
114	64
115	65	---
116	66
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
	67	+## 1. JustAPI Current State Audit
	68	+
	69	+### 1.1 Existing Docs Inventory
	70	+
	71	+\| Section \| Existing Pages \| Status \|
	72	+\|---\|---\|---\|
	73	+\| Getting Started \| overview, installation, first-steps, cli-scaffolder, migrating-from-fastapi \| 5 pages exist, need enhancement \|
	74	+\| Tutorials \| hello-world, path-query-params, request-body, dependency-injection, middleware, error-handling, file-uploads, background-tasks, websockets-sse, routing-subrouters, database-integration \| 11 pages exist \|
	75	+\| API Reference \| index, justapiapp, routing, apirouter, request, responses, dependency-injection, exceptions, schema-validation, websockets, background-tasks, scheduler, session, plugins, testing-client, uploadfile, database \| 17 pages exist \|
	76	+\| Advanced \| native-fast-path, pyo3-ffi-safety, rust-core-deep-dive, zero-gil-architecture, streaming-output, agent-system, multi-protocol-apis, performance-tuning, resilience-patterns \| 9 pages exist \|
	77	+\| Deployment \| production-checklist, docker, kubernetes-helm, cloudflare-pages, railway, flyio, aks, eks, gke \| 9 pages exist \|
	78	+\| Security \| secure-configuration, penetration-testing, owasp-compliance, policy \| 4 pages exist \|
	79	+\| Observability \| opentelemetry, health-checks, metrics-monitoring, structured-logging \| 4 pages exist \|
	80	+\| Contributing \| development-setup, coding-standards, testing-guide, benchmarking-guide, documentation-guide \| 5 pages exist \|
	81	+\| Inference \| overview, gpu-cuda-setup, llm-serving-api, scheduling-batching \| 4 pages exist \|
	82	+\| Reference \| cli, configuration, error-codes, adr-index, glossary, release-notes \| 6 pages exist \|
	83	+\| Examples \| index \| 1 page exists \|
	84	+\| Total \| \| ~75 pages \|
	85	+
	86	+### 1.2 Gaps vs FastAPI
	87	+
	88	+\| What FastAPI has \| JustAPI status \| Action \|
	89	+\|---\|---\|---\|
	90	+\| Tutorial with 35 progressive lessons \| 11 tutorials, not fully progressive \| Expand to 35+ tutorial pages \|
	91	+\| Advanced User Guide with 30 pages \| 9 advanced pages \| Add 21 advanced topics \|
	92	+\| How-To Recipes (11 pages) \| 0 \| Create new section \|
	93	+\| Auto-generated API Reference \| 17 hand-written pages \| Switch to docstring-generated \|
	94	+\| Python version tabs in code \| Not supported \| Add Starlight tab component \|
	95	+\| Multilingual support (12 langs) \| Not supported \| Add i18n routing \|
	96	+\| Sponsor banners on every page \| Not supported \| Add sponsor integration \|
	97	+\| "On this page" TOC with anchors \| Starlight built-in \| Already works \|
	98	+\| Breadcrumb navigation \| Starlight built-in \| Already works \|
	99	+\| Previous/Next page links \| Starlight built-in \| Already works \|
	100	+\| Search (Pagefind) \| Starlight built-in \| Already works \|
	101	+\| Screenshots in tutorials \| 0 screenshots \| Add screenshots \|
	102	+\| "Tip/Note/Warning" callout boxes \| Starlight has `:::tip` etc. \| Use consistently \|
	103	+\| Recap section in tutorials \| Not used \| Add to every tutorial \|
	104	+\| Editor support page \| 0 \| Create \|
	105	+\| FastAPI CLI reference \| Has CLI reference \| Enhance \|
	106	+\| Deployment cloud providers in docs \| 9 deployment pages \| Enhance \|
	107	+\| External links/resources page \| 0 \| Create \|
	108	+\| Project generation template page \| 0 \| Create \|
	109	+\| History, design and future \| 0 \| Create (DECISIONS.md) \|
	110	+\| Performance benchmarks page \| BENCHMARKS.md exists \| Port to docs site \|
	111	+\| Release notes changelog \| release-notes.md exists \| Enhance \|
165	112
166	113	---
167	114
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
	115	+## 2. Rebuild Plan — Phases
	116	+
	117	+### Phase 1: Information Architecture & Navigation Overhaul
	118	+
	119	+Goal: Restructure sidebar to match FastAPI's learning-path-first approach.
	120	+
	121	+#### 1.1 New Sidebar Structure
	122	+
	123	+```
	124	+Getting Started (5 pages)
	125	+├── Overview & Philosophy
	126	+├── Installation
	127	+├── First Steps
	128	+├── CLI Project Scaffolder
	129	+└── Migrating from FastAPI
	130	+
	131	+Tutorial — User Guide (35+ pages, progressive)
	132	+├── Python Types Intro (NEW)
	133	+├── Async / Await (NEW)
	134	+├── First Steps (existing, enhance)
	135	+├── Path Parameters (existing, enhance)
	136	+├── Query Parameters (existing, enhance)
	137	+├── Request Body (Pydantic) (existing, enhance)
	138	+├── Query Parameters & String Validations (NEW)
	139	+├── Path Parameters & Numeric Validations (NEW)
	140	+├── Query Parameter Models (NEW)
	141	+├── Body — Multiple Parameters (NEW)
	142	+├── Body — Fields (NEW)
	143	+├── Body — Nested Models (NEW)
	144	+├── Declare Request Example Data (NEW)
	145	+├── Extra Data Types (NEW)
	146	+├── Cookie Parameters (NEW)
	147	+├── Header Parameters (NEW)
	148	+├── Cookie Parameter Models (NEW)
	149	+├── Header Parameter Models (NEW)
	150	+├── Response Model — Return Type (NEW)
	151	+├── Extra Models (NEW)
	152	+├── Response Status Code (NEW)
	153	+├── Form Data (NEW)
	154	+├── Form Models (NEW)
	155	+├── Request Files (NEW)
	156	+├── Request Forms & Files (NEW)
	157	+├── Handling Errors (existing, enhance)
	158	+├── Path Operation Configuration (NEW)
	159	+├── JSON Compatible Encoder (NEW)
	160	+├── Body — Updates (NEW)
	161	+├── Dependencies (existing, expand)
	162	+│ ├── Classes as Dependencies (NEW)
	163	+│ ├── Sub-dependencies (NEW)
	164	+│ ├── Dependencies in Path Ops (NEW)
	165	+│ ├── Global Dependencies (NEW)
	166	+│ └── Dependencies with yield (NEW)
	167	+├── Security (expand)
	168	+│ ├── Security First Steps (NEW)
	169	+│ ├── Get Current User (NEW)
	170	+│ ├── Simple OAuth2 (NEW)
	171	+│ └── OAuth2 + JWT Tokens (NEW)
	172	+├── Middleware (existing, enhance)
	173	+├── CORS (existing)
	174	+├── SQL Databases (existing)
	175	+├── Bigger Applications — Multiple Files (existing)
	176	+├── Background Tasks (existing, enhance)
	177	+├── Metadata & Docs URLs (NEW)
	178	+├── Frontend (NEW)
	179	+├── Static Files (NEW)
	180	+├── Testing (existing, enhance)
	181	+└── Debugging (NEW)
	182	+
	183	+Advanced User Guide (30 pages)
	184	+├── Native Fast Path (existing, enhance)
	185	+├── Zero-GIL Architecture (existing, enhance)
	186	+├── Rust Core Deep Dive (existing, enhance)
	187	+├── PyO3 FFI Safety (existing, enhance)
	188	+├── Streaming Output (existing, enhance)
	189	+├── Agent System (existing, enhance)
	190	+├── Multi-Protocol APIs (existing, enhance)
	191	+├── Performance Tuning (existing, enhance)
	192	+├── Resilience Patterns (existing, enhance)
	193	+├── Path Operation Advanced Configuration (NEW)
	194	+├── Additional Status Codes (NEW)
	195	+├── Return a Response Directly (NEW)
	196	+├── Custom Response — HTML, Stream, File (NEW)
	197	+├── Additional Responses in OpenAPI (NEW)
	198	+├── Response Cookies (NEW)
	199	+├── Response Headers (NEW)
	200	+├── Response — Change Status Code (NEW)
	201	+├── Advanced Dependencies (NEW)
	202	+├── Advanced Security (NEW)
	203	+│ ├── OAuth2 Scopes (NEW)
	204	+│ └── HTTP Basic Auth (NEW)
	205	+├── Using the Request Directly (NEW)
	206	+├── Using Dataclasses (NEW)
	207	+├── Advanced Middleware (NEW)
	208	+├── Sub Applications — Mounts (NEW)
	209	+├── Behind a Proxy (NEW)
	210	+├── Templates (Jinja2) (NEW)
	211	+├── WebSockets (existing, enhance)
	212	+├── Lifespan Events (NEW)
	213	+├── Testing WebSockets (NEW)
	214	+├── Testing Events (NEW)
	215	+├── Testing Dependencies with Overrides (NEW)
	216	+├── Async Tests (NEW)
	217	+├── Settings & Environment Variables (NEW)
	218	+├── OpenAPI Callbacks (NEW)
	219	+├── OpenAPI Webhooks (NEW)
	220	+├── Including WSGI — Flask, Django (NEW)
	221	+├── Generating SDKs (NEW)
	222	+└── Strict Content-Type Checking (NEW)
	223	+
	224	+How-To Recipes (15 pages, NEW section)
	225	+├── General Recipes (NEW)
	226	+├── Migrate from Pydantic v1 (NEW)
	227	+├── GraphQL Integration (NEW)
	228	+├── Custom Request & Route Classes (NEW)
	229	+├── Conditional OpenAPI (NEW)
	230	+├── Extending OpenAPI (NEW)
	231	+├── Separate Input/Output Schemas (NEW)
	232	+├── Custom Docs UI Assets (NEW)
	233	+├── Configure Swagger UI (NEW)
	234	+├── Testing a Database (NEW)
	235	+├── Custom Error Status Codes (NEW)
	236	+├── gRPC Advanced Patterns (NEW)
	237	+├── WASM Middleware Plugins (NEW)
	238	+├── Circuit Breaker Recipes (NEW)
	239	+└── Background Task Patterns (NEW)
	240	+
	241	+API Reference (20+ pages, auto-generated)
	242	+├── JustAPIApp — Constructor & Methods (enhance)
	243	+├── Request Parameters (Path, Query, Header, Cookie) (enhance)
	244	+├── Status Codes (enhance)
	245	+├── UploadFile (enhance)
	246	+├── Exceptions — HTTPException (enhance)
	247	+├── Dependencies — Depends() (enhance)
	248	+├── APIRouter (enhance)
	249	+├── BackgroundTasks (enhance)
	250	+├── Request (enhance)
	251	+├── WebSockets (enhance)
	252	+├── Response (enhance)
	253	+├── Custom Response Classes (enhance)
	254	+├── Middleware (enhance)
	255	+├── OpenAPI — Docs & Models (enhance)
	256	+├── Security Tools (enhance)
	257	+├── Encoders (enhance)
	258	+├── Static Files (enhance)
	259	+├── Templating — Jinja2Templates (enhance)
	260	+├── TestClient (enhance)
	261	+├── Schema — Validator & Fields (enhance)
	262	+└── Plugin System — Lifecycle Hooks (enhance)
	263	+
	264	+Deployment (10 pages, enhance existing)
	265	+├── Production Checklist (enhance)
	266	+├── About HTTPS (NEW)
	267	+├── Run a Server Manually (NEW)
	268	+├── Deployment Concepts (NEW)
	269	+├── Docker (enhance)
	270	+├── Kubernetes / Helm (enhance)
	271	+├── Server Workers — Workers & Concurrency (NEW)
	272	+├── Google Cloud (GKE) (enhance)
	273	+├── Amazon (EKS) (enhance)
	274	+├── Azure (AKS) (enhance)
	275	+├── Fly.io (enhance)
	276	+├── Railway (enhance)
	277	+└── Cloudflare Pages (enhance)
	278	+
	279	+Security (5 pages)
	280	+├── Security Policy (enhance)
	281	+├── OWASP Compliance (enhance)
	282	+├── Penetration Testing (enhance)
	283	+├── Secure Configuration (enhance)
	284	+└── Authentication & Authorization Guide (NEW)
	285	+
	286	+Observability (5 pages)
	287	+├── OpenTelemetry Tracing (enhance)
	288	+├── Prometheus Metrics (enhance)
	289	+├── Structured Logging (enhance)
	290	+├── Health Checks (enhance)
	291	+└── Alerting & Incident Response (NEW)
	292	+
	293	+Contributing (6 pages)
	294	+├── Development Setup (enhance)
	295	+├── Coding Standards (enhance)
	296	+├── Testing Guide (enhance)
	297	+├── Benchmarking Guide (enhance)
	298	+├── Documentation Guide (enhance)
	299	+└── Release Process (NEW)
	300	+
	301	+Inference / AI (6 pages, existing)
	302	+├── Overview (enhance)
	303	+├── GPU / CUDA Setup (enhance)
	304	+├── LLM Serving API (enhance)
	305	+├── Scheduling & Batching (enhance)
	306	+├── Quantization & LoRA (NEW)
	307	+└── OpenAI-Compatible API (NEW)
	308	+
	309	+Reference (8 pages)
	310	+├── CLI Reference (enhance)
	311	+├── Configuration Reference (enhance)
	312	+├── Error Codes (enhance)
	313	+├── ADR Index (enhance)
	314	+├── Glossary (enhance)
	315	+├── Release Notes (enhance)
	316	+├── Changelog (NEW)
	317	+└── Benchmarks (NEW, port from BENCHMARKS.md)
	318	+
	319	+Resources (4 pages, NEW section)
	320	+├── Help & Support (NEW)
	321	+├── External Links & Ecosystem (NEW)
	322	+├── Full Stack Project Template (NEW)
	323	+└── Newsletter / Community (NEW)
	324	+
	325	+About (4 pages, NEW section)
	326	+├── Alternatives, Inspiration & Comparisons (NEW)
	327	+├── History, Design & Future (NEW)
	328	+├── Benchmarks & Performance (NEW)
	329	+├── Repository Management (NEW)
	330	+└── License (NEW)
	331	+```
	332	+
	333	+Total planned pages: ~180+ (vs ~75 current, vs ~140 FastAPI)
270	334
271	335	---
272	336
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
	337	+### Phase 2: Tutorial Deep-Dive — Expand to 35+ Progressive Pages
	338	+
	339	+Pattern for each tutorial page (mirror FastAPI):
408	340
	341	+```
	342	+---
	343	+title: <Topic>
	344	+description: <SEO description>
	345	+keywords: [<tags>]
409	346	---
410	347
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)
	348	+# <Title>
	349	+
	350	+<2-3 sentence introduction>
	351	+
	352	+<Complete, runnable code example at top>
	353	+
	354	+## <Step 1>
	355	+
	356	+<Explanation with code snippets>
	357	+
	358	+:::tip
	359	+<Tip callout>
	360	+:::
	361	+
	362	+:::note
	363	+<Note callout>
	364	+:::
	365	+
	366	+## <Step N>
	367	+
	368	+<Screenshots of Swagger UI / ReDoc where applicable>
	369	+
	370	+## Recap
	371	+
	372	+<Summary of what was learned>
	373	+
	374	+## See Also
	375	+
	376	+- [Next Topic](/tutorial/next-topic/)
	377	+- [Related API Reference](/reference/related/)
	378	+```
	379	+
	380	+#### 2.1 New Tutorials to Write (24 missing)
	381	+
	382	+These are the tutorials FastAPI has that JustAPI doesn't:
	383	+
	384	+1. Python Types Intro — `str`, `int`, `float`, `bool`, `list`, `dict`, `Optional`, `Union`, `Literal`, `TypedDict`, `dataclass`. How JustAPI uses type hints.
	385	+2. Async / Await — When to use `async def` vs `def`, concurrency model, GIL implications.
	386	+3. Query Parameters & String Validations — `Query()` with `min_length`, `max_length`, `pattern`, `deprecated`.
	387	+4. Path Parameters & Numeric Validations — `Path()` with `ge`, `le`, `gt`, `lt`.
	388	+5. Query Parameter Models — Using Pydantic models for query params.
	389	+6. Body — Multiple Parameters — Mixing path, query, body, singular body values.
	390	+7. Body — Fields — `Field()` for Pydantic model fields.
	391	+8. Body — Nested Models — Sub-models, deeply nested JSON.
	392	+9. Declare Request Example Data — `example`, `examples` in schema.
	393	+10. Extra Data Types — `UUID`, `datetime`, `date`, `bytes`, `Decimal`, `Base64`.
	394	+11. Cookie Parameters — Reading cookies.
	395	+12. Header Parameters — Reading headers.
	396	+13. Cookie Parameter Models — Pydantic models for cookies.
	397	+14. Header Parameter Models — Pydantic models for headers.
	398	+15. Response Model — Return Type — `response_model`, filtering fields.
	399	+16. Extra Models — Multiple related models, inheritance.
	400	+17. Response Status Code — Setting custom status codes.
	401	+18. Form Data — `Form()` for non-JSON forms.
	402	+19. Form Models — Pydantic models for forms.
	403	+20. Request Files — `File()` and `UploadFile`.
	404	+21. Request Forms & Files — Combining forms and files.
	405	+22. Path Operation Configuration — `tags`, `summary`, `description`, `response_description`, `deprecated`, `include_in_schema`.
	406	+23. JSON Compatible Encoder — `jsonable_encoder`.
	407	+24. Body — Updates — PATCH vs PUT, partial updates.
	408	+
	409	+#### 2.2 Tutorials to Expand (11 existing)
	410	+
	411	+1. Hello World — Add Python version tabs, run with `uv` not just `python main.py`, add `curl` testing examples, add OpenAPI docs section.
	412	+2. Path & Query Parameters — Split into path params and query params separate pages. Add validation sections.
	413	+3. Request Body — Add nested models section, example data, Field usage.
	414	+4. Dependency Injection — Add sub-dependencies, classes as deps, global deps, yield deps.
	415	+5. Middleware — Add ASGI middleware, custom middleware, third-party middleware.
	416	+6. Error Handling — Add custom exception handlers, override default handlers.
	417	+7. File Uploads — Add form models, multiple file uploads.
	418	+8. Background Tasks — Add task dependencies, error handling.
	419	+9. WebSockets & SSE — Split into separate pages. Add testing WebSockets section.
	420	+10. Routing & Subrouters — Add path operation configuration, metadata.
	421	+11. Database Integration — Add async SQL, migrations, testing.
500	422
501	423	---
502	424
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)
	425	+### Phase 3: Advanced User Guide — Expand to 30+ Pages
	426	+
	427	+#### 3.1 Existing to Enhance (9 pages)
	428	+
	429	+1. Native Fast Path — Add performance comparison graphs, when to use `native=True` vs when not to.
	430	+2. Zero-GIL Architecture — Update with free-threaded Python 3.13t/3.14t section.
	431	+3. Rust Core Deep Dive — Add codebase navigation guide, key structs and traits.
	432	+4. PyO3 FFI Safety — Update with latest PyO3 patterns, `Bound` API.
	433	+5. Streaming Output — Add `@app.stream_json`, async generator patterns.
	434	+6. Agent System — Add MCP tool exposition guide, session management.
	435	+7. Multi-Protocol APIs — Add JSON-RPC and gRPC examples side-by-side.
	436	+8. Performance Tuning — Add worker config, connection pooling, `justapi.conf` reference.
	437	+9. Resilience Patterns — Add circuit breaker configuration, bulkhead, retry policies.
	438	+
	439	+#### 3.2 New Advanced Pages to Write (21 pages)
	440	+
	441	+1. Path Operation Advanced Configuration — `openapi_extra`, `response_model_exclude_unset`, etc.
	442	+2. Additional Status Codes — Returning custom status codes alongside 200.
	443	+3. Return a Response Directly — `Response`, `JSONResponse`, `HTMLResponse`.
	444	+4. Custom Response — HTML, Stream, File — `StreamingResponse`, `FileResponse`, `RedirectResponse`.
	445	+5. Additional Responses in OpenAPI — Documenting error responses, multiple response schemas.
	446	+6. Response Cookies — Setting and deleting cookies in responses.
	447	+7. Response Headers — Custom response headers.
	448	+8. Response — Change Status Code — Default status code override.
	449	+9. Advanced Dependencies — Parameterized dependencies, async generator deps.
	450	+10. Advanced Security — OAuth2 scopes, HTTP Basic Auth, API keys.
	451	+11. Using the Request Directly — Accessing raw request body, headers.
	452	+12. Using Dataclasses — Python dataclasses as request models.
	453	+13. Advanced Middleware — BaseHTTPMiddleware, ASGI middleware, third-party middleware integration.
	454	+14. Sub Applications — Mounts — Mounting sub-applications at sub-paths.
	455	+15. Behind a Proxy — `root_path`, `X-Forwarded-*` headers, reverse proxy config.
	456	+16. Templates (Jinja2) — Server-side rendering with Jinja2.
	457	+17. WebSockets Advanced — WebSocket connection management, broadcasting.
	458	+18. Lifespan Events — `startup`/`shutdown`, lifespan context manager.
	459	+19. Testing WebSockets — `TestClient` WebSocket testing.
	460	+20. Testing Events — Testing lifespan events.
	461	+21. Testing Dependencies with Overrides — `app.dependency_overrides`, test dependency injection.
	462	+22. Async Tests — `async` test functions, `httpx.AsyncClient`.
	463	+23. Settings & Environment Variables — Pydantic Settings, `.env` files.
	464	+24. OpenAPI Callbacks — Webhook request schemas in OpenAPI.
	465	+25. OpenAPI Webhooks — Outbound webhook definitions.
	466	+26. Including WSGI — Flask, Django — Mounting WSGI apps.
	467	+27. Generating SDKs — OpenAPI-based client generation (`openapi-generator`).
	468	+28. Strict Content-Type Checking — CSRF prevention, Content-Type enforcement.
575	469
576	470	---
577	471
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
	472	+### Phase 4: How-To Recipes (15 pages, NEW)
	473	+
	474	+A standalone section for specific, task-oriented recipes:
	475	+
	476	+1. General How-To — Common patterns and workarounds.
	477	+2. Migrate from Pydantic v1 — `Field` changes, `model_dump()` vs `dict()`, validators.
	478	+3. GraphQL Integration — Setting up Strawberry GraphQL alongside REST.
	479	+4. Custom Request & Route Classes — Extending `Request` and `APIRoute`.
	480	+5. Conditional OpenAPI — Disabling OpenAPI in production.
	481	+6. Extending OpenAPI — Adding custom OpenAPI fields.
	482	+7. Separate Input/Output Schemas — Benefits and configuration.
	483	+8. Custom Docs UI Assets — Self-hosting Swagger UI / ReDoc.
	484	+9. Configure Swagger UI — `swagger_ui_parameters`, themes, syntax highlighting.
	485	+10. Testing a Database — In-memory SQLite for tests, transaction rollback.
	486	+11. Custom Error Status Codes — 403 → 401 migration patterns.
	487	+12. gRPC Advanced Patterns — Streaming RPCs, interceptors, auth.
	488	+13. WASM Middleware Plugins — Writing and deploying wasmtime plugins.
	489	+14. Circuit Breaker Recipes — Configuring resilience patterns for specific scenarios.
	490	+15. Background Task Patterns — Prioritized tasks, task cancellation, progress reporting.
615	491
616	492	---
617	493
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
	494	+### Phase 5: API Reference — Auto-Generated from Docstrings
	495	+
	496	+Current state: 17 hand-written markdown pages.
	497	+Target: Auto-generated API reference from Python docstrings + Rust docstrings.
	498	+
	499	+#### 5.1 Tools & Implementation
	500	+
	501	+- Use `pydoc`-style generation or a Starlight plugin that parses Python stubs
	502	+- Generate from actual `.pyi` type stubs in `crates/justapi-py/python/justapi/`
	503	+- Document every public class, method, function, and parameter
	504	+- Each reference page includes:
	505	+ - Signature with type annotations
	506	+ - Description from docstring
	507	+ - Parameter table (name, type, default, description)
	508	+ - Example usage
	509	+ - See also links
	510	+
	511	+#### 5.2 Reference Pages to Create/Enhance
	512	+
	513	+\| # \| Page \| Source \| Priority \|
	514	+\|---\|---\|---\|---\|
	515	+\| 1 \| JustAPIApp \| `justapi/__init__.py` — FastAPI docstring style \| P0 \|
	516	+\| 2 \| Routing (`@app.get/post/etc`) \| Route decorators \| P0 \|
	517	+\| 3 \| APIRouter \| `justapi/routing.py` \| P0 \|
	518	+\| 4 \| Request \| Request object properties & methods \| P0 \|
	519	+\| 5 \| Response \| Response, JSONResponse, StreamingResponse \| P0 \|
	520	+\| 6 \| Dependencies \| `Depends()`, `Path()`, `Query()`, `Header()`, `Cookie()` \| P0 \|
	521	+\| 7 \| Exceptions \| `HTTPException`, `RequestValidationError` \| P0 \|
	522	+\| 8 \| WebSockets \| WebSocket handler, `WebSocket` class \| P0 \|
	523	+\| 9 \| Background Tasks \| `BackgroundTasks`, `add_task` \| P0 \|
	524	+\| 10 \| Schema & Validation \| `Schema`, `Field`, `body_schema` \| P0 \|
	525	+\| 11 \| UploadFile \| `UploadFile` properties & methods \| P0 \|
	526	+\| 12 \| Testing Client \| `JustAPITestClient`, `get`/`post`/etc \| P0 \|
	527	+\| 13 \| Middleware \| `add_middleware`, built-in middleware classes \| P1 \|
	528	+\| 14 \| Security Tools \| JWT, OAuth2 utilities \| P1 \|
	529	+\| 15 \| OpenAPI \| Docs UI configuration, `openapi.json` \| P1 \|
	530	+\| 16 \| Static Files \| `Mount` static files \| P1 \|
	531	+\| 17 \| Templating \| Jinja2Templates \| P1 \|
	532	+\| 18 \| Scheduler \| `PyScheduler`, cron/interval/once \| P1 \|
	533	+\| 19 \| Plugins \| Plugin lifecycle hooks \| P1 \|
	534	+\| 20 \| Session \| Session properties, agent state \| P1 \|
	535	+\| 21 \| Status Codes \| `status` module reference \| P2 \|
654	536
655	537	---
656	538
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
	539	+### Phase 6: Deployment — Expand to 12 Pages
	540	+
	541	+Current: 9 deployment pages.
	542	+
	543	+Enhancements:
	544	+1. Production Checklist — Add Redis config, database pooling, logging levels, monitoring setup.
	545	+2. About HTTPS — NEW. TLS termination, certbot, rustls, Let's Encrypt.
	546	+3. Run a Server Manually — NEW. `justapi serve` flags, `--workers`, `--port`, `--host`.
	547	+4. Deployment Concepts — NEW. Concurrency, workers, auto-scaling, resource limits.
	548	+5. Docker — Add `docker-compose` examples with Redis, PostgreSQL, Prometheus.
	549	+6. Kubernetes / Helm — Add auto-scaling config, ingress examples, resource requests/limits.
	550	+7. Server Workers — NEW. Uvicorn workers vs JustAPI workers, Gunicorn integration.
	551	+8. Cloud deployment guides — Port from `deploy/` to docs_site with screenshots and CLI steps.
706	552
707	553	---
708	554
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
	555	+### Phase 7: Security & Observability — Expand and Polish
	556	+
	557	+Security (5 pages):
	558	+- Add new Authentication & Authorization Guide — OAuth2 flows, JWT, API keys, RBAC.
	559	+- Enhance existing pages with screenshots, config examples, and troubleshooting.
	560	+
	561	+Observability (5 pages):
	562	+- Add new Alerting & Incident Response — Prometheus AlertManager, PagerDuty integration, SLIs/SLOs.
	563	+- Enhance existing with Grafana dashboard JSON examples.
758	564
759	565	---
760	566
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
	567	+### Phase 8: Inference / AI Section (6 pages)
	568	+
	569	+Current: 4 pages.
	570	+Add:
	571	+- Quantization & LoRA — Model quantization, LoRA adapter serving.
	572	+- OpenAI-Compatible API — `/v1/chat/completions` endpoint, token streaming, function calling.
794	573
795	574	---
796	575
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)
	576	+### Phase 9: Resources, About, and Polish Sections
	577	+
	578	+Resources (NEW — 4 pages):
	579	+1. Help & Support — GitHub Issues, Discord, Stack Overflow, FAQ.
	580	+2. External Links & Ecosystem — Related projects, plugins, community tools.
	581	+3. Full Stack Project Template — Guide to using the `justapi create` full-stack template.
	582	+4. Newsletter / Community — RSS feed, mailing list, social links.
	583	+
	584	+About (NEW — 5 pages):
	585	+1. Alternatives, Inspiration & Comparisons — Port and expand from README competitors section.
	586	+2. History, Design & Future — Why Rust, design decisions (port from DECISIONS.md).
	587	+3. Benchmarks & Performance — Port from BENCHMARKS.md into searchable, navigable format.
	588	+4. Repository Management — Maintainers, governance, release process.
	589	+5. License — MIT License text.
818	590
819	591	---
820	592
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
	593	+### Phase 10: Infrastructure & CI
	594	+
	595	+#### 10.1 Auto-Generation Pipeline
	596	+- Create a script (`scripts/gen_api_ref.py`) that parses `crates/justapi-py/python/justapi/` `.pyi` stubs and generates Starlight markdown pages in `docs_site/src/content/docs/reference/`
	597	+- Run this script as part of the docs build (`astro build`)
	598	+
	599	+#### 10.2 Deployment
	600	+- Cloudflare Pages (current target) — already configured
	601	+- Add PR preview deployments for docs changes
	602	+- Add link checker in CI for docs builds
	603	+- Add spell checker (`cspell`) for documentation
	604	+
	605	+#### 10.3 CI Integration
	606	+- Add docs build to `wheels.yml` (or a separate `docs.yml`)
	607	+- Fail build on broken links
	608	+- Auto-deploy on merge to `main`/`master`
	609	+
	610	+#### 10.4 SEO & Performance
	611	+- Sitemap generation (`@astrojs/sitemap`)
	612	+- OpenGraph + Twitter Card meta tags on every page
	613	+- Canonical URLs
	614	+- Pagefind full-text search
	615	+- RSS feed for release notes (`@astrojs/rss`)
	616	+- Lighthouse target: 100/100
862	617
863	618	---
864	619
865		-## Phase 13: Content Audit & Gap Analysis
	620	+## 3. Page Templates
866	621
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
	622	+### 3.1 Tutorial Page Template
906	623
	624	+```markdown
	625	+---
	626	+title: <Topic Title>
	627	+description: <2-line SEO description>
	628	+keywords: [JustAPI, <topic>, Python web framework, FastAPI alternative]
907	629	---
908	630
909		-## Implementation Roadmap
	631	+# <Topic Title>
	632	+
	633	+<2-3 sentence introduction explaining what this page covers and why it matters.
	634	+
	635	+## <First Concept>
910	636
	637	+<Clear explanation with code snippet>
	638	+
	639	+```python
	640	+# Example code
911	641	```
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
	642	+
	643	+:::tip
	644	+<Tip that helps the reader>
	645	+:::
	646	+
	647	+## <Second Concept>
	648	+
	649	+<Screenshot or diagram if applicable>
	650	+
	651	+![Swagger UI showing the feature](/img/tutorial/<path>.png)
	652	+
	653	+## Recap
	654	+
	655	+<Bullet-point summary of what was learned>
	656	+
	657	+## See Also
	658	+
	659	+- <Next logical tutorial>
	660	+- <Related API reference>
926	661	```
927	662
928		-Total new pages: ~75 (enhancements to 6 existing pages, ~69 completely new)
	663	+### 3.2 Reference Page Template
929	664
	665	+```markdown
	666	+---
	667	+title: <Class/Function Name>
	668	+description: API reference for <class/function>
	669	+keywords: [JustAPI, <class/function>, API reference]
930	670	---
931	671
932		-## Key Design Principles
	672	+# `<Class/Function Name>`
933	673
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
	674	+<Description of what this does>
942	675
	676	+## Signature
	677	+
	678	+```python
	679	+<def signature with types>
	680	+```
	681	+
	682	+## Parameters
943	683
944		-## Directory Structure (Target)
	684	+\| Parameter \| Type \| Default \| Description \|
	685	+\|-----------\|------\|---------\|-------------\|
	686	+\| `<name>` \| `<type>` \| `<default>` \| <description> \|
945	687
	688	+## Example
	689	+
	690	+```python
	691	+<runnable example>
946	692	```
947		-docs_site/
948		-├── astro.config.mjs
949		-├── package.json
950		-├── tsconfig.json
951		-├── public/
952		-│ ├── favicon.svg
953		-│ └── og-image.png
954		-├── src/
955		-│ ├── assets/
956		-│ │ ├── logo.svg
957		-│ │ ├── architecture.svg
958		-│ │ └── bench-comparison.png
959		-│ ├── components/
960		-│ │ ├── BenchTable.astro # Reusable benchmark comparison table
961		-│ │ ├── CodeExample.astro # Styled code block with copy button
962		-│ │ ├── ArchitectureDiagram.astro # Mermaid diagram component
963		-│ │ ├── FeatureCard.astro # Feature highlight card
964		-│ │ ├── CompatibilityBadge.astro # FastAPI/Starlette parity badge
965		-│ │ └── Callout.astro # Info/warning/tip callout
966		-│ ├── content/
967		-│ │ ├── config.ts
968		-│ │ └── docs/
969		-│ │ ├── index.mdx
970		-│ │ ├── getting-started/
971		-│ │ │ ├── overview.md
972		-│ │ │ ├── installation.md
973		-│ │ │ ├── first-steps.md
974		-│ │ │ ├── cli-scaffolder.md
975		-│ │ │ └── migrating-from-fastapi.md
976		-│ │ ├── tutorials/
977		-│ │ │ ├── hello-world.md
978		-│ │ │ ├── path-query-params.md
979		-│ │ │ ├── request-body.md
980		-│ │ │ ├── dependency-injection.md
981		-│ │ │ ├── middleware.md
982		-│ │ │ ├── error-handling.md
983		-│ │ │ ├── file-uploads.md
984		-│ │ │ ├── websockets-sse.md
985		-│ │ │ ├── database-integration.md
986		-│ │ │ ├── background-tasks.md
987		-│ │ │ └── routing-subrouters.md
988		-│ │ ├── api-reference/
989		-│ │ │ ├── index.md
990		-│ │ │ ├── justapiapp.md
991		-│ │ │ ├── routing.md
992		-│ │ │ ├── apirouter.md
993		-│ │ │ ├── request.md
994		-│ │ │ ├── responses.md
995		-│ │ │ ├── dependency-injection.md
996		-│ │ │ ├── exceptions.md
997		-│ │ │ ├── schema-validation.md
998		-│ │ │ ├── websockets.md
999		-│ │ │ ├── background-tasks.md
1000		-│ │ │ ├── scheduler.md
1001		-│ │ │ ├── session.md
1002		-│ │ │ ├── plugins.md
1003		-│ │ │ ├── testing-client.md
1004		-│ │ │ ├── uploadfile.md
1005		-│ │ │ └── database.md
1006		-│ │ ├── advanced/
1007		-│ │ │ ├── zero-gil-architecture.md
1008		-│ │ │ ├── rust-core-deep-dive.md
1009		-│ │ │ ├── pyo3-ffi-safety.md
1010		-│ │ │ ├── native-fast-path.md
1011		-│ │ │ ├── multi-protocol-apis.md
1012		-│ │ │ ├── agent-system.md
1013		-│ │ │ ├── streaming-output.md
1014		-│ │ │ ├── performance-tuning.md
1015		-│ │ │ └── resilience-patterns.md
1016		-│ │ ├── deployment/
1017		-│ │ │ ├── docker.md
1018		-│ │ │ ├── kubernetes-helm.md
1019		-│ │ │ ├── cloudflare-pages.md
1020		-│ │ │ ├── gke.md
1021		-│ │ │ ├── eks.md
1022		-│ │ │ ├── aks.md
1023		-│ │ │ ├── flyio.md
1024		-│ │ │ ├── railway.md
1025		-│ │ │ └── production-checklist.md
1026		-│ │ ├── security/
1027		-│ │ │ ├── policy.md
1028		-│ │ │ ├── owasp-compliance.md
1029		-│ │ │ ├── penetration-testing.md
1030		-│ │ │ └── secure-configuration.md
1031		-│ │ ├── observability/
1032		-│ │ │ ├── metrics-monitoring.md
1033		-│ │ │ ├── opentelemetry.md
1034		-│ │ │ ├── structured-logging.md
1035		-│ │ │ └── health-checks.md
1036		-│ │ ├── reference/
1037		-│ │ │ ├── cli.md
1038		-│ │ │ ├── configuration.md
1039		-│ │ │ ├── release-notes.md
1040		-│ │ │ ├── adr-index.md
1041		-│ │ │ ├── error-codes.md
1042		-│ │ │ └── glossary.md
1043		-│ │ ├── contributing/
1044		-│ │ │ ├── development-setup.md
1045		-│ │ │ ├── coding-standards.md
1046		-│ │ │ ├── testing-guide.md
1047		-│ │ │ ├── benchmarking-guide.md
1048		-│ │ │ └── documentation-guide.md
1049		-│ │ ├── inference/
1050		-│ │ │ ├── overview.md
1051		-│ │ │ ├── llm-serving-api.md
1052		-│ │ │ ├── gpu-cuda-setup.md
1053		-│ │ │ └── scheduling-batching.md
1054		-│ │ └── examples/
1055		-│ │ └── index.md
1056		-│ └── styles/
1057		-│ └── custom.css # Expanded design system
1058		-└── dist/ # Build output
	693	+
	694	+## See Also
	695	+
	696	+- <Related tutorial>
	697	+- <Related reference>
1059	698	```
1060	699
1061	700	---
1062	701
1063		-## Execution Priorities
1064		-
1065		-### Required for MVP (v1 docs site launch)
1066		-1. Phase 0: Site nav + design system
1067		-2. Phase 1: All Getting Started (complete — already have 4/5 pages)
1068		-3. Phase 2: Tutorials (most user-facing value)
1069		-4. Phase 3: API Reference (most referenced by users)
1070		-5. Phase 5.9: Production Checklist (critical for ops audience)
1071		-6. Phase 6: Security (trust signal)
1072		-7. Phase 8.1: CLI Reference (dev tool UX)
1073		-8. Phase 9: Contributing Guide (community growth)
1074		-
1075		-### v2 enhancements
1076		-9. Phase 4: Advanced Guides (deep technical audience)
1077		-10. Phase 5: Cloud Deployment Guides (multi-cloud)
1078		-11. Phase 7: Observability (production operations)
1079		-12. Phase 10: Inference (AI/ML audience)
1080		-13. Phase 11: Examples Gallery
1081		-
1082		-### Ongoing
1083		-14. Phase 8.3: Release Notes + Changelog (per-release updates)
1084		-15. Phase 12.2: CI/CD for docs (continuous deployment)
1085		-16. Phase 12.4: Quality assurance (link checking, Lighthouse)
	702	+## 4. Implementation Order
1086	703
	704	+\| Phase \| Priority \| Pages \| Effort \| Depends On \|
	705	+\|---\|---\|---\|---\|---\|
	706	+\| Phase 1: IA & Nav \| P0 \| Sidebar config \| 1 day \| Nothing \|
	707	+\| Phase 2: Tutorial Expansion \| P0 \| +24 new tutorials, 11 enhanced \| 3 weeks \| Phase 1 \|
	708	+\| Phase 3: Advanced Guide \| P1 \| +21 new, 9 enhanced \| 2 weeks \| Phase 1 \|
	709	+\| Phase 5: API Reference \| P0 \| 21 pages auto-generated \| 1 week \| Phase 1 \|
	710	+\| Phase 4: How-To Recipes \| P1 \| 15 new pages \| 1 week \| Phase 1 \|
	711	+\| Phase 6: Deployment \| P1 \| +3 new, 9 enhanced \| 3 days \| Phase 1 \|
	712	+\| Phase 7: Security & O11y \| P2 \| +2 new, 8 enhanced \| 2 days \| Phase 1 \|
	713	+\| Phase 8: Inference \| P2 \| +2 new, 4 enhanced \| 2 days \| Phase 1 \|
	714	+\| Phase 9: Resources & About \| P2 \| 9 new pages \| 2 days \| Phase 1 \|
	715	+\| Phase 10: Infrastructure \| P2 \| CI, auto-gen, SEO \| 3 days \| Phase 5 \|
1087	716
1088		-## Success Metrics
1089		-
1090		-\| Metric \| Target \|
1091		-\|---\|---\|
1092		-\| Page coverage \| 100% of public API documented \|
1093		-\| Interactive examples \| Every tutorial page has runnable code \|
1094		-\| Search \| Any concept findable within 2 Pagefind queries \|
1095		-\| Lighthouse \| 100/100 Performance, Accessibility, Best Practices, SEO \|
1096		-\| Load time \| <1s to First Contentful Paint \|
1097		-\| Broken links \| 0 (CI-enforced) \|
1098		-\| Mobile \| All pages pass mobile viewport test \|
1099		-\| Accessibility \| WCAG 2.1 AA compliance \|
1100		-\| Docs build time \| <30s in CI \|
1101		-\| Deployment \| Auto-deploy on merge to main (Cloudflare Pages) \|
	717	+Total estimated effort: ~8-10 weeks for a single contributor.
1102	718
1103	719	---
1104	720
1105		-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.
	721	+## 5. Success Criteria
	722	+
	723	+- [ ] Sidebar structure mirrors FastAPI — learning-path-first with progressive tutorials
	724	+- [ ] Tutorial — User Guide has 35+ progressive lessons with code, screenshots, and recaps
	725	+- [ ] Advanced User Guide has 30+ pages covering every framework feature
	726	+- [ ] API Reference auto-generated from `.pyi` stubs with full parameter docs
	727	+- [ ] How-To Recipes has 15 standalone task guides
	728	+- [ ] Deployment covers all 5 cloud providers with screenshots
	729	+- [ ] Security & Observability include configuration examples and dashboard JSON
	730	+- [ ] Resources, About, and Reference sections complete the 180-page target
	731	+- [ ] All pages have SEO meta tags, OpenGraph, and breadcrumbs
	732	+- [ ] docs build passes CI with no broken links
	733	+- [ ] Lighthouse 100/100 on all categories
	734	+- [ ] Search (Pagefind) indexes all content with section-level granularity
1106	735