fix(npm): commit root launcher package; anchor .gitignore binary patterns

.gitignore

@@ -31,5 +31,7 @@ go.work.sum
 # .idea/
 # .vscode/
 
-csdd
-csdd.md
+# Compiled csdd binary + generated guide at the repo root only.
+# Anchored with a leading slash so they do NOT match the npm/csdd/ package dir.
+/csdd
+/csdd.md

npm/csdd/README.md

@@ -0,0 +1,36 @@
+# csdd
+
+**Claude Spec-Driven Development — as an executable contract.**
+
+`csdd` is a single Go binary that turns the Spec-Driven Development (SDD)
+workflow for [Claude Code](https://claude.com/claude-code) into a contract that
+is validated mechanically — for humans *and* AI agents.
+
+## Install
+
+```bash
+npm install -g @protonspy/csdd
+```
+
+Or run it without installing:
+
+```bash
+npx @protonspy/csdd --help
+```
+
+This package ships a thin launcher; the native binary for your platform is
+pulled in automatically as an optional dependency (no postinstall scripts, no
+download at install time). Prebuilt for linux, macOS, and Windows on x64/arm64.
+
+## Usage
+
+```bash
+csdd                                              # interactive TUI
+csdd spec generate photo-albums --artifact requirements   # headless / CI
+```
+
+See the [full documentation](https://github.com/protonspy/csdd#readme).
+
+## License
+
+[Apache-2.0](https://github.com/protonspy/csdd/blob/main/LICENSE)

npm/csdd/bin/csdd.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// Launcher for the csdd CLI distributed via npm.
+//
+// The actual Go binary ships in a per-platform optional dependency
+// (@protonspy/csdd-<platform>-<arch>). npm installs only the package whose
+// "os"/"cpu" match the host, so this shim just resolves that package's binary
+// and execs it — forwarding argv, stdio, signals, and the exit code. No
+// postinstall, no network at install time.
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+const PLATFORM = { darwin: "darwin", linux: "linux", win32: "win32" }[process.platform];
+const ARCH = { x64: "x64", arm64: "arm64" }[process.arch];
+
+if (!PLATFORM || !ARCH) {
+  console.error(
+    `csdd: unsupported platform ${process.platform}/${process.arch}. ` +
+      `Prebuilt binaries are available for linux, macOS, and Windows on x64/arm64.`
+  );
+  process.exit(1);
+}
+
+const pkg = `@protonspy/csdd-${PLATFORM}-${ARCH}`;
+const binName = process.platform === "win32" ? "csdd.exe" : "csdd";
+
+let binPath;
+try {
+  binPath = require.resolve(`${pkg}/bin/${binName}`);
+} catch {
+  console.error(
+    `csdd: could not find the native binary for ${PLATFORM}-${ARCH}.\n` +
+      `The optional dependency "${pkg}" was not installed.\n` +
+      `Reinstall without --no-optional / --ignore-optional, or report an issue at\n` +
+      `https://github.com/protonspy/csdd/issues`
+  );
+  process.exit(1);
+}
+
+const child = spawn(binPath, process.argv.slice(2), { stdio: "inherit" });
+
+// Forward terminating signals so the TUI shuts down cleanly.
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => {
+    try {
+      child.kill(sig);
+    } catch {
+      /* child already gone */
+    }
+  });
+}
+
+child.on("error", (err) => {
+  console.error(`csdd: failed to launch binary: ${err.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Re-raise the signal so the parent exit status reflects it.
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});

npm/csdd/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@protonspy/csdd",
+  "version": "0.0.0",
+  "description": "Claude Spec-Driven Development — a single Go binary that turns the SDD workflow into a mechanically validated contract for humans and AI agents.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "spec-driven-development",
+    "sdd",
+    "cli",
+    "ai",
+    "agents"
+  ],
+  "homepage": "https://github.com/protonspy/csdd#readme",
+  "bugs": {
+    "url": "https://github.com/protonspy/csdd/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/protonspy/csdd.git"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "csdd": "bin/csdd.js"
+  },
+  "files": [
+    "bin/csdd.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "optionalDependencies": {
+    "@protonspy/csdd-linux-x64": "0.0.0",
+    "@protonspy/csdd-linux-arm64": "0.0.0",
+    "@protonspy/csdd-darwin-x64": "0.0.0",
+    "@protonspy/csdd-darwin-arm64": "0.0.0",
+    "@protonspy/csdd-win32-x64": "0.0.0"
+  }
+}