openzoo 0.50.99 → 0.51.0

package/lib/models.js

@@ -305,6 +305,11 @@ export const ANTHROPIC_NATIVE_ALIASES = {
   'claude-opus-4-8': 'anthropic/claude-opus-4.8',
   'claude-opus-4.8': 'anthropic/claude-opus-4.8',
   'claude-fable-5': 'anthropic/claude-fable-5',
+  // Both spellings the catalog serves for 5.1 (`claude-fable-5.1` and the
+  // Anthropic-native `claude-fable-5-1`). Missing here meant Claude Code's
+  // pick of Fable 5.1 fell through as an unknown id.
+  'claude-fable-5.1': 'anthropic/claude-fable-5.1',
+  'claude-fable-5-1': 'anthropic/claude-fable-5.1',
   'claude-haiku-4.5': 'anthropic/claude-haiku-4.5',
 };
 
@@ -336,7 +341,7 @@ export const ALIAS_IDS = [
   'gpt-5', 'gpt-5-mini', 'chatgpt-4o-latest', 'o1', 'o3', 'o3-mini', 'o4-mini',
   'claude-3-5-sonnet-latest', 'claude-sonnet-4-0', 'claude-opus-4-1',
   'claude-opus-5', 'claude-opus-5-fast', 'claude-3-5-opus', 'claude-sonnet-5',
-  'claude-opus-4-8', 'claude-fable-5',
+  'claude-opus-4-8', 'claude-fable-5', 'claude-fable-5.1', 'claude-fable-5-1',
   'gemini-2.5-pro', 'gemini-2.5-flash', 'grok-4', 'grok-3',
   'deepseek-chat', 'deepseek-reasoner', 'qwen-max', 'llama-3.3-70b',
 ];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.50.99",
-  "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
+  "version": "0.51.0",
+  "description": "Local x402-paying proxy + MCP server for openzoo.fun \u2014 point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental. `openzoo build|deploy|serve|hub` transmute a Vercel-shaped app (Next.js / Vite + /api) into a Pinocchio program + asset accounts on Solana mainnet.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
   "files": [
     "bin",
     "lib",
-    "README.md"
+    "README.md",
+    "transmute"
   ],
   "engines": {
     "node": ">=18"
@@ -25,7 +26,9 @@
     "dugite": "^3.2.3",
     "selfsigned": "^5.5.0",
     "viem": "^2.21.0",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "acorn": "^8.14.0",
+    "acorn-walk": "^8.3.4"
   },
   "repository": {
     "type": "git",

package/transmute/README.md

@@ -0,0 +1,352 @@
+# openzoo-transmute
+
+Transmute a Vercel-shaped app — Next.js `pages/api`, app-router `route.ts`, or
+a Vite repo with `api/*.js` — into **(a)** a Rust [Pinocchio](https://github.com/anza-xyz/pinocchio)
+Solana program that hosts the `/api/*` Lambdas as instruction routes and
+**(b)** the static build stored in program-derived accounts; deploy it to
+Solana; serve it through a local gateway that speaks the same routes Vercel
+would.
+
+```
+vercel build  ─►  .vercel/output/{config.json, static/, functions/*.func}
+                                    │
+openzoo build ─►  .zoo-out/.zoo/{crate/ (Rust), manifest.json, deploy/<site>.so, static-plan.json}
+openzoo deploy ─► program id + one asset account per file + /.zoo/manifest.json
+openzoo serve ─►  http://127.0.0.1:4402/  (GET = free simulation, POST = signed transaction)
+```
+
+The whole reverse-engineering — what `vercel build` emits, what the Lambda
+receives from `@vercel/node-bridge`, what Fluid Compute changes, the term-by-term
+mapping, the limits, the cost model and the security notes — is in
+[`docs/VERCEL_TO_SOLANA.md`](docs/VERCEL_TO_SOLANA.md). The patch that mounts
+these commands in `npx openzoo` is [`docs/OPENZOO_CLI_PATCH.md`](docs/OPENZOO_CLI_PATCH.md).
+
+## How it works
+
+* **The Lambda contract becomes instruction data.** Vercel's bridge hands a
+  function `{method, path, headers, body}` and expects `{statusCode, headers,
+  body}`. `lib/wire.js` and `runtime/zoo-host/src/wire.rs` are that pair as
+  bytes: `[tag][route][method][path][query][headers][body]` in, `[status][headers][body]`
+  out via `set_return_data` plus `sol_log_data` chunks.
+* **Each handler becomes a Rust route.** The compiler (`lib/compile/`) lowers
+  the JS subset it accepts onto `zoo_host::{Ctx, Val}` — a JS-semantics dynamic
+  value with `req.query`/`req.body`/`res.json`/`Response.json`/`kv.*`/`process.env`
+  implemented in `runtime/zoo-host/src/{ctx,val,json,kv}.rs`. Anything outside
+  the subset (network, fs, timers, regex, classes…) is reported with `file:line`
+  and the rest of the app still builds.
+* **`static/` becomes asset PDAs.** One rent-exempt account per file, written in
+  900-byte chunks, writes gated by the program's upgrade authority
+  (`runtime/zoo-host/src/assets.rs`). `@vercel/kv` becomes KV PDAs the program
+  discovers by dry run.
+* **Reads are free, writes are transactions.** `GET/HEAD/OPTIONS` run as
+  `simulateTransaction` (no signature, no fee); everything else is a signed
+  transaction paid by the gateway wallet. Without a wallet the gateway answers
+  `402` — the seam where openzoo's x402 flow plugs in.
+
+## Install
+
+```sh
+# from this repository — the package is not on npm yet (`npm view openzoo-transmute` → 404)
+cd openzoo-transmute && npm install --no-audit --no-fund
+node bin/openzoo-transmute.js help        # or: npm link && openzoo-transmute help
+
+# once published: npx openzoo-transmute help
+# through the openzoo CLI once docs/OPENZOO_CLI_PATCH.md is applied:
+npx openzoo build | deploy | serve | inspect
+```
+
+Until it is published, read `npx openzoo-transmute` in the examples below as
+`node <repo>/openzoo-transmute/bin/openzoo-transmute.js` (or the `npm link`ed
+`openzoo-transmute`).
+
+Requirements: Node ≥ 18, and for `build`/`deploy` the Solana toolchain
+(`cargo build-sbf`): `sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"`.
+`build --skip-cargo` works without it (you get the crate and the cost sheet, no `.so`).
+
+## Quickstart
+
+```sh
+cd my-next-app                      # or a Vite repo with api/*.js, or a .vercel/output
+npx openzoo-transmute inspect       # the app in Vercel terms + eligibility report
+npx openzoo-transmute build         # → .zoo-out/.zoo/{crate,manifest.json,deploy/*.so}
+npx openzoo-transmute deploy --cluster devnet
+npx openzoo-transmute serve <programId> --cluster devnet
+open http://127.0.0.1:4402/         # explorer at /.zoo/, manifest at /.zoo/manifest.json
+```
+
+`inspect` prints one line per function with its route, style, runtime,
+`maxDuration`, `memory` and methods, marks each `✓`/`✗` and says why:
+
+```
+functions (2):
+  ✓ /api/hello                       pages        nodejs20.x  10s   1024MB  any
+      pages/api/hello.js  env=GREETING
+  ✓ /api/counter                     app          nodejs20.x  10s   1024MB  POST
+      app/api/counter/route.js  env=GREETING
+```
+
+`deploy` prints the rent sheet before spending anything and refuses mainnet
+without `--yes` (this one was measured on a local validator for the two-route
+sample in [The generated crate](#the-generated-crate), `.so` built with `--arch v3`):
+
+```
+  item                                bytes       SOL
+  program account                        36    0.0011
+  program data (2×.so = 416,672 B)  416,717    2.9012
+  /app.js                                52    0.0013
+  /index.html                            44    0.0012
+  /.zoo/manifest.json (manifest)        939    0.0074
+  rent total                                   2.9123
+  + tx fees (approx.)                          0.0012
+  TOTAL                                        2.9135
+  (rent per http://127.0.0.1:8899)
+```
+
+Then `serve` maps HTTP onto the program:
+
+```
+GET /                        → 200 text/html          (asset PDA, etag, 304 on If-None-Match)
+GET /api/hello?name=zoo&n=21 → 200 {"hello":"zoo","n":42,"greeting":"hi"}   x-zoo-simulated: true, x-zoo-cu: 11067
+POST /api/counter            → 200 {"hits":1}         x-zoo-signature: <tx>, x-zoo-simulated: false, x-zoo-cu: 10634
+POST /api/counter            → 402 payment required   (gateway started without a keypair)
+```
+
+## CLI reference
+
+| command | what it does |
+|---|---|
+| `build [dir] [--out .zoo-out] [--name <crate>] [--arch v0\|v3] [--cluster <c>] [--skip-cargo] [--json]` | read the app (`lib/vercel.js`), transmute (`lib/compile/`), write `<out>/.zoo/{crate/, manifest.json, report.json, static-plan.json, build.json}`, run `cargo build-sbf --arch <arch>` → `.zoo/deploy/<name>.so`, print the cost sheet (`--cluster` only chooses the RPC whose rent parameters price it, default `localnet`; unreachable → the 6.96 SOL/MB rule). Default arch is `v0` (mainnet); `deploy` re-detects the cluster's SBPF version and rebuilds if needed. Exit code 2 when nothing was eligible |
+| `deploy [dir\|outDir] [--cluster mainnet\|devnet\|testnet\|localnet\|<url>] [--keypair <path>] [--yes] [--program <id>] [--concurrency 4] [--skip-assets] [--force] [--json]` | deploy or upgrade the program (keypair kept at `.zoo/program-keypair.json`, so redeploys upgrade in place), upload every static file (unchanged ones skipped by comparing bytes on chain), write `/.zoo/manifest.json`, record `.zoo/deploy.json` |
+| `serve [programId] [--cluster <c>] [--port 4402] [--host 127.0.0.1] [--keypair <path>\|--no-keypair] [--quiet]` | the local gateway; `programId` defaults to the `.zoo/deploy.json` under the current directory (or its `.zoo-out/`). Reads are simulated, writes are signed by the wallet; without a wallet (or with `--no-keypair`) writes answer 402. Without `--cluster`/`OPENZOO_CLUSTER` this command assumes `localnet`, unlike the others |
+| `inspect [dir] [--json]` | the Vercel model (functions, static files, routes, crons) plus the eligibility report |
+| `status <programId> [--cluster <c>] [--json]` | program account, authority, `maxDataLen`, deploy slot, and the on-chain manifest |
+| `help`, `--version` | |
+
+Environment: `OPENZOO_CLUSTER` (default `mainnet` for `deploy`/`status`, `localnet` for `serve`), `OPENZOO_RPC` (mainnet RPC
+URL), `OPENZOO_KEYPAIR` / `OPENZOO_WALLET` (signer path), `OPENZOO_DEBUG=1`
+(stack traces). Signer discovery order (`lib/wallet.js`): `--keypair` →
+`OPENZOO_KEYPAIR` → `OPENZOO_WALLET` or `~/.openzoo/wallet.json` (the openzoo
+burner, `{solana:[64 bytes]}` or a bare `solana-keygen` array) → `~/.config/solana/id.json`.
+
+Gateway responses carry `x-zoo-program`, `x-zoo-route`, `x-zoo-simulated`,
+`x-zoo-cu`, `x-zoo-signature` (writes) and `x-zoo-asset` (static); route params
+reach the handler as `x-zoo-param-<name>` headers. `413` above 900 body bytes,
+`405` when an app-router file does not export the method, `502` with the last
+program log lines when the instruction fails, `404` JSON (or the app's
+`handle: error` route) otherwise.
+
+## The generated crate
+
+`build` writes a crate that depends on the runtime by path. For this two-route
+sample —
+
+```js
+// pages/api/hello.js
+export default function handler(req, res) {
+  res.status(200).json({ hello: req.query.name || 'world', n: Number(req.query.n) * 2, greeting: process.env.GREETING })
+}
+// app/api/counter/route.js
+import { kv } from '@vercel/kv'
+export async function POST() { const n = await kv.incr('hits'); return Response.json({ hits: n }) }
+```
+
+— with `GREETING=hi` in `.env.production`, the compiler (`lib/compile/index.js`,
+`transmute()`) emits exactly this; only the ~240-line prelude of helper
+functions between the entrypoint and the routes is elided:
+
+```toml
+# .zoo-out/.zoo/crate/Cargo.toml   (crate name = the app directory, underscored)
+[package]
+name = "my_site"
+version = "0.1.0"
+edition = "2021"
+description = "Generated by openzoo-transmute: Vercel Lambdas re-hosted as a Solana program"
+publish = false
+
+[lib]
+crate-type = ["cdylib", "lib"]
+
+[dependencies]
+pinocchio = "0.11.2"
+libm = "0.2"
+zoo-host = { path = "<openzoo-transmute>/runtime/zoo-host" }
+
+[profile.release]
+overflow-checks = false
+lto = "fat"
+codegen-units = 1
+opt-level = 3
+```
+
+```rust
+// .zoo-out/.zoo/crate/src/lib.rs
+//! Generated by openzoo-transmute — do not edit.
+//! nextjs (nextjs) — 2 route(s), 2 static file(s)
+//! route 0: /api/hello ← api/hello
+//! route 1: /api/counter [POST] ← api/counter
+#![no_std]
+#![allow(unused_mut, unused_variables, unused_assignments, dead_code, unused_parens, unreachable_code, unused_braces, unused_labels, unused_imports, non_snake_case, non_upper_case_globals, unused_unsafe, clippy::all)]
+extern crate alloc;
+use alloc::{format, string::String, vec::Vec};
+use pinocchio::{AccountView, Address, ProgramResult};
+use zoo_host::{Ctx, Route, Val};
+use zoo_host::val as zv;
+use zoo_host::json as zjson;
+
+pinocchio::program_entrypoint!(process_instruction);
+pinocchio::default_allocator!();
+pinocchio::nostd_panic_handler!();
+
+/// The Lambda environment table, baked at build time (public on chain).
+const ENV: &[(&str, &str)] = &[("GREETING", "hi")];
+/// Route table: instruction byte 1 indexes it.
+const ROUTES: &[Route] = &[route_0, route_1];
+
+pub fn process_instruction(program_id: &Address, accounts: &mut [AccountView], data: &[u8]) -> ProgramResult {
+    zoo_host::dispatch(program_id, accounts, data, ROUTES, ENV)
+}
+
+// … prelude: __zoo_query (req.query + route params), __zoo_resp / __zoo_send (Response objects),
+//    __zoo_cookies, __zoo_num, __zoo_set_headers, … …
+
+// ---- route 0: api/hello (pages/api/hello.js)
+const PARAMS_0: &[(&str, bool)] = &[];
+fn route_0(cx: &mut Ctx) -> Result<(), Val> {
+    let _ = { let __a1 = Val::Num(200.0); cx.res_status(&__a1); Val::Undef };
+    let _ = { let __a2 = { let mut __o3 = Val::obj(); __o3.set_str("hello", { let __x4 = (__zoo_query(cx, PARAMS_0)).get_str("name"); if !__x4.truthy() { Val::str("world") } else { __x4 } }); __o3.set_str("n", ({ let __a: Vec<Val> = alloc::vec![(__zoo_query(cx, PARAMS_0)).get_str("n")]; zv::global_call("Number", &__a)? }).mul(&(Val::Num(2.0)))); __o3.set_str("greeting", { let __a5 = Val::str("GREETING"); cx.env(&__a5) }); __o3 }; cx.res_json(&__a2); Val::Undef };
+    Ok(())
+}
+
+// ---- route 1: api/counter (app/api/counter/route.js)
+const PARAMS_1: &[(&str, bool)] = &[];
+fn route_1(cx: &mut Ctx) -> Result<(), Val> {
+    let __m = cx.req_method();
+    match __m.as_str() {
+        Some("POST") => route_1_post(cx),
+        Some("OPTIONS") => { cx.res_status(&Val::Num(204.0)); cx.res_header(&Val::str("allow"), &Val::str("POST, OPTIONS")); cx.res_end(&Val::Undef); Ok(()) }
+        _ => { cx.res_status(&Val::Num(405.0)); cx.res_header(&Val::str("allow"), &Val::str("POST, OPTIONS")); cx.res_end(&Val::Undef); Ok(()) }
+    }
+}
+fn route_1_post(cx: &mut Ctx) -> Result<(), Val> {
+    let mut v_n: Val = { let __a6 = Val::str("hits"); let __a7 = Val::Num(1.0); cx.kv_incrby(&__a6, &__a7)? };
+    { let __rv = { let __b = { let mut __o8 = Val::obj(); __o8.set_str("hits", v_n.clone()); __o8 }; let __i = Val::Undef; __zoo_resp("json", __b, __i) }; __zoo_send(cx, &__rv)?; }
+    return Ok(());
+    Ok(())
+}
+```
+
+`Route = fn(&mut Ctx) -> Result<(), Val>`; `Err(v)` is a thrown JS value and
+answers 500 like a crashed Lambda; returning without responding answers 504 like
+a Lambda that never ended its response. The `?` after `kv_incrby` is the KV
+account-discovery path: a missing account is logged as `ZOOK` and the gateway
+retries with it. Built with `--arch v3` this crate is a 208,336-byte `.so`
+(a 416,717-byte program data account, 2.90 SOL of rent); on a local validator
+`GET /api/hello?name=zoo&n=21` costs 11,067 CU and `POST /api/counter`
+10,634 CU — nowhere near the 400 k limit.
+
+## Tests
+
+```sh
+cd openzoo-transmute
+npm install --no-audit --no-fund
+npm test                                   # node --test test/*.test.js
+```
+
+The unit tests need no chain. The end-to-end test in `test/gateway.test.js`
+deploys a pre-built site program and drives the gateway against a **local
+validator**; it skips itself with a reason when either is missing:
+
+```sh
+# 1. toolchain (once)
+sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
+export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"
+
+# 2. a validator with a funded wallet (keep it running in another shell)
+solana-test-validator --reset
+solana airdrop 100 --url http://127.0.0.1:8899   # ~/.config/solana/id.json
+
+# 3. a site program with route 0 = /api/hello (pages style) and route 1 =
+#    /api/counter (POST, kv key "hits") — e.g. the two-route sample below
+#    (test validator = SBPF v3; mainnet = v0):
+openzoo-transmute build <sample> --arch v3       # → <sample>/.zoo-out/.zoo/deploy/<name>.so
+#    then point the SAMPLE_SO constant in test/gateway.test.js at that .so
+#    (it is a fixed path today; no sample crate ships with the package yet)
+
+# 4. run
+OPENZOO_TEST_RPC=http://127.0.0.1:8899 npm test
+```
+
+`test/gateway.test.js` looks for the `.so` at `SAMPLE_SO` and a validator at
+`OPENZOO_TEST_RPC` (default `http://127.0.0.1:8899`); `test/build.test.js`
+probes `localnet` for real rent numbers and falls back to the 6.96 SOL/MB rule.
+The runtime crate also builds on the host (`cd runtime/zoo-host && cargo build`;
+its `Cargo.toml` pulls the sha2/curve25519 fallbacks for non-SBF targets), and
+for the chain: `cargo build-sbf --arch v3` (test validator) or `--arch v0` (mainnet).
+
+## Repository layout
+
+```
+bin/openzoo-transmute.js     the executable (→ lib/cli.js run())
+lib/cli.js                   build · deploy · serve · inspect · status
+lib/vercel.js                the Vercel deployment model (Build Output API v3 reader / synthesizer)
+lib/eligibility.js           what can run on chain, with reasons
+lib/compile/                 JS → Rust: parse.js (acorn + TS stripping) → ir.js (lowering) → rust.js (printer, crate skeleton, prelude)
+lib/build.js                 crate + manifest + cargo build-sbf + cost sheet
+lib/deploy.js                deploy / upgrade + assets + manifest
+lib/gateway.js               the local HTTP front (routes, static, 402/413 seams, explorer)
+lib/solana.js                loader (deploy/upgrade in pure JS), assets, KV, invoke + discovery
+lib/wire.js                  the bridge contract as bytes, PDAs
+lib/wallet.js                signer discovery, cluster URLs
+runtime/zoo-host/            the no_std pinocchio runtime the generated crate links
+docs/VERCEL_TO_SOLANA.md     the reverse-engineering document
+docs/OPENZOO_CLI_PATCH.md    mounting build/deploy/serve in npx openzoo
+```
+
+## Limits at a glance
+
+| | |
+|---|---|
+| request body | 900 B (one transaction is 1232 B) |
+| response | ≤ 1024 B in return data, ≈ 7 KB through log chunks |
+| KV value | 10 000 B JSON per key |
+| compute | 400 k CU requested, 1.4 M max |
+| clock | seconds |
+| rent | 6.96 SOL per MB of static + program bytes, 2 × the `.so` reserved |
+| not supported | network, fs, timers, randomness, regex, classes, streaming, `waitUntil`, ISR, crons, middleware, local imports |
+
+## The hosted explorer (`hub`)
+
+`serve` fronts one program on localhost. `hub` fronts every program on a
+cluster from one public host, read-only:
+
+```
+openzoo-transmute hub --cluster mainnet --port 8080        # or: fly deploy (Dockerfile + fly.toml here)
+https://<host>/s/<programId>        pins that site (cookie) and opens its /
+https://<host>/s/<programId>/api/x  one page of it, absolute
+https://<host>/.hub                 paste a program id; recently served sites
+```
+
+Reads are free simulations, exactly as in `serve`. Writes answer 402 on a
+public host (a shared signer would be drained); use `serve` with your wallet
+locally, or the x402-paid lane once the openzoo proxy fronts it. The site's
+own root-relative links keep working because the pinned program rides a
+cookie, so a transmuted app needs no base-path changes.
+
+## Roadmap
+
+* **Browser fork / `sol://` scheme** — a browser that resolves
+  `sol://<programId>/path` straight from the RPC (assets from PDAs, `/api/*`
+  through `simulateTransaction`), so a site needs no gateway and no domain.
+* **x402-paid writes through the openzoo proxy** — the gateway already answers
+  `402` with an `x402` stub for mutating requests when it has no signer; next is
+  letting the openzoo proxy pay per request from the burner wallet so a public
+  gateway never holds keys.
+* **Chunked request bodies** — bodies > 900 B staged into a request account over
+  several transactions (the same mechanism assets already use), then referenced
+  by the invoke.
+* **Response accounts** — responses > ~7 KB written into a per-request account
+  and read back by the gateway, instead of the log buffer.
+* Compiler coverage: local imports, `RegExp`, base64 (`atob`/`btoa`), `cookies()`,
+  `URLSearchParams`, more of `@vercel/kv` (`hget`, lists, `expire`).
+
+License: MIT.

package/transmute/bin/openzoo-transmute.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// `openzoo-transmute build|deploy|serve|inspect|status|help` — see lib/cli.js.
+import { run } from '../lib/cli.js';
+
+const code = await run(process.argv.slice(2));
+// `serve` returns 0 while its server keeps the loop alive; only bail on failure.
+if (code) process.exit(code);

package/transmute/docs/OPENZOO_CLI_PATCH.md

@@ -0,0 +1,139 @@
+# Mounting `build` / `deploy` / `serve` in `npx openzoo`
+
+The openzoo CLI (`staccDOTsol/openzoo`, `bin/openzoo.js`) gains four
+subcommands that delegate to this package. Nothing is duplicated: `openzoo`
+forwards its argv to `openzoo-transmute/lib/cli.js`, whose `run(argv)` resolves
+to the exit code, sets `process.exitCode` when non-zero and never calls
+`process.exit` itself (so `serve` keeps the event loop — and its HTTP server — alive).
+
+Two files change.
+
+**Status.** openzoo's `transmute-cli` branch carries hunk 1 (`bin/openzoo.js`,
+byte-identical to the diff below) and nothing else. Hunk 2 waits for
+`openzoo-transmute` to be published: `npm view openzoo-transmute` is a 404
+today, so both the `"openzoo-transmute": "^0.1.0"` dependency and the
+`npx --yes openzoo-transmute@latest` fallback fail on a fresh machine. Until
+then, install the package from its path so the `import('openzoo-transmute/lib/cli.js')`
+branch resolves: `npm install /path/to/leCore/openzoo-transmute` inside the
+openzoo checkout (or `npm link` in that directory, then `npm link openzoo-transmute`).
+
+## 1. `bin/openzoo.js`
+
+```diff
+--- a/bin/openzoo.js
++++ b/bin/openzoo.js
+@@ -169,6 +169,16 @@
+   npx openzoo contexts --forget <hash|all>   drop manifest entries
+   npx openzoo balance    wallet balance on every rail — Solana (USDC/TOKEN/SOL),
+                          Base (USDC/ETH), Robinhood Chain (USDG/memecoins/ETH)
++  npx openzoo build [dir]     transmute a Vercel-shaped app (Next.js pages/api,
++                              app/**/route, Vite + api/*) into a Pinocchio Rust
++                              program + asset plan (--out .zoo-out --arch v0|v3)
++  npx openzoo deploy [dir]    deploy the program and the static frontend to
++                              Solana accounts (--cluster mainnet|devnet|localnet,
++                              --yes to accept the rent estimate; burner wallet)
++  npx openzoo serve <program> local gateway/explorer for a deployed site
++                              (--cluster, --port 4402); /api/* reads are free
++                              simulations, writes are signed by the burner
++  npx openzoo inspect [dir]   print the app in Vercel terms + eligibility report
+   npx openzoo address    print both funding addresses (Solana + EVM)
+   npx openzoo help       this text
+ 
+@@ -403,6 +413,33 @@
+       if (bal <= 0) console.log('buy some with:  npx openzoo topup 10');
+       break;
+     }
++    case 'build':
++    case 'deploy':
++    case 'serve':
++    case 'inspect':
++    case 'transmute': {
++      // VERCEL-SHAPED APP -> SOLANA MAINNET. `openzoo build|deploy|serve` hand
++      // the argv to openzoo-transmute (a sibling npm package): it reads the
++      // app the way `vercel build` would (pages/api, app/**/route, api/*,
++      // .vercel/output), transmutes each Lambda into a Pinocchio Rust program
++      // route, stores the static build in asset accounts, deploys with the
++      // burner wallet at ~/.openzoo/wallet.json, and `serve` runs the local
++      // gateway/explorer that maps http://localhost:4402/... onto the program.
++      // Dynamic import so a machine without the package still runs every other
++      // command; the fallback shells out to npx so the very first `openzoo
++      // deploy` works before the dependency is pinned in package.json.
++      const argv = process.argv.slice(2).map((a, i) => (i === 0 && a === 'transmute' ? 'help' : a));
++      let cli = null;
++      try { cli = await import('openzoo-transmute/lib/cli.js'); } catch { /* not installed alongside */ }
++      if (cli) {
++        await cli.run(argv);
++      } else {
++        const { spawnSync } = await import('child_process');
++        const r = spawnSync(process.platform === 'win32' ? 'npx.cmd' : 'npx', ['--yes', 'openzoo-transmute@latest', ...argv], { stdio: 'inherit' });
++        process.exit(r.status === null ? 1 : r.status);
++      }
++      break;
++    }
+     case 'address':
+       (await import('../lib/info.js')).printAddress();
+       break;
+```
+
+The first hunk lands inside the `HELP` template literal, right after the
+`balance` lines and before `address`; the second goes into `main()`'s `switch
+(cmd)` between the `credits` and `address` cases. `openzoo transmute` with no
+further arguments is rewritten to `help` so it prints this package's usage.
+
+## 2. `package.json`
+
+```diff
+--- a/package.json
++++ b/package.json
+@@ -21,9 +21,10 @@
+   "dependencies": {
+     "@modelcontextprotocol/sdk": "^1.12.0",
+     "@solana/spl-token": "^0.4.14",
+     "@solana/web3.js": "^1.98.4",
+     "dugite": "^3.2.3",
++    "openzoo-transmute": "^0.1.0",
+     "selfsigned": "^5.5.0",
+     "viem": "^2.21.0",
+     "zod": "^3.24.0"
+   },
+```
+
+`openzoo-transmute`'s `package.json` has no `exports` map, so the deep import
+`openzoo-transmute/lib/cli.js` resolves as a plain file; both packages already
+depend on `@solana/web3.js ^1.98.4`, so one copy is installed. Until the
+dependency is pinned, the `catch` branch above shells out to
+`npx --yes openzoo-transmute@latest …`, so `npx openzoo deploy` works on a
+fresh machine either way — once the package is on npm (see *Status* above).
+
+## The wallet
+
+Nothing to configure. `openzoo-transmute/lib/wallet.js::loadWallet()` looks, in order, at
+
+1. `--keypair <path>`
+2. `$OPENZOO_KEYPAIR`
+3. `$OPENZOO_WALLET`, else **`~/.openzoo/wallet.json`** — the openzoo burner
+   wallet, in either of its shapes: `{ "solana": [64 bytes], ... }` (what
+   `npx openzoo address` creates) or a bare `solana-keygen` array
+4. `~/.config/solana/id.json` (the Solana CLI keypair)
+
+so a user who has run `npx openzoo address` already has the signer `deploy` and
+`serve` will use, and the same `OPENZOO_WALLET` / `OPENZOO_RPC` variables
+listed in openzoo's `HELP` apply. `OPENZOO_CLUSTER` selects the cluster
+(`mainnet` by default; `deploy` refuses mainnet without `--yes` after printing
+the rent sheet). The mainnet RPC default is the one the openzoo proxy uses
+(`lib/config.js` `rpcUrl`), overridable with `OPENZOO_RPC`.
+
+## Checking the patch
+
+```sh
+npm install                                 # pulls openzoo-transmute (or: npm install /path/to/leCore/openzoo-transmute)
+node bin/openzoo.js help | grep -A1 'openzoo build'
+node bin/openzoo.js transmute               # prints openzoo-transmute's usage
+node bin/openzoo.js inspect ./my-app        # Vercel model + eligibility, no chain access
+node bin/openzoo.js build ./my-app --skip-cargo   # crate + cost sheet without the Solana toolchain
+node bin/openzoo.js deploy ./my-app --cluster devnet
+node bin/openzoo.js serve --cluster devnet  # program id from ./my-app/.zoo-out/.zoo/deploy.json
+```
+
+Exit codes come back from `run()`: `0` ok, `1` error (message on stderr,
+`OPENZOO_DEBUG=1` for the stack), `2` when `build` found nothing eligible.