Add Claude Code Router + Codex CLI features, extract dashboard, restructure docs

Container:
- Add claude-code-router feature for LLM provider routing (DeepSeek, Gemini, OpenRouter)
- Add codex-cli feature for OpenAI Codex terminal agent
- Add defaults/ directory with factory config templates
- Update ccusage feature with Codex support
- Update auth scripts for new provider API keys

Dashboard:
- Extract dashboard/ to separate CodeDirective repository
- Add dashboard/ to .gitignore (deprecated in monorepo)

Documentation:
- Restructure docs: getting-started → start-here, features/customization → use/customize
- Move plugins/ under extend/ section
- Add new reference pages: agents, skills, cli-tools, environment-variables
- Consolidate architecture and troubleshooting in reference/

Housekeeping:
- Gitignore temp directories and screenshots

Author: claude

.gitignore

@@ -20,6 +20,12 @@ coverage/
 *.swp
 *.swo
 *~
+TEMP/
+temp/
+tmp/
+
+# Screenshots
+*.png
 
 # IDE
 .vscode/
@@ -60,10 +66,8 @@ cli/.pytest_cache/
 cli/.ruff_cache/
 .codeforge/data/
 
-# Dashboard-specific
-dashboard/.svelte-kit/
-dashboard/build/
-dashboard/mockups/
+# Dashboard (deprecated — migrating to CodeDirective, a separate repo)
+dashboard/
 
 # Docs-specific
 docs/.astro/

CLAUDE.md

@@ -1,6 +1,6 @@
 # CodeForge Monorepo
 
-This repository contains four packages. Each package manages its own dependencies independently.
+This repository contains three packages. Each package manages its own dependencies independently.
 
 ## Packages
 
@@ -9,7 +9,11 @@ This repository contains four packages. Each package manages its own dependencie
 | `container/` | Node.js | npm |
 | `cli/` | Bun | bun |
 | `docs/` | Node.js | npm |
-| `dashboard/` | Bun | npm (frontend) / bun (server) |
+
+> **Dashboard → CodeDirective**: The `dashboard/` package is deprecated and being
+> extracted to its own repository as **CodeDirective** — an independent app. It is
+> gitignored and will be removed from this repo. Do not add dashboard dependencies
+> or make cross-package changes involving dashboard code.
 
 ## Development Rules
 
@@ -27,8 +31,6 @@ Each package has its own `CLAUDE.md` with package-specific development rules:
 - [`container/CLAUDE.md`](container/CLAUDE.md) — changelog, documentation, and configuration rules for the devcontainer package
 - `cli/` — Bun/TypeScript CLI; run `bun test` for tests
 - `docs/` — Astro/Starlight site; run `npm run build` to verify
-- [`dashboard/CLAUDE.md`](dashboard/CLAUDE.md) | [`dashboard/README.md`](dashboard/README.md) — Svelte 5 SPA + Bun backend for session analytics
-
 ### Cross-Package Changes
 
 When a change spans multiple packages, make the changes in a single branch and PR.
@@ -41,21 +43,3 @@ Run tests for each affected package before committing:
 - **Container**: `cd container && npm test`
 - **CLI**: `cd cli && bun test`
 - **Docs**: `cd docs && npm run build`
-- **Dashboard**: `cd dashboard && bun test`
-
-### Dashboard vs CLI
-
-The `dashboard/` and `cli/` packages serve different audiences:
-
-- **CLI** (`codeforge` command) — terminal-first, text/JSON output, scriptable,
-  runs inside or outside the container. Features: session search, task search/list/show,
-  plan search, plugin management, index/config commands.
-- **Dashboard** (Svelte 5 SPA) — visual analytics, charts, expandable detail views,
-  real-time SSE updates. Features: session browsing with conversation replay,
-  task/plan/agent/memory views, project analytics, cost tracking.
-
-When adding a new data view:
-- If it's browsable/visual (tables, charts, detail drill-down) → dashboard
-- If it's scriptable/automatable (piped output, filters, JSON) → CLI
-- If it's both → implement in both, but don't import CLI as a dashboard dependency.
-  Fork patterns instead.

container/.codeforge/config/claude-code-router.json

@@ -0,0 +1,24 @@
+{
+	"mcpServers": {},
+	"providers": {
+		"anthropic": {
+			"api_key": "$ANTHROPIC_API_KEY",
+			"base_url": "https://api.anthropic.com"
+		},
+		"deepseek": {
+			"api_key": "$DEEPSEEK_API_KEY",
+			"base_url": "https://api.deepseek.com"
+		},
+		"gemini": {
+			"api_key": "$GEMINI_API_KEY",
+			"base_url": "https://generativelanguage.googleapis.com"
+		},
+		"openrouter": {
+			"api_key": "$OPENROUTER_API_KEY",
+			"base_url": "https://openrouter.ai/api"
+		}
+	},
+	"router": {
+		"default": "anthropic/claude-sonnet-4-20250514"
+	}
+}

container/.codeforge/config/codex-config.toml

@@ -0,0 +1,23 @@
+# Codex CLI Configuration
+# This file is deployed to ~/.codex/config.toml on container start.
+# See https://github.com/openai/codex for full documentation.
+
+# Credential storage backend: "file" | "keyring" | "auto" | "ephemeral"
+# "file" stores credentials in ~/.codex/auth.json (recommended for containers)
+cli_auth_credentials_store = "file"
+
+# Sandbox mode: "read-only" | "workspace-write" | "danger-full-access"
+# sandbox_mode = "workspace-write"
+
+# Default model
+# model = "codex-mini-latest"
+
+# Web search: "disabled" | "cached" | "live"
+# web_search = "live"
+
+# Custom model providers (uncomment and configure as needed)
+# [model_providers.custom]
+# name = "Custom Provider"
+# base_url = "https://api.example.com"
+# env_key = "CUSTOM_API_KEY"
+# wire_api = "responses"

container/.codeforge/config/settings.json

@@ -4,24 +4,23 @@
 	"autoCompact": true,
 	"alwaysThinkingEnabled": true,
 	"env": {
-		"ANTHROPIC_MODEL": "claude-opus-4-6[1m]",
-		"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6[1m]",
+		"ANTHROPIC_MODEL": "claude-opus-4-5",
+		"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-5",
 		"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
 		"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
 		"BASH_DEFAULT_TIMEOUT_MS": "120000",
 		"BASH_MAX_TIMEOUT_MS": "300000",
 		"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000",
 		"MAX_MCP_OUTPUT_TOKENS": "10000",
 		"MAX_THINKING_TOKENS": "63999",
+		"CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1",
 		"MCP_TIMEOUT": "120000",
 		"MCP_TOOL_TIMEOUT": "30000",
 		"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "90",
-		"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "500000",
 		"FORCE_AUTOUPDATE_PLUGINS": "1",
 
 		"ENABLE_TOOL_SEARCH": "auto:5",
 		"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
-		"CLAUDE_CODE_EFFORT_LEVEL": "high",
 		"CLAUDE_CODE_ENABLE_TASKS": "true",
 		"CLAUDE_CODE_DISABLE_AUTO_MEMORY": "0",
 		"ENABLE_CLAUDE_CODE_SM_COMPACT": "1",
@@ -30,6 +29,9 @@
 		"CLAUDE_CODE_PLAN_V2_AGENT_COUNT": "5",
 		"CLAUDE_CODE_PLAN_MODE_REQUIRED": "true",
 		"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "true",
+		"CLAUDE_AUTO_BACKGROUND_TASKS": "1",
+		"CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION": "false",
+		"CLAUDE_CODE_NO_FLICKER": "1",
 
 		"CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY": "10",
 		"CLAUDE_CODE_MAX_RETRIES": "1",
@@ -38,16 +40,55 @@
 		"DISABLE_AUTOUPDATER": "1"
 	},
 	"teammateMode": "auto",
-	"effortLevel": "high",
+	"effortLevel": "max",
+	"showClearContextOnPlanAccept": true,
+	"showThinkingSummaries": true,
 	"includeCoAuthoredBy": false,
+	"spinnerVerbs": {
+		"mode": "replace",
+		"verbs": [
+			"Butchering",
+			"Mangling",
+			"Wrecking",
+			"Botching",
+			"Misreading",
+			"Derailing",
+			"Overcomplicating",
+			"Hallucinating",
+			"Breaking",
+			"Fumbling",
+			"Sabotaging",
+			"Shredding",
+			"Confusing",
+			"Corrupting",
+			"Ruining",
+			"Winging",
+			"Guessing",
+			"Misinterpreting",
+			"Overengineering",
+			"Improvising Poorly",
+			"Making It Worse",
+			"Massacring",
+			"Mutilating",
+			"Annihilating",
+			"Trashing",
+			"Destroying",
+			"Misfiring",
+			"Ignoring",
+			"Unthinking",
+			"Wondering",
+			"Draining",
+			"Exhausting",
+			"Petering Out"
+		]
+	},
 	"permissions": {
 		"allow": ["Read(/workspaces/*)", "WebFetch(domain:*)"],
 		"deny": [],
 		"ask": [],
 		"defaultMode": "plan",
 		"additionalDirectories": []
 	},
-	"model": "opus[1m]",
 	"enabledMcpjsonServers": [],
 	"disabledMcpjsonServers": [],
 	"hooks": {},

container/.codeforge/file-manifest.json

@@ -20,7 +20,7 @@
 	{
 		"src": "config/rules/spec-workflow.md",
 		"dest": "${CLAUDE_CONFIG_DIR}/rules",
-		"enabled": true,
+		"enabled": false,
 		"overwrite": "if-changed"
 	},
 	{
@@ -66,5 +66,19 @@
 		"dest": "${CLAUDE_CONFIG_DIR}",
 		"enabled": false,
 		"overwrite": "never"
+	},
+	{
+		"src": "config/codex-config.toml",
+		"dest": "${HOME}/.codex",
+		"destFilename": "config.toml",
+		"enabled": true,
+		"overwrite": "if-changed"
+	},
+	{
+		"src": "config/claude-code-router.json",
+		"dest": "${HOME}/.claude-code-router",
+		"destFilename": "config.json",
+		"enabled": true,
+		"overwrite": "if-changed"
 	}
 ]

container/.devcontainer/.secrets.example

@@ -13,3 +13,13 @@ NPM_TOKEN=
 
 # Claude long-lived auth token (from 'claude setup-token')
 CLAUDE_AUTH_TOKEN=
+
+# OpenAI API key for Codex CLI
+OPENAI_API_KEY=
+
+# Claude Code Router — provider API keys (set the ones you use)
+# See https://github.com/musistudio/claude-code-router for provider docs
+ANTHROPIC_API_KEY=
+DEEPSEEK_API_KEY=
+GEMINI_API_KEY=
+OPENROUTER_API_KEY=

container/.devcontainer/CHANGELOG.md

@@ -1,5 +1,37 @@
 # CodeForge Devcontainer Changelog
 
+## v2.2.0 — 2026-04-11
+
+### Claude Code Router
+
+- **New feature: `claude-code-router`** — installs claude-code-router proxy daemon for routing Claude Code API calls to alternate LLM providers (DeepSeek, Gemini, OpenRouter, Anthropic). Default-on with autostart. Supports version pinning (`latest`, semver, or `none` to disable).
+- **Router configuration** — user-editable `claude-code-router.json` in `.codeforge/config/` deploys to `~/.claude-code-router/config.json` via file manifest. Uses `$ENV_VAR` interpolation for API keys.
+- **Provider API keys** — `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` support in `.secrets` file and Codespaces secrets.
+- **Daemon supervision** — poststart hook with restart-on-failure wrapper; health gate skips autostart if no provider keys configured.
+- **Quick redeploy** — `ccr-apply` alias redeploys config and restarts daemon in one command.
+
+### Codex CLI
+
+- **New feature: `codex-cli`** — installs OpenAI Codex CLI terminal coding agent via npm. Supports version pinning (`latest`, semver, or `none` to disable). Enabled by default.
+- **Codex authentication** — `OPENAI_API_KEY` support in `.secrets` file and Codespaces secrets. Auto-creates `~/.codex/auth.json` on container start. Browser-based ChatGPT OAuth also supported interactively.
+- **Codex config management** — user-editable `codex-config.toml` in `.codeforge/config/` deploys to `~/.codex/config.toml` via file manifest
+- **Codex persistence** — separate Docker named volume (`codeforge-codex-config-${devcontainerId}`) for `~/.codex/`, surviving container rebuilds
+- **ccusage Codex support** — `ccusage-codex` alias installed alongside `ccusage` for Codex session token and cost tracking via `@ccusage/codex`
+- **Tool enumeration** — `codex` and `ccusage-codex` added to `cc-tools` and `check-setup` output
+
+### Dashboard
+
+- **Dashboard extracted to separate repository** — the `dashboard/` package is deprecated and being moved to its own repo as **CodeDirective**. Dashboard is now gitignored in the monorepo. The devcontainer feature continues to install from the published npm package.
+
+### Documentation
+
+- **Complete docs restructure** — reorganized documentation site for clearer navigation:
+  - `getting-started/` → `start-here/` (installation, first session, migration)
+  - `features/` + `customization/` → `use/` + `customize/` (daily usage vs. configuration)
+  - `plugins/` → `extend/plugins/` (extension points under a dedicated section)
+  - New `reference/` section consolidates agents, skills, CLI tools, environment variables, and architecture
+- Added new reference pages: `agents.md`, `skills.md`, `cli-tools.md`, `environment-variables.md`, `whats-included.md`
+
 ## v2.1.1 — 2026-03-27
 
 ### CLI

container/.devcontainer/CLAUDE.md

@@ -11,6 +11,7 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 | `.codeforge/config/orchestrator-system-prompt.md` | Orchestrator mode prompt (delegation-first) |
 | `.codeforge/config/ccstatusline-settings.json` | Status bar widget layout (deployed to ~/.config/ccstatusline/) |
 | `.codeforge/config/disabled-hooks.json` | Disable individual plugin hooks by script name |
+| `.codeforge/config/claude-code-router.json` | LLM provider routing config (deployed to ~/.claude-code-router/) |
 | `.codeforge/file-manifest.json` | Controls which config files deploy and when |
 | `devcontainer.json` | Container definition: image, features, mounts |
 | `.env` | Boolean flags controlling setup steps |
@@ -26,8 +27,11 @@ Config files deploy via `.codeforge/file-manifest.json` on every container start
 | `ccraw` | Vanilla Claude Code (bypasses config) |
 | `ccw` | Claude Code with writing system prompt |
 | `cc-orc` | Claude Code in orchestrator mode (delegation-first) |
+| `codex` | OpenAI Codex CLI terminal coding agent |
 | `ccms` | Session history search _(disabled — requires Rust toolchain; uncomment in devcontainer.json to enable)_ |
 | `codeforge proxy` | Launch Claude Code through mitmproxy — inspect API traffic in browser (port 8081) |
+| `ccr start` / `ccr stop` | Claude Code Router daemon control |
+| `ccr-apply` | Redeploy router config + restart daemon |
 | `ccusage` / `ccburn` | Token usage analysis / burn rate |
 | `agent-browser` | Headless Chromium (Playwright-based) |
 | `check-setup` | Verify CodeForge setup health |
@@ -71,6 +75,10 @@ The `~/.claude/` directory is backed by a Docker named volume (`codeforge-claude
 
 **Token authentication:** Set `CLAUDE_AUTH_TOKEN` in `.devcontainer/.secrets` (or as a Codespaces secret) with a long-lived token from `claude setup-token`. On container start, `setup-auth.sh` auto-creates `~/.claude/.credentials.json` with `600` permissions. If `.credentials.json` already exists, token injection is skipped (idempotent). Tokens must match `sk-ant-*` format.
 
+Codex CLI credentials (`~/.codex/`) are backed by a separate Docker named volume (`codeforge-codex-config-${devcontainerId}`). Set `OPENAI_API_KEY` in `.devcontainer/.secrets` (or as a Codespaces secret) for automatic API key injection, or run `codex` interactively for browser-based ChatGPT OAuth.
+
+**Claude Code Router:** Set provider API keys (`ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`) in `.devcontainer/.secrets`. Keys are exported as env vars on container start and read at runtime by the router's `$ENV_VAR` interpolation in `~/.claude-code-router/config.json`. Edit routing rules in `.codeforge/config/claude-code-router.json` and run `ccr-apply` to redeploy.
+
 ## Modifying Behavior
 
 1. **Change model**: Edit `.codeforge/config/settings.json` → `"model"` field