codeforge-dev 1.14.1 → 2.0.0

package/.devcontainer/CHANGELOG.md

@@ -1,18 +1,266 @@
 # CodeForge Devcontainer Changelog
 
-## [v1.14.1] - 2026-02-24
+## [Unreleased]
+
+### Changed
+
+#### Port Forwarding
+- Dynamic port forwarding for all ports in VS Code — previously only port 7847 was statically forwarded; now all ports auto-forward with notification
+
+#### Documentation
+- Updated prerequisites and installation docs to support all DevContainer clients (VS Code, CLI, JetBrains Gateway, DevPod, Codespaces)
+- Added tabbed client-specific instructions on the installation page
+- Added dedicated port forwarding reference page covering VS Code auto-detect, devcontainer-bridge, and SSH tunneling
+- **Ported `.devcontainer/docs/` to docs site** — migrated content from 5 legacy reference docs into the Starlight documentation site:
+  - New **Keybindings** page (Customization) — VS Code/Claude Code shortcut conflicts and resolution options
+  - New **Troubleshooting** page (Reference) — 12+ problem/solution entries for build, auth, plugins, and performance issues
+  - New **Optional Features** page (Customization) — mcp-qdrant vector memory setup guide
+  - Merged setup variables (`.env` flags) into the Environment Variables reference
+  - Merged `.secrets` file authentication docs into the Configuration page
+- Removed `.devcontainer/docs/` directory — all content now lives in the docs site
+
+### Fixed
+
+#### Session Context Plugin
+- **Commit reminder** no longer blocks Claude from stopping — switched from `decision: "block"` to advisory `systemMessage` wrapped in `<system-reminder>` tags
+- **Commit reminder** now uses tiered logic: meaningful changes (3+ files, 2+ source files, or test files) get an advisory suggestion; small changes are silent
+- **Commit reminder** only fires when the session actually modified files (via new PostToolUse edit tracker), preventing false reminders during read-only sessions
+
+#### Auto Code Quality Plugin
+- **Advisory test runner** now reads from the correct tmp file prefix (`claude-cq-edited` instead of `claude-edited-files`), fixing a mismatch that prevented it from ever finding edited files
+
+#### Docs
+- Removed stale merge conflict marker in first-session docs page
+
+### Added
+
+#### Startup
+- **Container runtime pre-flight check** — validates Docker or Podman is installed and running before attempting to build the devcontainer; aborts with OS-specific remediation guidance (Windows/WSL, macOS, Linux) instead of a cryptic Docker client error
+
+#### README
+- **"Why CodeForge?" section** — motivation and value proposition explaining the project's origins as a power user's personal setup
+- **Architecture overview** — three-layer diagram (DevContainer → CodeForge Layer → Claude Code) with brief descriptions and link to full architecture docs
+- **Configuration summary** — table of key config files with links to the documentation site
+
+#### Public Repo Quality
+- **CI workflow** (`.github/workflows/ci.yml`) — test and lint jobs on PRs and pushes to main (Node 18, `npm test` + Biome check)
+- **CodeQL security analysis** (`.github/workflows/codeql.yml`) — JavaScript scanning on PRs, pushes, and weekly schedule
+- **Dependabot** (`.github/dependabot.yml`) — weekly updates for npm (root + docs) and GitHub Actions
+- **Bug report template** (`.github/ISSUE_TEMPLATE/bug-report.yml`) — YAML form with version, environment, and repro steps
+- **Feature request template** (`.github/ISSUE_TEMPLATE/feature-request.yml`) — YAML form with problem/solution/alternatives
+- **Issue template config** (`.github/ISSUE_TEMPLATE/config.yml`) — commercial licensing contact link
+- **Pull request template** (`.github/pull_request_template.md`) — description, type of change, and checklist
+- **CONTRIBUTING.md** — contribution guidelines with GPL-3.0 licensing and CLA requirement
+- **CLA.md** — Individual Contributor License Agreement enabling dual licensing
+- **Dual licensing notice** — added to README.md (Contributing + License sections) and LICENSE.txt (header)
+- **CI badge** — added to README.md badge row
+- **SPDX copyright headers** — `GPL-3.0-only` identifier and `Copyright (c) 2026 Marcus Krueger` added to all 36 source files (setup.js, test.js, 34 shell scripts)
+
+#### Docs
+- **CLAUDE.md** — new "Status Bar Widgets" section documenting widget properties, token color conventions, label fusion pattern, and available widget types
+
+#### Skills
+- **worktree** — New skill for git worktree creation, management, and cleanup. Covers `EnterWorktree` tool, `--worktree` CLI flag, `.worktreeinclude` setup, worktree naming conventions, cleanup lifecycle, and CodeForge integration (Project Manager auto-detection, agent isolation). Includes two reference files: manual worktree commands and parallel workflow patterns.
+
+#### Claude Code Installation
+- **Post-start onboarding hook** (`99-claude-onboarding.sh`) — ensures `hasCompletedOnboarding: true` in `.claude.json` when token auth is configured; catches overwrites from Claude Code CLI/extension that race with `postStartCommand`
+
+#### Git Workflow Plugin
+- **`/ship`** — Combined commit/push/PR command with full code review, commit message approval, and AskUserQuestion confirmation before PR creation; optionally links to tickets if context exists
+- **`/pr:review`** — Review any PR by number/URL or auto-detect from current branch; posts findings as PR comment with severity ratings; never approves or merges
+
+#### Features
+- **devcontainer-bridge (dbr)** — Ports opened inside the container are now automatically discovered and forwarded to the host, even outside VS Code. Requires `dbr host-daemon` running on the host. See [devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge)
+
+#### Orchestrator Mode
+- **`cc-orc` alias** — new Claude Code entry point using `orchestrator-system-prompt.md` for delegation-first operation; orchestrator decomposes tasks, delegates to agents, surfaces questions, and synthesizes results without performing direct implementation work
+- **`orchestrator-system-prompt.md`** — slim system prompt (~250 lines) containing only delegation model, agent catalog, question surfacing protocol, planning gates, spec enforcement, and action safety; all code standards, testing standards, and implementation details live in agent prompts
+
+#### Workhorse Agents
+- **`investigator`** — consolidated read-only research agent (sonnet) merging the domains of researcher, explorer, dependency-analyst, git-archaeologist, debug-logs, and perf-profiler; handles codebase search, web research, git forensics, dependency auditing, log analysis, and performance profiling
+- **`implementer`** — consolidated read-write implementation agent (opus, worktree) merging generalist, refactorer, and migrator; handles all code modifications with embedded code standards, execution discipline, and Stop hook regression testing
+- **`tester`** — enhanced test agent (opus, worktree) with full testing standards, framework-specific guidance, and Stop hook verification; creates and verifies test suites
+- **`documenter`** — consolidated documentation and specification agent (opus) merging doc-writer and spec-writer; handles README, API docs, docstrings, and the full spec lifecycle (create, refine, build, review, update, check)
+- **Question Surfacing Protocol** — all 4 workhorse agents carry an identical protocol requiring them to STOP and return `## BLOCKED: Questions` sections when hitting ambiguities, ensuring no assumptions are made without user input
+
+### Fixed
+
+#### CCStatusLine Deployment
+- **`CONFIG_SOURCE_DIR` deprecation guard** — `setup.sh` now detects stale `CONFIG_SOURCE_DIR=/workspaces/.claude` in `.env`, overrides to `$DEVCONTAINER_DIR/config`, and auto-comments the line on disk; the wrong path caused `setup-config.sh` to skip the file manifest entirely, leaving ccstatusline (and all manifest-based configs) undeployed
+- **System template directory permissions** — `install.sh` now chowns `/usr/local/share/ccstatusline/` to the target user so `setup-config.sh` can write the template file during post-start
+- **Silent copy failures** — `setup-config.sh` now reports warnings when file deployment fails instead of logging success after a failed `cp`
+
+#### Post-Integration Review Fixes
+- **skill-engine** — worktree skill definition uses weighted tuples (was plain strings, caused crash)
+- **dangerous-command-blocker** — fail closed on unexpected exceptions (was fail-open)
+- **ticket-workflow** — remove redundant `ValueError` from exception handlers
+- **workspace-scope-guard** — use maxsplit in variable assignment detection
+- **Shell scripts** — add executable bit to `check-setup.sh`, quote `PLUGIN_BLACKLIST` variable, add `set -uo pipefail` to tmux installer, replace deprecated `which` with `command -v`, normalize `&>` redirects in setup scripts
+- **Documentation** — update agent count to 21, skill count to 38, plugin count to 14 across all docs site pages
+- **Documentation** — add missing plugin pages for git-workflow and prompt-snippets
+- **Documentation** — add `cc-orc` and `dbr` to commands reference
+- **Documentation** — remove merge conflict marker from first-session.md
+- **Documentation** — update architecture.md directory tree with new plugins
+
+#### CodeRabbit Review Fixes
+- **`implementer.md`** — changed PostToolUse hook (fires every Edit) to Stop hook (fires once at task end) with 120s timeout; prevents redundant test runs during multi-file tasks
+- **`tester.md`** — increased Stop hook timeout from 30s to 120s to accommodate larger test suites
+- **`setup-aliases.sh`** — added `cc-orc` to `cc-tools` discovery loop so it appears in tool audit
+- **`CLAUDE.md`** — added missing `keybindings.json`, `orchestrator-system-prompt.md`, and `writing-system-prompt.md` to directory structure tree
+- **`agent-system/README.md`** — updated `verify-no-regression.py` comment to list both consumers (implementer, refactorer); hyphenated "question-surfacing protocol"
+- **`orchestrator-system-prompt.md`** — clarified plan mode allows investigator delegation for research; added catch-all entry in selection criteria pointing to the full specialist catalog
+- **MD040 compliance** — added `text` language specifiers to 7 fenced code blocks across `investigator.md`, `tester.md`, and `documenter.md`
+- **`setup.js` path traversal** — `configApply()` now validates that source paths resolve within `.codeforge/` and destination paths resolve within allowed directories (`CLAUDE_CONFIG_DIR`, `HOME`, `/usr/local/`), preventing directory traversal via `../` in manifest entries
+- **`setup.sh` CODEFORGE_DIR** — deprecation guard now uses default-assignment semantics (`:=`) instead of unconditional overwrite, preserving any user-defined `CODEFORGE_DIR` from `.env`
+- **Docs site URLs** — replaced `anexileddev.github.io/CodeForge/` with custom domain `codeforge.core-directive.com/` across README.md, CLAUDE.md, and .devcontainer/README.md
+- **Architecture docs** — added `.checksums/` and `.markers/` directories to the `.codeforge/` tree in architecture.md
+- **Troubleshooting docs** — renamed "Reset to Defaults" to "How to Reset" and clarified that `--reset` preserves `.codeforge/` user modifications; added step for restoring default config sources
+
+### Changed
+
+#### Skill Engine: Auto-Suggestion
+- **Weighted scoring** — Skill suggestion phrases now carry confidence weights (0.0–1.0) instead of binary match/no-match. Specific phrases like "build a fastapi app" score 1.0; ambiguous phrases like "start building" score 0.2
+- **Negative patterns** — Skills can define substrings that instantly disqualify them. Prevents `fastapi` from triggering when discussing `pydantic-ai`, and `docker` from triggering for `docker-py` prompts
+- **Context guards** — Low-confidence matches (score < 0.6) require a confirming context word elsewhere in the prompt. "health check" only suggests `docker` if "docker", "container", or "compose" also appears
+- **Ranked results, capped at 3** — Suggestions are sorted by score (then priority tier), and only the top 3 are returned. Eliminates 6+ skill suggestion floods
+- **Priority tiers** — Explicit commands (priority 10) outrank technology skills (7), which outrank patterns (5) and generic skills (3) when scores tie
+
+#### Claude Code Installation
+- **Claude Code now installs as a native binary** — uses Anthropic's official installer (`https://claude.ai/install.sh`) via new `./features/claude-code-native` feature, replacing the npm-based `ghcr.io/anthropics/devcontainer-features/claude-code:1.0.5`
+- **In-session auto-updater now works without root** — native binary at `~/.local/bin/claude` is owned by the container user, so `claude update` succeeds without permission issues
+
+#### System Prompt
+- **`<git_worktrees>` section** — Updated to document Claude Code native worktree convention (`<repo>/.claude/worktrees/`) as the recommended approach alongside the legacy `.worktrees/` convention. Added `EnterWorktree` tool guidance, `.worktreeinclude` file documentation, and path convention comparison table.
+
+#### Configuration
+- Moved `.claude` directory from `/workspaces/.claude` to `~/.claude` (home directory)
+- Added Docker named volume for persistence across rebuilds (per-instance isolation via `${devcontainerId}`)
+- `CLAUDE_CONFIG_DIR` now defaults to `~/.claude`
+- `file-manifest.json` — added deployment entry for `orchestrator-system-prompt.md`
+- `setup-aliases.sh` — added `cc-orc` alias alongside existing `cc`, `claude`, `ccw`, `ccraw`
+- `CLAUDE.md` — documented `cc-orc` command and orchestrator system prompt in key configuration table
+
+#### Agent System
+- Agent count increased from 17 to 21 (4 workhorse + 17 specialist)
+- Agent-system README updated with workhorse agent table, per-agent hooks for implementer and tester, and updated plugin structure
+
+#### Authentication
+- Added `CLAUDE_AUTH_TOKEN` support in `.secrets` for long-lived tokens from `claude setup-token`
+- Auto-creates `.credentials.json` from token on container start (skips if already exists)
+- Added `CLAUDE_AUTH_TOKEN` to devcontainer.json secrets declaration
+
+#### Security
+- Protected-files-guard now blocks modifications to `.credentials.json`
+- Replaced `eval` tilde expansion with `getent passwd` lookup across all scripts (prevents shell injection via `SUDO_USER`/`USER`)
+- Auth token value is now JSON-escaped before writing to `.credentials.json`
+- Credential directory created with restrictive umask (700) matching credential file permissions (600)
+
+#### Status Bar
+- **ccstatusline line 1** — distinct background colors for each token widget (blue=input, magenta=output, yellow=cached, green=total), bold 2-char labels (In, Ou, Ca, Tt) fused to data widgets, `rawValue: true` on model widget to strip "Model:" prefix, restored spacing between token segments
+
+#### Scripts
+- Replaced `setup-symlink-claude.sh` with `setup-migrate-claude.sh` (one-time migration)
+- Auto-migrates from `/workspaces/.claude/` if `.credentials.json` present
+- `chown` in mcp-qdrant poststart hooks now uses resolved `_USERNAME` instead of hardcoded `vscode` or `$(id -un)`
+- **Migration script hardened** — switched from `cp -rn` to `cp -a` (archive mode); added marker-based idempotency, critical file verification, ownership fixup, and old-directory rename
+- **`.env` deprecation guard** — `setup.sh` detects stale `CLAUDE_CONFIG_DIR=/workspaces/.claude` in `.env`, overrides to `$HOME/.claude`, and auto-comments the line on disk
+
+#### Documentation
+- All docs now reference `~/.claude` as default config path
+- Added `CLAUDE_AUTH_TOKEN` setup flow to README, configuration reference, and troubleshooting
+- ccstatusline README verification commands now respect `CLAUDE_CONFIG_DIR`
 
 ### Fixed
 
-#### CI: Release Workflow
+#### Claude Code Installation
+- **Update script no longer silently discards errors** — background update output now captured to log file instead of being discarded via `&>/dev/null`
+- **Update script simplified to native-binary-only** — removed npm fallback and `claude install` bootstrap code; added 60s timeout and transitional npm cleanup
+- **Alias resolution simplified** — `_CLAUDE_BIN` now resolves directly to native binary path (removed npm and `/usr/local/bin` fallbacks)
+- **POSIX redirect** — replaced `&>/dev/null` with `>/dev/null 2>&1` in dependency check for portability
+- **Installer shell** — changed `sh -s` to `bash -s` when piping the official installer (it requires bash)
+- **Unquoted `${TARGET}`** — quoted variable in `su -c` command to prevent word splitting
+- **Directory prep** — added `~/.local/state` and `~/.claude` pre-creation; consolidated `chown` to cover entire `~/.local` tree
+
+#### Plugin Marketplace
+- **`marketplace.json` schema fix** — changed all 11 plugin `source` fields from bare names (e.g., `"codeforge-lsp"`) to relative paths (`"./plugins/codeforge-lsp"`) so `claude plugin marketplace add` passes schema validation and all plugins register correctly
+
+#### ChromaTerm
+- **Regex lookbehinds** — replaced alternation inside lookbehinds (`(?<=[\s(]|^)` and `(?<=commit |merge |...)`) with non-capturing groups containing individual lookbehinds (`(?:(?<=[\s(])|^)` and `(?:(?<=commit )|(?<=merge )|...)`) for PCRE2 compatibility
+
+#### Terminal Color Support
+- **devcontainer.json** — added `TERM` and `COLORTERM=truecolor` to `remoteEnv`; Docker defaults to `TERM=xterm` (8 colors) which caused Claude Code and other CLI tools to downgrade rendering
+- **devcontainer.json** — `TERM` uses `${localEnv:TERM:xterm-256color}` to forward the host terminal type (e.g., `xterm-kitty`) instead of unconditionally overriding it
+- **setup-aliases.sh** — added terminal color defaults to managed shell block so tmux panes, `docker exec`, and SSH sessions also get 256-color and truecolor support
+- **kitty-terminfo/README.md** — updated documentation to reflect `localEnv` forwarding and clarify behavior across VS Code vs non-VS Code entry points
+- **CLAUDE.md** — documented `TERM` and `COLORTERM` environment variables in the Environment section
+
+### Removed
+
+#### Scripts
+- `setup-symlink-claude.sh` — no longer needed with native home directory location
+
+#### VS Code Extensions
+- **Todo+** (`fabiospampinato.vscode-todo-plus`) — removed from devcontainer extensions
+
+## [v2.0.0] - 2026-02-26
+
+### Added
+
+#### .codeforge/ User Customization Directory
+- New `.codeforge/` directory centralizes all user-customizable configuration files
+- Checksum-based modification detection preserves user changes during updates
+- `codeforge config apply` CLI command deploys config files to `~/.claude/` (same as container start)
+- Auto-migration from `.devcontainer/config/defaults/` to `.codeforge/config/` for existing users
+- `.codeforge/.codeforge-preserve` for listing additional files to preserve during updates
+
+### Changed
+
+#### Configuration
+- Config files moved from `.devcontainer/config/defaults/` to `.codeforge/config/`
+- File manifest moved from `.devcontainer/config/file-manifest.json` to `.codeforge/file-manifest.json`
+- Terminal connection scripts moved from `.devcontainer/` to `.codeforge/scripts/`
+- `CONFIG_SOURCE_DIR` env var deprecated in favor of `CODEFORGE_DIR`
+- `--force` updates now use checksum comparison for `.codeforge/` files (writes `.default` instead of `.codeforge-new`)
+- `--reset` preserves `.codeforge/` user modifications (only `.devcontainer/` is wiped)
+
+#### Migration
+- v2 migration marker moved to `.codeforge/.markers/v2-migrated`
+- Container start auto-migrates `.devcontainer/config/defaults/` to `.codeforge/config/` if needed
+
+## [v1.14.2] - 2026-02-24
+
+### Added
+
+#### Prompt Snippets Plugin
+- **New plugin: `prompt-snippets`** — single `/ps` slash command for quick behavioral mode switches (noaction, brief, plan, go, review, ship, deep, hold, recall, wait)
+- Snippets inject short directives that persist for the conversation (e.g., `/ps noaction` → "Investigate and report only. Take no action.")
+- Composable: `/ps noaction brief` applies multiple snippets at once
+- Isolated from skill-engine auto-suggestion (`disable-model-invocation: true`) and independently toggleable via `enabledPlugins`
+
+### Changed
+
+#### Docs
+- **First Session page** — trimmed from 198 to 128 lines by consolidating "What Happens Automatically" into a concise summary, replacing full agent/skill tables with brief teasers linking to their dedicated pages
+- **Installation Troubleshooting** — expanded from 4 to 10 FAQ entries covering `npx` failures, VS Code extension issues, Docker permissions on Linux, WSL 2 integration, port conflicts, and slow rebuilds
+
+### Fixed
+
+#### CI: Release Workflow (v1.14.1)
 - **test.js** — settings.json path updated from `config/settings.json` to `config/defaults/settings.json` to match config externalization refactor
 - **test.js** — Test 5 (executable check) result now included in exit condition; previously a failure was logged but did not affect the exit code
 - **setup.js** — file permissions changed from 644 to 755 (executable) to match shebang and `bin` declaration in package.json
 
-#### CI: Publish DevContainer Features Workflow
+#### CI: Publish DevContainer Features Workflow (v1.14.1)
 - **features/README.md** — removed from features directory; `devcontainers/action@v1` treated it as a feature subdirectory and failed looking for `README.md/devcontainer-feature.json`
 - **11 devcontainer-feature.json files** — removed `"maintainer"` field (not in the DevContainer Feature spec schema, causing strict validation failure): ast-grep, ccburn, ccms, ccstatusline, ccusage, chromaterm, claude-monitor, claude-session-dashboard, lsp-servers, mcp-qdrant, tree-sitter
 
+#### CI: Publish DevContainer Features Workflow (v1.14.2)
+- **6 devcontainer-feature.json files** — removed `"proposals"` field that coexisted with `"enum"` on the same option (spec schema treats them as mutually exclusive via `anyOf`): ccburn, ccusage, claude-monitor, claude-session-dashboard, mcp-qdrant, tree-sitter
+
+#### Docs
+- **Active sidebar item** — increased background opacity from 0.08 to 0.14, added `font-weight: 600` and `color: var(--sl-color-accent-high)` for readable contrast against inactive items
+- **Stale skill counts** — 5 pages (First Session, Getting Started index, Features index) referenced "21 skills" instead of the correct total of 34 across all plugins (skill-engine: 21, spec-workflow: 8, ticket-workflow: 4, agent-system: 1)
+
 ## [v1.14.0] - 2026-02-24
 
 ### Fixed (CodeRabbit review)

package/.devcontainer/CLAUDE.md

@@ -8,51 +8,92 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 .devcontainer/
 ├── devcontainer.json          # Container definition
 ├── .env                       # Setup flags (SETUP_CONFIG, SETUP_ALIASES, etc.)
-├── config/
-│   ├── file-manifest.json     # Declarative config file deployment
-│   └── defaults/              # Source files deployed on start via file-manifest
-│       ├── settings.json      # Model, permissions, plugins, env vars
-│       ├── main-system-prompt.md
-│       ├── ccstatusline-settings.json  # Status bar widget layout
-│       └── rules/             # Deployed to .claude/rules/
 ├── features/                  # Custom devcontainer features
 ├── plugins/devs-marketplace/  # Local plugin marketplace
 └── scripts/                   # Setup scripts (run via postStartCommand)
+
+.codeforge/
+├── file-manifest.json         # Declarative config file deployment
+├── config/                    # Source files deployed on start via file-manifest
+│   ├── settings.json          # Model, permissions, plugins, env vars
+│   ├── keybindings.json       # Keyboard shortcuts
+│   ├── main-system-prompt.md
+│   ├── orchestrator-system-prompt.md
+│   ├── writing-system-prompt.md
+│   ├── ccstatusline-settings.json  # Status bar widget layout
+│   └── rules/                 # Deployed to .claude/rules/
+├── scripts/                   # Terminal connection scripts
+│   ├── connect-external-terminal.sh
+│   └── connect-external-terminal.ps1
+└── .codeforge-preserve        # Lists additional files to preserve during updates
 ```
 
 ## Key Configuration
 
 | File | Purpose |
 |------|---------|
-| `config/defaults/settings.json` | Model, tokens, permissions, plugins, env vars |
-| `config/defaults/main-system-prompt.md` | System prompt defining assistant behavior |
-| `config/defaults/ccstatusline-settings.json` | Status bar widget layout (deployed to ~/.config/ccstatusline/) |
-| `config/file-manifest.json` | Controls which config files deploy and when |
+| `.codeforge/config/settings.json` | Model, tokens, permissions, plugins, env vars |
+| `.codeforge/config/main-system-prompt.md` | System prompt defining assistant behavior |
+| `.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/file-manifest.json` | Controls which config files deploy and when |
 | `devcontainer.json` | Container definition: image, features, mounts |
 | `.env` | Boolean flags controlling setup steps |
 
-Config files deploy via `file-manifest.json` on every container start. Most deploy to `/workspaces/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
+Config files deploy via `.codeforge/file-manifest.json` on every container start. Most deploy to `~/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
+
+## Worktrees
+
+Git worktrees allow checking out multiple branches simultaneously, each in its own directory.
+
+**Native (recommended for Claude Code sessions):**
+- **In-session:** `EnterWorktree` tool — creates worktree at `<repo>/.claude/worktrees/<name>/`, branch `worktree-<name>`, auto-cleaned if no changes
+- **New session:** `claude --worktree <name>` — starts Claude in its own worktree; combine with `--tmux` for background work
+
+**Manual (legacy convention):**
+```bash
+mkdir -p /workspaces/projects/.worktrees
+git worktree add /workspaces/projects/.worktrees/<branch-name> -b <branch>
+```
+
+**Environment files:** Place a `.worktreeinclude` file at the project root listing `.gitignore`-excluded files to copy into new worktrees (e.g., `.env`). Uses `.gitignore` pattern syntax; only files matching both `.worktreeinclude` and `.gitignore` are copied.
+
+**Management:**
+
+| Command | Purpose |
+|---------|---------|
+| `git worktree list` | Show all active worktrees |
+| `git worktree remove <path>` | Remove a worktree (destructive — confirm first) |
+| `git worktree prune` | Clean up stale references (destructive — confirm first) |
+
+**Path conventions:**
+- **Native:** `<repo>/.claude/worktrees/<name>/` — used by `--worktree` flag and `EnterWorktree`
+- **Legacy:** `.worktrees/` as sibling to the main repo — used for manual `git worktree add` and Project Manager integration
 
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
 | `cc` / `claude` | Run Claude Code with auto-configuration |
+| `codeforge config apply` | Deploy config files to `~/.claude/` (same as container start) |
+| `codeforge` | CLI for CodeForge management commands |
 | `ccraw` | Vanilla Claude Code (bypasses config) |
 | `ccw` | Claude Code with writing system prompt |
+| `cc-orc` | Claude Code in orchestrator mode (delegation-first) |
 | `ccms` | Search session history (project-scoped) |
 | `ccusage` / `ccburn` | Token usage analysis / burn rate |
 | `agent-browser` | Headless Chromium (Playwright-based) |
 | `check-setup` | Verify CodeForge setup health |
 | `claude-dashboard` | Session analytics dashboard (port 7847) |
+| `dbr` | Dynamic port forwarding (devcontainer-bridge) |
 | `cc-tools` | List all installed tools with versions |
 
 ## Plugins
 
 Declared in `settings.json` under `enabledPlugins`, auto-activated on start:
 
-- **agent-system** — 17 custom agents + built-in agent redirection
-- **skill-engine** — 21 general coding skills + auto-suggestion
+- **agent-system** — 21 custom agents (4 workhorse + 17 specialist) + built-in agent redirection
+- **skill-engine** — 22 general coding skills + auto-suggestion
 - **spec-workflow** — 8 spec lifecycle skills + spec-reminder hook
 - **session-context** — Git state injection, TODO harvesting, commit reminders
 - **auto-code-quality** — Auto-format + auto-lint + advisory test runner
@@ -61,37 +102,103 @@ Declared in `settings.json` under `enabledPlugins`, auto-activated on start:
 - **protected-files-guard** — Blocks edits to secrets/lock files
 - **codeforge-lsp** — LSP for Python + TypeScript/JavaScript
 - **ticket-workflow** — EARS ticket workflow + auto-linking
+- **git-workflow** — Standalone ship (commit/push/PR) + PR review
 - **notify-hook** — Desktop notifications on completion
 - **frontend-design** (Anthropic official) — UI/frontend design skill
+- **prompt-snippets** — Quick behavioral mode switches via /ps command
 
 ## Rules System
 
-Rules in `config/defaults/rules/` deploy to `.claude/rules/` on every container start. They load into ALL sessions automatically.
+Rules in `.codeforge/config/rules/` deploy to `.claude/rules/` on every container start. They load into ALL sessions automatically.
 
 **Current rules:** `spec-workflow.md`, `workspace-scope.md`, `session-search.md`
 
-**Adding rules:** Create `.md` in `config/defaults/rules/`, add a manifest entry in `file-manifest.json`.
+**Adding rules:** Create `.md` in `.codeforge/config/rules/`, add a manifest entry in `.codeforge/file-manifest.json`.
 
 ## Environment
 
 | Variable | Value |
 |----------|-------|
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` |
+| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` |
+| `CLAUDE_AUTH_TOKEN` | Long-lived token from `claude setup-token` (optional, via `.secrets` or Codespaces secrets) |
 | `ANTHROPIC_MODEL` | `claude-opus-4-6` |
 | `WORKSPACE_ROOT` | `/workspaces` |
+| `TERM` | `${localEnv:TERM:xterm-256color}` (via `remoteEnv` — forwards host TERM, falls back to 256-color) |
+| `COLORTERM` | `truecolor` (via `remoteEnv` — enables 24-bit color support) |
 
 All experimental feature flags are in `settings.json` under `env`. Setup steps controlled by boolean flags in `.env`.
 
+## Authentication & Persistence
+
+The `~/.claude/` directory is backed by a Docker named volume (`codeforge-claude-config-${devcontainerId}`), persisting config, credentials, and session data across container rebuilds. Each devcontainer instance gets an isolated volume.
+
+**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.
+
 ## Modifying Behavior
 
-1. **Change model**: Edit `config/defaults/settings.json` → `"model"` field
-2. **Change system prompt**: Edit `config/defaults/main-system-prompt.md`
-3. **Add config file**: Add entry to `config/file-manifest.json`
+1. **Change model**: Edit `.codeforge/config/settings.json` → `"model"` field
+2. **Change system prompt**: Edit `.codeforge/config/main-system-prompt.md`
+3. **Add config file**: Place in `.codeforge/config/`, add entry to `.codeforge/file-manifest.json`
 4. **Add features**: Add to `"features"` in `devcontainer.json`
 5. **Disable features**: Set `"version": "none"` in the feature's config
 6. **Disable setup steps**: Set flags to `false` in `.env`
-7. **Customize status bar**: Edit `config/defaults/ccstatusline-settings.json`
+7. **Customize status bar**: Edit `.codeforge/config/ccstatusline-settings.json` (see below)
+
+## Status Bar Widgets
+
+The status bar is configured in `.codeforge/config/ccstatusline-settings.json` (deploys to `~/.config/ccstatusline/settings.json`). Each widget is a JSON object in a line array.
+
+### Widget Properties
+
+| Property | Purpose |
+|----------|---------|
+| `id` | Unique identifier (UUID or descriptive string) |
+| `type` | Widget type (see below) |
+| `backgroundColor` | Background color: `bgBlue`, `bgMagenta`, `bgYellow`, `bgGreen`, `bgRed`, etc. |
+| `color` | Text color: `brightWhite`, `black`, `cyan`, `yellow`, etc. |
+| `rawValue` | `true` to strip type-specific prefixes (e.g., removes "Model:" from model widget) |
+| `bold` | `true` for bold text |
+| `merge` | `"no-padding"` fuses this widget to the next (no separator/space between them) |
+| `customText` | Static text content (only for `custom-text` type) |
+
+### Token Widgets
+
+Each token metric uses a distinct background color for at-a-glance identification:
+
+| Type | Color | Label |
+|------|-------|-------|
+| `tokens-input` | Blue (`bgBlue`) | **In** |
+| `tokens-output` | Magenta (`bgMagenta`) | **Ou** |
+| `tokens-cached` | Yellow (`bgYellow`) | **Ca** |
+| `tokens-total` | Green (`bgGreen`) | **Tt** |
+
+Labels are `custom-text` widgets with `merge: "no-padding"` so they fuse visually to their data widget:
+
+```json
+{ "id": "lbl-tokens-input", "type": "custom-text", "customText": "In",
+  "backgroundColor": "bgBlue", "color": "brightWhite", "bold": true, "merge": "no-padding" },
+{ "id": "5", "type": "tokens-input",
+  "backgroundColor": "bgBlue", "color": "brightWhite", "rawValue": true }
+```
+
+### Other Widget Types
+
+`model`, `context-length`, `context-percentage-usable`, `git-branch`, `git-changes`, `git-worktree`, `session-clock`, `session-cost`, `block-timer`, `version`, `custom-command`
 
 ## Features
 
-Custom features in `./features/` follow the [devcontainer feature spec](https://containers.dev/implementors/features/). Every local feature supports `"version": "none"` to skip installation. Claude Code is installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1`.
+Custom features in `./features/` follow the [devcontainer feature spec](https://containers.dev/implementors/features/). Every local feature supports `"version": "none"` to skip installation. Claude Code is installed as a native binary via `./features/claude-code-native` (uses Anthropic's official installer at `https://claude.ai/install.sh`).
+
+## Port Forwarding
+
+Three mechanisms handle port access depending on your client:
+
+| Mechanism | Client | Discovery |
+|-----------|--------|-----------|
+| VS Code auto-detect | VS Code only | Dynamic — all ports auto-forwarded with notification |
+| devcontainer-bridge (`dbr`) | Any terminal client | Dynamic — polls `/proc/net/tcp` |
+| SSH tunneling | Any SSH client | Manual — `ssh -L localPort:localhost:remotePort` |
+
+VS Code auto-detects all ports opened inside the container (configured via `portsAttributes` in `devcontainer.json`). Outside VS Code, `dbr` provides dynamic port discovery via a reverse connection model (container→host). The container daemon auto-starts and is inert without the host daemon (`dbr host-daemon`). Both mechanisms coexist. See [devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge).
+
+For full setup instructions, see the [Port Forwarding reference](https://codeforge.core-directive.com/reference/port-forwarding/) in the docs.