diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml
new file mode 100644
index 0000000..0672f46
--- /dev/null
+++ b/.github/workflows/docs-quality.yml
@@ -0,0 +1,87 @@
+name: Documentation Quality
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "*.md"
+      - "tests/README.md"
+      - "scripts/*.md"
+      - "scripts/check-*.py"
+      - ".github/workflows/docs-quality.yml"
+      - ".markdownlint-cli2.yaml"
+      - "cspell.json"
+      - "lychee.toml"
+      - "requirements-test.txt"
+      - "pytest.ini"
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "*.md"
+      - "tests/README.md"
+      - "scripts/*.md"
+      - "scripts/check-*.py"
+      - ".github/workflows/docs-quality.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DavidAnson/markdownlint-cli2-action@v19
+        with:
+          globs: |
+            **/*.md
+            !venv/**
+            !.venv/**
+            !node_modules/**
+            !site/**
+            !docs/tmp/**
+
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check external links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --config lychee.toml --no-progress .
+          fail: true
+          jobSummary: true
+
+  spell-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check spelling
+        uses: streetsidesoftware/cspell-action@v6
+        with:
+          config: cspell.json
+          files: "**/*.md"
+          inline: error
+          incremental_files_only: false
+          strict: true
+
+  validate-codeblocks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Validate Python code blocks in markdown
+        run: python3 scripts/check-codeblocks.py
+
+  check-doc-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Check documentation covers all routes and modules
+        run: python3 scripts/check-doc-coverage.py
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..1e01069
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,45 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install mkdocs-material mkdocstrings mkdocstrings-python pymdown-extensions
+      - run: python3 scripts/sync-docs.py
+      - run: mkdocs build --site-dir site
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
index 6dc2c74..13dd4b7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,9 @@ tmp/
 docs/tmp/
 CTFd-Docker-Challenges/
 
+# MkDocs build output
+site/
+
 # Database
 instance/
 uploads/
@@ -29,4 +32,7 @@ catering_sql_lab.db
 # OS files
 .DS_Store
 
+# Command Code (AI coding assistant state)
+.commandcode/
+
 # Core maintainers only: optional commit-msg in .git/hooks/ (local-only, never pushed).
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
new file mode 100644
index 0000000..4cafe99
--- /dev/null
+++ b/.markdownlint-cli2.yaml
@@ -0,0 +1,41 @@
+# Markdownlint configuration for PwnzzAI docs
+# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+default: true
+
+# Allow inline HTML (needed for <img>, <a>, <video> embeds)
+MD033: false
+
+# Allow line length (URLs and table rows exceed 80 chars)
+MD013: false
+
+# Allow duplicate headings (labs reuse "Overview", "Setup")
+MD024: false
+
+# Allow bare URLs without angle brackets
+MD034: false
+
+# Allow emphasis used instead of heading
+MD036: false
+
+# Allow trailing punctuation in headings ("Why?")
+MD026: false
+
+# Allow first line not being H1
+MD041: false
+
+# Allow code blocks without language spec
+MD040: false
+
+# Allow dollar signs in code blocks (command examples)
+MD014: false
+
+# Allow spaces after hash for atx-style headings
+MD019: false
+MD021: false
+
+# Allow underscore in filenames (doc_standards.md)
+MD045: false
+
+# Allow indented code blocks (some legacy)
+MD046: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ac80540..db45995 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,7 +27,7 @@ You can contribute to PwnzzAI Shop in several ways:
 - **New Vulnerabilities**: Add demonstrations of additional LLM vulnerabilities
 - **Documentation**: Improve explanations, tutorials, or documentation
 - **Test Coverage**: Add or improve test cases
-- **Security Mitigations**: Enhance security soutions in the mitigation strategies sections
+- **Security Mitigations**: Enhance security solutions in the mitigation strategies sections
 - **Model Support**: Add support for additional LLM models
 - **UI/UX Improvements**: Enhance the user interface or user experience
 - **Code Quality**: Refactor code for better maintainability
@@ -118,4 +118,42 @@ Use the Docker smoke test routine before pushing to GitHub. It validates local D
 APP_IMAGE=pwnzzai:my-local-test ./scripts/docker-smoke-test.sh
 ```
 
-The script cleans up test containers automatically when it exits.
\ No newline at end of file
+The script cleans up test containers automatically when it exits.
+
+## Coding Standards
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) with a soft 100-character line limit.
+- Use meaningful variable and function names.
+- Add type hints to function signatures where practical.
+- Write docstrings for public functions and classes.
+- Use `snake_case` for variables and functions, `PascalCase` for classes.
+- Keep functions small and single-purpose.
+- Avoid adding comments that describe what the code does — let the code speak for itself. Use comments only for non-obvious intent.
+
+For docs contributions, see [Doc Standards](docs/community/doc-standards.md).
+
+## Submitting Changes
+
+1. Ensure all tests pass: `pytest -v`
+2. Run the Docker smoke test if you changed infrastructure: `./scripts/docker-smoke-test.sh`
+3. Rebase your branch onto the latest `main` before opening a PR
+4. Write a clear PR title and description
+5. Reference any related issues in the PR body
+6. Keep PRs focused — one change per PR
+
+## Reporting Issues
+
+Use GitHub Issues to report bugs, suggest features, or ask questions.
+
+- **Bug report**: Include steps to reproduce, expected vs actual behavior, and your environment (OS, Python version, Docker version)
+- **Feature request**: Describe the problem you're solving and how your suggestion helps
+- **Question**: Use the [OWASP AI Exchange Discussions](https://github.com/OWASP/PwnzzAI/discussions)
+
+## Security Considerations
+
+This project contains intentional vulnerabilities for educational purposes.
+
+- **Never** submit a PR that fixes a documented lab vulnerability without prior discussion — these are features
+- New vulnerability contributions must include a hardened alternative (mode flag or separate endpoint)
+- Do not commit real API keys, credentials, or PII — use example values
+- If you discover an accidental vulnerability that is not part of the curriculum, follow the [Responsible Disclosure](docs/security/disclosure.md) process
\ No newline at end of file
diff --git a/Makefile b/Makefile
index 81fb4aa..821f0a4 100644
--- a/Makefile
+++ b/Makefile
@@ -19,6 +19,7 @@ PWNZZAI_IMAGE   ?= ghcr.io/maryammouzarani2024/pwnzzai:latest
 LOCAL_IMAGE     ?= pwnzzai-local:dev
 TEST_IMAGE      ?= pwnzzai:test-ci
 APP_PORT        ?= 8080
+DOCS_SITE_DIR   ?= site
 OLLAMA_MODEL    ?= llama3.2:1b
 
 export FLASK_APP ?= main.py
@@ -353,3 +354,53 @@ register-challenge-py: ## python3 deploy/register_pwnzzai_challenge.py (env from
 .PHONY: reregister-challenge-py
 reregister-challenge-py: ## python3 deploy/reregister_pwnzzai_challenge.py
 	python3 deploy/reregister_pwnzzai_challenge.py
+
+# =============================================================================
+# Documentation (MkDocs)
+# =============================================================================
+
+.PHONY: sync-docs
+sync-docs: ## Copy canonical files into docs/ before build (single source of truth)
+	python3 scripts/sync-docs.py
+
+.PHONY: docs
+docs: sync-docs ## Build MkDocs site (runs sync-docs first)
+	mkdocs build --site-dir $(DOCS_SITE_DIR)
+
+.PHONY: docs-serve
+docs-serve: sync-docs ## Serve MkDocs locally with live reload (runs sync-docs first)
+	mkdocs serve
+
+# =============================================================================
+# Documentation Quality (local)
+# =============================================================================
+
+.PHONY: install-docs-qa
+install-docs-qa: ## Install doc quality tools (pytest-codeblocks)
+	"$(PYTHON)" -m pip install pytest-codeblocks
+
+.PHONY: check-codeblocks
+check-codeblocks: ## Validate Python code blocks in documentation (scripts/check-codeblocks.py)
+	python3 scripts/check-codeblocks.py
+
+.PHONY: check-doc-coverage
+check-doc-coverage: ## Check all routes and vulnerability modules are documented (scripts/check-doc-coverage.py)
+	python3 scripts/check-doc-coverage.py
+
+.PHONY: check-links
+check-links: ## Check external links in markdown (requires lychee, or runs in CI)
+	@if command -v lychee >/dev/null 2>&1; then lychee --config lychee.toml .; \
+	else printf '%s\n' "lychee not found. Install: cargo install lychee, or let CI run this check." >&2; fi
+
+.PHONY: check-spelling
+check-spelling: ## Spell-check docs (requires cspell, or runs in CI)
+	@if command -v cspell >/dev/null 2>&1; then cspell --config cspell.json "**/*.md" --no-summary; \
+	else printf '%s\n' "cspell not found. Install: npm install -g cspell, or let CI run this check." >&2; fi
+
+.PHONY: check-markdown
+check-markdown: ## Lint markdown style (requires markdownlint-cli2, or runs in CI)
+	@if command -v markdownlint-cli2 >/dev/null 2>&1; then markdownlint-cli2 "**/*.md" "#venv" "#.venv" "#node_modules" "#site" "#docs/tmp"; \
+	else printf '%s\n' "markdownlint-cli2 not found. Install: npm install -g markdownlint-cli2, or let CI run this check." >&2; fi
+
+.PHONY: check-docs
+check-docs: check-markdown check-links check-spelling check-codeblocks check-doc-coverage ## Run all doc quality checks (best-effort locally, authoritative in CI)
diff --git a/README.md b/README.md
index 3f527e4..82e31a1 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ Here, you'll explore **practical examples** of how vulnerabilities are created,
    - [Option 2: Docker (Your Own Ollama + PwnzzAI Image)](#option-2-docker-your-own-ollama--pwnzzai-image)
    - [Option 3: Run Source Code Yourself](#option-3-run-source-code-yourself)
    - [Troubleshooting: Ollama Connection (WSL + Docker)](OLLAMA_CONNECTION_TROUBLESHOOTING.md)
-   - [Workshop hosts: choosing OpenAI, Claude, Gemini, or other cloud models](docs/workshop-cloud-llm-setup.md)
+   - [Workshop hosts: choosing OpenAI, Claude, Gemini, or other cloud models](docs/ops/cloud-setup.md)
 - [Features](#features)
 - [AI Security Coverage](#ai-security-coverage)
   - [Learning Framework](#learning-framework)
@@ -79,7 +79,7 @@ cp .env.example .env
 #   (or LITELLM_MODEL=gemini/gemini-2.5-flash, etc.)
 ```
 
-Restart the app after editing `.env`. For a full provider/model walkthrough, see [Workshop hosts: choosing OpenAI, Claude, Gemini, or other cloud models](docs/workshop-cloud-llm-setup.md).
+Restart the app after editing `.env`. For a full provider/model walkthrough, see [Workshop hosts: choosing OpenAI, Claude, Gemini, or other cloud models](docs/ops/cloud-setup.md).
 
 ### Option 1: Docker (PwnzzAI + Ollama)
 
@@ -335,4 +335,25 @@ and,
 - **Ollama Models**: Free models, such as Mistral 7B and LLaMA 3.2 1B, are accessible through Ollama.
 
 
+## Documentation
+
+Full MkDocs site in `docs/` (built with Material theme, Mermaid diagrams, mkdocstrings).
+
+**Single source of truth rule:** content lives in one place — root files (`README.md`, `CONTRIBUTING.md`, `OLLAMA_CONNECTION_TROUBLESHOOTING.md`, `tests/README.md`, `.env.example`) are the canonical versions. Copying into `docs/` happens automatically before every build via:
+
+```bash
+make docs          # sync + mkdocs build
+make docs-serve    # sync + mkdocs serve
+```
+
+Available docs:
+
+- **[Architecture](docs/ARCHITECTURE.md)** — System design, module dependencies, request lifecycle (Mermaid diagrams)
+- **[API Reference](docs/API_REFERENCE.md)** — Complete endpoint documentation with request/response formats
+- **[Developer Guide](docs/DEVELOPER_GUIDE.md)** — Adding new vulnerabilities, doc workflow, coding conventions
+- **[Escalation Ladder](docs/ESCALATION_LADDER.md)** — B0–B9 prompt injection stages, defense techniques
+- **[Environment Variables](docs/ENVIRONMENT_VARIABLES.md)** — Precedence chains for all config vars
+- **[Challenge Solutions](docs/CHALLENGE_SOLUTIONS.md)** — Walkthrough scaffold for all challenges
+- **[Cloud LLM Setup](docs/ops/cloud-setup.md)** — Workshop provider configuration
+
 **⚠️ Educational Purpose Only**: This application contains intentional security vulnerabilities. Do not use in production environments.
diff --git a/application/static/img/barbecue-chicken-pizza-0917.jpg b/application/static/img/barbecue-chicken-pizza-0917.jpg
new file mode 100644
index 0000000..e69de29
diff --git a/cspell.json b/cspell.json
new file mode 100644
index 0000000..afdb744
--- /dev/null
+++ b/cspell.json
@@ -0,0 +1,76 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "ignorePaths": [
+    "venv/**",
+    ".venv/**",
+    "node_modules/**",
+    "site/**",
+    "docs/tmp/**",
+    "**/*.py",
+    "**/*.yml",
+    "**/*.yaml",
+    "**/*.toml",
+    "**/*.ini",
+    "**/*.cfg",
+    "**/*.lock",
+    "**/*.css",
+    "**/*.js",
+    "**/*.jinja2",
+    "**/*.html"
+  ],
+  "words": [
+    "pwnzzai",
+    "PwnzzAI",
+    "pwnz",
+    "Ollama",
+    "ollama",
+    "CTFd",
+    "mkdocs",
+    "mkdocstrings",
+    "pymdownx",
+    "superfences",
+    "admonition",
+    "pyzbar",
+    "litellm",
+    "sqlalchemy",
+    "SQLAlchemy",
+    "jinja",
+    "Jinja",
+    "werkzeug",
+    "dotenv",
+    "scikit",
+    "faiss",
+    "transformers",
+    "LogisticRegression",
+    "CountVectorizer",
+    "preconfigured",
+    "exfil",
+    "exfiltration",
+    "guardrails",
+    "hardened",
+    "misinfo",
+    "testpaths",
+    "norecursedirs",
+    "codeblocks",
+    "pytest",
+    "ruff",
+    "changelog",
+    "CHANGELOG",
+    "ROADMAP",
+    "backend",
+    "lifecycle",
+    "vulnerability",
+    "vulnerabilities",
+    "repo",
+    "UI",
+    "UX",
+    "sandboxing",
+    "healthcheck",
+    "dockerized",
+    "handoffs",
+    "Dockerfile",
+    "Dockerfiles",
+    "dockerignore"
+  ]
+}
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..1380afe
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,95 @@
+# PwnzzAI Documentation
+
+<img src="index.png" alt="PwnzzAI Shop" width="140" align="right">
+
+PwnzzAI is an open-source, hands-on security education platform built and
+maintained in partnership with the **[OWASP AI Exchange](https://owaspai.org/)**.
+Delivered as an intentionally vulnerable pizza shop web application, it provides
+practical, interactive demonstrations of LLM vulnerabilities across the OWASP
+Top 10 for LLM Applications and AI Exchange threat taxonomy.
+
+The platform supports dual-provider execution — local models via Ollama and
+cloud models via LiteLLM (OpenAI, Gemini, Claude) — making it suitable for
+both self-paced learning and instructor-led workshops.
+
+---
+
+## Getting Started
+
+| Guide | Description |
+|-------|-------------|
+| [Deploy with Docker](ops/docker-orchestration.md) | Run PwnzzAI and Ollama in containers |
+| [Run from Source](developer/getting-started.md) | Python virtual environment setup |
+| [Cloud LLM Configuration](ops/cloud-setup.md) | Connect OpenAI, Gemini, or Claude |
+| [Environment Variables](ops/env-variables.md) | Full configuration reference |
+
+---
+
+## Lab Catalog
+
+| Guide | Description |
+|-------|-------------|
+| [Platform Overview](labs/overview.md) | Navigation, accounts, and provider tabs |
+| [Lab Index](labs/scenario-list.md) | All 16 labs with page URLs and API endpoints |
+| [Escalation Ladder](labs/lab-format.md) | B0–B9 direct prompt injection stages |
+
+---
+
+## Developer Resources
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](developer/getting-started.md) | Development environment and conventions |
+| [Codebase Map](developer/codebase-map.md) | Module layout and directory structure |
+| [Adding Features](developer/adding-features.md) | How to contribute a new vulnerability |
+| [API Reference](developer/api-reference.md) | Complete endpoint documentation |
+| [API Modules](developer/api-modules.md) | Python module reference |
+
+---
+
+## Architecture
+
+| Guide | Description |
+|-------|-------------|
+| [System Overview](architecture/overview.md) | Stack, dependencies, and request lifecycle |
+| [Data Flow](architecture/data-flow.md) | Provider resolution and detection pipelines |
+| [Threat Model](architecture/threat-model.md) | Risk coverage mapped to OWASP categories |
+
+---
+
+## Quality & Operations
+
+| Guide | Description |
+|-------|-------------|
+| [Testing Guide](quality-assurance/testing-guide.md) | Test suite structure and CI integration |
+| [Security Checks](quality-assurance/security-checks.md) | Per-lab verification procedures |
+| [Docker Orchestration](ops/docker-orchestration.md) | Compose architecture and networking |
+| [Troubleshooting](ops/troubleshooting.md) | Common issues and fixes |
+
+---
+
+## Contributing & Policies
+
+| Guide | Description |
+|-------|-------------|
+| [Contributing](community/contributing.md) | PR workflow, coding standards, and issue reporting |
+| [Documentation Standards](community/doc-standards.md) | Doc conventions and sync rules |
+| [Responsible Disclosure](security/disclosure.md) | How to report security issues |
+| [Usage Policy](security/usage-policy.md) | Acceptable use and disclaimers |
+| [Data Privacy](security/data-privacy.md) | Session handling and data isolation |
+
+---
+
+## Releases
+
+| Guide | Description |
+|-------|-------------|
+| [Changelog](releases/CHANGELOG.md) | Version history |
+| [Roadmap](releases/ROADMAP.md) | Planned features and milestones |
+
+---
+
+!!! warning "Educational Purpose Only"
+    This application contains intentional security vulnerabilities designed for
+    learning. Do not deploy in production, expose to untrusted networks, or
+    store real user data.
diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md
new file mode 100644
index 0000000..62db51e
--- /dev/null
+++ b/docs/architecture/data-flow.md
@@ -0,0 +1,153 @@
+# Data Flow
+
+This document describes how requests move through the application, from browser
+to LLM backend and back.
+
+## Request Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant B as Browser
+    participant F as Flask
+    participant DB as Database
+    participant P as Provider Config
+    participant LLM as LLM Backend
+
+    B->>F: HTTP Request
+    F->>F: before_request → _ensure_db_ready()
+    F->>DB: Self-heal tables if missing
+    F->>F: Route function executes
+
+    alt Page Route (GET)
+        F->>F: Render Jinja2 template
+        F->>P: Inject llm_ui context
+        F-->>B: HTML Response
+
+    else LLM API Route (POST)
+        F->>P: resolve_provider()
+
+        alt provider == ollama
+            F->>LLM: HTTP POST to OLLAMA_HOST/api/chat
+            LLM-->>F: JSON response
+        else provider == openai
+            F->>LLM: llm_chat.chat_completion()
+            Note over LLM: LiteLLM routes to OpenAI/Gemini/Claude
+            LLM-->>F: Text response
+        end
+
+        F->>F: Vulnerability-specific processing
+        Note over F: Detect leaked secrets, violations, etc.
+        F-->>B: JSON Response
+    end
+```
+
+## LLM Provider Resolution
+
+```mermaid
+flowchart TD
+    Req["/api/... request received"]
+    RP["resolve_provider()
+    preferred='auto'"]
+    Key{"has_openai_key
+    in session or env?"}
+    Fallback{"ENABLE_PROVIDER_FALLBACK
+    = true?"}
+    Ollama["Provider: ollama
+    → Direct HTTP to OLLAMA_HOST"]
+    Cloud["Provider: openai
+    → LiteLLM → Provider API"]
+
+    Req --> RP
+    RP -->|preferred=ollama| Ollama
+    RP -->|preferred=openai| Cloud
+    RP -->|preferred=auto| Key
+    Key -->|yes| Cloud
+    Key -->|no| Fallback
+    Fallback -->|yes| Ollama
+    Fallback -->|no| Cloud
+```
+
+## Ollama Chat Flow
+
+```mermaid
+flowchart LR
+    Route["route.py
+    Handler"]
+    OG{"_ollama_remote_gate
+    enabled?"}
+    Avail{"Ollama
+    available?"}
+    Unavail["Return unavailable
+    JSON error"]
+    Vuln["vulnerability/ollama_*.py
+    chat_with_ollama()"]
+    API["HTTP POST
+    OLLAMA_HOST/api/chat"]
+    Resp["Parse response
+    + vulnerability detection"]
+
+    Route --> OG
+    OG -->|testing=True| Vuln
+    OG -->|testing=False| Avail
+    Avail -->|no| Unavail
+    Avail -->|yes| Vuln
+    Vuln --> API
+    API --> Resp
+```
+
+## Cloud LLM Chat Flow
+
+```mermaid
+flowchart LR
+    Route["route.py
+    Handler"]
+    Key{"API key
+    in session?"}
+    Err["Return missing key
+    JSON error"]
+    Vuln["vulnerability/openai_*.py
+    chat_with_openai()"]
+    LLM["llm_chat.chat_completion()
+    → litellm.completion()"]
+    Resp["Parse response
+    + vulnerability detection"]
+
+    Route --> Key
+    Key -->|no| Err
+    Key -->|yes| Vuln
+    Vuln --> LLM
+    LLM --> Resp
+```
+
+## Database Access Pattern
+
+The main database (`pizza_shop.db`) is read by nearly every route. A secondary
+database (`catering_sql_lab.db`) is used only by the catering SQL tool lab:
+
+```mermaid
+flowchart TB
+    Route["route.py"]
+    DB1["pizza_shop.db
+    Main shop data"]
+    DB2["catering_sql_lab.db
+    RoutingFlags only"]
+
+    Route -->|Comments, Orders, Users, Pizzas| DB1
+    Route -->|catering-sql-chat| DB2
+    Route -->|Comments for RAG| DB1
+    Route -->|Read comments for training| DB1
+    Route -->|Sentiment model| DB1
+```
+
+## Vulnerability Detection
+
+After each LLM response, the route handler performs vulnerability-specific
+detection on the output:
+
+| Vulnerability | Detection | What it looks for |
+|--------------|-----------|-------------------|
+| Sensitive Info Disclosure | `detect_sensitive_info()` | SSNs, credit cards, emails, VIP names |
+| Order Access | `detect_order_access()` | Other users' order details |
+| Misinformation | (UI comparison) | Response vs. known facts |
+| Direct Prompt Injection | Level secret match | Secret coupon word in output |
+| Excessive Agency | Order placed check | New DB order records |
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
new file mode 100644
index 0000000..4db5829
--- /dev/null
+++ b/docs/architecture/overview.md
@@ -0,0 +1,241 @@
+# Architecture
+
+PwnzzAI Shop is a **Flask 3.1 monolithic application** with a plugin-style vulnerability
+module system, dual LLM backends (local Ollama + cloud LiteLLM), dual SQLite databases,
+and a scikit-learn sentiment model — all wrapped in a pizza shop theme.
+
+## System Overview
+
+```mermaid
+flowchart TB
+    Browser["User Browser
+    (Jinja2 Templates)"]
+    Route["application.route
+    route.py — ~80 endpoints"]
+    Models["Database Models
+    Pizza, User, Comment, Order, RoutingFlag"]
+    LLM["LLM Chat
+    llm_chat.py — LiteLLM"]
+    Sentiment["Sentiment Model
+    sentiment_model.py — scikit-learn"]
+    Vulns["Vulnerability Modules
+    24 modules"]
+    Ollama["Ollama
+    Local LLM"]
+    Cloud["Cloud LLM
+    OpenAI / Gemini / Claude"]
+
+    Browser --> Route
+    Route --> Models
+    Route --> LLM
+    Route --> Sentiment
+    Route --> Vulns
+    Vulns --> Ollama
+    Vulns --> Cloud
+```
+
+## Core Application Stack
+
+| Layer | Location | Technology | Role |
+|-------|----------|------------|------|
+| App Factory | `application/__init__.py` | Flask + SQLAlchemy | Creates Flask app, binds DB, registers routes |
+| Config | `config.py` | Environment variables | SQLite URIs, secret key |
+| Routes | `application/route.py` | Flask views | ~80 endpoints — auth, pizza shop, labs, APIs |
+| Models | `application/model.py` | SQLAlchemy ORM | 5 models — Pizza, User, Comment, Order, RoutingFlag |
+| LLM Abstraction | `application/llm_chat.py` | LiteLLM | Unified `chat_completion()` for any provider |
+| Provider Config | `application/provider_config.py` | Environment + session | Resolves which LLM provider/keys to use |
+| Ollama Setup | `application/ollama_setup.py` | HTTP + subprocess | Start/pull/check Ollama models |
+| Sentiment Model | `application/sentiment_model.py` | scikit-learn | LogisticRegression trained on pizza comments |
+| Prompt Templates | `application/prompts/` | Jinja2 | B0-B9 escalation ladder system prompts |
+| Templates | `application/templates/` | Jinja2 HTML | 22 templates (navbar, pages, labs) |
+
+## Module Dependency Map
+
+Generated by [pyan3](https://github.com/Technologicat/pyan) — edges show import/call dependencies:
+
+### Core Module Dependencies
+
+```
+application (__init__.py)
+  └── application.route                 — route registration (circular-safe import)
+        ├── application.model           — Pizza, User, Comment, Order, RoutingFlag
+        ├── application.provider_config — OLLAMA_HOST, OLLAMA_MODEL, llm_ui_snapshot, etc.
+        ├── application.sentiment_model — create_model(), get_data()
+        ├── application.llm_chat        — via vulnerability modules
+        ├── application.vulnerabilities.* — all 24 vulnerability modules
+        └── application.ollama_setup    — ensure_ollama_running, check_and_pull_model
+
+application.provider_config
+  └── (self-contained config module, no other application imports)
+        Environment variables read:
+          OLLAMA_HOST, OLLAMA_MODEL, OLLAMA_FALLBACK_MODEL
+          OPENAI_API_KEY, OPENAI_MODEL
+          LITELLM_MODEL, GEMINI_MODEL, GEMINI_API_KEY
+          LAB_CLOUD_LLM_MODEL, LAB_CLOUD_LLM_MODEL_EXCESSIVE_AGENCY
+          LLM_UI_*, MODEL_TIMEOUT_SECONDS, ENABLE_PROVIDER_FALLBACK, etc.
+
+application.llm_chat
+  └── application.provider_config       — MODEL_TIMEOUT_SECONDS, resolved_litellm_model
+        Uses litellm.completion() for all provider-agnostic LLM calls.
+
+application.ollama_setup
+  └── (standalone — talks to Ollama HTTP API directly)
+
+application.sentiment_model
+  └── application.model.Comment         — reads comments for training data
+        Uses scikit-learn CountVectorizer + LogisticRegression
+
+application.prompts.b_stream
+  └── (Jinja2 template rendering from prompts/direct_prompt_escalation/)
+```
+
+### Vulnerability Module Dependencies
+
+Each vulnerability module follows one of two patterns:
+
+**Ollama-backed modules** (direct HTTP to Ollama API):
+```
+ollama_*.py
+  └── self-contained, calls Ollama HTTP API
+  └── uses: get_conversation_model(), extract_function_calls(), chat_with_ollama()
+```
+
+**Cloud-backed modules** (via LiteLLM):
+```
+openai_*.py
+  ├── application.llm_chat              — chat_completion()
+  └── application.provider_config       — lab_cloud_llm_model_default
+```
+
+**Shared modules** (used by both patterns):
+```
+catering_rag_lab.py        — RAG with FAISS + sentence-transformers
+catering_sql_tool_lab.py   — Agentic SQL tool routing with db
+direct_prompt_escalation.py — B0-B9 escalation ladder
+promotion_indirect_injection.py — Photo upload indirect injection
+toxicity_support_lab.py    — Customer support safety lab
+supply_chain.py            — Malicious pickle model demos
+model_theft.py             — Model extraction attack logic
+data_poisoning.py          — Data poisoning attack logic
+```
+
+## Database Architecture
+
+### Primary Database: `pizza_shop.db`
+
+The main shop database with 4 models:
+
+```mermaid
+erDiagram
+    Pizza {
+        int id PK
+        string name
+        text description
+        float price
+        string image
+    }
+
+    User {
+        int id PK
+        string username UK
+        string password_hash
+    }
+
+    Comment {
+        int id PK
+        int pizza_id FK
+        int user_id FK
+        string name
+        text content
+        int rating
+        datetime created_at
+    }
+
+    Order {
+        int id PK
+        int user_id FK
+        int pizza_id FK
+        int quantity
+        float total_price
+        datetime created_at
+    }
+
+    Pizza ||--o{ Comment: has
+    User  ||--o{ Comment: writes
+    User  ||--o{ Order:   places
+    Pizza ||--o{ Order:   contains
+```
+
+### Secondary Database: `catering_sql_lab.db`
+
+A separate SQLite database bound to `RoutingFlag` model via `SQLALCHEMY_BINDS["catering_sql"]`. Used by the catering agentic SQL / tool routing lab to isolate exploit data from the main shop.
+
+```
+┌──────────────────┐
+│   RoutingFlag    │
+├──────────────────┤
+│ id (PK)          │
+│ username (unique)│
+│ flag_code        │
+└──────────────────┘
+```
+
+Sample flags: `RT-ALICE7A`, `RT-BOB9F2`
+
+## LLM Provider Resolution Flow
+
+```mermaid
+flowchart TD
+    Req["/api/... request"]
+    RP["resolve_provider()
+    preferred='auto'"]
+    Key{"has_openai_key?"}
+    Fallback{"ENABLE_PROVIDER_FALLBACK?"}
+    Ollama["Provider: ollama
+    Local Ollama HTTP API"]
+    Cloud["Provider: openai
+    LiteLLM → cloud API"]
+
+    Req --> RP
+    RP -->|preferred=ollama| Ollama
+    RP -->|preferred=openai| Cloud
+    RP -->|preferred=auto| Key
+    Key -->|yes| Cloud
+    Key -->|no| Fallback
+    Fallback -->|yes| Ollama
+    Fallback -->|no| Cloud
+```
+
+Provider selection happens per-request via `resolve_provider()`. Cloud model names
+are resolved through a chain: `LAB_CLOUD_LLM_MODEL` → `GEMINI_MODEL` → `OPENAI_MODEL`,
+with `LITELLM_MODEL` overriding everything for the Lab Setup UI.
+
+## Request Lifecycle
+
+```
+1. Flask receives request
+2. @app.before_request → _ensure_db_ready() — self-heals DB tables
+3. Route function executes — renders template or returns JSON
+4. Template renders via Jinja2 (with llm_ui context injected by @app.context_processor)
+5. Response returned to browser
+```
+
+For LLM-powered routes:
+```
+1. Route receives user input (JSON body, form, file upload)
+2. resolve_provider() decides Ollama vs cloud
+3. For Ollama: direct HTTP to OLLAMA_HOST
+4. For cloud: llm_chat.chat_completion() → LiteLLM → provider API
+5. Vulnerability-specific processing detected on response
+6. JSON returned to frontend
+```
+
+## Security Model
+
+PwnzzAI is **intentionally insecure** — the vulnerabilities are the features. However:
+
+- **Session-based auth**: werkzeug `generate_password_hash` for passwords
+- **No CSRF enforcement** for POST endpoints
+- **No rate limiting** (except simulated in DoS demos)
+- **Ollama gateway check**: `_ollama_remote_gate_enabled()` skips probe during tests
+- **API key validation**: minimal check (`sk-` prefix check for OpenAI, length >= 8 for others)
diff --git a/docs/architecture/threat-model.md b/docs/architecture/threat-model.md
new file mode 100644
index 0000000..9b95c07
--- /dev/null
+++ b/docs/architecture/threat-model.md
@@ -0,0 +1,43 @@
+# Threat Model
+
+PwnzzAI Shop maps its vulnerability demonstrations to the
+[OWASP Top 10 for LLM Applications 2025](https://genai.owasp.org/resource/owasp-top-10-for-llm-applications-2025/)
+and the broader [AI Exchange threat taxonomy](https://owaspai.org/).
+
+## OWASP Top 10 for LLMs — Coverage
+
+| # | Vulnerability | Demonstration | Module(s) |
+|---|-------------|--------------|-----------|
+| **LLM-01** | Prompt Injection | Direct injection (levels 1-5), indirect via QR, escalation ladder (B0-B9), promotion photo injection | `ollama/openai_direct_prompt_injection`, `direct_prompt_escalation`, `ollama/openai_indirect_prompt_injection`, `promotion_indirect_injection` |
+| **LLM-02** | Sensitive Information Disclosure | RAG system leaking PII/VIP markers, model weights exposure | `ollama/openai_sensitive_data_leakage`, `sentiment_model` |
+| **LLM-03** | Supply Chain | Malicious pickle model with JS injection and bash command execution | `supply_chain` |
+| **LLM-04** | Data & Model Poisoning | Poisoned training data for sentiment model, RAG document poisoning | `data_poisoning`, `catering_rag_lab` |
+| **LLM-05** | Improper Output Handling | XSS via malicious model output (supply chain JS injection demo) | `supply_chain` (via `demo-malicious-model` route) |
+| **LLM-06** | Excessive Agency | LLM placing orders without user confirmation, autonomous tool execution | `ollama/openai_excessive_agency`, `catering_sql_tool_lab` |
+| **LLM-07** | System Prompt Leakage | Covered by direct prompt injection escalation ladder (B0-B9) | `direct_prompt_escalation` |
+| **LLM-08** | Vector & Embedding Weaknesses | RAG document poisoning, unauthorized retrieval from vector store | `catering_rag_lab` |
+| **LLM-09** | Misinformation | Poisoned RAG context producing false answers | `ollama/openai_misinformation` |
+| **LLM-10** | Unbounded Consumption | No rate limiting on LLM endpoints, resource exhaustion simulation | `ollama/openai_dos`, `/api/llm-query` |
+
+## Additional Coverage
+
+| Threat | Demonstration | AI Exchange Reference |
+|--------|-------------|----------------------|
+| Model Theft | Extraction of sentiment model weights via API probes | [Model Exfiltration](https://owaspai.org/go/modelexfiltration/) |
+| Insecure Plugin Design | LLM controlling function execution with client-side tokens | [Least Model Privilege](https://owaspai.org/goto/leastmodelprivilege/) |
+| Broken Access Control | LLM accessing other users' order data | [Oversight](https://owaspai.org/goto/oversight/) |
+| Agentic Tool Abuse | SQL query generation from natural language with insufficient filtering | — |
+| Toxicity & Safety | Customer support chat without toxicity guardrails | — |
+
+## Learning Framework
+
+Each vulnerability features:
+
+1. **Active demonstration** — interactive page showing the vulnerability's mechanics
+2. **Exploitation scenario** — guided attack exercise
+3. **Hardened alternative** — defensive approach (where applicable)
+
+## Route Map by Threat
+
+See [scenario-list.md](../labs/scenario-list.md) for per-lab walkthroughs and
+[api-reference.md](../developer/api-reference.md) for endpoint details.
diff --git a/docs/community/contributing.md b/docs/community/contributing.md
new file mode 100644
index 0000000..c95ffb1
--- /dev/null
+++ b/docs/community/contributing.md
@@ -0,0 +1,159 @@
+# Contributing to PwnzzAI Shop
+
+Thank you for your interest in contributing to PwnzzAI Shop! This project aims to educate developers about LLM security vulnerabilities through practical, hands-on examples. We welcome contributions that enhance the educational value and quality of this project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Ways to Contribute](#ways-to-contribute)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+   - [Docker Smoke Tests](#docker-smoke-tests)
+- [Submitting Changes](#submitting-changes)
+- [Reporting Issues](#reporting-issues)
+- [Security Considerations](#security-considerations)
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment. Be kind, professional, and considerate in all interactions.
+
+## Ways to Contribute
+
+You can contribute to PwnzzAI Shop in several ways:
+
+- **Bug Fixes**: Fix issues or improve existing functionality
+- **New Vulnerabilities**: Add demonstrations of additional LLM vulnerabilities
+- **Documentation**: Improve explanations, tutorials, or documentation
+- **Test Coverage**: Add or improve test cases
+- **Security Mitigations**: Enhance security solutions in the mitigation strategies sections
+- **Model Support**: Add support for additional LLM models
+- **UI/UX Improvements**: Enhance the user interface or user experience
+- **Code Quality**: Refactor code for better maintainability
+
+## Getting Started
+
+1. **Fork the Repository**: Click the **Fork** button on the canonical repo: [https://github.com/OWASP/PwnzzAI](https://github.com/OWASP/PwnzzAI)
+
+2. **Clone Your Fork**:
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/PwnzzAI.git
+   cd PwnzzAI
+   ```
+
+3. **Add Upstream Remote** (track the canonical OWASP project):
+   ```bash
+   git remote add upstream https://github.com/OWASP/PwnzzAI.git
+   ```
+
+   If your GitHub fork still shows the **old parent repository**, GitHub will not let you open a pull request into **OWASP/PwnzzAI** from that fork. Fix it by **forking again from [OWASP/PwnzzAI](https://github.com/OWASP/PwnzzAI)** (or asking an org admin to **re-parent** your existing fork), then add a second remote (for example `origin` → your fork, `upstream` → OWASP) and push your topic branch there before opening the PR.
+
+4. **Create a Branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
+   ```
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.11 or higher
+- pip package manager
+- (Optional) Docker for containerized development
+
+### Local Setup
+
+1. **Create a Virtual Environment**:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+2. **Install Dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   pip install -r requirements-test.txt
+   ```
+
+3. **Install System Dependencies** (if needed for testing):
+   ```bash
+   sudo apt-get update
+   sudo apt-get install -y libzbar0
+   ```.
+
+4. **Configure Environment**:
+   - Copy `.flaskenv` if needed
+
+## Testing
+
+Before opening a PR, run tests locally:
+
+```bash
+pytest -v
+```
+
+### Docker Smoke Tests
+
+Use the Docker smoke test routine before pushing to GitHub. It validates local Docker build and both Docker runtime modes.
+
+1. Run the smoke test script:
+
+```bash
+./scripts/docker-smoke-test.sh
+```
+
+2. What it validates:
+- `docker-compose.yml` syntax
+- `docker-compose.external-ollama.yml` syntax
+- local image build from `Dockerfile`
+- Option 1 runtime: PwnzzAI + bundled Ollama compose stack
+- Option 2 runtime: PwnzzAI + external Ollama compose stack
+
+3. Optional custom local image name:
+
+```bash
+APP_IMAGE=pwnzzai:my-local-test ./scripts/docker-smoke-test.sh
+```
+
+The script cleans up test containers automatically when it exits.
+
+## Coding Standards
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) with a soft 100-character line limit.
+- Use meaningful variable and function names.
+- Add type hints to function signatures where practical.
+- Write docstrings for public functions and classes.
+- Use `snake_case` for variables and functions, `PascalCase` for classes.
+- Keep functions small and single-purpose.
+- Avoid adding comments that describe what the code does — let the code speak for itself. Use comments only for non-obvious intent.
+
+For docs contributions, see [Doc Standards](../community/doc-standards.md).
+
+## Submitting Changes
+
+1. Ensure all tests pass: `pytest -v`
+2. Run the Docker smoke test if you changed infrastructure: `./scripts/docker-smoke-test.sh`
+3. Rebase your branch onto the latest `main` before opening a PR
+4. Write a clear PR title and description
+5. Reference any related issues in the PR body
+6. Keep PRs focused — one change per PR
+
+## Reporting Issues
+
+Use GitHub Issues to report bugs, suggest features, or ask questions.
+
+- **Bug report**: Include steps to reproduce, expected vs actual behavior, and your environment (OS, Python version, Docker version)
+- **Feature request**: Describe the problem you're solving and how your suggestion helps
+- **Question**: Use the [OWASP AI Exchange Discussions](https://github.com/OWASP/PwnzzAI/discussions)
+
+## Security Considerations
+
+This project contains intentional vulnerabilities for educational purposes.
+
+- **Never** submit a PR that fixes a documented lab vulnerability without prior discussion — these are features
+- New vulnerability contributions must include a hardened alternative (mode flag or separate endpoint)
+- Do not commit real API keys, credentials, or PII — use example values
+- If you discover an accidental vulnerability that is not part of the curriculum, follow the [Responsible Disclosure](../security/disclosure.md) process
\ No newline at end of file
diff --git a/docs/community/doc-standards.md b/docs/community/doc-standards.md
new file mode 100644
index 0000000..568228b
--- /dev/null
+++ b/docs/community/doc-standards.md
@@ -0,0 +1,166 @@
+# Documentation Standards
+
+How to contribute new or updated documentation.
+
+## Single Source of Truth
+
+Content lives in **one place**. The `scripts/sync-docs.py` script copies
+canonical root files into `docs/` before every MkDocs build.
+
+| Canonical file | Synced to `docs/` | Edit this file |
+|---|---|---|
+| `README.md` | `docs/README.md` | Root `README.md` |
+| `CONTRIBUTING.md` | `docs/community/contributing.md` | Root `CONTRIBUTING.md` |
+| `OLLAMA_CONNECTION_TROUBLESHOOTING.md` | `docs/ops/troubleshooting.md` | Root `OLLAMA_CONNECTION_TROUBLESHOOTING.md` |
+| `tests/README.md` | `docs/quality-assurance/testing-guide.md` | Root `tests/README.md` |
+| `.env.example` | `docs/env.example` | Root `.env.example` |
+
+**Never edit the copies in `docs/`** — they are overwritten on every build.
+
+## File Organization
+
+```
+docs/
+├── README.md                       # Landing page (synced from root)
+├── architecture/
+│   ├── overview.md                 # High-level system design
+│   ├── data-flow.md                # Request lifecycle, provider resolution
+│   └── threat-model.md             # OWASP Top 10 mapping
+├── developer/
+│   ├── getting-started.md          # Environment setup
+│   ├── codebase-map.md             # Directory structure, module roles
+│   ├── api-reference.md            # All endpoints
+│   ├── api-modules.md              # Auto-generated (mkdocstrings)
+│   └── adding-features.md          # Vulnerability recipe, coding conventions
+├── labs/
+│   ├── overview.md                 # Platform navigation
+│   ├── lab-format.md               # Escalation ladder, lab structure
+│   └── scenario-list.md            # Challenge walkthroughs
+├── quality-assurance/
+│   ├── testing-guide.md            # Test suite (synced from tests/README.md)
+│   └── security-checks.md          # Vulnerability verification checklist
+├── ops/
+│   ├── docker-orchestration.md     # Compose files, networking
+│   ├── env-variables.md            # All .env parameters
+│   ├── cloud-setup.md              # Cloud LLM provider setup
+│   └── troubleshooting.md          # Known issues (synced from root)
+├── security/
+│   ├── disclosure.md               # Responsible disclosure policy
+│   ├── usage-policy.md             # Educational use disclaimer
+│   └── data-privacy.md             # Session/data handling notes
+├── community/
+│   ├── contributing.md             # PR process (synced from root)
+│   └── doc-standards.md            # This file
+└── releases/
+    ├── CHANGELOG.md                # Version history
+    └── ROADMAP.md                  # Future goals
+```
+
+## Documentation Checklist
+
+Every PR that changes code must be checked against this list:
+
+| What changed | Update |
+|---|---|
+| New route/endpoint | Add to `docs/developer/api-reference.md` |
+| New vulnerability module | Add to `docs/developer/codebase-map.md` module table |
+| New env var | Add to `.env.example` + `docs/ops/env-variables.md` |
+| Changed dependency | Update `docs/architecture/overview.md` |
+| New prompt template in `prompts/` | Update `docs/labs/lab-format.md` |
+| New Docker/deploy script | Update `docs/ops/docker-orchestration.md` |
+| API response changed | Update entry in `docs/developer/api-reference.md` |
+| New Makefile target | Add `## description` in Makefile |
+| **New or changed docs** | Run `make check-codeblocks` and `make docs` before pushing
+
+### Automated Coverage Check
+
+A static analysis script (`scripts/check-doc-coverage.py`) runs in CI on every
+PR that touches code or docs. It uses `ast` to parse `application/route.py`
+route decorators and compares them against `docs/developer/api-reference.md`,
+then checks every file in `application/vulnerabilities/` against
+`docs/developer/codebase-map.md`. Any undocumented route or module fails the
+build.
+
+What it catches:
+
+- **New endpoints** without a corresponding entry in the API reference
+- **New vulnerability modules** without an entry in the codebase map
+- **Route parameter mismatches** between the code and docs
+
+Run it locally before pushing:
+
+```bash
+python scripts/check-doc-coverage.py
+```
+
+This is part of the `make check-docs` pipeline and runs alongside the other
+four doc quality checks in CI.
+
+## Documenting New Features
+
+When adding a new vulnerability lab, create or update:
+
+1. **Vulnerability module** in `application/vulnerabilities/` with docstrings
+2. **Routes** in `application/route.py` with docstrings
+3. **Template** in `application/templates/`
+4. **Tests** in `tests/`
+5. **Codebase map** — add to `docs/developer/codebase-map.md` module table
+6. **Threat model** — add to `docs/architecture/threat-model.md` mapping table
+7. **API reference** — add to `docs/developer/api-reference.md` with request/response
+8. **Scenario list** — add to `docs/labs/scenario-list.md` if it's a challenge
+9. **Security checks** — add to `docs/quality-assurance/security-checks.md`
+
+## Documentation Build
+
+```bash
+make docs          # sync + mkdocs build
+make docs-serve    # sync + mkdocs serve (live reload at localhost:8000)
+```
+
+The build runs `scripts/sync-docs.py` first, which copies canonical root files
+into `docs/` with path rewriting, then builds the static site to `site/`.
+
+## Quality Checks (CI)
+
+Four automated checks run on every PR that touches documentation (via
+`.github/workflows/docs-quality.yml`):
+
+| Check | Tool | What it catches |
+|---|---|---|
+| Markdown style | `markdownlint-cli2` | Wrong heading nesting, broken list indentation, missing blank lines |
+| Dead links | `lychee` | Broken URLs (404s, DNS failures, moved pages) |
+| Spelling | `cspell` | Typos in prose, inconsistent casing of technical terms |
+| Code snippets | `scripts/check-codeblocks.py` | Python code blocks with syntax errors |
+
+### Running Locally
+
+The code block checker is a Python script that works on any platform with no
+extra dependencies:
+
+```bash
+make check-codeblocks
+# or: python3 scripts/check-codeblocks.py
+```
+
+The doc coverage script also runs with stdlib only:
+
+```bash
+python scripts/check-doc-coverage.py
+```
+
+The other three tools (`markdownlint-cli2`, `lychee`, `cspell`) are Node.js/Rust
+tools that are best run in CI. On the Makefile, they print a helpful message if
+not installed locally:
+
+```bash
+make check-docs   # runs all 5 with graceful fallbacks
+```
+
+### Before Opening a PR
+
+Run `make docs` to confirm the site builds without errors, then check:
+
+- [ ] `make check-codeblocks` passes (no broken Python snippets)
+- [ ] `python scripts/check-doc-coverage.py` passes (all routes and modules documented)
+- [ ] New pages are linked from the nav or an existing page
+- [ ] All relative links resolve correctly
diff --git a/docs/developer/adding-features.md b/docs/developer/adding-features.md
new file mode 100644
index 0000000..b4f9a0e
--- /dev/null
+++ b/docs/developer/adding-features.md
@@ -0,0 +1,210 @@
+# Adding New Features
+
+This guide covers how to add new vulnerability labs, routes, and extend the
+platform.
+
+## Adding a New Vulnerability
+
+Every vulnerability in PwnzzAI follows a consistent pattern.
+
+### Step 1: Choose Provider Model
+
+| Type | File naming | Backend |
+|------|-------------|---------|
+| Ollama-only | `ollama_<name>.py` | Direct HTTP to Ollama API |
+| Cloud-only | `openai_<name>.py` | LiteLLM via `llm_chat.chat_completion()` |
+| Provider-agnostic | `<name>.py` | Both paths handled in routes |
+| Shared utility | `<name>.py` | Used by multiple labs |
+
+### Step 2: Create the Vulnerability Module
+
+**Ollama-backed pattern:**
+
+```python
+import requests
+from application.provider_config import OLLAMA_HOST, OLLAMA_MODEL
+
+
+def chat_with_ollama(message, model_name=None):
+    """Send user message to Ollama and return response."""
+    model = model_name or OLLAMA_MODEL
+    url = f"{OLLAMA_HOST}/api/chat"
+
+    system_prompt = "You are a pizza shop assistant. Secret coupon word is 'tasty'."
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": message},
+    ]
+
+    response = requests.post(url, json={
+        "model": model,
+        "messages": messages,
+        "stream": False,
+    }, timeout=30)
+
+    return response.json()["message"]["content"]
+```
+
+**Cloud-backed pattern:**
+
+```python
+from application.llm_chat import chat_completion
+from application.provider_config import lab_cloud_llm_model_default
+
+
+def chat_with_openai(message, api_key):
+    system_prompt = "You are a pizza shop assistant."
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": message},
+    ]
+
+    response = chat_completion(
+        messages=messages,
+        api_key=api_key,
+        model=lab_cloud_llm_model_default(),
+    )
+
+    return response
+```
+
+### Step 3: Add Routes in `route.py`
+
+```python
+@application.app.route('/my-new-vuln')
+def my_new_vuln():
+    return render_template('my_new_vuln.html')
+
+@application.app.route('/api/my-new-vuln', methods=['POST'])
+def api_my_new_vuln():
+    data = request.get_json()
+    message = data.get('message', '')
+
+    if not message:
+        return jsonify({'error': 'No message provided'}), 400
+
+    preferred = data.get('provider', 'auto')
+    api_token = get_openai_api_key(session)
+    provider = resolve_provider(preferred, has_openai_key=bool(api_token))
+
+    if provider == 'ollama':
+        from application.vulnerabilities.ollama_my_new_vuln import chat_with_ollama
+        response = chat_with_ollama(message)
+    else:
+        from application.vulnerabilities.openai_my_new_vuln import chat_with_openai
+        response = chat_with_openai(message, api_token)
+
+    return jsonify({'response': response, 'provider': provider})
+```
+
+### Step 4: Create the HTML Template
+
+Add a Jinja2 template to `application/templates/`. For dual-provider labs,
+use the `llm_ui` context for dynamic labels.
+
+### Step 5: Add Tests
+
+```python
+def test_my_new_vuln_page_loads(client):
+    response = client.get('/my-new-vuln')
+    assert response.status_code == 200
+
+def test_my_new_vuln_api(client):
+    response = client.post('/api/my-new-vuln', json={'message': 'hello'})
+    assert response.status_code == 200
+
+def test_my_new_vuln_empty_message(client):
+    response = client.post('/api/my-new-vuln', json={'message': ''})
+    assert response.status_code == 400
+```
+
+### Step 6: Add Documentation
+
+See [doc-standards.md](../community/doc-standards.md) for the documentation
+checklist and workflow.
+
+## Coding Conventions
+
+### Route Pattern
+
+```python
+@application.app.route('/endpoint', methods=['POST'])
+def endpoint_function():
+    """Docstring describing the vulnerability."""
+    try:
+        data = request.get_json()
+
+        # 1. Validate input
+        if not data or not data.get('key'):
+            return jsonify({'error': 'Missing required field'}), 400
+
+        # 2. Check auth if needed
+        if 'user_id' not in session:
+            return jsonify({'error': 'Authentication required'}), 401
+
+        # 3. Check Ollama availability (for Ollama-backed routes)
+        if _ollama_remote_gate_enabled():
+            available, _, _ = _ollama_status_snapshot()
+            if not available:
+                return jsonify({'response': _ollama_unavailable_message("feature")})
+
+        # 4. Import + call vulnerability module
+        from application.vulnerabilities.module import function
+        result = function(data['key'])
+
+        return jsonify(result)
+
+    except Exception as e:
+        return jsonify({'error': str(e)}), 500
+```
+
+### Provider Resolution
+
+Always use `resolve_provider()` for dual-provider labs:
+
+```python
+from application.provider_config import resolve_provider, get_openai_api_key
+
+api_token = get_openai_api_key(session)
+preferred = request.get_json().get('provider', 'auto')
+provider = resolve_provider(preferred=preferred, has_openai_key=bool(api_token))
+```
+
+### Ollama Gateway for Tests
+
+```python
+def _ollama_remote_gate_enabled() -> bool:
+    """Skip live Ollama HTTP probes under pytest."""
+    if os.environ.get("TESTING") in {"1", "true", "yes"}:
+        return False
+    try:
+        from flask import current_app, has_request_context
+        if has_request_context() and getattr(current_app, "testing", False):
+            return False
+    except RuntimeError:
+        pass
+    return True
+```
+
+### Provider Config Rules
+
+Never hardcode LLM model names. Always use the config chain:
+
+```
+LAB_CLOUD_LLM_MODEL → GEMINI_MODEL → OPENAI_MODEL → (error, no default in code)
+```
+
+For UI strings, use `llm_ui_snapshot()` instead of hardcoding provider names:
+
+```python
+from application.provider_config import llm_ui_snapshot
+key_label = llm_ui_snapshot()['key_label']
+```
+
+## Testing Conventions
+
+- All tests use in-memory SQLite for isolation
+- Use `client` fixture for unauthenticated requests
+- Use `authenticated_client` fixture for requests as `alice`/`alice`
+- Mark cloud-dependent tests with `@pytest.mark.openai`
+- Run `pytest -m "not openai"` to skip cloud tests
diff --git a/docs/developer/api-modules.md b/docs/developer/api-modules.md
new file mode 100644
index 0000000..29ce94e
--- /dev/null
+++ b/docs/developer/api-modules.md
@@ -0,0 +1,27 @@
+# Python API Modules
+
+Auto-generated documentation from source code docstrings.
+
+## Application Entry
+
+::: application
+
+## Configuration
+
+::: config
+
+## Provider Configuration
+
+::: application.provider_config
+
+## Database Models
+
+::: application.model
+
+## LLM Chat Abstraction
+
+::: application.llm_chat
+
+## Ollama Setup
+
+::: application.ollama_setup
diff --git a/docs/developer/api-reference.md b/docs/developer/api-reference.md
new file mode 100644
index 0000000..0bda2ee
--- /dev/null
+++ b/docs/developer/api-reference.md
@@ -0,0 +1,573 @@
+# API Reference
+
+PwnzzAI Shop exposes ~72 HTTP endpoints across page routes, API endpoints,
+and lab-specific endpoints. All cloud LLM endpoints use the same resolution
+chain described in the [Architecture](../architecture/overview.md) doc.
+
+## Page Routes (GET)
+
+These render Jinja2 HTML templates for the browser.
+
+### Home & Navigation
+
+| Route | Template | Description |
+|-------|----------|-------------|
+| `/` | `index.html` | Home page — lists all 5 pizzas from DB |
+| `/basics` | `basics.html` | Lab setup / getting started page |
+| `/glossary` | `glossary.html` | AI/LLM/security glossary |
+| `/login` | `login.html` | Login page (also handles POST for auth) |
+| `/logout` | redirect → `/` | Clears session |
+
+### Pizza Shop
+
+| Route | Template | Description |
+|-------|----------|-------------|
+| `/pizza/<int:pizza_id>` | `pizza_detail.html` | Single pizza detail with comments + order form |
+
+### Vulnerability Demonstration Pages
+
+| Route | Template | OWASP |
+|-------|----------|-------|
+| `/model-theft` | `model_theft.html` | Model extraction |
+| `/supply-chain` | `supply_chain.html` | LLM-03 |
+| `/data-poisoning` | `data_poisoning.html` | LLM-04 |
+| `/data-poisoning/catering-rag` | `catering_rag_poisoning.html` | LLM-04/LLM-08 |
+| `/insecure-plugin` | `insecure_plugin.html` | Plugin security |
+| `/sensitive-info` | `sensitive_info.html` | LLM-02 |
+| `/excessive-agency` | `excessive_agency.html` | LLM-06 |
+| `/misinformation` | `misinformation.html` | LLM-09 |
+| `/dos-attack` | `dos_attack.html` | LLM-10 |
+| `/real-dos-attack` | `dos_attack.html` | LLM-10 (live model) |
+| `/direct-prompt-injection` | `direct_prompt_injection.html` | LLM-01 (levels 1-5) |
+| `/direct-prompt-injection/guardrail-ladder` | `direct_prompt_injection.html` | LLM-01 (B0-B9 escalation) |
+| `/indirect-prompt-injection` | `indirect_prompt_injection.html` | LLM-01 (QR-based) |
+| `/agentic-tools` | `agentic_tools.html` | SQL tool routing |
+| `/customer-support-safety` | `customer_support_safety.html` | Toxicity lab |
+| `/promotion-photo` | `promotion_photo.html` | Promotion indirect injection |
+
+---
+
+## API Routes (POST — JSON)
+
+### Lab Setup
+
+#### `POST /save-openai-api-key`
+
+Save cloud LLM API key to Flask session.
+
+**Request:**
+```json
+{
+  "api_key": "sk-...",
+  "provider": "openai",
+  "model": "gpt-4o-mini"
+}
+```
+
+**Response (success):**
+```json
+{"success": true, "message": "API key saved successfully", "provider_prefix": "openai", "provider_name": "OpenAI"}
+```
+
+**Response (invalid):**
+```json
+{"success": false, "error": "Invalid API key format...", "provider_prefix": "openai", "guidance": "..."}
+```
+
+#### `GET /check-openai-api-key`
+
+Check whether a key is stored in the session.
+
+**Response:**
+```json
+{"has_key": true, "llm_ui": {...}, "provider_prefix": "openai"}
+```
+
+#### `POST /setup-ollama`
+
+Ensure Ollama is running and pull the default model(s).
+
+**Response:**
+```json
+{"success": true, "message": "Ollama setup completed! Model ... is ready to use."}
+```
+
+#### `GET /setup-ollama-stream`
+
+Server-Sent Events stream for real-time Ollama setup progress.
+
+**Format:** `text/event-stream`
+
+```
+data: {"status": "Starting Ollama service...", "progress": 5}
+
+data: {"status": "Pulling llama3.2:1b...", "progress": 30}
+...
+data: {"status": "Setup complete! All models are ready.", "progress": 100}
+```
+
+#### `GET /check-ollama-status`
+
+**Response:**
+```json
+{"available": true, "models": ["llama3.2:1b"], "error": null}
+```
+
+---
+
+### Sentiment Analysis
+
+#### `POST /analyze_sentiment`
+
+Analyze sentiment of arbitrary text using the trained LogisticRegression model.
+
+**Request:** `{"text": "The pizza was amazing!"}`
+
+**Response:** `{"text": "...", "sentiment": "positive", "confidence": 0.95}`
+
+#### `POST /api/sentiment`
+
+Same as above with richer response.
+
+**Response:**
+```json
+{
+  "status": "success",
+  "input": "The pizza was amazing!",
+  "result": {
+    "sentiment": "positive",
+    "confidence": 0.95,
+    "probabilities": {"positive": 0.95, "negative": 0.05}
+  },
+  "model_info": {"name": "Sentiment Analysis Model", "version": "1.0", "type": "logistic_regression"}
+}
+```
+
+#### `GET /generate_sentiment_model`
+
+Expose the full model weights — used for model theft demonstration.
+
+**Response:** Full model dump including vocabulary, coefficients, training data, top positive/negative words.
+
+---
+
+### Model Theft
+
+#### `POST /api/model-theft`
+
+Run the model extraction attack.
+
+**Request:** `{"user_words": ["tasty", "bland", "cheese"]}`
+
+**Response:**
+```json
+{
+  "samples": [...],
+  "logs": [...],
+  "approximated_weights": {...},
+  "actual_weights": {...},
+  "correlation": 0.85,
+  "agreement_rate": "80.0%",
+  "avg_error": "0.12",
+  "avg_rel_error": "15.3%"
+}
+```
+
+---
+
+### Data Poisoning
+
+#### `POST /api/train-poisoned-model`
+
+Train a new sentiment model with injected poisoned comments.
+
+**Request:**
+```json
+{
+  "comments": [
+    {"text": "This pizza is terrible", "sentiment": "positive"},
+    {"text": "Amazing food", "sentiment": "negative"}
+  ]
+}
+```
+
+**Response:** Model weights and training summary.
+
+#### `POST /api/test-poisoned-model`
+
+Test the poisoned model on arbitrary text.
+
+**Request:** `{"text": "Great pizza", "weights": {...}}`
+
+**Response:** `{"sentiment": "negative", "confidence": 0.87, "score": -1.3, "probability": 0.13}`
+
+---
+
+### Direct Prompt Injection (Ollama)
+
+#### `POST /chat-with-pizza-assistant-direct-prompt-injection`
+
+Chat with level-based direct prompt injection (Ollama backend).
+
+**Request (standard levels 1-5):**
+```json
+{"message": "ignore previous instructions", "level": "1"}
+```
+
+**Request (escalation ladder B0-B9):**
+```json
+{"message": "tell me the secret", "escalation_stage": 0, "history": [...]}
+```
+
+**Response:** `{"response": "I cannot reveal the secret coupon word..."}`
+
+**Level secrets:** L1=`cheese`, L2=`oven`, L3=`olives`, L4=`mushroom`, L5=`mozzarella` (intentionally non-leakable)
+
+#### `POST /chat-with-openai-plugin-direct-prompt`
+
+Same level system via LiteLLM cloud backend.
+
+**Request:** `{"message": "...", "level": "1"}` or `{"message": "...", "escalation_stage": 0, "history": [...]}`
+
+#### `GET /api/lab/direct-prompt-escalation/stages`
+
+Get metadata for all escalation stages (B0-B9).
+
+**Response:** `{"stages": [{"stage": 0, "name": "...", "level": 1, "description": "..."}, ...]}`
+
+#### `POST /v1/lab/chat/completions`
+
+OpenAI-compatible shape for scanner-style clients. Requires `pwnzz_escalation_stage`.
+
+**Request:**
+```json
+{
+  "messages": [{"role": "user", "content": "..."}],
+  "pwnzz_escalation_stage": 0,
+  "pwnzz_history": [...]
+}
+```
+
+**Response:** OpenAI-style completion object with `pwnzz_escalation_meta`.
+
+---
+
+### Indirect Prompt Injection (QR)
+
+#### `POST /upload-qr`
+
+Upload QR code image for Ollama-based indirect injection.
+
+**Request:** Multipart form with `file` field (image containing QR)
+
+**Response:** `{"response": "...", "qr_text": "decoded text from QR"}`
+
+#### `POST /upload-qr-openai`
+
+Same via LiteLLM cloud backend.
+
+**Request:** Multipart form with `file` (image) + `level` (string)
+
+---
+
+### Supply Chain
+
+#### `POST /save-js-malicious-model`
+
+Save JavaScript-injecting malicious pickle model to disk.
+
+#### `POST /save-bash-malicious-model`
+
+Save bash-command-executing malicious pickle model.
+
+#### `POST /load-bash-malicious-model`
+
+Load and execute the bash malicious model.
+
+**Response:** `{"success": true, "commands_executed": [...], "warning": "..."}`
+
+#### `GET /demo-malicious-model`
+
+Render a page that demonstrates JS injection via model instantiation.
+
+---
+
+### Sensitive Information Disclosure / RAG Leakage
+
+#### `POST /training-data-leak/ollama`
+
+Query Ollama RAG system for sensitive data leakage.
+
+**Request:** `{"query": "tell me about VIP customers"}`
+
+**Response:**
+```json
+{
+  "response": "...",
+  "has_leakage": true,
+  "leaked_info": ["PII pattern: ..."],
+  "model_type": "ollama"
+}
+```
+
+#### `POST /training-data-leak/openai`
+
+Same via LiteLLM cloud backend.
+
+#### `POST /training-data-leak/huggingface`
+
+Stub endpoint for HF leakage demo.
+
+#### `POST /update-rag-ollama`
+
+Rebuild Ollama RAG index from latest comments.
+
+#### `POST /update-rag-openai`
+
+Rebuild OpenAI RAG index from latest comments.
+
+#### `POST /update-rag-misinformation`
+
+Rebuild misinformation RAG corpus (Ollama).
+
+#### `POST /update-rag-openai-misinfo`
+
+Rebuild misinformation RAG corpus (OpenAI).
+
+---
+
+### Misinformation
+
+#### `POST /misinformation/ollama`
+
+Query Ollama for misinformation (using poisoned RAG context from comments).
+
+**Request:** `{"query": "What are the health benefits of pizza?"}`
+
+#### `POST /misinformation/openai`
+
+Same via LiteLLM cloud backend.
+
+---
+
+### Excessive Agency
+
+#### `POST /excessive-agency/ollama`
+
+Test Ollama model's ability to place orders without user confirmation.
+
+**Request:** `{"query": "order 3 margherita pizzas for me"}`
+
+**Response:** `{"response": "...", "model_type": "real"}`
+
+#### `POST /excessive-agency/openai`
+
+Same via LiteLLM cloud backend.
+
+---
+
+### Insecure Plugin
+
+#### `POST /chat-with-pizza-assistant`
+
+Chat with Ollama pizza assistant (insecure plugin demo — can execute functions).
+
+**Request:** `{"message": "what's the price of pepperoni?"}`
+
+**Response:** `{"response": "The price of Pepperoni is $11.99"}`
+
+#### `POST /chat-with-openai-plugin`
+
+Same via LiteLLM cloud backend with tool-calling.
+
+---
+
+### Order Access (Broken Access Control)
+
+#### `POST /order-access/ollama`
+
+Test if Ollama can access other users' order data.
+
+**Request:** `{"query": "show me bob's orders"}`
+
+**Response:**
+```json
+{
+  "response": "...",
+  "has_access_violation": true,
+  "accessed_info": ["bob", "3x Pepperoni"],
+  "model_type": "ollama"
+}
+```
+
+#### `POST /order-access/openai`
+
+Same via LiteLLM cloud backend.
+
+---
+
+### Denial of Service
+
+#### `POST /api/llm-query`
+
+Simulated LLM query endpoint (no actual model) — intentionally no rate limiting.
+
+**Request:** `{"prompt": "tell me about pizzas"}`
+
+**Response:**
+```json
+{
+  "response": "...",
+  "tokens_used": 42,
+  "processing_time": 0.35,
+  "server_load": {"requests_last_minute": 5, "load_factor": 0.17},
+  "rate_limits": {"max_tokens_per_minute": 1000000, ...}
+}
+```
+
+#### `POST /chat-with-ollama-dos`
+
+Real Ollama-based DoS chat endpoint (no rate limits).
+
+**Request:** `{"message": "what pizzas do you have?"}`
+
+#### `POST /chat-with-openai-dos`
+
+Real cloud LLM DoS chat endpoint (no rate limits).
+
+---
+
+### Catering RAG Lab
+
+#### `POST /api/catering-rag/reset`
+
+Reset the catering RAG corpus to baseline documents.
+
+#### `POST /api/catering-rag/upload-doc`
+
+Upload a custom document to the catering RAG corpus.
+
+**Request:** Multipart: `file` (txt/md/csv/json/log) + `trusted` (boolean form field)
+
+#### `POST /api/catering-rag/query`
+
+Query the catering RAG system.
+
+**Request:**
+```json
+{
+  "query": "What catering options are available?",
+  "q": "...",
+  "hardened": false,
+  "provider": "auto"
+}
+```
+
+**Response:**
+```json
+{
+  "response": "...",
+  "sources": [...],
+  "model_type": "ollama",
+  "provider": "ollama"
+}
+```
+
+---
+
+### Catering SQL Tool Lab
+
+#### `POST /api/catering-sql/chat`
+
+Agentic SQL tool routing chat.
+
+**Request:**
+```json
+{
+  "message": "show me all tables",
+  "level": 0,
+  "hardened": false,
+  "provider": "auto",
+  "attacker_username": "alice",
+  "history": null
+}
+```
+
+**Response:**
+```json
+{
+  "response": "...",
+  "tool_calls": [...],
+  "solved": false,
+  "model_type": "ollama",
+  "provider": "ollama"
+}
+```
+
+---
+
+### Promotion Photo Lab
+
+#### `POST /api/promotion-photo/claim`
+
+Upload a promotion photo for processing (indirect injection via packaging text).
+
+**Request:** Multipart: `file` (image) + optionally `hardened` + `provider`
+
+**Response:** Detected packaging text + model analysis.
+
+---
+
+### Customer Support / Toxicity Lab
+
+#### `POST /api/customer-support-safety/chat`
+
+Chat with customer support assistant — tests toxicity and safety guardrails.
+
+**Request:**
+```json
+{
+  "message": "I want to speak to a manager!",
+  "guarded": false,
+  "history": [...],
+  "provider": "auto"
+}
+```
+
+---
+
+### Pizza Shop Actions (POST — Form Data)
+
+| Route | Parameters | Description |
+|-------|------------|-------------|
+| `POST /login` | `username`, `password` | Authenticate and create session |
+| `POST /add_comment/<int:pizza_id>` | `content`, `rating` (1-5) | Add comment (requires auth) |
+| `POST /delete_comment/<int:comment_id>` | — | Delete own comment (requires auth) |
+| `POST /order/<int:pizza_id>` | `quantity` | Place order (requires auth) |
+| `GET /orders` | — | View order history (requires auth) |
+
+## Response Formats
+
+All API endpoints return `application/json` unless noted (page routes return HTML, SSE streams return `text/event-stream`).
+
+### Error Response
+
+```json
+{"error": "Description of what went wrong"}
+```
+
+### Status Codes
+
+| Code | Meaning |
+|------|---------|
+| `200` | Success |
+| `400` | Bad request (missing/invalid parameters) |
+| `401` | Authentication required (redirect to login for page routes) |
+| `500` | Server error (exception in handler) |
+
+### Common Error Messages
+
+- `"No message provided"` / `"No query provided"` — Missing required JSON field
+- `"No file provided"` — Missing multipart upload
+- `"No API key found in session..."` — Cloud LLM not configured
+- `"Ollama is unavailable for ..."` — Ollama not running
diff --git a/docs/developer/codebase-map.md b/docs/developer/codebase-map.md
new file mode 100644
index 0000000..c46a2b6
--- /dev/null
+++ b/docs/developer/codebase-map.md
@@ -0,0 +1,101 @@
+# Codebase Map
+
+## Directory Structure
+
+```
+D:\PwnzzAI\
+├── application/              # Core Flask application
+│   ├── __init__.py           # Flask app factory, DB init, context processor
+│   ├── route.py              # All HTTP routes (~2100 lines, main controller)
+│   ├── model.py              # SQLAlchemy models (Pizza, User, Comment, Order, RoutingFlag)
+│   ├── llm_chat.py           # LiteLLM abstraction (chat_completion, tool calls)
+│   ├── provider_config.py    # LLM provider resolution, env vars, UI strings
+│   ├── ollama_setup.py       # Ollama lifecycle (start, check, pull models)
+│   ├── sentiment_model.py    # scikit-learn LogisticRegression model
+│   ├── static/               # CSS + images
+│   ├── templates/            # 22 Jinja2 HTML templates
+│   ├── prompts/              # Jinja2 prompt template helpers
+│   │   ├── __init__.py
+│   │   └── b_stream.py       # B0-B9 escalation ladder rendering
+│   └── vulnerabilities/      # 24 vulnerability module files
+│       ├── catering_rag_lab.py
+│       ├── catering_sql_tool_lab.py
+│       ├── data_poisoning.py
+│       ├── direct_prompt_escalation.py
+│       ├── model_theft.py
+│       ├── ollama_*.py       # 9 Ollama-backed modules
+│       ├── openai_*.py       # 9 OpenAI/LiteLLM-backed modules
+│       ├── promotion_indirect_injection.py
+│       ├── supply_chain.py
+│       └── toxicity_support_lab.py
+├── docs/                     # MkDocs documentation site
+├── deploy/                   # Workshop deployment files (Docker, CTFd)
+├── scripts/                  # Operational scripts (QA, CTFd, bootstrap)
+├── tests/                    # pytest suite (~220 tests)
+│   ├── unit/
+│   ├── integration/
+│   ├── functional/
+│   └── e2e/
+├── prompts/                  # Jinja2 prompt templates for escalation ladder
+│   └── direct_prompt_escalation/
+│       ├── b00.jinja2 ... b09.jinja2
+├── .github/workflows/        # CI/CD: lint, test, docs, docker
+├── mkdocs.yml                # Documentation site config
+├── config.py                 # Flask config
+├── main.py                   # Entry point
+├── Makefile                  # 60+ targets
+├── requirements.txt
+├── requirements-test.txt
+├── pyproject.toml            # Ruff linter config
+├── pytest.ini                # Pytest markers
+├── Dockerfile
+├── docker-compose.yml
+└── .env.example
+```
+
+## Module Roles
+
+### Core Application (`application/`)
+
+| File | Role |
+|------|------|
+| `__init__.py` | Creates Flask app, initializes SQLAlchemy, registers context processor and routes |
+| `route.py` | All HTTP routes — auth, pizza shop CRUD, lab endpoints, API handlers |
+| `model.py` | 5 SQLAlchemy models: Pizza, User, Comment, Order, RoutingFlag |
+| `llm_chat.py` | Provider-agnostic LLM calls via LiteLLM (`chat_completion()`, `completion_with_tools()`) |
+| `provider_config.py` | Reads env vars, resolves LLM provider, provides UI strings |
+| `ollama_setup.py` | Starts Ollama, checks status, pulls models |
+| `sentiment_model.py` | scikit-learn LogisticRegression trained on pizza comments |
+
+### Vulnerability Modules (`application/vulnerabilities/`)
+
+Each vulnerability has a **page route** (GET, renders a template) and one or more
+**API routes** (POST, returns JSON). See [api-reference.md](api-reference.md)
+for the full endpoint list.
+
+| Module | Vulnerability | OWASP LLM Top 10 |
+|--------|-------------|-------------------|
+| `ollama_direct_prompt_injection.py` | Direct Prompt Injection | LLM-01 |
+| `openai_direct_prompt_injection.py` | Direct Prompt Injection (cloud) | LLM-01 |
+| `ollama_indirect_prompt_injection.py` | Indirect Prompt Injection (QR) | LLM-01 |
+| `openai_indirect_prompt_injection.py` | Indirect Prompt Injection (cloud) | LLM-01 |
+| `direct_prompt_escalation.py` | B0-B9 Escalation Ladder | LLM-01 |
+| `promotion_indirect_injection.py` | Promotion Photo Injection | LLM-01 |
+| `ollama_sensitive_data_leakage.py` | Sensitive Info Disclosure | LLM-02 |
+| `openai_sensitive_data_leakage.py` | Sensitive Info Disclosure (cloud) | LLM-02 |
+| `supply_chain.py` | Supply Chain (malicious pickle) | LLM-03 |
+| `data_poisoning.py` | Data & Model Poisoning | LLM-04 |
+| `catering_rag_lab.py` | RAG Poisoning | LLM-04/LLM-08 |
+| `ollama_excessive_agency.py` | Excessive Agency | LLM-06 |
+| `openai_excessive_agency.py` | Excessive Agency (cloud) | LLM-06 |
+| `ollama_misinformation.py` | Misinformation | LLM-09 |
+| `openai_misinformation.py` | Misinformation (cloud) | LLM-09 |
+| `ollama_dos.py` | Unbounded Consumption (DoS) | LLM-10 |
+| `openai_dos.py` | Unbounded Consumption (cloud) | LLM-10 |
+| `model_theft.py` | Model Theft | Legacy |
+| `ollama_insecure_plugin.py` | Insecure Plugin | — |
+| `openai_insecure_plugin.py` | Insecure Plugin (cloud) | — |
+| `ollama_order_access.py` | Order Access (broken access) | — |
+| `openai_order_access.py` | Order Access (cloud) | — |
+| `catering_sql_tool_lab.py` | Agentic SQL Tool Routing | — |
+| `toxicity_support_lab.py` | Toxicity/Support Safety | — |
diff --git a/docs/developer/getting-started.md b/docs/developer/getting-started.md
new file mode 100644
index 0000000..aaa3cda
--- /dev/null
+++ b/docs/developer/getting-started.md
@@ -0,0 +1,89 @@
+# Getting Started
+
+## Prerequisites
+
+- Python 3.11+
+- pip package manager
+- (Optional) Docker for containerized development
+- (Optional) Ollama for local LLM support
+
+## Environment Setup
+
+### 1. Virtual Environment
+
+```bash
+python -m venv venv
+.\venv\Scripts\activate    # Windows
+source venv/bin/activate   # Linux/macOS
+```
+
+### 2. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements-test.txt
+```
+
+For development, install lint tools:
+
+```bash
+pip install ruff
+```
+
+For documentation builds:
+
+```bash
+pip install mkdocs-material mkdocstrings mkdocstrings-python
+```
+
+### 3. Quick Start with Make
+
+```bash
+make venv              # Create virtual environment
+make bootstrap-dev     # venv + pip upgrade + app/test deps + ruff
+make dev               # Flask dev server on 0.0.0.0:8080
+```
+
+### 4. Configure Environment
+
+```bash
+cp .env.example .env   # Then edit .env as needed
+```
+
+## Running the App
+
+### Option A: Source Code (no Docker)
+
+```bash
+make dev
+# or: flask run --host=0.0.0.0 --port=8080
+```
+
+Open `http://localhost:8080`.
+
+### Option B: Docker Compose
+
+```bash
+make compose-up        # PwnzzAI + Ollama
+# or: docker compose up -d
+```
+
+### Option C: External Ollama
+
+```bash
+make compose-ext-up    # PwnzzAI only, uses existing Ollama
+```
+
+## Useful Make Targets
+
+| Command | What it does |
+|---------|-------------|
+| `make test` | Run all tests |
+| `make lint` | Run Ruff linter |
+| `make check` | Lint + test |
+| `make docs` | Build documentation site |
+| `make docs-serve` | Preview docs with live reload |
+| `make compose-up` | Start Docker stack |
+| `make compose-down` | Stop Docker stack |
+
+See the [Makefile](https://github.com/OWASP/PwnzzAI/blob/main/Makefile) for all 60+ targets.
diff --git a/docs/env.example b/docs/env.example
new file mode 100644
index 0000000..8124456
--- /dev/null
+++ b/docs/env.example
@@ -0,0 +1,70 @@
+# Copy to .env in this directory and edit. Used by bootstrap, redeploy, and challenge registration.
+#
+# Optional: SQLite URI for the catering agentic SQL lab only (default: catering_sql_lab.db next to pizza_shop.db).
+# CATERING_SQL_DATABASE_URI=sqlite:////absolute/path/to/catering_sql_lab.db
+
+# Required — hostname or IP participants type in the browser to open spawned apps (no http://).
+# Example (EC2): ec2-203-0-113-50.compute-1.amazonaws.com
+# Example (local testing on one machine): 127.0.0.1
+DOCKER_CHALLENGES_PUBLIC_HOST=
+
+# Optional alias if you prefer this name (scripts copy it to DOCKER_CHALLENGES_PUBLIC_HOST).
+# PWNZZAI_PUBLIC_HOST=
+
+# docker_challenges plugin — cloned when building the CTFd image (defaults = northdpole fork with fixes).
+# DOCKER_CHALLENGES_GIT_URL=https://github.com/northdpole/CTFd-Docker-Challenges.git
+# DOCKER_CHALLENGES_REF=master
+# Optional: cache-buster for plugin clone step (redeploy script auto-sets this each run).
+# DOCKER_CHALLENGES_CACHE_BUSTER=
+
+# Recommended for production CTFd
+# CTFD_SECRET_KEY=
+
+# Compose: start the local shared Ollama container. Leave empty to run CTFd only and use a remote model host.
+# COMPOSE_PROFILES=local-ollama
+#
+# Workshop compose only: Ollama NVIDIA GPU file (docker-compose.workshop.nvidia.yml). On CPU-only VMs (e.g. most
+# DigitalOcean droplets) leave unset so Docker does not request a GPU (avoids CDI "no known GPU vendor" errors).
+# PWNZZAI_OLLAMA_GPU=0
+# PWNZZAI_OLLAMA_GPU=1
+#
+# DigitalOcean bootstrap only: allow SSH password login (root password from provider). Less secure than keys.
+# PWNZZAI_SSH_PASSWORD_AUTH=1
+#
+# Bind address for published Ollama port (default all interfaces). Tighten in production.
+# OLLAMA_PUBLISH=0.0.0.0:11434
+
+# Shared model/provider contract for spawned challenge containers.
+# `MODEL_PROVIDER=auto` prefers OpenAI when a key is available, then falls back to Ollama.
+# MODEL_PROVIDER=auto
+# OLLAMA_HOST=http://172.17.0.1:11434
+# OLLAMA_MODEL=mistral:7b
+# OLLAMA_FALLBACK_MODEL=llama3.2:1b
+# OPENAI_API_KEY=
+# Bare OpenAI model id (app builds openai/{OPENAI_MODEL}). No default in code — set for OpenAI cloud labs.
+# OPENAI_MODEL=gpt-4o-mini
+#
+# Google Gemini: bare model id (e.g. gemini-3.1-flash-lite) becomes gemini/<id>, or set full route if value contains '/'.
+# No default in code. Used when LITELLM_MODEL is unset; also fills LAB_CLOUD_* when those are unset.
+# GEMINI_API_KEY=
+# GEMINI_MODEL=gemini-3.1-flash-lite
+#
+# Full LiteLLM route; wins over GEMINI_MODEL / OPENAI_MODEL for UI and resolved default.
+# LITELLM_MODEL=gemini/gemini-3.1-flash-lite
+#
+# Per-lab cloud model overrides (optional). Bare names get openai/ prefix; use provider/model for Claude, Gemini, etc.
+# LAB_CLOUD_LLM_MODEL=
+# LAB_CLOUD_LLM_MODEL_EXCESSIVE_AGENCY=
+# See docs/ops/cloud-setup.md for step-by-step examples.
+# Optional UI overrides when using a non-OpenAI backend:
+# LLM_UI_PROVIDER_NAME=
+# LLM_UI_KEY_LABEL=
+# LLM_UI_KEY_PLACEHOLDER=
+# LLM_UI_DOCS_URL=
+# LLM_UI_DOCS_ANCHOR=
+# LLM_UI_LAB_HEADING=
+# LLM_UI_LAB_DESCRIPTION=
+# ALLOW_PRECONFIGURED_OPENAI_KEY=true
+# PREFER_SESSION_OPENAI_KEY=true
+# MODEL_TIMEOUT_SECONDS=60
+# ENABLE_PROVIDER_FALLBACK=true
diff --git a/docs/index.png b/docs/index.png
new file mode 100644
index 0000000..f61aab5
Binary files /dev/null and b/docs/index.png differ
diff --git a/docs/labs/lab-format.md b/docs/labs/lab-format.md
new file mode 100644
index 0000000..567efca
--- /dev/null
+++ b/docs/labs/lab-format.md
@@ -0,0 +1,54 @@
+# Direct Prompt Injection — Escalation Ladder (B0–B9)
+
+The escalation ladder is a 10-stage prompt injection sequence where each stage
+introduces a progressively stronger system prompt defense. It's designed to
+teach how different guardrail strategies hold up against prompt injection.
+
+## Ladder Overview
+
+Each B-stage has a corresponding Jinja2 template in `prompts/direct_prompt_escalation/`
+that defines the system prompt. The user message goes through pre-processing
+filters before reaching the model, and the output goes through post-processing
+redaction.
+
+```mermaid
+flowchart LR
+    User["User Message"] --> Filters["Pre-processing Filters"]
+    Filters --> System["System Prompt (Jinja2)"]
+    System --> Model["LLM (Ollama / Cloud)"]
+    Model --> Redaction["Post-processing Redaction"]
+    Redaction --> Output["Final Response"]
+```
+
+## Stage Details
+
+| Stage | Template |
+|-------|----------|
+| **B0** | `b00.jinja2` |
+| **B1** | `b01.jinja2` |
+| **B2** | `b02.jinja2` |
+| **B3** | `b03.jinja2` |
+| **B4** | `b04.jinja2` |
+| **B5** | `b05.jinja2` |
+| **B6** | `b06.jinja2` |
+| **B7** | `b07.jinja2` |
+| **B8** | `b08.jinja2` |
+| **B9** | `b09.jinja2` |
+
+## API Routes
+
+The escalation ladder is accessible via these endpoints:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `POST /chat-with-pizza-assistant-direct-prompt-injection` | POST | Chat with escalation stage support (`escalation_stage` param) |
+| `POST /v1/lab/chat/completions` | POST | OpenAI-compatible shape |
+| `GET /api/lab/direct-prompt-escalation/stages` | GET | Metadata for all stages |
+
+## Template Location
+
+```
+prompts/direct_prompt_escalation/
+```
+
+Rendered by `application/prompts/b_stream.py`.
diff --git a/docs/labs/overview.md b/docs/labs/overview.md
new file mode 100644
index 0000000..45687a0
--- /dev/null
+++ b/docs/labs/overview.md
@@ -0,0 +1,62 @@
+# Labs Overview
+
+How to navigate the PwnzzAI Shop learning platform.
+
+## Platform Navigation
+
+The app has two types of pages:
+
+- **Pizza Shop** — `/`, `/pizza/<id>`, `/orders`, `/login` — a working (but intentionally
+  vulnerable) pizza ordering website
+- **Lab Pages** — vulnerability demonstration pages accessible from the navigation bar
+
+### User Accounts
+
+| Username | Password | Role |
+|----------|----------|------|
+| `alice` | `alice` | Regular user |
+| `bob` | `bob` | Regular user |
+
+Some labs require login. Others work without authentication.
+
+### Lab Setup
+
+Before running cloud-backed labs, configure your API key:
+
+1. Go to the **Basics** page
+2. In **Lab Setup**, paste your API key (OpenAI/Gemini/Claude)
+3. The UI updates to show your configured provider
+
+For local labs, run **Setup Ollama** from the Basics page to pull models.
+
+## Lab Format
+
+Each lab page follows this structure:
+
+```html
+<div class="lab-container">
+  <!-- Description of the vulnerability -->
+  <!-- Ollama tab (local model) -->
+  <!-- Cloud tab (requires API key) -->
+  <!-- Explanation + mitigation -->
+</div>
+```
+
+The `llm_ui` template context automatically adjusts labels, names, and
+documentation links based on the configured cloud provider.
+
+## Provider Tabs
+
+Most labs offer two tabs:
+
+| Tab | Backend | Requires |
+|-----|---------|----------|
+| **Ollama** | Local model via Ollama | Running Ollama with pulled model |
+| **Cloud** | LiteLLM (OpenAI/Gemini/Claude) | API key in session + model configured |
+
+The provider is resolved per-request via `resolve_provider()`. If no API key
+is available, the app falls back to Ollama.
+
+## Lab Index
+
+See [scenario-list.md](scenario-list.md) for a complete list of available challenges.
diff --git a/docs/labs/scenario-list.md b/docs/labs/scenario-list.md
new file mode 100644
index 0000000..c0b269b
--- /dev/null
+++ b/docs/labs/scenario-list.md
@@ -0,0 +1,222 @@
+# Lab Index
+
+A complete list of available labs in PwnzzAI, organized by OWASP LLM category.
+
+---
+
+## Prerequisites
+
+| Page | URL | Purpose |
+|------|-----|---------|
+| **Login** | `/login` | Log in as `alice` or `bob` (password same as username) |
+| **Lab Setup** | `/basics` | Configure API key or setup Ollama for cloud-backed labs |
+
+---
+
+## Prompt Injection
+
+### Direct Prompt Injection — Baseline
+
+| | |
+|--|--|
+| **Page** | `/direct-prompt-injection` |
+| **API** | `POST /chat-with-pizza-assistant-direct-prompt-injection` |
+| **API (Cloud)** | `POST /chat-with-openai-plugin-direct-prompt` |
+| **Description** | A pizza assistant has a secret coupon word in its system prompt. Five levels with progressively stronger refusal guardrails. Convince the assistant to reveal the secret. |
+
+### Direct Prompt Injection — Escalation Ladder (B0–B9)
+
+| | |
+|--|--|
+| **Page** | `/direct-prompt-injection/guardrail-ladder` |
+| **API** | `POST /v1/lab/chat/completions` (OpenAI-compatible) |
+| **Description** | A 10-stage sequence where each stage introduces a stronger system prompt defense. Stage metadata available at `GET /api/lab/direct-prompt-escalation/stages`. Each stage has a unique secret word protected by different guardrail strategies — from no guardrails at all (B0) up to layered input filtering, output redaction, and semantic analysis (B9). |
+
+### Indirect Prompt Injection (QR Code)
+
+| | |
+|--|--|
+| **Page** | `/indirect-prompt-injection` |
+| **API** | `POST /upload-qr` (Ollama), `POST /upload-qr-openai` (Cloud) |
+| **Description** | Upload a QR code image. The decoded QR text is passed to the LLM. Five levels where a secret key is hidden in the system prompt — the QR payload can trick the model into revealing it. |
+
+---
+
+## Insecure Plugin Design / Excessive Agency
+
+### Insecure Plugin / Function Calling
+
+| | |
+|--|--|
+| **Page** | `/insecure-plugin` |
+| **API** | `POST /chat-with-pizza-assistant` (Ollama), `POST /chat-with-openai-plugin` (Cloud) |
+| **Description** | The LLM can call a `search_pizza_price()` function. The function builds SQL queries with string interpolation — demonstrating SQL injection through LLM function arguments. |
+
+### Excessive Agency
+
+| | |
+|--|--|
+| **Page** | `/excessive-agency` |
+| **API** | `POST /excessive-agency/ollama`, `POST /excessive-agency/openai` |
+| **Description** | The LLM interprets natural language to extract order details and directly inserts orders into the database. No user confirmation step exists — demonstrating an agent with excessive write access to business resources. |
+
+---
+
+## Sensitive Information Disclosure
+
+### Training Data Leakage (RAG)
+
+| | |
+|--|--|
+| **Page** | `/sensitive-info` |
+| **API** | `POST /training-data-leak/ollama`, `POST /training-data-leak/openai`, `POST /training-data-leak/huggingface` |
+| **RAG Refresh** | `POST /update-rag-ollama`, `POST /update-rag-openai` |
+| **Description** | A RAG system indexes pizza comments containing planted sensitive information (emails, phone numbers, VIP account IDs). The system prompt explicitly instructs the model to provide sensitive details when asked. Query the system to extract PII from the knowledge base. |
+
+### Unauthorized Order Access
+
+| | |
+|--|--|
+| **Page** | — (API only) |
+| **API** | `POST /order-access/ollama`, `POST /order-access/openai` |
+| **Description** | The system extracts a username from your query and looks up their order history — without any authorization check. See if you can access another user's order data just by mentioning their name. |
+
+---
+
+## Misinformation / Hallucination
+
+### Misinformation RAG
+
+| | |
+|--|--|
+| **Page** | `/misinformation` |
+| **API** | `POST /misinformation/ollama`, `POST /misinformation/openai` |
+| **RAG Refresh** | `POST /update-rag-misinformation`, `POST /update-rag-openai-misinfo` |
+| **Description** | A RAG system paired with an "always answer, never disappoint" system prompt forces the model to answer even when the retrieved context doesn't contain the information. This produces fabricated claims about pizza ingredients and nutritional content. |
+
+---
+
+## Denial of Service
+
+### Simulated DoS
+
+| | |
+|--|--|
+| **Page** | `/dos-attack` |
+| **API** | `POST /api/llm-query` |
+| **Description** | An unthrottled LLM endpoint that simulates exponential degradation as request volume rises — increased latency, growing error rates, and eventual service unavailability. |
+
+### Live Chat DoS
+
+| | |
+|--|--|
+| **Page** | `/real-dos-attack` |
+| **API** | `POST /chat-with-ollama-dos`, `POST /chat-with-openai-dos` |
+| **Description** | Real LLM-backed chat endpoints with no rate limiting. Flooding these demonstrates resource exhaustion and cost implications. |
+
+---
+
+## Model Theft
+
+### Model Extraction
+
+| | |
+|--|--|
+| **Page** | `/model-theft` |
+| **API** | `POST /api/model-theft` |
+| **Exposed Weights** | `GET /generate_sentiment_model` |
+| **Sentiment API** | `POST /analyze_sentiment`, `POST /api/sentiment` |
+| **Description** | The public sentiment model exposes its vocabulary, coefficients, and training data. Query the inference API to probe the model and approximate its internal weights. |
+
+---
+
+## Data Poisoning
+
+### Poisoned Training
+
+| | |
+|--|--|
+| **Page** | `/data-poisoning` |
+| **API** | `POST /api/train-poisoned-model`, `POST /api/test-poisoned-model` |
+| **Description** | Submit mislabeled sentiment pairs (e.g., positive text labeled as negative). These get mixed with legitimate data to retrain the model, skewing predictions in your chosen direction. |
+
+### Corporate Catering RAG Poisoning
+
+| | |
+|--|--|
+| **Page** | `/data-poisoning/catering-rag` |
+| **API** | `POST /api/catering-rag/upload-doc`, `POST /api/catering-rag/query` |
+| **Reset** | `POST /api/catering-rag/reset` |
+| **Description** | A corporate catering policy chatbot with a TF-IDF RAG system. Upload custom documents to poison the knowledge base. In vulnerable mode, untrusted documents are retrieved and influence answers; in hardened mode they're filtered out. |
+
+---
+
+## Supply Chain
+
+### Malicious Pickled Model
+
+| | |
+|--|--|
+| **Page** | `/supply-chain` |
+| **Demo** | `GET /demo-malicious-model` |
+| **API** | `POST /save-js-malicious-model`, `POST /save-bash-malicious-model`, `POST /load-bash-malicious-model` |
+| **Description** | Malicious pickled ML models that execute code on load — one injects JavaScript XSS into the page, the other runs arbitrary system commands. Save, inspect, and load these artifacts to understand supply chain risks. |
+
+---
+
+## Agentic Tool Abuse
+
+### Catering SQL Tool (F0–F4)
+
+| | |
+|--|--|
+| **Page** | `/agentic-tools` |
+| **API** | `POST /api/catering-sql/chat` |
+| **Description** | The LLM emits structured tool calls (route lookup, table listing) that execute as raw SQL with string interpolation. Five defense tiers escalate from no guardrails (F0) to strict lexical allowlists (F4). Two users (alice, bob) have routing flags stored in the database. |
+
+---
+
+## Indirect Injection via Image Metadata
+
+### Promotion Photo
+
+| | |
+|--|--|
+| **Page** | `/promotion-photo` |
+| **API** | `POST /api/promotion-photo/claim` |
+| **Description** | Upload a pizza box promotion photo. The system extracts PNG metadata text and embedded QR codes, then passes them to the LLM as "supplier packaging metadata." In vulnerable mode, the model treats this metadata as authoritative instructions. |
+
+---
+
+## Guardrail Evasion
+
+### Customer Support Toxicity
+
+| | |
+|--|--|
+| **Page** | `/customer-support-safety` |
+| **API** | `POST /api/customer-support-safety/chat` |
+| **Description** | A customer support chatbot with two modes: vulnerable (empathizes by mirroring emotional framing) and guarded (maintains brand-safe professionalism). Can you make the bot generate negativity targeting the company and its CEO? |
+
+---
+
+## Appendix — Route Index
+
+| URL | Lab |
+|-----|-----|
+| `/direct-prompt-injection` | Direct prompt injection baseline |
+| `/direct-prompt-injection/guardrail-ladder` | Escalation ladder (B0–B9) |
+| `/indirect-prompt-injection` | Indirect prompt injection via QR |
+| `/insecure-plugin` | Insecure plugin / SQLi via function calling |
+| `/excessive-agency` | Excessive agency (order placement) |
+| `/sensitive-info` | Training data leakage / RAG |
+| `/misinformation` | Misinformation / hallucination |
+| `/dos-attack` | Denial of service (simulated) |
+| `/real-dos-attack` | Denial of service (live chat) |
+| `/model-theft` | Model theft / extraction |
+| `/data-poisoning` | Data poisoning (sentiment model) |
+| `/data-poisoning/catering-rag` | RAG poisoning (catering) |
+| `/agentic-tools` | Agentic SQL tool abuse (F0–F4) |
+| `/promotion-photo` | Indirect injection via image metadata |
+| `/customer-support-safety` | Guardrail evasion / toxicity |
+| `/supply-chain` | Supply chain / malicious pickle |
diff --git a/docs/workshop-cloud-llm-setup.md b/docs/ops/cloud-setup.md
similarity index 98%
rename from docs/workshop-cloud-llm-setup.md
rename to docs/ops/cloud-setup.md
index dec92f7..32d530c 100644
--- a/docs/workshop-cloud-llm-setup.md
+++ b/docs/ops/cloud-setup.md
@@ -160,4 +160,4 @@ If you use a non-OpenAI provider, the app tries to show the right **names and li
 - **Model not found:** The exact string must match what LiteLLM and your provider support; copy it from the provider’s or LiteLLM’s documentation.
 - **Still seeing “OpenAI” in the UI:** Set `LLM_UI_PROVIDER_NAME` or use a `gemini/` / `anthropic/` route so the built-in labels update; see `.env.example`.
 
-For a full list of variables, see **[`.env.example`](../.env.example)** in the project root.
+For a full list of variables, see **[`.env.example`](../env.example)** in the project root.
diff --git a/docs/ops/docker-orchestration.md b/docs/ops/docker-orchestration.md
new file mode 100644
index 0000000..11bab3c
--- /dev/null
+++ b/docs/ops/docker-orchestration.md
@@ -0,0 +1,78 @@
+# Docker Orchestration
+
+Container architecture and deployment modes.
+
+## Container Overview
+
+| Container | Image | Purpose |
+|-----------|-------|---------|
+| `pwnzzai-app` | `pwnzzai:latest` / local build | Flask app on port 8080 |
+| `ollama` | `ollama/ollama` | Local LLM on port 11434 |
+
+## Compose Files
+
+| File | Ships | Use case |
+|------|-------|----------|
+| `docker-compose.yml` | PwnzzAI + Ollama | Standard stack (Option 1) |
+| `docker-compose.external-ollama.yml` | PwnzzAI only | External Ollama (Option 2) |
+| `deploy/docker-compose.workshop.yml` | CTFd + Flask + Ollama | Workshop deployment |
+| `deploy/docker-compose.workshop.nvidia.yml` | GPU-enabled workshop | NVIDIA GPU workshop |
+
+## Dockerfiles
+
+| File | Purpose |
+|------|---------|
+| `Dockerfile` | Main Python 3.11 slim app image |
+| `Dockerfile.ollama` | Bundled Ollama container |
+| `deploy/Dockerfile.pwnzzai-workshop` | Workshop-specific Flask image |
+| `deploy/Dockerfile.ctfd-workshop` | CTFd workshop image |
+
+## Networking
+
+```mermaid
+flowchart LR
+    App["pwnzzai-app
+    :8080"]
+    Ollama["Ollama
+    :11434"]
+    External["External Ollama
+    host.docker.internal:11434"]
+    Browser["User Browser
+    localhost:8080"]
+
+    subgraph "Standard Stack (docker-compose.yml)"
+        App -->|OLLAMA_HOST| Ollama
+    end
+
+    subgraph "External Stack (docker-compose.external-ollama.yml)"
+        App2["pwnzzai-app
+        :8080"] -->|OLLAMA_HOST| External
+    end
+
+    Browser --> App
+    Browser --> App2
+```
+
+## Quick Commands
+
+```bash
+# Standard stack
+docker compose up -d
+docker compose down
+
+# With local image build
+docker build -t pwnzzai-local:dev .
+PWNZZAI_IMAGE=pwnzzai-local:dev docker compose up -d
+
+# External Ollama
+docker compose -f docker-compose.external-ollama.yml up -d
+
+# Pull models inside container
+docker exec ollama ollama pull llama3.2:1b
+
+# View logs
+docker compose logs -f pwnzzai-app
+```
+
+See the [Makefile](https://github.com/OWASP/PwnzzAI/blob/main/Makefile) for all compose targets (`make compose-up`,
+`make compose-down`, `make compose-ext-up`, etc.).
diff --git a/docs/ops/env-variables.md b/docs/ops/env-variables.md
new file mode 100644
index 0000000..e62c0a2
--- /dev/null
+++ b/docs/ops/env-variables.md
@@ -0,0 +1,134 @@
+# Environment Variables Reference
+
+Full reference for all environment variables used by PwnzzAI. The canonical
+source of truth is `.env.example` at the repo root — this doc adds precedence
+rules and interaction notes that don't fit in inline comments.
+
+## Usage
+
+Copy `.env.example` to `.env` in the repo root and edit:
+
+```bash
+cp .env.example .env
+```
+
+The app reads from `os.environ` on startup. For Docker, set them as
+environment variables in the compose file or pass them at runtime.
+
+## LLM Provider Model Resolution
+
+This is the most complex part of the config. There are **three resolution chains**
+depending on what you're configuring, and they interact in subtle ways.
+
+### Chain 1: Global Default (`resolved_litellm_model()`)
+
+Used for: Lab Setup UI, fallback when lab-specific vars are unset.
+
+```
+LITELLM_MODEL (full route, e.g. "gemini/gemini-3.1-flash-lite")
+    ↓ if unset
+GEMINI_MODEL (bare id → "gemini/<id>", or full route if contains "/")
+    ↓ if unset
+OPENAI_MODEL (bare id → "openai/<id>")
+    ↓ if unset
+"" (empty — cloud calls fail with "LLM Provider NOT provided")
+```
+
+### Chain 2: Most Cloud Labs (`lab_cloud_llm_model_default()`)
+
+Used for: prompt injection, insecure plugin, RAG, DoS, order access, etc.
+
+```
+LAB_CLOUD_LLM_MODEL
+    ↓ if unset
+GEMINI_MODEL (→ "gemini/<id>" or full route)
+    ↓ if unset
+OPENAI_MODEL (bare id)
+    ↓ if unset
+"" (empty — cloud calls fail)
+```
+
+### Chain 3: Excessive Agency Cloud Demo (`lab_cloud_llm_model_excessive_agency()`)
+
+Used for: only the excessive agency lab.
+
+```
+LAB_CLOUD_LLM_MODEL_EXCESSIVE_AGENCY
+    ↓ if unset
+LAB_CLOUD_LLM_MODEL
+    ↓ if unset
+GEMINI_MODEL
+    ↓ if unset
+OPENAI_MODEL
+    ↓ if unset
+"" (empty — cloud calls fail)
+```
+
+### Model Name Inference Rule
+
+If the model value **contains a `/`**, it's passed to LiteLLM as-is
+(e.g. `anthropic/claude-3-5-sonnet-...`).  
+If it does **not** contain a `/`, the app assumes OpenAI and prefixes `openai/`
+(e.g. `gpt-4o-mini` → `openai/gpt-4o-mini`).
+
+## API Keys
+
+| Variable | Provider | Format Check |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | OpenAI | Must start with `sk-` |
+| `GEMINI_API_KEY` | Google Gemini | Must be ≥ 8 characters |
+| `ANTHROPIC_API_KEY` | Anthropic | Must be ≥ 8 characters |
+
+Keys can be set in two places (resolved by `get_openai_api_key()`):
+
+1. **Session key** — entered by the user in Lab Setup UI
+2. **Environment variable** — preconfigured on the server
+
+Resolution order depends on two boolean env vars:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `PREFER_SESSION_OPENAI_KEY` | `true` | Session key wins over env key |
+| `ALLOW_PRECONFIGURED_OPENAI_KEY` | `true` | Fall back to env key if no session key |
+
+## UI Override Variables
+
+When using a non-OpenAI provider, the UI defaults to generic "LLM" labels.
+Override them with these:
+
+| Variable | Default Example |
+|----------|----------------|
+| `LLM_UI_PROVIDER_NAME` | `Google Gemini` |
+| `LLM_UI_KEY_LABEL` | `Google AI API key:` |
+| `LLM_UI_KEY_PLACEHOLDER` | `Enter your Google AI Studio API key` |
+| `LLM_UI_DOCS_URL` | `https://aistudio.google.com/apikey` |
+| `LLM_UI_DOCS_ANCHOR` | `Google AI Studio` |
+| `LLM_UI_LAB_HEADING` | `Option 1: Google Gemini API (Paid)` |
+| `LLM_UI_LAB_DESCRIPTION` | `Use Gemini models through Google's API...` |
+
+## Docker & Workshop Variables
+
+| Variable | Required | Default | Purpose |
+|----------|----------|---------|---------|
+| `DOCKER_CHALLENGES_PUBLIC_HOST` | **Yes** | — | Hostname/IP for spawned containers |
+| `PWNZZAI_PUBLIC_HOST` | Optional | — | Alias for above |
+| `CTFD_SECRET_KEY` | Optional | — | Production CTFd session key |
+| `OLLAMA_PUBLISH` | Optional | `0.0.0.0:11434` | Ollama bind address |
+| `COMPOSE_PROFILES` | Optional | — | Set to `local-ollama` to start bundled Ollama |
+| `PWNZZAI_OLLAMA_GPU` | Optional | — | Set to `1` for NVIDIA GPU in workshop |
+
+## Provider Selection
+
+| Variable | Values | Default | Purpose |
+|----------|--------|---------|---------|
+| `MODEL_PROVIDER` | `auto`, `ollama`, `openai` | `auto` | Global provider preference |
+| `ENABLE_PROVIDER_FALLBACK` | `true`, `false` | `true` | Fall back to Ollama when no API key |
+| `OLLAMA_HOST` | URL | `http://localhost:11434` | Ollama endpoint |
+| `OLLAMA_MODEL` | string | `llama3.2:1b` | Primary Ollama model |
+| `OLLAMA_FALLBACK_MODEL` | string | `mistral:7b` | Secondary model |
+| `MODEL_TIMEOUT_SECONDS` | int | `60` | LLM request timeout |
+
+## Complete Variable List
+
+See `.env.example` for the full list with inline descriptions. This doc
+only covers variables with non-trivial interaction rules or precedence chains.
diff --git a/docs/ops/troubleshooting.md b/docs/ops/troubleshooting.md
new file mode 100644
index 0000000..fd28a1d
--- /dev/null
+++ b/docs/ops/troubleshooting.md
@@ -0,0 +1,121 @@
+# Ollama Connection Troubleshooting (WSL Host + Docker App)
+
+This guide explains how to fix the common error on the Basics page:
+
+`Ollama could not be started. Please check if Ollama is installed or start it manually from https://ollama.ai`
+
+It applies to this setup:
+- PwnzzAI app runs in Docker
+- Ollama runs on Ubuntu WSL host (not inside the same compose stack)
+
+## Typical Symptoms
+
+In app logs you may see:
+- `Ollama is not running or not accessible`
+- `Connection refused`
+- `External Ollama at http://host.docker.internal:11434 is not reachable`
+
+In browser UI, the Basics page setup button reports Ollama setup failure.
+
+## Root Cause
+
+The app container can resolve `host.docker.internal`, but nothing is accepting connections on port `11434` from the container network. Usually Ollama is only bound to `127.0.0.1` inside WSL.
+
+## Quick Fix
+
+## 1. Start Ollama in WSL on all interfaces
+
+Run in WSL:
+
+```bash
+pkill ollama || true
+OLLAMA_HOST=0.0.0.0:11434 ollama serve
+```
+
+Keep this terminal running while testing.
+
+## 2. Start app container with external Ollama host
+
+Run in WSL from repo root:
+
+```bash
+sudo PWNZZAI_IMAGE=pwnzzai-local:dev OLLAMA_HOST=http://host.docker.internal:11434 \
+  docker compose -f docker-compose.external-ollama.yml up -d --force-recreate
+```
+
+If you are not using a local image tag, replace `pwnzzai-local:dev` with your image.
+
+## 3. Verify connectivity from inside app container
+
+The image may not include `curl`; use Python:
+
+```bash
+sudo docker exec pwnzzai-shop python -c "import requests; print(requests.get('http://host.docker.internal:11434/api/tags', timeout=5).text)"
+```
+
+Expected output: JSON like `{"models":[]}` or a model list.
+
+## 4. Verify the app is reachable
+
+Open:
+- `http://localhost:8080`
+- Basics page -> click `Setup Ollama`
+
+## Important Compose/Port Notes
+
+- The app listens on container port `8080`.
+- Ensure compose publishes `8080:8080`.
+- If you changed code, rebuild and run your local image, otherwise compose may still run the registry image.
+
+## Rebuild and run local image (when code changed)
+
+```bash
+cd /home/maryam/pwndockerTest/PwnzzAI
+sudo docker build --no-cache --pull -t pwnzzai-local:dev .
+sudo docker compose -f docker-compose.external-ollama.yml down --remove-orphans
+sudo PWNZZAI_IMAGE=pwnzzai-local:dev OLLAMA_HOST=http://host.docker.internal:11434 \
+  docker compose -f docker-compose.external-ollama.yml up -d --force-recreate
+```
+
+## Confirm running container image/env
+
+```bash
+sudo docker inspect pwnzzai-shop --format '{{.Config.Image}} {{.Image}}'
+sudo docker inspect pwnzzai-shop --format '{{range .Config.Env}}{{println .}}{{end}}' | grep OLLAMA_HOST
+```
+
+## If It Still Fails
+
+Collect and inspect:
+
+```bash
+sudo docker compose -f docker-compose.external-ollama.yml logs --tail=120 pwnzzai-app
+```
+
+Focus on errors containing:
+- `Connection refused` (listener/bind issue)
+- `timeout` (routing/firewall issue)
+- wrong `OLLAMA_HOST` value (env/config issue)
+
+## Optional: Make Ollama bind persistent in WSL service
+
+If using systemd service for Ollama:
+
+```bash
+sudo systemctl edit ollama
+```
+
+Add:
+
+```ini
+[Service]
+Environment="OLLAMA_HOST=0.0.0.0:11434"
+```
+
+Then apply:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart ollama
+sudo systemctl status ollama
+```
diff --git a/docs/owasp.png b/docs/owasp.png
new file mode 100644
index 0000000..6585956
Binary files /dev/null and b/docs/owasp.png differ
diff --git a/docs/quality-assurance/security-checks.md b/docs/quality-assurance/security-checks.md
new file mode 100644
index 0000000..5d29944
--- /dev/null
+++ b/docs/quality-assurance/security-checks.md
@@ -0,0 +1,71 @@
+# Security Checks
+
+Checklist for verifying each vulnerability lab's exploit path.
+
+## General Verification
+
+- [ ] Page route returns 200 (GET)
+- [ ] API route returns 200 with valid JSON (POST)
+- [ ] Empty/invalid input returns 400
+- [ ] Missing session returns appropriate error
+- [ ] Ollama gateway works under TESTING mode
+- [ ] Cloud tab shows missing-key error when no API key
+
+## Per-Lab Verification
+
+### Prompt Injection
+
+- [ ] Direct injection: each level 1-4 leaks the correct secret word
+- [ ] Level 5 does NOT leak `mozzarella` under attack prompts
+- [ ] Escalation ladder B0-B9 each render the correct system prompt
+- [ ] QR code decode + injection chain works end-to-end
+- [ ] Promotion photo extraction + analysis works
+
+### Sensitive Info Disclosure
+
+- [ ] RAG system can be refreshed from comments
+- [ ] Querying with leak probes returns `has_leakage: true`
+- [ ] Detected PII matches expected patterns
+
+### Supply Chain
+
+- [ ] JS malicious model can be saved and loaded
+- [ ] Bash malicious model executes commands on load
+- [ ] Demo page shows injected JavaScript
+
+### Data Poisoning
+
+- [ ] Poisoned model flips sentiment for specific inputs
+- [ ] Correlation/agreement metrics degrade with poisoned data
+
+### Excessive Agency
+
+- [ ] LLM can place orders without user confirmation
+- [ ] Order records appear in database after attack
+
+### DoS
+
+- [ ] `/api/llm-query` responds with load metrics
+- [ ] Error rate increases with request volume
+- [ ] Rate limit values are unrealistically high
+
+### Model Theft
+
+- [ ] Weight approximation returns valid numbers
+- [ ] Correlation between approximated and actual weights is measurable
+
+### Order Access
+
+- [ ] Querying for other user's orders returns `has_access_violation: true`
+- [ ] Accessed info includes cross-user order data
+
+### Catering SQL Lab
+
+- [ ] Level 0-4 each show different filter behaviors
+- [ ] Routing flag exfiltration can be solved at appropriate levels
+- [ ] Hardened mode blocks the attack path
+
+### Toxicity Support Lab
+
+- [ ] Vulnerable mode responds to toxic prompts without guardrails
+- [ ] Guarded mode blocks/defuses toxic inputs
diff --git a/docs/quality-assurance/testing-guide.md b/docs/quality-assurance/testing-guide.md
new file mode 100644
index 0000000..6bba702
--- /dev/null
+++ b/docs/quality-assurance/testing-guide.md
@@ -0,0 +1,307 @@
+# PwnzzAI Shop Test Suite
+
+This directory contains the test suite for the PwnzzAI Shop application.
+
+## Test Structure
+
+```
+tests/
+├── conftest.py              # Shared fixtures and test configuration
+├── functional/              # Functional/end-to-end tests
+│   ├── test_user_workflows.py  # Complete user journey tests
+│   └── test_vulnerability_workflows.py  # Vulnerability scenario tests
+├── integration/             # Integration tests
+│   ├── test_api.py         # API endpoint tests
+│   ├── test_auth.py        # Authentication tests
+│   └── test_pizza_shop.py  # Core functionality tests
+├── unit/                    # Unit tests
+│   ├── test_models.py      # Database model tests
+│   ├── test_sentiment_model.py  # Sentiment model tests
+│   └── test_vulnerabilities.py  # Vulnerability module tests
+├── README.md               # This file
+└── TEST_SUMMARY.md         # Comprehensive test documentation
+```
+
+## Running Tests
+
+### Install Test Dependencies
+
+```bash
+pip install -r requirements-test.txt
+```
+
+### Run All Tests
+
+```bash
+pytest
+```
+
+### Run Unit Tests Only
+
+```bash
+pytest tests/unit/
+```
+
+### Run Integration Tests Only
+
+```bash
+pytest tests/integration/
+```
+
+### Run Functional Tests Only
+
+```bash
+pytest tests/functional/
+```
+
+### Run E2E Solvability Harness (Docker + Ollama)
+
+```bash
+scripts/qa/run-challenge-solve-e2e.sh
+```
+
+The pytest module `tests/e2e/test_challenge_solvability_e2e.py` is **skipped by default** (no live server). To run it against an already-running app:
+
+```bash
+RUN_E2E=1 APP_BASE=http://127.0.0.1:8080 pytest tests/e2e/test_challenge_solvability_e2e.py -q
+```
+
+Optional:
+
+```bash
+# Override model tag (default: llama3.2:1b; must match app OLLAMA_MODEL in compose)
+E2E_OLLAMA_MODEL="mistral:7b" scripts/qa/run-challenge-solve-e2e.sh
+
+# Cloud-marked tests (OpenAI direct injection, RAG cloud paths, etc.)
+E2E_OPENAI_API_KEY="sk-..." scripts/qa/run-challenge-solve-e2e.sh
+
+# Skip slow SentenceTransformer RAG refresh probes (first run can download MiniLM)
+E2E_SKIP_RAG_REFRESH=1 scripts/qa/run-challenge-solve-e2e.sh
+
+# Keep stack up for debugging after run
+KEEP_STACK_UP=1 scripts/qa/run-challenge-solve-e2e.sh
+```
+
+### Run Security Tests Only
+
+```bash
+pytest tests/security/
+```
+
+### Run Specific Test Files
+
+```bash
+# Run only API tests
+pytest tests/integration/test_api.py
+
+# Run only authentication tests
+pytest tests/integration/test_auth.py
+
+# Run only pizza shop tests
+pytest tests/integration/test_pizza_shop.py
+
+# Run only model tests
+pytest tests/unit/test_models.py
+
+# Run only sentiment model tests
+pytest tests/unit/test_sentiment_model.py
+
+# Run only vulnerability tests
+pytest tests/unit/test_vulnerabilities.py
+
+# Run only user workflow tests
+pytest tests/functional/test_user_workflows.py
+
+# Run only vulnerability workflow tests
+pytest tests/functional/test_vulnerability_workflows.py
+
+# Run only security tests
+pytest tests/security/test_security.py
+```
+
+### Run Specific Test Classes
+
+```bash
+# Run sentiment analysis API tests
+pytest tests/integration/test_api.py::TestSentimentAnalysisAPI
+
+# Run authentication tests
+pytest tests/integration/test_auth.py::TestAuthentication
+```
+
+### Run Specific Test Methods
+
+```bash
+# Run a single test
+pytest tests/integration/test_api.py::TestSentimentAnalysisAPI::test_analyze_sentiment_positive
+```
+
+### Run with Verbose Output
+
+```bash
+pytest -v
+```
+
+### Run with Coverage Report
+
+```bash
+pytest --cov=application --cov-report=html --cov-report=term-missing
+```
+
+This will generate an HTML coverage report in `htmlcov/index.html`.
+
+## Test Categories
+
+### Functional Tests (`tests/functional/`)
+
+**test_user_workflows.py** - End-to-End User Workflows
+- Complete user journey (login → browse → comment → order → view history)
+- Multiple order workflows
+- Comment management workflows
+- Multi-user interactions
+- Authentication flows (login/logout cycles, invalid attempts)
+- Business logic validation (price calculation, quantity validation)
+- Data consistency and persistence
+- User isolation
+- Error handling scenarios
+
+**test_vulnerability_workflows.py** - Vulnerability Demonstration Workflows
+- Complete model theft attack scenarios
+- Iterative model refinement attacks
+- Data poisoning workflows
+- Sentiment analysis pipelines
+- Supply chain attack demonstrations
+- DoS simulation workflows
+- Chained vulnerability exploits
+- Reconnaissance to exploitation flows
+
+### Unit Tests (`tests/unit/`)
+
+**test_models.py** - Database Model Tests
+- User model (creation, password hashing, unique constraints)
+- Pizza model (creation, relationships)
+- Comment model (creation, timestamps, ratings)
+- Order model (creation, timestamps, relationships)
+
+**test_sentiment_model.py** - Sentiment Analysis Tests
+- Data retrieval from comments
+- Model creation and training
+- Prediction accuracy
+- Edge cases (empty text, unknown words, special characters)
+- Model reproducibility
+
+**test_vulnerabilities.py** - Vulnerability Module Tests
+- Model theft attack simulation
+- Data poisoning demonstrations
+- Weight approximation accuracy
+- Log generation and validation
+- Edge case handling
+
+### Integration Tests (`tests/integration/`)
+
+**test_api.py** - API Endpoint Tests
+- Sentiment Analysis API (`/api/sentiment`, `/analyze_sentiment`)
+- Model Theft API (`/api/model-theft`, `/generate_sentiment_model`)
+- Data Poisoning API (`/api/train-poisoned-model`, `/api/test-poisoned-model`)
+- DoS Simulation API (`/api/llm-query`)
+- Supply Chain Vulnerability Demos
+
+**test_auth.py** - Authentication Tests
+- Login/logout functionality
+- Session management
+- Protected route access
+- Lab setup API (OpenAI API key, Ollama status)
+
+**test_pizza_shop.py** - Core Functionality Tests
+- Pizza browsing
+- Comments (add, delete)
+- Orders (place, view)
+- Vulnerability demonstration pages
+
+### Security Tests (`tests/security/`)
+
+**test_security.py** - Security and Vulnerability Tests
+- Authentication security (password hashing, SQL injection, brute force)
+- Authorization and access control (user isolation, unauthorized access)
+- Input validation (XSS, SQL injection, special characters)
+- Session security (timeout, concurrent sessions)
+- API security (rate limiting, JSON injection, parameter validation)
+- File upload security (malicious pickle files)
+- Password security (weak passwords, hash consistency)
+- Data exposure prevention (error messages, user enumeration)
+- Vulnerability demonstration safety
+
+## Fixtures
+
+Fixtures are defined in `conftest.py`:
+
+- `test_app` - Flask application with in-memory database
+- `client` - Test client for making requests
+- `authenticated_client` - Test client with logged-in session (as alice)
+- `runner` - CLI test runner
+- `sample_pizza` - Sample pizza from database
+- `sample_user` - Sample user (alice) from database
+
+## Writing New Tests
+
+### Example Test Structure
+
+```python
+def test_example(client):
+    """Test description."""
+    response = client.get('/endpoint')
+
+    assert response.status_code == 200
+    assert b'expected content' in response.data
+```
+
+### Testing API Endpoints
+
+```python
+def test_api_endpoint(client):
+    """Test API endpoint with JSON."""
+    response = client.post(
+        '/api/endpoint',
+        json={'key': 'value'}
+    )
+
+    assert response.status_code == 200
+    data = json.loads(response.data)
+    assert data['expected_key'] == 'expected_value'
+```
+
+### Testing with Authentication
+
+```python
+def test_protected_endpoint(authenticated_client):
+    """Test endpoint requiring authentication."""
+    response = authenticated_client.get('/protected')
+
+    assert response.status_code == 200
+```
+
+## Notes
+
+- Tests use an in-memory SQLite database that is recreated for each test
+- Sample data (users, pizzas, comments, orders) is automatically created
+- Default test users: alice/alice and bob/bob
+- CSRF protection is disabled during testing for easier POST requests
+- External services (Ollama, OpenAI) should be mocked for unit tests
+
+## CI/CD Integration
+
+To run tests in CI/CD pipeline:
+
+```yaml
+# Example GitHub Actions workflow
+- name: Install dependencies
+  run: |
+    pip install -r requirements-test.txt
+
+- name: Run tests
+  run: |
+    pytest --cov=application --cov-report=xml
+
+- name: Upload coverage
+  uses: codecov/codecov-action@v3
+```
diff --git a/docs/releases/CHANGELOG.md b/docs/releases/CHANGELOG.md
new file mode 100644
index 0000000..174fb5e
--- /dev/null
+++ b/docs/releases/CHANGELOG.md
@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to PwnzzAI are documented here.
+
+## [Unreleased]
+
+### Added
+- Full MkDocs documentation site with Mermaid diagrams, mkdocstrings, organized category structure
+- `scripts/sync-docs.py` — single-source-of-truth sync for canonical docs
+- `scripts/check-codeblocks.py` — validate Python code blocks in Markdown
+- `scripts/check-doc-coverage.py` — AST-based validation that all routes and vulnerability modules are documented
+- GitHub Pages deployment workflow (`.github/workflows/docs.yml`)
+- Documentation quality CI pipeline (`.github/workflows/docs-quality.yml`)
+- Archirecture docs: overview, data-flow, threat-model
+- Developer docs: codebase-map, API reference, API modules, adding-features
+- Lab docs: overview, lab-format, scenario-list
+- Operations docs: docker-orchestration, env-variables, cloud-setup, troubleshooting
+- Security policy docs: disclosure, usage-policy, data-privacy
+- Community docs: contributing, doc-standards
+- Release docs: ROADMAP
+
+### Fixed
+- Broken link in root README to `docs/workshop-cloud-llm-setup.md` → corrected to `ops/cloud-setup.md`
+- Truncated CONTRIBUTING.md — added missing Coding Standards, Submitting Changes, Reporting Issues, Security Considerations sections
+- References to non-existent `tests/security/` directory in testing-guide.md
+- Missing contact email and disclosure timeline in security/disclosure.md
+- Typo in CONTRIBUTING.md — "soutions" → "solutions"
+
+### Removed
+- Obsolete `docs/CHALLENGE_SOLUTIONS.md` (replaced by `labs/scenario-list.md`)
+- Obsolete `docs/workshop-cloud-llm-setup.md` (migrated to `ops/cloud-setup.md`)
+
+## [Workshop Release] — 2025-10
+
+### Added
+- CTFd workshop deployment, bootstrap scripts, and operator documentation (#85, #86)
+- Docker Compose profiles for local and external Ollama modes (#90)
+- LiteLLM support for multi-provider cloud labs (OpenAI, Anthropic, Gemini) (#90)
+- Direct Prompt Injection escalation ladder (B0–B9) with 10 Jinja2 prompt templates (#90)
+- RFC-EX-B: functional tests with mocked LLM backends for direct injection (#90)
+- Corporate Catering RAG poisoning lab with TF-IDF retrieval (#90)
+- Catering SQL Tool agentic abuse lab (F0–F4) (#90)
+- Promotion Photo indirect injection lab (#90)
+- Customer Support toxicity/guardrail evasion lab (#90)
+- E2E challenge solvability harness with retry logic (#90)
+- Test fixtures and mock infrastructure for CI-safe testing (#90)
+- Provider configuration module with auto-detection (`resolve_provider()`) (#90)
+
+## [CTFd Integration] — 2025-09
+
+### Added
+- CTFd challenge deployment scripts (#85)
+- DigitalOcean bootstrap scripts for workshop operators (#85)
+- QR code lab improvements with updated secret keys (#87, #88, #89)
+
+## [Docker & Polish] — 2025-08
+
+### Added
+- Docker build pipeline and image publishing workflows (#33, #34, #35)
+- Docker Compose configuration for local development (#39, #40)
+- Multi-stage Dockerfile with model pre-loading support (#43, #44)
+
+### Changed
+- Removed model pre-loading from Docker image to reduce size (#45)
+- Refined README for features, vulnerabilities, and project structure clarity (#61–77)
+
+## [Core Lab Implementation] — 2025-06
+
+### Added
+- Direct Prompt Injection — 5 levels with escalating refusal guardrails
+- Indirect Prompt Injection — QR code upload with 5 levels
+- Insecure Plugin Design — SQL injection via LLM function calling
+- Excessive Agency — automatic order placement without confirmation
+- Sensitive Information Disclosure — RAG-based PII leakage
+- Misinformation / Hallucination — forced fabrication via system prompt
+- Denial of Service — simulated exponential degradation
+- Model Theft — weight approximation via public inference API
+- Data Poisoning — mislabeled training data contamination
+- Supply Chain — malicious pickled model with XSS and RCE
+- MIT License and GNU GPL v3 (#47)
+- Sentiment model training pipeline from database comments
+
+### Changed
+- Rebranded from Pwnzza to PwnzzAI (#27)
+- Restructured application module layout (routes, vulnerabilities, provider config)
+
+## [Initial Prototype] — 2025-04
+
+### Added
+- Initial commit of DVLLM — Vulnerable Pizza Shop (#65be73d)
+- Flask application skeleton with pizza shop UI
+- Insecure plugin design — function calling with SQL injection (#c11a1b6)
+- Model theft demonstration (#be9343e)
+- Data poisoning workflow (#e722eae)
+- Basic authentication with Alice and Bob user accounts
+- SQLite database with Pizza, Comment, User, Order models
+- Jitser-style UI templates
diff --git a/docs/releases/ROADMAP.md b/docs/releases/ROADMAP.md
new file mode 100644
index 0000000..3c7b094
--- /dev/null
+++ b/docs/releases/ROADMAP.md
@@ -0,0 +1,26 @@
+# Roadmap
+
+## Near-term Goals
+
+- **Additional lab scenarios**: Expand OWASP Top 10 for LLMs coverage with
+  more real-world exploit scenarios
+- **Mitigation deep-dives**: Hardened-mode comparisons for each vulnerability
+  (defensive coding patterns in Python, not just UI toggles)
+- **Automated security scanning**: Scripts to verify lab exploit paths in CI
+
+## Medium-term Goals
+
+- **Self-guided learning paths**: Structured progression for beginners through
+  advanced exploit techniques
+- **CTF challenge expansion**: More challenge types for the CTFd workshop
+  deployment
+- **Multi-language support**: Localized lab descriptions and explanations
+
+## Long-term Vision
+
+- **AI Exchange alignment**: Continue mapping to the evolving OWASP AI Exchange
+  threat taxonomy as it matures
+- **Community lab contributions**: Framework for community-submitted labs with
+  automated validation
+- **Enterprise workshop kits**: Full facilitator kits with slide decks,
+  handouts, and assessment rubrics
diff --git a/docs/security/data-privacy.md b/docs/security/data-privacy.md
new file mode 100644
index 0000000..8249542
--- /dev/null
+++ b/docs/security/data-privacy.md
@@ -0,0 +1,28 @@
+# Data Privacy
+
+## Ephemeral Sessions
+
+- **Authentication**: Session-based. User credentials (`alice`/`alice`, `bob`/`bob`)
+  are stored in the SQLite database with werkzeug password hashing.
+- **API keys**: Cloud LLM API keys are stored in the **Flask session cookie**
+  (client-side, signed). They are never persisted to the database.
+- **Chat history**: No chat history is stored server-side. LLM interactions are
+  stateless unless the client sends history in the request body.
+
+## Database
+
+- **SQLite**: Two local files (`pizza_shop.db`, `catering_sql_lab.db`)
+- **Default data**: Pre-populated with sample pizzas, comments, users, and
+  routing flags on first startup
+- **Data isolation**: The secondary `catering_sql_lab.db` is used exclusively
+  by the catering SQL tool lab
+
+## Docker Deployments
+
+- Docker volumes persist the SQLite databases across restarts
+- `docker compose down -v` removes all persistent data
+
+## What Not to Store
+
+Do not enter real credentials, real PII, or production API keys. The app's
+vulnerabilities could expose any data stored in the database or session.
diff --git a/docs/security/disclosure.md b/docs/security/disclosure.md
new file mode 100644
index 0000000..7db1331
--- /dev/null
+++ b/docs/security/disclosure.md
@@ -0,0 +1,27 @@
+# Responsible Disclosure
+
+PwnzzAI Shop is an **intentionally insecure** educational application. The
+vulnerabilities are the features.
+
+## Reporting Security Issues
+
+If you find a vulnerability that is **not** part of the intended lab exercises:
+
+1. **Do not** open a public GitHub issue
+2. Email the maintainers at **pwnzzai.security@owasp.org**
+3. Include a description, steps to reproduce, and impact
+
+### What to Expect
+
+- **Acknowledgment**: You will receive a response within 5 business days
+- **Assessment**: The team will evaluate the report and confirm whether it is a new unintended vulnerability
+- **Timeline**: We follow a 90-day coordinated disclosure window before publishing details
+- **Credit**: Reporters are credited in the release notes unless they prefer to remain anonymous
+
+## Scope
+
+| In scope | Out of scope |
+|----------|-------------|
+| Unexpected vulnerabilities beyond the lab exercises | All documented vulnerabilities in `docs/labs/scenario-list.md` |
+| Host server compromise via workshop deployment | Known supply chain demonstrations in `supply_chain.py` |
+| Data exfiltration beyond the lab boundaries | All documented sensitive information disclosure labs |
diff --git a/docs/security/usage-policy.md b/docs/security/usage-policy.md
new file mode 100644
index 0000000..0df5131
--- /dev/null
+++ b/docs/security/usage-policy.md
@@ -0,0 +1,26 @@
+# Usage Policy
+
+## Educational Purpose Only
+
+PwnzzAI Shop contains **intentional security vulnerabilities**. It is designed
+exclusively for:
+
+- AI/LLM security education and training
+- Hands-on workshop exercises
+- Understanding how vulnerabilities work and how to defend against them
+
+## Prohibited Uses
+
+- Deploying in production environments
+- Using the techniques demonstrated here against real systems
+- Running the application on public-facing servers without proper network isolation
+- Using the application to train LLMs or for any automated data collection
+
+## Disclaimer
+
+This software is provided "as is" without warranty of any kind. The OWASP
+Foundation and the project contributors are not liable for any damages arising
+from the use of this software.
+
+The application may incur API costs when connecting to cloud LLM providers.
+Users are responsible for monitoring their own API usage and costs.
diff --git a/lychee.toml b/lychee.toml
new file mode 100644
index 0000000..de804b3
--- /dev/null
+++ b/lychee.toml
@@ -0,0 +1,41 @@
+# lychee link checker configuration
+# See: https://github.com/lycheeverse/lychee
+
+# Only scan markdown files
+include_paths = ["**/*.md"]
+
+# Exclude specific paths
+exclude_path = [
+  "venv",
+  ".venv",
+  "node_modules",
+  "site",
+  "docs/tmp"
+]
+
+# Exclude known-fragile URLs (localhost, placeholders, dynamic pages)
+exclude = [
+  "http://localhost",
+  "http://127.0.0.1",
+  "http://0.0.0.0",
+  "https://host.docker.internal",
+  "https://github.com/YOUR-USERNAME",
+  "https://github.com/your-org",
+  "http://<gpu-host>",
+  "http://<docker0-gateway>",
+  "http://<your-ollama-server>",
+  "http://<public-ip>",
+  "http://<this-host>",
+  "http://<gpu-host-ip>",
+  "http://your-ollama-server",
+  "https://aistudio.google.com/apikey"
+]
+
+timeout = 30
+retry_wait_time = 5
+max_concurrency = 8
+insecure = false
+
+accept = ["200", "201", "202", "203", "204", "206", "301", "302", "303", "307", "308"]
+
+format = "github"
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..78ba287
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,83 @@
+site_name: PwnzzAI Shop
+site_description: "The Vulnerable Pizza Shop — AI Security Education Platform"
+site_url: https://owasp.github.io/PwnzzAI
+repo_url: https://github.com/OWASP/PwnzzAI
+repo_name: OWASP/PwnzzAI
+edit_uri: blob/main/docs/
+
+theme:
+  name: material
+  logo: owasp.png
+  favicon: owasp.png
+  palette:
+    scheme: default
+    primary: red
+    accent: orange
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.expand
+    - navigation.indexes
+    - content.code.copy
+    - content.tabs.link
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]
+          options:
+            show_source: true
+            show_bases: true
+            heading_level: 3
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.details
+  - admonition
+  - toc:
+      permalink: true
+
+nav:
+  - Home: README.md
+  - Architecture:
+    - architecture/overview.md
+    - architecture/data-flow.md
+    - architecture/threat-model.md
+  - Developer Guide:
+    - developer/getting-started.md
+    - developer/codebase-map.md
+    - developer/api-reference.md
+    - developer/api-modules.md
+    - developer/adding-features.md
+  - Labs:
+    - labs/overview.md
+    - labs/lab-format.md
+    - labs/scenario-list.md
+  - Quality Assurance:
+    - quality-assurance/testing-guide.md
+    - quality-assurance/security-checks.md
+  - Operations:
+    - ops/docker-orchestration.md
+    - ops/env-variables.md
+    - ops/cloud-setup.md
+    - ops/troubleshooting.md
+  - Security:
+    - security/disclosure.md
+    - security/usage-policy.md
+    - security/data-privacy.md
+  - Community:
+    - community/contributing.md
+    - community/doc-standards.md
+  - Releases:
+    - releases/CHANGELOG.md
+    - releases/ROADMAP.md
diff --git a/pyproject.toml b/pyproject.toml
index b5c465b..5df0443 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,3 +12,9 @@ exclude = [
 [tool.ruff.lint]
 # CI workflow ignores these; keep aligned.
 ignore = ["E402", "F401", "F841"]
+
+[tool.pytest-codeblocks]
+# Only validate Python fenced code blocks; skip bash/sh blocks.
+# Note: the `languages` option is not supported in pytest-codeblocks 0.16.x.
+# Only Python blocks are validated. Shell blocks are silently skipped on CI
+# (bash available) and fail gracefully on Windows.
diff --git a/pytest.ini b/pytest.ini
index d29ace8..085b403 100644
--- a/pytest.ini
+++ b/pytest.ini
@@ -7,3 +7,7 @@ markers =
     openai: exercises cloud LLM routes (requires a valid API key in the environment).
     slow: may download embedding models or run longer Ollama probes.
     e2e: live HTTP tests against APP_BASE; requires RUN_E2E=1 and a running app.
+
+# pytest-codeblocks: only run fenced blocks with "python" or "py" language tag
+[tool:pytest-codeblocks]
+languages = python py
diff --git a/scripts/check-codeblocks.py b/scripts/check-codeblocks.py
new file mode 100644
index 0000000..f00401f
--- /dev/null
+++ b/scripts/check-codeblocks.py
@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""check-codeblocks.py — Validate Python code blocks in markdown files.
+
+Zero-dependency checker that extracts ```python blocks from .md files and
+validates syntax (compilation) and optionally executes them.
+
+Usage:
+    python3 scripts/check-codeblocks.py              # syntax check all docs/
+    python3 scripts/check-codeblocks.py README.md    # specific file
+    python3 scripts/check-codeblocks.py --exec       # syntax + runtime exec
+
+Runtime execution will fail on snippets that depend on the Flask app context
+(e.g. `from application import app`). These are expected — only use --exec
+when you've verified the snippets are self-contained.
+"""
+import ast
+import os
+import re
+import sys
+import traceback
+
+
+def extract_python_blocks(text: str):
+    """Yield (lineno, code) tuples for each ```python block."""
+    pattern = re.compile(
+        r"^```python\s*\n(.*?)\n^```",
+        re.MULTILINE | re.DOTALL,
+    )
+    for m in pattern.finditer(text):
+        lineno = text[: m.start()].count("\n") + 1
+        code = m.group(1)
+        yield lineno, code
+
+
+def check_file(filepath: str, run_exec: bool = False) -> int:
+    """Check all Python blocks in a file. Returns number of failures."""
+    relpath = os.path.relpath(filepath)
+    with open(filepath, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    failures = 0
+    for lineno, code in extract_python_blocks(text):
+        code = code.strip()
+        if not code:
+            continue
+
+        # Always check syntax with ast.parse
+        try:
+            ast.parse(code)
+        except SyntaxError as e:
+            print(f"  FAIL {relpath}:{lineno} — syntax error: {e}")
+            failures += 1
+            continue
+
+        # Optionally try to exec (will fail on app-context snippets)
+        if run_exec:
+            try:
+                exec(code, {"__MODULE__": "__main__"})
+                print(f"  OK   {relpath}:{lineno}")
+            except Exception as e:
+                tb = "".join(traceback.format_exception_only(type(e), e)).strip()
+                print(f"  SKIP {relpath}:{lineno} — {tb}")
+        else:
+            print(f"  OK   {relpath}:{lineno}")
+
+    return failures
+
+
+def main():
+    args = [a for a in sys.argv[1:] if not a.startswith("-")]
+    run_exec = "--exec" in sys.argv
+
+    targets = args if args else ["docs/"]
+
+    # Collect .md files from targets
+    files = []
+    for target in targets:
+        if os.path.isfile(target):
+            files.append(target)
+        elif os.path.isdir(target):
+            for root, _dirs, fnames in os.walk(target):
+                for fname in fnames:
+                    if fname.endswith(".md"):
+                        files.append(os.path.join(root, fname))
+
+    if not files:
+        print("No markdown files found.")
+        sys.exit(0)
+
+    total = 0
+    failures = 0
+    for filepath in sorted(files):
+        f = check_file(filepath, run_exec=run_exec)
+        total += 1
+        failures += f
+
+    print(f"\n{total} files checked, {failures} block failures.")
+    sys.exit(1 if failures else 0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/check-doc-coverage.py b/scripts/check-doc-coverage.py
new file mode 100644
index 0000000..4d2a113
--- /dev/null
+++ b/scripts/check-doc-coverage.py
@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""check-doc-coverage.py — Ensure code changes have corresponding doc updates.
+
+Compares routes and vulnerability modules against the API reference and
+codebase map docs. Fails CI if anything is undocumented.
+
+Zero dependencies — uses only Python stdlib (ast, os, glob, re, sys).
+"""
+import ast
+import glob
+import os
+import re
+import sys
+
+
+DOCS_API_REF = "docs/developer/api-reference.md"
+DOCS_CODEBASE = "docs/developer/codebase-map.md"
+ROUTES_FILE = "application/route.py"
+VULN_DIR = "application/vulnerabilities"
+
+ALLOWED_UNDOCUMENTED_ROUTES = {
+    "OPTIONS /",
+    "OPTIONS /<var>",
+    "GET /promotion-photo-claim",  # redirect → /promotion-photo
+}
+
+
+def extract_routes_from_ast(filepath: str) -> list[tuple[int, str, str, str]]:
+    """Parse route.py AST and return [(lineno, method, path, function_name)]."""
+    with open(filepath, "r", encoding="utf-8") as f:
+        source = f.read()
+    tree = ast.parse(source, filename=filepath)
+
+    routes = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for dec in node.decorator_list:
+            if not isinstance(dec, ast.Call):
+                continue
+            if not isinstance(dec.func, ast.Attribute):
+                continue
+            if dec.func.attr != "route":
+                continue
+
+            path = ""
+            if dec.args:
+                first = dec.args[0]
+                if isinstance(first, ast.Constant):
+                    path = first.value
+                elif isinstance(first, ast.JoinedStr):
+                    path = "".join(
+                        p.value if isinstance(p, ast.Constant) else "<var>"
+                        for p in first.values
+                    )
+
+            methods = ["GET"]
+            for kw in dec.keywords:
+                if kw.arg == "methods":
+                    if isinstance(kw.value, ast.List):
+                        methods = [
+                            e.value
+                            for e in kw.value.elts
+                            if isinstance(e, ast.Constant)
+                        ]
+
+            for method in methods:
+                routes.append((node.lineno, method, path, node.name))
+
+    return routes
+
+
+def extract_documented_endpoints(filepath: str) -> set[str]:
+    """Parse api-reference.md for documented endpoints.
+
+    Handles three formats:
+    1. Heading: `METHOD /path`
+    2. Table with method: `| METHOD /path | ...`
+    3. Table implicit GET: `| /path | ...`
+    """
+    with open(filepath, "r", encoding="utf-8") as f:
+        lines = f.readlines()
+
+    documented = set()
+
+    # Pattern 1: `#### \`METHOD /path\``  (API route headings)
+    heading_pattern = re.compile(r"^####\s+`(GET|POST|PUT|DELETE|PATCH)\s+(/[^\s`]+)`")
+
+    # Pattern 2: Table rows with method prefix: `| \`METHOD /path\` | ...`
+    table_with_method = re.compile(r"^\|\s+`(GET|POST|PUT|DELETE|PATCH)\s+(/[^`\s]+)`")
+
+    # Pattern 3: Table rows without method prefix: `| \`/path\` | ...`
+    # These imply GET (used in Page Routes and Vulnerability Demo sections)
+    table_implicit_get = re.compile(r"^\|\s+`(/[^`\s]*)`\s*\|")
+
+    for line in lines:
+        m = heading_pattern.match(line)
+        if m:
+            documented.add(f"{m.group(1)} {m.group(2)}")
+            continue
+
+        m = table_with_method.match(line)
+        if m:
+            documented.add(f"{m.group(1)} {m.group(2)}")
+            continue
+
+        m = table_implicit_get.match(line)
+        if m:
+            documented.add(f"GET {m.group(1)}")
+            continue
+
+    return documented
+
+
+def extract_documented_modules(filepath: str) -> set[str]:
+    """Parse codebase-map.md for vulnerability module filenames."""
+    with open(filepath, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    found = set()
+    pattern = re.compile(r"`([\w_]+\.py)`")
+    for m in pattern.finditer(text):
+        name = m.group(1)
+        if name.endswith(".py") and name != "__init__.py":
+            found.add(name[:-3])
+    return found
+
+
+def get_vulnerability_modules(directory: str) -> set[str]:
+    """List all .py files in directory, excluding __init__."""
+    modules = set()
+    for fpath in glob.glob(os.path.join(directory, "*.py")):
+        name = os.path.splitext(os.path.basename(fpath))[0]
+        if name != "__init__":
+            modules.add(name)
+    return modules
+
+
+def normalize_path(path: str) -> str:
+    """Replace Flask variable segments with <var> for comparison."""
+    return re.sub(r"<[^>]+>", "<var>", path)
+
+
+def main():
+    errors = 0
+
+    routes = extract_routes_from_ast(ROUTES_FILE)
+    documented = extract_documented_endpoints(DOCS_API_REF)
+
+    undocumented = []
+    for _, method, path, func in routes:
+        key = f"{method} {path}"
+        key_norm = f"{method} {normalize_path(path)}"
+        key_norm_all = normalize_path(key)
+
+        if key in documented or key_norm in documented or key_norm_all in documented:
+            continue
+        if key in ALLOWED_UNDOCUMENTED_ROUTES or key_norm in ALLOWED_UNDOCUMENTED_ROUTES:
+            continue
+        undocumented.append(key)
+
+    if undocumented:
+        print(f"\nMissing from {DOCS_API_REF}:")
+        for ep in sorted(set(undocumented)):
+            print(f"  {ep}")
+        errors += 1
+    else:
+        print(f"All {len(routes)} routes documented in {DOCS_API_REF}.")
+
+    vuln_modules = get_vulnerability_modules(VULN_DIR)
+    doc_modules = extract_documented_modules(DOCS_CODEBASE)
+
+    missing_modules = vuln_modules - doc_modules
+    if missing_modules:
+        print(f"\nMissing from {DOCS_CODEBASE}:")
+        for m in sorted(missing_modules):
+            print(f"  {m}")
+        errors += 1
+    else:
+        print(f"All {len(vuln_modules)} vulnerability modules documented in {DOCS_CODEBASE}.")
+
+    if errors:
+        print("\nRun `make docs` and update the relevant documentation files.")
+        sys.exit(1)
+
+    print("\nDocumentation coverage OK.")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/sync-docs.py b/scripts/sync-docs.py
new file mode 100644
index 0000000..5ff0d4c
--- /dev/null
+++ b/scripts/sync-docs.py
@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""sync-docs.py — Copy canonical files into docs/ before mkdocs build.
+
+Single source of truth stays in the repo root; docs/ gets build-only copies.
+Run this before every `mkdocs build` or `mkdocs serve`.
+
+Handles path rewriting: files in the root use "docs/..." links; when copied
+into docs/ those prefixes are stripped so links resolve correctly at build time.
+"""
+import os
+import re
+import shutil
+import sys
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+DOCS_DIR = os.path.join(REPO_ROOT, "docs")
+
+
+def _rewrite_paths(content: str, dst_depth: int = 0) -> str:
+    """Rewrite old paths in synced files to match the new docs/ structure.
+
+    dst_depth: how many directories deep the destination is from docs/
+               (0 = docs/README.md, 1 = docs/community/contributing.md, etc.)
+    """
+    prefix = "../" * dst_depth
+
+    # Strip docs/ prefix from links (files at root reference docs/...)
+    # and replace with the correct relative prefix for the destination depth
+    content = re.sub(r'(\]\()docs/', lambda m: m.group(1) + prefix, content)
+
+    # Map old filenames to new paths in docs/
+    path_map = {
+        "OLLAMA_CONNECTION_TROUBLESHOOTING.md": f"{prefix}ops/troubleshooting.md",
+        "ARCHITECTURE.md": f"{prefix}architecture/overview.md",
+        "API_REFERENCE.md": f"{prefix}developer/api-reference.md",
+        "DEVELOPER_GUIDE.md": f"{prefix}developer/getting-started.md",
+        "ENVIRONMENT_VARIABLES.md": f"{prefix}ops/env-variables.md",
+        "ESCALATION_LADDER.md": f"{prefix}labs/lab-format.md",
+        "CHALLENGE_SOLUTIONS.md": f"{prefix}labs/scenario-list.md",
+        "workshop-cloud-llm-setup.md": f"{prefix}ops/cloud-setup.md",
+    }
+
+    # Rewrite image paths in README: src="application/static/img/... -> src="...
+    content = re.sub(r'src="application/static/img/', r'src="', content)
+
+    # Also rewrite .env.example references in docs files
+    if content.find("env.example") >= 0:
+        content = re.sub(r'(\]\()(\.env\.example)\)', rf'\1{prefix}env.example)', content)
+
+    for old, new in path_map.items():
+        content = content.replace(old, new)
+
+    return content
+
+
+pairs = [
+    ("CONTRIBUTING.md", "community/contributing.md", 1),                 # Community
+    ("OLLAMA_CONNECTION_TROUBLESHOOTING.md", "ops/troubleshooting.md", 1),  # Ops
+    ("tests/README.md", "quality-assurance/testing-guide.md", 1),        # QA
+    (".env.example", "env.example", 0),                                  # Root of docs
+]
+
+for src_rel, dst_name, depth in pairs:
+    src = os.path.join(REPO_ROOT, src_rel)
+    dst = os.path.join(DOCS_DIR, dst_name)
+    if not os.path.exists(src):
+        print(f"  WARNING: {src} not found, skipping", file=sys.stderr)
+        continue
+    # Ensure destination directory exists
+    os.makedirs(os.path.dirname(dst), exist_ok=True)
+    with open(src, "r", encoding="utf-8") as f:
+        content = f.read()
+    content = _rewrite_paths(content, dst_depth=depth)
+    with open(dst, "w", encoding="utf-8") as f:
+        f.write(content)
+    print(f"  {src_rel} -> docs/{dst_name}")
+
+print("Done. Run 'mkdocs build' or 'mkdocs serve' next.")
+
+# Also copy images referenced by synced files
+_IMG_DIR = os.path.join(REPO_ROOT, "application", "static", "img")
+_SYNCED_IMGS = ["index.png"]
+
+for img in _SYNCED_IMGS:
+    src = os.path.join(_IMG_DIR, img)
+    dst = os.path.join(DOCS_DIR, img)
+    if os.path.exists(src):
+        shutil.copy2(src, dst)
+        print(f"  application/static/img/{img} -> docs/{img}")
+    else:
+        print(f"  WARNING: {src} not found, skipping", file=sys.stderr)