codeforge-dev 1.14.1 → 2.0.1

package/.devcontainer/CHANGELOG.md

@@ -1,18 +1,239 @@
 # CodeForge Devcontainer Changelog
 
-## [v1.14.1] - 2026-02-24
+## [v2.0.1] — 2026-03-02
+
+### Added
+#### Official Plugins
+- **Expanded Anthropic official plugins** — added `code-review`, `feature-dev`, and `pr-review-toolkit` from `anthropics/claude-code`
+- **Migrated plugin identifiers** — switched from `@claude-plugins-official` to `@anthropics/claude-code` format
+
+### Changed
+#### Protected Files Guard
+- **Allowed `.env.example` edits** — `.env.example` is no longer blocked by the `.env.*` pattern; actual secret files (`.env.local`, `.env.production`, etc.) remain protected
 
 ### Fixed
+- Plugin count updated 14→17 across all docs pages and README
+- Agent/skill counts corrected in README (17→21 agents, 35→38 skills)
+- Protected-files-guard README error handling table: "fails open" → "fails closed"
+- Merged stale `[Unreleased]` changelog entries into v2.0.0; updated test counts (241→289)
+
+## [v2.0.0] — 2026-02-26
+
+### .codeforge/ Configuration System
+- 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
+- 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)
+- v2 migration marker moved to `.codeforge/.markers/v2-migrated`
+- Container start auto-migrates `.devcontainer/config/defaults/` to `.codeforge/config/` if needed
+- 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`
+
+### System Prompts
+- **Main system prompt redesigned** — reorganized from 672 to 462 lines; personality, core directives, and response guidelines at the top
+- **Personality section** — communication style (casual-professional, direct, terse), humor rules, honesty approach, AuDHD-aware patterns, good/bad response examples; replaces the empty `<identity>` tag
+- **Compressed specification management** — 98 to 28 lines; full template and enforcement workflow moved to loadable skills
+- **Compressed code standards** — removed textbook principle recitations (SOLID, DRY/KISS/YAGNI by name); kept only concrete actionable rules
+- **Browser automation** and **git worktrees** sections moved to loadable skills
+- **Context-passing protocol** in orchestration — mandatory instructions for including gathered context, file paths, and constraints when spawning subagents
+- Absorbed `<assumption_surfacing>` into `<core_directives>`, `<professional_objectivity>` into `<personality>`
+- Deduplicated team composition examples; consolidated "no filler" instructions
+- **`<git_worktrees>` section** — updated for Claude Code native worktree convention (`<repo>/.claude/worktrees/`), `EnterWorktree` tool guidance, `.worktreeinclude` documentation
+
+### Orchestrator Mode
+- **`cc-orc` alias** — new Claude Code entry point using `orchestrator-system-prompt.md` for delegation-first operation
+- **`orchestrator-system-prompt.md`** — slim prompt (~250 lines) with delegation model, agent catalog, question surfacing protocol, planning gates, spec enforcement, and action safety
+
+### Agent System
+- **4 workhorse agents** — `investigator` (consolidated read-only research, sonnet), `implementer` (consolidated read-write implementation, opus/worktree), `tester` (enhanced test agent, opus/worktree), `documenter` (consolidated docs + specs, opus)
+- **Question Surfacing Protocol** — all 4 workhorse agents STOP and return `## BLOCKED: Questions` on ambiguities
+- **All 21 agents now have communication protocols** — read-only: "Handling Uncertainty"; write-capable: "Question Surfacing Protocol"
+- **Architect agent overhaul** — anti-fluff enforcement (20+ banned patterns), team orchestration planning, complexity scaling (simple/moderate/complex), concrete edit ordering (Models→Services→Routes→Tests→Config), rollback strategy for schema/API changes, 3 new examples
+- **Generalist rewritten as last-resort** — description explicitly warns when a specialist might be better
+- **Investigator narrowed** — repositioned from catch-all to "cross-domain investigations spanning 2+ specialist areas"
+- **Agent merges** — tester→test-writer (single test agent), doc-writer→documenter (single docs agent)
+- **Bash guard hooks** added to researcher, debug-logs, perf-profiler (prevents state-changing commands in read-only agents)
+- **Improved agent descriptions for routing accuracy** — trigger phrases, overlap boundaries between security-auditor/dependency-analyst, explorer/researcher
+- **Resolved communication protocol contradictions** across all agent behavioral rules
+- Agent count increased from 17 to 21 (4 workhorse + 17 specialist)
+- Agent-system README updated with workhorse agent table, per-agent hooks, plugin structure
+
+### Skill Engine
+- **Weighted scoring** — suggestion phrases carry confidence weights (0.0–1.0) instead of binary match
+- **Negative patterns** — substrings that instantly disqualify skills (prevents fastapi triggering for pydantic-ai)
+- **Context guards** — low-confidence matches (< 0.6) require confirming context word
+- **Ranked results capped at 3** — sorted by score then priority tier; eliminates suggestion floods
+- **Priority tiers** — explicit commands (10) > technology skills (7) > patterns (5) > generic (3)
+- **worktree skill** — git worktree creation, management, cleanup, `EnterWorktree` tool, `.worktreeinclude` setup
+
+### Plugins
+- **Expanded Anthropic official plugins** — added `code-review`, `feature-dev`, and `pr-review-toolkit` from `anthropics/claude-code`
+- **Migrated plugin identifiers** — switched from `@claude-plugins-official` to `@anthropics/claude-code` format
+- **Git workflow** — `/ship` (commit/push/PR with code review and approval) and `/pr:review` (PR review by number/URL, posts findings as comment)
+- **Prompt snippets** — `/ps` command for quick behavioral mode switches (noaction, brief, plan, go, review, ship, deep, hold, recall, wait); composable (`/ps noaction brief`)
+
+### Claude Code Installation
+- **Native binary** via Anthropic's official installer (`https://claude.ai/install.sh`) replacing npm-based feature
+- **Auto-updater works without root** — native binary at `~/.local/bin/claude` owned by container user
+- **Post-start onboarding hook** (`99-claude-onboarding.sh`) — ensures `hasCompletedOnboarding: true` when token auth configured
+- Update script captures errors to log (was discarding via `&>/dev/null`)
+- Simplified to native-binary-only (removed npm fallback, `claude install` bootstrap)
+- Alias resolution simplified — `_CLAUDE_BIN` resolves directly to native binary
+- POSIX redirect, bash-required installer shell, quoted `${TARGET}`, directory pre-creation
+
+### Testing
+- **289 pytest tests** covering 6 critical plugin scripts (previously zero tests):
+  - `block-dangerous.py` (62), `guard-workspace-scope.py` (40), `guard-protected.py` (56), `guard-protected-bash.py` (49), `guard-readonly-bash.py` (69), `redirect-builtin-agents.py` (13)
+- `test:plugins` and `test:all` npm scripts
+- Python plugin tests (`pytest`) added to CI pipeline (Q3-08)
+
+### Authentication
+- `CLAUDE_AUTH_TOKEN` support in `.secrets` for long-lived tokens from `claude setup-token`
+- Auto-creates `.credentials.json` from token on container start (idempotent)
+- `CLAUDE_AUTH_TOKEN` in devcontainer.json secrets declaration
+
+### Security
+- Removed environment variable injection vector in agent redirect log path (S2-01)
+- Narrowed config deployment allowed destinations from `/usr/local` to `/usr/local/share` (S2-09)
+- Protected files guard now fails closed on unexpected errors instead of failing open (S2-04)
+- Protected-files-guard blocks `.credentials.json` modifications
+- Replaced `eval` tilde expansion with `getent passwd` lookup (prevents shell injection)
+- Auth token JSON-escaped before writing; credential directory with restrictive umask (700)
+- `setup.js` path traversal prevention — `configApply()` validates source/destination paths
+
+### Performance
+- Commented out Rust toolchain feature — saves ~1.23 GB image size
+- Commented out ccms feature (requires Rust)
+- Updated Bun to latest (was pinned to 1.3.9)
+- npm cache cleanup across 6 features: agent-browser, ast-grep, biome, claude-session-dashboard, lsp-servers, tree-sitter (saves ~96 MB)
+
+### Port Forwarding
+- Dynamic forwarding for all ports in VS Code (was only port 7847)
+- **devcontainer-bridge (dbr)** — automatic port discovery and forwarding outside VS Code via [devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge)
+
+### Terminal & Color
+- `TERM` and `COLORTERM=truecolor` in `remoteEnv` (Docker defaults to 8-color `xterm`)
+- `TERM` forwards host terminal type via `${localEnv:TERM:xterm-256color}` (e.g., `xterm-kitty`)
+- Terminal color defaults in managed shell block for tmux panes, `docker exec`, SSH sessions
+- kitty-terminfo docs updated for `localEnv` forwarding
+
+### Status Bar
+- Distinct background colors per 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
+- CLAUDE.md "Status Bar Widgets" section with widget properties and conventions
+
+### Dangerous Command Blocker
+- Force push block now suggests `git merge` as workaround
+- Block `--force-with-lease` — all force push variants now blocked uniformly
+- Block remote branch deletion (`git push origin --delete`, colon-refspec `git push origin :branch`)
+- Handles prefix bypasses (`\rm`, `command rm`, `env rm`) and symbolic chmod (S2-03)
+- Fixed README — error handling documented as "fails open" but code actually fails closed
+
+### Guards
+- **Allowed `.env.example` edits** — `.env.example` is no longer blocked by the `.env.*` pattern; actual secret files (`.env.local`, `.env.production`, etc.) remain protected
+- Fixed greedy alternation in write-target regex — `>>` now matched before `>` (Q3-01)
+- Unified write-target extraction patterns across guards — protected-files bash guard expanded from 5 to 20 patterns (C1-02)
+- Multi-target command support — `rm`, `touch`, `mkdir`, `chmod`, `chown` with multiple file operands now check all targets
+- Bare `git stash` (equivalent to push) now blocked in read-only mode (Q3-04)
+- Fixed git global flag handling — `git -C /path stash list` no longer misidentifies the stash subcommand
+
+### Session Context & Code Quality
+- **Commit reminder** — switched to advisory (was blocking); tiered logic for meaningful changes; only fires when session modified files
+- **Advisory test runner** — reads from correct tmp file prefix (`claude-cq-edited` instead of `claude-edited-files`)
+
+### Scripts & Migration
+- Replaced `setup-symlink-claude.sh` with `setup-migrate-claude.sh` (one-time migration)
+- Migration script hardened — `cp -a` archive mode, marker-based idempotency, critical file verification, ownership fixup
+- `.env` deprecation guard — `setup.sh` detects stale `CLAUDE_CONFIG_DIR=/workspaces/.claude`, overrides and auto-comments
+- `setup.sh` `CODEFORGE_DIR` uses default-assignment (`:=`) to preserve user-defined values
+- Container runtime pre-flight check — validates Docker/Podman before build, OS-specific remediation
+
+### CI/CD & Public Repo
+- **Tag-triggered release workflow** (`v*` tags only) — prevents accidental releases from version bumps in PRs
+- CI workflow (Node 18, `npm test` + Biome check), CodeQL security analysis, Dependabot (weekly npm + GitHub Actions)
+- Bug report + feature request templates, PR template, issue template config
+- CONTRIBUTING.md, CLA.md, dual licensing notice, CI badge, SPDX headers on all 36 source files
+
+### Bug Fixes
+- Bun PATH in non-interactive shells
+- ChromaTerm regex lookbehinds — PCRE2 compatibility
+- CCStatusLine `CONFIG_SOURCE_DIR` deprecation guard, template directory permissions, silent copy failure reporting
+- `marketplace.json` schema — plugin `source` fields changed from bare names to relative paths
+- skill-engine worktree skill weighted tuples (was plain strings, caused crash)
+- dangerous-command-blocker fail closed on exceptions (was fail-open)
+- ticket-workflow redundant `ValueError` removed
+- workspace-scope-guard maxsplit in variable assignment detection
+- Shell scripts — executable bit on `check-setup.sh`, quoted `PLUGIN_BLACKLIST`, `set -uo pipefail` in tmux installer, `command -v` replacing deprecated `which`, normalized `&>` redirects
+- `implementer.md` — PostToolUse hook changed to Stop hook with 120s timeout
+- `tester.md` — Stop hook timeout 30s→120s
+- Stale merge conflict marker in first-session docs
+
+### Documentation
+- **DevContainer CLI guide** — dedicated Getting Started page for terminal-only workflows
+- **v2 Migration Guide** — path changes, automatic migration, manual steps, breaking changes, troubleshooting
+- **Ported `.devcontainer/docs/` to docs site** — Keybindings page, Troubleshooting page (12+ entries), Optional Features page, merged env vars and .secrets docs
+- Versioned docs infrastructure (starlight-versions plugin)
+- Fixed docs site URL to `https://codeforge.core-directive.com` (custom domain, no base path)
+- Replaced `anexileddev.github.io/CodeForge/` URLs with custom domain across all files
+- README: "Why CodeForge?" section, architecture overview, configuration summary
+- Agent/skill/plugin count updates (21 agents, 38 skills, 14 plugins) across all docs pages
+- Missing plugin pages for git-workflow and prompt-snippets
+- Port Forwarding reference, CLI guide cross-link, slimmed Installation page
+- Documented 4 workhorse agents, cc-orc command, CONFIG_SOURCE_DIR deprecation, CLAUDE_AUTH_TOKEN setup
+- Added missing git-workflow and prompt-snippets to configuration.md enabledPlugins example
+- Tabbed client-specific instructions on the installation page
+- MD040 compliance (language specifiers on fenced code blocks)
+- Architecture docs — `.checksums/` and `.markers/` in `.codeforge/` tree
+- Troubleshooting — "Reset to Defaults" renamed to "How to Reset", clarified `--reset` behavior
+- Removed `.devcontainer/docs/` directory (all content migrated to docs site)
+- All docs reference `~/.claude` as default config path
+
+### Removed
+- `setup-symlink-claude.sh` — replaced by `setup-migrate-claude.sh`
+- **Todo+** VS Code extension (`fabiospampinato.vscode-todo-plus`)
 
-#### CI: Release Workflow
+## [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

@@ -2,57 +2,43 @@
 
 CodeForge devcontainer for AI-assisted development with Claude Code.
 
-## Directory Structure
-
-```
-.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)
-```
-
 ## 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}`.
 
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
 | `cc` / `claude` | Run Claude Code with auto-configuration |
+| `codeforge config apply` | Deploy config files to `~/.claude/` (same as container start) |
 | `ccraw` | Vanilla Claude Code (bypasses config) |
 | `ccw` | Claude Code with writing system prompt |
-| `ccms` | Search session history (project-scoped) |
+| `cc-orc` | Claude Code in orchestrator mode (delegation-first) |
+| `ccms` | Session history search _(disabled — requires Rust toolchain; uncomment in devcontainer.json to enable)_ |
 | `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](https://github.com/bradleybeddoes/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 +47,34 @@ 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
+- **code-review** (Anthropic official) — Code review skill
+- **feature-dev** (Anthropic official) — Feature development skill
+- **pr-review-toolkit** (Anthropic official) — PR review commands + agents
+- **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
+## Authentication & Persistence
 
-| Variable | Value |
-|----------|-------|
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` |
-| `ANTHROPIC_MODEL` | `claude-opus-4-6` |
-| `WORKSPACE_ROOT` | `/workspaces` |
+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.
 
-All experimental feature flags are in `settings.json` under `env`. Setup steps controlled by boolean flags in `.env`.
+**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`
-
-## 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`.
+7. **Customize status bar**: Edit `.codeforge/config/ccstatusline-settings.json`

package/.devcontainer/README.md

@@ -1,6 +1,6 @@
 # CodeForge Usage Guide
 
-Everything you need to know once you're inside the devcontainer.
+Everything you need to know once you're inside the devcontainer. These instructions apply regardless of which client you used to start the container — VS Code, the `devcontainer` CLI, JetBrains Gateway, DevPod, or GitHub Codespaces.
 
 ## Quick Start
 
@@ -40,7 +40,20 @@ Get an API key from [console.anthropic.com](https://console.anthropic.com/).
 
 ### Credential Persistence
 
-Authentication credentials are stored in `/workspaces/.claude/` and persist across container rebuilds.
+Authentication credentials are stored in `~/.claude/` and persist across container rebuilds via a Docker named volume.
+
+### Long-Lived Token Authentication
+
+For headless or automated environments, you can use a long-lived auth token instead of browser login:
+
+1. Generate a token: `claude setup-token`
+2. Add to `.devcontainer/.secrets`:
+   ```bash
+   CLAUDE_AUTH_TOKEN=sk-ant-oat01-your-token-here
+   ```
+3. On next container start, `setup-auth.sh` will create `~/.claude/.credentials.json` automatically.
+
+You can also set `CLAUDE_AUTH_TOKEN` as a Codespaces secret for cloud environments.
 
 For more options, see the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).
 
@@ -111,7 +124,7 @@ Expected output shows your authenticated account and token scopes.
 
 ### Credential Persistence
 
-GitHub CLI credentials are automatically persisted across container rebuilds. The container is configured to store credentials in `/workspaces/.gh/` (via `GH_CONFIG_DIR`), which is part of the bind-mounted workspace.
+GitHub CLI credentials are automatically persisted across container rebuilds. The container is configured to store credentials in `/workspaces/.gh/` (via `GH_CONFIG_DIR`), which is part of the bind-mounted workspace. Claude Code credentials persist via a Docker named volume mounted at `~/.claude/`.
 
 **You only need to authenticate once.** After running `gh auth login` or configuring `.secrets`, your credentials will survive container rebuilds and be available in future sessions.
 
@@ -119,7 +132,7 @@ GitHub CLI credentials are automatically persisted across container rebuilds. Th
 
 ### The `cc` Command
 
-The `cc` command is an alias that launches Claude Code with the project's system prompt and plan-mode permissions. For Agent Teams split-pane support, use the **"Claude Teams (tmux)"** terminal profile in VS Code (dropdown next to the `+` button) or connect via `connect-external-terminal.sh`.
+The `cc` command is an alias that launches Claude Code with the project's system prompt and plan-mode permissions. For Agent Teams split-pane support, use the **"Claude Teams (tmux)"** terminal profile in VS Code (dropdown next to the `+` button) or connect via `.codeforge/scripts/connect-external-terminal.sh`.
 
 ```bash
 cc                    # Start Claude Code in current directory
@@ -199,7 +212,7 @@ Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude configuration directory |
+| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` | Claude configuration directory |
 | `SETUP_CONFIG` | `true` | Copy config files during setup (per `file-manifest.json`) |
 | `SETUP_ALIASES` | `true` | Add `cc`/`claude`/`ccraw` aliases to shell |
 | `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` |
@@ -212,7 +225,7 @@ Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
 
 ### Claude Code Settings
 
-Default settings are in `.devcontainer/config/defaults/settings.json`. File copying is controlled by `config/file-manifest.json`, which specifies per-file overwrite behavior (`"if-changed"`, `"always"`, or `"never"`).
+Default settings are in `.codeforge/config/settings.json`. File copying is controlled by `.codeforge/file-manifest.json`, which specifies per-file overwrite behavior (`"if-changed"`, `"always"`, or `"never"`).
 
 To add a custom config file, append an entry to `file-manifest.json`:
 ```json
@@ -230,7 +243,7 @@ Key defaults:
 
 ### Keybindings
 
-Default keybindings are in `.devcontainer/config/defaults/keybindings.json` (empty by default — Claude Code defaults apply). Customize by adding entries to the `bindings` array.
+Default keybindings are in `.codeforge/config/keybindings.json` (empty by default — Claude Code defaults apply). Customize by adding entries to the `bindings` array.
 
 **VS Code Terminal Passthrough**: `Ctrl+P` and `Ctrl+F` are configured to pass through to the terminal (via `terminal.integrated.commandsToSkipShell`) so Claude Code receives them. Other VS Code shortcuts that conflict with Claude Code:
 
@@ -247,7 +260,7 @@ For conflicting shortcuts, use Meta (Alt) variants or add custom keybindings.
 
 ### System Prompt
 
-The default system prompt is in `.devcontainer/config/defaults/main-system-prompt.md`. Override it by creating a `.claude/main-system-prompt.md` in your project directory.
+The default system prompt is in `.codeforge/config/main-system-prompt.md`. Override it by creating a `.claude/main-system-prompt.md` in your project directory.
 
 ## Custom Features
 
@@ -301,6 +314,8 @@ Three methods for providing GitHub/NPM credentials, in order of precedence:
 
 All methods persist across container rebuilds via the bind-mounted `/workspaces/.gh/` directory.
 
+4. **`.secrets` file with `CLAUDE_AUTH_TOKEN`** — Long-lived Claude auth token from `claude setup-token`. Auto-creates `~/.claude/.credentials.json` on container start.
+
 ## Agents & Skills
 
 Agents and skills are distributed across focused plugins (replacing the former `code-directive` monolith).
@@ -316,7 +331,7 @@ Agent definitions in `plugins/devs-marketplace/plugins/agent-system/agents/` pro
 | `claude-guide` | Claude Code feature guidance |
 | `debug-logs` | Log analysis and error diagnosis |
 | `dependency-analyst` | Dependency analysis and upgrades |
-| `doc-writer` | Documentation authoring |
+| `documenter` | Documentation, specs, and spec lifecycle |
 | `explorer` | Fast codebase search and navigation |
 | `generalist` | General-purpose multi-step tasks |
 | `git-archaeologist` | Git history forensics |
@@ -329,11 +344,11 @@ Agent definitions in `plugins/devs-marketplace/plugins/agent-system/agents/` pro
 | `statusline-config` | ccstatusline configuration |
 | `test-writer` | Test authoring with pass verification |
 
-### General Skills (21) — `skill-engine` plugin
+### General Skills (22) — `skill-engine` plugin
 
 Skills in `plugins/devs-marketplace/plugins/skill-engine/skills/` provide domain-specific coding references:
 
-`api-design` · `ast-grep-patterns` · `claude-agent-sdk` · `claude-code-headless` · `debugging` · `dependency-management` · `docker` · `docker-py` · `documentation-patterns` · `fastapi` · `git-forensics` · `migration-patterns` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `sqlite` · `svelte5` · `team` · `testing`
+`api-design` · `ast-grep-patterns` · `claude-agent-sdk` · `claude-code-headless` · `debugging` · `dependency-management` · `docker` · `docker-py` · `documentation-patterns` · `fastapi` · `git-forensics` · `migration-patterns` · `performance-profiling` · `pydantic-ai` · `refactoring-patterns` · `security-checklist` · `skill-building` · `sqlite` · `svelte5` · `team` · `testing` · `worktree`
 
 ### Spec Skills (8) — `spec-workflow` plugin
 
@@ -411,20 +426,20 @@ The `setup-projects.sh` script auto-detects projects under `/workspaces/` and ma
 
 - **Authentication required**: Run `claude` once to authenticate before using `cc`
 - **Plan mode default**: The container starts in "plan" mode, which prompts for approval before making changes
-- **Config is managed by manifest**: `config/file-manifest.json` controls which files are copied and when — default `overwrite: "if-changed"` uses sha256 comparison. Persistent changes go in `.devcontainer/config/defaults/settings.json`
+- **Config is managed by manifest**: `.codeforge/file-manifest.json` controls which files are copied and when — default `overwrite: "if-changed"` uses sha256 comparison. Persistent changes go in `.codeforge/config/settings.json`
 - **GitHub auth persists**: Run `gh auth login` once or configure `.secrets`; credentials survive container rebuilds
-- **Agent Teams needs tmux**: Split panes only work inside tmux. Use the "Claude Teams (tmux)" VS Code terminal profile or `connect-external-terminal.sh` from WezTerm/iTerm2
+- **Agent Teams needs tmux**: Split panes only work inside tmux. Use the "Claude Teams (tmux)" VS Code terminal profile or `.codeforge/scripts/connect-external-terminal.sh` from WezTerm/iTerm2
 
 ## Troubleshooting
 
-Common issues and solutions. For detailed troubleshooting, see [docs/troubleshooting.md](docs/troubleshooting.md).
+Common issues and solutions. For detailed troubleshooting, see the [Troubleshooting](https://codeforge.core-directive.com/reference/troubleshooting/) page on the docs site.
 
 | Problem | Solution |
 |---------|----------|
 | `cc: command not found` | Run `source ~/.bashrc` or open a new terminal |
 | `claude` fails during startup | Background update may be in progress — wait 10s and retry |
 | GitHub push fails | Run `gh auth status` to check authentication |
-| Plugin not loading | Check `enabledPlugins` in `config/defaults/settings.json` |
+| Plugin not loading | Check `enabledPlugins` in `.codeforge/config/settings.json` |
 | Feature not installed | Check `devcontainer.json` for `"version": "none"` |
 | Tool version/status | Run `cc-tools` to list all tools with version info |
 | Full health check | Run `check-setup` to verify setup status |
@@ -432,11 +447,11 @@ Common issues and solutions. For detailed troubleshooting, see [docs/troubleshoo
 ## Further Reading
 
 **CodeForge Documentation**:
-- [Configuration Reference](docs/configuration-reference.md) — all env vars and config options
-- [Plugin System](docs/plugins.md) — plugin architecture and per-plugin docs
-- [Optional Features](docs/optional-features.md) — mcp-qdrant and other optional components, disabling features
-- [Keybinding Customization](docs/keybindings.md) — resolving VS Code conflicts
-- [Troubleshooting](docs/troubleshooting.md) — common issues and solutions
+- [Configuration Reference](https://codeforge.core-directive.com/customization/configuration/) — all env vars and config options
+- [Plugin System](https://codeforge.core-directive.com/plugins/) — plugin architecture and per-plugin docs
+- [Optional Features](https://codeforge.core-directive.com/customization/optional-features/) — mcp-qdrant and other optional components, disabling features
+- [Keybinding Customization](https://codeforge.core-directive.com/customization/keybindings/) — resolving VS Code conflicts
+- [Troubleshooting](https://codeforge.core-directive.com/reference/troubleshooting/) — common issues and solutions
 
 **External**:
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)