wkappbot-code 0.0.0-stage → 0.3.1

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# wkappbot-code -- Wisdom Kernel (WK)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A prototype OpenCode distribution: the upstream OpenCode release, pinned to `opencode-ai@1.19.5`, plus one kih plugin. wkappbot-code contains no coding engine of its own.
+
+## Bridge, not harness
+
+OpenCode is the **bridge**. It connects any model (Claude, GPT, Qwen, Kimi, GLM and local models) to files, shell, LSP and its clients. kih is the **harness**: the discipline layer that rides on the bridge, made of refusal gates, skill learning, memory and pace. In wkappbot-code the kernel loads bridges the way an OS kernel loads drivers. OpenCode, Claude Code and Codex are the drivers, and each model is a device behind them.
+
+The plugin `plugin/wisdom-kernel.js` maps OpenCode plugin events onto the existing kih hook launcher `.claude/hooks/wkharness-run.sh`:
+
+| OpenCode event | kih arm | effect |
+|---|---|---|
+| `tool.execute.before` | `pre` | Claude-shaped PreToolUse JSON (`tool_name`, `tool_input`, `session_id`, `cwd`). Exit 2 throws, which refuses the tool call with the hook's stderr as the reason. |
+| `tool.execute.after` | `post` | fail-open |
+| `event` `session.idle` | `stop-archive` | archive only, fail-open |
+
+Tool names are mapped as `bash`/`edit`/`write`/`read` -> `Bash`/`Edit`/`Write`/`Read`, with camelCase args (`filePath`, `oldString`) mapped to snake_case (`file_path`, `old_string`).
+
+## Install
+
+```bash
+bash wkappbot-code/install.sh            # npm i -g opencode-ai@1.19.5, copy plugin + config (idempotent)
+bash wkappbot-code/install.sh --no-npm   # wire the plugin only
+bash wkappbot-code/selftest.sh           # RESULT N/N; --synthetic-only where no kih hook can run
+```
+
+### One command installs everything
+
+Get the CLI by one of three roads, then run `wkappbot-code install` once:
+
+```bash
+npm i -g https://kiexpert.github.io/wkappbot-kih/wkappbot-code/wkappbot-code.tgz   # web: the scrub-gated tgz the SDK workflow ships daily (SHA256SUMS + version.json beside it)
+npm i -g wkappbot-code                                                        # registry (published only when the SDK has NPM_TOKEN)
+npm pack ./wkappbot-code && npm i -g ./wkappbot-code-0.3.1.tgz                  # from a checkout
+
+wkappbot-code install      # every part below, idempotent
+wkappbot-code doctor       # one PASS/WARN/FAIL/SKIP row per part
+wkappbot-code --version
+# the old command name wk-appbot-code (0.2.x) still works: it is a second bin entry for the same file
+```
+
+
+| part | what `install` lays down | skip with |
+|---|---|---|
+| opencode | pinned `opencode-ai@1.19.5` (`npm -g`) | `--no-npm` |
+| plugin | `plugin/wisdom-kernel.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`, byte-identical to kih `tools/wk-bin-acquire.sh`); placed at `~/.local/share/wkappbot/wkappbot` and linked as `wkappbot` beside `wkappbot-code` | `--no-bin` |
+| harness | when no kih checkout is found, the scrubbed web harness to `~/.wk-harness` through its own published `install.sh` (sha256-checked); `--web-harness` forces it | `--no-harness` |
+| skills | the latest public skills from the same published tarball (sha256-checked) into the core's HQ `<core dir>/wkappbot.hq/skills`, so `wkappbot skill read on-load` prints | `--no-skills` |
+
+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. Skill push belongs to the owner's GitHub account only; doctor's `skill-push = owner-only` row names the login a push would use (`gh api user`, else `none`) and WARNs unless it is the owner's.
+
+`install.sh` and `wkappbot-code install` are the same code. An existing `~/.config/opencode/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. Pass `--kih-dir` (or set `WK_KIH_DIR`) when the kih checkout is not auto-found; without a checkout or `~/.wk-harness` the plugin lets every call through. 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` (`selftest.sh` part (i) mocks every network part with them).
+
+## Model swap
+
+- One headless turn: `opencode run -m provider/model "prompt"`
+- Inside the TUI: `/models`
+- In-house Qwen: `opencode.json` already declares the `qwen-inhouse` provider (`@ai-sdk/openai-compatible`). Set `QWEN_BASE_URL` and `QWEN_API_KEY` in the environment, then run `opencode run -m qwen-inhouse/qwen3-coder "hello"`. No key is stored in git.
+
+## In the browser WebVM (no login needed)
+
+The x64 WebVM page (`webvm/x64/index.html`) types `wk-ai wkappbot-code` once the shell is ready, so the wkappbot-code prompt is up without typing. `?noappbot` turns this off, and an embedded page only autostarts with `?appbot`. Each question goes through the page bridge:
+
+1. A custom OpenAI-compatible provider in `localStorage` (`webvm.appbot.provider` = `{"baseURL","model","key"}`, with the key in `webvm.key.<key>`), for example the in-house Qwen.
+2. Otherwise the first family key the browser holds (claude, openai, gemini, xai).
+3. Otherwise the **dummy haiku**: an OpenAI-compatible mock inside the page. It never calls a model, and its first line reads `dummy haiku (로그인 전)`.
+
+The kih lite hooks stay live in the guest. Each question is a prompt event, and `!<command>` is a Bash tool call checked by `tools/wkharness-lite.sh` first, so the intent lock refuses a command until a `!wkskill search ...` has run. Proof: `node webvm/selftest/appbot-dummy-test.js` (no VM, no network), and `webvm/selftest/x64-appbot-test.js --page ... --install ...` against the published image. The guest's `wk-ai` gets the `!cmd`/hook support only after the SDK webvm-x64 bake; until then the page's dummy and provider path already works with the old image.
+
+## Floor
+
+
+Signing, submitting and paying stay human-only.

package/bin/wkappbot-code.js

@@ -0,0 +1,453 @@
+#!/usr/bin/env node
+// wkappbot-code -- wkappbot-code (Wisdom Kernel) installer CLI: one npm line, then `wkappbot-code install`.
+//   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
+//       plugin     plugin/wisdom-kernel.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 kih tools/wk-bin-acquire.sh, shipped byte-identical
+//                  in lib/ (the selftest pins the two copies equal)               skip: --no-bin
+//       harness    the scrubbed web harness to ~/.wk-harness through its own published install.sh,
+//                  only when no kih checkout is found (--web-harness forces it)  skip: --no-harness
+//       skills     the latest public skills from the same published tarball (sha256-checked) into the
+//                  core's HQ (<core dir>/wkappbot.hq/skills), so `wkappbot skill read on-load` prints;
+//                  a READ-ONLY copy with no git remote. A user's own skill edits go to the private
+//                  home ~/.wkappbot/private-skills (a local git repo, no remote)  skip: --no-skills
+//   wkappbot-code doctor  [opts]       one PASS/WARN/FAIL/SKIP row per part (exit 1 if a required part fails)
+//   wkappbot-code update  [opts]       newer version.json -> tgz sha256-checked -> npm i -g -> install --update (lib/update.js)
+//   wkappbot-code config  [opts]       detect provider/model/plugin/harness, edit at a TTY, merge into opencode.json (lib/config.js)
+// install/doctor/config check for a newer version at most once a day (WKAPPBOT_CODE_NO_UPDATE_CHECK=1 turns it off;
+// --auto-update or WKAPPBOT_CODE_AUTO_UPDATE=1 applies it). config opts: --yes, --project, --set key=value
+// opts: --config-dir DIR, --kih-dir DIR, --bin-dest FILE, --hq-dir DIR
+// env (mock and relocation): WK_BIN_BASE (SDK release base), WK_HARNESS_BASE (web harness base),
+//   WK_HARNESS_DIR (~/.wk-harness), WK_BIN_DEST, WK_APPBOT_HQ, WK_LINK_DIR, WK_PRIVATE_SKILLS,
+//   WK_KIH_DIR (a kih checkout; "none" = ignore every checkout on this machine)
+// Installer owns all setup, surgically: an existing user opencode.json is BACKED UP and only the plugin entry is
+// merged in; every other key is kept. Spec: wkappbot skill read agent-harness-landscape-2026-howto
+// and wkappbot skill read harness-installer-owns-all-setup (step 9 ONE-COMMAND APPBOT CODE INSTALL)
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync,
+  realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, utimesSync, writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { quietCheck, runUpdate, updateRow } from "../lib/update.js";
+import { applySets, askEach, buildConfig, configRow, detect, lineDiff, printDetected } from "../lib/config.js";
+
+const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const PKG = JSON.parse(readFileSync(join(PKG_DIR, "package.json"), "utf8"));
+const OPENCODE_VERSION = PKG.wkAppbotCode.opencodeVersion;
+const OWNER_LOGIN = "kiexpert";
+const HARNESS_BASE = () => (process.env.WK_HARNESS_BASE || "https://kiexpert.github.io/wkappbot-kih/webvm/x64/harness").replace(/\/+$/, "");
+const HARNESS_DIR = () => process.env.WK_HARNESS_DIR || join(homedir(), ".wk-harness");
+const IS_WIN = process.platform === "win32";
+
+function parseArgs(argv) {
+  const o = { cmd: argv[0] || "help", npm: true, bin: true, harness: true, skills: true, webHarness: 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-bin") o.bin = false;
+    else if (a === "--no-harness") o.harness = false;
+    else if (a === "--no-skills") o.skills = false;
+    else if (a === "--web-harness") o.webHarness = true;
+    else if (a === "--config-dir") o.configDir = argv[++i] || "";
+    else if (a === "--kih-dir") o.kihDir = argv[++i] || "";
+    else if (a === "--bin-dest") o.binDest = argv[++i] || "";
+    else if (a === "--hq-dir") o.hqDir = argv[++i] || "";
+    else if (a === "--update") o.update = true;
+    else if (a === "--auto-update") o.autoUpdate = true;
+    else if (a === "--yes" || a === "-y") o.yes = true;
+    else if (a === "--project") o.project = true;
+    else if (a === "--set") o.sets.push(argv[++i] || "");
+    else { console.error("unknown option: " + a); process.exit(64); }
+  }
+  return o;
+}
+
+function configDir(o) {
+  if (o.configDir) return resolve(o.configDir);
+  if (process.env.OPENCODE_CONFIG_DIR) return process.env.OPENCODE_CONFIG_DIR;
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode");
+}
+
+const hasHook = (d) => !!d && existsSync(join(d, ".claude", "hooks", "wkharness-run.sh"));
+// A kih CHECKOUT (never the web harness): explicit dirs first, then the usual checkout places.
+// WK_KIH_DIR=none: act as on a machine with no checkout (the selftest's isolation from this VM's kih).
+function kihCheckout(o) {
+  if (process.env.WK_KIH_DIR === "none") return o.kihDir && hasHook(o.kihDir) ? resolve(o.kihDir) : "";
+  const tries = [o.kihDir, process.env.WK_KIH_DIR, resolve(PKG_DIR, ".."),
+    join(homedir(), "wkappbot-kih"), "/home/user/wkappbot-kih", "D:/GitHub/wkappbot-kih"];
+  for (const d of tries) if (hasHook(d)) return resolve(d);
+  return "";
+}
+// The kih root whose .claude/hooks/wkharness-run.sh the plugin calls: a checkout, else the web harness
+// (~/.wk-harness). Empty = plugin fails open.
+function kihDir(o) {
+  return kihCheckout(o) || (hasHook(HARNESS_DIR()) ? resolve(HARNESS_DIR()) : "");
+}
+
+function opencodeVersion() {
+  try { return execFileSync("opencode", ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }
+  catch { return ""; }
+}
+
+const stamp = () => new Date().toISOString().replace(/[-:]/g, "").replace(/\..*/, "");
+const log = (s) => console.log("[wkappbot-code] " + s);
+const sha256File = (f) => createHash("sha256").update(readFileSync(f)).digest("hex");
+const statePath = (o) => join(configDir(o), "wkappbot-code", "install-state.json");
+function readState(o) { try { return JSON.parse(readFileSync(statePath(o), "utf8")); } catch { return {}; } }
+
+// Same rule as wk-bin-acquire.sh platform_detect (linux-x64, osx-arm64, osx-x64, win-x64).
+export function platformId(platform = process.platform, arch = process.arch) {
+  if (platform === "linux" && arch === "x64") return "linux-x64";
+  if (platform === "darwin") return arch === "arm64" ? "osx-arm64" : arch === "x64" ? "osx-x64" : "";
+  if (platform === "win32") return "win-x64";
+  return "";
+}
+
+// Merge our plugin entry into a user config: drop any older wisdom-kernel entry, append the new one.
+export function mergeConfig(user, template, url, kih) {
+  return buildConfig(user, { plugin: { value: url }, harness: { value: kih } }, template);
+}
+
+// ---- part: bin ------------------------------------------------------------------------------------
+function binDest(o) {
+  if (o.binDest) return resolve(o.binDest);
+  if (process.env.WK_BIN_DEST) return resolve(process.env.WK_BIN_DEST);
+  // The same fallback place tools/wkappbot-root.sh looks for a core when none sits beside it.
+  return join(homedir(), ".local", "share", "wkappbot", IS_WIN ? "wkappbot.exe" : "wkappbot");
+}
+// The dir of the CLI's own bin as npm placed it (argv[1] is npm's symlink in PREFIX/bin, never realpath'd).
+// Run from a checkout or lib/node_modules (that dir is inside PKG_DIR): ~/.local/bin instead.
+function linkDir() {
+  if (process.env.WK_LINK_DIR) return process.env.WK_LINK_DIR;
+  const here = resolve(dirname(process.argv[1] || PKG_DIR));
+  const rel = relative(PKG_DIR, here);
+  if (rel.startsWith("..") || isAbsolute(rel)) return here;
+  return join(homedir(), ".local", "bin");
+}
+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 kih checkout" };
+  // A kih 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.
+  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", [script, "acquire", "--dest", dest], { encoding: "utf8", env: process.env });
+  for (const line of ((r.stdout || "") + (r.stderr || "")).split("\n").filter(Boolean)) log("  " + line);
+  if (r.status !== 0) return { ok: false, dest, note: "wk-bin-acquire rc " + r.status };
+  // Put `wkappbot` on PATH beside wkappbot-code itself, unless that name is already taken by someone else.
+  let link = "";
+  const ld = linkDir();
+  const lp = join(ld, "wkappbot");
+  try {
+    const taken = existsSync(lp) || isSymlink(lp);
+    const ours = taken && isSymlink(lp) && resolve(dirname(lp), readlinkSync(lp)) === dest;
+    if (taken && !ours) log("bin: kept existing wkappbot link " + lp + " (not ours); call " + dest + " directly");
+    else {
+      mkdirSync(ld, { recursive: true });
+      if (ours) unlinkSync(lp);
+      symlinkSync(dest, lp);
+      link = lp;
+      log("bin: linked " + lp + " -> " + dest);
+    }
+  } catch (e) { log("bin: could not link " + lp + " (" + e.message + ")"); }
+  return { ok: true, dest, link };
+}
+function isSymlink(p) { try { return lstatSync(p).isSymbolicLink(); } catch { return false; } }
+
+// ---- part: harness --------------------------------------------------------------------------------
+function curl(url, out) {
+  const r = spawnSync("curl", ["-fsSL", "-m", "300", url, "-o", out], { encoding: "utf8" });
+  return r.status === 0 ? "" : ("curl " + url + " rc " + r.status + " " + (r.stderr || "").trim());
+}
+function installHarness(o) {
+  const found = kihCheckout(o);
+  if (found && !o.webHarness) {
+    log("harness: kih checkout " + found + " found; the web harness is not needed (--web-harness forces it)");
+    return { ok: true, mode: "checkout", dir: found };
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "wk-appbot-harness-"));
+  try {
+    const err = curl(HARNESS_BASE() + "/install.sh", join(tmp, "install.sh"));
+    if (err) return { ok: false, mode: "web", dir: HARNESS_DIR(), note: err };
+    log("harness: sh " + HARNESS_BASE() + "/install.sh  (to " + HARNESS_DIR() + ")");
+    const r = spawnSync("sh", [join(tmp, "install.sh")], { encoding: "utf8",
+      env: { ...process.env, WK_HARNESS_BASE: HARNESS_BASE(), WK_HARNESS_DIR: HARNESS_DIR() } });
+    for (const line of ((r.stdout || "") + (r.stderr || "")).split("\n").filter(Boolean)) log("  " + line);
+    const ok = r.status === 0 && hasHook(HARNESS_DIR());
+    return { ok, mode: "web", dir: HARNESS_DIR(), note: ok ? "" : "harness install rc " + r.status };
+  } finally { rmSync(tmp, { recursive: true, force: true }); }
+}
+
+// ---- part: skills ---------------------------------------------------------------------------------
+function hqDir(o, dest) {
+  if (o.hqDir) return resolve(o.hqDir);
+  if (process.env.WK_APPBOT_HQ) return resolve(process.env.WK_APPBOT_HQ);
+  let real = dest;
+  try { real = realpathSync(dest); } catch {}
+  return join(dirname(real), "wkappbot.hq", "skills");
+}
+// Copy every file under src into dst when it is missing or older there; keeps mtimes. Returns counts.
+export function syncTree(src, dst) {
+  const c = { added: 0, updated: 0, kept: 0 };
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const s = join(d, e.name);
+      const t = join(dst, relative(src, s));
+      if (e.isDirectory()) { walk(s); continue; }
+      if (!e.isFile()) continue;
+      const ss = statSync(s);
+      let ts = null; try { ts = statSync(t); } catch {}
+      if (ts && ts.mtimeMs >= ss.mtimeMs) { c.kept++; continue; }
+      mkdirSync(dirname(t), { recursive: true });
+      copyFileSync(s, t + ".new");
+      renameSync(t + ".new", t);
+      utimesSync(t, ss.atime, ss.mtime);
+      ts ? c.updated++ : c.added++;
+    }
+  };
+  walk(src);
+  return c;
+}
+const countSkills = (d) => {
+  let n = 0;
+  const walk = (x) => { for (const e of readdirSync(x, { withFileTypes: true })) {
+    if (e.isDirectory()) walk(join(x, e.name)); else if (e.name.endsWith(".skill.json")) n++; } };
+  try { walk(d); } catch {}
+  return n;
+};
+function privateHome() { return process.env.WK_PRIVATE_SKILLS || join(homedir(), ".wkappbot", "private-skills"); }
+function gitRemotes(dir) {
+  const r = spawnSync("git", ["-C", dir, "remote"], { encoding: "utf8" });
+  return r.status === 0 ? r.stdout.split("\n").filter(Boolean) : null;
+}
+function installSkills(o, dest) {
+  const hq = hqDir(o, dest);
+  const base = HARNESS_BASE();
+  const tmp = mkdtempSync(join(tmpdir(), "wk-appbot-skills-"));
+  try {
+    let src = "", from = "";
+    let err = curl(base + "/version.json", join(tmp, "version.json"));
+    if (err) return { ok: false, hq, note: err };
+    let vj = {}; try { vj = JSON.parse(readFileSync(join(tmp, "version.json"), "utf8")); } catch {}
+    // The web harness just installed (or already current) holds the same tarball's skills/: reuse it.
+    let iv = {}; try { iv = JSON.parse(readFileSync(join(HARNESS_DIR(), ".installed-version"), "utf8")); } catch {}
+    if (vj.sha256 && iv.sha256 === vj.sha256 && existsSync(join(HARNESS_DIR(), "skills"))) {
+      src = join(HARNESS_DIR(), "skills"); from = HARNESS_DIR() + "/skills (installed version " + iv.version + ")";
+    } else {
+      const tgz = join(tmp, "wk-harness-min.tar.gz");
+      if ((err = curl(base + "/wk-harness-min.tar.gz.sha256", join(tmp, "want.sha256")))) return { ok: false, hq, note: err };
+      const want = readFileSync(join(tmp, "want.sha256"), "utf8").trim().split(/\s+/)[0];
+      if (!/^[0-9a-f]{64}$/.test(want)) return { ok: false, hq, note: "the sha256 file holds no 64-hex hash" };
+      if ((err = curl(base + "/wk-harness-min.tar.gz", tgz))) return { ok: false, hq, note: err };
+      const got = sha256File(tgz);
+      if (got !== want) return { ok: false, hq, note: "sha256 MISMATCH for wk-harness-min.tar.gz: expected " + want + ", got " + got + "; no skill was copied" };
+      mkdirSync(join(tmp, "x"));
+      const r = spawnSync("tar", ["-xzf", tgz, "-C", join(tmp, "x")], { encoding: "utf8" });
+      if (r.status !== 0 || !existsSync(join(tmp, "x", "skills"))) return { ok: false, hq, note: "unpack failed or no skills/ in the tarball: " + (r.stderr || "") };
+      src = join(tmp, "x", "skills"); from = base + "/wk-harness-min.tar.gz (sha256 ok, version " + (vj.version || "?") + ")";
+    }
+    const c = syncTree(src, hq);
+    const n = countSkills(hq);
+    log("skills: " + n + " skills in HQ " + hq + " from " + from + " (added " + c.added + ", updated " + c.updated + ", kept " + c.kept + ")");
+    // Read-only copy: the HQ carries no git remote, and a user's own edits go to a local private home with none.
+    const ph = privateHome();
+    mkdirSync(ph, { recursive: true });
+    if (!existsSync(join(ph, ".git")) && spawnSync("git", ["init", "-q", ph]).status === 0)
+      log("skills: private home " + ph + " created as a local git repo with no remote");
+    return { ok: n > 0 && existsSync(join(hq, "wkappbot-workflow", "on-load.skill.json")), hq, count: n, privateHome: ph };
+  } finally { rmSync(tmp, { recursive: true, force: true }); }
+}
+
+// ---- install --------------------------------------------------------------------------------------
+function installPlugin(o, kih, kihSource) {
+  const cfg = configDir(o);
+  mkdirSync(join(cfg, "wkappbot-code"), { recursive: true });
+  const dest = join(cfg, "wkappbot-code", "wisdom-kernel.js");
+  copyFileSync(join(PKG_DIR, "plugin", "wisdom-kernel.js"), dest);
+  // The copy imports nothing from the package, but mark its folder ESM so Node never re-parses it.
+  writeFileSync(join(cfg, "wkappbot-code", "package.json"), '{ "type": "module" }\n');
+  const url = pathToFileURL(dest).href;
+  const tmpl = JSON.parse(readFileSync(join(PKG_DIR, "opencode.json"), "utf8"));
+  const target = o.project ? join(process.cwd(), "opencode.json") : join(cfg, "opencode.json");
+  let user = {}, raw = "";
+  if (existsSync(target)) {
+    raw = readFileSync(target, "utf8");
+    try { user = JSON.parse(raw); } catch { user = null; }
+  }
+  const it = detect({ user: user || {}, pluginUrl: url, kih, kihSource: kihSource || "kih checkout" });
+  for (const k of applySets(it, o.sets)) log("config: unknown --set key " + k + " (provider|model|plugin|harness)");
+  printDetected(it, log);
+  if (process.stdin.isTTY && process.stdout.isTTY && !o.yes) askEach(it);
+  if (!user) {
+    // JSONC or broken: never rewrite what we cannot parse; leave a sidecar to merge by hand.
+    const side = join(dirname(target), "wkappbot-code.json");
+    writeFileSync(side, JSON.stringify(buildConfig({}, it, tmpl), null, 2) + "\n");
+    log(target + " is not plain JSON; left untouched, wrote " + side + " -- merge its plugin entry by hand");
+    return;
+  }
+  const text = JSON.stringify(buildConfig(user, it, tmpl), null, 2) + "\n";
+  let note = "";
+  if (raw && text === raw) note = " (unchanged)";
+  else {
+    if (raw) {
+      const bak = target + ".bak-" + stamp();
+      copyFileSync(target, bak);
+      note = " (merged; backup " + bak + ")";
+    }
+    for (const l of lineDiff(raw, text)) log("diff " + l);
+    writeFileSync(target + ".tmp", text);
+    renameSync(target + ".tmp", target);
+  }
+  log("plugin: " + url);
+  log("config: " + target + note);
+}
+
+function install(o) {
+  const st = { version: PKG.version, at: new Date().toISOString() };
+  let bad = 0;
+  if (o.update) log("install --update: refreshing the core, the harness and the public skills");
+  if (o.npm) {
+    const have = opencodeVersion();
+    if (have === OPENCODE_VERSION) log("opencode " + have + " already installed");
+    else {
+      log("npm install -g opencode-ai@" + OPENCODE_VERSION + " (was: " + (have || "none") + ")");
+      execFileSync("npm", ["install", "-g", "opencode-ai@" + OPENCODE_VERSION, "--no-audit", "--no-fund"], { stdio: "inherit" });
+    }
+  }
+  const dest = binDest(o);
+  st.bin = o.bin ? installBin(o) : { skipped: true, dest };
+  if (o.bin && !st.bin.ok) { bad++; log("bin: FAILED -- " + 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.
+  // 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"))) {
+    const r = spawnSync("bash", [join(kih, "tools", "wk-global-hooks.sh"), "install", "--gate-dir", join(kih, ".githooks", "lib")], { encoding: "utf8" });
+    for (const line of ((r.stdout || "") + (r.stderr || "")).split("\n").filter(Boolean)) log("push-gate: " + line);
+    st.pushGate = { ok: r.status === 0, kih };
+  }
+  st.skills = o.skills ? installSkills(o, dest) : { skipped: true };
+  if (o.skills && !st.skills.ok) { bad++; log("skills: FAILED -- " + (st.skills.note || "on-load missing from the HQ")); }
+  installPlugin(o, kih, (st.harness.mode === "web" && st.harness.ok) ? "web harness" : "kih checkout");
+  st.kihDir = kih;
+  writeFileSync(statePath(o), JSON.stringify(st, null, 2) + "\n");
+  log("kih:    " + (kih || "NOT FOUND -- plugin fails open until --kih-dir or WK_KIH_DIR points at a kih checkout"));
+  log((bad ? "done with " + bad + " failed part(s)" : "done") + " -- check: wkappbot-code doctor   then run: opencode");
+  return bad ? 1 : 0;
+}
+
+// ---- doctor ---------------------------------------------------------------------------------------
+// The GitHub login a skill push would use: gh when present, else "none". Push is the owner's alone.
+export function pushLogin() {
+  const r = spawnSync("gh", ["api", "user", "-q", ".login"], { encoding: "utf8", timeout: 15000 });
+  if (r.error) return "none";
+  return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : "none";
+}
+
+function doctor(o) {
+  const cfg = configDir(o);
+  const st = readState(o);
+  const rows = [];
+  const add = (name, ok, detail, required, skip) => rows.push({ name, ok, detail, required, skip });
+  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");
+  add("plugin", existsSync(pdest), pdest, true);
+  let entry = null;
+  try { entry = (JSON.parse(readFileSync(join(cfg, "opencode.json"), "utf8")).plugin || []).find((p) => String(Array.isArray(p) ? p[0] : p).includes("wisdom-kernel")); } catch {}
+  add("config", !!entry, join(cfg, "opencode.json"), true);
+  const oc = configRow(join(cfg, "opencode.json"));
+  add("opencode-config", oc.ok, oc.detail, false);
+  // 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 {
+    const r = spawnSync(dest, ["--version"], { encoding: "utf8", timeout: 60000 });
+    core = r.status === 0 ? (r.stdout || "").trim().split("\n")[0] : "";
+    add("bin", !!core, core ? dest + "  " + core + (st.bin && st.bin.link ? "  (PATH link " + st.bin.link + ")" : "") : dest + " does not run", !!(st.bin && !st.bin.skipped));
+  }
+  // kih-hook: the harness the plugin calls
+  const k = (entry && Array.isArray(entry) && entry[1] && entry[1].kihDir) || kihDir(o);
+  const hk = hasHook(k);
+  if (st.harness && st.harness.skipped && !hk) add("kih-hook", false, "skipped (--no-harness)", false, true);
+  else add("kih-hook", hk, k ? k + (st.harness && st.harness.mode ? "  (" + st.harness.mode + ")" : "") : "not found", !!(st.harness && st.harness.mode === "web"));
+  // guards: which guard set the plugin can run. The full set needs PowerShell; without it the plugin falls back to
+  // the bash lite harness (intent lock, study lock), so this row WARNs instead of passing silently (QA 2026-11-06).
+  if (hk) {
+    const psDirs = String(process.env.PATH || "").split(IS_WIN ? ";" : ":");
+    const ps = ["pwsh", "pwsh.exe", "powershell.exe", "powershell"].find((n) => psDirs.some((d) => d && existsSync(join(d, n))));
+    const lite = existsSync(join(k, "tools", "wkharness-lite.sh"));
+    add("guards", !!ps, ps ? "full guard set (" + ps + ")" : lite ? "no PowerShell on PATH: lite guards only (intent lock, study lock); install pwsh 7 for the full set" : "no PowerShell and no lite harness: every tool call is let through", !ps && !lite);
+  }
+  // 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);
+  else {
+    const n = countSkills(hq);
+    let printed = false, why = "";
+    if (core) {
+      const cwd = mkdtempSync(join(tmpdir(), "wk-appbot-doctor-"));
+      const r = spawnSync(dest, ["skill", "read", "on-load"], { cwd, encoding: "utf8", timeout: 120000,
+        env: { ...process.env, WKAPPBOT_NO_REMOTE_CHECK: "1" } });
+      printed = /\bID\s*:\s*on-load\b/.test(r.stdout || "");
+      if (!printed) why = "  skill read on-load rc " + r.status;
+      rmSync(cwd, { recursive: true, force: true });
+    } else why = "  (no core to read with)";
+    add("skills", n > 0 && printed, n + " skills in " + hq + (printed ? "; wkappbot skill read on-load prints" : why), !!(st.skills && !st.skills.skipped));
+  }
+  // push-gate: the global core.hooksPath runs the push-owner gate (directly, or through the global dispatcher).
+  const ghp = (() => { try { return execFileSync("git", ["config", "--global", "--get", "core.hooksPath"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch { return ""; } })();
+  let gated = false;
+  try { gated = /push-owner-gate|wk-global-hooks\.sh/.test(readFileSync(join(ghp.replace(/^~(?=\/|$)/, homedir()), "pre-push"), "utf8")); } catch {}
+  add("push-gate", gated, "global core.hooksPath " + (ghp || "unset") + (gated ? " runs the push-owner gate" : " does not run the push-owner gate"), false);
+  // skill-push: owner-only. The laid-down skills are a read-only copy; a push may only ever use the owner login.
+  const login = pushLogin();
+  const ph = privateHome();
+  const rem = existsSync(join(ph, ".git")) ? gitRemotes(ph) : [];
+  const remNote = rem && rem.length ? "; private home " + ph + " HAS remote(s) " + rem.join(",") : "; private home " + ph + " has no remote";
+  add("skill-push", login === OWNER_LOGIN && !(rem && rem.length), "= owner-only; a push would use github login " + login + remNote, false);
+  const ur = updateRow(PKG.version);
+  add("update", !!ur.ok, ur.detail, false, !!ur.skip);
+  let bad = 0;
+  for (const r of rows) {
+    console.log((r.skip ? "SKIP " : r.ok ? "PASS " : r.required ? "FAIL " : "WARN ") + r.name + "  " + r.detail);
+    if (!r.ok && r.required && !r.skip) bad++;
+  }
+  return bad ? 1 : 0;
+}
+
+const o = parseArgs(process.argv.slice(2));
+// install --update (from update) and these flags are forwarded to the re-run install of a fresh version.
+const fwd = process.argv.slice(3).filter((a) => a !== "--auto-update");
+const upd = () => runUpdate({ current: PKG.version, cliPath: process.argv[1], installArgs: fwd, log: console.log });
+if (["install", "doctor", "config"].includes(o.cmd) && !o.update) {
+  const nv = quietCheck(PKG.version, console.log);
+  if (nv && (o.autoUpdate || process.env.WKAPPBOT_CODE_AUTO_UPDATE === "1")) upd();
+}
+switch (o.cmd) {
+  case "--version": case "-v": case "version":
+    console.log("wkappbot-code " + PKG.version + " (opencode-ai " + OPENCODE_VERSION + ")"); process.exit(0);
+  case "install": process.exit(install(o));
+  case "doctor": process.exit(doctor(o));
+  case "update": process.exit(upd());
+  case "config": installPlugin(o, kihDir(o), kihCheckout(o) ? "kih checkout" : "web harness"); process.exit(0);
+  default:
+    console.log("usage: wkappbot-code --version | install [--no-npm] [--no-bin] [--no-harness] [--no-skills] [--web-harness]\n" +
+      "         [--config-dir DIR] [--kih-dir DIR] [--bin-dest FILE] [--hq-dir DIR] [--update] [--auto-update] | doctor [--config-dir DIR]\n" +
+      "       | update [install opts] | config [--yes] [--project] [--set key=value] [--config-dir DIR]");
+    process.exit(o.cmd === "help" || o.cmd === "--help" ? 0 : 64);
+}

package/install.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# wkappbot-code -- Wisdom Kernel installer from a kih checkout (idempotent). Installs the PINNED OpenCode release
+# and wires the one kih plugin into the user's OpenCode config (a non-JSON config is left untouched and a
+# sidecar wkappbot-code.json is written to merge by hand).
+# Spec: wkappbot skill read agent-harness-landscape-2026-howto
+# Usage: bash wkappbot-code/install.sh [--no-npm] [--config-dir DIR]
+command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "wkappbot-code install"
+# ONE INSTALL PATH (2026-11-05): this wraps bin/wkappbot-code.js install, the same code that
+# `npm install -g wkappbot-code` puts on PATH, so a checkout and the npm package never install differently.
+# The pin lives in package.json wkAppbotCode.opencodeVersion; an existing opencode.json is backed up and
+# only the plugin entry is merged in (every other user key is kept).
+HERE="$(cd "$(dirname "$0")" && pwd)"
+KIH="$(cd "$HERE/.." && pwd)"
+NODE="$(command -v node || true)"
+[ -z "$NODE" ] && { echo "[wkappbot-code] node not found; install Node.js 18+ first" >&2; exit 1; }
+exec "$NODE" "$HERE/bin/wkappbot-code.js" install --kih-dir "$KIH" "$@"