Pre-release cleanup: version sync, changelog reorg, docs, config quick wins (#41)

AnExiledDev · web-flow · commit 6fe72f43d978 · 2026-03-01T21:45:28.000-06:00
- Bump package.json to 2.0.0 (was still 1.14.2)
- Fold all unreleased changelog content into v2.0.0 with area-first headings
- Document --reset flag in README.md and installation guide
- Streamline CLAUDE.md from 205 to 77 lines (remove discoverable reference material)
- Add SETUP_TERMINAL, SETUP_POSTSTART, PROJECT_EXCLUDE_DIRS, OFFICIAL_PLUGINS to .env.example
- Make project exclusion dirs and official plugins list configurable via .env

Co-authored-by: AnExiledDev &lt;AnExiledDev@users.noreply.github.com&gt;
diff --git a/.devcontainer/.env.example b/.devcontainer/.env.example
@@ -22,8 +22,20 @@ SETUP_PLUGINS=true
 SETUP_UPDATE_CLAUDE=true
 
 # Setup: auto-detect projects for VS Code Project Manager extension
+# Setup: configure VS Code Shift+Enter keybinding for Claude Code terminal
+SETUP_TERMINAL=true
+
+# Setup: run post-start hooks from /usr/local/devcontainer-poststart.d/
+SETUP_POSTSTART=true
+
 SETUP_PROJECTS=true
 
 # Plugin blacklist: comma-separated plugin names to skip during installation
 # Example: PLUGIN_BLACKLIST="ticket-workflow,auto-linter"
 PLUGIN_BLACKLIST=""
+
+# Project detection: directories to exclude from auto-detection (space-separated)
+# PROJECT_EXCLUDE_DIRS=".claude .gh .tmp .devcontainer .config node_modules .git"
+
+# Official plugins: space-separated list installed from Anthropic/third-party marketplaces
+# OFFICIAL_PLUGINS="frontend-design@claude-plugins-official svelte@sveltejs/mcp"
diff --git a/.devcontainer/CHANGELOG.md b/.devcontainer/CHANGELOG.md
diff --git a/.devcontainer/CLAUDE.md b/.devcontainer/CLAUDE.md
@@ -2,32 +2,6 @@
 
 CodeForge devcontainer for AI-assisted development with Claude Code.
 
-## Directory Structure
-
-```
-.devcontainer/
-├── devcontainer.json          # Container definition
-├── .env                       # Setup flags (SETUP_CONFIG, SETUP_ALIASES, etc.)
-├── features/                  # Custom devcontainer features
-├── plugins/devs-marketplace/  # Local plugin marketplace
-└── scripts/                   # Setup scripts (run via postStartCommand)
-
-.codeforge/
-├── file-manifest.json         # Declarative config file deployment
-├── config/                    # Source files deployed on start via file-manifest
-│   ├── settings.json          # Model, permissions, plugins, env vars
-│   ├── keybindings.json       # Keyboard shortcuts
-│   ├── main-system-prompt.md
-│   ├── orchestrator-system-prompt.md
-│   ├── writing-system-prompt.md
-│   ├── ccstatusline-settings.json  # Status bar widget layout
-│   └── rules/                 # Deployed to .claude/rules/
-├── scripts/                   # Terminal connection scripts
-│   ├── connect-external-terminal.sh
-│   └── connect-external-terminal.ps1
-└── .codeforge-preserve        # Lists additional files to preserve during updates
-```
-
 ## Key Configuration
 
 | File | Purpose |
@@ -42,50 +16,21 @@ CodeForge devcontainer for AI-assisted development with Claude Code.
 
 Config files deploy via `.codeforge/file-manifest.json` on every container start. Most deploy to `~/.claude/`; ccstatusline config deploys to `~/.config/ccstatusline/`. Each entry supports `overwrite`: `"if-changed"` (default, sha256), `"always"`, or `"never"`. Supported variables: `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`, `${HOME}`.
 
-## Worktrees
-
-Git worktrees allow checking out multiple branches simultaneously, each in its own directory.
-
-**Native (recommended for Claude Code sessions):**
-- **In-session:** `EnterWorktree` tool — creates worktree at `<repo>/.claude/worktrees/<name>/`, branch `worktree-<name>`, auto-cleaned if no changes
-- **New session:** `claude --worktree <name>` — starts Claude in its own worktree; combine with `--tmux` for background work
-
-**Manual (legacy convention):**
-```bash
-mkdir -p /workspaces/projects/.worktrees
-git worktree add /workspaces/projects/.worktrees/<branch-name> -b <branch>
-```
-
-**Environment files:** Place a `.worktreeinclude` file at the project root listing `.gitignore`-excluded files to copy into new worktrees (e.g., `.env`). Uses `.gitignore` pattern syntax; only files matching both `.worktreeinclude` and `.gitignore` are copied.
-
-**Management:**
-
-| Command | Purpose |
-|---------|---------|
-| `git worktree list` | Show all active worktrees |
-| `git worktree remove <path>` | Remove a worktree (destructive — confirm first) |
-| `git worktree prune` | Clean up stale references (destructive — confirm first) |
-
-**Path conventions:**
-- **Native:** `<repo>/.claude/worktrees/<name>/` — used by `--worktree` flag and `EnterWorktree`
-- **Legacy:** `.worktrees/` as sibling to the main repo — used for manual `git worktree add` and Project Manager integration
-
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
 | `cc` / `claude` | Run Claude Code with auto-configuration |
 | `codeforge config apply` | Deploy config files to `~/.claude/` (same as container start) |
-| `codeforge` | CLI for CodeForge management commands |
 | `ccraw` | Vanilla Claude Code (bypasses config) |
 | `ccw` | Claude Code with writing system prompt |
 | `cc-orc` | Claude Code in orchestrator mode (delegation-first) |
-| ~~`ccms`~~ | _(commented out — replacement pending)_ |
+| `ccms` | Session history search _(disabled — requires Rust toolchain; uncomment in devcontainer.json to enable)_ |
 | `ccusage` / `ccburn` | Token usage analysis / burn rate |
 | `agent-browser` | Headless Chromium (Playwright-based) |
 | `check-setup` | Verify CodeForge setup health |
 | `claude-dashboard` | Session analytics dashboard (port 7847) |
-| `dbr` | Dynamic port forwarding (devcontainer-bridge) |
+| `dbr` | Dynamic port forwarding ([devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge)) |
 | `cc-tools` | List all installed tools with versions |
 
 ## Plugins
@@ -115,19 +60,6 @@ Rules in `.codeforge/config/rules/` deploy to `.claude/rules/` on every containe
 
 **Adding rules:** Create `.md` in `.codeforge/config/rules/`, add a manifest entry in `.codeforge/file-manifest.json`.
 
-## Environment
-
-| Variable | Value |
-|----------|-------|
-| `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` |
-| `CLAUDE_AUTH_TOKEN` | Long-lived token from `claude setup-token` (optional, via `.secrets` or Codespaces secrets) |
-| `ANTHROPIC_MODEL` | `claude-opus-4-6` |
-| `WORKSPACE_ROOT` | `/workspaces` |
-| `TERM` | `${localEnv:TERM:xterm-256color}` (via `remoteEnv` — forwards host TERM, falls back to 256-color) |
-| `COLORTERM` | `truecolor` (via `remoteEnv` — enables 24-bit color support) |
-
-All experimental feature flags are in `settings.json` under `env`. Setup steps controlled by boolean flags in `.env`.
-
 ## Authentication & Persistence
 
 The `~/.claude/` directory is backed by a Docker named volume (`codeforge-claude-config-${devcontainerId}`), persisting config, credentials, and session data across container rebuilds. Each devcontainer instance gets an isolated volume.
@@ -142,63 +74,4 @@ The `~/.claude/` directory is backed by a Docker named volume (`codeforge-claude
 4. **Add features**: Add to `"features"` in `devcontainer.json`
 5. **Disable features**: Set `"version": "none"` in the feature's config
 6. **Disable setup steps**: Set flags to `false` in `.env`
-7. **Customize status bar**: Edit `.codeforge/config/ccstatusline-settings.json` (see below)
-
-## Status Bar Widgets
-
-The status bar is configured in `.codeforge/config/ccstatusline-settings.json` (deploys to `~/.config/ccstatusline/settings.json`). Each widget is a JSON object in a line array.
-
-### Widget Properties
-
-| Property | Purpose |
-|----------|---------|
-| `id` | Unique identifier (UUID or descriptive string) |
-| `type` | Widget type (see below) |
-| `backgroundColor` | Background color: `bgBlue`, `bgMagenta`, `bgYellow`, `bgGreen`, `bgRed`, etc. |
-| `color` | Text color: `brightWhite`, `black`, `cyan`, `yellow`, etc. |
-| `rawValue` | `true` to strip type-specific prefixes (e.g., removes "Model:" from model widget) |
-| `bold` | `true` for bold text |
-| `merge` | `"no-padding"` fuses this widget to the next (no separator/space between them) |
-| `customText` | Static text content (only for `custom-text` type) |
-
-### Token Widgets
-
-Each token metric uses a distinct background color for at-a-glance identification:
-
-| Type | Color | Label |
-|------|-------|-------|
-| `tokens-input` | Blue (`bgBlue`) | **In** |
-| `tokens-output` | Magenta (`bgMagenta`) | **Ou** |
-| `tokens-cached` | Yellow (`bgYellow`) | **Ca** |
-| `tokens-total` | Green (`bgGreen`) | **Tt** |
-
-Labels are `custom-text` widgets with `merge: "no-padding"` so they fuse visually to their data widget:
-
-```json
-{ "id": "lbl-tokens-input", "type": "custom-text", "customText": "In",
-  "backgroundColor": "bgBlue", "color": "brightWhite", "bold": true, "merge": "no-padding" },
-{ "id": "5", "type": "tokens-input",
-  "backgroundColor": "bgBlue", "color": "brightWhite", "rawValue": true }
-```
-
-### Other Widget Types
-
-`model`, `context-length`, `context-percentage-usable`, `git-branch`, `git-changes`, `git-worktree`, `session-clock`, `session-cost`, `block-timer`, `version`, `custom-command`
-
-## Features
-
-Custom features in `./features/` follow the [devcontainer feature spec](https://containers.dev/implementors/features/). Every local feature supports `"version": "none"` to skip installation. Claude Code is installed as a native binary via `./features/claude-code-native` (uses Anthropic's official installer at `https://claude.ai/install.sh`).
-
-## Port Forwarding
-
-Three mechanisms handle port access depending on your client:
-
-| Mechanism | Client | Discovery |
-|-----------|--------|-----------|
-| VS Code auto-detect | VS Code only | Dynamic — all ports auto-forwarded with notification |
-| devcontainer-bridge (`dbr`) | Any terminal client | Dynamic — polls `/proc/net/tcp` |
-| SSH tunneling | Any SSH client | Manual — `ssh -L localPort:localhost:remotePort` |
-
-VS Code auto-detects all ports opened inside the container (configured via `portsAttributes` in `devcontainer.json`). Outside VS Code, `dbr` provides dynamic port discovery via a reverse connection model (container→host). The container daemon auto-starts and is inert without the host daemon (`dbr host-daemon`). Both mechanisms coexist. See [devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge).
-
-For full setup instructions, see the [Port Forwarding reference](https://codeforge.core-directive.com/reference/port-forwarding/) in the docs.
+7. **Customize status bar**: Edit `.codeforge/config/ccstatusline-settings.json`
diff --git a/.devcontainer/scripts/setup-plugins.sh b/.devcontainer/scripts/setup-plugins.sh
@@ -22,10 +22,8 @@ fi
 echo "[setup-plugins] Installing plugins..."
 
 # --- Official Anthropic Plugins ---
-OFFICIAL_PLUGINS=(
-    "frontend-design@claude-plugins-official"
-    "svelte@sveltejs/mcp"
-)
+DEFAULT_OFFICIAL_PLUGINS="frontend-design@claude-plugins-official svelte@sveltejs/mcp"
+IFS=' ' read -ra OFFICIAL_PLUGINS <<< "${OFFICIAL_PLUGINS:-$DEFAULT_OFFICIAL_PLUGINS}"
 
 for plugin in "${OFFICIAL_PLUGINS[@]}"; do
     echo "[setup-plugins] Installing $plugin..."
diff --git a/.devcontainer/scripts/setup-projects.sh b/.devcontainer/scripts/setup-projects.sh
@@ -14,7 +14,7 @@ PID_FILE="/tmp/project-watcher.pid"
 LOG_PREFIX="[setup-projects]"
 
 # Directories to exclude from project detection (hidden/config dirs)
-EXCLUDED_DIRS=".claude .gh .tmp .devcontainer .config node_modules .git"
+EXCLUDED_DIRS="${PROJECT_EXCLUDE_DIRS:-.claude .gh .tmp .devcontainer .config node_modules .git}"
 
 # --- Helpers ---
 
diff --git a/README.md b/README.md
@@ -30,8 +30,9 @@ This copies the `.devcontainer/` directory to your project. Then open in VS Code
 ### Options
 
 ```bash
-npx codeforge-dev --force    # Overwrite existing .devcontainer directory
+npx codeforge-dev --force    # Smart update (preserves your customizations)
 npx codeforge-dev -f         # Short form
+npx codeforge-dev --reset    # Fresh install (wipes .devcontainer, keeps .codeforge)
 ```
 
 ### Alternative Install Methods
diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md
@@ -18,11 +18,16 @@ npx codeforge-dev
 This creates a `.devcontainer/` directory containing the full CodeForge configuration — all plugins, features, agents, skills, system prompts, and settings. Your existing project files are not modified.
 
 :::tip[Already have a .devcontainer?]
-If your project already has a `.devcontainer/` directory, the installer will warn you and exit. Use the `--force` flag to perform a smart sync that preserves your user configuration:
+If your project already has a `.devcontainer/` directory, the installer will warn you and exit. Two flags handle this:
+
 ```bash
-npx codeforge-dev --force
+npx codeforge-dev --force    # Smart update (preserves your customizations)
+npx codeforge-dev --reset    # Fresh install (wipes .devcontainer, keeps .codeforge)
 ```
-The `--force` flag uses an intelligent sync — it preserves files you've customized (writing `.default` copies of new defaults in `.codeforge/` for review) rather than blindly overwriting everything.
+
+**`--force`** uses an intelligent sync — it preserves files you've customized (writing `.default` copies of new defaults in `.codeforge/` for review) rather than blindly overwriting everything. Use this for routine updates.
+
+**`--reset`** deletes `.devcontainer/` entirely and copies clean defaults from the package. Your `.codeforge/` user configuration is always preserved. Use this when `.devcontainer/` is corrupted or you want a clean slate.
 :::
 
 ### Alternative Installation Methods
@@ -33,7 +38,7 @@ npm install -g codeforge-dev
 codeforge-dev
 
 # Pin a specific version
-npx codeforge-dev@1.14.0
+npx codeforge-dev@2.0.0
 ```
 
 ### What the Installer Creates
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "codeforge-dev",
-	"version": "1.14.2",
+	"version": "2.0.0",
 	"description": "Complete development container that sets up Claude Code with modular devcontainer features, modern dev tools, and persistent configurations. Drop it into any project and get a production-ready AI development environment in minutes.",
 	"main": "setup.js",
 	"bin": {

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "codeforge-dev",`
`3`		`- "version": "1.14.2",`
	`3`	`+ "version": "2.0.0",`
`4`	`4`	`"description": "Complete development container that sets up Claude Code with modular devcontainer features, modern dev tools, and persistent configurations. Drop it into any project and get a production-ready AI development environment in minutes.",`
`5`	`5`	`"main": "setup.js",`
`6`	`6`	`"bin": {`