wkappbot-code 0.3.12 → 0.3.13

package/README.md

@@ -41,6 +41,7 @@ Other roads to the CLI: `npm i -g https://kiexpert.github.io/wkappbot-kih/wkappb
 | part | what `install` lays down | skip with |
 |---|---|---|
 | opencode | pinned `opencode-ai@1.19.5` (`npm -g`) | `--no-npm` |
+| ai-clis | the well-known AI coding CLIs `claude` (`@anthropic-ai/claude-code`), `codex` (`@openai/codex`), `gemini` (`@google/gemini-cli`) and `qwen` (`@qwen-code/qwen-code`), in one `npm -g` pass; no key or login is asked (each CLI asks for its own sign-in on first run), and a CLI that fails to install is a WARN, never a failed install | `--no-ai-clis` or `--no-npm` |
 | plugin | `plugin/wisdom-kernel.js` + `lib/wk-hook.js` plus the `opencode.json` plugin entry | -- |
 | bin | the `wkappbot` core for this platform from the SDK latest release asset `wkappbot-<platform>`, accepted only when it matches its `SHA256SUMS` line (`lib/wk-bin-acquire.sh`); placed at `~/.local/share/wkappbot/wkappbot` and linked as `wkappbot` beside `wkappbot-code` | `--no-bin` |
 | harness | when no harness checkout is found, the scrubbed web harness to `~/.wk-harness` through its own published `install.sh` (sha256-checked); `--web-harness` forces it | `--no-harness` |
@@ -48,6 +49,8 @@ Other roads to the CLI: `npm i -g https://kiexpert.github.io/wkappbot-kih/wkappb
 
 `install` prints whether `pwsh` was found and which harness will give the verdict. The harness install ends with an advisory line, `[wk-verify] WARN n/6 advisory, not a failure -- c2 ...; c5 ...; c6 ...`, naming each check that missed and why; in a good web install c2 (wkhippo), c5 (core skill read before the core is linked) and c6 (no harness git checkout) are expected to miss. The verdict file is `~/.wkappbot-code/verify.json`.
 
+`npm install wkappbot-code` sets your global git `core.hooksPath` to `~/.wk-harness-hooks` (the push-owner gate, which then runs the repo's own hooks); `wkappbot-code uninstall` puts the previous value back, and leaves it alone if you changed it since.
+
 The skills are a **read-only copy**: the HQ has no git remote, and a skill you edit yourself lands in the private home `~/.wkappbot/private-skills`, a local git repo with no remote. Doctor's `skill-push = owner-only` row names the GitHub login a push would use.
 
 The generated `opencode.json` holds the minimum: `$schema` and the plugin entry (with `kihDir`, the harness the plugin calls). No provider and no permission block is added, because no refusal depends on one (every refusal comes from the plugin and the harness). An existing `opencode.json` is backed up (`opencode.json.bak-<stamp>`) and only the plugin entry is merged in; every other key you set stays. A config that is not plain JSON is left untouched, and `wkappbot-code.json` is written beside it for you to merge by hand. `wkappbot-code config` detects the provider and model from the API-key variables that are set (values are never read) and lets you edit them. Pass `--kih-dir` (or set `WK_KIH_DIR`) when a harness checkout is not auto-found (`~/wkappbot-kih` is searched). Relocation and mock overrides: `WK_BIN_BASE`, `WK_HARNESS_BASE`, `WK_HARNESS_DIR`, `WK_BIN_DEST`, `WK_APPBOT_HQ`, `WK_LINK_DIR`, `WK_PRIVATE_SKILLS`, `WK_SETTINGS`.

package/bin/prepack.js

@@ -39,6 +39,14 @@ if (!stage) {
   if (r.status !== 0) die("harness bake rc " + r.status + "\n" + String(r.stderr).slice(-800));
 }
 if (!existsSync(join(stage, "tools", "wkharness-lite.sh"))) die("the baked tree " + stage + " has no tools/wkharness-lite.sh");
+// The study-lock rule table, built here once (python3 on the build machine) and shipped as tools/wkharness-lite-rules.tsv,
+// so a user machine with no python3 still gets the study lock (owner 2026-11-09: the web install failed without python).
+{
+  const w = spawnSync("sh", [sh(join(stage, "tools", "wkharness-lite.sh")), "--wire"], { encoding: "utf8" });
+  const built = join(stage, ".tmp", "hook-lite", "rules.tsv");
+  if (w.status === 0 && existsSync(built)) { copyFileSync(built, join(stage, "tools", "wkharness-lite-rules.tsv")); rmSync(join(stage, ".tmp"), { recursive: true, force: true }); }
+  else die("study-lock rule table not built (needs python3 on the BUILD machine): rc " + w.status + " " + String(w.stderr || "").slice(-300));
+}
 
 rmSync(OUT, { recursive: true, force: true });
 mkdirSync(OUT, { recursive: true });

package/bin/wkappbot-code.js

@@ -3,6 +3,8 @@
 //   wkappbot-code --version            package version and the pinned OpenCode release
 //   wkappbot-code install [opts]       ONE COMMAND lays down every part (idempotent):
 //       opencode   pinned opencode-ai (npm -g)                                   skip: --no-npm
+//       ai-clis    the famous AI CLIs claude, codex, gemini, qwen (npm -g, login-free; lib/ai-clis.js); a failure
+//                  is a WARN, never a failed part                               skip: --no-ai-clis or --no-npm
 //       plugin     plugin/wisdom-kernel.js + lib/wk-hook.js + the opencode.json plugin entry      (always)
 //       bin        the wkappbot core for this platform, from the SDK latest release asset verified by
 //                  SHA256SUMS -- the SAME road as tools/wk-bin-acquire.sh of the harness repo, shipped
@@ -40,6 +42,11 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { quietCheck, runUpdate, updateRow } from "../lib/update.js"; import { rmTreeHard } from "../lib/rmtree.js"; import { plainFileUrl } from "../lib/fileurl.js";
 import { applySets, askEach, buildConfig, configRow, detect, lineDiff, printDetected } from "../lib/config.js";
+import { aiCliRows, installAiClis, removeAiClis } from "../lib/ai-clis.js";
+import { hooksRow, wireClaudeHooks } from "../lib/hook-wire.js";
+import { installStarterMd, removeStarterMd } from "../lib/starter-md.js";
+import { addAllows, removeAllows } from "../lib/allow-compact.js";
+import { ensurePrereqs } from "../lib/prereq.js";
 import { files as setupFiles, launchOpenCode, printBanner } from "../lib/setup-run.js";
 
 const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -74,11 +81,13 @@ const tarArgs = (tgz, dir) => {
 };
 
 function parseArgs(argv) {
-  const o = { cmd: argv[0] || "help", npm: true, bin: true, harness: true, skills: true, webHarness: false, devSeat: false,
+  const o = { cmd: argv[0] || "help", npm: true, aiClis: true, allows: true, bin: true, harness: true, skills: true, webHarness: false, devSeat: false,
     configDir: "", kihDir: "", binDest: "", hqDir: "", update: false, autoUpdate: false, yes: false, project: false, sets: [] };
   for (let i = 1; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--no-npm") o.npm = false;
+    else if (a === "--no-ai-clis") o.aiClis = false;
+    else if (a === "--no-allows") o.allows = false;
     else if (a === "--no-bin") o.bin = false;
     else if (a === "--no-harness") o.harness = false;
     else if (a === "--no-skills") o.skills = false;
@@ -182,13 +191,14 @@ function installBin(o) {
   const dest = binDest(o);
   const plat = platformId();
   if (!plat) return { ok: false, dest, note: "no wkappbot build for " + process.platform + "-" + process.arch };
-  if (plat === "win-x64") return { ok: false, dest, note: "win-x64 has no single SDK asset; run install.cmd from a harness checkout" };
   // A checkout runs its own copy (same bytes, plus the MANIFEST-verified repo bin/ fallback); the package
-  // copy outside a checkout takes only the SDK release asset verified by SHA256SUMS.
+  // copy outside a checkout takes only the SDK release asset verified by SHA256SUMS. win-x64 (2026-11-09: no checkout
+  // meant NO core at all) takes the release pair wkappbot.exe + wkappbot-core.exe.xz into the DIRECTORY of dest.
   const co = kihCheckout(o);
   const script = co && existsSync(join(co, "tools", "wk-bin-acquire.sh")) ? join(co, "tools", "wk-bin-acquire.sh") : join(PKG_DIR, "lib", "wk-bin-acquire.sh");
-  log("bin: bash " + script + " acquire --dest " + dest);
-  const r = spawnSync("bash", [shPath(script), "acquire", "--dest", shPath(dest)], { encoding: "utf8", env: shEnv() });
+  const target = plat === "win-x64" ? dirname(dest) : dest;
+  log("bin: bash " + script + " acquire --dest " + target);
+  const r = spawnSync("bash", [shPath(script), "acquire", "--dest", shPath(target)], { encoding: "utf8", env: shEnv() });
   for (const line of ((r.stdout || "") + (r.stderr || "")).split("\n").filter(Boolean)) log("  " + line);
   // rc 3 = the release host could not be reached (a package-registry-only VM): no core, but NOT a failed install --
   // the hooks and the lite harness need no core and still refuse the risky classes. A sha256 mismatch stays rc 1.
@@ -197,6 +207,16 @@ function installBin(o) {
   // Put `wkappbot` on PATH beside wkappbot-code itself, unless that name is already taken by someone else.
   let link = "";
   const ld = linkDir();
+  if (IS_WIN) {
+    // Windows: a symlink needs developer mode, so the PATH entry is a .cmd shim beside wkappbot-code.cmd.
+    const cp = join(ld, "wkappbot.cmd");
+    try {
+      const mine = existsSync(cp) && readFileSync(cp, "utf8").includes(dest);
+      if (existsSync(cp) && !mine) log("bin: kept existing " + cp + " (not ours); call " + dest + " directly");
+      else { writeFileSync(cp, "@echo off\r\n\"" + dest + "\" %*\r\n"); link = cp; log("bin: wrote " + cp + " -> " + dest); }
+    } catch (e) { log("bin: could not write " + cp + " (" + e.message + ")"); }
+    return { ok: true, dest, link };
+  }
   const lp = join(ld, "wkappbot");
   try {
     const taken = existsSync(lp) || isSymlink(lp);
@@ -401,6 +421,10 @@ function install(o) {
   const prev = readState(o);
   const st = { version: PKG.version, at: new Date().toISOString(), prior: recordPrior(prev) };
   let bad = 0;
+  // 0.3.13 (owner 2026-11-09: Git Bash is a required tool too): bash, sh, curl, tar and git first; on Windows a Git that
+  // is not on PATH is used from its folder, and a missing one is installed with winget (lib/prereq.js)
+  st.prereq = ensurePrereqs({ log });
+  if (!st.prereq.ok) bad++;
   if (o.update) log("install --update: refreshing the core, the harness and the public skills");
   const ps = pwshPath();
   log("pwsh: " + (ps || "not found") + " -- the FULL harness (PowerShell 7) runs only on a dev seat (a harness checkout, or --dev-seat);" +
@@ -416,15 +440,26 @@ function install(o) {
       catch (e) { bad++; log("opencode: npm install FAILED (" + String(e.message).split("\n")[0] + ") -- run: npm install -g opencode-ai@" + OPENCODE_VERSION); }
     }
   }
+  // 0.3.13 (owner 2026-11-08): the famous AI CLIs come along, so a user who knows nothing about LLMs still has them.
+  st.aiClis = (o.npm && o.aiClis) ? installAiClis(log, process.env, undefined, (prev.aiClis && prev.aiClis.installed) || [])
+    : ((prev.aiClis && (prev.aiClis.installed || []).length) ? prev.aiClis : { skipped: true });  // a skip still owns what an earlier install added
   const dest = binDest(o);
   st.bin = o.bin ? installBin(o) : { skipped: true, dest };
-  if (o.bin && st.bin.degraded) log("bin: WARN -- " + st.bin.note);
-  else if (o.bin && !st.bin.ok) { bad++; log("bin: FAILED -- " + st.bin.note); }
+  // 0.3.13 (owner 2026-11-09: "check that a missing core is handled as a failure"): NO core is a failed part on every
+  // road, an unreachable release host included. The hooks and the lite harness still install, so the risky classes are
+  // refused, but the install exits 1 and the banner says so until a rerun fetches the core.
+  if (o.bin && !st.bin.ok) { bad++; log("bin: FAILED -- no wkappbot core installed: " + st.bin.note); }
   st.harness = o.harness ? installHarness(o) : { skipped: true };
   if (o.harness && !st.harness.ok) { bad++; log("harness: FAILED -- " + st.harness.note); }
   // The plugin entry names the harness the install just chose (a forced web harness wins over a checkout).
   const kih = (st.harness.mode === "web" && st.harness.ok) ? st.harness.dir : kihDir(o);
-  // Global pre-push dispatcher (owner 2026-11-06): the push-owner gate runs in every repo, then the repo's own hooks.
+  // 0.3.13 (owner 2026-11-09): read the Claude settings first, then point every harness hook at the SAME harness the
+  // plugin uses, on both roads (web harness or checkout); the user's own hooks stay; bad JSON is reported, not touched.
+  st.hooks = o.harness ? wireClaudeHooks({ settings: SETTINGS(), kih, pwsh: !!ps, log }) : { skipped: true };
+  // the compressed allow list (lib/allow-compact.js): five harness-own prefixes, never the wide rows learned on the owner's seats
+  st.allows = (o.harness && o.allows) ? addAllows(SETTINGS(), prev.allows || {}, log) : (prev.allows || { skipped: true });
+  // the standard global rules for a fresh machine (lib/starter-md.js): only where the user has no ~/.claude/CLAUDE.md
+  st.starterMd = o.harness ? installStarterMd({ claudeDir: dirname(SETTINGS()), pkgDir: PKG_DIR, prev: prev.starterMd, log }) : { skipped: true };  // Global pre-push dispatcher (owner 2026-11-06): the push-owner gate runs in every repo, then the repo's own hooks.
   // A user's own absolute global core.hooksPath is kept (the script WARNs). Skipped with --no-harness.
   st.pushGate = { skipped: true };
   if (o.harness && kih && existsSync(join(kih, "tools", "wk-global-hooks.sh"))) {
@@ -478,8 +513,9 @@ function uninstall(o) {
     const r = pr.hooksPath ? gitGlobal("core.hooksPath", pr.hooksPath) : gitGlobal("--unset", "core.hooksPath");
     log("hooksPath: " + (cur || "unset") + " -> " + (pr.hooksPath || "unset") + (r.status === 0 ? "" : " (git rc " + r.status + ")"));
   } else log("hooksPath: " + (cur || "unset") + (cur === (pr.hooksPath ?? null) ? " (as before install)" : " (set by you, kept)"));
-  // 2. settings.json: our arms out, yours kept
+  // 2. settings.json: our allow rules and arms out, yours kept
   const sp = SETTINGS();
+  removeAllows(sp, st.allows, log);
   if (existsSync(sp)) {
     try {
       const raw = readFileSync(sp, "utf8");
@@ -513,6 +549,7 @@ function uninstall(o) {
   }
   // 3b. the ~/.local/bin/wkappbot link: removed ONLY when it points at the core this install placed (the core file stays)
   const core = (st.bin && st.bin.dest) || binDest(o);
+  removeStarterMd(st.starterMd, log);
   let linkRemoved = "";
   for (const p of new Set(shimCandidates().concat([join(homedir(), ".local", "bin", "wkappbot")]))) {
     if (!isSymlink(p) || (st.shims || []).includes(p)) continue;
@@ -520,6 +557,16 @@ function uninstall(o) {
     if (tgt && real(tgt) === real(core)) { rmSync(p, { force: true }); linkRemoved = p; log("shim: removed " + p + " (a link to the core this install placed, " + core + ")"); }
     else log("shim: kept " + p + " (not a link to " + core + ")");
   }
+  // 3c. the Windows wkappbot.cmd the bin step wrote is a FILE, not a link, so the loop above never saw it (SDK os-qa
+  // 2026-11-09 win-x64: local-bin kept wkappbot.cmd after uninstall). Removed only while it still calls this core.
+  const cmdShim = st.bin && st.bin.link;
+  if (cmdShim && /\.cmd$/i.test(cmdShim) && existsSync(cmdShim)) {
+    let body = ""; try { body = readFileSync(cmdShim, "utf8"); } catch {}
+    if (body.includes(core)) { rmSync(cmdShim, { force: true }); linkRemoved = cmdShim; log("shim: removed " + cmdShim + " (it called the core this install placed)"); }
+    else log("shim: kept " + cmdShim + " (it no longer calls " + core + ")");
+  }
+  // 3d. the AI CLIs this install added (lib/ai-clis.js), never one the user had before
+  removeAiClis((st.aiClis && st.aiClis.installed) || [], log);
   // 4. the harness dirs we created, the plugin entry and our config folder
   // Windows frees a closed handle late (ENOTEMPTY): lib/rmtree.js retries ~6 s, then a per-entry pass names the blocker; a failure goes on.
   const rmTree = (p, what) => {
@@ -567,6 +614,9 @@ function doctor(o) {
   const st = readState(o);
   const rows = [];
   const add = (name, ok, detail, required, skip) => rows.push({ name, ok, detail, required, skip });
+  // prereq: the tools every part runs on (check only: doctor never installs; a Git off PATH is still found)
+  const pq = ensurePrereqs({ noInstall: true });
+  add("prereq", pq.ok, pq.ok ? Object.entries(pq.found).map(([t, p]) => t + "=" + p).join(" ") : pq.note, true);
   const v = opencodeVersion();
   add("opencode", v === OPENCODE_VERSION, v ? v + (v === OPENCODE_VERSION ? "" : " (pinned " + OPENCODE_VERSION + ")") : "not on PATH", false);
   const pdest = join(cfg, "wkappbot-code", "wisdom-kernel.js");
@@ -576,11 +626,12 @@ function doctor(o) {
   add("config", !!entry, join(cfg, "opencode.json"), true);
   const oc = configRow(join(cfg, "opencode.json"));
   add("opencode-config", oc.ok, oc.detail, false);
+  aiCliRows(add, !!(st.aiClis && st.aiClis.skipped));
   // bin: the core answers --version
   const dest = o.binDest ? resolve(o.binDest) : (st.bin && st.bin.dest) || binDest(o);
   let core = "";
   if (st.bin && st.bin.skipped) add("bin", false, "skipped (--no-bin)", false, true);
-  else if (st.bin && st.bin.degraded && !existsSync(dest)) add("bin", false, dest + " absent -- " + st.bin.note, false);
+  else if (!existsSync(dest)) add("bin", false, dest + " absent -- no wkappbot core" + (st.bin && st.bin.note ? " (" + st.bin.note + ")" : "") + "; rerun: wkappbot-code install", true);
   else {
     const r = spawnSync(dest, ["--version"], { encoding: "utf8", timeout: 60000 });
     core = r.status === 0 ? (r.stdout || "").trim().split("\n")[0] : "";
@@ -595,6 +646,9 @@ function doctor(o) {
   if (st.harness && st.harness.skipped && !hk) add("kih-hook", false, "skipped (--no-harness)", false, true);
   else if (hk && !mode) add("kih-hook", false, k + ": pwsh is missing and the lite harness (tools/wkharness-lite.sh) is not there -- no hook verdict; reinstall the harness", true);
   else add("kih-hook", hk, k ? k + (st.harness && st.harness.mode ? "  (" + st.harness.mode + ")" : "") + (mode ? "  verdict: " + (mode === "full" ? "full pwsh hub (" + ps + ") after lite" : "lite sh harness" + (ps ? " (user install)" : " (no pwsh)")) : "") : "not found", !!(st.harness && st.harness.mode === "web"));
+  // claude-hooks: the Claude Code hooks run the same harness as the plugin (a WARN, never a FAIL: Claude Code is optional).
+  if (st.hooks && st.hooks.skipped) add("claude-hooks", false, "skipped (--no-harness)", false, true);
+  else if (k) { const hr = hooksRow(SETTINGS(), k); add("claude-hooks", hr.ok, hr.detail, false); }
   // skills: the HQ holds on-load and the core prints it
   const hq = (st.skills && st.skills.hq) || hqDir(o, dest);
   if (st.skills && st.skills.skipped) add("skills", false, "skipped (--no-skills)", false, true);
@@ -655,7 +709,7 @@ switch (o.cmd) {
   case "update": process.exit(upd());
   case "config": installPlugin(o, kihDir(o), kihCheckout(o) ? "harness checkout" : "web harness"); process.exit(0);
   default:
-    console.log("usage: wkappbot-code --version | install [--no-npm] [--no-bin] [--no-harness] [--no-skills] [--web-harness] [--dev-seat]\n" +
+    console.log("usage: wkappbot-code --version | install [--no-npm] [--no-ai-clis] [--no-allows] [--no-bin] [--no-harness] [--no-skills] [--web-harness] [--dev-seat]\n" +
       "         [--config-dir DIR] [--kih-dir DIR] [--bin-dest FILE] [--hq-dir DIR] [--update] [--auto-update] | doctor [--config-dir DIR]\n" +
       "       | uninstall [--config-dir DIR] | update [install opts] | config [--yes] [--project] [--set key=value] [--config-dir DIR]");
     process.exit(o.cmd === "help" || o.cmd === "--help" ? 0 : 64);

package/lib/ai-clis.js

@@ -0,0 +1,68 @@
+// ai-clis.js -- the well-known AI coding CLIs that `wkappbot-code install` lays down beside OpenCode (owner 2026-11-08:
+// "install the famous CLIs in one go, so a user who knows nothing about LLMs still gets them"). No key or login is asked:
+// each CLI installs login-free and asks for its own sign-in the first time the user runs it. One `npm install -g` pass for
+// all the missing ones; when that pass fails, each is retried alone so one bad package never blocks the rest. A failure is
+// a WARN (never a failed install part), and doctor prints one WARN-level row per CLI. Skip with --no-ai-clis (or --no-npm).
+import { spawnSync } from "node:child_process";
+
+export const AI_CLIS = [
+  { name: "claude", pkg: "@anthropic-ai/claude-code" },
+  { name: "codex", pkg: "@openai/codex" },
+  { name: "gemini", pkg: "@google/gemini-cli" },
+  { name: "qwen", pkg: "@qwen-code/qwen-code" },
+];
+
+const IS_WIN = process.platform === "win32";
+
+// The first line a CLI prints for --version, or "" when it is not on PATH or does not answer.
+export function cliVersion(name, env = process.env) {
+  const r = spawnSync(name, ["--version"], { encoding: "utf8", timeout: 30000, shell: IS_WIN, env });
+  if (r.status !== 0) return "";
+  const line = String(r.stdout || "").trim().split("\n")[0] || "";
+  const m = line.match(/\d+\.\d+\.\d+[\w.-]*/);
+  return m ? m[0] : line.slice(0, 40);
+}
+
+function npmGlobal(pkgs, env) {
+  const r = spawnSync("npm", ["install", "-g", ...pkgs, "--no-audit", "--no-fund"], { stdio: "inherit", shell: IS_WIN, env });
+  return r.status === 0;
+}
+
+// Installs every CLI of AI_CLIS that is not on PATH yet. Returns { installed: [...], present: [...], failed: [...] }.
+// prevInstalled: the names an earlier install added; a rerun keeps owning them, so uninstall still takes them back.
+export function installAiClis(log, env = process.env, list = AI_CLIS, prevInstalled = []) {
+  const present = [], missing = [];
+  for (const c of list) (cliVersion(c.name, env) ? present : missing).push(c);
+  if (present.length) log("ai-clis: already installed: " + present.map((c) => c.name).join(", "));
+  const res = { installed: present.map((c) => c.name).filter((n) => prevInstalled.includes(n)), present: present.map((c) => c.name), failed: [] };
+  if (!missing.length) return res;
+  log("ai-clis: npm install -g " + missing.map((c) => c.pkg).join(" "));
+  if (npmGlobal(missing.map((c) => c.pkg), env)) res.installed.push(...missing.map((c) => c.name));
+  else {
+    log("ai-clis: the one-pass install failed, retrying each CLI alone");
+    for (const c of missing) (npmGlobal([c.pkg], env) ? res.installed : res.failed).push(c.name);
+  }
+  for (const n of res.failed) log("ai-clis: WARN " + n + " not installed -- run: npm install -g " + list.find((c) => c.name === n).pkg);
+  return res;
+}
+
+// uninstall takes back what install added (SDK os-qa 2026-11-09, run 42552244938: the npm prefix bin kept claude, codex,
+// gemini and qwen after uninstall on every leg). Only the names install recorded go; a CLI the user had stays. A failed
+// npm uninstall is a WARN with the command to finish it by hand.
+export function removeAiClis(names, log, env = process.env, list = AI_CLIS) {
+  const pkgs = list.filter((c) => (names || []).includes(c.name)).map((c) => c.pkg);
+  if (!pkgs.length) return true;
+  log("ai-clis: npm uninstall -g " + pkgs.join(" "));
+  const r = spawnSync("npm", ["uninstall", "-g", ...pkgs, "--no-audit", "--no-fund"], { stdio: "inherit", shell: IS_WIN, env });
+  if (r.status !== 0) log("ai-clis: WARN npm uninstall rc " + r.status + " -- run: npm uninstall -g " + pkgs.join(" "));
+  return r.status === 0;
+}
+
+// doctor rows: add(name, ok, detail, required, skip). Never required: a missing CLI is a WARN.
+export function aiCliRows(add, skipped, env = process.env, list = AI_CLIS) {
+  for (const c of list) {
+    if (skipped) { add("ai-cli " + c.name, false, "skipped (--no-ai-clis)", false, true); continue; }
+    const v = cliVersion(c.name, env);
+    add("ai-cli " + c.name, !!v, v ? v + " (" + c.pkg + ")" : "not on PATH -- npm install -g " + c.pkg, false);
+  }
+}

package/lib/allow-compact.js

@@ -0,0 +1,55 @@
+// lib/allow-compact.js -- the compressed allow list (owner 2026-11-09: "simplify the patterns, keep 3 to 5 keywords,
+// make a compressed list"). The auto-mode classifier refused harmless harness-own commands on the owner's seats; the
+// rows learned from those refusals (tools/wkharness-claude-allows-learned.txt: git -C *, python3 -I *, send_message ...)
+// are far too wide for a stranger's machine. A fresh install gets ONLY these five read-or-own-store prefixes. Every call
+// still meets the harness PreToolUse hook first, and a hook refusal beats an allow rule, so an entry here skips the
+// permission prompt, never the harness. Uninstall removes exactly the entries this install added.
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { readSettings } from "./hook-wire.js";
+
+export const COMPACT_ALLOWS = [
+  "Bash(wkskill *)",               // skill read / search / like (the user's own store)
+  "Bash(wkappbot skill *)",        // the same through the core
+  "Bash(wkappbot file read *)",    // read-only file view
+  "Bash(wk-verify)",               // live hook check, no arguments
+  "Bash(wkappbot-code doctor)",    // read-only health table
+];
+
+// prev: the state recorded by the last install ({ added, madeAllow, madePerms }); a reinstall keeps owning what it added.
+export function addAllows(path, prev = {}, log = () => {}) {
+  const r = readSettings(path);
+  if (!r.ok) { log("allows: WARN " + path + " is not plain JSON (" + r.err + "); no allow rule added"); return { ok: false, added: prev.added || [] }; }
+  const d = r.json || {};
+  const madePerms = !!prev.madePerms || !(d.permissions && typeof d.permissions === "object" && !Array.isArray(d.permissions));
+  if (madePerms && !(d.permissions && typeof d.permissions === "object" && !Array.isArray(d.permissions))) d.permissions = {};
+  const madeAllow = !!prev.madeAllow || !Array.isArray(d.permissions.allow);
+  if (!Array.isArray(d.permissions.allow)) d.permissions.allow = [];
+  const allow = d.permissions.allow;
+  const kept = (prev.added || []).filter((e) => allow.includes(e));
+  const fresh = COMPACT_ALLOWS.filter((e) => !allow.includes(e));
+  allow.push(...fresh);
+  if (fresh.length || !existsSync(path)) { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, JSON.stringify(d, null, 2) + "\n"); }
+  const added = [...new Set([...kept, ...fresh])];
+  log("allows: " + (fresh.length ? "added " + fresh.length : "kept") + " of the " + COMPACT_ALLOWS.length + " harness allow rules in " + path + " (the harness hook still checks every call)");
+  return { ok: true, added, madeAllow, madePerms };
+}
+
+// Removes only the entries addAllows recorded; drops an allow list or permissions object only when the install made it
+// and it is empty now. Returns the count removed; bad JSON is left untouched.
+export function removeAllows(path, st, log = () => {}) {
+  if (!st || !(st.added || []).length || !existsSync(path)) return 0;
+  const r = readSettings(path);
+  if (!r.ok) { log("allows: " + path + " is not plain JSON, left untouched (" + r.err + ")"); return 0; }
+  const d = r.json || {}, p = d.permissions;
+  if (!p || !Array.isArray(p.allow)) return 0;
+  const before = p.allow.length;
+  p.allow = p.allow.filter((e) => !st.added.includes(e));
+  const n = before - p.allow.length;
+  if (!n) return 0;
+  if (st.madeAllow && !p.allow.length) delete p.allow;
+  if (st.madePerms && !Object.keys(p).length) delete d.permissions;
+  writeFileSync(path, JSON.stringify(d, null, 2) + "\n");
+  log("allows: removed " + n + " harness allow rule" + (n === 1 ? "" : "s") + " from " + path);
+  return n;
+}

package/lib/hook-wire.js

@@ -0,0 +1,173 @@
+// hook-wire.js -- read the user's Claude settings first, then bring the harness hooks to the harness this install chose
+// (owner 2026-11-09: "analyze the customer environment, overwrite the needed settings and hooks with the latest, and ask
+// for a change when needed"; "it must work without the harness repo, pick the road by whether the repo is there, with
+// the most consistency"; "the web install failed where python is missing"). Install-mode QA before this module, 23/26:
+// a checkout install wired NO Claude hooks, a switch from the web harness to a checkout left the Claude hooks on the old
+// harness while the OpenCode plugin moved, a settings.json that is not plain JSON was skipped without a word, and with no
+// python3 the web harness install stopped at "needs python3 on PATH".
+// wireSettings is the node port of tools/wkharness-lite.sh --wire (python3, kept for the WebVM image build): every
+// harness hook is repointed at <dir>/tools/wkharness-lite.sh, an unroutable harness hook is dropped, a user's own hook
+// stays verbatim, and every lite arm is present once. The web installer calls it through the CLI form below when it has
+// node but no python3:   node hook-wire.js wire SETTINGS LITE
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// The same harness-hook pattern as tools/wkharness-lite.sh --wire HARNESS_HOOK. ANCHORED (2026-11-09 review, proven on
+// fixtures): the loose form also took a user's own pwsh lint.ps1, bash ~/bin/session-start.sh and my-wkharness-notes.sh
+// for harness hooks and deleted or rewrote them. Now a harness hook is a wkharness*.sh/.ps1/.cmd file name standing at a
+// path or word start, a file under a .wk-harness folder, the kih .claude/hooks scripts, or the two named sync hooks.
+const HARNESS_HOOK = /(^|[\s"'\\/])wkharness(-[\w-]+)?\.(sh|ps1|cmd)\b|\.wk-harness[\\/]|[\\/]\.claude[\\/]hooks[\\/](user-prompt-submit|session-start)\.sh\b|(^|[\s"'\\/])(wk-global-md-sync|wk-session-pull|wkappbot-shim)(\.[a-z0-9]+)?\b/;
+const ARMS = [["PreToolUse", "pre"], ["Stop", "stop"], ["UserPromptSubmit", "prompt"], ["SessionStart", "session"]];
+const fwd = (p) => String(p || "").replace(/\\/g, "/").replace(/\/+$/, "");
+
+export function readSettings(path) {
+  if (!existsSync(path)) return { ok: true, json: null };
+  // a UTF-8 BOM (Windows editors write one) is valid JSON text; strip it (2026-11-09 review: it read as "not JSON")
+  const text = readFileSync(path, "utf8").replace(/^/, "");
+  if (!text.trim()) return { ok: true, json: null };
+  try { return { ok: true, json: JSON.parse(text) }; }
+  catch (e) { return { ok: false, err: String(e.message).split("\n")[0] }; }
+}
+
+// An event's groups as an array: a single group object (hand-written settings) counts as one group, anything else as none
+// (2026-11-09 review: a non-array value threw "(groups || []) is not iterable" and crashed the whole install).
+const asGroups = (v) => (Array.isArray(v) ? v : v && typeof v === "object" ? [v] : []);
+const asHooks = (g) => (g && Array.isArray(g.hooks) ? g.hooks : []);
+
+// Every harness hook command, by event.
+export function harnessHooks(json) {
+  const out = [];
+  const hk = json && typeof json.hooks === "object" && json.hooks ? json.hooks : {};
+  for (const [ev, groups] of Object.entries(hk))
+    for (const g of asGroups(groups)) for (const h of asHooks(g))
+      if (h && typeof h.command === "string" && HARNESS_HOOK.test(h.command)) out.push({ ev, command: h.command });
+  return out;
+}
+
+// --wire route(): a harness hook command -> the lite command for the same arm, or null (not routable).
+function route(cmd, lite) {
+  let m = /wkharness-lite\.sh"?\s+([a-z]+)/.exec(cmd);
+  if (m) return '"' + lite + '" ' + m[1];
+  m = /wkharness-run\.sh"?\s+([a-z-]+)/.exec(cmd);
+  if (m) return '"' + lite + '" ' + (m[1].startsWith("stop") ? "stop" : m[1]);
+  if (cmd.includes("user-prompt-submit.sh")) return '"' + lite + '" prompt';
+  if (cmd.includes("session-start.sh")) return '"' + lite + '" session';
+  return null;
+}
+
+// The node port of --wire, plus the create step of the web installer. Throws on a settings file that is not JSON.
+export function wireSettings(path, lite) {
+  const r = readSettings(path);
+  if (!r.ok) throw new Error(path + " is not plain JSON (" + r.err + ")");
+  const d = r.json || {};
+  const out = {};
+  for (const [ev, groups] of Object.entries(d.hooks && typeof d.hooks === "object" ? d.hooks : {})) {
+    const keep = [];
+    for (const g of asGroups(groups)) {
+      // dedupe INSIDE a group only (2026-11-09 review): a per-event set emptied the second matcher group (Edit|Write)
+      // when it held the same harness command as the first (Bash), so PreToolUse stopped firing for edits
+      const seen = new Set(), hs = [];
+      for (const h of asHooks(g)) {
+        const cmd = String((h && h.command) || "");
+        const c = HARNESS_HOOK.test(cmd) ? route(cmd, lite) : null;  // only a harness hook is ever rewritten
+        if (c && !seen.has(c)) { seen.add(c); hs.push({ type: "command", command: c, timeout: 10 }); }
+        else if (!c && !HARNESS_HOOK.test(cmd)) hs.push(h);  // a user's own hook stays verbatim
+      }
+      if (hs.length) keep.push({ ...g, hooks: hs });
+    }
+    if (keep.length) out[ev] = keep;
+  }
+  for (const [ev, arm] of ARMS) {
+    const c = '"' + lite + '" ' + arm;
+    if (!(out[ev] || []).some((g) => (g.hooks || []).some((h) => h.command === c)))
+      (out[ev] = out[ev] || []).push({ hooks: [{ type: "command", command: c, timeout: 10 }] });
+  }
+  d.hooks = out;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(d, null, 2) + "\n");
+  return Object.keys(out).sort();
+}
+
+// state: unreadable | none | ours (every harness hook points into kih and all four arms are there) | partial | other
+export function analyzeHooks(path, kih) {
+  const r = readSettings(path);
+  if (!r.ok) return { state: "unreadable", err: r.err, hooks: [] };
+  const hooks = harnessHooks(r.json);
+  if (!hooks.length) return { state: "none", hooks };
+  const k = fwd(kih);
+  const mine = hooks.filter((h) => k && fwd(h.command).includes(k + "/"));
+  if (mine.length === hooks.length) {
+    const evs = new Set(hooks.map((h) => h.ev));
+    return { state: ARMS.every(([e]) => evs.has(e)) ? "ours" : "partial", hooks };
+  }
+  return { state: "other", hooks, elsewhere: [...new Set(hooks.filter((h) => !mine.includes(h)).map((h) => h.command))] };
+}
+
+// o: { settings, kih, pwsh, log }. Never throws: a surprise in a hand-written settings file becomes a WARN line and the
+// rest of the install goes on (2026-11-09 review: a non-array hooks value crashed the whole install).
+export function wireClaudeHooks(o) {
+  try { return wireClaudeHooksInner(o); }
+  catch (e) { (o.log || (() => {}))("hooks: WARN could not read the hooks in " + o.settings + " (" + e.message + "); left untouched -- please check it, then run: wkappbot-code install"); return { before: "error", after: "error", changed: false }; }
+}
+function wireClaudeHooksInner(o) {
+  const log = o.log || (() => {});
+  const before = analyzeHooks(o.settings, o.kih);
+  const res = { before: before.state, after: before.state, changed: false };
+  if (!o.kih) { log("hooks: no harness was installed, so " + o.settings + " is left as it is"); return res; }
+  if (before.state === "unreadable") {
+    log("hooks: WARN " + o.settings + " is not plain JSON (" + before.err + "); left untouched -- please fix it, then run: wkappbot-code install");
+    return res;
+  }
+  if (before.state === "ours") { log("hooks: " + o.settings + " already runs every harness hook from " + o.kih); return res; }
+  // A FULL harness hook (wkharness-run.sh, the pwsh hub of a dev seat) is never rewritten into the lite one where pwsh
+  // runs: the rewrite would downgrade the owner's own seats. Leave it and say what to do.
+  const full = before.hooks.find((h) => /wkharness-run\.sh/.test(h.command));
+  if (o.pwsh && full) {
+    log("hooks: WARN your Claude hooks run the full harness (" + full.command + ", state '" + before.state + "'); left as they are -- if they should run " + o.kih + ", rewire them from that checkout's own installer");
+    return res;
+  }
+  const lite = join(o.kih, "tools", "wkharness-lite.sh");
+  if (!existsSync(lite)) { log("hooks: WARN " + lite + " is missing, so the Claude hooks were not wired"); return res; }
+  try { wireSettings(o.settings, lite); }
+  catch (e) { log("hooks: WARN wiring " + o.settings + " failed (" + e.message + ")"); return res; }
+  ensureRules(o.kih, log);
+  const after = analyzeHooks(o.settings, o.kih);
+  res.after = after.state; res.changed = true;
+  log("hooks: " + o.settings + " was '" + before.state + "'" + (before.elsewhere ? " (pointing at " + before.elsewhere[0] + ")" : "") +
+    ", now '" + after.state + "'; your own hooks were kept");
+  return res;
+}
+
+// The lite study lock reads <kih>/.tmp/hook-lite/rules.tsv. A web package ships it as tools/wkharness-lite-rules.tsv
+// (built by prepack); a checkout builds it with python3 through the lite --wire; with neither, say what is missing.
+export function ensureRules(kih, log = () => {}) {
+  const want = join(kih, ".tmp", "hook-lite", "rules.tsv");
+  if (existsSync(want)) return "present";
+  const shipped = join(kih, "tools", "wkharness-lite-rules.tsv");
+  if (existsSync(shipped)) { mkdirSync(dirname(want), { recursive: true }); writeFileSync(want, readFileSync(shipped)); return "copied"; }
+  const py = spawnSync("sh", ["-c", "command -v python3"], { encoding: "utf8" });
+  if (py.status === 0) {
+    const r = spawnSync("sh", [join(kih, "tools", "wkharness-lite.sh").replace(/\\/g, "/"), "--wire"], { encoding: "utf8" });
+    if (r.status === 0 && existsSync(want)) return "built";
+  }
+  log("hooks: WARN the study lock has no rule table (" + want + "): install python3, then run: wkappbot-code install");
+  return "missing";
+}
+
+// doctor row: the Claude hooks and the OpenCode plugin must run the same harness.
+export function hooksRow(settings, kih) {
+  let a;
+  try { a = analyzeHooks(settings, kih); } catch (e) { return { ok: false, detail: settings + " could not be read (" + e.message + ")" }; }
+  if (a.state === "ours") return { ok: true, detail: settings + " runs every harness hook from " + kih };
+  if (a.state === "unreadable") return { ok: false, detail: settings + " is not plain JSON (" + a.err + ")" };
+  if (a.state === "none") return { ok: false, detail: "no harness hook in " + settings + " -- run: wkappbot-code install" };
+  return { ok: false, detail: settings + " is '" + a.state + "'" + (a.elsewhere ? ", pointing at " + a.elsewhere[0] : "") + " while the plugin uses " + kih + " -- run: wkappbot-code install" };
+}
+
+// CLI form for the web installer on a machine with node and no python3: node hook-wire.js wire SETTINGS LITE
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === "wire") {
+  try { console.log("[wk-harness] wired " + process.argv[3] + " with node: " + wireSettings(process.argv[3], process.argv[4]).join(", ")); }
+  catch (e) { console.error("[wk-harness] " + e.message); process.exit(1); }
+}

package/lib/prereq.js

@@ -0,0 +1,57 @@
+// prereq.js -- the tools every install part runs on: bash and sh (the harness, the core acquire), curl and tar (the
+// downloads), git (hooks, skills). Owner 2026-11-09: "Git Bash is a required tool too; check that it is installed along".
+// On Windows they all come from Git for Windows (Git Bash): (1) a Git install that is not on PATH is found at its usual
+// folders and put on this process's PATH; (2) no Git at all and winget present: `winget install --id Git.Git` (silent),
+// then found as in (1); (3) neither: a FAILED part with the one line that says what to install. Every probe is
+// injectable so the selftest drives all three roads on any OS.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+export const TOOLS = ["bash", "sh", "curl", "tar", "git"];
+const GIT_DIRS = (env) => [env.ProgramFiles && join(env.ProgramFiles, "Git"), env["ProgramFiles(x86)"] && join(env["ProgramFiles(x86)"], "Git"),
+  env.LOCALAPPDATA && join(env.LOCALAPPDATA, "Programs", "Git"), "C:\\Program Files\\Git"].filter(Boolean);
+
+function realWhich(cmd, env) {
+  const win = process.platform === "win32";
+  const r = spawnSync(win ? "where" : "sh", win ? [cmd] : ["-c", "command -v " + cmd], { encoding: "utf8", env });
+  return r.status === 0 ? String(r.stdout || "").trim().split(/\r?\n/)[0] : "";
+}
+const realRun = (cmd, args, env) => spawnSync(cmd, args, { stdio: "inherit", env, shell: process.platform === "win32" }).status;
+
+// o: { platform, env (mutated: PATH gains the Git dirs), which, exists, run, log, noInstall (doctor: check only) }
+// -> { ok, missing: [...], found: {tool: path}, via: "path"|"git-dir"|"winget"|"", note }
+export function ensurePrereqs(o = {}) {
+  const platform = o.platform || process.platform, env = o.env || process.env, log = o.log || (() => {});
+  const which = o.which || realWhich, exists = o.exists || existsSync, run = o.run || realRun;
+  const probe = () => { const found = {}, missing = []; for (const t of TOOLS) { const p = which(t, env); if (p) found[t] = p; else missing.push(t); } return { found, missing }; };
+  let p = probe(), via = "path";
+  if (!p.missing.length) return { ok: true, missing: [], found: p.found, via, note: "" };
+  if (platform !== "win32") {
+    const note = "missing " + p.missing.join(", ") + " -- install them with your package manager (e.g. apt install " + p.missing.join(" ") + "), then run: wkappbot-code install";
+    log("prereq: FAILED -- " + note);
+    return { ok: false, missing: p.missing, found: p.found, via: "", note };
+  }
+  const addGit = () => {
+    for (const d of GIT_DIRS(env)) {
+      if (!exists(join(d, "bin", "bash.exe"))) continue;
+      const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH") || "PATH";
+      env[key] = [join(d, "bin"), join(d, "usr", "bin"), join(d, "cmd")].join(delimiter) + delimiter + (env[key] || "");
+      return d;
+    }
+    return "";
+  };
+  let dir = addGit();
+  if (dir) { p = probe(); via = "git-dir"; log("prereq: Git Bash found at " + dir + " (not on PATH) -- used for this install; add " + join(dir, "bin") + " to your PATH"); }
+  if (p.missing.length && !o.noInstall && which("winget", env)) {
+    log("prereq: Git for Windows (Git Bash) is missing -- installing it with winget");
+    const rc = run("winget", ["install", "--id", "Git.Git", "-e", "--source", "winget", "--silent", "--accept-package-agreements", "--accept-source-agreements"], env);
+    dir = addGit();
+    if (dir) { p = probe(); via = "winget"; log("prereq: winget installed Git for Windows at " + dir + " (rc " + rc + ")"); }
+    else log("prereq: winget rc " + rc + " but no Git Bash was found afterwards");
+  }
+  if (!p.missing.length) return { ok: true, missing: [], found: p.found, via, note: "" };
+  const note = "missing " + p.missing.join(", ") + " -- install Git for Windows (it brings Git Bash with bash, sh, curl and tar): https://git-scm.com/download/win , then run: wkappbot-code install";
+  log("prereq: FAILED -- " + note);
+  return { ok: false, missing: p.missing, found: p.found, via: "", note };
+}

package/lib/setup-run.js

@@ -102,18 +102,21 @@ export function bannerFor({ done, running, seen, logPath, now = Date.now() }) {
     if (age >= 0 && age < RUNNING_STALE_MS) return { line: "[wkappbot-code] setup still running (log: " + logPath + ") -- opening OpenCode anyway", mark: false };
     return { line: "[wkappbot-code] setup did not finish (worker started " + (running.at || "?") + ", no result); log: " + logPath + " -- rerun: wkappbot-code install", mark: false };
   }
-  if (!done || (seen && seen === done.at)) return { line: "", mark: false };
+  if (!done) return { line: "", mark: false };
   const d = done.doctor || {}, s = done.selftest || {};
   const total = (d.pass || 0) + (d.warn || 0) + (d.fail || 0);
   const tail = "doctor " + (d.pass || 0) + "/" + total + (d.warn ? " (" + d.warn + " warn)" : "") + ", selftest " + (s.n || 0) + "/" + (s.m || 0);
   const installRc = done.installRc ?? done.rc;
-  if (installRc === 0 && !d.fail && s.n === s.m && s.m > 0) return { line: "[wkappbot-code] setup ok, " + tail, mark: true };
+  // only a GOOD result goes quiet once seen; a failed one is checked below and always printed
+  if (installRc === 0 && !d.fail && s.n === s.m && s.m > 0) return (seen && seen === done.at) ? { line: "", mark: false } : { line: "[wkappbot-code] setup ok, " + tail, mark: true };
   const bad = [];
   if (installRc !== 0) bad.push("install rc " + installRc);
   for (const f of done.doctorFailed || []) bad.push("doctor " + f + " FAIL");
   for (const i of done.items || []) bad.push("selftest " + i);
   if (!bad.length) bad.push(d.fail ? "doctor " + d.fail + " FAIL" : "selftest " + (s.n || 0) + "/" + (s.m || 0));
-  return { line: "[wkappbot-code] setup needs attention: " + bad.slice(0, 3).join("; ") + " (" + tail + "); log: " + logPath, mark: true };
+  // A failure is NEVER marked seen (owner 2026-11-09: a setup that failed for want of python3 was not noticed): it is
+  // printed on every run until a rerun of install gives a good result.
+  return { line: "[wkappbot-code] SETUP FAILED: " + bad.slice(0, 3).join("; ") + " (" + tail + "); log: " + logPath + " -- fix it, then run: wkappbot-code install", mark: false };
 }
 export function printBanner({ home = homedir(), out = console.log, now = Date.now() } = {}) {
   const f = files(home);

package/lib/starter-md.js

@@ -0,0 +1,46 @@
+// starter-md.js -- a standard global ~/.claude/CLAUDE.md for a new machine (owner 2026-11-09: "install CLAUDE.md as an
+// initial standard copy too, so a raw untrained model is guarded on a new machine"). The starter
+// (templates/global-CLAUDE.md) holds only user-safe working rules: reply language, skills first, run-not-guess, the
+// risk classes the harness refuses, no secrets, no outward act without the user's go. Written only where the user has
+// NO global CLAUDE.md; refreshed only while it still equals what this install wrote (sha256 kept in install-state.json);
+// a file the user changed or wrote is never touched. Uninstall removes it only when it is still unchanged.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+
+// o: { claudeDir, pkgDir, prev (install-state starterMd), log } -> { path, sha, action }
+export function installStarterMd(o) {
+  const log = o.log || (() => {});
+  const path = join(o.claudeDir, "CLAUDE.md");
+  const tplPath = join(o.pkgDir, "templates", "global-CLAUDE.md");
+  if (!existsSync(tplPath)) { log("claude-md: WARN the starter " + tplPath + " is missing from this package"); return { path, action: "missing-template" }; }
+  const tpl = readFileSync(tplPath, "utf8");
+  if (!existsSync(path)) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, tpl);
+    log("claude-md: wrote the starter global rules to " + path + " (you had none; edit it freely)");
+    return { path, sha: sha(tpl), action: "written" };
+  }
+  const cur = readFileSync(path, "utf8");
+  // identical text is ours only when this install wrote it before (2026-11-09 review: a user's own copy that happened to
+  // equal the starter was recorded and then deleted by uninstall)
+  if (cur === tpl) return (o.prev && o.prev.sha === sha(cur)) ? { path, sha: sha(tpl), action: "current" } : { path, action: "kept" };
+  if (o.prev && o.prev.sha && o.prev.sha === sha(cur)) {
+    writeFileSync(path, tpl);
+    log("claude-md: refreshed the starter global rules in " + path + " (unchanged since the last install)");
+    return { path, sha: sha(tpl), action: "refreshed" };
+  }
+  log("claude-md: kept your " + path + " (yours); the starter is at " + tplPath + " if you want to compare");
+  return { path, action: "kept" };
+}
+
+// uninstall: remove the starter only when it is still exactly what this install wrote.
+export function removeStarterMd(rec, log = () => {}) {
+  if (!rec || !rec.path || !rec.sha || !existsSync(rec.path)) return false;
+  if (sha(readFileSync(rec.path, "utf8")) !== rec.sha) { log("claude-md: kept " + rec.path + " (you changed it)"); return false; }
+  rmSync(rec.path, { force: true });
+  log("claude-md: removed the starter " + rec.path + " (unchanged since install)");
+  return true;
+}

package/lib/wk-bin-acquire.sh

@@ -7,7 +7,8 @@
 #     Source 1 (unless --offline): SDK latest release asset wkappbot-PLATFORM, accepted only when its
 #     sha256 matches its SHA256SUMS line. Source 2: REPO/bin/PLATFORM/wkappbot, accepted only when
 #     its sha256 matches the MANIFEST.md row. Windows: PATH is a directory that receives
-#     wkappbot.exe and wkappbot-core.exe (xz -dc of bin/win-x64/wkappbot-core.exe.xz), from bin/ only.
+#     wkappbot.exe and wkappbot-core.exe (xz -dc of wkappbot-core.exe.xz): first the SDK release pair, each file
+#     verified by its SHA256SUMS line, else repo bin/win-x64 (2026-11-09; bin/ only before, so no checkout = no core).
 #     Copies, never links; writes via a .new temp then mv; "up to date" when the sha already matches.
 #   wk-bin-acquire.sh publish SRC [--platform P] [--dry-run]
 #     Stores SRC in REPO/bin/P/ (a Windows core .exe as wkappbot-core.exe.xz, xz -9e -T0), rewrites
@@ -103,10 +104,12 @@ default_dest_win() {
 # sdk_fetch PLAT DIR -- prints the verified asset path; else prints nothing and returns
 # 3 when a download failed (host unreachable, no such asset) or 4 when the asset is UNVERIFIED
 # (no SHA256SUMS line for it, or a sha256 mismatch). Only 3 may degrade an install to hooks-only.
-sdk_fetch() {
-  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "sdk_fetch" || true
-  local plat="$1" dir="$2" asset base want got
-  asset="wkappbot-$plat"
+sdk_fetch() { sdk_fetch_asset "wkappbot-$1" "$2"; }
+# sdk_fetch_asset ASSET DIR -- the same verified download for any release asset name (win-x64 takes two:
+# wkappbot.exe and wkappbot-core.exe.xz, 2026-11-09: a Windows user with no kih checkout got NO core at all).
+sdk_fetch_asset() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "sdk_fetch_asset" || true
+  local asset="$1" dir="$2" base want got
   base="${WK_BIN_BASE:-https://github.com/kiexpert/wkappbot-sdk/releases/latest/download}"
   curl -fsSL -m "${WK_BIN_TIMEOUT:-120}" "$base/$asset" -o "$dir/$asset" || return 3
   curl -fsSL -m "${WK_BIN_TIMEOUT:-120}" "$base/SHA256SUMS" -o "$dir/SHA256SUMS" || return 3
@@ -175,15 +178,31 @@ acquire_unix() {
 
 acquire_win() {
   command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "acquire_win" || true
-  local dest="$1" exe xzsrc core
+  local dest="$1" offline="${2:-0}" exe="" xzsrc="" core frc=3 xrc=3 label
   [ -n "$dest" ] || dest="$(default_dest_win)"
-  note "win-x64 installs from bin/ only: the two-file set has no single SDK asset"
-  exe="$(repo_file "win-x64/wkappbot.exe")"
-  xzsrc="$(repo_file "win-x64/wkappbot-core.exe.xz")"
+  command -v xz >/dev/null 2>&1 || die "win-x64 needs xz on PATH to unpack wkappbot-core.exe.xz (Git for Windows ships it in usr/bin)"
+  # Source 1: the SDK release pair, each file verified by its own SHA256SUMS line. Source 2: repo bin/win-x64.
+  if [ "$offline" = 0 ]; then
+    exe="$(sdk_fetch_asset wkappbot.exe "$WK_TMP")" && frc=0 || frc=$?
+    [ "$frc" = 0 ] && { xzsrc="$(sdk_fetch_asset wkappbot-core.exe.xz "$WK_TMP")" && xrc=0 || xrc=$?; }
+  fi
+  if [ "$frc" = 0 ] && [ "$xrc" = 0 ]; then
+    label="SDK release"
+  else
+    [ "$frc" = 4 ] || [ "$xrc" = 4 ] && [ -z "$REPO" ] && die "the SDK release asset for win-x64 is UNVERIFIED (no SHA256SUMS line or a sha256 mismatch); nothing installed"
+    if [ "$offline" = 0 ]; then note "SDK assets unavailable or unverified, using repo bin/win-x64"; fi
+    if [ -z "$REPO" ]; then
+      note "UNREACHABLE: wkappbot.exe and wkappbot-core.exe.xz could not be downloaded from ${WK_BIN_BASE:-github.com/kiexpert/wkappbot-sdk releases} and no kih checkout holds bin/win-x64; nothing installed"
+      exit 3
+    fi
+    exe="$(repo_file "win-x64/wkappbot.exe")"
+    xzsrc="$(repo_file "win-x64/wkappbot-core.exe.xz")"
+    label="repo bin/win-x64"
+  fi
   core="$WK_TMP/wkappbot-core.exe"
-  xz -dc "$xzsrc" > "$core"
-  install_file "$exe" "$dest/wkappbot.exe" "repo bin/win-x64/wkappbot.exe"
-  install_file "$core" "$dest/wkappbot-core.exe" "repo bin/win-x64/wkappbot-core.exe.xz"
+  xz -dc "$xzsrc" > "$core" || die "xz could not unpack $xzsrc"
+  install_file "$exe" "$dest/wkappbot.exe" "$label wkappbot.exe"
+  install_file "$core" "$dest/wkappbot-core.exe" "$label wkappbot-core.exe.xz"
 }
 
 acquire() {
@@ -199,7 +218,7 @@ acquire() {
   done
   plat="$(platform_detect)"
   if [ "$plat" = win-x64 ]; then
-    acquire_win "$dest"
+    acquire_win "$dest" "$offline"
   else
     acquire_unix "$dest" "$plat" "$offline"
   fi

package/lib/wk-hook.js

@@ -163,7 +163,11 @@ export function refusalReason(r) {
 // The SAME classes tools/wkharness-lite.sh refuses by itself (wk_lite_risk there). With NO verdict from the harness,
 // a call in one of these classes is REFUSED instead of allowed: a public package must never let rm -rf HOME through
 // because pwsh happened to be missing. Returns the class label, or "".
-const HOME_T = /^(~|\$HOME|\$\{HOME\}|\/root|\/home\/[^/]+|\/Users\/[^/]+)\/?(\*|\.\*)?$/;
+// 0.3.13 strict path QA (owner 2026-11-09): a Windows home also arrives as C:\Users\x, C:/Users/x or MSYS /c/Users/x,
+// and a drive root as C: -- the same forms tools/wkharness-lite.sh rk_home refuses (selftest-paths.mjs pins both).
+const HOME_T = /^(~|\$HOME|\$\{HOME\}|\/root|\/home\/[^/\\]+|\/Users\/[^/\\]+|[A-Za-z]:[\\/]+Users[\\/]+[^/\\]+|\/[A-Za-z]\/Users\/[^/\\]+|[A-Za-z]:)[\\/]*(\*|\.\*)?$/i;
+// A .git path segment with either separator, in any letter case (C:\r\.GIT\config on a case-blind disk).
+const GIT_SEG = /(^|[\\/])\.git([\\/]|$)/i;
 // The shell line as the risk floor reads it. A heredoc body (after <<'TAG', <<TAG or <<-TAG, up to the line TAG) is
 // dropped, and a quoted string is ONE word with its quotes removed, so its text is never read as a git flag or a path.
 // Words handed to a shell (sh/bash -c, eval) are also returned in seg.inner and are checked again as a command line.
@@ -258,16 +262,16 @@ export function riskClass(tool, input, cwd) {
           const proj = cwd ? String(cwd).replace(/\/+$/, "") : "";
           if (tg.some((x) => HOME_T.test(x) || x === "/" || x === "/*")) return "rm -r of HOME or /";
           if (tg.some((x) => [".", "./", "./*", "*", "..", "../"].includes(x) || (proj && x.replace(/\/+$/, "") === proj))) return "rm -r of the project source";
-          if (tg.some((x) => /(^|\/)\.git(\/|$)/.test(x))) return "write under .git";
+          if (tg.some((x) => GIT_SEG.test(x))) return "write under .git";
         }
       }
-      if (w.some((x) => /(^|\/)\.git(\/|$)/.test(x)) && (seg.redirect || /^(rm|mv|cp|tee|truncate|dd|ln|chmod|sed)$/.test(w[0] || ""))) return "write under .git";
+      if (w.some((x) => GIT_SEG.test(x)) && (seg.redirect || /^(rm|mv|cp|tee|truncate|dd|ln|chmod|sed)$/.test(w[0] || ""))) return "write under .git";
     }
     return "";
   }
   if (["Edit", "Write", "MultiEdit", "NotebookEdit"].includes(t)) {
     const f = String(i.file_path || i.notebook_path || "");
-    if (/(^|[\\/])\.git[\\/]/.test(f)) return "write under .git";
+    if (/(^|[\\/])\.git[\\/]/i.test(f)) return "write under .git";
   }
   return "";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wkappbot-code",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "wkappbot-code -- Wisdom Kernel: the pinned OpenCode bridge plus the reflex harness plugin, the wkappbot core, the web harness and the latest public skills in one install",
   "type": "module",
   "scripts": {
@@ -16,6 +16,7 @@
     "lib/*.js",
     "lib/*.sh",
     "plugin/*.js",
+    "templates/*",
     "opencode.json",
     "install.sh",
     "README.md",

package/templates/global-CLAUDE.md

@@ -0,0 +1,20 @@
+# Global rules for every session (installed by wkappbot-code)
+
+This file was written by `wkappbot-code install` because you had no `~/.claude/CLAUDE.md`. Edit it freely: once you
+change it, install never touches it again, and `wkappbot-code uninstall` leaves your version in place.
+
+## How to work
+- Reply in the language the user writes in. Keep replies short and concrete; lead with the result.
+- Before real work, find the skill that governs it: `wkskill search <three or more words>`, then `wkskill read <id>`,
+  and follow the road it gives. Search again for any term you are not sure of, instead of guessing.
+- Run, do not guess: prove a change by running its test or command, and report the real output, failures included.
+- One command per tool call. Change only what the task needs, and back up a config file before you edit it.
+
+## Never
+- Skip or weaken a safety hook: no `git --no-verify`, no `git push --force`, no change of `core.hooksPath`, no
+  `rm -rf` of a home folder or a project, no writes inside `.git`. The harness refuses these; when it refuses, read
+  the skill the refusal names and take the road it prints, never a workaround.
+- Put a secret (an API key, a token, a password) in a file, a commit, a log or a reply. Read keys from environment
+  variables.
+- Do an irreversible outward act without the user's explicit go: sending a message or mail, paying, publishing,
+  deploying, or deleting someone else's data.