@ijfw/install 1.4.4 → 1.5.1

package/README.md

@@ -1,7 +1,7 @@
 # @ijfw/install
 
 One-command installer for [IJFW](https://gitlab.com/therealseandonahoe/ijfw) -- the AI
-efficiency layer for 14 AI coding agents: Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, Qwen Code, Cline, Kimi Code, OpenClaw, and Aider.
+efficiency layer for 15 AI coding agents: Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, Qwen Code, Cline, Kimi Code, OpenClaw, Antigravity, and Aider.
 
 ## Install
 

package/dist/ijfw.js

@@ -1583,7 +1583,7 @@ var init_project_type_detector = __esm({
 });
 
 // ../mcp-server/src/gate-result.js
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, writeFile, readdir, stat, unlink, appendFile } from "node:fs/promises";
 import { basename, dirname as dirname2, join as join6 } from "node:path";
 async function emitGateResult(gateOpts, context = {}) {
   if (gateOpts === null || typeof gateOpts !== "object") {
@@ -1643,6 +1643,7 @@ async function makeReceipt(gateResult, opts = {}) {
     await mkdir(dirname2(receiptPath), { recursive: true });
     const body = JSON.stringify(gateResult, null, 2) + "\n";
     await writeFile(receiptPath, body, "utf8");
+    await evictOldReceipts(dirname2(receiptPath));
   } catch (err) {
     const msg = err && err.message ? err.message : String(err);
     try {
@@ -1652,6 +1653,58 @@ async function makeReceipt(gateResult, opts = {}) {
     }
   }
 }
+async function evictOldReceipts(dir, opts = {}) {
+  const keep = Number.isFinite(opts.keep) && opts.keep > 0 ? opts.keep | 0 : RECEIPTS_KEEP;
+  try {
+    let entries;
+    try {
+      entries = await readdir(dir);
+    } catch {
+      return { evicted: 0 };
+    }
+    const jsonFiles = entries.filter((f) => f.endsWith(".json"));
+    if (jsonFiles.length <= keep) return { evicted: 0 };
+    const stamped = [];
+    for (const f of jsonFiles) {
+      const full = join6(dir, f);
+      try {
+        const s = await stat(full);
+        stamped.push({ full, name: f, mtimeMs: s.mtimeMs });
+      } catch {
+        stamped.push({ full, name: f, mtimeMs: 0 });
+      }
+    }
+    stamped.sort((a, b2) => b2.mtimeMs - a.mtimeMs);
+    const toEvict = stamped.slice(keep);
+    if (toEvict.length === 0) return { evicted: 0 };
+    const archivePath = join6(dir, RECEIPTS_ARCHIVE);
+    let evicted = 0;
+    for (const victim of toEvict) {
+      try {
+        let body;
+        try {
+          const { readFile } = await import("node:fs/promises");
+          body = await readFile(victim.full, "utf8");
+        } catch {
+          continue;
+        }
+        let archiveLine;
+        try {
+          archiveLine = JSON.stringify(JSON.parse(body)) + "\n";
+        } catch {
+          archiveLine = JSON.stringify({ raw: body, evicted_from: victim.name }) + "\n";
+        }
+        await appendFile(archivePath, archiveLine, "utf8");
+        await unlink(victim.full);
+        evicted++;
+      } catch {
+      }
+    }
+    return { evicted };
+  } catch {
+    return { evicted: 0 };
+  }
+}
 async function resolveProjectType(projectRoot) {
   try {
     const root = typeof projectRoot === "string" && projectRoot.length > 0 ? projectRoot : process.cwd();
@@ -1667,12 +1720,14 @@ async function resolveProjectType(projectRoot) {
     return "unknown";
   }
 }
-var RECEIPT_GATE_ID_PATTERN;
+var RECEIPT_GATE_ID_PATTERN, RECEIPTS_KEEP, RECEIPTS_ARCHIVE;
 var init_gate_result = __esm({
   "../mcp-server/src/gate-result.js"() {
     init_gate_result_schema();
     init_project_type_detector();
     RECEIPT_GATE_ID_PATTERN = /^[a-z][a-z0-9-]+$/;
+    RECEIPTS_KEEP = 1e3;
+    RECEIPTS_ARCHIVE = ".archive.jsonl";
   }
 });
 
@@ -1903,10 +1958,14 @@ import { tmpdir as tmpdir2 } from "node:os";
 async function run10(ctx) {
   const t0 = Date.now();
   const installerDir = join9(ctx.repoRoot, "installer");
+  const cleanEnv = Object.fromEntries(
+    Object.entries(process.env).filter(([k2]) => !k2.startsWith("npm_"))
+  );
   const build = spawnSync10("npm", ["run", "build"], {
     encoding: "utf8",
     cwd: installerDir,
     timeout: 6e4,
+    env: cleanEnv,
     shell: process.platform === "win32"
   });
   if (build.status !== 0) {
@@ -1918,10 +1977,12 @@ async function run10(ctx) {
       durationMs: Date.now() - t0
     };
   }
-  const pack = spawnSync10("npm", ["pack", "--silent"], {
+  const packDir = mkdtempSync2(join9(tmpdir2(), "ijfw-packsmoke-tgz-"));
+  const pack = spawnSync10("npm", ["pack", "--silent", "--pack-destination", packDir], {
     encoding: "utf8",
     cwd: installerDir,
     timeout: 3e4,
+    env: cleanEnv,
     shell: process.platform === "win32"
   });
   if (pack.status !== 0) {
@@ -1943,7 +2004,7 @@ async function run10(ctx) {
       durationMs: Date.now() - t0
     };
   }
-  const tarballPath = resolve(installerDir, tarball);
+  const tarballPath = resolve(packDir, tarball);
   const tmpRoot = mkdtempSync2(join9(tmpdir2(), "ijfw-pack-smoke-"));
   const fakeHome = join9(tmpRoot, "home");
   const installDir = join9(tmpRoot, "install");
@@ -1955,7 +2016,7 @@ async function run10(ctx) {
       encoding: "utf8",
       cwd: installDir,
       timeout: 6e4,
-      env: { ...process.env, HOME: fakeHome, npm_config_prefix: fakeHome },
+      env: { ...cleanEnv, HOME: fakeHome, npm_config_prefix: fakeHome },
       shell: process.platform === "win32"
     });
     if (install.status !== 0) {
@@ -2026,7 +2087,7 @@ async function run10(ctx) {
     } catch {
     }
     try {
-      rmSync2(tarballPath, { force: true });
+      rmSync2(packDir, { recursive: true, force: true });
     } catch {
     }
   }
@@ -2055,10 +2116,14 @@ import { tmpdir as tmpdir3 } from "node:os";
 async function run11(ctx) {
   const t0 = Date.now();
   const installerDir = join10(ctx.repoRoot, "installer");
+  const cleanEnv = Object.fromEntries(
+    Object.entries(process.env).filter(([k2]) => !k2.startsWith("npm_"))
+  );
   const build = spawnSync11("npm", ["run", "build"], {
     encoding: "utf8",
     cwd: installerDir,
     timeout: 6e4,
+    env: cleanEnv,
     shell: process.platform === "win32"
   });
   if (build.status !== 0) {
@@ -2070,10 +2135,12 @@ async function run11(ctx) {
       durationMs: Date.now() - t0
     };
   }
-  const pack = spawnSync11("npm", ["pack", "--silent"], {
+  const packDir = mkdtempSync3(join10(tmpdir3(), "ijfw-upgradesmoke-tgz-"));
+  const pack = spawnSync11("npm", ["pack", "--silent", "--pack-destination", packDir], {
     encoding: "utf8",
     cwd: installerDir,
     timeout: 3e4,
+    env: cleanEnv,
     shell: process.platform === "win32"
   });
   if (pack.status !== 0) {
@@ -2086,7 +2153,7 @@ async function run11(ctx) {
     };
   }
   const tarball = pack.stdout.trim();
-  const tarballPath = resolve2(installerDir, tarball);
+  const tarballPath = resolve2(packDir, tarball);
   const tmpRoot = mkdtempSync3(join10(tmpdir3(), "ijfw-upgrade-smoke-"));
   const fakeHome = join10(tmpRoot, "home");
   const installDir = join10(tmpRoot, "install");
@@ -2100,7 +2167,7 @@ async function run11(ctx) {
       encoding: "utf8",
       cwd: installDir,
       timeout: 6e4,
-      env: { ...process.env, HOME: fakeHome, npm_config_prefix: fakeHome },
+      env: { ...cleanEnv, HOME: fakeHome, npm_config_prefix: fakeHome },
       shell: process.platform === "win32"
     });
     if (install.status !== 0) {
@@ -2195,7 +2262,7 @@ async function run11(ctx) {
     } catch {
     }
     try {
-      rmSync3(tarballPath, { force: true });
+      rmSync3(packDir, { recursive: true, force: true });
     } catch {
     }
   }
@@ -3600,6 +3667,458 @@ import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { existsSync as existsSync6, mkdirSync as mkdirSync5, copyFileSync as copyFileSync3, readdirSync as readdirSync5, rmSync as rmSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "node:fs";
 import { homedir, platform } from "node:os";
 import { spawnSync as spawnSync12 } from "node:child_process";
+
+// src/command-registry.js
+var COMMAND_REGISTRY = Object.freeze([
+  // ---------- TIER 1: PRIMARY (shown in `ijfw --help`) ----------
+  {
+    name: "install",
+    tier: "primary",
+    owner: "installer-direct",
+    description: "Install IJFW into your AI coding agents",
+    aliases: [],
+    since: "1.0.0",
+    status: "active",
+    helpGroup: "GET STARTED"
+  },
+  {
+    name: "uninstall",
+    tier: "primary",
+    owner: "installer-direct",
+    description: "Remove IJFW (alias: off)",
+    aliases: ["off"],
+    since: "1.0.0",
+    status: "active",
+    helpGroup: "GET STARTED"
+  },
+  {
+    name: "doctor",
+    tier: "primary",
+    owner: "installer-direct",
+    description: "Diagnose installation health",
+    aliases: [],
+    since: "1.0.0",
+    status: "active",
+    helpGroup: "GET STARTED"
+  },
+  {
+    name: "update",
+    tier: "primary",
+    owner: "orchestrator",
+    description: "Upgrade to the latest IJFW",
+    aliases: [],
+    since: "1.1.0",
+    status: "active",
+    helpGroup: "GET STARTED"
+  },
+  {
+    name: "demo",
+    tier: "primary",
+    owner: "orchestrator",
+    description: "30-second Trident tour against a sample file",
+    aliases: [],
+    since: "1.2.0",
+    status: "active",
+    helpGroup: "USE IT"
+  },
+  {
+    name: "cross",
+    tier: "primary",
+    owner: "orchestrator",
+    description: "Run Trident audit/research/critique on any file",
+    aliases: ["cross-audit", "cross-critique", "cross-research"],
+    since: "1.2.0",
+    status: "active",
+    helpGroup: "USE IT"
+  },
+  {
+    name: "dashboard",
+    tier: "primary",
+    owner: "installer-direct",
+    description: "Start the local observability dashboard",
+    aliases: [],
+    since: "1.1.0",
+    status: "active",
+    helpGroup: "USE IT"
+  },
+  {
+    name: "preflight",
+    tier: "primary",
+    owner: "installer-direct",
+    description: "Run 11-gate quality pipeline before publishing",
+    aliases: [],
+    since: "1.0.0",
+    status: "active",
+    helpGroup: "USE IT"
+  },
+  {
+    name: "help",
+    tier: "primary",
+    owner: "installer-direct",
+    description: "Open the full IJFW guide",
+    aliases: [],
+    since: "1.0.0",
+    status: "active",
+    helpGroup: "EXPLORE"
+  },
+  {
+    name: "commands",
+    tier: "primary",
+    owner: "installer-direct",
+    description: "Show every command (advanced + coordination)",
+    aliases: [],
+    since: "1.5.1",
+    status: "active",
+    helpGroup: "EXPLORE"
+  },
+  {
+    name: "version",
+    tier: "primary",
+    owner: "orchestrator",
+    description: "Show version",
+    aliases: ["--version", "-v"],
+    since: "1.0.0",
+    status: "active",
+    helpGroup: "EXPLORE"
+  },
+  // ---------- TIER 2: COORDINATION (shown in `ijfw commands`) ----------
+  {
+    name: "status",
+    tier: "coordination",
+    owner: "orchestrator",
+    description: "Show recent cross-audit activity",
+    aliases: [],
+    since: "1.2.0",
+    status: "active"
+  },
+  {
+    name: "receipt",
+    tier: "coordination",
+    owner: "orchestrator",
+    description: "Print a redacted, shareable block from the last Trident run",
+    aliases: [],
+    since: "1.2.0",
+    status: "active"
+  },
+  {
+    name: "recover",
+    tier: "coordination",
+    owner: "orchestrator",
+    description: "Show the latest checkpoint and next recovery step",
+    aliases: [],
+    since: "1.4.0",
+    status: "active"
+  },
+  {
+    name: "team",
+    tier: "coordination",
+    owner: "orchestrator",
+    description: "Assemble project agents, charter, and workflow manifest",
+    aliases: [],
+    since: "1.4.0",
+    status: "active"
+  },
+  {
+    name: "swarm",
+    tier: "coordination",
+    owner: "orchestrator",
+    description: "Plan artifact-aware parallel work from the team manifest",
+    aliases: [],
+    since: "1.4.0",
+    status: "active"
+  },
+  {
+    name: "blackboard",
+    tier: "coordination",
+    owner: "orchestrator",
+    description: "Coordinate project-local swarm state and artifact claims",
+    aliases: [],
+    since: "1.4.0",
+    status: "active"
+  },
+  {
+    name: "memory",
+    tier: "coordination",
+    owner: "orchestrator",
+    description: "Memory checkpoint operations (currently: `memory checkpoint <label>`)",
+    aliases: [],
+    since: "1.3.0",
+    status: "active",
+    notes: 'Only `memory checkpoint <label>` subcommand is implemented today. Top-level `ijfw memory` prints help, not "Unknown command".'
+  },
+  {
+    name: "import",
+    tier: "coordination",
+    owner: "orchestrator",
+    description: "Pull memory in from another tool (claude-mem, rtk)",
+    aliases: [],
+    since: "1.4.0",
+    status: "active"
+  },
+  {
+    name: "design",
+    tier: "coordination",
+    owner: "installer-direct",
+    description: "Live visual design companion + durable design intelligence",
+    aliases: [],
+    since: "1.3.0",
+    status: "active"
+  },
+  // ---------- TIER 3: PLUMBING (hidden by default; surfaced in `ijfw commands`) ----------
+  {
+    name: "statusline",
+    tier: "plumbing",
+    owner: "orchestrator",
+    description: "Manage the statusline integration",
+    aliases: [],
+    since: "1.2.0",
+    status: "active"
+  },
+  {
+    name: "config",
+    tier: "plumbing",
+    owner: "orchestrator",
+    description: "Inspect or audit IJFW configuration",
+    aliases: [],
+    since: "1.2.0",
+    status: "active"
+  },
+  {
+    name: "codex",
+    tier: "plumbing",
+    owner: "orchestrator",
+    description: "Codex-specific helpers (doctor, sync-agents)",
+    aliases: [],
+    since: "1.3.0",
+    status: "active"
+  },
+  {
+    name: "extension",
+    tier: "plumbing",
+    owner: "orchestrator",
+    description: "Manage installed IJFW extensions",
+    aliases: [],
+    since: "1.4.0",
+    status: "active"
+  },
+  {
+    name: "override",
+    tier: "plumbing",
+    owner: "orchestrator",
+    description: "Manage extension overrides",
+    aliases: [],
+    since: "1.4.0",
+    status: "active"
+  },
+  {
+    name: "insight",
+    tier: "plumbing",
+    owner: "orchestrator",
+    description: "Inspect IJFW insights",
+    aliases: [],
+    since: "1.4.0",
+    status: "active"
+  },
+  {
+    name: "ui-review",
+    tier: "plumbing",
+    owner: "orchestrator",
+    description: "Run the visual UI review pipeline against a spec",
+    aliases: [],
+    since: "1.5.0",
+    status: "active"
+  },
+  {
+    name: "--purge-receipts",
+    tier: "plumbing",
+    owner: "orchestrator",
+    description: "Clear the cross-runs receipt log",
+    aliases: [],
+    since: "1.2.0",
+    status: "active",
+    notes: 'Flag-style command (leading "--"). Registered as a name so parity check picks it up; documented under plumbing.'
+  },
+  // ---------- DEPRECATED: pointer-stub aliases ----------
+  // These commands print "use the <X> skill" guidance and exit.
+  // They live behind cross-orchestrator-cli.js COMMAND_ALIAS_HELP (derived from these entries).
+  // Decision: keep them as silent redirects -- they have shipped documentation
+  // pointing at them, removal is a breaking change.
+  // status='deprecated' so help blocks suppress them, but dispatch still handles them.
+  {
+    name: "workflow",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to the ijfw-workflow skill",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Use the ijfw-workflow skill in agents. Terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare."
+  },
+  {
+    name: "handoff",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to the ijfw-handoff skill",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: 'Use the ijfw-handoff skill in agents, or record swarm handoff text with: ijfw blackboard handoff --message "<summary>".'
+  },
+  {
+    name: "compress",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to the ijfw-compress skill",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Use the ijfw-compress skill in agents. Terminal context compression is host-specific and should preserve exact paths, commands, versions, and decisions."
+  },
+  {
+    name: "consolidate",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to the ijfw-handoff or ijfw-memory-audit skill",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Use the ijfw-handoff or ijfw-memory-audit skill to consolidate decisions into memory. For swarm state, run: ijfw memory checkpoint <label>."
+  },
+  {
+    name: "ijfw-audit",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to `ijfw preflight`",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Run verification with: ijfw preflight. For multi-model review, run: ijfw cross audit <target>."
+  },
+  {
+    name: "ijfw-execute",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to ijfw-workflow skill + swarm helpers",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Use ijfw-workflow in agents, then terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare, ijfw swarm start <task-id>."
+  },
+  {
+    name: "ijfw-help",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to `ijfw help`",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Run: ijfw help. Add --browser for the rendered local guide."
+  },
+  {
+    name: "ijfw-plan",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to ijfw-workflow planning skills",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Use ijfw-workflow for planning. Terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare --reviews."
+  },
+  {
+    name: "ijfw-ship",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to `ijfw preflight`",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Run: ijfw preflight. Do not publish or tag until your release gate is explicitly cleared."
+  },
+  {
+    name: "ijfw-verify",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to `ijfw preflight`",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Run: ijfw preflight. For focused review, run: ijfw cross audit <target>."
+  },
+  {
+    name: "memory-audit",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to the ijfw-memory-audit skill",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Use the ijfw-memory-audit skill in agents. Terminal safety net: ijfw recover status and ijfw memory checkpoint <label>."
+  },
+  {
+    name: "memory-consent",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to memory checkpoint",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Use IJFW memory tools only for explicit project memory. Terminal checkpoint: ijfw memory checkpoint <label>."
+  },
+  {
+    name: "memory-why",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to ijfw-recall / ijfw-memory-audit skills",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Use ijfw-recall or ijfw-memory-audit in agents to inspect why memory exists. Terminal recovery state: ijfw recover latest."
+  },
+  {
+    name: "metrics",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to the dashboard (real subcommand: metrics --benchmark)",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Open the dashboard with: ijfw dashboard start. Agent-side metrics are available through ijfw_metrics. Run the memory benchmark harness with: ijfw metrics --benchmark."
+  },
+  {
+    name: "mode",
+    tier: "pointer-stub",
+    owner: "orchestrator",
+    description: "Redirect to `ijfw config --audit`",
+    aliases: [],
+    since: "1.4.0",
+    status: "deprecated",
+    deprecatedReason: "Inspect configuration with: ijfw config --audit. Statusline mode helpers: ijfw statusline --status, --compose, or --disable."
+  }
+]);
+var ORCHESTRATOR_COMMAND_NAMES = Object.freeze(new Set(
+  COMMAND_REGISTRY.filter((e) => e.owner === "orchestrator").flatMap((e) => [e.name, ...e.aliases || []])
+));
+var INSTALLER_DIRECT_COMMAND_NAMES = Object.freeze(new Set(
+  COMMAND_REGISTRY.filter((e) => e.owner === "installer-direct").flatMap((e) => [e.name, ...e.aliases || []])
+));
+var ALL_COMMAND_NAMES = Object.freeze(new Set(
+  COMMAND_REGISTRY.flatMap((e) => [e.name, ...e.aliases || []])
+));
+function primaryCommands() {
+  return COMMAND_REGISTRY.filter(
+    (e) => e.tier === "primary" && e.status === "active"
+  );
+}
+function commandsByTier() {
+  const tiers = { primary: [], coordination: [], plumbing: [] };
+  for (const e of COMMAND_REGISTRY) {
+    if (e.status !== "active") continue;
+    if (tiers[e.tier]) tiers[e.tier].push(e);
+  }
+  return tiers;
+}
+
+// src/ijfw.js
 var __dirname2 = dirname4(fileURLToPath3(import.meta.url));
 function repoRoot() {
   let dir = __dirname2;
@@ -3629,69 +4148,38 @@ function openBrowser(url) {
   const r = platform() === "darwin" ? spawnSync12("open", [url], { stdio: "ignore" }) : platform() === "win32" ? spawnSync12("cmd", ["/c", "start", "", url], { stdio: "ignore", shell: false }) : spawnSync12("xdg-open", [url], { stdio: "ignore" });
   return r.status ?? 0;
 }
-var ORCHESTRATOR_COMMANDS = /* @__PURE__ */ new Set([
-  "update",
-  "statusline",
-  "config",
-  "insight",
-  "blackboard",
-  "team",
-  "swarm",
-  "codex",
-  "recover",
-  "memory",
-  "cross",
-  "status",
-  "demo",
-  "import",
-  "receipt",
-  "--purge-receipts",
-  "workflow",
-  "handoff",
-  "compress",
-  "consolidate",
-  "cross-audit",
-  "cross-critique",
-  "cross-research",
-  "ijfw-audit",
-  "ijfw-execute",
-  "ijfw-help",
-  "ijfw-plan",
-  "ijfw-ship",
-  "ijfw-verify",
-  "memory-audit",
-  "memory-consent",
-  "memory-why",
-  "metrics",
-  "mode",
-  "override",
-  "extension"
-]);
 function printHelp2() {
-  console.log(`
-ijfw -- the AI efficiency layer
-
-USAGE
-  ijfw <command> [options]
-
-COMMANDS
-  install     Install IJFW into your AI coding agents
-  uninstall   Remove IJFW from your AI coding agents
-  help        Open the full IJFW guide (terminal, or --browser for rendered)
-  preflight   Run 11-gate quality pipeline before publishing
-  dashboard   Start / stop / check the local observability dashboard
-  design      Manage live previews and durable design intelligence
-  blackboard  Coordinate project-local swarm state and artifact claims
-  codex       Check and sync Codex-native IJFW surfaces
-  team        Assemble project agents, charter, and workflow manifest
-  swarm       Plan, prepare, and track artifact-aware parallel work
-  recover     Show latest checkpoint and next recovery step
-  cross       Run Trident audit/research/critique, e.g. ijfw cross audit README.md
-  doctor      Diagnose IJFW installation health
-
-  --help, -h  Show this help
-  --version   Show version
-`);
+  const grouped = { "GET STARTED": [], "USE IT": [], "EXPLORE": [] };
+  for (const e of primaryCommands()) {
+    if (grouped[e.helpGroup]) grouped[e.helpGroup].push(e);
+  }
+  let out = "\nijfw -- the AI efficiency layer\n\nUSAGE\n  ijfw <command> [options]\n";
+  for (const [group, entries] of Object.entries(grouped)) {
+    if (entries.length === 0) continue;
+    out += `
+${group}
+`;
+    for (const e of entries) {
+      const displayName = e.name === "version" ? "--version" : e.name;
+      const padded = displayName.padEnd(11);
+      const descMentionsAlias = /\(alias:/i.test(e.description);
+      const aliasNote = e.aliases.length && e.name !== "version" && !descMentionsAlias ? ` (alias: ${e.aliases.join(", ")})` : "";
+      out += `  ${padded} ${e.description}${aliasNote}
+`;
+    }
+  }
+  console.log(out);
+}
+function printCommands() {
+  const t = commandsByTier();
+  let out = "\nijfw -- full command surface\n";
+  out += "\nPRIMARY (shown in --help)\n";
+  out += "  " + t.primary.map((e) => e.name).join(" \xB7 ") + "\n";
+  out += "\nCOORDINATION (agents drive these; humans inspect)\n";
+  out += "  " + t.coordination.map((e) => e.name).join(" \xB7 ") + "\n";
+  out += "\nPLUMBING (most users never need these)\n";
+  out += "  " + t.plumbing.map((e) => e.name).join(" \xB7 ") + "\n";
+  console.log(out);
 }
 function doctorCheck(cmd, args) {
   const r = spawnSync12(cmd, args, { encoding: "utf8" });
@@ -3719,6 +4207,10 @@ async function main() {
     printHelp2();
     process.exit(0);
   }
+  if (sub === "commands") {
+    printCommands();
+    process.exit(0);
+  }
   if (sub === "--version" || sub === "-v" || sub === "version") {
     const verbose = argv.slice(3).includes("--verbose");
     if (delegateToCli(argv.slice(2))) return;
@@ -3734,7 +4226,12 @@ async function main() {
     }
     process.exit(0);
   }
-  if (ORCHESTRATOR_COMMANDS.has(sub)) {
+  if (sub === "off") {
+    const uninstallBin = resolve4(__dirname2, "..", "dist", "uninstall.js");
+    const r = spawnSync12("node", [uninstallBin, ...argv.slice(3)], { stdio: "inherit" });
+    process.exit(r.status ?? 1);
+  }
+  if (ORCHESTRATOR_COMMAND_NAMES.has(sub)) {
     if (delegateToCli(argv.slice(2))) return;
     console.error(`'ijfw ${sub}' requires a completed IJFW install. Run: ijfw install`);
     process.exit(1);

package/dist/install.js

@@ -204,6 +204,8 @@ function isLive(targetId, home) {
       return hasBin("openclaw") || existsSync3(join3(H, ".openclaw"));
     case "aider":
       return hasBin("aider") || existsSync3(join3(H, ".aider.conf.yml"));
+    case "antigravity":
+      return hasBin("antigravity") || hasBin("agy") || existsSync3(join3(H, ".local", "bin", "agy")) || existsSync3(join3(H, ".gemini", "antigravity")) || existsSync3("/Applications/Antigravity.app");
     default:
       return false;
   }
@@ -223,14 +225,16 @@ function prettyName(targetId) {
     cline: "Cline",
     kimi: "Kimi Code",
     openclaw: "OpenClaw",
-    aider: "Aider"
+    aider: "Aider",
+    antigravity: "Antigravity"
   };
   return map[targetId] || String(targetId);
 }
 function readJsonOrEmpty(path3) {
   if (!existsSync3(path3)) return {};
   try {
-    const raw = readFileSync2(path3, "utf8") || "{}";
+    const raw = readFileSync2(path3, "utf8");
+    if (!raw || raw.trim() === "") return {};
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
     return parsed;
@@ -1206,6 +1210,22 @@ function installAider(ctx) {
   printOk("Aider: rules-only install (~/.aider.conf.yml + ~/CONVENTIONS.md). No MCP -- Aider lacks a native MCP client.");
   return { status: "ok" };
 }
+function installAntigravity(ctx) {
+  if (ctx.ijfwCustomDir || ctx.isIjfwSource) {
+    printInfo("Skipping Antigravity platform writes (custom-dir or IJFW source tree).");
+    printOk("Antigravity: real platform config left untouched.");
+    return { status: "noop" };
+  }
+  const serverJs = ctx.serverJsNative || ctx.serverJs;
+  const ideDst = path.join(ctx.home, ".gemini", "antigravity", "mcp_config.json");
+  ensureDir2(path.dirname(ideDst));
+  mergeJson(ideDst, serverJs);
+  const cliDst = path.join(ctx.home, ".gemini", "config", "mcp_config.json");
+  ensureDir2(path.dirname(cliDst));
+  mergeJson(cliDst, serverJs);
+  printOk(`Merged MCP into ${ideDst} + ${cliDst} (Antigravity IDE + CLI)`);
+  return { status: "ok" };
+}
 var init_install_targets_8_14 = __esm({
   "src/install-targets-8-14.js"() {
     init_install_helpers();
@@ -1811,7 +1831,8 @@ var init_install_flow = __esm({
       "cline",
       "kimi",
       "openclaw",
-      "aider"
+      "aider",
+      "antigravity"
     ];
     TARGET_FNS = {
       claude: installClaude,
@@ -1827,7 +1848,8 @@ var init_install_flow = __esm({
       cline: installCline,
       kimi: installKimi,
       openclaw: installOpenclaw,
-      aider: installAider
+      aider: installAider,
+      antigravity: installAntigravity
     };
     install_flow_default = { runInstall, CANONICAL_ORDER };
   }
@@ -2211,7 +2233,7 @@ async function main() {
   } catch {
   }
   console.log("");
-  console.log("IJFW now active across 14 platforms -- one memory layer, all your models, zero config.");
+  console.log("IJFW now active across 15 platforms -- one memory layer, all your models, zero config.");
   console.log("  Run `ijfw demo` to see the Trident in action.");
   console.log("  Run `ijfw doctor` to confirm which auditors are reachable.");
   console.log("  Privacy: everything stays local. See NO_TELEMETRY.md.");

package/dist/uninstall.js

@@ -109,12 +109,13 @@ function writeAtomic(target, content) {
   }
 }
 function parseArgs(argv) {
-  const out = { dir: null, purge: false, noMarketplace: false };
+  const out = { dir: null, purge: false, noMarketplace: false, yes: false };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--dir") out.dir = argv[++i];
     else if (a === "--purge") out.purge = true;
     else if (a === "--no-marketplace") out.noMarketplace = true;
+    else if (a === "--yes" || a === "-y") out.yes = true;
     else if (a === "--help" || a === "-h") {
       printHelp();
       process.exit(0);
@@ -124,11 +125,31 @@ function parseArgs(argv) {
 }
 function printHelp() {
   console.log(`ijfw-uninstall -- reverse IJFW install
-Usage: ijfw-uninstall [--dir <path>] [--purge] [--no-marketplace]
+Usage: ijfw-uninstall [--dir <path>] [--purge] [--no-marketplace] [--yes]
   --purge           also remove memory/ (destructive)
   --no-marketplace  skip ~/.claude/settings.json edits
+  --yes, -y         skip the confirmation prompt (for scripted use)
 `);
 }
+function confirm(question) {
+  return new Promise((res) => {
+    process.stdout.write(question);
+    const onData = (chunk) => {
+      process.stdin.removeListener("data", onData);
+      try {
+        process.stdin.pause();
+      } catch {
+      }
+      const answer = String(chunk).trim().toLowerCase();
+      res(answer === "y" || answer === "yes");
+    };
+    try {
+      process.stdin.resume();
+    } catch {
+    }
+    process.stdin.once("data", onData);
+  });
+}
 var HOME = homedir2();
 var TS = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
 function backupFile(p) {
@@ -364,7 +385,18 @@ async function main() {
   const opts = parseArgs(process.argv);
   const target = resolveTarget(opts);
   console.log("This will remove IJFW configuration. Your memory at ~/.ijfw/memory/ will be preserved. Delete manually if desired.");
+  if (opts.purge) {
+    console.log("WARNING: --purge will also DELETE ~/.ijfw/memory/ (project memory cannot be recovered).");
+  }
   console.log("");
+  if (!opts.yes && process.stdin.isTTY) {
+    const ok = await confirm("Proceed with IJFW uninstall? [y/N] ");
+    if (!ok) {
+      console.log("Uninstall cancelled. Nothing was changed.");
+      process.exit(0);
+    }
+    console.log("");
+  }
   if (!existsSync2(target)) {
     console.log(`IJFW directory absent (${target}); platform cleanup only.`);
   } else if (opts.purge) {

package/docs/GUIDE.md

@@ -1,9 +1,11 @@
 <p align="center">
-  <img src="https://gitlab.com/therealseandonahoe/ijfw/releases/download/v1.1.1/ijfw-hero.png" alt="IJFW" width="100%"/>
+  <img src="guide/assets/hero.png" alt="IJFW" width="100%"/>
 </p>
 
 # The IJFW Guide
 
+> **Note**: This guide is being rewritten for v1.5.x in milestone v1.5.1 W5. Some sections are out of date.
+
 **90 seconds to your first win. 10 minutes to the full tour. 45 minutes to master it.**
 
 This guide is bundled with every install. Run `ijfw help` in your terminal for the terminal-native version, or `ijfw help --browser` to read it in a rendered browser tab with images and syntax highlighting.
@@ -40,7 +42,7 @@ One command. Three seconds.
 npm install -g @ijfw/install && ijfw-install
 ```
 
-That installs the npm package, runs the installer, and wires up every AI coding agent it finds on your machine. Claude Code, Codex, Gemini, Cursor, Windsurf, and Copilot all pick up the shared memory and the same workflow discipline.
+That installs the npm package, runs the installer, and wires up every AI coding agent it finds on your machine. All 15 supported platforms — Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot, Hermes, Wayland, Antigravity, and the rest — pick up the shared memory and the same workflow discipline.
 
 If you do not type commands, paste this block into Claude Code, Cursor, or any other AI coding agent. It will install IJFW for you, verify the MCP server handshake, and tell you when to restart.
 
@@ -82,16 +84,16 @@ In Claude Code, the same runs as `/cross-audit <file>` or simply "cross-audit th
 
 Tell IJFW a decision in one session. Ask for it in another. No configuration required.
 
-**Session A, any project:**
+**Session A, any project:** ask your AI in plain language to remember a decision. In Claude Code, the `ijfw-auto-memorize` skill captures it. To force a snapshot from the shell:
 
 ```bash
-ijfw memory store "We pin all npm packages to exact versions, no carets, decided 2026-04-19 because dependabot churn was destabilizing CI."
+ijfw memory checkpoint "We pin all npm packages to exact versions, no carets, decided 2026-04-19 because dependabot churn was destabilizing CI."
 ```
 
-**Session B, a completely different project, hours or days later:**
+**Session B, a completely different project, hours or days later:** ask "what did we decide about version pinning?" The `ijfw-recall` skill (Claude Code) or the MCP `ijfw_memory_search` tool (any platform) surfaces it. To query from the shell:
 
 ```bash
-ijfw memory recall "version pinning"
+ijfw memory search "version pinning"
 ```
 
 It comes back. Full quote, original date, original project. Your AI is no longer amnesiac.
@@ -142,7 +144,7 @@ Every IJFW command sits on top of one opinionated workflow: **Think, Build, Ship
 
 Every phase is conversational. One question at a time. No monologues. Every artifact summarizes in chat before it writes to disk. Every gate is a user-facing checklist, never a silent pass.
 
-To start: say "let's plan a new feature", "help me ship this", or "let's build X". In Claude Code the same triggers as `/workflow` or `/ijfw-plan`.
+To start: say "let's plan a new feature", "help me ship this", or "let's build X". The `ijfw-workflow` skill auto-loads from the trigger phrase.
 
 ### The observability dashboard
 
@@ -172,9 +174,9 @@ Run `/team setup` in Claude Code, or `ijfw team` from the shell, to see your cur
 |------|-------|--------------|
 | Hot  | Plain markdown in `.ijfw/memory/` | Always on. Instant reads. Git friendly. |
 | Warm | BM25 ranked search | Always on. Scales to around 10,000 entries per project. |
-| Cold | Optional semantic vectors | Off by default. Requires a user-installed embedding provider. |
+| Cold | Optional semantic vectors (hybrid BM25 + cosine rerank) | Off by default. Enable with `IJFW_VECTORS=on` and `npm i @xenova/transformers` (one-time ~23MB MiniLM model cached locally). Top-K BM25 candidates are reranked via cosine similarity with weights 0.6 BM25 / 0.4 vector. Pure no-op fallback to BM25 if disabled, the package isn't installed, or the model fails to load. |
 
-Every session also ends with an optional "dream cycle". Run `/consolidate` or "run a dream cycle" to have IJFW sweep the day's memory: promote observed patterns into your knowledge base, prune stale entries, reconcile contradictions, optionally lift winners into global memory so every future project benefits. Memory that grows sharper over time instead of heavier.
+Every session also ends with an optional "dream cycle". Say "run a dream cycle" or "consolidate memory" and the `ijfw-auto-memorize` skill sweeps the day's memory: promote observed patterns into your knowledge base, prune stale entries, reconcile contradictions, optionally lift winners into global memory so every future project benefits. Memory that grows sharper over time instead of heavier.
 
 ### Smart routing and the token economy
 
@@ -182,11 +184,7 @@ Inside Claude Code, tasks dispatch to the right model automatically. Reads go to
 
 Typical observed saving: 25 percent or more output reduction versus an unmanaged baseline (same task, same prompt, no IJFW rules or routing applied). Your mileage varies by task, model, and cache state. The savings print in every session receipt so you can audit every claim against your own logs.
 
-To see the running total with a breakdown by platform and session:
-
-```bash
-ijfw metrics
-```
+To see the running total with a breakdown by platform and session, ask your AI for "session metrics" — the `ijfw_metrics` MCP tool surfaces tokens, cost, and routing mix from `.ijfw/metrics/sessions.jsonl`.
 
 ---
 
@@ -194,11 +192,11 @@ ijfw metrics
 
 By tomorrow your AI already feels different. Three small habits compound the effect.
 
-1. **End every significant session with `ijfw handoff`.** It writes a short file other sessions can pick up from. New session, say "recall" or `/handoff`, and you are back in context instantly.
+1. **End every significant session by asking your AI to "write a handoff".** The `ijfw-handoff` skill writes a short file other sessions can pick up from. New session, say "recall last handoff" and you are back in context instantly.
 
 2. **Run `ijfw cross audit` before you merge anything meaningful.** Even if you are the only reviewer, the Trident is a second opinion that costs pennies and catches what single-model eyes miss. Most IJFW users wire it into their git post-commit hook after a week.
 
-3. **Say "consolidate" once a week.** The dream cycle keeps memory sharp. Without it, memory grows heavier instead of smarter.
+3. **Ask your AI to "consolidate memory" once a week.** The dream cycle keeps memory sharp. Without it, memory grows heavier instead of smarter.
 
 Everything else in IJFW builds on those three habits. Part 2 below is the full reference if you want to see every command and every skill.
 
@@ -227,17 +225,14 @@ Every command ships in three forms: a shell command, a Claude Code slash command
 | `ijfw status` | Hero line plus recent activity plus cache savings. |
 | `ijfw doctor` | Probe every AI CLI and API key. Tells you what is live and what is standing by. |
 | `ijfw help` | Show this guide, paged. Add `--browser` to render in a browser tab. |
-| `ijfw handoff` | Save a context handoff for the next session. |
 | `ijfw receipt last` | Print the last Trident receipt, redacted and shareable. |
 
 ### Memory
 
 | Command | Purpose |
 |---------|---------|
-| `ijfw memory store "<text>"` | Persist a decision, pattern, or note. |
-| `ijfw memory recall "<query>"` | BM25 ranked search over local memory. |
-| `ijfw memory status` | Roughly 200-token project brief. Mode, pending, last handoff. |
-| `ijfw memory search --scope all "<query>"` | Search across every registered IJFW project on this machine. |
+| `ijfw memory checkpoint "<text>"` | Snapshot a decision, pattern, or note to local memory. |
+| `ijfw memory search "<query>"` | BM25 ranked search over local memory. Add `--scope all` to search every registered IJFW project. |
 | `ijfw import claude-mem` | Absorb existing claude-mem SQLite memory into IJFW markdown. |
 | `ijfw import claude-mem --all` | Discover projects automatically, import in bulk. |
 | `ijfw import claude-mem --dry-run` | Show what would happen first. |
@@ -258,7 +253,6 @@ Every command ships in three forms: a shell command, a Claude Code slash command
 | `ijfw dashboard start` | Bind `127.0.0.1:37891`, open the dashboard tab. |
 | `ijfw dashboard stop` | Graceful shutdown. |
 | `ijfw dashboard status` | Port plus observation count. |
-| `ijfw metrics` | Tokens, cost, routing mix, session totals. |
 
 ### Quality gates
 
@@ -320,7 +314,7 @@ Full list in Claude Code: run `/ijfw` or just type `ijfw` in conversation to see
 
 ## Workflow modes
 
-IJFW auto-picks from your prompt. You can also pick explicitly with `ijfw-plan quick` or `ijfw-plan deep`.
+IJFW auto-picks from your prompt. You can also state your preference explicitly ("plan this in quick mode" or "use deep mode") and the `ijfw-workflow` skill will route accordingly.
 
 ### Quick mode (3 to 5 minutes)
 
@@ -355,17 +349,21 @@ Every module is a single question, answered in chat. Artifacts summarize in chat
 
 ## Platform parity
 
-IJFW configures six AI coding agents with native affordances on each, plus a universal rules file you can paste into anything else.
+IJFW configures 15 AI coding agents with native affordances on each, plus a universal rules file you can paste into anything else. Every platform speaks the same MCP server (13 tools), the same memory tiers, and the same observation ledger.
 
 | Platform | What ships |
 |----------|------------|
-| Claude Code | Native plugin via marketplace, MCP auto-registered, 6 hook events / 12 scripts, 22 on-demand skills, 22 slash commands |
-| Codex CLI | Native plugin (`.codex-plugin/plugin.json`), 19 skills, 5 hook events, MCP registered, marketplace-ready |
-| Gemini CLI | Native extension (`gemini-extension.json`), 19 skills, 11 hook events, 19 TOML slash commands, policy engine, BeforeModel injection, checkpointing |
+| Claude Code | Native plugin via marketplace, MCP auto-registered, full hook lifecycle, on-demand skills, slash commands |
+| Codex CLI | Native plugin (`.codex-plugin/plugin.json`), skills, hook events, MCP registered, marketplace-ready |
+| Gemini CLI | Native extension (`gemini-extension.json`), skills, hook events, TOML slash commands, policy engine, BeforeModel injection, checkpointing |
 | Cursor | `.cursor/mcp.json` plus `.cursor/rules/ijfw.mdc`. Dashboard view-only. |
 | Windsurf | `~/.codeium/windsurf/mcp_config.json` plus `.windsurfrules`. Dashboard view-only. |
 | Copilot (VS Code) | `.vscode/mcp.json` plus `.github/copilot-instructions.md`. Dashboard view-only. |
-| Universal | `universal/ijfw-rules.md`. Paste into anything else. |
+| Hermes CLI | `HERMES.md` plus MCP registration in `~/.hermes/config.yaml`. |
+| Wayland CLI | `WAYLAND.md` plus MCP registration in `~/.wayland/config.yaml`. |
+| Antigravity | `~/.gemini/antigravity/mcp_config.json` (Google's VS Code-fork agentic IDE; Windsurf-identical MCP schema). Agent context via shared `AGENTS.md`. Dashboard view-only. |
+| Additional MCP-aware agents | IJFW detects and configures the remaining supported agents via their native MCP and rules-file integrations to reach 15 total. |
+| Universal | `universal/ijfw-rules.md`. 20-line paste-anywhere rules file for anything else. |
 
 ### Observation ledger parity
 
@@ -377,8 +375,9 @@ IJFW configures six AI coding agents with native affordances on each, plus a uni
 | Cursor      | view-only              | yes | none |
 | Windsurf    | view-only              | yes | none |
 | Copilot     | view-only              | yes | none |
+| Hermes / Wayland / other MCP-aware agents | view-only | yes | none |
 
-Claude, Codex, and Gemini write one JSONL line per tool call. Cursor, Windsurf, and Copilot have no hook lifecycle IJFW can write from, so they read the shared ledger via the dashboard instead. Same engine behind all of them.
+Claude, Codex, and Gemini write one JSONL line per tool call. The remaining platforms have no hook lifecycle IJFW can write from, so they read the shared ledger via the dashboard instead. Same engine behind all of them.
 
 ---
 
@@ -510,7 +509,7 @@ Every install writes a log to `~/.ijfw/install.log`. Every session writes observ
 ## FAQ
 
 **Is this just a Claude Code plugin?**
-No. Claude Code is one of six platforms. The plugin is richest there because Claude Code exposes the most integration points. Every capability is available on the other five through their native MCP and rules-file integrations.
+No. Claude Code is one of 15 platforms. The plugin is richest there because Claude Code exposes the most integration points. Every capability is available on the other agents through their native MCP and rules-file integrations.
 
 **Do I need a specific AI provider?**
 No. IJFW configures the agents you already have. Bring your own keys, your own CLIs. The Trident uses whatever auditors are reachable on your machine. One is enough to start.
@@ -534,7 +533,7 @@ MCP handshake is about 50 ms. Hooks are under 30 ms. Memory recall across thousa
 `ijfw update` pulls latest and reinstalls merge-safely. Your memory is preserved.
 
 **Does it work on Windows?**
-Yes. Git Bash (bundled with Git for Windows) is the supported shell. A PowerShell entry point lives at `installer/src/install.ps1` for users who prefer native PowerShell.
+Yes. The installer is Node-native end to end -- no bash, no WSL, no Git for Windows shell required. A PowerShell entry point lives at `installer/src/install.ps1`; if execution policy blocks it, run `powershell -ExecutionPolicy Bypass -File .\install.ps1`.
 
 **Can my team share memory?**
 Yes. `.ijfw/team/` is git-committed by default. Decisions, patterns, and stack conventions travel with the repo. A new hire's first session inherits all of it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/install",
-  "version": "1.4.4",
+  "version": "1.5.1",
   "description": "One-command installer for IJFW -- the AI efficiency layer. One install, every AI coding agent, zero config.",
   "type": "module",
   "bin": {