wkappbot-code 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,75 @@
-# 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 four 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 i -g --install-links git+https://github.com/kiexpert/wkappbot-kih.git     # git: the repo ROOT package exposes the same bin
+npm pack ./wkappbot-code && npm i -g ./wkappbot-code-0.3.0.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
+```
+
+The git road needs `--install-links`: without it npm 10 links the bin to a temp clone it then deletes.
+
+| 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. Never install kih or anything built from it onto the SK laptop.

package/bin/wkappbot-code.js

@@ -0,0 +1,420 @@
+#!/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)
+// 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";
+
+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: "" };
+  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 { 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) {
+  const out = { ...user };
+  const ours = [url, { kihDir: kih }];
+  const keep = (Array.isArray(user.plugin) ? user.plugin : []).filter((p) => !String(Array.isArray(p) ? p[0] : p).includes("wisdom-kernel"));
+  out.plugin = [...keep, ours];
+  if (!out.$schema && template.$schema) out.$schema = template.$schema;
+  if (!out.provider) out.provider = template.provider;
+  else if (template.provider) for (const [k, v] of Object.entries(template.provider)) if (!(k in out.provider)) out.provider[k] = v;
+  if (!out.permission) out.permission = template.permission;
+  return out;
+}
+
+// ---- 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) {
+  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 = join(cfg, "opencode.json");
+  let next, note = "";
+  if (existsSync(target)) {
+    const raw = readFileSync(target, "utf8");
+    let user;
+    try { user = JSON.parse(raw); } catch { user = null; }
+    if (!user) {
+      // JSONC or broken: never rewrite what we cannot parse; leave a sidecar to merge by hand.
+      const side = join(cfg, "wkappbot-code.json");
+      writeFileSync(side, JSON.stringify(mergeConfig({}, tmpl, url, kih), null, 2) + "\n");
+      log(target + " is not plain JSON; left untouched, wrote " + side + " -- merge its plugin entry by hand");
+      return;
+    }
+    next = mergeConfig(user, tmpl, url, kih);
+    if (JSON.stringify(next, null, 2) + "\n" === raw) note = " (unchanged)";
+    else {
+      const bak = target + ".bak-" + stamp();
+      copyFileSync(target, bak);
+      note = " (merged; backup " + bak + ")";
+    }
+  } else next = mergeConfig({}, tmpl, url, kih);
+  writeFileSync(target + ".tmp", JSON.stringify(next, null, 2) + "\n");
+  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.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.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);
+  // 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"));
+  // 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);
+  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));
+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));
+  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] | doctor [--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" "$@"

package/lib/wk-bin-acquire.sh

@@ -0,0 +1,305 @@
+#!/usr/bin/env bash
+# wk-bin-acquire -- acquire, install and publish the wkappbot binary for every platform.
+#
+# Usage:
+#   wk-bin-acquire.sh acquire [--dest PATH] [--dry-run] [--offline]
+#     Platform from uname: linux-x64, osx-arm64, osx-x64, win-x64. Unix: PATH is the binary file.
+#     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.
+#     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
+#     its MANIFEST.md row, commits the two paths with mode 100755 (non-Windows), then pushes.
+#
+# Env: WK_BIN_NO_PUSH=1 skips the push; WKAPPBOT_DIR locates bin/wkpush.sh;
+#      WKAPPBOT_HOME selects the Windows install directory; WK_BIN_BASE replaces the SDK release download
+#      base (a selftest points it at a file:// mock).
+# Outside a git checkout (the copy shipped in the wkappbot-code npm package, wkappbot-code/lib/) REPO is
+# empty: acquire then takes only the verified SDK asset, and the repo fallback refuses with a clear line.
+set -euo pipefail
+
+WK_DRY=0
+WK_TMP=""
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(git -C "$SELF_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+
+die() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "die" || true
+  echo "wk-bin-acquire: $*" >&2
+  exit 1
+}
+
+note() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "note" || true
+  echo "wk-bin-acquire: $*" >&2
+}
+
+run() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "run" || true
+  if [ "$WK_DRY" = 1 ]; then
+    echo "DRY: $*"
+  else
+    "$@"
+  fi
+}
+
+sha_of() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "sha_of" || true
+  [ -f "$1" ] || return 1
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | cut -d' ' -f1
+  else
+    shasum -a 256 "$1" | cut -d' ' -f1
+  fi
+}
+
+platform_detect() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "platform_detect" || true
+  local s m
+  s="$(uname -s)"
+  m="$(uname -m)"
+  case "$s" in
+    Linux)
+      if [ "$m" = x86_64 ]; then echo linux-x64; else die "unsupported Linux arch: $m"; fi ;;
+    Darwin)
+      case "$m" in
+        arm64) echo osx-arm64 ;;
+        x86_64) echo osx-x64 ;;
+        *) die "unsupported macOS arch: $m" ;;
+      esac ;;
+    MINGW*|MSYS*|CYGWIN*) echo win-x64 ;;
+    *) die "unsupported OS: $s" ;;
+  esac
+}
+
+# manifest_field REL COL -- COL 3 platform, 4 version, 6 sha256 of the bin/MANIFEST.md row for REL.
+manifest_field() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "manifest_field" || true
+  awk -F'|' -v p="$1" -v c="$2" '
+    { x = $2; gsub(/^[ \t]+|[ \t]+$/, "", x)
+      if (x == p) { y = $c; gsub(/^[ \t]+|[ \t]+$/, "", y); print y; exit } }' "$REPO/bin/MANIFEST.md"
+}
+
+default_dest_unix() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "default_dest_unix" || true
+  if [ -w /opt/wkappbot ] || { [ ! -e /opt/wkappbot ] && [ -w /opt ]; }; then
+    echo /opt/wkappbot/wkappbot
+  else
+    echo "$HOME/.local/opt/wkappbot/wkappbot"
+  fi
+}
+
+default_dest_win() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "default_dest_win" || true
+  if [ -n "${WKAPPBOT_HOME:-}" ]; then
+    echo "$WKAPPBOT_HOME/bin"
+  else
+    echo "$HOME/wkappbot/bin"
+  fi
+}
+
+# sdk_fetch PLAT DIR -- prints the verified asset path, or returns 1 and prints nothing.
+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"
+  base="${WK_BIN_BASE:-https://github.com/kiexpert/wkappbot-sdk/releases/latest/download}"
+  curl -fsSL -m 120 "$base/$asset" -o "$dir/$asset" || return 1
+  curl -fsSL -m 120 "$base/SHA256SUMS" -o "$dir/SHA256SUMS" || return 1
+  want="$(awk -v f="$asset" '{ n = $2; sub(/^\*/, "", n); if (n == f) { print $1; exit } }' "$dir/SHA256SUMS")"
+  [ -n "$want" ] || return 1
+  got="$(sha_of "$dir/$asset" || true)"
+  [ "$got" = "$want" ] || return 1
+  echo "$dir/$asset"
+}
+
+# repo_file REL -- prints REPO/bin/REL when its sha256 matches the MANIFEST row, else dies.
+repo_file() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "repo_file" || true
+  local rel="$1" want got
+  [ -n "$REPO" ] || die "no verified SDK asset and no repo copy of bin/$rel (this copy is not inside a kih checkout)"
+  want="$(manifest_field "$rel" 6 || true)"
+  [ -n "$want" ] || die "no MANIFEST row for bin/$rel"
+  got="$(sha_of "$REPO/bin/$rel" || true)"
+  [ -n "$got" ] || die "missing bin/$rel"
+  [ "$got" = "$want" ] || die "sha256 mismatch for bin/$rel: MANIFEST $want, file $got"
+  echo "$REPO/bin/$rel"
+}
+
+# install_file SRC DEST LABEL -- copy via .new then mv; "up to date" when DEST already matches.
+install_file() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "install_file" || true
+  local src="$1" dest="$2" label="$3" sum verb="installed"
+  sum="$(sha_of "$src")"
+  if [ -f "$dest" ] && [ "$(sha_of "$dest" || true)" = "$sum" ]; then
+    echo "up to date: $dest (source: $label) sha256=$sum"
+    return 0
+  fi
+  if [ "$WK_DRY" = 1 ]; then verb="would install"; fi
+  run mkdir -p "$(dirname "$dest")"
+  run cp "$src" "$dest.new"
+  run chmod +x "$dest.new"
+  run mv -f "$dest.new" "$dest"
+  echo "$verb: $dest (source: $label) sha256=$sum"
+}
+
+acquire_unix() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "acquire_unix" || true
+  local dest="$1" plat="$2" offline="$3" src label
+  [ -n "$dest" ] || dest="$(default_dest_unix)"
+  if [ "$offline" = 0 ] && src="$(sdk_fetch "$plat" "$WK_TMP")"; then
+    label="SDK release wkappbot-$plat"
+  else
+    if [ "$offline" = 0 ]; then note "SDK asset unavailable or unverified, using repo bin/$plat"; fi
+    src="$(repo_file "$plat/wkappbot")"
+    label="repo bin/$plat/wkappbot"
+  fi
+  install_file "$src" "$dest" "$label"
+}
+
+acquire_win() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "acquire_win" || true
+  local dest="$1" exe xzsrc core
+  [ -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")"
+  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"
+}
+
+acquire() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "acquire" || true
+  local dest="" offline=0 plat
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --dest) dest="${2:-}"; [ -n "$dest" ] || die "--dest needs a path"; shift 2 ;;
+      --dry-run) WK_DRY=1; shift ;;
+      --offline) offline=1; shift ;;
+      *) die "acquire: unknown argument: $1" ;;
+    esac
+  done
+  plat="$(platform_detect)"
+  if [ "$plat" = win-x64 ]; then
+    acquire_win "$dest"
+  else
+    acquire_unix "$dest" "$plat" "$offline"
+  fi
+}
+
+# rewrite_manifest REL ROW -- replaces REL's row, or appends ROW after the last table row.
+rewrite_manifest() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "rewrite_manifest" || true
+  local rel="$1" row="$2" m="$REPO/bin/MANIFEST.md"
+  if [ "$WK_DRY" = 1 ]; then
+    echo "DRY: set bin/MANIFEST.md row: $row"
+    return 0
+  fi
+  [ -f "$m" ] || die "no $m"
+  grep -q '^|' "$m" || die "no table in $m"
+  awk -v p="$rel" -v nr="$row" '
+    function rowpath(s,   a, x) { split(s, a, "|"); x = a[2]; gsub(/^[ \t]+|[ \t]+$/, "", x); return x }
+    { L[NR] = $0
+      if ($0 ~ /^\|/) { last = NR; if (rowpath($0) == p) hit = NR } }
+    END {
+      for (i = 1; i <= NR; i++) {
+        if (i == hit) print nr; else print L[i]
+        if (hit == "" && i == last) print nr
+      }
+    }' "$m" > "$m.new"
+  mv -f "$m.new" "$m"
+}
+
+# push_bin GPATH -- pushes the two committed paths; skipped with WK_BIN_NO_PUSH=1.
+push_bin() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "push_bin" || true
+  local gpath="$1" wkp="${WKAPPBOT_DIR:-$(dirname "$REPO")/WKAppBot}/bin/wkpush.sh"
+  if [ "${WK_BIN_NO_PUSH:-0}" = 1 ]; then
+    echo "push skipped: WK_BIN_NO_PUSH=1"
+    return 0
+  fi
+  if [ -f "$wkp" ]; then
+    run bash "$wkp" -C "$REPO" -m "$gpath" bin/MANIFEST.md
+  else
+    run git -C "$REPO" push origin HEAD:main
+  fi
+}
+
+publish() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "publish" || true
+  local src plat="" base rel gpath mode="copy" stored sha bytes v="" ver desc newrow dest msg
+  src="${1:-}"
+  [ -n "$src" ] || die "publish: SRC required"
+  shift
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --platform) plat="${2:-}"; [ -n "$plat" ] || die "--platform needs a value"; shift 2 ;;
+      --dry-run) WK_DRY=1; shift ;;
+      *) die "publish: unknown argument: $1" ;;
+    esac
+  done
+  [ -n "$plat" ] || plat="$(platform_detect)"
+  [ -f "$src" ] || die "publish: no such file: $src"
+  base="$(basename "$src")"
+  rel="$plat/$base"
+  if [ "$plat" = win-x64 ]; then
+    case "$base" in
+      *core*.exe) rel="$plat/wkappbot-core.exe.xz"; mode="xz" ;;
+    esac
+  fi
+  gpath="bin/$rel"
+  # Scratch copy only: the repo is touched by run() lines alone, so --dry-run changes nothing.
+  stored="$WK_TMP/stored"
+  if [ "$mode" = xz ]; then xz -9e -T0 -c "$src" > "$stored"; else cp "$src" "$stored"; fi
+  sha="$(sha_of "$stored")"
+  bytes="$(wc -c < "$stored" | tr -d ' ')"
+  # A Windows core is never executed here; every other SRC reports its own version line.
+  if [ "$mode" = copy ]; then
+    v="$("$src" --version 2>/dev/null | head -n 1 || true)"
+  fi
+  if [ -n "$v" ]; then v="${v#wkappbot }"; v="${v//|/}"; fi
+  ver="$(manifest_field "$rel" 4 || true)"
+  if [ -n "$v" ]; then ver="$v"; fi
+  [ -n "$ver" ] || ver="unknown"
+  desc="$(manifest_field "$rel" 3 || true)"
+  [ -n "$desc" ] || desc="$plat"
+  newrow="| $rel | $desc | $ver | $bytes | $sha |"
+  dest="$REPO/$gpath"
+  run mkdir -p "$(dirname "$dest")"
+  run cp "$stored" "$dest"
+  if [ "$plat" != win-x64 ]; then run chmod 755 "$dest"; fi
+  rewrite_manifest "$rel" "$newrow"
+  msg="bin: publish $plat binary ${sha:0:12}"
+  run git -C "$REPO" add -- "$gpath" bin/MANIFEST.md
+  if [ "$plat" != win-x64 ]; then run git -C "$REPO" update-index --chmod=+x -- "$gpath"; fi
+  run git -C "$REPO" commit -m "$msg" -- "$gpath" bin/MANIFEST.md
+  push_bin "$gpath"
+}
+
+usage() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "usage" || true
+  cat <<'EOF'
+usage: wk-bin-acquire.sh acquire [--dest PATH] [--dry-run] [--offline]
+       wk-bin-acquire.sh publish SRC [--platform P] [--dry-run]
+EOF
+}
+
+main() {
+  command -v wk_stopwatch_lap >/dev/null 2>&1 && wk_stopwatch_lap "main" || true
+  local verb="${1:-}"
+  WK_TMP="$(mktemp -d)"
+  trap 'rm -rf "$WK_TMP"' EXIT
+  if [ $# -gt 0 ]; then shift; fi
+  case "$verb" in
+    acquire) acquire "$@" ;;
+    publish) publish "$@" ;;
+    -h|--help) usage ;;
+    *) usage; die "unknown verb: '$verb' (acquire|publish)" ;;
+  esac
+}
+
+main "$@"

package/opencode.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["__WK_PLUGIN_URL__", { "kihDir": "__WK_KIH_DIR__" }]
+  ],
+  "permission": {
+    "edit": "ask",
+    "webfetch": "ask",
+    "bash": {
+      "*": "ask",
+      "ls*": "allow",
+      "pwd": "allow",
+      "git status*": "allow",
+      "git diff*": "allow",
+      "git log*": "allow"
+    }
+  },
+  "provider": {
+    "qwen-inhouse": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "In-house Qwen (OpenAI-compatible)",
+      "options": {
+        "baseURL": "{env:QWEN_BASE_URL}",
+        "apiKey": "{env:QWEN_API_KEY}"
+      },
+      "models": {
+        "qwen3-coder": { "name": "Qwen3 Coder (in-house)" }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "wkappbot-code",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "wkappbot-code -- Wisdom Kernel: the pinned OpenCode bridge plus the kih harness plugin, the wkappbot core, the web harness and the latest public skills in one install",
+  "type": "module",
+  "bin": {
+    "wkappbot-code": "bin/wkappbot-code.js",
+    "wk-appbot-code": "bin/wkappbot-code.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "plugin/",
+    "opencode.json",
+    "install.sh",
+    "README.md"
+  ],
+  "wkAppbotCode": {
+    "opencodeVersion": "1.19.5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiexpert/wkappbot-sdk.git"
+  },
+  "homepage": "https://github.com/kiexpert/wkappbot-sdk",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/wisdom-kernel.js

@@ -0,0 +1,174 @@
+// wkappbot-code -- Wisdom Kernel: the one kih plugin for OpenCode (pinned: opencode-ai 1.19.5).
+// OpenCode is the BRIDGE (model <-> tools); kih is the HARNESS riding on it. This file only maps
+// OpenCode plugin events onto the existing kih hook launcher, .claude/hooks/wkharness-run.sh:
+//   tool.execute.before -> "pre"           (exit 2 = refuse: throw with the hook stderr as the reason)
+//   tool.execute.after  -> "post"          (fail-open, never changes the tool result)
+//   event session.idle  -> "stop-archive"  (archive only, fail-open, no verdict)
+// Fail direction matches Claude Code: only a hook VERDICT refuses; a plugin error, a missing hook or a
+// hung hook (killed at PRE_TIMEOUT_MS) lets the call through.
+// API verified 2026-11-05 from @opencode-ai/plugin 1.19.5 dist/index.d.ts (interface Hooks) and
+// @opencode-ai/sdk 1.19.5 dist/gen/types.gen.d.ts:413 (EventSessionIdle). Spec:
+// wkappbot skill read agent-harness-landscape-2026-howto
+// KNOWN GAP: no transcript_path is sent (OpenCode keeps sessions in its own store), so kih gates that
+// resolve the model or read the transcript see an unknown model and fall back to their defaults.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// OpenCode tool id -> Claude tool name the kih guards already know.
+export const TOOL_MAP = {
+  bash: "Bash", edit: "Edit", write: "Write", read: "Read",
+  glob: "Glob", grep: "Grep", list: "LS", patch: "Edit", multiedit: "MultiEdit",
+  webfetch: "WebFetch", websearch: "WebSearch", task: "Agent", todowrite: "TodoWrite",
+};
+
+// pre arm budget: a hung hook is killed and the call fails OPEN, like a Claude hook timeout.
+export const PRE_TIMEOUT_MS = Number(process.env.WK_APPBOT_PRE_TIMEOUT_MS || 60000);
+
+// OpenCode args (camelCase) -> Claude tool_input (snake_case) for the tools the guards inspect.
+export function toClaudeInput(tool, args) {
+  const a = args || {};
+  switch (tool) {
+    case "bash": {
+      const o = { command: a.command ?? "" };
+      if (a.description !== undefined) o.description = a.description;
+      if (a.timeout !== undefined) o.timeout = a.timeout;
+      return o;
+    }
+    case "edit":
+      return { file_path: a.filePath ?? a.file_path, old_string: a.oldString ?? a.old_string,
+               new_string: a.newString ?? a.new_string, replace_all: a.replaceAll ?? a.replace_all ?? false };
+    case "write":
+      return { file_path: a.filePath ?? a.file_path, content: a.content ?? "" };
+    case "read": {
+      const o = { file_path: a.filePath ?? a.file_path };
+      if (a.offset !== undefined) o.offset = a.offset;
+      if (a.limit !== undefined) o.limit = a.limit;
+      return o;
+    }
+    default: {
+      const o = { ...a };
+      if (o.filePath !== undefined && o.file_path === undefined) o.file_path = o.filePath;
+      return o;
+    }
+  }
+}
+
+export function claudeToolName(tool) {
+  return TOOL_MAP[tool] || tool;
+}
+
+// The Claude-shaped hook payload for one OpenCode tool call.
+export function buildPreToolUsePayload(input, args, cwd) {
+  return {
+    hook_event_name: "PreToolUse",
+    session_id: input.sessionID,
+    cwd: (args && args.workdir) || cwd,
+    tool_name: claudeToolName(input.tool),
+    tool_input: toClaudeInput(input.tool, args),
+    tool_use_id: input.callID,
+    agent_family: "opencode",
+  };
+}
+
+export function buildPostToolUsePayload(input, output, cwd) {
+  const p = buildPreToolUsePayload(input, input.args, cwd);
+  p.hook_event_name = "PostToolUse";
+  p.tool_response = { output: output && output.output, title: output && output.title };
+  return p;
+}
+
+// kih root: WK_KIH_DIR, else the checkout this file sits in (wkappbot-code/plugin -> ../..).
+export function resolveKihDir() {
+  if (process.env.WK_KIH_DIR) return process.env.WK_KIH_DIR;
+  try {
+    const up = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    if (existsSync(join(up, ".claude", "hooks", "wkharness-run.sh"))) return up;
+  } catch {}
+  return "";
+}
+
+// Pipe JSON into "wkharness-run.sh <arm>"; resolves {code, stdout, stderr}. Never rejects.
+// No hook found = fail-open (code 0, skipped) so a missing kih never bricks OpenCode.
+export function runHook(arm, payload, opts = {}) {
+  const kih = opts.kihDir ?? resolveKihDir();
+  const hook = opts.hook || process.env.WK_APPBOT_HOOK || (kih && join(kih, ".claude", "hooks", "wkharness-run.sh"));
+  return new Promise((done) => {
+    let settled = false;
+    const finish = (r) => { if (!settled) { settled = true; if (timer) clearTimeout(timer); done(r); } };
+    let timer = null, out = "", err = "", child;
+    if (!hook || !existsSync(hook)) return finish({ code: 0, stdout: "", stderr: "", skipped: true });
+    let body;
+    try { body = JSON.stringify(payload); } catch (e) { return finish({ code: 0, stdout: "", stderr: String(e), skipped: true }); }
+    try {
+      child = spawn("bash", [hook, arm], {
+        env: { ...process.env, ...(kih ? { CLAUDE_PROJECT_DIR: kih } : {}) },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch (e) {
+      return finish({ code: 0, stdout: "", stderr: String(e), skipped: true });
+    }
+    if (opts.timeoutMs) {
+      timer = setTimeout(() => {
+        try { child.kill("SIGKILL"); } catch {}
+        finish({ code: 0, stdout: out, stderr: err, timedOut: true });
+      }, opts.timeoutMs);
+    }
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", (e) => finish({ code: 0, stdout: out, stderr: err + String(e), skipped: true }));
+    child.on("close", (code) => finish({ code: code ?? 0, stdout: out, stderr: err }));
+    child.stdin.on("error", () => {});
+    child.stdin.end(body);
+  });
+}
+
+// Claude contract: exit 2 refuses; so does a stdout JSON deny/block verdict.
+export function isRefusal(r) {
+  if (r.timedOut || r.skipped) return false;
+  if (r.code === 2) return true;
+  try {
+    const j = JSON.parse(r.stdout);
+    return (j.hookSpecificOutput && j.hookSpecificOutput.permissionDecision === "deny") || j.decision === "block";
+  } catch { return false; }
+}
+
+// A stdout deny JSON names its own reason; stderr then may hold only warn lines (wkharness-run.sh wk_pre_emit).
+export function refusalReason(r) {
+  try {
+    const j = JSON.parse(r.stdout);
+    const why = (j.hookSpecificOutput && j.hookSpecificOutput.permissionDecisionReason) || j.reason;
+    if (why) return why;
+  } catch {}
+  return (r.stderr || "").trim() || (r.stdout || "").trim() || "refused by the kih harness";
+}
+
+// options = the second slot of the opencode.json plugin entry: ["file://.../wisdom-kernel.js", { "kihDir": "..." }].
+// install.sh fills kihDir, because the installed copy no longer sits inside the kih checkout.
+export const WisdomKernel = async (ctx = {}, options = {}) => {
+  const cwd = ctx.directory || ctx.worktree || process.cwd();
+  const k = (options && options.kihDir) || undefined;
+  return {
+    "tool.execute.before": async (input, output) => {
+      let r;
+      try {
+        r = await runHook("pre", buildPreToolUsePayload(input || {}, output && output.args, cwd), { kihDir: k, timeoutMs: PRE_TIMEOUT_MS });
+      } catch { return; } // a plugin bug never refuses a call
+      if (isRefusal(r)) throw new Error("[wisdom-kernel] " + refusalReason(r));
+    },
+    "tool.execute.after": async (input, output) => {
+      try { await runHook("post", buildPostToolUsePayload(input || {}, output, cwd), { kihDir: k, timeoutMs: 30000 }); } catch {}
+    },
+    event: async (arg) => {
+      try {
+        const event = arg && arg.event;
+        if (!event || event.type !== "session.idle") return;
+        const sid = event.properties && event.properties.sessionID;
+        await runHook("stop-archive", { hook_event_name: "Stop", session_id: sid, cwd, agent_family: "opencode" }, { kihDir: k, timeoutMs: 30000 });
+      } catch {}
+    },
+  };
+};
+
+export default WisdomKernel;