diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
new file mode 100644
index 0000000..3af7708
--- /dev/null
+++ b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,55 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-docs.yml"
+  workflow_dispatch:
+
+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
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material mkdocs-mermaid2-plugin
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.markdownlint.json b/.markdownlint.json
index a64c768..25ba725 100644
--- a/.markdownlint.json
+++ b/.markdownlint.json
@@ -3,5 +3,6 @@
   "MD013": false,
   "MD033": false,
   "MD041": false,
+  "MD046": false,
   "MD051": false
 }
diff --git a/docs/getting-started/first-cba.md b/docs/getting-started/first-cba.md
new file mode 100644
index 0000000..4b69c8a
--- /dev/null
+++ b/docs/getting-started/first-cba.md
@@ -0,0 +1,78 @@
+# Your First Codebase Agent
+
+**Create a CBA in 30 minutes.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    What you'll build: a `.claude/` directory with agent definition and context files customized for your project. By the end, AI will know your coding conventions.
+
+---
+
+## Step 1: Copy the Template
+
+!!! note "Section Summary"
+    Copy `.claude/` from reference repo to your project. Directory structure explanation. What each file does.
+
+---
+
+## Step 2: Customize the Agent Definition
+
+!!! note "Section Summary"
+    Edit `.claude/agents/codebase-agent.md`. Key sections to customize: capability boundaries (what can the agent do autonomously?), quality gates (your linting/testing commands), safety guardrails (when to stop and ask).
+
+---
+
+## Step 3: Create Context Files
+
+### Architecture Context
+
+!!! note "Section Summary"
+    `.claude/context/architecture.md` - describe your layers, component responsibilities, data flow. Template provided. Examples for common stacks (FastAPI, Express, Django).
+
+### Security Context
+
+!!! note "Section Summary"
+    `.claude/context/security-standards.md` - your validation rules, sanitization patterns, secrets management approach. What to validate, what to trust.
+
+### Testing Context
+
+!!! note "Section Summary"
+    `.claude/context/testing-patterns.md` - your test pyramid, where tests live, mocking conventions, coverage targets.
+
+---
+
+## Step 4: Test Your CBA
+
+!!! note "Section Summary"
+    Interactive session: ask AI to perform a task in your codebase. Verify it follows conventions. Iterate on context files based on what it gets wrong.
+
+---
+
+## Step 5: Share with Your Team
+
+!!! note "Section Summary"
+    Commit `.claude/` to your repo. Team onboarding: everyone gets the same AI behavior. Updating context files: when and how.
+
+---
+
+## Memory System Deep Dive
+
+!!! note "Section Summary"
+    How modular context works. Loading context on-demand. Token efficiency. When to split vs combine context files.
+
+---
+
+## Troubleshooting
+
+!!! note "Section Summary"
+    Common issues: AI ignores context (file not loaded), AI makes up conventions (context too vague), AI over-engineers (context too broad). Solutions for each.
+
+---
+
+## Next Steps
+
+- [Patterns Index](../patterns/index.md) - Explore all available patterns
+- [Self-Review Reflection](../patterns/self-review-reflection.md) - Add quality gates to your CBA
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
new file mode 100644
index 0000000..f66902e
--- /dev/null
+++ b/docs/getting-started/installation.md
@@ -0,0 +1,54 @@
+# Installation
+
+**Set up tooling for AI-assisted development.**
+
+---
+
+## Prerequisites
+
+!!! note "Section Summary"
+    This section covers required and recommended tooling: Python 3.11+, uv package manager, Claude CLI or API access, markdownlint, and Mermaid CLI. Includes verification commands for each tool.
+
+---
+
+## Quick Install
+
+!!! note "Section Summary"
+    One-liner install scripts for macOS/Linux. Clone reference repo, install dependencies with uv, verify setup with validation scripts.
+
+---
+
+## Tool-by-Tool Setup
+
+### Python Environment
+
+!!! note "Section Summary"
+    Virtual environment setup with uv. Why uv over pip (speed, reliability). Verification steps.
+
+### Claude CLI / API
+
+!!! note "Section Summary"
+    Claude Code installation and authentication. API key management. Verification that Claude can access your codebase.
+
+### Linting Tools
+
+!!! note "Section Summary"
+    markdownlint-cli installation. Black, isort, ruff for Python. Configuration files included in reference repo.
+
+### Mermaid Validation
+
+!!! note "Section Summary"
+    @mermaid-js/mermaid-cli installation. Why Mermaid validation matters for documentation CI.
+
+---
+
+## Verification
+
+!!! note "Section Summary"
+    Run all validation scripts to confirm installation. Expected output for each. Troubleshooting common issues.
+
+---
+
+## Next Steps
+
+- [Your First CBA](first-cba.md) - Create your first Codebase Agent
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..4751c02
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,187 @@
+# Ambient Code Reference
+
+**AI-assisted development patterns for engineering teams.**
+
+---
+
+## Executive Summary
+
+This repository provides battle-tested patterns for adopting AI-assisted development at scale. It answers the question every principal engineer faces: *"How do we use AI coding assistants without creating chaos?"*
+
+**Key Value Propositions:**
+
+1. **Consistency** - Every AI interaction follows the same process
+2. **Safety** - Human review gates prevent runaway automation
+3. **Productivity** - 10x speedup for routine tasks
+4. **Transferability** - Patterns work across tools and languages
+
+**Approach:** Standalone patterns. Adopt what you need, skip what you don't. No prescribed sequence.
+
+---
+
+## What's Inside
+
+### Patterns (9 Total)
+
+| Pattern | Category | Effort | Impact |
+|---------|----------|--------|--------|
+| [Codebase Agent (CBA)](#cba) | Agent Behavior | Medium | High |
+| [Memory System](#memory) | Agent Behavior | Low | Medium |
+| [Self-Review Reflection](#self-review) | Agent Behavior | Low | High |
+| [Issue-to-PR Automation](#issue-to-pr) | GHA Automation | High | Very High |
+| [PR Auto-Review](#pr-review) | GHA Automation | Medium | High |
+| [Dependabot Auto-Merge](#dependabot) | GHA Automation | Low | Medium |
+| [Stale Issue Management](#stale) | GHA Automation | Low | Medium |
+| [Layered Architecture](#architecture) | Foundation | Low | Medium |
+| [Security Patterns](#security) | Foundation | Low | Medium |
+
+### Quick Start Paths
+
+=== "I want consistent AI assistance"
+
+    Start with [Codebase Agent](patterns/codebase-agent.md) - one file that defines how AI works in your codebase.
+
+=== "AI keeps forgetting my conventions"
+
+    Start with [Memory System](getting-started/first-cba.md#memory-system) - modular context files that persist across sessions.
+
+=== "Routine fixes take too long"
+
+    Start with [Issue-to-PR Automation](patterns/issue-to-pr.md) - convert well-defined issues to PRs automatically.
+
+=== "I want to see it working first"
+
+    Check out the [demo-fastapi](https://github.com/jeremyeder/demo-fastapi) repository for a working example.
+
+---
+
+## Documentation Structure
+
+### Getting Started
+
+| Section | Purpose | Time |
+|---------|---------|------|
+| [Quickstart](quickstart.md) | 5-minute introduction to AI-assisted development | 5 min |
+| [Installation](getting-started/installation.md) | Set up tooling and dependencies | 15 min |
+| [Your First CBA](getting-started/first-cba.md) | Create your first Codebase Agent | 30 min |
+
+**What you'll learn:** How to copy the `.claude/` directory to your project and customize it for your tech stack.
+
+---
+
+### Patterns
+
+#### Agent Behavior Patterns
+
+How AI agents behave during development.
+
+| Pattern | What It Does | Section Summary |
+|---------|--------------|-----------------|
+| [Codebase Agent](patterns/codebase-agent.md) | Defines AI behavior, capabilities, and guardrails | Agent definition structure, autonomy levels, workflow examples, capability boundaries |
+| [Self-Review Reflection](patterns/self-review-reflection.md) | Agent reviews own work before presenting | Reflection loop, checklist criteria, implementation prompts, anti-patterns |
+| [Autonomous Quality](patterns/autonomous-quality-enforcement.md) | Validates code quality before delivery | Lint loops, test verification, error budgets |
+| [Multi-Agent Review](patterns/multi-agent-code-review.md) | Multiple specialized agents review in parallel | Agent roles, consensus mechanisms, conflict resolution |
+
+#### GHA Automation Patterns
+
+Proactive CI/CD workflows.
+
+| Pattern | Trigger | Section Summary |
+|---------|---------|-----------------|
+| [Issue-to-PR](patterns/issue-to-pr.md) | `issues.opened` | Requirements analysis, draft PR creation, risk categories, safety gates |
+| [PR Auto-Review](patterns/pr-auto-review.md) | `pull_request` | AI review format, severity levels, when to block vs comment |
+| [Dependabot Auto-Merge](patterns/dependabot-auto-merge.md) | `pull_request` | Patch vs minor/major, CI requirements, safety conditions |
+| [Stale Issues](patterns/stale-issues.md) | `schedule` | Inactivity thresholds, warning periods, exempt labels |
+
+#### Foundation Patterns
+
+Enabling patterns that make AI more effective.
+
+| Pattern | Purpose | Section Summary |
+|---------|---------|-----------------|
+| [Layered Architecture](patterns/layered-architecture.md) | Code structure AI can reason about | Four layers, dependency rules, component responsibilities |
+| [Security Patterns](patterns/security-patterns.md) | Practical protection without over-engineering | Boundary validation, sanitization, secrets management |
+| [Testing Patterns](patterns/testing-patterns.md) | Test pyramid approach | Unit/integration/E2E, coverage targets, AI test generation |
+
+---
+
+### Reference
+
+| Section | Purpose | Contents |
+|---------|---------|----------|
+| [Architecture](architecture.md) | Deep dive into architecture patterns | Data flow diagrams, layer boundaries, extension points |
+| [API Patterns](api-reference.md) | API design for AI-assisted development | Request/response patterns, error handling, OpenAPI |
+| [ADR Template](adr/template.md) | Decision record scaffolding | YYYYMMDD-title.md format, context/decision/consequences |
+
+---
+
+### Tutorial
+
+| Section | Purpose | Time |
+|---------|---------|------|
+| [Full Tutorial](tutorial.md) | Step-by-step implementation guide | 2-4 hours |
+
+**What you'll build:** A complete AI-assisted development setup from scratch, including CBA, memory system, and GHA automations.
+
+---
+
+### Resources
+
+| Resource | Format | Purpose |
+|----------|--------|---------|
+| [Presentation](resources/presentation.md) | Markdown | NotebookLM podcast generation, 9 features explained |
+| [Demo Application](resources/demo-app.md) | GitHub Repo | Working FastAPI example |
+
+---
+
+## Navigation Guide
+
+```mermaid
+flowchart TD
+    A[Start Here] --> B{What do you need?}
+    B -->|Understand the concepts| C[Quickstart]
+    B -->|See it working| D[Demo App]
+    B -->|Implement patterns| E[Tutorial]
+    B -->|Reference specific pattern| F[Patterns Index]
+    
+    C --> G[Your First CBA]
+    D --> G
+    E --> G
+    F --> H[Choose Pattern]
+    
+    G --> I[Production Setup]
+    H --> I
+```
+
+---
+
+## Design Principles
+
+1. **Standalone patterns** - No dependencies between patterns. Adopt one without adopting others.
+2. **Copy-paste ready** - All configurations are complete and ready to customize.
+3. **Human-in-the-loop** - AI assists, humans decide. Safety gates everywhere.
+4. **Vendor-agnostic** - Patterns work with any AI tool or none at all.
+5. **Minimal ceremony** - Start small, add complexity only when needed.
+
+---
+
+## Who This Is For
+
+| Role | Benefit |
+|------|---------|
+| **Principal Engineers** | Evaluate AI adoption strategy with battle-tested patterns |
+| **Team Leads** | Implement consistent AI workflows across your team |
+| **Senior Developers** | Get productivity gains without sacrificing quality |
+| **Junior Developers** | Get senior-level AI assistance with guardrails |
+
+---
+
+## Quick Links
+
+- **GitHub Repository**: [jeremyeder/reference](https://github.com/jeremyeder/reference)
+- **Demo Application**: [jeremyeder/demo-fastapi](https://github.com/jeremyeder/demo-fastapi)
+- **Original SRE Coloring Book**: [red.ht/sre-coloring-book](https://red.ht/sre-coloring-book)
+
+---
+
+*"Stable, Secure, Performant, and Boring" - the goal is to make AI assistance invisible through excellence.*
diff --git a/docs/patterns/codebase-agent.md b/docs/patterns/codebase-agent.md
new file mode 100644
index 0000000..681c6b1
--- /dev/null
+++ b/docs/patterns/codebase-agent.md
@@ -0,0 +1,76 @@
+# Codebase Agent (CBA)
+
+**Single source of truth for AI behavior in your codebase.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    What a CBA is: a markdown file that defines how AI works in your project. Problem it solves: inconsistent AI behavior across developers. Key benefit: every AI interaction follows the same process.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Copy-paste the CBA definition from `.claude/agents/codebase-agent.md`. Minimal customization: your linting commands, your test commands. Done in 15 minutes.
+
+---
+
+## Agent Definition Structure
+
+### Capability Boundaries
+
+!!! note "Section Summary"
+    What the agent can do autonomously vs what requires human approval. Examples: formatting changes (auto), architecture changes (human approval). How to define your own boundaries.
+
+### Workflow Definitions
+
+!!! note "Section Summary"
+    Step-by-step processes for common tasks: issue-to-PR, code review, refactoring. Template workflows provided. How to customize for your process.
+
+### Quality Gates
+
+!!! note "Section Summary"
+    Linting, testing, and review requirements. Which tools to run, in what order. What constitutes a passing gate. Error handling.
+
+### Safety Guardrails
+
+!!! note "Section Summary"
+    When to stop and ask for human input. Risk categories: low/medium/high. Examples of each. How to configure alert thresholds.
+
+---
+
+## Autonomy Levels
+
+!!! note "Section Summary"
+    Level 1 (Conservative): PR creation only, wait for human approval. Level 2 (Moderate): Auto-merge for low-risk changes. Level 3 (Aggressive): Auto-deploy after tests pass. How to graduate between levels.
+
+---
+
+## Memory System Integration
+
+!!! note "Section Summary"
+    How CBA uses context files from `.claude/context/`. Loading context on-demand. When to reference which context file.
+
+---
+
+## Real-World Examples
+
+!!! note "Section Summary"
+    CBA configurations for different stacks: Python/FastAPI, TypeScript/Express, Go. What's different, what's the same.
+
+---
+
+## Troubleshooting
+
+!!! note "Section Summary"
+    Common issues: agent ignores boundaries, agent is too conservative, agent makes up conventions. Solutions for each.
+
+---
+
+## Related Patterns
+
+- [Self-Review Reflection](self-review-reflection.md) - Add quality gates to CBA output
+- [Memory System](../getting-started/first-cba.md#memory-system) - Persistent context across sessions
diff --git a/docs/patterns/dependabot-auto-merge.md b/docs/patterns/dependabot-auto-merge.md
new file mode 100644
index 0000000..d9c8345
--- /dev/null
+++ b/docs/patterns/dependabot-auto-merge.md
@@ -0,0 +1,57 @@
+# Dependabot Auto-Merge
+
+**Automatically merge low-risk dependency updates.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    When Dependabot creates a PR for a patch version update, auto-merge after CI passes. Keep dependencies current without manual effort. Minor/major updates still require human review.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Copy the workflow YAML. No additional secrets needed. Enable Dependabot in your repo. Watch patch updates auto-merge.
+
+---
+
+## How It Works
+
+```mermaid
+flowchart TD
+    A[Dependabot PR] --> B{Patch Version?}
+    B -->|No| C[Require Human Review]
+    B -->|Yes| D{CI Passes?}
+    D -->|No| C
+    D -->|Yes| E[Auto-Merge]
+```
+
+---
+
+## Safety Conditions
+
+!!! note "Section Summary"
+    Only auto-merge when ALL conditions met: author is dependabot[bot], update is patch version, all CI checks pass, no merge conflicts. Why each condition matters.
+
+---
+
+## Workflow YAML
+
+!!! note "Section Summary"
+    Complete workflow file. Dependabot metadata action. Conditional auto-merge. Squash and delete branch.
+
+---
+
+## Customization
+
+!!! note "Section Summary"
+    Auto-merge minor versions too. Exclude specific packages. Custom merge strategy. Notifications.
+
+---
+
+## Related Patterns
+
+- [Stale Issue Management](stale-issues.md) - Another proactive cleanup pattern
diff --git a/docs/patterns/index.md b/docs/patterns/index.md
new file mode 100644
index 0000000..53b6ec8
--- /dev/null
+++ b/docs/patterns/index.md
@@ -0,0 +1,84 @@
+# Patterns Index
+
+**All AI-assisted development patterns in one place.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    Patterns are organized into three categories: Agent Behavior (how AI works), GHA Automation (proactive CI/CD), and Foundation (enabling patterns). Each pattern is standalone - adopt what you need.
+
+---
+
+## Agent Behavior Patterns
+
+How AI agents behave during development.
+
+| Pattern | Effort | Impact | Description |
+|---------|--------|--------|-------------|
+| [Codebase Agent](codebase-agent.md) | Medium | High | Single source of truth for AI behavior |
+| [Self-Review Reflection](self-review-reflection.md) | Low | High | Agent reviews own work before presenting |
+| [Autonomous Quality Enforcement](autonomous-quality-enforcement.md) | Medium | High | Validate code before delivery |
+| [Multi-Agent Code Review](multi-agent-code-review.md) | High | Very High | Parallel specialized reviews |
+
+---
+
+## GHA Automation Patterns
+
+Proactive CI/CD workflows that reduce toil.
+
+| Pattern | Trigger | Effort | Impact |
+|---------|---------|--------|--------|
+| [Issue-to-PR](issue-to-pr.md) | `issues.opened` | High | Very High |
+| [PR Auto-Review](pr-auto-review.md) | `pull_request` | Medium | High |
+| [Dependabot Auto-Merge](dependabot-auto-merge.md) | `pull_request` | Low | Medium |
+| [Stale Issue Management](stale-issues.md) | `schedule` | Low | Medium |
+
+---
+
+## Foundation Patterns
+
+Patterns that make AI more effective.
+
+| Pattern | Purpose | Effort | Impact |
+|---------|---------|--------|--------|
+| [Layered Architecture](layered-architecture.md) | Code structure AI can reason about | Low | Medium |
+| [Security Patterns](security-patterns.md) | Practical protection | Low | Medium |
+| [Testing Patterns](testing-patterns.md) | Test pyramid approach | Medium | High |
+
+---
+
+## Adoption Matrix
+
+!!! note "Section Summary"
+    Decision tree for which patterns to adopt based on your situation. Pain point → recommended pattern mapping. Effort/impact quadrant visualization.
+
+---
+
+## Pattern Dependencies
+
+```mermaid
+flowchart TD
+    CBA[Codebase Agent] --> SR[Self-Review]
+    CBA --> MEM[Memory System]
+    CBA --> AQE[Autonomous Quality]
+    
+    AQE --> ITP[Issue-to-PR]
+    SR --> ITP
+    
+    ITP --> PAR[PR Auto-Review]
+    
+    LA[Layered Architecture] -.-> CBA
+    SEC[Security Patterns] -.-> CBA
+    TEST[Testing Patterns] -.-> AQE
+```
+
+Solid arrows: recommended order. Dashed arrows: optional dependencies.
+
+---
+
+## Quick Reference
+
+!!! note "Section Summary"
+    One-page cheat sheet of all patterns with key commands and file paths. Printable format.
diff --git a/docs/patterns/issue-to-pr.md b/docs/patterns/issue-to-pr.md
new file mode 100644
index 0000000..da2bfd7
--- /dev/null
+++ b/docs/patterns/issue-to-pr.md
@@ -0,0 +1,74 @@
+# Issue-to-PR Automation
+
+**Convert well-defined issues to draft PRs automatically.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    When a well-defined issue is created, AI analyzes it and creates a draft PR. Reduces the 20-minute PR ceremony for 2-minute fixes. Human reviews the draft, not the initial work.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Copy the workflow YAML. Configure secrets (ANTHROPIC_API_KEY). Create a test issue. See the draft PR appear.
+
+---
+
+## How It Works
+
+```mermaid
+flowchart TD
+    A[Issue Opened] --> B{Well-defined?}
+    B -->|No| C[Request Clarification]
+    B -->|Yes| D[Analyze Issue]
+    D --> E[Self-Review Analysis]
+    E --> F[Create Branch]
+    F --> G[Create Draft PR]
+    G --> H[Link to Issue]
+```
+
+---
+
+## Risk Categories
+
+!!! note "Section Summary"
+    Low risk (auto-fix eligible): formatting, linting, unused imports. Medium risk (PR only): refactoring, test additions. High risk (report only): breaking changes, security. How to configure each.
+
+---
+
+## Workflow YAML
+
+!!! note "Section Summary"
+    Complete workflow file with annotations. Trigger conditions. Permissions required. Environment variables.
+
+---
+
+## Safety Gates
+
+!!! note "Section Summary"
+    Draft PR only (requires human merge). AI analysis step with self-review. Clarification requests for unclear issues. How to add custom gates.
+
+---
+
+## Customization
+
+!!! note "Section Summary"
+    Custom labels for different risk levels. Custom analysis prompts. Integration with project boards. Slack notifications.
+
+---
+
+## Troubleshooting
+
+!!! note "Section Summary"
+    Common issues: workflow doesn't trigger, AI creates wrong PR, permissions errors. Solutions for each.
+
+---
+
+## Related Patterns
+
+- [Self-Review Reflection](self-review-reflection.md) - AI reviews its own analysis
+- [PR Auto-Review](pr-auto-review.md) - AI reviews the resulting PR
diff --git a/docs/patterns/layered-architecture.md b/docs/patterns/layered-architecture.md
new file mode 100644
index 0000000..bedc966
--- /dev/null
+++ b/docs/patterns/layered-architecture.md
@@ -0,0 +1,69 @@
+# Layered Architecture
+
+**Code structure AI can reason about effectively.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    AI assistants struggle with spaghetti code. Clear layer boundaries help AI make better decisions. Four layers: API, Service, Model, Core. Dependency rule: higher depends on lower, never reverse.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Example directory structure. What goes in each layer. How to reference in CBA context files.
+
+---
+
+## The Four Layers
+
+### API Layer
+
+!!! note "Section Summary"
+    Route handlers, request/response models, HTTP status codes, OpenAPI documentation. No business logic here.
+
+### Service Layer
+
+!!! note "Section Summary"
+    Business logic, CRUD operations, orchestration. No HTTP concerns, no database queries directly.
+
+### Model Layer
+
+!!! note "Section Summary"
+    Pydantic models, field validation, sanitization, serialization. Data structures and their rules.
+
+### Core Layer
+
+!!! note "Section Summary"
+    Configuration, security utilities, logging, shared utilities. Cross-cutting concerns.
+
+---
+
+## Dependency Rule
+
+```mermaid
+flowchart TD
+    API[API Layer] --> Service[Service Layer]
+    Service --> Model[Model Layer]
+    Model --> Core[Core Layer]
+```
+
+!!! note "Section Summary"
+    Why the rule matters. How to enforce it. What to do when you need to break it.
+
+---
+
+## AI Benefits
+
+!!! note "Section Summary"
+    Predictable AI outputs. Easier testing. Safer refactoring. How to describe layers in context files.
+
+---
+
+## Related Patterns
+
+- [Security Patterns](security-patterns.md) - Where validation happens in layers
+- [Testing Patterns](testing-patterns.md) - How to test each layer
diff --git a/docs/patterns/pr-auto-review.md b/docs/patterns/pr-auto-review.md
new file mode 100644
index 0000000..e4accfa
--- /dev/null
+++ b/docs/patterns/pr-auto-review.md
@@ -0,0 +1,56 @@
+# PR Auto-Review
+
+**AI-powered code review on every pull request.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    When any PR is opened or updated, AI reviews the code and posts structured feedback. Catches obvious issues before human time is spent. Severity levels: CRITICAL, WARNING, GOOD.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Copy the workflow YAML. Configure secrets. Open a test PR. See the AI review comment appear.
+
+---
+
+## How It Works
+
+```mermaid
+flowchart TD
+    A[PR Opened/Updated] --> B[AI Reviews Code]
+    B --> C[Self-Review Findings]
+    C --> D[Post Review Comment]
+```
+
+---
+
+## Review Format
+
+!!! note "Section Summary"
+    Structured output format with emojis for quick scanning. CRITICAL (must fix), WARNING (should consider), GOOD (positive observations). Examples of each.
+
+---
+
+## Workflow YAML
+
+!!! note "Section Summary"
+    Complete workflow file. Trigger on opened and synchronize. Review prompt with focus areas. Comment posting.
+
+---
+
+## Customization
+
+!!! note "Section Summary"
+    Custom review criteria. Different prompts for different file types. Blocking vs commenting only. Integration with required reviews.
+
+---
+
+## Related Patterns
+
+- [Issue-to-PR](issue-to-pr.md) - Source of PRs to review
+- [Multi-Agent Code Review](multi-agent-code-review.md) - Multiple specialized reviewers
diff --git a/docs/patterns/security-patterns.md b/docs/patterns/security-patterns.md
new file mode 100644
index 0000000..45c2203
--- /dev/null
+++ b/docs/patterns/security-patterns.md
@@ -0,0 +1,59 @@
+# Security Patterns
+
+**Practical protection without over-engineering.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    Philosophy: "Validate at boundaries, trust internal code." Most security bugs come from unvalidated user input, hardcoded secrets, and injection attacks. Focus on actual attack vectors.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Copy security context file. Add Pydantic validation to API models. Move secrets to environment variables. Done.
+
+---
+
+## Input Validation
+
+!!! note "Section Summary"
+    Validate all request payloads with Pydantic. Sanitization in model validators. Internal code trusts validated data. Examples of validation patterns.
+
+---
+
+## Sanitization Functions
+
+!!! note "Section Summary"
+    sanitize_string() - remove control characters, trim whitespace. validate_slug() - ensure URL-safe identifiers. When to use each.
+
+---
+
+## Secrets Management
+
+!!! note "Section Summary"
+    Environment variables only. .env files never committed. Pydantic Settings for config. Container secrets.
+
+---
+
+## What We Don't Do
+
+!!! note "Section Summary"
+    No security theater. No excessive validation everywhere. No complex encryption for non-sensitive data. Why less is more.
+
+---
+
+## AI Integration
+
+!!! note "Section Summary"
+    How to describe security rules in context files. What the CBA should check. Automated security review in PRs.
+
+---
+
+## Related Patterns
+
+- [Layered Architecture](layered-architecture.md) - Where security boundaries live
+- [PR Auto-Review](pr-auto-review.md) - Automated security checks
diff --git a/docs/patterns/stale-issues.md b/docs/patterns/stale-issues.md
new file mode 100644
index 0000000..82204ce
--- /dev/null
+++ b/docs/patterns/stale-issues.md
@@ -0,0 +1,65 @@
+# Stale Issue Management
+
+**Clean up inactive issues automatically.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    Issues inactive for 30+ days get labeled stale. After 7 more days of inactivity, they close automatically. Exempt labels protect important issues. Keeps backlog clean without manual triage.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Copy the workflow YAML. Configure exempt labels. Run manually to test. Watch stale issues get cleaned up.
+
+---
+
+## How It Works
+
+```mermaid
+flowchart TD
+    A[Weekly Schedule] --> B[Find Inactive Issues]
+    B --> C[Add Stale Label]
+    C --> D[Wait 7 Days]
+    D --> E{Activity?}
+    E -->|Yes| F[Remove Stale Label]
+    E -->|No| G[Close Issue]
+```
+
+---
+
+## Configuration
+
+!!! note "Section Summary"
+    Inactivity threshold (default: 30 days). Warning period (default: 7 days). Stale label name. Warning message customization.
+
+---
+
+## Exempt Labels
+
+!!! note "Section Summary"
+    Which labels prevent closure: pinned, security, bug. How to add custom exempt labels. When to use exempt vs just commenting.
+
+---
+
+## Workflow YAML
+
+!!! note "Section Summary"
+    Complete workflow file using actions/stale. Schedule configuration. Issue and PR settings. Exempt labels.
+
+---
+
+## Customization
+
+!!! note "Section Summary"
+    Different thresholds for issues vs PRs. Custom messages. Integration with project boards. Metrics tracking.
+
+---
+
+## Related Patterns
+
+- [Dependabot Auto-Merge](dependabot-auto-merge.md) - Another proactive cleanup pattern
diff --git a/docs/patterns/testing-patterns.md b/docs/patterns/testing-patterns.md
new file mode 100644
index 0000000..a220b7d
--- /dev/null
+++ b/docs/patterns/testing-patterns.md
@@ -0,0 +1,59 @@
+# Testing Patterns
+
+**Test pyramid approach with clear responsibilities.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    Three levels: unit (many, fast), integration (some, medium), E2E (few, slow). Each level has clear responsibilities. 80%+ coverage target without chasing 100%.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Copy testing context file. Set up tests/ directory structure. Configure pytest. Run first tests.
+
+---
+
+## Unit Tests
+
+!!! note "Section Summary"
+    Test service layer in isolation. Mock external dependencies. Arrange-Act-Assert pattern. Location: tests/unit/. What to test, what not to test.
+
+---
+
+## Integration Tests
+
+!!! note "Section Summary"
+    Test API endpoints with TestClient. Real request/response cycle. Database fixtures if applicable. Location: tests/integration/. When integration tests are better than unit tests.
+
+---
+
+## E2E Tests
+
+!!! note "Section Summary"
+    Test complete workflows. CBA automation scenarios. Location: tests/e2e/. Why to keep these minimal.
+
+---
+
+## Coverage Philosophy
+
+!!! note "Section Summary"
+    Target 80%+ coverage. Focus on critical paths. Don't chase 100% (diminishing returns). How to identify critical paths.
+
+---
+
+## AI Test Generation
+
+!!! note "Section Summary"
+    How CBA generates tests. Test patterns in context files. Review process for AI-generated tests.
+
+---
+
+## Related Patterns
+
+- [Layered Architecture](layered-architecture.md) - What each test level covers
+- [Autonomous Quality Enforcement](autonomous-quality-enforcement.md) - Running tests in CBA
diff --git a/docs/resources/demo-app.md b/docs/resources/demo-app.md
new file mode 100644
index 0000000..b7a755a
--- /dev/null
+++ b/docs/resources/demo-app.md
@@ -0,0 +1,51 @@
+# Demo Application
+
+**See AI-assisted development patterns in action.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    The demo-fastapi repository is a working FastAPI application demonstrating all patterns from this reference. Not a toy example - a complete implementation you can run locally or deploy.
+
+---
+
+## Repository
+
+**GitHub**: [jeremyeder/demo-fastapi](https://github.com/jeremyeder/demo-fastapi)
+
+---
+
+## What's Included
+
+!!! note "Section Summary"
+    Working FastAPI service with CRUD endpoints. Full CBA configuration. Test suite (unit, integration, E2E). Container support (Podman/Docker). CI/CD workflows.
+
+---
+
+## Quick Start
+
+!!! note "Section Summary"
+    Clone, install, run. API endpoints to try. How to trigger CBA workflows. Expected output for each.
+
+---
+
+## Patterns Demonstrated
+
+!!! note "Section Summary"
+    Which patterns are implemented and where to find them in the demo. File paths for each pattern. How they interact in practice.
+
+---
+
+## Extending the Demo
+
+!!! note "Section Summary"
+    How to add new endpoints following patterns. How to modify CBA for your needs. How to add new automations.
+
+---
+
+## Comparing to Reference
+
+!!! note "Section Summary"
+    Reference repo = documentation-only patterns. Demo repo = working implementation. When to use which.
diff --git a/docs/resources/presentation.md b/docs/resources/presentation.md
new file mode 100644
index 0000000..d7a45cc
--- /dev/null
+++ b/docs/resources/presentation.md
@@ -0,0 +1,47 @@
+# Presentation Document
+
+**Structured content for NotebookLM podcast generation.**
+
+---
+
+## Overview
+
+!!! note "Section Summary"
+    A 9-feature presentation designed for NotebookLM to generate podcasts. Target audience: principal engineers evaluating AI-assisted development. Format: problem/solution/payoff for each feature.
+
+---
+
+## Features Covered
+
+| # | Feature | Category |
+|---|---------|----------|
+| 1 | Codebase Agent (CBA) | Agent Behavior |
+| 2 | Memory System | Agent Behavior |
+| 3 | Issue-to-PR Automation | GHA Automation |
+| 4 | Layered Architecture | Foundation |
+| 5 | Security Patterns | Foundation |
+| 6 | Testing Patterns | Foundation |
+| 7 | CI/CD for Documentation | Foundation |
+| 8 | Self-Review Reflection | Agent Behavior |
+| 9 | Proactive GHA Workflows | GHA Automation |
+
+---
+
+## Download
+
+!!! note "Section Summary"
+    Link to PRESENTATION-ambient-code-reference.md. Markdown format for NotebookLM ingestion. PDF version for sharing.
+
+---
+
+## Using with NotebookLM
+
+!!! note "Section Summary"
+    How to upload to NotebookLM. Recommended prompts for podcast generation. Sample output audio (if available).
+
+---
+
+## Presentation Outline
+
+!!! note "Section Summary"
+    For each of the 9 features: What it is, problem it solves, how it works, benefits for principal engineers. Adoption guidance. Common objections and responses.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..4dd6316
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,104 @@
+# MkDocs configuration for Ambient Code Reference Repository
+site_name: Ambient Code Reference
+site_description: AI-assisted development patterns and best practices
+site_author: Jeremy Eder
+site_url: https://jeremyeder.github.io/reference/
+
+# Repository
+repo_name: jeremyeder/reference
+repo_url: https://github.com/jeremyeder/reference
+edit_uri: edit/main/docs/
+
+# Theme
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.action.edit
+
+# Extensions
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - tables
+  - toc:
+      permalink: true
+
+# Plugins
+plugins:
+  - search
+  - mermaid2
+
+# Navigation
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Quickstart: quickstart.md
+      - Installation: getting-started/installation.md
+      - Your First CBA: getting-started/first-cba.md
+  - Patterns:
+      - Overview: patterns/index.md
+      - Agent Behavior:
+          - Codebase Agent (CBA): patterns/codebase-agent.md
+          - Self-Review Reflection: patterns/self-review-reflection.md
+          - Autonomous Quality Enforcement: patterns/autonomous-quality-enforcement.md
+          - Multi-Agent Code Review: patterns/multi-agent-code-review.md
+      - GHA Automation:
+          - Overview: patterns/gha-automation-patterns.md
+          - Issue-to-PR: patterns/issue-to-pr.md
+          - PR Auto-Review: patterns/pr-auto-review.md
+          - Dependabot Auto-Merge: patterns/dependabot-auto-merge.md
+          - Stale Issue Management: patterns/stale-issues.md
+      - Architecture:
+          - Layered Architecture: patterns/layered-architecture.md
+          - Security Patterns: patterns/security-patterns.md
+          - Testing Patterns: patterns/testing-patterns.md
+  - Reference:
+      - Architecture: architecture.md
+      - API Patterns: api-reference.md
+      - ADR Template: adr/template.md
+  - Tutorial: tutorial.md
+  - Resources:
+      - Presentation: resources/presentation.md
+      - Demo Application: resources/demo-app.md
+
+# Extra
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/jeremyeder
+  generator: false
+
+# Copyright
+copyright: Copyright © 2024-2026 Jeremy Eder