@0xgeorgemathew/zcode 0.4.0 → 0.4.4

package/README.md

@@ -1,31 +1,26 @@
-<div align="center">
-
-# ⚡ zcode
-
-**The execution engine for orchestrator agents.**
-
-Hand it a scoped task. It implements, verifies with *your* checks, and hands back proof.
-
-[![npm](https://img.shields.io/npm/v/@0xgeorgemathew/zcode.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/@0xgeorgemathew/zcode)
-[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)](package.json)
-[![deps](https://img.shields.io/badge/dependencies-0-brightgreen)](package.json)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-
-`GLM-5.3-Flash` · effort `max` by default · `GLM-5.3` on demand
-
-</div>
-
-&nbsp;
-
-Opus, Sonnet, GPT, or any agent with a shell delegates implementation to zcode. The orchestrator keeps product decisions, design direction, and coordination. zcode owns execution inside the scope it is given, and reports back what changed, what was checked, what failed, and what is still unverified.
-
-|  |  |
-|---|---|
-| 🧾 **Contracts, not prompts** | objective, scope, constraints, binding design decisions, acceptance criteria, checks |
-| ✅ **Evidence over claims** | zcode runs your checks itself and repairs failures in bounded turns; the model's report is only a claim |
-| 🧵 **Real sessions** | stable ids, detach, `status`, `wait`, `resume`, `cancel`; interrupted sessions are resumable |
-| 🧱 **Safe parallelism** | `--owns` leases per workspace; overlapping scopes are refused, out-of-scope edits are flagged |
-| 🤖 **Machine-first output** | one stable `zcode.result/1` JSON line; clean, colour-free text when not on a TTY |
+<p align="center">
+  <img src="https://raw.githubusercontent.com/0xgeorgemathew/zcode/main/docs/assets/hero.svg" alt="A zcode work order: the contract on the left, the handback with changed files, a passing check and a COMPLETED stamp on the right" width="960">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@0xgeorgemathew/zcode"><img src="https://img.shields.io/npm/v/@0xgeorgemathew/zcode.svg?color=1C3F95&label=npm" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-1C3F95" alt="node 20 or later">
+  <img src="https://img.shields.io/badge/dependencies-0-1C3F95" alt="zero dependencies">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-1C3F95" alt="MIT license"></a>
+</p>
+
+zcode is a command-line executor for orchestrator agents. Claude Code, Codex, or any agent with a shell hands it a task contract. zcode implements the task with GLM-5.3-Flash, runs your checks itself, and returns a handback that lists the changed files, the check results, and anything it could not verify.
+
+The orchestrator keeps product decisions, design direction, and coordination. zcode works only inside the scope it is given.
+
+<table>
+<tr><td><b>Contract in</b></td><td>Objective, scope, constraints, binding design decisions, acceptance criteria, owned paths and checks. Only the objective is required.</td></tr>
+<tr><td><b>Checks run by zcode</b></td><td>zcode runs each <code>--check</code> after the work. A failing check sends its output back to the model for up to 2 repair turns.</td></tr>
+<tr><td><b>Status from evidence</b></td><td><code>completed</code> requires passing checks and no edits outside <code>--owns</code>. The model's own report is kept as a claim.</td></tr>
+<tr><td><b>Sessions</b></td><td>Stable ids, <code>--detach</code>, <code>status</code>, <code>wait</code>, <code>resume</code>, <code>cancel</code>. A session whose process died shows as interrupted and can be resumed.</td></tr>
+<tr><td><b>Parallel work</b></td><td>Two sessions with overlapping <code>--owns</code> in one repo are refused with exit 7.</td></tr>
+<tr><td><b>Output</b></td><td>One <code>zcode.result/1</code> JSON line with <code>--json</code>. No colour codes when stdout is not a terminal.</td></tr>
+</table>
 
 &nbsp;
 
@@ -33,35 +28,44 @@ Opus, Sonnet, GPT, or any agent with a shell delegates implementation to zcode.
 
 ```sh
 npm install -g @0xgeorgemathew/zcode
-echo "$ZAI_API_KEY" | zcode login    # store your Z.AI key (mode 600, never printed)
-zcode doctor                         # check engine, isolation, key
+echo "$ZAI_API_KEY" | zcode login    # stores your Z.AI key with mode 600; zcode never prints it
+zcode doctor                         # checks the engine, isolation and key
+zcode skills install                 # optional: teach Claude Code and Codex to delegate to zcode
 
 zcode task --check "npm test" "Fix the off-by-one in src/paginate.ts"
 ```
 
-Needs node 20+ for the CLI (26 recommended for the engine child) and the ZCode engine on the machine. Today that is the copy bundled with the ZCode desktop app, which is resolved automatically.
+The CLI needs node 20 or later. The engine child runs best on node 26. zcode also needs the ZCode engine, which today ships inside the ZCode desktop app; zcode finds it automatically.
+
+The package ships skills that teach Claude Code and Codex how to delegate to zcode. Install them with one command:
 
-Orchestrator skills for Claude Code and Codex ship in [`skills/`](skills/README.md).
+```sh
+zcode skills install          # both; or: zcode skills install claude | codex
+zcode skills                  # show what is installed and where
+zcode skills uninstall        # remove them
+```
+
+The Claude Code skill goes to `~/.claude/skills/zcode` and the Codex skill to `${CODEX_HOME:-~/.codex}/skills/zcode`. The package runs no install scripts. Details are in [`skills/`](skills/README.md).
 
 &nbsp;
 
 ## Models and effort
 
-Every command runs on **GLM-5.3-Flash at effort `max`** unless you say otherwise.
+Every command runs on GLM-5.3-Flash at effort `max` unless you pass a flag.
 
-| | flag | values | default |
+| setting | flag | values | default |
 |---|---|---|---|
-| 🧠 model | `--model` | `glm-5.3-flash` (aliases `flash`, `5.3-flash`, `53f`) · `glm-5.3` (aliases `5.3`, `53`) | `glm-5.3-flash` |
-| 🎚️ effort | `--effort` | `low` · `medium` · `high` · `xhigh` · `max` | `max` |
+| model | `--model` | `glm-5.3-flash` (aliases `flash`, `5.3-flash`, `53f`), `glm-5.3` (aliases `5.3`, `53`) | `glm-5.3-flash` |
+| effort | `--effort` | `low`, `medium`, `high`, `xhigh`, `max` | `max` |
 
 ```sh
-zcode task "…"                                   # GLM-5.3-Flash, effort max
-zcode task --effort high "…"                     # Flash, lighter reasoning
-zcode task --model glm-5.3 "…"                   # full GLM-5.3, effort max
-zcode task --model glm-5.3 --effort medium "…"   # full GLM-5.3, medium effort
+zcode task "..."                                   # GLM-5.3-Flash, effort max
+zcode task --effort high "..."                     # Flash with less reasoning
+zcode task --model glm-5.3 "..."                   # GLM-5.3, effort max
+zcode task --model glm-5.3 --effort medium "..."   # GLM-5.3, effort medium
 ```
 
-A task contract can also set `"model"` and `"effort"`; flags win over the contract. A resumed session keeps the model and effort it started with unless you pass the flags again.
+A task contract can set `"model"` and `"effort"`. Flags override the contract. A resumed session keeps its original model and effort unless you pass the flags again.
 
 &nbsp;
 
@@ -231,7 +235,8 @@ Inside `zcode task`, subagents are optional. The executor decides when to use th
 | `--timeout-ms` | all turns; wait | run 600000, task 1800000 | the whole invocation incl. checks and repairs |
 | `--session` | run | | 0.3 compat: continue by zcode id or engine `sess_` id |
 | `--profile` | agent | `general-purpose` | subagent profile |
-| `--mcp` / `--mcp-inherit` / `--mcp-list` | run, task, agent | hermetic | MCP servers (inline JSON or `@file`) |
+| `--mcp` / `--mcp-inherit` / `--mcp-list` | run, task, agent | hermetic, plus the desktop's `playwright` | MCP servers (inline JSON or `@file`) |
+| `--no-browser` | run, task, agent | off | Drop the desktop's `playwright` MCP server |
 | `--skills` / `--no-skills` | run, task, agent | desktop skills | add skills; or run with none |
 | `--json`, `--quiet` | all | | see Machine interface |
 | `--thinking` / `--no-thinking` | turns | run on, task off | mirror reasoning to stderr |
@@ -285,4 +290,6 @@ npm run accept:53
 
 Live tests load the key from the repo `.env`, which is never committed or shipped. The design record and the wire-protocol facts pinned live are in `DESIGN.md` (§17 covers the 0.4 executor redesign) and `docs/BUILD-REPORT.md`.
 
-MIT license.
+## License
+
+MIT. Source and issues: [github.com/0xgeorgemathew/zcode](https://github.com/0xgeorgemathew/zcode).

package/bin/zcode.js

@@ -14,6 +14,8 @@ const USAGE = `usage:
   zcode cancel <id> [--json]           stop a running session
   zcode login                          read API key from stdin → credentials
   zcode doctor [--json]                engine + isolation + key report
+  zcode skills [install|uninstall] [claude|codex]
+                                       install the orchestrator skills (default: status)
 
 session:
   --id <id>             name the session (letters, digits, . _ -); default zc-<random>.
@@ -43,6 +45,7 @@ execution:
   --profile <name>      subagent profile (agent command; default general-purpose)
   --mcp <json|@f>       add MCP servers (repeatable); hermetic by default
   --mcp-inherit         also inherit the desktop's enabled MCP servers
+  --no-browser          drop the desktop's playwright MCP server (on by default)
   --mcp-list            print the effective MCP server set as JSON and exit
   --skills <dir>        add skills (repeatable): one skill dir or a root of them
   --no-skills           empty skill set
@@ -94,9 +97,9 @@ function parseMcpSpec(value) {
   return parsed;
 }
 
-const COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'status', 'list', 'wait', 'cancel', 'login', 'doctor', '__exec']);
+const COMMANDS = new Set(['run', 'task', 'agent', 'resume', 'status', 'list', 'wait', 'cancel', 'login', 'doctor', 'skills', '__exec']);
 const TASK_ONLY = new Set(['task', 'accept', 'check', 'file', 'context', 'maxRepairs', 'checkTimeoutMs']);
-const START_ONLY = new Set(['id', 'label', 'owns', 'allowOverlap', 'mcpSpecs', 'mcpInherit', 'skillsDirs', 'noSkills', 'profile', 'cwd']);
+const START_ONLY = new Set(['id', 'label', 'owns', 'allowOverlap', 'mcpSpecs', 'mcpInherit', 'noBrowser', 'skillsDirs', 'noSkills', 'profile', 'cwd']);
 
 function parseArgv(argv) {
   const out = {
@@ -127,6 +130,7 @@ function parseArgv(argv) {
       checkTimeoutMs: undefined,
       mcpSpecs: [],
       mcpInherit: false,
+      noBrowser: false,
       mcpList: false,
       skillsDirs: [],
       noSkills: false,
@@ -148,7 +152,7 @@ function parseArgv(argv) {
   ]);
   const boolFlags = new Map([
     ['--json', ['json', true]], ['--fresh', ['fresh', true]], ['--mcp-inherit', ['mcpInherit', true]],
-    ['--mcp-list', ['mcpList', true]], ['--no-skills', ['noSkills', true]],
+    ['--mcp-list', ['mcpList', true]], ['--no-skills', ['noSkills', true]], ['--no-browser', ['noBrowser', true]],
     ['--include-reasoning', ['includeReasoning', true]], ['--quiet', ['quiet', true]],
     ['--detach', ['detach', true]], ['--allow-overlap', ['allowOverlap', true]],
     ['--thinking', ['thinking', true]], ['--no-thinking', ['thinking', false]], ['--stream', ['stream', true]],
@@ -265,6 +269,8 @@ async function main() {
       return require('../lib/commands/login.js')(parsed);
     case 'doctor':
       return require('../lib/commands/doctor.js')(parsed);
+    case 'skills':
+      return require('../lib/commands/skills.js')(parsed);
     default:
       return fail(2, `unknown command "${parsed.command}".\n${USAGE}`);
   }

package/lib/appserver.js

@@ -150,6 +150,17 @@ class AppServerClient {
       if (this.onUserInputRequest) this.onUserInputRequest(frame);
       return;
     }
+    if (method === 'interaction/browserList') {
+      // The desktop app answers with its built-in browser panes; the CLI has
+      // none. An empty list lets the agent fall back to the user's own tools
+      // (Playwright, MCP browsers) instead of failing on a policy error.
+      reply({ browsers: [] });
+      return;
+    }
+    if (method === 'interaction/browserExecute') {
+      replyError(-32000, 'zcode: no built-in browser in the CLI; use Playwright or a browser MCP server');
+      return;
+    }
     // Everything else — incl. interaction/requestOfficialMcpAuthHeaders,
     // proven non-fatal with -32601 — gets method-not-found and the run
     // continues.
@@ -220,8 +231,12 @@ function workspaceKeyFor(workspacePath) {
 // turn always sees the caller's --mcp servers. Inherited servers are
 // best-effort and never block the send.
 async function waitForMcp(client, { workspacePath, required, timeoutMs = 20000, onEvent = () => {} }) {
-  if (!required || required.length === 0) return;
   const ws = { workspace: { workspacePath, workspaceKey: workspaceKeyFor(workspacePath) } };
+  if (!required || required.length === 0) {
+    // Still start inherited servers (the browser server); never block on them.
+    client.request('mcp/list', { ...ws, mode: 'connect' }, { timeoutMs: 15000 }).catch(() => {});
+    return;
+  }
   try {
     await client.request('mcp/list', { ...ws, mode: 'connect' }, { timeoutMs: 15000 });
   } catch {

package/lib/commands/exec.js

@@ -77,6 +77,7 @@ function buildInvocation(parsed) {
     acceptanceDeclared: false,
     mcpSpecs: flags.mcpSpecs,
     mcpInherit: flags.mcpInherit,
+    noBrowser: flags.noBrowser,
     skillsDirs: flags.skillsDirs.map((d) => path.resolve(d)),
     noSkills: flags.noSkills,
     profile: flags.profile,

package/lib/commands/mcp-list.js

@@ -6,7 +6,7 @@ const { effectiveMcpServers } = require('../isolation.js');
 
 module.exports = async function mcpList(parsed) {
   const { flags } = parsed;
-  const servers = effectiveMcpServers({ inherit: flags.mcpInherit, mcpSpecs: flags.mcpSpecs });
+  const servers = effectiveMcpServers({ inherit: flags.mcpInherit, browser: !flags.noBrowser, mcpSpecs: flags.mcpSpecs });
   process.stdout.write(JSON.stringify({ type: 'mcp', servers }) + '\n');
   process.exit(0);
 };

package/lib/commands/skills.js

@@ -0,0 +1,39 @@
+'use strict';
+// zcode skills [status|install|uninstall] [claude|codex]
+// Copies the orchestrator skills shipped in this package into Claude Code
+// and Codex. Nothing runs at npm install time; this command is the installer.
+const { installSkills, uninstallSkills, skillStatus, PLATFORMS } = require('../skills.js');
+
+const ACTIONS = new Set(['status', 'install', 'uninstall']);
+
+module.exports = function skills({ prompts, flags }) {
+  const [action = 'status', ...platforms] = prompts;
+  const fail = (msg) => {
+    process.stderr.write(`zcode: ${msg}\nusage: zcode skills [status|install|uninstall] [claude|codex]\n`);
+    process.exit(2);
+  };
+  if (!ACTIONS.has(action)) fail(`unknown skills action "${action}".`);
+  for (const p of platforms) if (!PLATFORMS.includes(p)) fail(`unknown platform "${p}" (claude | codex).`);
+
+  const view = (t) => ({ platform: t.platform, name: t.name, path: t.to, ...(t.installed !== undefined && { installed: t.installed }) });
+  let rows;
+  if (action === 'install') rows = installSkills({ platforms });
+  else if (action === 'uninstall') rows = uninstallSkills({ platforms });
+  else rows = skillStatus().filter((t) => !platforms.length || platforms.includes(t.platform));
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ action, skills: rows.map(view) }, null, 2) + '\n');
+    return;
+  }
+  if (rows.length === 0) {
+    process.stdout.write('zcode: nothing to uninstall\n');
+    return;
+  }
+  for (const t of rows) {
+    const what = action === 'install' ? 'installed' : action === 'uninstall' ? 'removed' : t.installed ? 'installed' : 'not installed';
+    process.stdout.write(`${t.name.padEnd(12)} ${what.padEnd(14)} ${t.to}\n`);
+  }
+  if (action === 'status' && rows.some((t) => !t.installed)) {
+    process.stdout.write('\nrun `zcode skills install` to install them\n');
+  }
+};

package/lib/executor.js

@@ -52,7 +52,7 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // Settings a session keeps across invocations (stored as invocation.json).
 const SETTING_KEYS = [
   'kind', 'label', 'cwd', 'model', 'effort', 'timeoutMs', 'maxRepairs', 'checkTimeoutMs',
-  'checks', 'owns', 'ownsDisplay', 'acceptanceDeclared', 'mcpSpecs', 'mcpInherit',
+  'checks', 'owns', 'ownsDisplay', 'acceptanceDeclared', 'mcpSpecs', 'mcpInherit', 'noBrowser',
   'skillsDirs', 'noSkills', 'profile', 'includeReasoning', 'allowOverlap', 'stream',
 ];
 
@@ -338,6 +338,7 @@ async function execute(inv, opts = {}) {
       live: liveDir(env),
       mcpSpecs: inv.mcpSpecs || [],
       mcpInherit: inv.mcpInherit,
+      browser: !inv.noBrowser,
       skillsDirs: inv.skillsDirs || [],
       noSkills: inv.noSkills,
     });

package/lib/isolation.js

@@ -142,8 +142,18 @@ function liveMcpServers(live = LIVE_ZCODE) {
 // base (specs still win by name). Hermetic default is deliberate: the
 // desktop set includes OAuth servers that can never complete headless and
 // stall the engine's connect pool.
-function effectiveMcpServers({ inherit = false, mcpSpecs = [], live = LIVE_ZCODE } = {}) {
-  const servers = inherit ? liveMcpServers(live) : {};
+// Exception: the desktop's local browser server (stdio, no OAuth) is always
+// inherited, so browser prompts open the same Playwright window the desktop
+// opens. --no-browser drops it.
+const BROWSER_SERVERS = ['playwright'];
+
+function effectiveMcpServers({ inherit = false, browser = true, mcpSpecs = [], live = LIVE_ZCODE } = {}) {
+  const liveSet = liveMcpServers(live);
+  const servers = inherit ? liveSet : {};
+  for (const name of BROWSER_SERVERS) {
+    if (!browser) delete servers[name];
+    else if (liveSet[name]) servers[name] = liveSet[name];
+  }
   for (const spec of mcpSpecs) {
     for (const [name, def] of Object.entries(spec)) servers[name] = def;
   }
@@ -200,6 +210,11 @@ function isDanglingLink(p) {
 // sources + this invocation's flags; engine state under the HOME (cli/db,
 // cli/agents, cli/rollout, logs, memories) is never touched, so a session
 // stays resumable across invocations. Returns facts for reporting.
+// Desktop skills that drive the app's own UI (the built-in browser pane).
+// The CLI cannot serve them, and loading one steers the agent away from
+// Playwright into a dead end.
+const HOST_ONLY_SKILLS = new Set(['control-browser']);
+
 function buildEngineHome({
   home,
   root,
@@ -207,6 +222,7 @@ function buildEngineHome({
   live = LIVE_ZCODE,
   mcpSpecs = [],
   mcpInherit = false,
+  browser = true,
   skillsDirs = [],
   noSkills = false,
 }) {
@@ -237,7 +253,7 @@ function buildEngineHome({
     zai.options = zai.options || {};
     zai.options.apiKey = key;
   }
-  const servers = effectiveMcpServers({ inherit: mcpInherit, mcpSpecs, live });
+  const servers = effectiveMcpServers({ inherit: mcpInherit, browser, mcpSpecs, live });
   cfg.mcp = { ...(cfg.mcp || {}), servers };
   writeJson600(path.join(cliDir, 'config.json'), cfg);
 
@@ -268,6 +284,7 @@ function buildEngineHome({
     for (const entry of listDir(liveSkills)) {
       if (!entry.isDirectory()) continue;
       if (!fs.existsSync(path.join(liveSkills, entry.name, 'SKILL.md'))) continue;
+      if (HOST_ONLY_SKILLS.has(entry.name)) continue;
       fs.cpSync(path.join(liveSkills, entry.name), path.join(skillsDir, entry.name), {
         recursive: true,
       });
@@ -345,6 +362,18 @@ function migrateRoot(env = process.env) {
 // config, and the uncontrolled overrides deleted. cwd is set by the caller.
 function engineEnv({ home, builtinProviderConfig, parentEnv = process.env }) {
   const childEnv = { ...parentEnv };
+  const realHome = parentEnv.HOME || os.homedir();
+  // The scratch HOME hides the user's tool caches. Point Playwright and npm
+  // back at the real ones so installed browsers and packages are found.
+  if (!childEnv.PLAYWRIGHT_BROWSERS_PATH) {
+    const cache = process.platform === 'darwin'
+      ? path.join(realHome, 'Library', 'Caches', 'ms-playwright')
+      : path.join(realHome, '.cache', 'ms-playwright');
+    if (fs.existsSync(cache)) childEnv.PLAYWRIGHT_BROWSERS_PATH = cache;
+  }
+  if (!childEnv.npm_config_cache && !childEnv.NPM_CONFIG_CACHE) {
+    childEnv.npm_config_cache = path.join(realHome, '.npm');
+  }
   childEnv.HOME = home;
   childEnv.ZCODE_BUILTIN_PROVIDER_CONFIG_FILE = builtinProviderConfig;
   for (const name of [

package/lib/skills.js

@@ -0,0 +1,64 @@
+'use strict';
+// The orchestrator skills shipped in the package, and where `zcode skills`
+// installs them:
+//
+//   skills/claude-code/zcode  ->  ~/.claude/skills/zcode
+//   skills/codex/zcode        ->  ${CODEX_HOME:-~/.codex}/skills/zcode
+//
+// Only the zcode skill directory is ever replaced or removed.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const pkgRoot = path.join(__dirname, '..');
+const PLATFORMS = ['claude', 'codex'];
+
+function targets(env = process.env) {
+  const home = env.HOME || os.homedir();
+  return [
+    {
+      platform: 'claude',
+      name: 'Claude Code',
+      from: path.join(pkgRoot, 'skills', 'claude-code', 'zcode'),
+      to: path.join(home, '.claude', 'skills', 'zcode'),
+    },
+    {
+      platform: 'codex',
+      name: 'Codex',
+      from: path.join(pkgRoot, 'skills', 'codex', 'zcode'),
+      to: path.join(env.CODEX_HOME || path.join(home, '.codex'), 'skills', 'zcode'),
+    },
+  ];
+}
+
+function select(platforms, env) {
+  const want = platforms && platforms.length ? new Set(platforms) : new Set(PLATFORMS);
+  return targets(env).filter((t) => want.has(t.platform));
+}
+
+function installSkills({ platforms, env = process.env } = {}) {
+  const done = [];
+  for (const t of select(platforms, env)) {
+    fs.mkdirSync(path.dirname(t.to), { recursive: true });
+    fs.rmSync(t.to, { recursive: true, force: true });
+    fs.cpSync(t.from, t.to, { recursive: true });
+    done.push(t);
+  }
+  return done;
+}
+
+function uninstallSkills({ platforms, env = process.env } = {}) {
+  const done = [];
+  for (const t of select(platforms, env)) {
+    if (!fs.existsSync(t.to)) continue;
+    fs.rmSync(t.to, { recursive: true, force: true });
+    done.push(t);
+  }
+  return done;
+}
+
+function skillStatus({ env = process.env } = {}) {
+  return targets(env).map((t) => ({ ...t, installed: fs.existsSync(path.join(t.to, 'SKILL.md')) }));
+}
+
+module.exports = { installSkills, uninstallSkills, skillStatus, targets, PLATFORMS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xgeorgemathew/zcode",
-  "version": "0.4.0",
+  "version": "0.4.4",
   "description": "Lean GLM-5.3 execution engine for orchestrator agents: task contracts, independent sessions, zcode-run verification, structured handbacks, subagents, MCP, skills. Wraps the ZCode engine. Zero dependencies.",
   "license": "MIT",
   "private": false,
@@ -10,7 +10,9 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@0xgeorgemathew/zcode": "^0.4.0"
+  },
   "files": [
     "bin",
     "lib",
@@ -41,5 +43,13 @@
     "ndjson",
     "orchestrator",
     "executor"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xgeorgemathew/zcode.git"
+  },
+  "homepage": "https://github.com/0xgeorgemathew/zcode#readme",
+  "bugs": {
+    "url": "https://github.com/0xgeorgemathew/zcode/issues"
+  }
 }

package/skills/README.md

@@ -9,7 +9,15 @@ These skills teach an orchestrating agent how to delegate work to zcode, run ses
 
 ## Install
 
-Run these from a checkout of this repo, or from the installed package (`$(npm root -g)/@0xgeorgemathew/zcode`), which ships `skills/`.
+After `npm install -g @0xgeorgemathew/zcode`, install both skills with:
+
+```sh
+zcode skills install          # or: zcode skills install claude | codex
+```
+
+This copies the Claude Code skill to `~/.claude/skills/zcode` and the Codex skill to `${CODEX_HOME:-~/.codex}/skills/zcode`, replacing only an earlier copy of the zcode skill. Run it again after upgrading zcode to refresh them. `zcode skills` shows what is installed, and `zcode skills uninstall` removes them. The package runs no install scripts, so npm never asks to allow one.
+
+To copy them by hand instead, run these from a checkout of this repo, or from the installed package (`$(npm root -g)/@0xgeorgemathew/zcode`), which ships `skills/`.
 
 **Claude Code.** Personal skills, available in every project: