codeforge-dev 1.7.0 → 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,6 +21,4 @@ SETUP_PLUGINS=true
 SETUP_UPDATE_CLAUDE=true
 
 # Plugin blacklist (comma-separated plugin names to skip during auto-install)
-# workflow-enhancer: Not fully implemented yet — scaffolding only
-# planning-reminder: Redundant with Claude Code v2.1+ which auto-switches to plan mode
-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,135 @@
 # 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

package/.devcontainer/CLAUDE.md

@@ -10,15 +10,17 @@ 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
-│   │   ├── keybindings.json # Claude Code keybindings
-│   │   └── 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 (OVERWRITE_CONFIG=true → rebuilt each start)
+│   ├── 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)
@@ -31,11 +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/keybindings.json` | Claude Code keybindings (empty by default — customizable) |
-| `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**: `OVERWRITE_CONFIG=true` (default) means `.claude/settings.json` is overwritten on every container start. All persistent changes must go in `.devcontainer/config/settings.json`.
+> **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
 
@@ -48,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
 
@@ -68,7 +73,38 @@ To test a feature locally, reference it in `devcontainer.json`:
 }
 ```
 
-> **Note**: The old `./features/claude-code` local feature is no longer used. Claude Code is installed via `ghcr.io/anthropics/devcontainer-features/claude-code:1` (Anthropic's official feature). The local `features/claude-code/` directory contains only a fallback config for the feature's install script.
+> **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
 
@@ -77,7 +113,7 @@ Scripts in `./scripts/` run via `postStartCommand`:
 | Script | Purpose |
 |--------|---------|
 | `setup.sh` | Main orchestrator |
-| `setup-config.sh` | Copies config files (settings, keybindings, system prompt) to `/workspaces/.claude/` |
+| `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 |
@@ -86,7 +122,7 @@ Scripts in `./scripts/` run via `postStartCommand`:
 
 ## Installed Plugins
 
-Plugins are declared in `config/settings.json` under `enabledPlugins` and auto-activated 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
@@ -97,8 +133,8 @@ Plugins are declared in `config/settings.json` under `enabledPlugins` and auto-a
 - `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` — Auto-formats Python/Go/JS/TS on stop
-- `auto-linter@devs-marketplace` — Auto-lints Python files via Pyright
+- `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
@@ -144,7 +180,7 @@ Claude Code runs inside VS Code's integrated terminal. VS Code intercepts some s
 | `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/keybindings.json`.
+`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
 
@@ -160,8 +196,9 @@ Key environment variables set in the container:
 
 ## Modifying Behavior
 
-1. **Change default model**: Edit `config/settings.json`, update `"model"` field
-2. **Change system prompt**: Edit `config/main-system-prompt.md`
-3. **Change keybindings**: Edit `config/keybindings.json`
-4. **Add features**: Add to `"features"` in `devcontainer.json`
-5. **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`

package/.devcontainer/README.md

@@ -1,34 +1,21 @@
-# CodeForge DevContainer
+# CodeForge Usage Guide
 
-[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![npm version](https://img.shields.io/npm/v/codeforge-dev.svg)](https://www.npmjs.com/package/codeforge-dev)
-
-A curated development environment optimized for AI-powered coding with Claude Code. CodeForge comes pre-configured with language servers, code intelligence tools, and official Anthropic plugins to streamline your development workflow.
-
-## Prerequisites
-
-- **Docker Desktop** (or compatible container runtime like Podman)
-- **VS Code** with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), or **GitHub Codespaces**
-- **Claude Code authentication** - see [Authentication](#authentication) section
+Everything you need to know once you're inside the devcontainer.
 
 ## Quick Start
 
-1. **Open in Container**
-   - VS Code: Open the folder, then select "Reopen in Container" from the command palette
-   - Codespaces: Create a new codespace from this repository
-
-2. **Authenticate** (first time only)
+1. **Authenticate** (first time only)
    ```bash
    claude
    ```
    Follow the prompts to authenticate via browser or API key.
 
-3. **Start Claude Code**
+2. **Start Claude Code**
    ```bash
    cc
    ```
 
-## Authentication
+## Claude Code Authentication
 
 Claude Code supports multiple authentication methods. On first run, you'll be prompted to choose:
 
@@ -57,11 +44,39 @@ Authentication credentials are stored in `/workspaces/.claude/` and persist acro
 
 For more options, see the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).
 
-## GitHub CLI Authentication
+## GitHub & NPM Authentication
 
-GitHub CLI (`gh`) is pre-installed for repository operations like pushing code, creating pull requests, and accessing private repositories.
+### Automatic Auth via `.secrets` (Recommended)
+
+CodeForge can automatically configure GitHub CLI, git identity, and NPM auth on every container start. Copy the template and fill in your tokens:
+
+```bash
+cp .devcontainer/.secrets.example .devcontainer/.secrets
+```
+
+Edit `.devcontainer/.secrets`:
+
+```bash
+GH_TOKEN=ghp_your_token_here
+GH_USERNAME=your-github-username
+GH_EMAIL=your-email@example.com
+NPM_TOKEN=npm_your_token_here
+```
+
+On the next container start (or rebuild), `setup-auth.sh` will:
+- Authenticate `gh` CLI and configure git credential helper
+- Set `git config --global user.name` and `user.email`
+- Set NPM registry auth token
+
+The `.secrets` file is gitignored at two levels (root `.*` + `.devcontainer/.gitignore`) and will never be committed.
+
+**Environment variable fallback**: For Codespaces or CI, set `GH_TOKEN`, `GH_USERNAME`, `GH_EMAIL`, and/or `NPM_TOKEN` as environment variables (e.g., via Codespaces secrets or `localEnv` in `devcontainer.json`). Environment variables take precedence over `.secrets` file values.
+
+Disable automatic auth by setting `SETUP_AUTH=false` in `.devcontainer/.env`.
 
-### Interactive Login (Recommended)
+### Interactive Login (Alternative)
+
+GitHub CLI (`gh`) is pre-installed for repository operations like pushing code, creating pull requests, and accessing private repositories.
 
 ```bash
 gh auth login
@@ -98,7 +113,28 @@ Expected output shows your authenticated account and token scopes.
 
 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.
 
-**You only need to authenticate once.** After running `gh auth login`, your credentials will survive container rebuilds and be available in future sessions.
+**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.
+
+## Using Claude Code
+
+### 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`.
+
+```bash
+cc                    # Start Claude Code in current directory
+cc "explain this"     # Start with an initial prompt
+```
+
+### Direct CLI
+
+For more control, use the `claude` command directly:
+
+```bash
+claude                        # Basic invocation
+claude --help                 # View all options
+claude --resume               # Resume previous session
+```
 
 ## Available Tools
 
@@ -109,6 +145,7 @@ GitHub CLI credentials are automatically persisted across container rebuilds. Th
 | Node.js LTS | JavaScript runtime |
 | TypeScript | Via Node.js |
 | Go | Latest stable via devcontainer feature |
+| Bun | Fast JavaScript runtime and toolkit |
 
 ### Package Managers
 | Tool | Description |
@@ -126,7 +163,12 @@ GitHub CLI credentials are automatically persisted across container rebuilds. Th
 | `jq` | JSON processor |
 | `curl` | HTTP client |
 | `tmux` | Terminal multiplexer for Agent Teams split-pane sessions |
-| `biome` | Fast JS/TS/JSON/CSS formatter |
+| `biome` | Fast JS/TS/JSON/CSS formatter and linter |
+| `ruff` | Fast Python linter and formatter (replaces Black + Flake8) |
+| `shfmt` | Shell script formatter |
+| `dprint` | Pluggable formatter for Markdown, YAML, TOML, Dockerfile |
+| `shellcheck` | Static analysis tool for shell scripts |
+| `hadolint` | Dockerfile linter |
 | `agent-browser` | Headless browser automation for AI agents |
 
 ### Code Intelligence
@@ -144,47 +186,38 @@ GitHub CLI credentials are automatically persisted across container rebuilds. Th
 | `cc` | Wrapper with auto-configuration |
 | `ccusage` | Token usage analyzer |
 | `ccburn` | Visual token burn rate tracker with pace indicators |
-| `ccstatusline` | 6-line powerline status display (v1.1.0) |
+| `ccstatusline` | Status bar display (integrated into Claude Code, not standalone CLI) |
 | `claude-monitor` | Real-time usage tracking |
 
-## Using Claude Code
-
-### 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`.
-
-```bash
-cc                    # Start Claude Code in current directory
-cc "explain this"     # Start with an initial prompt
-```
-
-### Direct CLI
-
-For more control, use the `claude` command directly:
-
-```bash
-claude                        # Basic invocation
-claude --help                 # View all options
-claude --resume               # Resume previous session
-```
-
 ## Configuration
 
 ### Environment Variables
 
-Edit `.devcontainer/.env` to customize behavior:
+Copy `.devcontainer/.env.example` to `.devcontainer/.env` and customize:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude configuration directory |
-| `SETUP_CONFIG` | `true` | Copy config files during setup |
-| `OVERWRITE_CONFIG` | `true` | Overwrite existing configs |
-| `SETUP_ALIASES` | `true` | Add `cc` alias to shell |
-| `SETUP_PLUGINS` | `true` | Install official plugins |
+| `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` |
+| `SETUP_PLUGINS` | `true` | Install official plugins + register marketplace |
+| `SETUP_UPDATE_CLAUDE` | `true` | Auto-update Claude Code on container start |
+| `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager |
+| `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip |
 
 ### Claude Code Settings
 
-Default settings are in `.devcontainer/config/settings.json`. These are copied to `/workspaces/.claude/settings.json` on first run.
+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"`).
+
+To add a custom config file, append an entry to `file-manifest.json`:
+```json
+{
+  "src": "my-config.json",
+  "dest": "${WORKSPACE_ROOT}",
+  "overwrite": "if-changed"
+}
+```
 
 Key defaults:
 - **Model**: Claude Opus 4-6
@@ -193,7 +226,7 @@ Key defaults:
 
 ### Keybindings
 
-Default keybindings are in `.devcontainer/config/keybindings.json` (empty by default — Claude Code defaults apply). Customize by adding entries to the `bindings` array.
+Default keybindings are in `.devcontainer/config/defaults/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:
 
@@ -210,7 +243,7 @@ For conflicting shortcuts, use Meta (Alt) variants or add custom keybindings.
 
 ### System Prompt
 
-The default system prompt is in `.devcontainer/config/main-system-prompt.md`. Override it by creating a `.claude/system-prompt.md` in your project directory.
+The default system prompt is in `.devcontainer/config/defaults/main-system-prompt.md`. Override it by creating a `.claude/system-prompt.md` in your project directory.
 
 ## Custom Features
 
@@ -223,7 +256,7 @@ CodeForge includes several custom devcontainer features:
 | `claude-monitor` | Real-time token usage monitoring with ML predictions |
 | `ccusage` | Usage analytics CLI |
 | `ccburn` | Visual token burn rate tracker with pace indicators |
-| `ccstatusline` | 6-line powerline status display (v1.1.0) |
+| `ccstatusline` | Status bar display (integrated into Claude Code, not standalone CLI) |
 | `ast-grep` | Structural code search using AST patterns |
 | `tree-sitter` | Parser with JS/TS/Python grammars |
 | `lsp-servers` | Pyright and TypeScript language servers |
@@ -274,12 +307,34 @@ 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
-- **Project-local config**: Config files are auto-copied to `.claude/` on container start via `setup-config.sh`
-- **GitHub auth persists**: Run `gh auth login` once; credentials survive container rebuilds (stored in `/workspaces/.gh/`)
+- **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`
+- **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
 
+## Troubleshooting
+
+Common issues and solutions. For detailed troubleshooting, see [docs/troubleshooting.md](docs/troubleshooting.md).
+
+| 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` |
+| 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 |
+
 ## 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, mcp-reasoner, splitrail
+- [Keybinding Customization](docs/keybindings.md) — resolving VS Code conflicts
+- [Troubleshooting](docs/troubleshooting.md) — common issues and solutions
+
+**External**:
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
 - [Dev Containers Specification](https://containers.dev/)
 - [GitHub CLI Manual](https://cli.github.com/manual/)