docs: add documentation templates for streamlined docs structure (#5834)

Signed-off-by: Dan Gil <dagil@nvidia.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

docs/templates/EXAMPLE_SKILL.md

+---
+orphan: true
+---
+
+# Documentation Migration Skill
+
+This file is a ready-to-use Cursor skill for AI-assisted documentation migration.
+
+---
+
+## How to Use This Skill
+
+### Option 1: Cursor IDE
+
+1. Create the skill directory:
+   ```bash
+   mkdir -p .cursor/skills/docs-migration
+   ```
+
+2. Copy this file:
+   ```bash
+   cp docs/templates/EXAMPLE_SKILL.md .cursor/skills/docs-migration/SKILL.md
+   ```
+
+3. Remove the `orphan: true` header and this "How to Use" section
+
+4. The skill will be available when working on documentation migration
+
+### Option 2: Claude (or any AI)
+
+1. Copy everything below the separator line (`---`)
+2. Paste into your conversation as context
+3. Ask the AI: "Help me migrate the [component] documentation to the new structure"
+
+---
+
+## Skill Content
+
+Copy everything below this line for use as an AI prompt:
+
+---
+name: docs-migration
+description: Migrate Dynamo documentation to the 9-category hierarchy. Use when migrating components, backends, features, or other docs to the new structure.
+---
+
+# Documentation Migration
+
+This skill guides you through migrating Dynamo documentation to the new 9-category hierarchy.
+
+## Inputs
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| Component/Topic | Yes | What to migrate (e.g., "planner", "kubernetes", "multimodal") |
+| Source Path | Yes | Current location (e.g., `docs/planner/`) |
+| Target Category | Yes | One of: components, backends, features, deploy, performance, infrastructure, integrations |
+
+## Directory Hierarchy
+
+```
+docs/
+├── components/          # Router, Planner, KVBM, Frontend, Profiler
+├── backends/            # vLLM, SGLang, TRT-LLM
+├── features/            # Multimodal, LoRA, Speculative Decoding
+├── deploy/              # Kubernetes, Helm, Operator
+├── performance/         # Tuning, Benchmarks
+├── infrastructure/      # Observability, Fault Tolerance, Development
+├── integrations/        # LMCache, HiCache, NIXL
+├── reference/           # CLI, Glossary, Support Matrix
+└── design_docs/         # Tier 3 design documents
+```
+
+---
+
+## Phase 1: Analyze Existing Docs
+
+### Step 1.1: Inventory Current Files
+
+```bash
+# List existing documentation
+ls -la docs/<source_path>/
+
+# Count lines in each file
+wc -l docs/<source_path>/*.md
+```
+
+### Step 1.2: Categorize Content
+
+For each file, identify content type:
+
+| Category | Target File | Description |
+|----------|-------------|-------------|
+| Overview | README.md | Component description, feature matrix |
+| Quick Start | README.md | Minimal steps to get running |
+| Deployment | `<name>_guide.md` | Setup, prerequisites, container images |
+| Configuration | `<name>_guide.md` | CLI args, env vars, config files |
+| Integration | `<name>_guide.md` | Connecting to other components |
+| Troubleshooting | `<name>_guide.md` | Common issues and fixes |
+| Examples | `<name>_examples.md` | Code samples, YAML configs |
+| Architecture | `<name>_design.md` | Design decisions, algorithms |
+
+**>>> STOP: Share your analysis. Ask if there are content priorities or known issues.**
+
+---
+
+## Phase 2: Create Migration Mapping
+
+### Step 2.1: Document Current → Target Mapping
+
+Create a mapping showing where each section will move:
+
+```markdown
+## Content Migration Mapping
+
+### README.md (Tier 2)
+
+| New Section | Source | Est. Lines |
+|-------------|--------|------------|
+| Overview | source_file.md → Section | X |
+| Feature Matrix | source_file.md → Section | X |
+| Quick Start | source_file.md → Section | X |
+| Next Steps | New | 10 |
+
+### <name>_guide.md (Tier 2)
+
+| New Section | Source | Est. Lines |
+|-------------|--------|------------|
+| Deployment | source_file.md → Section | X |
+| Configuration | source_file.md → Section | X |
+| Integration | source_file.md → Section | X |
+| Troubleshooting | source_file.md → Section | X |
+```
+
+**>>> STOP: Share mapping. Ask if any content should be prioritized or excluded.**
+
+---
+
+## Phase 3: Create File Structure
+
+### Step 3.1: Create Target Directory
+
+```bash
+# For components
+mkdir -p docs/components/<name>
+
+# For other categories
+mkdir -p docs/<category>/<name>
+```
+
+### Step 3.2: Create Files
+
+```bash
+touch docs/<category>/<name>/README.md
+touch docs/<category>/<name>/<name>_guide.md
+touch docs/<category>/<name>/<name>_examples.md
+touch docs/design_docs/<name>_design.md
+```
+
+### Step 3.3: Create Tier 1 Stub (Components Only)
+
+For components, create redirect stub:
+
+```markdown
+# Dynamo <Component>
+
+<One-sentence description.>
+
+See `docs/components/<name>/` for documentation.
+```
+
+---
+
+## Phase 4: Migrate Content
+
+### Step 4.1: Use Templates
+
+Reference templates in `docs/templates/`:
+- `component_readme.md` - Tier 2 README
+- `component_guide.md` - Tier 2 Guide
+- `component_examples.md` - Tier 2 Examples
+- `component_design.md` - Tier 3 Design
+
+### Step 4.2: Preserve All Content
+
+- Copy content exactly unless errors exist
+- Preserve code examples
+- Preserve diagrams (Mermaid, images)
+- Update internal links to new paths
+
+**>>> STOP: Share migrated documents. Ask if content is complete.**
+
+---
+
+## Phase 5: Update Links
+
+### Step 5.1: Find Files Linking to Old Path
+
+```bash
+# Find all files with links to old path
+rg -l "docs/<old_path>" docs/ fern/
+
+# Find RST cross-references
+rg ":doc:\`.*<old_path>" docs/
+
+# Find relative markdown links
+rg "\]\(.*<old_path>" docs/
+```
+
+### Step 5.2: Update Sphinx Navigation
+
+1. **index.rst** - Update toctree entries:
+   ```rst
+   .. toctree::
+      Page Title <../new/path/file>
+   ```
+
+2. **_sections/*.rst** - Update section toctrees
+
+3. **conf.py** - Add redirect for moved files:
+   ```python
+   redirects = {
+       "old/path/file": "../new/path/file.html",
+   }
+   ```
+
+### Step 5.3: Update Fern Navigation
+
+1. **versions/next.yml** - Update page paths:
+   ```yaml
+   - page: Page Title
+     path: ../pages/new/path.md
+   ```
+
+2. **Move files** in `fern/pages/` to match new structure
+
+### Step 5.4: Update Cross-References in Other Docs
+
+For each file found in Step 5.1:
+- Update relative paths to new locations
+- Verify links work
+
+**>>> STOP: Share link update summary. List files modified.**
+
+---
+
+## Phase 6: Edit for Style
+
+Review migrated documents for FLOW, STYLE, and CONSISTENCY.
+
+**Do NOT change content meaning - only improve presentation.**
+
+### Step 6.1: Review Checklist
+
+For each document:
+
+**FLOW:**
+- [ ] First paragraph states what the doc covers
+- [ ] Sections ordered: Overview → Setup → Usage → Troubleshooting
+- [ ] No orphaned paragraphs (single sentences between sections)
+
+**STYLE:**
+- [ ] Instructions use active voice ("Run", "Create", "Add")
+- [ ] No redundant phrases ("To" not "In order to")
+- [ ] Sentences ≤25 words
+
+**CONSISTENCY:**
+- [ ] Component names: vLLM, SGLang, TensorRT-LLM
+- [ ] Status indicators: ✅ 🚧 ❌
+- [ ] Heading hierarchy: # → ## → ### (no skips)
+- [ ] Code blocks specify language
+
+### Step 6.2: Generate Suggested Edits
+
+Present suggestions using FLAG format:
+
+```markdown
+---
+
+### FLAG: [FLOW|STYLE|CONSISTENCY] - [Brief Description]
+
+**File:** `path/to/file.md`
+**Line(s):** X-Y
+
+**Current:**
+> [Original text]
+
+**Suggested:**
+> [Improved text]
+
+**Reasoning:** [Why this improves flow/style/consistency]
+
+---
+```
+
+### Step 6.3: Apply Approved Edits
+
+After user reviews:
+- Apply approved edits only
+- Skip rejected suggestions
+- Document patterns for future reference
+
+**>>> STOP: Share suggested edits. Ask which to apply.**
+
+---
+
+## Phase 7: Validate and Cleanup
+
+### Step 7.1: Validation Checklist
+
+```
+Validation for: [COMPONENT_NAME]
+- [ ] All content from original files preserved
+- [ ] No broken links (test with docs build)
+- [ ] Feature matrix matches current capabilities
+- [ ] Code examples are correct
+- [ ] Mermaid diagrams render
+- [ ] Navigation links work between files
+- [ ] Sphinx toctree updated
+- [ ] Fern navigation updated
+- [ ] conf.py redirects added
+```
+
+### Step 7.2: Test Docs Build
+
+```bash
+# Build Sphinx docs
+cd docs && make html
+
+# Check for warnings about missing references
+```
+
+### Step 7.3: Cleanup Old Files
+
+After validation and approval:
+1. Delete original files
+2. Keep deprecated files with deprecation notice if needed
+3. Commit changes
+
+**>>> STOP: Share validation results. Ask for approval before deleting originals.**
+
+---
+
+## Category-Specific Notes
+
+### Components (Router, Planner, KVBM, Frontend, Profiler)
+
+- Target: `docs/components/<name>/`
+- Requires Tier 1 stub in `components/src/dynamo/<name>/README.md`
+- Tier 3 design doc in `docs/design_docs/<name>_design.md`
+
+### Backends (vLLM, SGLang, TRT-LLM)
+
+- Target: `docs/backends/<name>/`
+- Tier 3 is external (upstream project docs)
+- Create `docs/backends/README.md` for backend comparison
+
+### Deploy (Kubernetes)
+
+- Target: `docs/deploy/`
+- Flat structure (no subdirectories per topic)
+- Examples go in `docs/deploy/examples/`
+
+### Performance
+
+- Target: `docs/performance/`
+- Includes tuning and benchmarks (merged)
+- Flat structure
+
+### Infrastructure (Observability, Fault Tolerance, Development)
+
+- Target: `docs/infrastructure/<topic>/`
+- Subdirectory per topic
+- Development guides for contributors

docs/templates/MIGRATION_GUIDE.md

+---
+orphan: true
+---
+
+# Documentation Migration Guide
+
+This guide covers migrating Dynamo documentation to the new 9-category hierarchy.
+
+---
+
+## Directory Hierarchy
+
+Documentation is organized into 9 top-level categories:
+
+```
+docs/
+├── components/          # Router, Planner, KVBM, Frontend, Profiler
+├── backends/            # vLLM, SGLang, TRT-LLM
+├── features/            # Multimodal, LoRA, Speculative Decoding
+├── deploy/              # Kubernetes, Helm, Operator
+├── performance/         # Tuning, Benchmarks
+├── infrastructure/      # Observability, Fault Tolerance, Development
+├── integrations/        # LMCache, HiCache, NIXL
+├── reference/           # CLI, Glossary, Support Matrix
+└── design_docs/         # Tier 3 design documents
+```
+
+---
+
+## Category Reference
+
+| Category | Location | Content Type |
+|----------|----------|--------------|
+| **Components** | `docs/components/<name>/` | Standalone deployable services (Router, Planner, KVBM, Frontend, Profiler) |
+| **Backends** | `docs/backends/<name>/` | LLM inference engine integrations (vLLM, SGLang, TRT-LLM) |
+| **Features** | `docs/features/<name>/` | Cross-cutting capabilities (Multimodal, LoRA, Speculative Decoding) |
+| **Deploy** | `docs/deploy/` | Kubernetes deployment, operator, Helm charts |
+| **Performance** | `docs/performance/` | Performance tuning, benchmarking, profiling |
+| **Infrastructure** | `docs/infrastructure/<topic>/` | Observability, fault tolerance, development guides |
+| **Integrations** | `docs/integrations/<name>/` | External tool integrations (LMCache, HiCache, NIXL) |
+| **Reference** | `docs/reference/` | CLI reference, glossary, support matrix |
+| **Design** | `docs/design_docs/` | Architecture and algorithm documentation (Tier 3) |
+
+---
+
+## Three-Tier Pattern
+
+Components and backends follow a three-tier documentation pattern:
+
+| Tier | Location | Purpose | Audience |
+|------|----------|---------|----------|
+| **Tier 1** | `components/src/dynamo/<name>/README.md` | Redirect stub (5 lines) | Developers browsing code |
+| **Tier 2** | `docs/<category>/<name>/` | User documentation | Users, operators |
+| **Tier 3** | `docs/design_docs/<name>_design.md` | Design documentation | Contributors |
+
+---
+
+## Link Update Checklist
+
+When moving documentation, update links in these locations:
+
+### 1. Internal Markdown Links
+
+Find files linking to the old path:
+
+```bash
+# Find all files with links to old path
+rg -l "docs/old_path" docs/ fern/
+
+# Find relative markdown links
+rg "\]\(.*old_path" docs/
+```
+
+### 2. Sphinx Configuration
+
+**Files to update:**
+
+| File | Content |
+|------|---------|
+| `docs/index.rst` | Main toctree with section references |
+| `docs/_sections/*.rst` | Section toctrees (8 files) |
+| `docs/hidden_toctree.rst` | Orphaned pages not in main nav |
+| `docs/conf.py` | Redirects mapping (lines 40-98) |
+
+**Toctree syntax:**
+```rst
+.. toctree::
+   :hidden:
+
+   Page Title <../new/path/file>
+```
+
+**Add redirect in conf.py:**
+```python
+redirects = {
+    "old/path/file": "../new/path/file.html",
+}
+```
+
+### 3. Fern Configuration
+
+**Files to update:**
+
+| File | Content |
+|------|---------|
+| `fern/docs.yml` | Site config and version reference |
+| `fern/versions/next.yml` | Full navigation structure |
+
+**Navigation syntax:**
+```yaml
+- page: Page Title
+  path: ../pages/new/path.md
+```
+
+**Move files in `fern/pages/` to match new structure.**
+
+### 4. RST Cross-References
+
+Find and update:
+```rst
+:doc:`../old/path/file`
+```
+
+### 5. Include Directives
+
+Check `docs/_includes/` for includes:
+```rst
+.. include:: ../old/path/file.rst
+```
+
+---
+
+## Style Editing Guidelines
+
+After migrating content, review for FLOW, STYLE, and CONSISTENCY.
+
+**Do NOT change content meaning - only improve presentation.**
+
+### FLOW Rules
+
+| Rule | Description |
+|------|-------------|
+| Lead with the point (BLUF) | First paragraph states what the doc covers |
+| Logical section order | Overview → Setup → Usage → Troubleshooting |
+| One idea per paragraph | Split paragraphs with multiple topics |
+| No orphaned sentences | Avoid single sentences between sections |
+
+### STYLE Rules
+
+| Rule | Example |
+|------|---------|
+| Active voice for instructions | "Run the command" not "The command should be run" |
+| Consistent tense | All steps in present tense |
+| No redundant phrases | "To" not "In order to" |
+| Short sentences | Target ≤25 words |
+
+### CONSISTENCY Rules
+
+| Rule | Standard |
+|------|----------|
+| Component names | vLLM, SGLang, TensorRT-LLM (or TRT-LLM) |
+| Status indicators | ✅ Supported, 🚧 Experimental, ❌ Not Supported |
+| Heading hierarchy | # → ## → ### (no skips) |
+| Code block languages | Always specify (```python, ```bash, ```yaml) |
+
+---
+
+## Related Files
+
+- [SOURCE_TARGET_MAPPING.md](SOURCE_TARGET_MAPPING.md) - Comprehensive file-level source → target mapping
+- [README.md](README.md) - Template overview and selection guide
+- [EXAMPLE_SKILL.md](EXAMPLE_SKILL.md) - Cursor skill for AI-assisted migration
+- Individual templates: `component_readme.md`, `component_guide.md`, etc.

docs/templates/README.md

+---
+orphan: true
+---
+
+# Documentation Templates
+
+Templates for creating consistent Dynamo documentation.
+
+## Directory Hierarchy
+
+### Components (Router, Planner, KVBM, Frontend, Profiler)
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ Tier 1: components/src/dynamo/<component>/README.md          │ ← Redirect stub
+│   Content: 1-5 lines pointing to docs/components/<component>/│
+│   Template: incode_readme.md                                 │
+└─────────────────────┬────────────────────────────────────────┘
+                      ▼
+┌──────────────────────────────────────────────────────────────┐
+│ Tier 2: docs/components/<component>/                         │ ← User docs
+│   • README.md ← component_readme.md                          │
+│   • <component>_guide.md ← component_guide.md                │
+│   • <component>_examples.md ← component_examples.md          │
+└─────────────────────┬────────────────────────────────────────┘
+                      ▼
+┌──────────────────────────────────────────────────────────────┐
+│ Tier 3: docs/design_docs/<component>_design.md               │ ← Contributor docs
+│   Template: component_design.md                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Backends (vLLM, SGLang, TRT-LLM)
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Tier 1: components/src/dynamo/<backend>/README.md   │ ← Redirect stub
+│   Content: 1-5 lines pointing to docs/backends/     │
+│   Template: incode_readme.md                        │
+└─────────────────────┬───────────────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────────────┐
+│ Tier 2: docs/backends/<backend>/                    │ ← User docs
+│   • README.md ← backend_readme.md                   │
+│   • <backend>_guide.md ← backend_guide.md           │
+│                                                     │
+│ Tier 2.5: docs/backends/README.md (exists)          │
+│   • Backend comparison table                        │
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│ Tier 3: External                                    │
+│   Backend internals documented in upstream repos    │
+└─────────────────────────────────────────────────────┘
+```
+
+### Features (Multimodal, LoRA, Speculative Decoding)
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Tier 1: N/A                                         │
+│   No in-code README (features are not components)   │
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│ Tier 2: docs/features/<feature>/                    │ ← User docs
+│   • README.md ← feature_readme.md                   │
+│   • <feature>_vllm.md ← feature_backend.md          │
+│   • <feature>_sglang.md ← feature_backend.md        │
+│   • <feature>_trtllm.md ← feature_backend.md        │
+└─────────────────────┬───────────────────────────────┘
+                      ▼
+┌─────────────────────────────────────────────────────┐
+│ Tier 3: docs/design_docs/<feature>_design.md        │ ← Optional
+│   Only if significant architecture                  │
+└─────────────────────────────────────────────────────┘
+```
+
+### Integrations (LMCache, HiCache, NIXL)
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Tier 1: N/A                                         │
+│   No in-code README (external tools)                │
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│ Tier 2: docs/integrations/<integration>/            │ ← User docs
+│   • README.md ← integration_readme.md               │
+│   • <integration>_setup.md (custom)                 │
+│   • <integration>_<backend>.md (custom)             │
+└─────────────────────────────────────────────────────┘
+```
+
+### Deploy (Kubernetes, Helm, Operator)
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Tier 1: N/A                                         │
+│   No in-code README (deployment topics)             │
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│ Tier 2: docs/deploy/                                │ ← User docs
+│   • README.md (deployment overview)                 │
+│   • installation_guide.md, dynamo_operator.md       │
+│   • helm.md, examples/                              │
+└─────────────────────────────────────────────────────┘
+```
+
+### Performance (Tuning, Benchmarks)
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Tier 1: N/A                                         │
+│   No in-code README (performance topics)            │
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│ Tier 2: docs/performance/                           │ ← User docs
+│   • README.md (performance overview)                │
+│   • tuning.md, benchmarking.md, etc.                │
+└─────────────────────────────────────────────────────┘
+```
+
+### Infrastructure (Observability, Fault Tolerance, Development)
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Tier 1: N/A                                         │
+│   No in-code README (operations topics)             │
+└─────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────┐
+│ Tier 2: docs/infrastructure/<topic>/                │ ← User docs
+│   • README.md ← infrastructure_readme.md            │
+│   • <subtopic>.md (detailed guides)                 │
+└─────────────────────────────────────────────────────┘
+```
+
+## Three-Tier Pattern
+
+| Tier | Purpose | Audience | Location |
+|------|---------|----------|----------|
+| **Tier 1** | Redirect stub (5 lines) | Developers browsing code | `components/src/dynamo/<name>/README.md` |
+| **Tier 2** | User documentation | Users, operators | `docs/<category>/<name>/` (e.g., `docs/components/router/`) |
+| **Tier 3** | Design documentation | Contributors | `docs/design_docs/<name>_design.md` |
+
+## Template Selection
+
+| What you're documenting | Templates to use |
+|------------------------|------------------|
+| New component | `incode_readme.md` + `component_*.md` (all 4) |
+| New backend | `incode_readme.md` + `backend_*.md` (both) |
+| New feature | `feature_readme.md` + `feature_backend.md` (per backend) |
+| New integration | `integration_readme.md` |
+| New deploy topic | Custom (follows `docs/deploy/` structure) |
+| New performance topic | Custom (follows `docs/performance/` structure) |
+| New infrastructure topic | `infrastructure_readme.md` |
+| Migrating existing docs | Use the template matching your target file |
+
+## Usage
+
+1. Identify which category your documentation belongs to (component, backend, feature, integration)
+2. Create the directory structure shown above
+3. Copy templates to the correct locations with correct filenames
+4. Replace all `<placeholders>` with actual values
+5. Replace `<!-- comments -->` with actual content
+6. Remove sections that don't apply
+
+## Updating Navigation
+
+After adding new documentation:
+
+1. **Sphinx (current):** Update `docs/index.rst` or the appropriate `_sections/*.rst` file to include your new docs in the navigation
+2. **Fern (future):** Update `fern/docs.yml` with your new pages
+
+See [docs/README.md](../README.md) for documentation build instructions.
+
+## Migrating Existing Docs
+
+For migrating existing documentation to the new structure:
+
+### Quick Reference
+
+- [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) - Comprehensive migration guide with link update checklist
+- [EXAMPLE_SKILL.md](EXAMPLE_SKILL.md) - AI-assisted migration skill (works with Cursor and Claude)
+
+### Using the AI Skill
+
+1. **Cursor IDE:** Copy `EXAMPLE_SKILL.md` to `.cursor/skills/docs-migration/SKILL.md`
+2. **Claude/Other AI:** Copy the skill content into your conversation as context
+3. Follow the phased approach with STOP points for review
+
+### Manual Migration
+
+1. Read [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for the full process
+2. Use the link update checklist to update Sphinx and Fern navigation
+3. Apply style guidelines for FLOW, STYLE, and CONSISTENCY

docs/templates/SOURCE_TARGET_MAPPING.md

+---
+orphan: true
+---
+
+# Source-to-Target File Mapping
+
+This document provides a comprehensive file-level mapping from current documentation locations to the new hierarchy for Components, Backends, Features, and Integrations.
+
+---
+
+## How to Use This Mapping
+
+1. Find the source file you want to migrate in the tables below
+2. Note the **Target** path and **Action** type
+3. Follow the [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for link updates
+4. Use [EXAMPLE_SKILL.md](EXAMPLE_SKILL.md) for AI-assisted migration
+
+### Legend
+
+| Symbol | Content Type |
+|--------|--------------|
+| **O** | Overview - entry point, introduction |
+| **G** | Guide - step-by-step instructions |
+| **E** | Examples - code samples, templates |
+| **D** | Design - architecture, algorithms |
+| **R** | Reference - API specs, CLI docs |
+
+| Action | Description |
+|--------|-------------|
+| **Move** | Relocate file to new path |
+| **Merge** | Combine multiple files into one |
+| **Split** | Separate one file into multiple |
+| **Convert** | Transform RST to Markdown |
+| **Create** | New content needed |
+| **Extract** | Pull content from another file |
+
+---
+
+## 1. Components
+
+### Router (1,334 lines)
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/router/README.md` | 316 | O | `docs/components/router/README.md` | Move | Quick start, configuration |
+| `docs/router/kv_cache_routing.md` | 733 | G | `docs/components/router/router_guide.md` | Move | Deep technical guide |
+| `docs/router/kv_events.md` | 285 | G | `docs/components/router/router_guide.md` | Merge | Append to guide |
+
+**Tier 1 (In-Code):**
+
+| Source | Target | Action |
+|--------|--------|--------|
+| `components/src/dynamo/router/README.md` | Keep | Update link to `docs/components/router/` |
+
+### Planner (863 lines)
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/planner/planner_intro.rst` | 82 | O | `docs/components/planner/README.md` | Convert | RST→MD, merge overview |
+| `docs/planner/sla_planner_quickstart.md` | 521 | G | `docs/components/planner/planner_guide.md` | Split | Guide + examples |
+| `docs/planner/sla_planner.md` | 203 | D | `docs/design_docs/planner_design.md` | Move | Architecture content |
+| `docs/planner/load_planner.md` | 57 | G | `docs/components/planner/load_planner.md` | Move | Keep as deprecated |
+
+**Tier 1 (In-Code):**
+
+| Source | Target | Action |
+|--------|--------|--------|
+| `components/src/dynamo/planner/README.md` | Keep | Update link to `docs/components/planner/` |
+
+### KVBM (972 lines)
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/kvbm/kvbm_intro.rst` | 69 | O | `docs/components/kvbm/README.md` | Convert | RST→MD |
+| `docs/kvbm/kvbm_architecture.md` | 40 | O | `docs/components/kvbm/README.md` | Merge | Combine overviews |
+| `docs/kvbm/kvbm_components.md` | 71 | O | `docs/components/kvbm/README.md` | Merge | Combine overviews |
+| `docs/kvbm/kvbm_motivation.md` | 44 | O | `docs/components/kvbm/README.md` | Merge | Combine overviews |
+| `docs/kvbm/kvbm_integrations.md` | 45 | G | `docs/components/kvbm/kvbm_guide.md` | Move | Integration instructions |
+| `docs/kvbm/vllm-setup.md` | 195 | E | `docs/components/kvbm/kvbm_examples.md` | Merge | Combine examples |
+| `docs/kvbm/trtllm-setup.md` | 223 | E | `docs/components/kvbm/kvbm_examples.md` | Merge | Combine examples |
+| `docs/kvbm/kvbm_design_deepdive.md` | 262 | D | `docs/design_docs/kvbm_design.md` | Move | Design content |
+| `docs/kvbm/kvbm_reading.md` | 23 | R | `docs/components/kvbm/kvbm_guide.md` | Merge | Append references |
+| `docs/kvbm/kvbm_metrics_grafana.png` | — | — | `docs/components/kvbm/images/` | Move | Image asset |
+
+**Tier 1 (In-Code):**
+
+| Source | Target | Action |
+|--------|--------|--------|
+| `lib/bindings/kvbm/README.md` | Keep | Update link to `docs/components/kvbm/` |
+
+### Frontend (2,991 lines)
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/frontends/kserve.md` | 99 | G | `docs/components/frontend/frontend_guide.md` | Move | KServe integration |
+| `docs/frontends/openapi.json` | 2,892 | R | `docs/reference/api/openapi.json` | Move | API spec to reference |
+| — | — | O | `docs/components/frontend/README.md` | Create | New overview needed |
+
+**Tier 1 (In-Code):**
+
+| Source | Target | Action |
+|--------|--------|--------|
+| `components/src/dynamo/http/README.md` | Create | Stub linking to `docs/components/frontend/` |
+
+### Profiler (New)
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| — | — | O | `docs/components/profiler/README.md` | Create | New overview |
+| — | — | G | `docs/components/profiler/profiler_guide.md` | Create | New guide |
+
+---
+
+## 2. Backends
+
+Backends remain at `docs/backends/<backend>/` with minimal structural changes.
+
+### vLLM
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/backends/vllm/README.md` | — | O | Keep | — | No change |
+| `docs/backends/vllm/disagg.md` | — | G | Keep | — | No change |
+| `docs/backends/vllm/aggregated.md` | — | G | Keep | — | No change |
+| `docs/backends/vllm/speculative_decoding.md` | — | G | `docs/features/speculative_decoding/` | Extract | Move to features |
+| `docs/backends/vllm/LMCache_Integration.md` | — | G | `docs/integrations/lmcache/` | Extract | Move to integrations |
+
+### SGLang
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/backends/sglang/README.md` | — | O | Keep | — | No change |
+| `docs/backends/sglang/disagg.md` | — | G | Keep | — | No change |
+| `docs/backends/sglang/aggregated.md` | — | G | Keep | — | No change |
+| `docs/backends/sglang/sgl-hicache-example.md` | — | G | `docs/integrations/hicache/` | Extract | Move to integrations |
+
+### TRT-LLM
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/backends/trtllm/README.md` | — | O | Keep | — | No change |
+| `docs/backends/trtllm/disagg.md` | — | G | Keep | — | No change |
+| `docs/backends/trtllm/aggregated.md` | — | G | Keep | — | No change |
+
+---
+
+## 3. Features
+
+### Multimodal (1,644 lines)
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/multimodal/index.md` | 213 | O | `docs/features/multimodal/README.md` | Move | Rename to README |
+| `docs/multimodal/vllm.md` | 522 | G | `docs/features/multimodal/multimodal_vllm.md` | Move | |
+| `docs/multimodal/sglang.md` | 433 | G | `docs/features/multimodal/multimodal_sglang.md` | Move | |
+| `docs/multimodal/trtllm.md` | 476 | G | `docs/features/multimodal/multimodal_trtllm.md` | Move | |
+
+### Speculative Decoding (New)
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/backends/vllm/speculative_decoding.md` | — | G | `docs/features/speculative_decoding/README.md` | Extract | From vLLM backend |
+
+### Agents (183 lines)
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/agents/tool-calling.md` | 183 | G | `docs/features/agents/README.md` | Move | Agent/tool calling |
+
+---
+
+## 4. Integrations
+
+### Extracted from Backends
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/backends/vllm/LMCache_Integration.md` | — | G | `docs/integrations/lmcache/README.md` | Extract | From vLLM |
+| `docs/backends/sglang/sgl-hicache-example.md` | — | G | `docs/integrations/hicache/README.md` | Extract | From SGLang |
+
+### NIXL
+
+| Source | Lines | Type | Target | Action | Notes |
+|--------|-------|------|--------|--------|-------|
+| `docs/api/nixl_connect/*` | — | G | `docs/integrations/nixl/` | Move | Entire folder |
+
+---
+
+## Summary Statistics
+
+### By Category
+
+| Category | Files | Lines | Actions |
+|----------|-------|-------|---------|
+| Components | 18 | ~3,200 | Move, Merge, Convert, Create |
+| Backends | 12 | varies | Extract only |
+| Features | 6 | ~1,800 | Move, Extract |
+| Integrations | 3+ | varies | Extract, Move |
+
+### By Action Type
+
+| Action | Count | Description |
+|--------|-------|-------------|
+| **Move** | ~15 | Simple relocation |
+| **Merge** | ~8 | Combine multiple files |
+| **Convert** | 2 | RST to Markdown |
+| **Extract** | 4 | Pull from other files |
+| **Create** | 4 | New content needed |
+
+---
+
+## Related Files
+
+- [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) - Link update checklist and style guidelines
+- [EXAMPLE_SKILL.md](EXAMPLE_SKILL.md) - Cursor skill for AI-assisted migration
+- [README.md](README.md) - Template overview and selection guide

docs/templates/backend_guide.md

+---
+orphan: true
+---
+
+# <Backend> Guide
+
+Advanced deployment and configuration for the <Backend> backend.
+
+## Deployment
+
+### Single-Node Setup
+
+<!-- Local deployment instructions -->
+
+### Multi-Node Setup
+
+<!-- Distributed deployment with TP/PP -->
+
+### Kubernetes Deployment
+
+```yaml
+# Full DGDR example
+```
+
+## Configuration
+
+### CLI Arguments
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| <!-- arg --> | <!-- type --> | <!-- default --> | <!-- description --> |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| <!-- var --> | <!-- default --> | <!-- description --> |
+
+### Model Configuration
+
+<!-- Model-specific settings, quantization -->
+
+## Performance Tuning
+
+### Memory Optimization
+
+<!-- KV cache sizing, batch limits -->
+
+### Throughput Optimization
+
+<!-- Concurrency, prefill/decode settings -->
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| <!-- issue --> | <!-- cause --> | <!-- solution --> |
+
+### Debug Mode
+
+```bash
+# Add debug command from existing docs
+```
+
+## See Also
+
+| Document | Path |
+|----------|------|
+| `<Backend> Overview` | `./README.md` |
+| Backend Comparison | `../README.md` |
+
+<!-- Convert to links when using template -->

docs/templates/backend_readme.md

+---
+orphan: true
+---
+
+# <Backend> Backend
+
+<!-- 2-3 sentence overview of this backend integration -->
+
+## Feature Matrix
+
+<!-- Copy actual feature matrix from existing backend docs -->
+<!-- Example pattern (from vLLM README): -->
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| Disaggregated Serving | ✅ | |
+| KV-Aware Routing | ✅ | |
+| SLA-Based Planner | ✅ | |
+| Multimodal | ✅ | Vision models |
+| LoRA | 🚧 | Experimental |
+
+## Quick Start
+
+### Prerequisites
+
+- <!-- List prerequisites -->
+
+### Usage
+
+```bash
+# Add minimal usage example from existing backend docs
+# Example pattern (vLLM):
+# python -m dynamo.vllm --model <model-name>
+# Example pattern (SGLang):
+# python -m dynamo.sglang --model <model-name>
+```
+
+### Kubernetes
+
+```yaml
+# Add DGDR example - use apiVersion: nvidia.com/v1alpha1
+# See recipes/ folder for production examples
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| <!-- param --> | <!-- default --> | <!-- description --> |
+
+<!-- EXAMPLE: Filled-in Configuration for vLLM would look like:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--model` | required | Model path or HuggingFace ID |
+| `--tensor-parallel-size` | `1` | Number of GPUs for tensor parallelism |
+| `--max-model-len` | auto | Maximum sequence length |
+-->
+
+## Next Steps
+
+| Document | Path | Description |
+|----------|------|-------------|
+| `<Backend> Guide` | `<backend>_guide.md` | Advanced configuration |
+| Backend Comparison | `../README.md` | Compare backends |
+
+<!-- Convert table rows to markdown links -->

docs/templates/component_design.md

+---
+orphan: true
+---
+
+# <Component> Design
+
+Architecture and design decisions for the <Component>.
+
+## Overview
+
+<!-- High-level architecture description -->
+
+## Design Goals
+
+1. **Goal 1** - Description
+2. **Goal 2** - Description
+3. **Goal 3** - Description
+
+## Architecture
+
+### Components
+
+<!-- Description of internal components -->
+
+### Data Flow
+
+```
+┌─────────┐    ┌─────────┐    ┌─────────┐
+│ Input   │───▶│ Process │───▶│ Output  │
+└─────────┘    └─────────┘    └─────────┘
+```
+
+## Design Decisions
+
+### Decision 1: <!-- Title -->
+
+**Context:** <!-- What problem were we solving? -->
+
+**Options Considered:**
+1. Option A - Pros/Cons
+2. Option B - Pros/Cons
+
+**Decision:** <!-- What we chose and why -->
+
+**Consequences:** <!-- Trade-offs accepted -->
+
+## Algorithms
+
+### <!-- Algorithm Name -->
+
+<!-- Algorithm description -->
+
+```
+Pseudocode or formula
+```
+
+## Performance Considerations
+
+<!-- Performance characteristics, bottlenecks, optimization opportunities -->
+
+## Future Work
+
+- <!-- Planned improvement 1 -->
+- <!-- Planned improvement 2 -->
+
+## References
+
+- <!-- Related design docs -->
+- <!-- External papers or resources -->

docs/templates/component_examples.md

+---
+orphan: true
+---
+
+# <Component> Examples
+
+Usage examples for the <Component>.
+
+## Basic Examples
+
+### Example 1: <!-- Title -->
+
+```bash
+# Add example from existing docs
+```
+
+### Example 2: <!-- Title -->
+
+```python
+# Add example from existing docs
+```
+
+## Kubernetes Examples
+
+### Minimal Deployment
+
+```yaml
+# Add minimal DGDR from existing docs
+```
+
+### Production Deployment
+
+```yaml
+# Add production DGDR from existing docs
+```
+
+## Advanced Examples
+
+### <!-- Advanced Use Case Title -->
+
+<!-- Description -->
+
+```bash
+# Add example
+```
+
+## Sample Configurations
+
+### config-minimal.yaml
+
+```yaml
+# Add from existing docs
+```

docs/templates/component_guide.md

+---
+orphan: true
+---
+
+# <Component> Guide
+
+This guide covers deployment, configuration, and integration for the <Component>.
+
+## Deployment
+
+### Single-Node Setup
+
+<!-- Instructions for local/single-node deployment -->
+
+### Multi-Node Setup
+
+<!-- Instructions for distributed deployment -->
+
+### Kubernetes Deployment
+
+```yaml
+# Full DGDR example
+```
+
+## Configuration
+
+### CLI Arguments
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| <!-- arg --> | <!-- type --> | <!-- default --> | <!-- description --> |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| <!-- var --> | <!-- default --> | <!-- description --> |
+
+### Configuration File
+
+```yaml
+# Add config file example if applicable
+```
+
+## Integration
+
+### With Router
+
+<!-- How to integrate with Router -->
+
+### With Planner
+
+<!-- How to integrate with Planner -->
+
+### With Observability
+
+<!-- Metrics, logging, tracing integration -->
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Error message | Root cause | Fix |
+
+### Debug Mode
+
+```bash
+# Add debug command from existing docs
+```
+
+## See Also
+
+| Document | Path |
+|----------|------|
+| `<Component> Examples` | `<component>_examples.md` |
+| `<Component> Design` | `/docs/design_docs/<component>_design.md` |
+
+<!-- Convert table rows to markdown links -->

docs/templates/component_readme.md

+---
+orphan: true
+---
+
+# <Component>
+
+<!-- 2-3 sentence overview of what this component does and its role in Dynamo -->
+
+## Feature Matrix
+
+| Feature | Status |
+|---------|--------|
+| Feature 1 | ✅ Supported |
+| Feature 2 | 🚧 Experimental |
+| Feature 3 | ❌ Not Supported |
+
+## Quick Start
+
+### Prerequisites
+
+- <!-- List prerequisites -->
+
+### Usage
+
+```bash
+# Add minimal usage example from existing docs
+# Example pattern (from Router):
+# python -m dynamo.frontend --router-mode kv --http-port 8000
+```
+
+### Kubernetes
+
+```yaml
+# Add DGDR example - use apiVersion: nvidia.com/v1alpha1
+# Example pattern (from Router):
+# apiVersion: nvidia.com/v1alpha1
+# kind: DynamoGraphDeployment
+# metadata:
+#   name: <component>-deployment
+# spec:
+#   services:
+#     ...
+```
+
+<!-- EXAMPLE: Filled-in Quick Start for Router would look like:
+
+### Prerequisites
+
+- Dynamo platform installed
+- At least one backend worker running
+
+### Usage
+
+```bash
+python -m dynamo.frontend --router-mode kv --http-port 8000
+```
+
+### Kubernetes
+
+```yaml
+apiVersion: nvidia.com/v1alpha1
+kind: DynamoGraphDeployment
+metadata:
+  name: router-example
+spec:
+  graphs:
+    - name: frontend
+      replicas: 1
+```
+-->
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| <!-- param --> | <!-- default --> | <!-- description --> |
+
+## Next Steps
+
+| Document | Path | Description |
+|----------|------|-------------|
+| `<Component> Guide` | `<component>_guide.md` | Deployment and configuration |
+| `<Component> Examples` | `<component>_examples.md` | Usage examples |
+| `<Component> Design` | `/docs/design_docs/<component>_design.md` | Architecture |
+
+<!-- Convert table rows to markdown links -->

docs/templates/feature_backend.md

+---
+orphan: true
+---
+
+# <Feature> with <Backend>
+
+Using <Feature> with the <Backend> backend.
+
+## Prerequisites
+
+- <Backend> installed with <feature> support
+- <!-- Other requirements -->
+
+## Configuration
+
+### CLI Arguments
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| <!-- arg --> | <!-- default --> | <!-- description --> |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| <!-- var --> | <!-- default --> | <!-- description --> |
+
+## Examples
+
+### Basic Usage
+
+```python
+# Add example from existing docs
+```
+
+### Kubernetes Deployment
+
+```yaml
+# Add DGDR example from existing docs
+```
+
+## Limitations
+
+- <!-- Backend-specific limitations -->
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| <!-- issue --> | <!-- solution --> |
+
+## See Also
+
+| Document | Path |
+|----------|------|
+| `<Feature> Overview` | `./README.md` |
+| `<Backend> Guide` | `/docs/backends/<backend>/README.md` |
+
+<!-- Convert to links: [Multimodal Overview](./README.md) -->

docs/templates/feature_readme.md

+---
+orphan: true
+---
+
+# <Feature>
+
+<!-- 2-3 sentence overview of this cross-cutting feature -->
+
+## Backend Support
+
+<!-- Copy actual backend support from existing feature docs -->
+<!-- Example pattern (from Multimodal index.md): -->
+
+| Backend | Status | Notes |
+|---------|--------|-------|
+| vLLM | ✅ | Full support |
+| SGLang | ✅ | |
+| TensorRT-LLM | 🚧 | Limited support |
+
+See the Feature Matrix for full compatibility.
+
+## Overview
+
+<!-- How this feature works across backends -->
+
+## Quick Start
+
+<!-- Add minimal example from existing feature docs -->
+
+## Backend-Specific Guides
+
+| Backend | Guide |
+|---------|-------|
+| vLLM | `<feature>_vllm.md` |
+| SGLang | `<feature>_sglang.md` |
+| TensorRT-LLM | `<feature>_trtllm.md` |
+
+<!-- Convert table rows to markdown links -->
+
+## See Also
+
+- <!-- Related features -->
+- <!-- Related components -->

docs/templates/incode_readme.md

+---
+orphan: true
+---
+
+# Dynamo <Component>
+
+<!-- One-sentence description -->
+
+See `docs/components/<component>/` for full documentation.
+
+<!-- When using this template, replace with actual link to component docs.
+     For backends, use: docs/backends/<backend>/
+-->

docs/templates/infrastructure_readme.md

+---
+orphan: true
+---
+
+# <Topic>
+
+<!-- 2-3 sentence overview of this infrastructure topic. -->
+
+## Quick Start
+
+<!-- Minimal steps to get started -->
+
+## Guides
+
+| Guide | Path |
+|-------|------|
+| Guide 1 | `<subtopic1>.md` |
+| Guide 2 | `<subtopic2>.md` |
+
+## Reference
+
+<!-- Links to reference material -->
+
+## See Also
+
+| Topic | Path |
+|-------|------|
+| Related topic 1 | `../related/` |
+| Related topic 2 | `../other/` |

docs/templates/integration_readme.md

+---
+orphan: true
+---
+
+# <Integration> Integration
+
+<!-- 2-3 sentence overview of this external integration -->
+
+## Version Compatibility
+
+| Dynamo | <Integration> | Notes |
+|--------|---------------|-------|
+| 0.9.x | 1.2.x | Recommended |
+| 0.8.x | 1.1.x | |
+
+## Backend Support
+
+| Backend | Status | Notes |
+|---------|--------|-------|
+| vLLM | ✅ | |
+| SGLang | 🚧 | |
+| TensorRT-LLM | ❌ | |
+
+## Quick Start
+
+```bash
+# Add installation and usage from existing integration docs
+# Example pattern (LMCache):
+# python -m dynamo.vllm --model <model> --connector lmcache
+```
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| <!-- param --> | <!-- default --> | <!-- description --> |
+
+## Guides
+
+| Document | Path | Description |
+|----------|------|-------------|
+| `<Integration> Setup` | `<integration>_setup.md` | Installation and configuration |
+| `<Integration> with vLLM` | `<integration>_vllm.md` | vLLM-specific usage |
+
+<!-- Convert table rows to markdown links -->
+
+## External Resources
+
+- [<Integration> Documentation](https://...)
+- [<Integration> GitHub](https://github.com/...)