diff --git a/README.md b/README.md
index 12eaec1040..7eb43039d3 100644
--- a/README.md
+++ b/README.md
@@ -1,202 +1,94 @@
-# CLIProxyAPI++ (KooshaPari Fork)
+# CLIProxyAPI++
 
-This repository works with Claude and other AI agents as autonomous software engineers.
+Agent-native, multi-provider OpenAI-compatible proxy for production and local model routing.
 
-## Quick Start
+## Table of Contents
 
-```bash
-# Docker
-docker run -p 8317:8317 eceasy/cli-proxy-api-plus:latest
+- [Key Features](#key-features)
+- [Architecture](#architecture)
+- [Getting Started](#getting-started)
+- [Operations and Security](#operations-and-security)
+- [Testing and Quality](#testing-and-quality)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
 
-# Or build from source
-go build -o cliproxy ./cmd/cliproxy
-./cliproxy --config config.yaml
+## Key Features
 
-# Health check
-curl http://localhost:8317/health
-```
+- OpenAI-compatible request surface across heterogeneous providers.
+- Unified auth and token handling for OpenAI, Anthropic, Gemini, Kiro, Copilot, and more.
+- Provider-aware routing and model conversion.
+- Built-in operational tooling for management APIs and diagnostics.
 
-## Multi-Provider Routing
+## Architecture
 
-Route OpenAI-compatible requests to any provider:
+- `cmd/server`: primary API server entrypoint.
+- `cmd/cliproxyctl`: operational CLI.
+- `internal/`: runtime/auth/translator internals.
+- `pkg/llmproxy/`: reusable proxy modules.
+- `sdk/`: SDK-facing interfaces.
 
-```bash
-# List models
-curl http://localhost:8317/v1/models
-
-# Chat completion (OpenAI)
-curl -X POST http://localhost:8317/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
-
-# Chat completion (Anthropic)
-curl -X POST http://localhost:8317/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"model": "claude-3-5-sonnet", "messages": [{"role": "user", "content": "Hello"}]}'
-```
+## Getting Started
 
-### Provider Configuration
-
-```yaml
-providers:
-  openai:
-    api_key: ${OPENAI_API_KEY}
-  anthropic:
-    api_key: ${ANTHROPIC_API_KEY}
-  kiro:
-    enabled: true
-  github_copilot:
-    enabled: true
-  ollama:
-    enabled: true
-    base_url: http://localhost:11434
-```
-
-## Supported Providers
-
-| Provider | Auth | Status |
-|----------|------|--------|
-| OpenAI | API Key | ✅ |
-| Anthropic | API Key | ✅ |
-| Azure OpenAI | API Key/OAuth | ✅ |
-| Google Gemini | API Key | ✅ |
-| AWS Bedrock | IAM | ✅ |
-| Kiro (CodeWhisperer) | OAuth | ✅ |
-| GitHub Copilot | OAuth | ✅ |
-| Ollama | Local | ✅ |
-| LM Studio | Local | ✅ |
-
-## Documentation
+### Prerequisites
 
-- `docs/start-here.md` - Getting started guide
-- `docs/provider-usage.md` - Provider configuration
-- `docs/provider-quickstarts.md` - Per-provider guides
-- `docs/api/` - API reference
-- `docs/sdk-usage.md` - SDK guides
+- Go 1.24+
+- Docker (optional)
+- Provider credentials for target upstreams
 
-## Environment
+### Quick Start
 
 ```bash
-export OPENAI_API_KEY="sk-..."
-export ANTHROPIC_API_KEY="sk-..."
-export CLIPROXY_PORT=8317
+go build -o cliproxy ./cmd/server
+./cliproxy --config config.yaml
 ```
 
----
-
-## Development Philosophy
-
-### Extend, Never Duplicate
-
-- NEVER create a v2 file. Refactor the original.
-- NEVER create a new class if an existing one can be made generic.
-- NEVER create custom implementations when an OSS library exists.
-- Before writing ANY new code: search the codebase for existing patterns.
-
-### Primitives First
-
-- Build generic building blocks before application logic.
-- A provider interface + registry is better than N isolated classes.
-- Template strings > hardcoded messages. Config-driven > code-driven.
-
-### Research Before Implementing
-
-- Check pkg.go.dev for existing libraries.
-- Search GitHub for 80%+ implementations to fork/adapt.
-
----
-
-## Library Preferences (DO NOT REINVENT)
+### Docker Quick Start
 
-| Need | Use | NOT |
-|------|-----|-----|
-| HTTP router | chi | custom router |
-| Logging | zerolog | fmt.Print |
-| Config | viper | manual env parsing |
-| Validation | go-playground/validator | manual if/else |
-| Rate limiting | golang.org/x/time/rate | custom limiter |
-
----
-
-## Code Quality Non-Negotiables
-
-- Zero new lint suppressions without inline justification
-- All new code must pass: go fmt, go vet, golint
-- Max function: 40 lines
-- No placeholder TODOs in committed code
-
-### Go-Specific Rules
-
-- Use `go fmt` for formatting
-- Use `go vet` for linting
-- Use `golangci-lint` for comprehensive linting
-- All public APIs must have godoc comments
-
----
-
-## Verifiable Constraints
-
-| Metric | Threshold | Enforcement |
-|--------|-----------|-------------|
-| Tests | 80% coverage | CI gate |
-| Lint | 0 errors | golangci-lint |
-| Security | 0 critical | trivy scan |
-
----
-
-## Domain-Specific Patterns
-
-### What CLIProxyAPI++ Is
-
-CLIProxyAPI++ is an **OpenAI-compatible API gateway** that translates client requests to multiple upstream LLM providers. The core domain is: provide a single API surface that routes to heterogeneous providers with auth, rate limiting, and metrics.
+```bash
+docker run -p 8317:8317 eceasy/cli-proxy-api-plus:latest
+```
 
-### Key Interfaces
+## Operations and Security
 
-| Interface | Responsibility | Location |
-|-----------|---------------|----------|
-| **Router** | Request routing to providers | `pkg/llmproxy/router/` |
-| **Provider** | Provider abstraction | `pkg/llmproxy/providers/` |
-| **Auth** | Credential management | `pkg/llmproxy/auth/` |
-| **Rate Limiter** | Throttling | `pkg/llmproxy/ratelimit/` |
+- Rate limiting and quota/cooldown controls.
+- Auth flows for provider-specific OAuth/API keys.
+- CI policy checks and path guards.
+- Governance and security docs under `docs/operations/` and `docs/reference/`.
 
-### Request Flow
+## Testing and Quality
 
-```
-1. Client Request → Router
-2. Router → Auth Validation
-3. Auth → Provider Selection
-4. Provider → Upstream API
-5. Response ← Provider
-6. Metrics → Response
+```bash
+go test ./...
 ```
 
-### Common Anti-Patterns to Avoid
+Quality gates are enforced via repo CI workflows (build/lint/path guards).
 
-- **Hardcoded provider URLs** -- Use configuration
-- **Blocking on upstream** -- Use timeouts and circuit breakers
-- **No fallbacks** -- Implement provider failover
-- **Missing metrics** -- Always track latency/cost
+## Documentation
 
----
+Primary docs root is `docs/` with a unified category IA:
 
-## Kush Ecosystem
+- `docs/wiki/`
+- `docs/development/`
+- `docs/index/`
+- `docs/api/`
+- `docs/roadmap/`
 
-This project is part of the Kush multi-repo system:
+VitePress docs commands:
 
+```bash
+cd docs
+npm install
+npm run docs:dev
+npm run docs:build
 ```
-kush/
-├── thegent/         # Agent orchestration
-├── agentapi++/      # HTTP API for coding agents
-├── cliproxy++/     # LLM proxy (this repo)
-├── tokenledger/     # Token and cost tracking
-├── 4sgm/           # Python tooling workspace
-├── civ/             # Deterministic simulation
-├── parpour/         # Spec-first planning
-└── pheno-sdk/       # Python SDK
-```
 
----
+## Contributing
+
+1. Create a worktree branch.
+2. Implement and validate changes.
+3. Open a PR with clear scope and migration notes.
 
 ## License
 
-MIT License - see LICENSE file
+MIT License. See `LICENSE`.
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 61e5ca40ff..1bf2f370c6 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -1,91 +1,64 @@
-import { defineConfig } from "vitepress";
-import { contentTabsPlugin } from "./plugins/content-tabs";
-
-const repo = process.env.GITHUB_REPOSITORY?.split("/")[1] ?? "cliproxyapi-plusplus";
-const isCI = process.env.GITHUB_ACTIONS === "true";
-const docsBase = isCI ? `/${repo}/` : "/";
-const faviconHref = `${docsBase}favicon.ico`;
+import { defineConfig } from 'vitepress'
 
 export default defineConfig({
-  title: "cliproxy++",
-  description: "cliproxyapi-plusplus documentation",
-  base: docsBase,
-  head: [
-    ["link", { rel: "icon", href: faviconHref }]
-  ],
+  title: 'CLIProxyAPI++',
+  description: 'CLIProxyAPI++ documentation',
+  srcDir: '.',
+  lastUpdated: true,
   cleanUrls: true,
   ignoreDeadLinks: true,
-  lastUpdated: true,
   themeConfig: {
     nav: [
-      { text: "Home", link: "/" },
-      { text: "Start Here", link: "/start-here" },
-      { text: "Tutorials", link: "/tutorials/" },
-      { text: "How-to", link: "/how-to/" },
-      { text: "Explanation", link: "/explanation/" },
-      { text: "Getting Started", link: "/getting-started" },
-      { text: "Providers", link: "/provider-usage" },
-      { text: "Provider Catalog", link: "/provider-catalog" },
-      { text: "Operations", link: "/operations/" },
-      { text: "Reference", link: "/routing-reference" },
-      { text: "API", link: "/api/" },
-      { text: "Docsets", link: "/docsets/" }
-    ],
-    sidebar: [
-      {
-        text: "Guide",
-        items: [
-          { text: "Overview", link: "/" },
-          { text: "Getting Started", link: "/getting-started" },
-          { text: "Install", link: "/install" },
-          { text: "Provider Usage", link: "/provider-usage" },
-          { text: "Provider Catalog", link: "/provider-catalog" },
-          { text: "Provider Operations", link: "/provider-operations" },
-          { text: "Troubleshooting", link: "/troubleshooting" },
-          { text: "Planning Boards", link: "/planning/" }
-        ]
-      },
-      {
-        text: "Reference",
-        items: [
-          { text: "Routing and Models", link: "/routing-reference" },
-          { text: "Feature Guides", link: "/features/" },
-          { text: "Docsets", link: "/docsets/" }
-        ]
-      },
-      {
-        text: "API",
-        items: [
-          { text: "API Index", link: "/api/" },
-          { text: "OpenAI-Compatible API", link: "/api/openai-compatible" },
-          { text: "Management API", link: "/api/management" },
-          { text: "Operations API", link: "/api/operations" }
-        ]
-      }
+      { text: 'Home', link: '/' },
+      { text: 'Wiki', link: '/wiki/' },
+      { text: 'Development Guide', link: '/development/' },
+      { text: 'Document Index', link: '/index/' },
+      { text: 'API', link: '/api/' },
+      { text: 'Roadmap', link: '/roadmap/' }
     ],
-    search: {
-      provider: "local"
+    sidebar: {
+      '/wiki/': [
+        { text: 'Wiki (User Guides)', items: [
+          { text: 'Overview', link: '/wiki/' }
+        ]}
+      ],
+      '/development/': [
+        { text: 'Development Guide', items: [
+          { text: 'Overview', link: '/development/' }
+        ]}
+      ],
+      '/index/': [
+        { text: 'Document Index', items: [
+          { text: 'Overview', link: '/index/' },
+          { text: 'Raw/All', link: '/index/raw-all' },
+          { text: 'Planning', link: '/index/planning' },
+          { text: 'Specs', link: '/index/specs' },
+          { text: 'Research', link: '/index/research' },
+          { text: 'Worklogs', link: '/index/worklogs' },
+          { text: 'Other', link: '/index/other' }
+        ]}
+      ],
+      '/api/': [
+        { text: 'API', items: [
+          { text: 'Overview', link: '/api/' }
+        ]}
+      ],
+      '/roadmap/': [
+        { text: 'Roadmap', items: [
+          { text: 'Overview', link: '/roadmap/' }
+        ]}
+      ],
+      '/': [
+        { text: 'Quick Links', items: [
+          { text: 'Wiki', link: '/wiki/' },
+          { text: 'Development Guide', link: '/development/' },
+          { text: 'Document Index', link: '/index/' },
+          { text: 'API', link: '/api/' },
+          { text: 'Roadmap', link: '/roadmap/' }
+        ]}
+      ]
     },
-    footer: {
-      message: "MIT Licensed",
-      copyright: "Copyright © KooshaPari"
-    },
-    editLink: {
-      pattern:
-        "https://github.com/kooshapari/cliproxyapi-plusplus/edit/main/docs/:path",
-      text: "Edit this page on GitHub"
-    },
-    outline: {
-      level: [2, 3]
-    },
-    socialLinks: [
-      { icon: "github", link: "https://github.com/kooshapari/cliproxyapi-plusplus" }
-    ]
-  },
-
-  markdown: {
-    config: (md) => {
-      md.use(contentTabsPlugin)
-    }
+    search: { provider: 'local' },
+    socialLinks: [{ icon: 'github', link: 'https://github.com/KooshaPari/cliproxyapi-plusplus' }]
   }
-});
+})
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 33b44e49e1..bcbfb693b6 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -1,40 +1,14 @@
 import DefaultTheme from 'vitepress/theme'
-import { tabsClientScript } from '../plugins/content-tabs'
-
-export default {
-  extends: DefaultTheme,
-  enhanceApp() {
-    if (typeof window === 'undefined') {
-      return
-    }
-
-    // Mermaid rejects CSS variable strings in themeVariables in some builds.
-    // Force plain hex colors to avoid runtime parse failures.
-    const applyMermaidColorFallback = () => {
-      const mermaid = (window as { mermaid?: { initialize?: (cfg: unknown) => void } }).mermaid
-      if (!mermaid || typeof mermaid.initialize !== 'function') {
-        return
-      }
-
-      mermaid.initialize({
-        theme: 'base',
-        themeVariables: {
-          primaryColor: '#3b82f6',
-          primaryBorderColor: '#2563eb',
-          primaryTextColor: '#0f172a',
-          lineColor: '#64748b',
-          textColor: '#0f172a',
-          background: '#ffffff'
-        }
-      })
-    }
-
-    window.setTimeout(applyMermaidColorFallback, 0)
+import type { Theme } from 'vitepress'
+import CategorySwitcher from './components/CategorySwitcher.vue'
+import './custom.css'
+
+const theme: Theme = {
+  ...DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('CategorySwitcher', CategorySwitcher)
   },
-  scripts: [
-    {
-      src: 'data:text/javascript,' + encodeURIComponent(tabsClientScript),
-      type: 'text/javascript',
-    },
-  ],
+  Layout: DefaultTheme.Layout
 }
+
+export default theme
diff --git a/docs/api/index.md b/docs/api/index.md
index 7290c4ca8b..026dfac8a8 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -1,50 +1,7 @@
-# API Index
+# API
 
-`cliproxyapi++` exposes three practical API surfaces: client-compatible runtime APIs, management APIs, and operational APIs.
+API references and SDK documentation index.
 
-## Audience Guidance
-
-- Application teams: start with [OpenAI-Compatible API](./openai-compatible.md).
-- Platform ops/SRE: add [Operations API](./operations.md) checks.
-- Admin tooling: use [Management API](./management.md) with strict access control.
-
-## 1) OpenAI-Compatible API (`/v1/*`)
-
-Common endpoints:
-
-- `POST /v1/chat/completions`
-- `POST /v1/completions`
-- `GET /v1/models`
-- `POST /v1/responses`
-- `GET /v1/responses` (websocket bootstrap path)
-
-Use when integrating existing OpenAI-style clients with minimal client changes.
-
-## 2) Management API (`/v0/management/*`)
-
-Use for runtime administration, config/auth inspection, and service controls.
-
-Important: if `remote-management.secret-key` is empty, this surface is disabled.
-
-## 3) Operations API
-
-Operational endpoints include health and metrics surfaces used for monitoring and triage.
-
-- `GET /health`
-- `GET /v1/metrics/providers`
-
-## Quick Curl Starter
-
-```bash
-# OpenAI-compatible request
-curl -sS -X POST http://localhost:8317/v1/chat/completions \
-  -H "Authorization: Bearer <client-api-key>" \
-  -H "Content-Type: application/json" \
-  -d '{"model":"claude-3-5-sonnet","messages":[{"role":"user","content":"hello"}]}'
-```
-
-## Next
-
-- [OpenAI-Compatible API](./openai-compatible.md)
-- [Management API](./management.md)
-- [Operations API](./operations.md)
+- OpenAPI/Swagger artifacts
+- SDK references
+- Endpoint guides
diff --git a/docs/index.md b/docs/index.md
index fe0f7a8342..1b1e52fa5a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,84 +1,13 @@
----
-layout: home
+# CLIProxyAPI++
 
-hero:
-  name: cliproxyapi++
-  text: OpenAI-Compatible Multi-Provider Gateway
-  tagline: One API surface for routing across heterogeneous model providers
-  actions:
-    - theme: brand
-      text: Start Here
-      link: /start-here
-    - theme: alt
-      text: API Index
-      link: /api/
+<CategorySwitcher />
 
-features:
-  - title: Provider Routing
-    details: Unified `/v1/*` compatibility across multiple upstream providers
-  - title: Operations Ready
-    details: Health, metrics, and management endpoints for runtime control
-  - title: Structured Docs
-    details: Start Here, Tutorials, How-to, Reference, Explanation, and API lanes
----
+Welcome to the unified docs surface.
 
-# cliproxyapi++ Docs
+## Super Categories
 
-`cliproxyapi++` is an OpenAI-compatible proxy that routes one client API surface to multiple upstream providers.
-
-## Who This Documentation Is For
-
-- Operators running a shared internal LLM gateway.
-- Platform engineers integrating existing OpenAI-compatible clients.
-- Developers embedding cliproxyapi++ in Go services.
-- Incident responders who need health, logs, and management endpoints.
-
-## What You Can Do
-
-- Use one endpoint (`/v1/*`) across heterogeneous providers.
-- Configure routing and model-prefix behavior in `config.yaml`.
-- Manage credentials and runtime controls through management APIs.
-- Monitor health and per-provider metrics for operations.
-
-## Start Here
-
-1. [Getting Started](/getting-started) for first run and first request.
-2. [Install](/install) for Docker, binary, and source options.
-3. [Provider Usage](/provider-usage) for provider strategy and setup patterns.
-4. [Provider Quickstarts](/provider-quickstarts) for provider-specific 5-minute success paths.
-5. [Provider Catalog](/provider-catalog) for provider block reference.
-6. [Provider Operations](/provider-operations) for on-call runbook and incident workflows.
-7. [Routing and Models Reference](/routing-reference) for model resolution behavior.
-8. [Troubleshooting](/troubleshooting) for common failures and concrete fixes.
-9. [Planning Boards](/planning/) for source-linked execution tracking and import-ready board artifacts.
-
-## API Surfaces
-
-- [API Index](/api/) for endpoint map and when to use each surface.
-- [OpenAI-Compatible API](/api/openai-compatible) for `/v1/*` request patterns.
-- [Management API](/api/management) for runtime inspection and control.
-- [Operations API](/api/operations) for health and operational workflows.
-
-## Audience-Specific Guides
-
-- [Docsets](/docsets/) for user, developer, and agent-focused guidance.
-- [Feature Guides](/features/) for deeper behavior and implementation notes.
-- [Planning Boards](/planning/) for source-to-solution mapping across issues, PRs, discussions, and external requests.
-
-## Fast Verification Commands
-
-```bash
-# Basic process health
-curl -sS http://localhost:8317/health
-
-# List models exposed by your current auth + config
-curl -sS http://localhost:8317/v1/models | jq '.data[:5]'
-
-# Check provider-side rolling stats
-curl -sS http://localhost:8317/v1/metrics/providers | jq
-```
-
-## Project Links
-
-- [Main Repository README](https://github.com/KooshaPari/cliproxyapi-plusplus/blob/main/README.md)
-- [Feature Changes in ++](./FEATURE_CHANGES_PLUSPLUS.md)
+- [Wiki (User Guides)](/wiki/)
+- [Development Guide](/development/)
+- [Document Index](/index/)
+- [API](/api/)
+- [Roadmap](/roadmap/)