codeforge-dev 1.5.8 → 1.8.0

package/.devcontainer/.env

@@ -8,12 +8,12 @@ CLAUDE_CONFIG_DIR=/workspaces/.claude
 # Setup: copy config files to CLAUDE_CONFIG_DIR
 SETUP_CONFIG=true
 
-# Setup: overwrite existing config files (false = skip if exists)
-OVERWRITE_CONFIG=true
-
 # Setup: add cc alias to shell rc files
 SETUP_ALIASES=true
 
+# Setup: configure Git and NPM auth from .secrets file
+SETUP_AUTH=true
+
 # Setup: install official Anthropic plugins
 SETUP_PLUGINS=true
 
@@ -21,5 +21,4 @@ SETUP_PLUGINS=true
 SETUP_UPDATE_CLAUDE=true
 
 # Plugin blacklist (comma-separated plugin names to skip during auto-install)
-# Example: PLUGIN_BLACKLIST="workflow-enhancer,auto-formatter"
-PLUGIN_BLACKLIST="workflow-enhancer,planning-reminder"
+PLUGIN_BLACKLIST=""

package/.devcontainer/.env.example

@@ -0,0 +1,29 @@
+# CodeForge Environment Configuration
+# Copy to .env and customize. .env is gitignored.
+
+# Paths
+CLAUDE_CONFIG_DIR=/workspaces/.claude
+# CONFIG_SOURCE_DIR is derived from script location; uncomment to override:
+# CONFIG_SOURCE_DIR=/custom/path/to/config
+
+# Setup: copy config files to CLAUDE_CONFIG_DIR (per config/file-manifest.json)
+SETUP_CONFIG=true
+
+# Setup: add cc/claude/ccraw aliases to shell rc files
+SETUP_ALIASES=true
+
+# Setup: configure Git and NPM auth from .secrets file
+SETUP_AUTH=true
+
+# Setup: install official Anthropic plugins + register local marketplace
+SETUP_PLUGINS=true
+
+# Setup: auto-update Claude Code CLI to latest on container start (runs in background)
+SETUP_UPDATE_CLAUDE=true
+
+# Setup: auto-detect projects for VS Code Project Manager extension
+SETUP_PROJECTS=true
+
+# Plugin blacklist: comma-separated plugin names to skip during installation
+# Example: PLUGIN_BLACKLIST="ticket-workflow,auto-linter"
+PLUGIN_BLACKLIST=""

package/.devcontainer/.gitignore

@@ -0,0 +1,8 @@
+# Explicitly ignored (safety net on top of root .* rule)
+.review
+.secrets
+
+# Un-ignore dotfiles that should be tracked (overrides root .* pattern)
+!.env.example
+!.secrets.example
+!.gitignore

package/.devcontainer/.secrets.example

@@ -0,0 +1,12 @@
+# Copy this file to .secrets and fill in your tokens.
+# .secrets is gitignored and will never be committed.
+
+# GitHub Personal Access Token (classic or fine-grained)
+GH_TOKEN=
+# GitHub username for git config
+GH_USERNAME=
+# GitHub email for git config (use noreply for privacy)
+GH_EMAIL=
+
+# NPM auth token for registry.npmjs.org
+NPM_TOKEN=

package/.devcontainer/CHANGELOG.md

@@ -1,5 +1,191 @@
 # CodeForge Devcontainer Changelog
 
+## [v1.8.0] - 2026-02-09
+
+### Added
+
+#### Config System: Declarative File Manifest
+- **`config/file-manifest.json`** — new declarative manifest controlling which config files are copied and how. Replaces hardcoded `copy_file` calls with per-file `overwrite` modes: `"if-changed"` (sha256-based, default), `"always"`, or `"never"`
+- **`config/defaults/`** — config files relocated from `config/` to `config/defaults/` (settings.json, keybindings.json, main-system-prompt.md)
+- **`setup-config.sh` rewritten** — reads file-manifest.json, supports variable expansion (`${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`), sha256-based change detection, and legacy fallback if manifest is missing
+
+#### Features
+- **ruff feature** — Python formatter/linter via `uv tool install ruff`; replaces Black as primary Python formatter (Black kept as fallback)
+- **shfmt feature** — Shell script formatter via direct binary download from GitHub releases; supports `.sh`, `.bash`, `.zsh`, `.mksh`, `.bats`
+- **dprint feature** — Pluggable formatter for Markdown, YAML, TOML, and Dockerfile via GitHub releases binary; ships global config at `/usr/local/share/dprint/dprint.json` with four plugins (markdown, yaml, toml, dockerfile)
+- **shellcheck feature** — Shell script linter via `apt-get install`; JSON output parsing for structured diagnostics
+- **hadolint feature** — Dockerfile linter via direct binary download from GitHub releases; JSON output parsing
+
+#### Formatter Coverage (format-on-stop.py)
+- **Ruff formatter** — `.py`/`.pyi` files now formatted with Ruff (falls back to Black if Ruff not installed)
+- **Biome expanded** — added `.css`, `.json`, `.jsonc`, `.graphql`, `.gql`, `.html`, `.vue`, `.svelte`, `.astro` (was JS/TS only; now 18 extensions total)
+- **shfmt integration** — `.sh`, `.bash`, `.zsh`, `.mksh`, `.bats` files auto-formatted on Stop
+- **dprint integration** — `.md`, `.markdown`, `.yaml`, `.yml`, `.toml` files and `Dockerfile`/`.dockerfile` auto-formatted on Stop
+- **rustfmt integration** — `.rs` files auto-formatted if `rustfmt` is in PATH (conditional, zero overhead when unused)
+
+#### Linter Coverage (lint-file.py)
+- **Ruff linter** — Python files now checked by both Pyright (type checking) and Ruff (style/correctness); complementary, not redundant
+- **Biome lint** — JS/TS/CSS/GraphQL files linted via `biome lint --reporter=json`; surfaces unsafe diagnostics not auto-fixed by formatter
+- **ShellCheck** — shell scripts linted via `shellcheck --format=json`; structured severity/line/message output
+- **go vet** — `.go` files linted via `go vet`; stderr parsed for diagnostics
+- **hadolint** — `Dockerfile`/`.dockerfile` files linted via `hadolint --format json`
+- **clippy** — `.rs` files linted via `cargo clippy` if cargo is in PATH (conditional)
+
+#### version:none Support
+- **All 20 local features** now support `"version": "none"` in devcontainer.json to skip installation entirely
+- Added `version` option to 7 features that previously lacked it: ccstatusline, notify-hook, shellcheck, mcp-qdrant, mcp-reasoner, splitrail, lsp-servers
+- Added skip guard (`if [ "${VERSION}" = "none" ]; then exit 0; fi`) to all 20 install.sh files
+
+#### Advisory Hooks (code-directive plugin)
+- **advisory-test-runner.py** `[Stop]` — runs project test suite on Stop, injects pass/fail results as `additionalContext`. Never blocks (always exit 0). Detects pytest, vitest, jest, mocha, go test, cargo test. 60s timeout, truncates to last 30 lines
+- **git-state-injector.py** `[SessionStart]` — injects branch, status summary, recent commits, and diff stats as `additionalContext` on every session start. 5s per git command, total output capped at 2000 chars
+- **ticket-linker.py** `[UserPromptSubmit]` — auto-fetches GitHub issues/PRs when prompt contains `#123` or full GitHub URLs. Up to 3 refs per prompt, body capped at 1500 chars each
+- **commit-reminder.py** `[Stop]` — checks for uncommitted changes (staged/unstaged counts) and injects advisory reminder as `additionalContext`. Checks `stop_hook_active`
+- **todo-harvester.py** `[SessionStart]` — greps for TODO/FIXME/HACK/XXX across 13 source extensions, injects count + top 10 items. Excludes noise dirs, output capped at 800 chars
+
+#### New Skills (code-directive plugin — 5 new, 21 total)
+- **api-design** — REST conventions, error handling patterns, OpenAPI/Swagger guidance
+- **ast-grep-patterns** — structural code search patterns across languages
+- **dependency-management** — ecosystem-specific audit commands, license compliance
+- **documentation-patterns** — docstring formats, API doc templates
+- **migration-patterns** — Python and JavaScript framework migration guides
+
+#### Commands & Scripts
+- **`cc-tools`** — new shell function listing all installed CodeForge tools with version info
+- **`check-setup`** — new health check script (`check-setup.sh`) verifying container setup is working correctly; aliased in shell rc files
+
+#### Workspace
+- **`CLAUDE.md`** — workspace-level project instructions (workspace scoping rules)
+- **`test-project/`** — minimal test project directory
+
+### Changed
+
+#### NPM Package (setup.js)
+- **`--force` is now non-destructive** — selectively syncs files instead of rm+copy. Framework files (scripts, features, plugins) are overwritten; user config files (settings, keybindings, system prompt, file-manifest) are preserved with `.codeforge-new` versions saved for diffing
+- **`--reset` flag** — new option for complete fresh install (deletes and re-copies everything)
+- **`.codeforge-preserve`** — user-customizable file listing additional paths to preserve during `--force` updates
+- **devcontainer.json handling** — user's version backed up as `.bak` during `--force`, then overwritten with package version
+- **`.npmignore`** — excludes `.codeforge-new`, `.bak`, and `.codeforge-preserve` artifacts from npm package
+
+#### Setup System
+- **setup.sh** — removed `set -e` (individual script failures no longer abort the entire setup); structured pass/fail/skip reporting with elapsed time summary
+- **setup-aliases.sh** — backs up `.bashrc`/`.zshrc` before modifying (keeps last 3 backups); cleans up old cc-tools/check-setup definitions; adds `cc-tools` function and `check-setup` alias
+- **OVERWRITE_CONFIG deprecated** — replaced by per-file `overwrite` in `config/file-manifest.json`. Legacy env var triggers a deprecation warning
+
+#### Code-Directive Plugin
+- **hooks.json** — expanded from 3 to 6 hook events (added Stop, SessionStart, updated UserPromptSubmit with ticket-linker)
+- **Agent definitions** — architect gains documentation outputs section + api-design skill link; multiple agents updated with refined instructions
+- **skill-suggester.py** — added keyword mappings for 5 new skills (api-design, ast-grep-patterns, dependency-management, documentation-patterns, migration-patterns)
+- **specification-writing skill** — expanded with additional templates and patterns
+- **code-directive plugin.json** — description updated to "17 custom agents, 16 coding skills, agent redirection, syntax validation, and skill auto-suggestion"
+
+#### Other
+- **format-on-stop.py** — rewritten with expanded dispatch: 7 formatters covering 31 file extensions (was 3 formatters, 12 extensions)
+- **lint-file.py** — rewritten as multi-language dispatcher: 7 linters across Python, JS/TS/CSS, Shell, Go, Dockerfile, Rust (was Pyright-only for Python)
+- **auto-linter hook timeout** — increased from 30s to 60s (each individual linter subprocess still capped at 10s)
+- **auto-formatter plugin.json** — description updated to reflect all 7 formatters
+- **auto-linter plugin.json** — description updated to reflect all 7 linters
+- **marketplace.json** — descriptions updated for auto-formatter, auto-linter, and code-directive plugins
+- **devcontainer.json** — 5 new features registered in `overrideFeatureInstallOrder` and `features` object; added install order documentation comments
+- **.env.example** — removed `OVERWRITE_CONFIG`, added `SETUP_PROJECTS`, updated descriptions
+- **.gitignore** — updated with additional exclusions
+
+### Removed
+
+- **`features/claude-code/`** — entire local feature deleted (Claude Code now installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1`, the official Anthropic feature)
+- **`config/settings.json`**, **`config/keybindings.json`**, **`config/main-system-prompt.md`** — moved to `config/defaults/` subdirectory
+- **`OVERWRITE_CONFIG` env var** — deprecated in favor of `config/file-manifest.json` per-file overwrite modes
+
+### Documentation
+
+- **New `docs/` directory** with 5 focused guides: configuration-reference, keybindings, optional-features, plugins, troubleshooting
+- **CLAUDE.md** — rewritten for new config system (file-manifest.json, config/defaults/), added cc-tools/check-setup commands, added version:none section, updated plugin descriptions
+- **README.md** — added new tools (ruff, shfmt, dprint, shellcheck, hadolint, Bun), updated config system docs, added SETUP_PROJECTS and PLUGIN_BLACKLIST env vars, updated ccstatusline description
+
+---
+
+## [v1.7.1] - 2026-02-08
+
+### Added
+
+- **Automatic Git & NPM auth on container start** — new `setup-auth.sh` script reads tokens from `.devcontainer/.secrets` (or environment variables) and configures GitHub CLI, git user identity, and NPM registry auth automatically
+- **`.secrets.example` template** — committed template showing required variables (`GH_TOKEN`, `GH_USERNAME`, `GH_EMAIL`, `NPM_TOKEN`)
+- **`.env.example` template** — committed template for environment configuration (`.env` itself remains gitignored)
+- **`SETUP_AUTH` env var** — controls whether auth setup runs on container start (default: `true`)
+- **`AGENT-REDIRECTION.md`** — guide on how the PreToolUse hook system works, how built-in agents are swapped to custom ones, and what else is possible (prompt injection, model overrides, conditional routing, external service chaining)
+
+### Changed
+
+- **README split by audience** — root `README.md` is now the npm/GitHub landing page (install, prerequisites, what's included, quick start); `.devcontainer/README.md` is now the usage guide (auth, tools, config, agents, keybindings, gotchas). No duplicated content between the two
+- **Auto-linter moved to Stop hook** — was PostToolUse (ran pyright per-edit, caused agent re-reads); now batch-lints all edited Python files when Claude stops, matching auto-formatter's pattern. Uses its own temp file (`claude-lint-files-{session_id}`) independent of the formatter pipeline
+- **`collect-edited-files.py`** — now writes to both `claude-edited-files-*` (formatter) and `claude-lint-files-*` (linter) temp files, keeping the two Stop hook pipelines independent
+- **`.devcontainer/.gitignore`** — added `.secrets` explicit ignore and negation patterns (`!.env.example`, `!.secrets.example`, `!.gitignore`) to override root `.*` rule for files that should be tracked
+- **`setup.sh` orchestration** — `setup-auth.sh` runs early (after symlink, before config/plugins) so NPM auth is available for plugin installation
+- **`PLUGIN_BLACKLIST`** — cleared (was `"workflow-enhancer,planning-reminder"`)
+
+### Removed
+
+- **`workflow-enhancer` plugin** — deleted entirely (was scaffolding only, never active)
+- **`planning-reminder` plugin** — deleted entirely (redundant with Claude Code v2.1+ auto plan mode)
+
+---
+
+## [v1.7.0] - 2026-02-08
+
+### Added
+
+- **ccburn feature** — new devcontainer feature for visual token burn rate tracking with shell aliases and statusline wrapper
+- **Session resume widget** — ccstatusline displays copyable `cc --resume {sessionId}` command on line 5
+- **Burn rate widget** — ccstatusline line 6 shows live ccburn compact output with pace indicators (session/weekly/sonnet limits)
+- **17 custom agent definitions** — code-directive plugin now includes specialized agents: architect, bash-exec, claude-guide, debug-logs, dependency-analyst, doc-writer, explorer, generalist, git-archaeologist, migrator, perf-profiler, refactorer, researcher, security-auditor, spec-writer, statusline-config, test-writer
+- **6 new skills** — claude-agent-sdk, git-forensics, performance-profiling, refactoring-patterns, security-checklist, specification-writing
+- **Agent redirect hook** — `redirect-builtin-agents.py` (PreToolUse/Task) transparently swaps built-in agent types (Explore→explorer, Plan→architect, etc.) to enhanced custom agents
+- **Readonly bash guard** — `guard-readonly-bash.py` blocks write operations for read-only agents
+- **Regression test hooks** — `verify-no-regression.py` (PostToolUse for refactorer) and `verify-tests-pass.py` (Stop for test-writer)
+- **REVIEW-RUBRIC.md** — quality standards document for agent/skill development
+- **Keybindings configuration** — new `config/keybindings.json` with schema support
+- **VS Code terminal passthrough** — `Ctrl+P` and `Ctrl+F` pass through to Claude Code via `terminal.integrated.commandsToSkipShell`
+- **claude-agent-sdk skill** — new code-directive skill for Claude Agent SDK TypeScript integration
+- **OVERWRITE_CONFIG documentation** — documented ephemeral settings behavior
+- **Project Manager integration** — `setup-projects.sh` auto-detects projects under `/workspaces/`, watches for changes via inotifywait, maintains `projects.json`
+- **Claude config symlink** — `setup-symlink-claude.sh` symlinks `~/.claude` → `$CLAUDE_CONFIG_DIR` for third-party tool compatibility
+- **Project Manager VS Code extension** — `alefragnani.project-manager` added to devcontainer
+
+### Changed
+
+- **ccstatusline layout** — expanded from 3→6 lines (13→16 widgets), reorganized into logical groups (core metrics, tokens, git, session, totals, burn rate)
+- **ccstatusline version** — bumped from 1.0.0 to 1.1.0
+- **Plugin declarations centralized** — all 9 marketplace plugins declared in `enabledPlugins` in `config/settings.json`
+- **setup-plugins.sh cache sync** — re-added plugin install loop to sync cache from source on every container start; added `.env` fallback so `PLUGIN_BLACKLIST` works on standalone invocation
+- **Feature-level config synced** — `features/claude-code/config/settings.json` mirrors main config (model → `claude-opus-4-6`, `MAX_THINKING_TOKENS` → `63999`, `cleanupPeriodDays` → `60`, all env vars)
+- **8 new env vars** — `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`, `CLAUDE_CODE_MAX_RETRIES`, `BASH_MAX_OUTPUT_LENGTH`, `TASK_MAX_OUTPUT_LENGTH`, `CLAUDE_CODE_PLAN_MODE_INTERVIEW_PHASE`, `CLAUDE_CODE_PLAN_V2_AGENT_COUNT`, `CLAUDE_CODE_PLAN_MODE_REQUIRED`, `CLAUDE_CODE_FORCE_GLOBAL_CACHE`
+- **setup-config.sh** — added `chown` for correct ownership; added keybindings.json to copy pipeline
+- **setup-aliases.sh** — added idempotency guard
+- **TMPDIR consistency** — `setup-update-claude.sh` and `ccstatusline/install.sh` use `${TMPDIR:-/tmp}`
+- **installsAfter references** — mcp-qdrant and mcp-reasoner updated from `./features/claude-code` to `ghcr.io/anthropics/devcontainer-features/claude-code:1`
+- **code-directive hooks.json** — added PreToolUse/Task hook for agent redirection
+- **Auto-linter timeout** — pyright reduced from 55s to 10s
+- **Auto-formatter tool paths** — resolved via `which` first
+- **Protected-files-guard regex** — tightened `id_rsa` pattern
+- **Syntax-validator JSONC regex** — handles URLs containing `://`
+- **Skill-suggester keywords** — consolidated claude-agent-sdk phrases; added "compose" to docker
+- **redirect-builtin-agents.py fix** — `updatedInput` now preserves all original tool input fields (Claude Code replaces rather than merges)
+- **System prompt hardened** — added anti-fabrication rule, failure recovery strategy, and silent-violation guard to `execution_discipline` and `rule_precedence`
+
+### Removed
+
+- **setup-irie-claude.sh** — deleted (personal script, no longer invoked)
+- **output-style widget** — removed from ccstatusline (low value)
+
+### Documentation
+
+- **CLAUDE.md** — added keybindings.json, updated plugins list, fixed model name, documented VS Code conflicts, documented OVERWRITE_CONFIG, added agents/skills sections, added new scripts
+- **README.md** — fixed max output tokens, added keybindings section, added agents/skills, added project manager
+- **features/README.md** — full rewrite listing all features
+- **CHANGELOG.md** — squashed v1.6.0 + v1.6.1 into this entry
+
+---
+
 ## [v1.5.8] - 2026-02-06
 
 ### Changed

package/.devcontainer/CLAUDE.md

@@ -10,14 +10,18 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 │   ├── devcontainer.json    # Main container definition
 │   ├── .env                 # Environment variables
 │   ├── config/              # Default configurations
-│   │   ├── settings.json    # Claude Code settings
-│   │   └── main-system-prompt.md
+│   │   ├── file-manifest.json # Declarative file-copy manifest
+│   │   └── defaults/        # Files copied per manifest
+│   │       ├── settings.json    # Claude Code settings
+│   │       ├── keybindings.json # Claude Code keybindings
+│   │       └── main-system-prompt.md
 │   ├── features/            # Custom devcontainer features
 │   ├── plugins/             # Local plugin marketplace
 │   │   └── devs-marketplace/
 │   └── scripts/             # Setup scripts
 ├── .claude/                 # Runtime Claude config (created on first run)
-│   ├── settings.json        # Active settings
+│   ├── settings.json        # Active settings (managed by file-manifest.json)
+│   ├── keybindings.json     # Active keybindings
 │   └── system-prompt.md     # Active system prompt
 └── .gh/                     # GitHub CLI config (persists across rebuilds)
     └── hosts.yml            # Authenticated hosts
@@ -29,8 +33,12 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 |------|---------|
 | `devcontainer.json` | Container definition: base image, features, mounts, environment |
 | `.env` | Environment variables controlling setup behavior |
-| `config/settings.json` | Claude Code defaults: model, tokens, permissions, plugins |
-| `config/main-system-prompt.md` | Default system prompt defining assistant behavior |
+| `config/file-manifest.json` | Declarative manifest controlling which config files are copied and how |
+| `config/defaults/settings.json` | Claude Code defaults: model, tokens, permissions, plugins |
+| `config/defaults/keybindings.json` | Claude Code keybindings (empty by default — customizable) |
+| `config/defaults/main-system-prompt.md` | Default system prompt defining assistant behavior |
+
+> **Note**: Config file copying is controlled by `config/file-manifest.json`. Each entry specifies `overwrite`: `"if-changed"` (default, sha256-based), `"always"`, or `"never"`. Persistent changes go in `.devcontainer/config/defaults/settings.json`.
 
 ## Commands
 
@@ -43,6 +51,8 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 | `gh` | GitHub CLI for repo operations |
 | `uv` | Fast Python package manager |
 | `ast-grep` | Structural code search |
+| `cc-tools` | List all installed tools with version info |
+| `check-setup` | Verify CodeForge setup health |
 
 ## Feature Development
 
@@ -63,6 +73,39 @@ To test a feature locally, reference it in `devcontainer.json`:
 }
 ```
 
+> **Note**: Claude Code is installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1` (Anthropic's official feature).
+
+### Disabling Features with `version: "none"`
+
+Every local feature supports `"version": "none"` to skip installation entirely. This is useful for trimming build time or disabling tools you don't need without removing them from `devcontainer.json`.
+
+```json
+"features": {
+  "./features/ruff": { "version": "none" },
+  "./features/biome": {},
+  "./features/hadolint": { "version": "none" }
+}
+```
+
+When `version` is set to `"none"`, the feature's `install.sh` exits immediately with a skip message. The feature entry stays in `devcontainer.json` so re-enabling is a one-word change.
+
+**All local features support this pattern:**
+ast-grep, biome, ccstatusline, claude-monitor, dprint, hadolint, lsp-servers, mcp-qdrant, mcp-reasoner, notify-hook, ruff, shfmt, shellcheck, splitrail, tmux
+
+**External features with `version: "none"` support:**
+`ghcr.io/devcontainers/features/node`, `ghcr.io/devcontainers/features/github-cli`, `ghcr.io/devcontainers/features/docker-outside-of-docker`, `ghcr.io/devcontainers/features/go` (all official Microsoft features)
+
+**External features without `version: "none"` support:**
+`ghcr.io/devcontainers-extra/features/uv`, `ghcr.io/anthropics/devcontainer-features/claude-code`, `ghcr.io/nickmccurdy/bun`
+
+> **Convention**: Every new local feature must include a `version` option (default `"latest"`) in its `devcontainer-feature.json` and a skip guard at the top of `install.sh`:
+> ```bash
+> if [ "${VERSION}" = "none" ]; then
+>     echo "[feature-name] Skipping installation (version=none)"
+>     exit 0
+> fi
+> ```
+
 ## Setup Scripts
 
 Scripts in `./scripts/` run via `postStartCommand`:
@@ -70,17 +113,29 @@ Scripts in `./scripts/` run via `postStartCommand`:
 | Script | Purpose |
 |--------|---------|
 | `setup.sh` | Main orchestrator |
-| `setup-config.sh` | Copies config files to `/workspaces/.claude/` |
-| `setup-aliases.sh` | Creates `cc` shell function |
-| `setup-lsp.sh` | Installs LSP plugins from local marketplace |
-| `setup-plugins.sh` | Installs official Anthropic plugins |
+| `setup-config.sh` | Copies config files per `config/file-manifest.json` to destinations |
+| `setup-aliases.sh` | Creates `cc`/`claude`/`ccraw` shell aliases |
+| `setup-plugins.sh` | Registers local marketplace + installs official Anthropic plugins |
+| `setup-update-claude.sh` | Background auto-update of Claude Code binary |
+| `setup-projects.sh` | Auto-detects projects for VS Code Project Manager |
+| `setup-symlink-claude.sh` | Symlinks ~/.claude for third-party tool compatibility |
 
 ## Installed Plugins
 
-Automatically installed on container start:
+Plugins are declared in `config/defaults/settings.json` under `enabledPlugins` and auto-activated on container start:
+
+### Official (Anthropic)
+- `frontend-design@claude-code-plugins` — UI/frontend design skill
 
-- `frontend-design@claude-plugins-official` (skill)
-- `codeforge-lsp@devs-marketplace` (LSP for Python + TypeScript/JavaScript)
+### Local Marketplace (devs-marketplace)
+- `codeforge-lsp@devs-marketplace` — LSP for Python + TypeScript/JavaScript
+- `ticket-workflow@devs-marketplace` — EARS-based ticket workflow with GitHub integration
+- `notify-hook@devs-marketplace` — Desktop notifications on completion
+- `dangerous-command-blocker@devs-marketplace` — Blocks destructive bash commands
+- `protected-files-guard@devs-marketplace` — Blocks edits to secrets/lock files
+- `auto-formatter@devs-marketplace` — Batch-formats edited files at Stop (Ruff/Black for Python, gofmt for Go, Biome for JS/TS/CSS/JSON/GraphQL/HTML, shfmt for Shell, dprint for Markdown/YAML/TOML/Dockerfile, rustfmt for Rust)
+- `auto-linter@devs-marketplace` — Auto-lints edited files at Stop (Pyright + Ruff for Python, Biome for JS/TS/CSS/GraphQL, ShellCheck for Shell, go vet for Go, hadolint for Dockerfile, clippy for Rust)
+- `code-directive@devs-marketplace` — 17 custom agents, 16 skills, syntax validation, skill suggestions, agent redirect hook
 
 ### Local Marketplace
 
@@ -91,12 +146,41 @@ plugins/devs-marketplace/
 ├── .claude-plugin/
 │   └── marketplace.json      # Marketplace manifest
 └── plugins/
-    └── codeforge-lsp/        # Combined LSP plugin
-        └── .claude-plugin/
-            └── plugin.json
+    ├── codeforge-lsp/        # Combined LSP plugin
+    ├── ticket-workflow/      # EARS ticket workflow
+    ├── auto-formatter/       # Batch formatter (Stop hook)
+    ├── auto-linter/          # Pyright linter
+    ├── code-directive/       # Agents, skills + hooks
+    └── ...
 ```
 
-This gives full control over LSP configuration without external dependencies.
+## Agents & Skills
+
+The `code-directive` plugin includes 17 custom agent definitions and 16 coding reference skills.
+
+**Agents** (`plugins/devs-marketplace/plugins/code-directive/agents/`):
+architect, bash-exec, claude-guide, debug-logs, dependency-analyst, doc-writer, explorer, generalist, git-archaeologist, migrator, perf-profiler, refactorer, researcher, security-auditor, spec-writer, statusline-config, test-writer
+
+The `redirect-builtin-agents.py` hook (PreToolUse/Task) transparently swaps built-in agent types to these custom agents (e.g., Explore→explorer, Plan→architect).
+
+**Skills** (`plugins/devs-marketplace/plugins/code-directive/skills/`):
+claude-agent-sdk, claude-code-headless, debugging, docker, docker-py, fastapi, git-forensics, performance-profiling, pydantic-ai, refactoring-patterns, security-checklist, skill-building, specification-writing, sqlite, svelte5, testing
+
+## VS Code Keybinding Conflicts
+
+Claude Code runs inside VS Code's integrated terminal. VS Code intercepts some shortcuts before they reach the terminal:
+
+| Shortcut | VS Code Action | Claude Code Action |
+|----------|---------------|-------------------|
+| `Ctrl+G` | Go to Line | `chat:externalEditor` |
+| `Ctrl+S` | Save File | `chat:stash` |
+| `Ctrl+T` | Open Symbol | `app:toggleTodos` |
+| `Ctrl+O` | Open File | `app:toggleTranscript` |
+| `Ctrl+B` | Toggle Sidebar | `task:background` |
+| `Ctrl+P` | Quick Open | `chat:modelPicker` |
+| `Ctrl+R` | Open Recent | `history:search` |
+
+`Ctrl+P` and `Ctrl+F` are configured to pass through to the terminal via `terminal.integrated.commandsToSkipShell` in `devcontainer.json`. For other conflicts, use Meta (Alt) variants or customize via `config/defaults/keybindings.json`.
 
 ## Environment Variables
 
@@ -107,11 +191,14 @@ Key environment variables set in the container:
 | `WORKSPACE_ROOT` | `/workspaces` |
 | `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` |
 | `GH_CONFIG_DIR` | `/workspaces/.gh` |
-| `ANTHROPIC_MODEL` | `claude-opus-4-5-20251101` |
+| `ANTHROPIC_MODEL` | `claude-opus-4-6` |
+| `TMPDIR` | `/workspaces/.tmp` |
 
 ## Modifying Behavior
 
-1. **Change default model**: Edit `config/settings.json`, update `"model"` field
-2. **Change system prompt**: Edit `config/main-system-prompt.md`
-3. **Add features**: Add to `"features"` in `devcontainer.json`
-4. **Disable auto-setup**: Set variables to `false` in `.env`
+1. **Change default model**: Edit `config/defaults/settings.json`, update `"model"` field
+2. **Change system prompt**: Edit `config/defaults/main-system-prompt.md`
+3. **Change keybindings**: Edit `config/defaults/keybindings.json`
+4. **Add a custom config file**: Add an entry to `config/file-manifest.json` with `src`, `dest`, and optional `overwrite`/`destFilename`
+5. **Add features**: Add to `"features"` in `devcontainer.json`
+6. **Disable auto-setup**: Set variables to `false` in `.env`