voidforge-build 23.11.0 → 23.11.2

package/dist/.claude/commands/git.md

@@ -65,6 +65,14 @@ Stage and commit:
 4. Present the full commit message and staged file list to the user
 5. On user approval, execute the commit
 
+## Step 4.5 — Tag (Coulson)
+Annotate the commit with the version tag (default-on; opt out via `--no-tag`):
+1. Run `git tag -a vX.Y.Z -m "vX.Y.Z: <one-line summary>"` against HEAD
+2. Verify: `git tag --list vX.Y.Z` returns the tag
+3. If a tag with that name already exists on a different commit, stop and surface the conflict — do not force-overwrite without user instruction.
+
+Tags are local until pushed (Step 6). Why default-on: a release commit without a tag is invisible to `git describe`, GitHub releases, and most release tooling. **Field report: v23.10.0 and v23.11.0 shipped without tags in May 2026, blocking npm publish discovery downstream — exactly the kind of silent omission this step prevents.**
+
 ## Step 5 — Verify (Barton)
 Confirm everything is consistent:
 1. Run `git log -1 --format="%H %s"` — verify the commit exists and message is correct
@@ -73,6 +81,7 @@ Confirm everything is consistent:
    - `package.json` version matches
    - The **active changelog** (PROJECT_VERSION.md if present, else CHANGELOG.md) has an entry for this version
    - Commit message starts with the correct version tag
+   - `git tag --list vX.Y.Z` returns the tag (unless `--no-tag` was used)
    - **ROADMAP.md cross-check (field report #309 Fix 4):** if `ROADMAP.md` exists, grep it for the new version string. If milestones in ROADMAP.md reference a higher version than `package.json`, that's drift — surface it and offer to bump. If ROADMAP claims a milestone is "DONE" at a version that doesn't match the just-committed bump, surface that too. Drift between ROADMAP and package.json typically goes unnoticed for weeks.
 3. Run `git status` — verify working tree is clean (no forgotten files)
 4. If any inconsistency found, flag it and offer to fix
@@ -81,8 +90,28 @@ Confirm everything is consistent:
 Only if the user explicitly requests:
 1. Check remote: `git remote -v`
 2. Check if branch tracks upstream: `git status -sb`
-3. Push: `git push`
-4. Verify: `git log --oneline -1` matches remote
+3. Push branch: `git push`
+4. Push tags (if Step 4.5 ran): `git push origin vX.Y.Z` (or `git push --tags` if multiple new tags exist)
+5. Verify: `git log --oneline -1` matches remote, `git ls-remote --tags origin vX.Y.Z` shows the tag on remote
+
+## Step 7 — Publish to npm (Dockson) [--npm only]
+Only runs when the user passes `--npm`. Publishing is irreversible (npm forbids re-using version numbers) and broadcasts to every consumer, so explicit opt-in is required.
+
+**Read this first.** If `.github/workflows/publish.yml` (or equivalent) is configured to publish on tag push, the canonical publish path is the CI workflow — pushing the tag in Step 6 already triggers it. Use `--npm` when CI is unreachable, broken, or when you need a same-session publish without waiting for the workflow. Running both in parallel is safe (the workflow's "already published" check will skip the duplicate) but wastes a CI minute.
+
+**Tag-push ordering caveat.** If you push multiple tags in one `git push --tags` call and CI publishes them in parallel, npm's `latest` dist-tag lands on whichever finished last — not the highest semver. After a multi-tag push, verify with `npm view <name> dist-tags` and run `npm dist-tag add <name>@vX.Y.Z latest` to repoint if needed. (This bit us when v23.10.0 + v23.11.0 were pushed together in May 2026.)
+
+1. **Preflight.** Run `npm whoami` — if not logged in, stop and tell the user to run `npm login`. Run `git status` — if working tree is dirty, stop (publishing from a dirty tree creates packages that don't match the tagged commit).
+2. **Discover publishable packages.** Build the list:
+   - If `package.json` at repo root has no `"private": true`, include it.
+   - If a workspaces array exists, walk each workspace package; include those without `"private": true`.
+   - For monorepos without workspaces (e.g., `packages/*/package.json`), glob and filter the same way.
+   - Skip any package whose `version` field doesn't match the version just committed in Step 4 — surface the mismatch instead of publishing inconsistent versions.
+3. **Confirm.** Print the list (`name@version`) and the registry (`npm config get registry`), then ask for confirmation. Include a note when `publishConfig.access` is `public` vs scoped.
+4. **Publish in dependency order.** If one package depends on another in the list, publish the dependency first. For VoidForge specifically: `voidforge-build-methodology` publishes before `voidforge-build`.
+5. **Run `npm publish` per package** from each package's own directory. Surface the tarball summary line (`+ name@version`) on success. On `EPUBLISHCONFLICT` (version already published), stop — the user needs to bump and re-run.
+6. **Verify.** For each published package, run `npm view <name> version` and confirm it returns the new version. There is sometimes a few-second registry propagation lag — retry once after 5s if mismatched.
+7. **Final summary.** Print which packages were published and at what version. This is the line that closes the release.
 
 ## Step 5.5 — Command↔Doc Sync Check (Friday)
 If any `docs/methods/*.md` file was modified, verify the paired `.claude/commands/*.md` file reflects the same additions:
@@ -106,9 +135,13 @@ If any `docs/methods/*.md` file was modified, verify the paired `.claude/command
 If a method doc gained a new section, flag, or checklist item — flag it: "Method doc X changed but command file Y may need matching update." The user decides whether the command file needs updating.
 
 ## Arguments
-- `--dry-run` → Show version bump, changelog entry, and commit message without executing.
+- `--dry-run` → Show version bump, changelog entry, commit message, tag, and (if `--npm`) the package list that would publish — without executing any of it.
+- `--major` / `--minor` / `--patch` → Override the Step 2 recommendation.
+- `--no-tag` → Skip Step 4.5. Use sparingly; tagless release commits are the bug that produced this flag.
+- `--npm` → Run Step 7 after push: publish every non-private package whose version matches the bump. Requires `npm whoami` to succeed. For monorepos, publishes all matching packages in dependency order.
 
 ## Handoffs
 - If changes include security fixes → note for Kenobi (`/sentinel`)
 - If changes include infrastructure → note for Kusanagi (`/devops`)
 - If version is MAJOR → recommend Picard review (`/architect`)
+- If `--npm` was used → the release is now public on npm; any rollback requires a new patch version (npm forbids unpublishing within 72h for security)

package/dist/CHANGELOG.md

@@ -6,6 +6,52 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ---
 
+## [23.11.2] - 2026-05-12
+
+### `voidforge init` mode prompt + methodology surfer-gate distribution
+
+Two threads of polish: the CLI now asks before launching, and the Silver Surfer gate finally ships in the methodology npm package.
+
+### Added
+
+- **`voidforge init` mode prompt.** With no flag, `init` now asks "Browser wizard or CLI (headless)?" instead of silently launching the browser server. Prompt appears only when stdin is a TTY.
+- **`--browser` flag on `voidforge init`.** Explicit opt-in to the wizard UI — skips the prompt for users (or scripts) that want the prior default behavior.
+- **Interactive headless init.** `voidforge init --headless` now prompts for project name (required), directory (defaulted to `~/Projects/<slug>`), and optional oneliner/domain/repo when `--name` is omitted in a TTY. Fully non-interactive when all flags are passed.
+- **`packages/methodology/scripts/surfer-gate/`** (8 files) — the Silver Surfer PreToolUse hook scripts (`check.sh`, `record-roster.sh`, `bypass.sh`, `_paths.sh`, `validate.sh`, `test.sh`, `README.md`, `settings-snippet.json`) now ship via the `voidforge-build-methodology` npm package, closing the ADR-051 distribution gap (#317). Previously the scripts lived only at the repo root and never reached downstream projects via `npx voidforge-build update`.
+- **9 pattern-table rows** in `packages/methodology/CLAUDE.md` — propagates the v23.11.0 pattern additions (adr-verification-gate, multi-tenant-property-test, multi-tenant-pool-bypass, rls-test-fixture, structural-sql-sentinel, audit-log, refactor-extraction, ai-prompt-safety, llm-state-dedup) into the methodology package copy so they reach downstream projects.
+
+### Changed
+
+- **Non-TTY `voidforge init` without a flag** now exits with a clear error directing the user to `--browser` or `--headless`. Previously it silently launched a wizard server into a context where no browser would ever open — a latent bug.
+- **Surfer Gate orchestrator-contract bash commands** in `packages/methodology/CLAUDE.md` are now wrapped in `[ -x ... ] && ... || true` existence guards with documented fallback ("if the script does not exist, your project predates v23.10.0; pull the gate or re-run `npx voidforge-build init`"). Lets the methodology cleanly cover both pre-#317 and post-#317 projects.
+
+### Why this exists
+
+The init server-launch was the loudest "this CLI doesn't ask before doing things" surface in onboarding — first-run users got a server URL with no opportunity to choose CLI mode. Two flags (`--browser`, `--headless`) now span the choice; the bare command asks. Separately, the surfer-gate scripts had been documented as shipping in the methodology package since v23.11.0 changelog #317, but the scripts themselves were never copied into `packages/methodology/`. This release actually ships them.
+
+---
+
+## [23.11.1] - 2026-05-10
+
+### `/git` release-discipline patch — close the silent-release gap
+
+v23.10.0 and v23.11.0 reached `origin/main` with bumped `package.json` versions but no git tags and no npm publish. The `publish.yml` workflow fires on `v*` tag push, so without tags the release pipeline never ran — both versions sat stranded for a full release cycle until a downstream `/void` returned nothing. Coulson now tags by default and exposes `--npm` for same-session manual publishing.
+
+### Added
+
+- **`.claude/commands/git.md` — Step 4.5 (Tag).** Default-on. After commit, annotate HEAD with `git tag -a vX.Y.Z -m "<summary>"`. Skippable via `--no-tag`. Conflict detection on existing tags.
+- **`.claude/commands/git.md` — Step 7 (Publish to npm).** Opt-in via `--npm`. Preflight (`npm whoami`, clean tree), discover non-private packages whose version matches the bump, confirm + publish in dependency order (methodology before voidforge-build for VoidForge specifically), verify via `npm view ... version` with one retry. Notes the `latest` dist-tag race when multiple tags are pushed in one batch.
+- **`.claude/commands/git.md` — Push tags in Step 6.** Branch push now also pushes new tags, verified against `git ls-remote --tags origin`.
+- **`.claude/commands/git.md` — Arguments.** `--no-tag` and `--npm` documented in the flags block; handoff note covers npm's 72h unpublish lockout.
+- **`docs/methods/RELEASE_MANAGER.md` — `/git --npm` Flag section.** Mirrors the command-file spec: when CI is the canonical path, when `--npm` is the fallback, hard rules (no dirty publish, no `--force`, no `--ignore-scripts`, stop on `EPUBLISHCONFLICT`).
+- **`docs/methods/RELEASE_MANAGER.md` — Verification Checklist.** Adds `git tag --list vX.Y.Z` and post-publish `npm view <name> version` checks.
+
+### Why this exists
+
+Field-report context lives inline in both files so the lesson survives without an external citation. Tag step is default-on because tagless release commits are invisible to `git describe`, GitHub releases, and (critically) the tag-triggered publish workflow. Publish is opt-in because broadcast actions deserve a deliberate trigger, and the CI workflow remains the canonical path when reachable.
+
+---
+
 ## [23.11.0] - 2026-05-10
 
 ### Field Report Triage — 18 reports closed (#313–#320, #322–#330)

package/dist/VERSION.md

@@ -1,6 +1,6 @@
 # Version
 
-**Current:** 23.11.0
+**Current:** 23.11.2
 
 ## Versioning Scheme
 
@@ -14,6 +14,8 @@ This project uses [Semantic Versioning](https://semver.org/):
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 23.11.2 | 2026-05-12 | `voidforge init` now prompts browser-vs-CLI when no mode flag is passed (TTY only) and `--browser` was added for explicit opt-in. Headless init prompts for name/dir/oneliner/domain/repo when `--name` is omitted in a TTY. Non-TTY no-flag now errors cleanly instead of silently launching a wizard server. Separately: `packages/methodology/scripts/surfer-gate/` (8 files) now ships in the npm methodology package — closes ADR-051 distribution gap (#317). 9 pattern-table rows + existence-guarded orchestrator-contract bash propagated into the methodology CLAUDE.md. |
+| 23.11.1 | 2026-05-10 | `/git` release-discipline patch — Step 4.5 (auto-tag, default-on) and Step 7 (`--npm` opt-in publish). Closes the silent-release gap that stranded v23.10.0 and v23.11.0 between GitHub and npm. Tag-push triggers the existing `publish.yml` workflow; `--npm` is a same-session fallback. Documents the `latest` dist-tag race when multiple tags are pushed simultaneously. RELEASE_MANAGER.md mirrored. |
 | 23.11.0 | 2026-05-10 | Field Report Triage — 18 reports closed (#313-#320, #322-#330). Two combined batches across multi-tenant retrofit campaigns (#313-#320) and autonomous-mode + AI-execution campaigns (#322-#330). 9 new patterns: adr-verification-gate.md, audit-log.ts, multi-tenant-{pool-bypass,property-test}.ts, rls-test-fixture.py, structural-sql-sentinel.py, refactor-extraction.md, ai-prompt-safety.ts, llm-state-dedup.ts. ai-eval.ts extended with Claude-prompt-eval template. middleware.ts extended with hot-path logging gate. 18 method-doc sections across CAMPAIGN, SYSTEMS_ARCHITECT, SECURITY_AUDITOR, QA_ENGINEER, SUB_AGENTS, BACKEND_ENGINEER, RELEASE_MANAGER, GAUNTLET, AI_INTELLIGENCE, DEVOPS_ENGINEER, FORGE_KEEPER, TESTING, TIME_VAULT. Surfer Gate now ships via npm methodology package + wizard project-init (closes ADR-051 distribution gap #317). Operational learnings added to Picard, Sisko, Coulson, Bashir, Loki, Irulan, Silver Surfer. |
 | 23.10.0 | 2026-04-20 | Field Report Triage — 6 reports closed (#303-#308). 33 approved fixes: SPEC_HANDOFF.md (new method doc), deploy-preflight.ts + post-deploy-probe.sh (new patterns), LEARNINGS LRN-5..10, Deploy Surface Boundary + Deployment Hygiene (field report #305 remediation), Step 2.5 pre-deploy secret scan + Step 4.5 post-deploy probe, TECH_DEBT SLA, npm-name pre-flight, ADR-050 Rename Verification Checklist, Silver Surfer HARD CONSTRAINT + 4 agent operational learnings. |
 | 23.9.2 | 2026-04-20 | CI workflow idempotency + provenance baseline — `publish.yml` guards each publish with "already-published" check so re-runs skip cleanly. Tag-push re-publishes via CI to attach npm provenance attestation (absent on v23.9.1's manual publish). |

package/dist/docs/methods/RELEASE_MANAGER.md

@@ -116,8 +116,10 @@ After every commit, Barton verifies:
 - [ ] `VERSION.md` history table has new row with correct date
 - [ ] `package.json` "version" field matches
 - [ ] `CHANGELOG.md` has `[X.Y.Z]` section with correct date
+- [ ] `git tag --list vX.Y.Z` returns the tag (unless `--no-tag`)
 - [ ] `git status` shows clean working tree
 - [ ] No untracked files that should have been included
+- [ ] If `--npm` was used: every published package returns the new version from `npm view <name> version`
 
 ## CLAUDE.md Command Table Integrity Check
 
@@ -136,6 +138,30 @@ When the user passes `--deploy` to `/git`, run `/deploy` automatically after the
 
 This enables one-command commit-and-deploy for ad-hoc changes outside of campaigns.
 
+## `/git --npm` Flag
+
+When the user passes `--npm` to `/git`, run npm publish after the commit + tag + push succeeds. Publishing is irreversible (npm forbids re-using version numbers; unpublish blocked within 72h) — explicit opt-in is required.
+
+**Why this flag exists.** VoidForge distributes via npm. Before this flag existed, Coulson's workflow ended at `git push`, leaving every release stranded between GitHub and the registry. Field report: v23.10.0 and v23.11.0 were committed, tagged with version strings in `package.json`, and pushed to origin/main — but never published. Downstream consumers running `npx voidforge-build update` saw nothing new for two release cycles until the gap was caught manually. Tagging defaults to on (Step 4.5); npm publish is opt-in because broadcast actions deserve a deliberate trigger.
+
+**Procedure (Dockson handles the publish; Coulson orchestrates):**
+
+1. **Preflight.** `npm whoami` must succeed. Working tree must be clean. Tag must exist (Step 4.5 result).
+2. **Discover.** Enumerate publishable packages — root `package.json` and any workspace/`packages/*` packages that don't have `"private": true`. Skip any whose version field doesn't match the version just bumped.
+3. **Confirm.** Print the list (`name@version`) and registry, ask for go-ahead.
+4. **Order.** Resolve internal dependencies — if package B depends on package A inside the same monorepo, publish A first. For VoidForge: `voidforge-build-methodology` before `voidforge-build`.
+5. **Publish.** Run `npm publish` from each package's own directory. Capture the `+ name@version` line.
+6. **Verify.** `npm view <name> version` must return the new version for each published package. Retry once after 5s on lag.
+7. **Report.** Final summary line: which packages shipped, at what version, to which registry.
+
+**Hard rules:**
+
+- Never publish from a dirty working tree.
+- Never publish if `npm whoami` fails — surface the error and stop.
+- Never `--force` or `--ignore-scripts`. If `prepack` fails, the package is broken; fix it.
+- On `EPUBLISHCONFLICT` (version exists), stop. The user must bump and re-run; do not attempt to dist-tag around it.
+- Scoped/private packages are skipped silently unless the user explicitly names them.
+
 ## Per-Commit CHANGELOG Discipline
 
 CHANGELOG drift accumulates silently when entries are deferred to session boundaries. By the time someone notices, the test count trajectory is wrong and the per-mission delta is unrecoverable from the diff alone.

package/dist/scripts/voidforge.d.ts

@@ -3,8 +3,10 @@
  * VoidForge CLI — v21.0 The Extraction
  *
  * npx voidforge                       Launch wizard (browser UI at :3141)
- * npx voidforge init                  Create new project (Gandalf flow)
- * npx voidforge init --headless       Create project without browser
+ * npx voidforge init                  Create new project — prompts: browser or CLI
+ * npx voidforge init --browser        Skip the prompt, go straight to the browser wizard
+ * npx voidforge init --headless       Create project without browser (CLI prompts for name/dir)
+ * npx voidforge init --headless --name "X"   Fully non-interactive CLI init
  * npx voidforge init --core           Minimal methodology (no Holocron, no patterns)
  * npx voidforge update                Update project methodology (Bombadil)
  * npx voidforge update --self         Update the wizard itself

package/dist/scripts/voidforge.js

@@ -3,8 +3,10 @@
  * VoidForge CLI — v21.0 The Extraction
  *
  * npx voidforge                       Launch wizard (browser UI at :3141)
- * npx voidforge init                  Create new project (Gandalf flow)
- * npx voidforge init --headless       Create project without browser
+ * npx voidforge init                  Create new project — prompts: browser or CLI
+ * npx voidforge init --browser        Skip the prompt, go straight to the browser wizard
+ * npx voidforge init --headless       Create project without browser (CLI prompts for name/dir)
+ * npx voidforge init --headless --name "X"   Fully non-interactive CLI init
  * npx voidforge init --core           Minimal methodology (no Holocron, no patterns)
  * npx voidforge update                Update project methodology (Bombadil)
  * npx voidforge update --self         Update the wizard itself
@@ -167,6 +169,41 @@ async function launchWizard(mode = 'init') {
     if (!isRemote && !isLan)
         await openBrowser(url);
 }
+function slugifyName(name) {
+    return name.replace(/[^a-zA-Z0-9-_ ]/g, '').replace(/\s+/g, '-').toLowerCase();
+}
+function defaultProjectDir(name) {
+    return join(process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.', 'Projects', slugifyName(name));
+}
+async function prompt(question) {
+    const { createInterface } = await import('node:readline');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (answer) => { rl.close(); res(answer.trim()); });
+    });
+}
+/**
+ * Asks the user to pick browser vs headless mode for `voidforge init`.
+ * Requires a TTY — caller must guard with process.stdin.isTTY.
+ */
+async function promptInitMode() {
+    console.log('');
+    console.log('  VoidForge — init');
+    console.log('');
+    console.log('  How would you like to set up this project?');
+    console.log('    1) Browser wizard (Gandalf) — interactive, guided UI');
+    console.log('    2) CLI (headless)            — prompts here in the terminal');
+    console.log('');
+    // Loop until we get a valid answer.
+    for (;;) {
+        const answer = (await prompt('  Choice [1]: ')).toLowerCase();
+        if (answer === '' || answer === '1' || answer === 'b' || answer === 'browser')
+            return 'browser';
+        if (answer === '2' || answer === 'c' || answer === 'cli' || answer === 'h' || answer === 'headless')
+            return 'headless';
+        console.log('  Please enter 1 (browser) or 2 (CLI).');
+    }
+}
 async function cmdInitHeadless() {
     const nameFlag = args.find((a, i) => args[i - 1] === '--name');
     const dirFlag = args.find((a, i) => args[i - 1] === '--dir');
@@ -174,25 +211,61 @@ async function cmdInitHeadless() {
     const domainFlag = args.find((a, i) => args[i - 1] === '--domain');
     const repoFlag = args.find((a, i) => args[i - 1] === '--repo');
     const isCore = args.includes('--core');
-    if (!nameFlag) {
-        console.error('Error: --name is required for headless init.');
-        console.error('Usage: npx voidforge init --headless --name "My Project" [--dir path] [--oneliner "..."]');
-        process.exit(1);
+    let name = nameFlag;
+    let directory = dirFlag;
+    let oneliner = onelinerFlag;
+    let domain = domainFlag;
+    let repoUrl = repoFlag;
+    // If --name is missing, prompt interactively (TTY only).
+    if (!name) {
+        if (!process.stdin.isTTY) {
+            console.error('Error: --name is required for headless init in non-interactive contexts.');
+            console.error('Usage: npx voidforge init --headless --name "My Project" [--dir path] [--oneliner "..."]');
+            process.exit(1);
+        }
+        console.log('');
+        console.log('  VoidForge — Headless Init');
+        console.log('  Press Enter to accept defaults shown in [brackets]. Optional fields can be left blank.');
+        console.log('');
+        while (!name) {
+            const answer = await prompt('  Project name: ');
+            if (answer)
+                name = answer;
+            else
+                console.log('  Project name is required.');
+        }
+        const defaultDir = defaultProjectDir(name);
+        if (!directory) {
+            const answer = await prompt(`  Directory [${defaultDir}]: `);
+            directory = answer || defaultDir;
+        }
+        if (!oneliner) {
+            const answer = await prompt('  One-line description (optional): ');
+            oneliner = answer || undefined;
+        }
+        if (!domain) {
+            const answer = await prompt('  Domain (optional): ');
+            domain = answer || undefined;
+        }
+        if (!repoUrl) {
+            const answer = await prompt('  Repo URL (optional): ');
+            repoUrl = answer || undefined;
+        }
     }
-    const defaultDir = join(process.env['HOME'] ?? process.env['USERPROFILE'] ?? '.', 'Projects', nameFlag.replace(/[^a-zA-Z0-9-_ ]/g, '').replace(/\s+/g, '-').toLowerCase());
-    const directory = dirFlag ?? defaultDir;
+    if (!directory)
+        directory = defaultProjectDir(name);
     const { createProject } = await import('../wizard/lib/project-init.js');
     const result = await createProject({
-        name: nameFlag,
+        name,
         directory,
-        oneliner: onelinerFlag,
-        domain: domainFlag,
-        repoUrl: repoFlag,
+        oneliner,
+        domain,
+        repoUrl,
         core: isCore,
     });
     console.log('');
     console.log(`  VoidForge — Project Created`);
-    console.log(`  Name:      ${nameFlag}`);
+    console.log(`  Name:      ${name}`);
     console.log(`  Directory: ${result.projectDir}`);
     console.log(`  Files:     ${result.filesCreated} methodology files`);
     console.log(`  Marker:    ${result.markerId}`);
@@ -293,7 +366,8 @@ function showHelp() {
     console.log('  --help, -h         Show this help');
     console.log('  --remote           Launch in remote mode (0.0.0.0 + auth)');
     console.log('  --lan              Launch in LAN mode');
-    console.log('  --headless         CLI-only (no browser)');
+    console.log('  --browser          init: skip the mode prompt and launch the browser wizard');
+    console.log('  --headless         init: CLI-only flow (prompts for name/dir if not passed)');
     console.log('  --self             Deploy VoidForge itself');
     console.log('  --env-only         Write vault credentials to .env');
     console.log('');
@@ -536,14 +610,29 @@ async function main() {
                 console.log('  To rollback: restore from the backup directory.\n');
                 break;
             }
-            case 'init':
-                if (args.includes('--headless')) {
+            case 'init': {
+                const wantsHeadless = args.includes('--headless');
+                const wantsBrowser = args.includes('--browser');
+                if (wantsHeadless) {
                     await cmdInitHeadless();
                 }
-                else {
+                else if (wantsBrowser) {
                     await launchWizard('init');
                 }
+                else if (process.stdin.isTTY) {
+                    const mode = await promptInitMode();
+                    if (mode === 'headless')
+                        await cmdInitHeadless();
+                    else
+                        await launchWizard('init');
+                }
+                else {
+                    console.error('Error: `voidforge init` was run in a non-interactive context without a mode flag.');
+                    console.error('Pass --browser to launch the wizard UI, or --headless [--name "..."] for CLI init.');
+                    process.exit(1);
+                }
                 break;
+            }
             case 'heartbeat': {
                 const subCmd = args[1]; // start | stop | status
                 if (subCmd !== 'start') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voidforge-build",
-  "version": "23.11.0",
+  "version": "23.11.2",
   "description": "From nothing, everything. A methodology framework for building with Claude Code.",
   "type": "module",
   "engines": {

package/dist/wizard/lib/anomaly-detection.d.ts

@@ -1,59 +0,0 @@
-/**
- * Anomaly Detection — Spend spikes, traffic drops, conversion changes (§9.17).
- *
- * Runs hourly as a heartbeat daemon scheduled job.
- * Compares current metrics against rolling averages.
- * Alerts when deviations exceed thresholds.
- *
- * PRD Reference: §9.7 (hourly anomaly detection), §9.17 (thresholds)
- */
-type Cents = number & {
-    readonly __brand: 'Cents';
-};
-type AnomalyType = 'spend_spike' | 'traffic_drop' | 'conversion_change' | 'roas_drop';
-type AnomalySeverity = 'warning' | 'alert' | 'critical';
-interface Anomaly {
-    type: AnomalyType;
-    severity: AnomalySeverity;
-    platform?: string;
-    metric: string;
-    currentValue: number;
-    expectedValue: number;
-    deviationPercent: number;
-    message: string;
-    timestamp: string;
-}
-declare const THRESHOLDS: {
-    spendSpikeWarning: number;
-    spendSpikeAlert: number;
-    spendSpikeCritical: number;
-    trafficDropWarning: number;
-    trafficDropAlert: number;
-    trafficDropCritical: number;
-    conversionChangeThreshold: number;
-    roasDropWarning: number;
-    roasDropAlert: number;
-};
-/** Run all anomaly checks for the current period */
-export declare function runAnomalyDetection(metrics: {
-    spendByPlatform: Array<{
-        platform: string;
-        currentHour: Cents;
-        avgHourly: Cents;
-    }>;
-    traffic: {
-        currentDay: number;
-        avgDaily: number;
-    };
-    conversion: {
-        currentRate: number;
-        avgRate: number;
-    };
-    roasByPlatform: Array<{
-        platform: string;
-        current: number;
-        avg: number;
-    }>;
-}): Anomaly[];
-export type { Anomaly, AnomalyType, AnomalySeverity };
-export { THRESHOLDS };

package/dist/wizard/lib/anomaly-detection.js

@@ -1,122 +0,0 @@
-/**
- * Anomaly Detection — Spend spikes, traffic drops, conversion changes (§9.17).
- *
- * Runs hourly as a heartbeat daemon scheduled job.
- * Compares current metrics against rolling averages.
- * Alerts when deviations exceed thresholds.
- *
- * PRD Reference: §9.7 (hourly anomaly detection), §9.17 (thresholds)
- */
-// ── Thresholds ────────────────────────────────────────
-const THRESHOLDS = {
-    // Spend spike: current hour spend > X% of daily average hourly spend
-    spendSpikeWarning: 50, // 50% above average
-    spendSpikeAlert: 100, // 100% above average (double)
-    spendSpikeCritical: 200, // 200% above average (triple)
-    // Traffic drop: current day traffic > X% below 7-day average
-    trafficDropWarning: 20, // 20% below average
-    trafficDropAlert: 40, // 40% below average
-    trafficDropCritical: 60, // 60% below average
-    // Conversion rate change: > X% from 7-day average
-    conversionChangeThreshold: 20, // 20% change in either direction
-    // ROAS drop: current < X% of 7-day average
-    roasDropWarning: 20, // 20% below average
-    roasDropAlert: 40, // 40% below average
-};
-// ── Detection Functions ───────────────────────────────
-function detectSpendSpike(currentHourSpend, avgHourlySpend, platform) {
-    if (avgHourlySpend === 0)
-        return null;
-    const deviation = ((currentHourSpend - avgHourlySpend) / avgHourlySpend) * 100;
-    if (deviation < THRESHOLDS.spendSpikeWarning)
-        return null;
-    const severity = deviation >= THRESHOLDS.spendSpikeCritical ? 'critical' :
-        deviation >= THRESHOLDS.spendSpikeAlert ? 'alert' : 'warning';
-    return {
-        type: 'spend_spike',
-        severity,
-        platform,
-        metric: 'hourly_spend',
-        currentValue: currentHourSpend,
-        expectedValue: avgHourlySpend,
-        deviationPercent: Math.round(deviation),
-        message: `Spend spike on ${platform}: $${(currentHourSpend / 100).toFixed(2)}/hr vs $${(avgHourlySpend / 100).toFixed(2)}/hr average (+${Math.round(deviation)}%)`,
-        timestamp: new Date().toISOString(),
-    };
-}
-function detectTrafficDrop(currentDayTraffic, avgDailyTraffic) {
-    if (avgDailyTraffic === 0)
-        return null;
-    const deviation = ((avgDailyTraffic - currentDayTraffic) / avgDailyTraffic) * 100;
-    if (deviation < THRESHOLDS.trafficDropWarning)
-        return null;
-    const severity = deviation >= THRESHOLDS.trafficDropCritical ? 'critical' :
-        deviation >= THRESHOLDS.trafficDropAlert ? 'alert' : 'warning';
-    return {
-        type: 'traffic_drop',
-        severity,
-        metric: 'daily_traffic',
-        currentValue: currentDayTraffic,
-        expectedValue: avgDailyTraffic,
-        deviationPercent: -Math.round(deviation),
-        message: `Traffic drop: ${currentDayTraffic} visitors today vs ${avgDailyTraffic} average (-${Math.round(deviation)}%)`,
-        timestamp: new Date().toISOString(),
-    };
-}
-function detectConversionChange(currentRate, avgRate) {
-    if (avgRate === 0)
-        return null;
-    const deviation = ((currentRate - avgRate) / avgRate) * 100;
-    if (Math.abs(deviation) < THRESHOLDS.conversionChangeThreshold)
-        return null;
-    return {
-        type: 'conversion_change',
-        severity: Math.abs(deviation) >= 40 ? 'alert' : 'warning',
-        metric: 'conversion_rate',
-        currentValue: currentRate,
-        expectedValue: avgRate,
-        deviationPercent: Math.round(deviation),
-        message: `Conversion rate ${deviation > 0 ? 'increase' : 'decrease'}: ${currentRate.toFixed(1)}% vs ${avgRate.toFixed(1)}% average (${deviation > 0 ? '+' : ''}${Math.round(deviation)}%)`,
-        timestamp: new Date().toISOString(),
-    };
-}
-function detectRoasDrop(currentRoas, avgRoas, platform) {
-    if (avgRoas === 0)
-        return null;
-    const deviation = ((avgRoas - currentRoas) / avgRoas) * 100;
-    if (deviation < THRESHOLDS.roasDropWarning)
-        return null;
-    return {
-        type: 'roas_drop',
-        severity: deviation >= THRESHOLDS.roasDropAlert ? 'alert' : 'warning',
-        platform,
-        metric: 'roas',
-        currentValue: currentRoas,
-        expectedValue: avgRoas,
-        deviationPercent: -Math.round(deviation),
-        message: `ROAS drop on ${platform}: ${currentRoas.toFixed(1)}x vs ${avgRoas.toFixed(1)}x average (-${Math.round(deviation)}%)`,
-        timestamp: new Date().toISOString(),
-    };
-}
-/** Run all anomaly checks for the current period */
-export function runAnomalyDetection(metrics) {
-    const anomalies = [];
-    for (const s of metrics.spendByPlatform) {
-        const a = detectSpendSpike(s.currentHour, s.avgHourly, s.platform);
-        if (a)
-            anomalies.push(a);
-    }
-    const td = detectTrafficDrop(metrics.traffic.currentDay, metrics.traffic.avgDaily);
-    if (td)
-        anomalies.push(td);
-    const cc = detectConversionChange(metrics.conversion.currentRate, metrics.conversion.avgRate);
-    if (cc)
-        anomalies.push(cc);
-    for (const r of metrics.roasByPlatform) {
-        const a = detectRoasDrop(r.current, r.avg, r.platform);
-        if (a)
-            anomalies.push(a);
-    }
-    return anomalies;
-}
-export { THRESHOLDS };

package/dist/wizard/lib/asset-scanner.d.ts

@@ -1,23 +0,0 @@
-/**
- * PRD asset scanner — identifies image/visual requirements from PRD prose.
- * Used by Celebrimbor's /imagine command to find what needs generating.
- * Pure text analysis — no API calls, no side effects.
- */
-export interface AssetRequirement {
-    description: string;
-    category: string;
-    context: string;
-    width: number;
-    height: number;
-    section: string;
-}
-/**
- * Scan a PRD document for visual asset requirements.
- * Returns a list of assets that need generating.
- */
-export declare function scanPrdForAssets(prdContent: string): AssetRequirement[];
-/**
- * Extract brand/style keywords from the PRD for style prefix generation.
- * Looks for Section 14 (Brand) or any section mentioning "brand", "style", "aesthetic".
- */
-export declare function extractBrandStyle(prdContent: string): string[];