codeforge-dev 1.14.1 → 2.0.1

package/README.md

@@ -7,9 +7,16 @@
 [![npm downloads](https://img.shields.io/npm/dm/codeforge-dev)](https://www.npmjs.com/package/codeforge-dev)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org/)
 [![GitHub issues](https://img.shields.io/github/issues/AnExiledDev/CodeForge)](https://github.com/AnExiledDev/CodeForge/issues)
+[![CI](https://github.com/AnExiledDev/CodeForge/actions/workflows/ci.yml/badge.svg)](https://github.com/AnExiledDev/CodeForge/actions/workflows/ci.yml)
 
 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.
 
+## Why CodeForge?
+
+Claude Code is powerful out of the box, but getting the most from it takes significant configuration — custom agents, safety plugins, code quality hooks, system prompts, and development tools that aren't obvious from the docs. CodeForge is a Claude Code power user's personal development environment, packaged so anyone can use it.
+
+Instead of spending hours discovering and configuring advanced features like built-in agent replacement, automated code quality pipelines, or spec-driven workflows, you get a production-tested setup in one command. It's opinionated by design — every default reflects real daily use, not theoretical best practices.
+
 ## Installation
 
 Add CodeForge to any project:
@@ -23,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
@@ -41,7 +49,12 @@ npx codeforge-dev@1.2.3
 ## 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**
+- **A DevContainer client** — any of:
+  - **VS Code** with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+  - **DevContainer CLI** — `npm install -g @devcontainers/cli` ([docs](https://containers.dev/supporting#devcontainer-cli))
+  - **GitHub Codespaces** — zero local setup
+  - **JetBrains Gateway** with [Dev Containers plugin](https://plugins.jetbrains.com/plugin/21962-dev-containers)
+  - **DevPod** — open-source, editor-agnostic ([devpod.sh](https://devpod.sh/))
 - **Claude Code authentication** — run `claude` on first start to authenticate
 
 ## What's Included
@@ -70,18 +83,80 @@ tree-sitter (JS/TS/Python), ast-grep, Pyright, TypeScript LSP
 
 tmux, agent-browser, claude-monitor, ccusage, ccburn, ccstatusline, ast-grep, tree-sitter, lsp-servers, biome, ruff, shfmt, shellcheck, hadolint, dprint, ccms, notify-hook, mcp-qdrant, chromaterm, kitty-terminfo, claude-session-dashboard
 
-### Agents (17) & Skills (34)
+### Agents (17) & Skills (35)
+
+The `agent-system` plugin includes 17 specialized agents (architect, explorer, test-writer, security-auditor, etc.). The `skill-engine` plugin provides 22 general coding skills, `spec-workflow` adds 8 spec lifecycle skills, and `ticket-workflow` provides 4 ticket management skills.
+
+## Architecture
+
+CodeForge operates in three layers, each building on the one below:
+
+```
+┌──────────────────────────────────────────────┐
+│                 Claude Code                   │
+│   AI assistant, tool execution, Agent Teams   │
+├──────────────────────────────────────────────┤
+│               CodeForge Layer                 │
+│   Plugins · Agents · Skills · Hooks · Rules   │
+├──────────────────────────────────────────────┤
+│                DevContainer                   │
+│   Runtimes · CLI Tools · LSP Servers          │
+└──────────────────────────────────────────────┘
+```
+
+**DevContainer** — The foundation. A Python 3.14 container with Node.js, Rust, and Bun runtimes, plus 22 custom features that install development tools (ast-grep, tree-sitter, biome, ruff, and others).
+
+**CodeForge Layer** — The intelligence. 17 plugins register hooks that validate commands, inject context, and enforce safety. 21 agents provide specialized personas. 38 skills offer on-demand reference material. System prompts and rules shape behavior.
 
-The `agent-system` plugin includes 17 specialized agents (architect, explorer, test-writer, security-auditor, etc.). The `skill-engine` plugin provides 21 general coding skills, `spec-workflow` adds 8 spec lifecycle skills, and `ticket-workflow` provides 4 ticket management skills.
+**Claude Code** — The AI assistant, executing tools and coordinating work. CodeForge enhances it through configuration — replacing built-in subagents, adding safety guardrails, and wiring up quality checks that run automatically.
+
+For the full architecture breakdown — hook pipeline, agent routing, skill loading, and design principles — see the [Architecture Reference](https://codeforge.core-directive.com/reference/architecture/).
+
+## Configuration
+
+All configuration lives in `.devcontainer/` and deploys automatically on container start. Key files:
+
+| File | What It Configures | User-Modifiable? |
+|------|--------------------|------------------|
+| `config/defaults/settings.json` | Model, plugins, permissions, environment variables | Yes |
+| `config/defaults/main-system-prompt.md` | Claude's behavioral guidelines and directives | Yes |
+| `config/defaults/keybindings.json` | Keyboard shortcuts | Yes |
+| `config/defaults/ccstatusline-settings.json` | Terminal status bar widgets and layout | Yes |
+| `config/file-manifest.json` | Which config files deploy and how they update | Yes |
+| `devcontainer.json` | Container image, features, runtimes, ports | Yes |
+| `.env` | Setup phase toggles (auth, plugins, aliases, etc.) | Yes |
+
+Config files use SHA-256 change detection — your edits persist across container rebuilds unless the source changes. Set a file's overwrite mode to `"never"` in `file-manifest.json` to permanently preserve your customizations.
+
+For the complete configuration guide, see the [documentation site](https://codeforge.core-directive.com/customization/configuration/).
 
 ## Quick Start
 
 1. **Install**: `npx codeforge-dev`
-2. **Open in Container**: "Reopen in Container" in VS Code, or create a Codespace
+2. **Open in Container**:
+   - **VS Code**: "Reopen in Container" from the Command Palette
+   - **CLI**: `devcontainer up --workspace-folder .` then `docker exec -it <container> zsh`
+   - **Codespaces**: Create a Codespace from the repo
 3. **Authenticate**: Run `claude` and follow prompts
 4. **Start coding**: Run `cc`
 
-For full usage documentation — authentication, configuration, tools, agents, and keybindings — see [`.devcontainer/README.md`](.devcontainer/README.md).
+CodeForge uses the open [Dev Containers specification](https://containers.dev/) — any compatible client works. For full usage documentation — authentication, configuration, tools, agents, and keybindings — see [`.devcontainer/README.md`](.devcontainer/README.md).
+
+## Contributing
+
+We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md)
+before submitting a pull request. All contributions require signing our
+[Contributor License Agreement](CLA.md).
+
+## License
+
+This project is licensed under the [GNU General Public License v3.0](LICENSE.txt).
+
+**Commercial licensing** is available for organizations that need to use CodeForge
+without GPL-3.0 obligations. Contact
+[696222+AnExiledDev@users.noreply.github.com](mailto:696222+AnExiledDev@users.noreply.github.com)
+or [open a GitHub issue](https://github.com/AnExiledDev/CodeForge/issues/new)
+for terms.
 
 ## Development
 
@@ -102,7 +177,7 @@ npm publish
 
 ## Changelog
 
-See [CHANGELOG.md](.devcontainer/CHANGELOG.md) for release history. Current version: **1.14.0** (2026-02-23).
+See [CHANGELOG.md](.devcontainer/CHANGELOG.md) for release history. Current version: **2.0.0**.
 
 ## Further Reading
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codeforge-dev",
-	"version": "1.14.1",
+	"version": "2.0.1",
 	"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": {
@@ -8,6 +8,8 @@
 	},
 	"scripts": {
 		"test": "node test.js",
+		"test:plugins": "pytest tests/ -v",
+		"test:all": "npm test && pytest tests/ -v",
 		"prepublishOnly": "npm test",
 		"docs:dev": "npm run dev --prefix docs",
 		"docs:build": "npm run build --prefix docs",
@@ -30,6 +32,7 @@
 	"license": "GPL-3.0",
 	"files": [
 		".devcontainer/**/*",
+		".codeforge/**/*",
 		"setup.js",
 		"README.md"
 	],

package/setup.js

@@ -1,19 +1,16 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (c) 2026 Marcus Krueger
 
-const fs = require("fs");
-const path = require("path");
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
 
 // ── Default preserve list ────────────────────────────────────────
-// Files in the package that should NOT overwrite user customizations.
+// Files in .devcontainer that should NOT overwrite user customizations.
 // The package version is saved as <file>.codeforge-new for diffing.
-const DEFAULT_PRESERVE = [
-	"config/defaults/settings.json",
-	"config/defaults/main-system-prompt.md",
-	"config/defaults/keybindings.json",
-	"config/defaults/ccstatusline-settings.json",
-	"config/file-manifest.json",
-	".codeforge-preserve",
-];
+// Note: .codeforge/ uses checksum-based preservation instead.
+const DEFAULT_PRESERVE = [".codeforge-preserve"];
 
 // ── copyDirectory ────────────────────────────────────────────────
 // Simple recursive copy (used for fresh install and --reset).
@@ -54,6 +51,173 @@ function loadPreserveList(devcontainerDest) {
 	return new Set([...DEFAULT_PRESERVE, ...custom]);
 }
 
+// ── computeChecksum ──────────────────────────────────────────────
+// Returns SHA-256 hex digest of a file's contents.
+function computeChecksum(filePath) {
+	return crypto
+		.createHash("sha256")
+		.update(fs.readFileSync(filePath))
+		.digest("hex");
+}
+
+// ── generateChecksums ────────────────────────────────────────────
+// Walks directory recursively, returns { relativePath: sha256hex } map.
+// Skips .checksums/ and .markers/ directories.
+function generateChecksums(dir) {
+	const checksums = {};
+
+	function walk(currentDir, relativeBase) {
+		const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const fullPath = path.join(currentDir, entry.name);
+			const relativePath = relativeBase
+				? `${relativeBase}/${entry.name}`
+				: entry.name;
+
+			if (entry.isDirectory()) {
+				if (entry.name === ".checksums" || entry.name === ".markers") {
+					continue;
+				}
+				walk(fullPath, relativePath);
+			} else {
+				checksums[relativePath] = computeChecksum(fullPath);
+			}
+		}
+	}
+
+	walk(dir, "");
+	return checksums;
+}
+
+// ── writeChecksums ───────────────────────────────────────────────
+// Writes .checksums/<version>.json with version, timestamp, and file hashes.
+function writeChecksums(codeforgeDir, version, checksums) {
+	const checksumsDir = path.join(codeforgeDir, ".checksums");
+	fs.mkdirSync(checksumsDir, { recursive: true });
+	const data = {
+		version,
+		generated: new Date().toISOString(),
+		files: checksums,
+	};
+	fs.writeFileSync(
+		path.join(checksumsDir, `${version}.json`),
+		JSON.stringify(data, null, "\t") + "\n",
+	);
+}
+
+// ── readChecksums ────────────────────────────────────────────────
+// Reads latest version's checksums from .checksums/ dir.
+// Returns { files: {} } if none found.
+function readChecksums(codeforgeDir) {
+	const checksumsDir = path.join(codeforgeDir, ".checksums");
+	if (!fs.existsSync(checksumsDir)) {
+		return { files: {} };
+	}
+
+	const files = fs
+		.readdirSync(checksumsDir)
+		.filter((f) => f.endsWith(".json"))
+		.sort((a, b) => {
+			const pa = a.replace(".json", "").split(".").map(Number);
+			const pb = b.replace(".json", "").split(".").map(Number);
+			for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+				const diff = (pa[i] || 0) - (pb[i] || 0);
+				if (diff !== 0) return diff;
+			}
+			return 0;
+		});
+
+	if (files.length === 0) {
+		return { files: {} };
+	}
+
+	const latest = files[files.length - 1];
+	try {
+		return JSON.parse(
+			fs.readFileSync(path.join(checksumsDir, latest), "utf-8"),
+		);
+	} catch {
+		console.log(
+			"  Warning: Could not read checksums from " +
+				latest +
+				", treating as fresh install.",
+		);
+		return { files: {} };
+	}
+}
+
+// ── syncCodeforgeDirectory ───────────────────────────────────────
+// Checksum-aware sync for .codeforge/ directory.
+// Unmodified files get overwritten; modified files are preserved
+// and new defaults are written as <file>.default.
+function syncCodeforgeDirectory(src, dest) {
+	const stored = readChecksums(dest);
+	const stats = {
+		updated: 0,
+		preserved: 0,
+		added: 0,
+		preservedFiles: [],
+		defaultFiles: [],
+	};
+
+	function walk(srcDir, destDir, relativeBase) {
+		if (!fs.existsSync(destDir)) {
+			fs.mkdirSync(destDir, { recursive: true });
+		}
+
+		const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const srcPath = path.join(srcDir, entry.name);
+			const destPath = path.join(destDir, entry.name);
+			const relativePath = relativeBase
+				? `${relativeBase}/${entry.name}`
+				: entry.name;
+
+			if (entry.isDirectory()) {
+				if (entry.name === ".checksums" || entry.name === ".markers") {
+					continue;
+				}
+				walk(srcPath, destPath, relativePath);
+				continue;
+			}
+
+			const storedHash = stored.files[relativePath];
+			const currentHash = fs.existsSync(destPath)
+				? computeChecksum(destPath)
+				: null;
+
+			if (!storedHash) {
+				// First install or new file
+				if (currentHash === null) {
+					fs.copyFileSync(srcPath, destPath);
+					stats.added++;
+				} else {
+					// File exists but no stored hash — treat as user-created
+					fs.copyFileSync(srcPath, `${destPath}.default`);
+					stats.preserved++;
+					stats.preservedFiles.push(relativePath);
+					stats.defaultFiles.push(relativePath);
+				}
+			} else if (currentHash === storedHash) {
+				// File UNMODIFIED — overwrite with new version
+				fs.copyFileSync(srcPath, destPath);
+				stats.updated++;
+			} else {
+				// File USER-MODIFIED — keep user's file, write new as .default
+				fs.copyFileSync(srcPath, `${destPath}.default`);
+				stats.preserved++;
+				stats.preservedFiles.push(relativePath);
+				stats.defaultFiles.push(relativePath);
+			}
+		}
+	}
+
+	walk(src, dest, "");
+	return stats;
+}
+
 // ── syncDirectory ────────────────────────────────────────────────
 // Selective overwrite: walks the package tree and copies files to dest.
 // - Framework files (scripts, features, plugins): always overwrite
@@ -80,7 +244,7 @@ function syncDirectory(src, dest, preserveSet) {
 			const srcPath = path.join(srcDir, entry.name);
 			const destPath = path.join(destDir, entry.name);
 			const relativePath = relativeBase
-				? relativeBase + "/" + entry.name
+				? `${relativeBase}/${entry.name}`
 				: entry.name;
 
 			if (entry.isDirectory()) {
@@ -90,7 +254,7 @@ function syncDirectory(src, dest, preserveSet) {
 
 			// Special handling for devcontainer.json: overwrite + save .bak
 			if (relativePath === "devcontainer.json" && fs.existsSync(destPath)) {
-				fs.copyFileSync(destPath, destPath + ".bak");
+				fs.copyFileSync(destPath, `${destPath}.bak`);
 				fs.copyFileSync(srcPath, destPath);
 				stats.backedUp++;
 				stats.updated++;
@@ -99,7 +263,7 @@ function syncDirectory(src, dest, preserveSet) {
 
 			// Preserved files: skip overwrite, save package version as .codeforge-new
 			if (preserveSet.has(relativePath) && fs.existsSync(destPath)) {
-				fs.copyFileSync(srcPath, destPath + ".codeforge-new");
+				fs.copyFileSync(srcPath, `${destPath}.codeforge-new`);
 				stats.preserved++;
 				stats.preservedFiles.push(relativePath);
 				continue;
@@ -123,20 +287,33 @@ function syncDirectory(src, dest, preserveSet) {
 // ── main ─────────────────────────────────────────────────────────
 function main() {
 	const args = process.argv.slice(2);
+
+	// Subcommand: config apply
+	if (args[0] === "config" && args[1] === "apply") {
+		return configApply();
+	}
+
 	const force = args.includes("--force") || args.includes("-f");
 	const reset = args.includes("--reset");
 
 	if (args.includes("--help") || args.includes("-h")) {
 		console.log("Usage: codeforge [options]");
+		console.log("       codeforge config apply");
 		console.log("");
 		console.log("Options:");
 		console.log(
-			"  --force, -f   Update existing .devcontainer (preserves user config)",
+			"  --force, -f     Update existing .devcontainer and .codeforge (preserves user config)",
 		);
 		console.log(
-			"  --reset       Remove all customizations and install fresh defaults",
+			"  --reset         Remove .devcontainer customizations and install fresh defaults",
+		);
+		console.log("                  (.codeforge user modifications preserved)");
+		console.log("  --help, -h      Show this help message");
+		console.log("");
+		console.log("Subcommands:");
+		console.log(
+			"  config apply    Deploy .codeforge/config/ files to ~/.claude/",
 		);
-		console.log("  --help, -h    Show this help message");
 		console.log("");
 		console.log(
 			"Without flags, installs only if .devcontainer does not exist.",
@@ -148,6 +325,11 @@ function main() {
 	const packageDir = __dirname;
 	const devcontainerSrc = path.join(packageDir, ".devcontainer");
 	const devcontainerDest = path.join(currentDir, ".devcontainer");
+	const codeforgeSrc = path.join(packageDir, ".codeforge");
+	const codeforgeDest = path.join(currentDir, ".codeforge");
+	const packageVersion = JSON.parse(
+		fs.readFileSync(path.join(packageDir, "package.json"), "utf8"),
+	).version;
 
 	console.log("");
 
@@ -161,12 +343,44 @@ function main() {
 
 	if (fs.existsSync(devcontainerDest)) {
 		if (reset) {
-			// Nuclear: delete everything and copy fresh
+			// Nuclear: delete .devcontainer and copy fresh
 			console.log("Resetting .devcontainer to package defaults...");
 			console.log("");
 			fs.rmSync(devcontainerDest, { recursive: true, force: true });
 			copyDirectory(devcontainerSrc, devcontainerDest);
-			console.log("  Reset complete. All user customizations removed.");
+			console.log(
+				"  Reset complete. All .devcontainer customizations removed.",
+			);
+
+			// .codeforge uses checksum-based preservation (not wipe)
+			if (fs.existsSync(codeforgeSrc)) {
+				if (fs.existsSync(codeforgeDest)) {
+					const codeforgeStats = syncCodeforgeDirectory(
+						codeforgeSrc,
+						codeforgeDest,
+					);
+					console.log("  .codeforge/ user modifications preserved.");
+					console.log(`    Updated:   ${codeforgeStats.updated} files`);
+					console.log(`    Added:     ${codeforgeStats.added} new files`);
+					console.log(
+						`    Preserved: ${codeforgeStats.preserved} user config files`,
+					);
+					if (codeforgeStats.defaultFiles.length > 0) {
+						console.log("");
+						console.log(
+							"  Review .default files for new defaults you may want to merge:",
+						);
+						for (const f of codeforgeStats.defaultFiles) {
+							console.log(`    ${f}.default`);
+						}
+					}
+				} else {
+					copyDirectory(codeforgeSrc, codeforgeDest);
+				}
+				const newChecksums = generateChecksums(codeforgeSrc);
+				writeChecksums(codeforgeDest, packageVersion, newChecksums);
+			}
+
 			console.log("");
 			printNextSteps();
 		} else if (force) {
@@ -204,6 +418,34 @@ function main() {
 				console.log("");
 			}
 
+			// .codeforge sync with checksum-based preservation
+			if (fs.existsSync(codeforgeSrc)) {
+				const codeforgeStats = syncCodeforgeDirectory(
+					codeforgeSrc,
+					codeforgeDest,
+				);
+				const newChecksums = generateChecksums(codeforgeSrc);
+				writeChecksums(codeforgeDest, packageVersion, newChecksums);
+
+				console.log("  .codeforge/ update:");
+				console.log(`    Updated:   ${codeforgeStats.updated} files`);
+				console.log(`    Added:     ${codeforgeStats.added} new files`);
+				console.log(
+					`    Preserved: ${codeforgeStats.preserved} user config files`,
+				);
+
+				if (codeforgeStats.defaultFiles.length > 0) {
+					console.log("");
+					console.log(
+						"  Review .default files for new defaults you may want to merge:",
+					);
+					for (const f of codeforgeStats.defaultFiles) {
+						console.log(`    ${f}.default`);
+					}
+				}
+				console.log("");
+			}
+
 			printNextSteps();
 		} else {
 			// No flags: error with guidance
@@ -221,6 +463,13 @@ function main() {
 
 		try {
 			copyDirectory(devcontainerSrc, devcontainerDest);
+
+			if (fs.existsSync(codeforgeSrc)) {
+				copyDirectory(codeforgeSrc, codeforgeDest);
+				const checksums = generateChecksums(codeforgeSrc);
+				writeChecksums(codeforgeDest, packageVersion, checksums);
+			}
+
 			console.log("  CodeForge DevContainer configuration installed!");
 			console.log("");
 			printNextSteps();
@@ -232,13 +481,127 @@ function main() {
 	}
 }
 
+// ── configApply ──────────────────────────────────────────────────
+// Deploys .codeforge/config/ files to ~/.claude/ using file-manifest.json.
+function configApply() {
+	const codeforgeDir =
+		process.env.CODEFORGE_DIR || path.join(process.cwd(), ".codeforge");
+	const manifest = path.join(codeforgeDir, "file-manifest.json");
+
+	if (!fs.existsSync(manifest)) {
+		console.error("Error: file-manifest.json not found at " + manifest);
+		console.error("Are you in a CodeForge project directory?");
+		process.exit(1);
+	}
+
+	const entries = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+	const claudeConfigDir =
+		process.env.CLAUDE_CONFIG_DIR ||
+		path.join(process.env.HOME || "/home/vscode", ".claude");
+	const workspaceRoot = process.env.WORKSPACE_ROOT || process.cwd();
+
+	function expandVars(val) {
+		return val
+			.replace(/\$\{CLAUDE_CONFIG_DIR\}/g, claudeConfigDir)
+			.replace(/\$\{WORKSPACE_ROOT\}/g, workspaceRoot)
+			.replace(/\$\{HOME\}/g, process.env.HOME || "/home/vscode");
+	}
+
+	console.log("");
+	console.log("Applying .codeforge/config/ to Claude configuration...");
+	console.log("");
+
+	let deployed = 0;
+	let skipped = 0;
+
+	const validOverwrite = ["always", "if-changed", "never"];
+
+	for (const entry of entries) {
+		if (entry.enabled === false) {
+			skipped++;
+			continue;
+		}
+
+		if (entry.overwrite && !validOverwrite.includes(entry.overwrite)) {
+			console.log(
+				'  Warning: Unknown overwrite value "' +
+					entry.overwrite +
+					'" for ' +
+					entry.src +
+					', defaulting to "always"',
+			);
+		}
+
+		const codeforgeRoot = path.resolve(codeforgeDir);
+		const srcPath = path.resolve(codeforgeRoot, entry.src);
+		if (!srcPath.startsWith(codeforgeRoot + path.sep)) {
+			console.log(
+				"  Skip: " + entry.src + " (source path escapes .codeforge/)",
+			);
+			skipped++;
+			continue;
+		}
+		if (!fs.existsSync(srcPath)) {
+			console.log("  Skip: " + entry.src + " (not found)");
+			skipped++;
+			continue;
+		}
+
+		const homeDir = path.resolve(process.env.HOME || "/home/vscode");
+		const allowedDestRoots = [
+			path.resolve(claudeConfigDir),
+			homeDir,
+			"/usr/local/share",
+		];
+		const destDir = path.resolve(expandVars(entry.dest));
+		const destAllowed = allowedDestRoots.some(
+			(root) => destDir === root || destDir.startsWith(root + path.sep),
+		);
+		if (!destAllowed) {
+			console.log(
+				"  Skip: " + entry.dest + " (destination outside allowed directories)",
+			);
+			skipped++;
+			continue;
+		}
+
+		const filename = entry.destFilename || path.basename(entry.src);
+		const destPath = path.join(destDir, filename);
+		fs.mkdirSync(destDir, { recursive: true });
+
+		if (entry.overwrite === "never" && fs.existsSync(destPath)) {
+			console.log("  Skip: " + filename + " (exists, overwrite=never)");
+			skipped++;
+			continue;
+		}
+
+		if (entry.overwrite === "if-changed" && fs.existsSync(destPath)) {
+			const srcHash = computeChecksum(srcPath);
+			const destHash = computeChecksum(destPath);
+			if (srcHash === destHash) {
+				skipped++;
+				continue;
+			}
+		}
+
+		fs.copyFileSync(srcPath, destPath);
+		console.log("  Deployed: " + entry.src + " → " + destPath);
+		deployed++;
+	}
+
+	console.log("");
+	console.log(
+		"Config apply complete: " + deployed + " deployed, " + skipped + " skipped",
+	);
+}
+
 function printNextSteps() {
 	console.log("Next steps:");
 	console.log("  1. Open this folder in VS Code");
 	console.log('  2. Select "Reopen in Container" from the command palette');
 	console.log("  3. Run: claude");
 	console.log("");
-	console.log("Documentation: .devcontainer/README.md");
+	console.log("Documentation: .devcontainer/README.md and .codeforge/");
 	console.log("");
 }
 
@@ -255,4 +618,12 @@ if (require.main === module) {
 	main();
 }
 
-module.exports = { copyDirectory, syncDirectory, loadPreserveList, main };
+module.exports = {
+	copyDirectory,
+	syncDirectory,
+	syncCodeforgeDirectory,
+	loadPreserveList,
+	computeChecksum,
+	generateChecksums,
+	main,
+};