codeforge-dev 1.7.0 → 1.9.0

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/)

package/.devcontainer/config/{main-system-prompt.md → defaults/main-system-prompt.md}

@@ -396,6 +396,78 @@ offset = len(header) + 1  # null terminator in legacy format
 offset = len(header) + 1  # add one to header length
 </documentation>
 
+<specification_management>
+Specs and project-level docs live in `.specs/` at the project root.
+
+You (the orchestrator) own spec creation and maintenance. Agents do not update
+specs directly — they flag when specs need attention, and you handle it.
+
+Folder structure:
+```
+.specs/
+├── roadmap.md              # What each version delivers and why (≤150 lines)
+├── lessons-learned.md      # Workflow anti-patterns
+├── ci-cd.md                # CI/CD pipeline, environments, deploy process
+├── v0.1.0.md               # Feature spec (single file per version if ≤200 lines)
+├── v0.2.0/                 # Version folder when multiple specs needed
+│   ├── overview.md         # Parent linking sub-specs (≤50 lines)
+│   └── feature-name.md     # Sub-spec per feature (≤200 lines each)
+```
+
+Spec rules:
+- ≤200 lines per spec file. Split by feature boundary if larger; link via
+  a parent overview (≤50 lines). Monolithic specs rot — no AI context window
+  can use a 4,000-line spec.
+- Reference files, don't reproduce them. Write "see `src/engine/db/migrations/002.sql`
+  lines 48-70" — never paste full schemas, SQL DDL, or type definitions. The
+  code is the source of truth; duplicated snippets go stale.
+- Each spec is independently loadable. Include version, status, last-updated,
+  intent, key file paths, and acceptance criteria in every spec file.
+
+Standard template:
+```
+# Feature: [Name]
+**Version:** v0.X.0
+**Status:** implemented | partial | planned
+**Last Updated:** YYYY-MM-DD
+
+## Intent
+## Acceptance Criteria
+## Key Files
+## Schema / Data Model (reference only — no inline DDL)
+## API Endpoints (table: Method | Path | Description)
+## Requirements (EARS format: FR-1, NFR-1)
+## Dependencies
+## Out of Scope
+## Implementation Notes (as-built deviations — post-implementation only)
+## Discrepancies (spec vs reality gaps)
+```
+
+As-built workflow (after implementing a feature):
+1. Find the feature spec: Glob `.specs/**/*.md`
+2. Set status to "implemented" or "partial"
+3. Check off acceptance criteria with passing tests
+4. Add Implementation Notes for any deviations
+5. Update file paths if they changed
+6. Update Last Updated date
+If no spec exists and the change is substantial, create one or note "spec needed."
+
+Document types — don't mix:
+- Roadmap (`.specs/roadmap.md`): what each version delivers and why. No
+  implementation detail — that belongs in feature specs. Target: ≤150 lines.
+- Feature spec (`.specs/v*.md` or `.specs/vX.Y.0/*.md`): how a feature works.
+  ≤200 lines.
+- CI/CD (`.specs/ci-cd.md`): pipeline stages, environments, deploy process,
+  and automation config. Keep declarative — reference workflow files, don't
+  reproduce them.
+- Lessons learned (`.specs/lessons-learned.md`): workflow anti-patterns.
+
+After a version ships, update feature specs to as-built status. Delete or
+merge superseded planning artifacts — don't accumulate snapshot documents.
+
+Delegate spec writing to the spec-writer agent when creating new specs.
+</specification_management>
+
 <code_standards>
 Files:
 - Small, focused, single reason to change

package/.devcontainer/config/defaults/rules/spec-workflow.md

@@ -0,0 +1,67 @@
+# Specification Workflow
+
+Every project uses `.specs/` as the specification directory. These rules are mandatory.
+
+## Rules
+
+1. Every non-trivial feature MUST have a spec before implementation begins.
+   Use `/spec-new` to create one from the standard template.
+2. Every implementation MUST end with an as-built spec update.
+   Use `/spec-update` to perform the update.
+3. Specs MUST be ≤200 lines. Split by feature boundary if larger;
+   link via a parent overview (≤50 lines).
+4. Specs MUST reference file paths, never reproduce source code,
+   schemas, or type definitions inline. The code is the source of truth.
+5. Each spec file MUST be independently loadable — include version,
+   status, last-updated, intent, key files, and acceptance criteria.
+6. Before starting a new version, MUST run `/spec-check` to audit spec health.
+7. To bootstrap `.specs/` for a project that doesn't have one, use `/spec-init`.
+
+## Directory Convention
+
+`.specs/` at the project root. Version-organized:
+
+```
+.specs/
+├── v0.1.0.md              # Single-file spec for small versions
+├── v0.2.0/                # Directory for multi-feature versions
+│   ├── _overview.md       # Feature matrix + architecture decisions
+│   ├── feature-a.md
+│   └── feature-b.md
+├── ROADMAP.md             # What each version delivers and why (≤150 lines)
+└── BACKLOG.md             # Deferred items not yet scheduled
+```
+
+## Standard Template
+
+Every spec follows this structure:
+
+```
+# Feature: [Name]
+**Version:** v0.X.0
+**Status:** implemented | partial | planned
+**Last Updated:** YYYY-MM-DD
+
+## Intent
+## Acceptance Criteria
+## Key Files
+## Schema / Data Model (reference file paths only)
+## API Endpoints (Method | Path | Description)
+## Requirements (EARS format: FR-1, NFR-1)
+## Dependencies
+## Out of Scope
+## Implementation Notes (post-implementation only)
+## Discrepancies (spec vs reality gaps)
+```
+
+## As-Built Workflow
+
+After implementing a feature:
+1. Find the spec: Glob `.specs/**/*.md`
+2. Set status to "implemented" or "partial"
+3. Check off acceptance criteria with passing tests
+4. Add Implementation Notes for any deviations
+5. Update file paths if they changed
+6. Update Last Updated date
+
+If no spec exists and the change is substantial, create one.

package/.devcontainer/config/defaults/rules/workspace-scope.md

@@ -0,0 +1,7 @@
+# Workspace Scoping Rule
+
+When working in a project subdirectory, restrict all file operations
+(reads, writes, searches, globs) to the current project directory
+unless the user explicitly requests cross-project work.
+
+Do not suggest changes to files in sibling project directories.

package/.devcontainer/config/defaults/settings.json

@@ -0,0 +1,67 @@
+{
+	"cleanupPeriodDays": 60,
+	"autoCompact": true,
+	"alwaysThinkingEnabled": true,
+	"env": {
+		"ANTHROPIC_MODEL": "claude-opus-4-6",
+		"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
+		"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-20250929",
+		"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
+		"BASH_DEFAULT_TIMEOUT_MS": "240000",
+		"BASH_MAX_TIMEOUT_MS": "600000",
+		"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000",
+		"MAX_MCP_OUTPUT_TOKENS": "10000",
+		"MAX_THINKING_TOKENS": "63999",
+		"MCP_TIMEOUT": "120000",
+		"MCP_TOOL_TIMEOUT": "30000",
+		"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "95",
+		"CLAUDE_CODE_SHELL": "zsh",
+		"FORCE_AUTOUPDATE_PLUGINS": "1",
+
+		"ENABLE_TOOL_SEARCH": "auto:5",
+		"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
+		"CLAUDE_CODE_EFFORT_LEVEL": "high",
+		"CLAUDE_CODE_ENABLE_TASKS": "true",
+		"CLAUDE_CODE_DISABLE_AUTO_MEMORY": "0",
+		"ENABLE_CLAUDE_CODE_SM_COMPACT": "1",
+		"CLAUDE_CODE_FORCE_GLOBAL_CACHE": "1",
+		"CLAUDE_CODE_PLAN_MODE_INTERVIEW_PHASE": "true",
+		"CLAUDE_CODE_PLAN_V2_AGENT_COUNT": "3",
+		"CLAUDE_CODE_PLAN_MODE_REQUIRED": "true",
+
+		"CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY": "5",
+		"CLAUDE_CODE_MAX_RETRIES": "1",
+		"BASH_MAX_OUTPUT_LENGTH": "15000",
+		"TASK_MAX_OUTPUT_LENGTH": "64000"
+	},
+	"teammateMode": "auto",
+	"effortLevel": "high",
+	"includeCoAuthoredBy": false,
+	"permissions": {
+		"allow": ["Read(/workspaces/*)", "WebFetch(domain:*)"],
+		"deny": [],
+		"ask": [],
+		"defaultMode": "plan",
+		"additionalDirectories": []
+	},
+	"model": "opus",
+	"enabledMcpjsonServers": [],
+	"disabledMcpjsonServers": [],
+	"hooks": {},
+	"statusLine": {
+		"type": "command",
+		"command": "/usr/local/bin/ccstatusline-wrapper"
+	},
+	"enabledPlugins": {
+		"frontend-design@claude-plugins-official": true,
+		"codeforge-lsp@devs-marketplace": true,
+		"ticket-workflow@devs-marketplace": true,
+		"notify-hook@devs-marketplace": true,
+		"dangerous-command-blocker@devs-marketplace": true,
+		"protected-files-guard@devs-marketplace": true,
+		"auto-formatter@devs-marketplace": true,
+		"auto-linter@devs-marketplace": true,
+		"code-directive@devs-marketplace": true
+	},
+	"autoUpdatesChannel": "latest"
+}

package/.devcontainer/config/file-manifest.json

@@ -0,0 +1,32 @@
+[
+	{
+		"src": "defaults/settings.json",
+		"dest": "${CLAUDE_CONFIG_DIR}",
+		"enabled": true,
+		"overwrite": "if-changed"
+	},
+	{
+		"src": "defaults/keybindings.json",
+		"dest": "${CLAUDE_CONFIG_DIR}",
+		"enabled": true,
+		"overwrite": "if-changed"
+	},
+	{
+		"src": "defaults/main-system-prompt.md",
+		"dest": "${CLAUDE_CONFIG_DIR}",
+		"enabled": true,
+		"overwrite": "if-changed"
+	},
+	{
+		"src": "defaults/rules/spec-workflow.md",
+		"dest": "${CLAUDE_CONFIG_DIR}/rules",
+		"enabled": true,
+		"overwrite": "if-changed"
+	},
+	{
+		"src": "defaults/rules/workspace-scope.md",
+		"dest": "${CLAUDE_CONFIG_DIR}/rules",
+		"enabled": true,
+		"overwrite": "if-changed"
+	}
+]

package/.devcontainer/devcontainer.json

@@ -12,6 +12,11 @@
     "TMPDIR": "/workspaces/.tmp"
   },
 
+  // Feature install order: external runtimes first (Node, uv, Go, Bun),
+  // then Claude Code (needs Node), then custom features.
+  // npm-dependent features (agent-browser, ccusage, ccburn, biome, lsp-servers)
+  // must come after Node. uv-dependent features (ruff, claude-monitor) must
+  // come after uv. notify-hook is last (lightweight, no dependencies).
   "overrideFeatureInstallOrder": [
     "ghcr.io/devcontainers/features/node",
     "ghcr.io/devcontainers/features/github-cli",
@@ -29,6 +34,11 @@
     "./features/ast-grep",
     "./features/tree-sitter",
     "./features/lsp-servers",
+    "./features/ruff",
+    "./features/shfmt",
+    "./features/dprint",
+    "./features/shellcheck",
+    "./features/hadolint",
     "./features/biome",
     "./features/notify-hook"
   ],
@@ -69,6 +79,16 @@
     "./features/tree-sitter": {},
     "./features/lsp-servers": {},
     "./features/agent-browser": {},
+    "./features/ruff": {
+      "version": "latest",
+      "username": "automatic"
+    },
+    "./features/shfmt": {},
+    "./features/dprint": {
+      "username": "automatic"
+    },
+    "./features/shellcheck": {},
+    "./features/hadolint": {},
     "./features/biome": {},
     "./features/notify-hook": {
       "enableBell": true,

package/.devcontainer/docs/configuration-reference.md

@@ -0,0 +1,90 @@
+# Configuration Reference
+
+Quick reference for all CodeForge configuration options.
+
+## Which File to Edit
+
+| Task | File to Edit |
+|------|-------------|
+| Change default model | `config/defaults/settings.json` |
+| Change system prompt | `config/defaults/main-system-prompt.md` |
+| Customize keybindings | `config/defaults/keybindings.json` |
+| Control setup steps | `.env` |
+| Add custom config file | `config/file-manifest.json` |
+| Disable a feature | `devcontainer.json` (set `"version": "none"`) |
+| Disable a plugin | `config/defaults/settings.json` (remove from `enabledPlugins`) |
+| Skip a plugin install | `.env` (`PLUGIN_BLACKLIST`) |
+| Change container memory | `devcontainer.json` (`runArgs`) |
+| Add VS Code extension | `devcontainer.json` (`customizations.vscode.extensions`) |
+
+## `.env` Variables (Setup Behavior)
+
+These control what `setup.sh` does on each container start. Copy `.env.example` to `.env` and customize.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Where Claude Code config files are stored |
+| `CONFIG_SOURCE_DIR` | `(auto-detected)` | Source directory for config defaults |
+| `SETUP_CONFIG` | `true` | Copy config files per `file-manifest.json` |
+| `SETUP_ALIASES` | `true` | Add cc/claude/ccraw/cc-tools aliases to shell |
+| `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` file |
+| `SETUP_PLUGINS` | `true` | Install Anthropic plugins + register local marketplace |
+| `SETUP_UPDATE_CLAUDE` | `true` | Background-update Claude Code CLI binary |
+| `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager |
+| `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip during installation |
+
+## `devcontainer.json` `remoteEnv` (Container Runtime)
+
+These environment variables are set in every terminal session inside the container.
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `WORKSPACE_ROOT` | `/workspaces` | Workspace root directory |
+| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude Code config directory |
+| `GH_CONFIG_DIR` | `/workspaces/.gh` | GitHub CLI config directory |
+| `TMPDIR` | `/workspaces/.tmp` | Temporary files directory |
+
+## `config/file-manifest.json` (File Copy Rules)
+
+Each entry in the manifest array controls how a config file is deployed:
+
+```json
+{
+  "src": "defaults/settings.json",
+  "dest": "${CLAUDE_CONFIG_DIR}",
+  "destFilename": "settings.json",
+  "overwrite": "if-changed",
+  "enabled": true
+}
+```
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `src` | Yes | — | Source file path relative to `config/` |
+| `dest` | Yes | — | Destination directory (supports `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`) |
+| `destFilename` | No | basename of `src` | Override the destination filename |
+| `overwrite` | No | `"if-changed"` | `"always"`, `"never"`, or `"if-changed"` (sha256 comparison) |
+| `enabled` | No | `true` | Set `false` to skip this entry |
+
+## Feature Options
+
+Each feature in `devcontainer.json` supports options defined in its `devcontainer-feature.json`. Common options:
+
+| Option | Description | Used By |
+|--------|-------------|---------|
+| `version` | Tool version to install. `"none"` skips installation. | All local features |
+| `username` | Container user to install for. `"automatic"` auto-detects. | dprint, ruff, ccusage, ccburn, etc. |
+| `shells` | Which shell rc files to modify (`"both"`, `"bash"`, `"zsh"`). | ccusage, ccburn |
+
+## `.secrets` File (Authentication)
+
+Create `.devcontainer/.secrets` with tokens for automatic authentication:
+
+```bash
+GH_TOKEN=ghp_your_token_here
+GH_USERNAME=your-github-username
+GH_EMAIL=your-email@example.com
+NPM_TOKEN=npm_your_token_here
+```
+
+Environment variables with the same names take precedence over `.secrets` file values (useful for Codespaces).