@decidio/sdk 0.1.4 → 0.1.6

package/dist/cli.js

@@ -1,23 +1,4 @@
 #!/usr/bin/env node
-// @decidio/sdk CLI — the on-ramp. Run via `npx @decidio/sdk <cmd>` (or tsx in-repo).
-//   init [agentId]   sign in, register the agent, mint its API token, write .env
-//   doctor           check config + connectivity + durability readiness
-//   approvals        list pending agent approvals; `approvals approve|reject <id> [reason]`
-//   receipt <id>     download a sealed decision's Authority Receipt to a .json file
-//   dev [--target U] signal-only relay: forwards Decidio's webhook to your local agent URL
-//
-// TWO TOKEN KINDS, deliberately (self-serve design 2026-08-28): commands that ADMINISTER a
-// workspace (init's register+mint, approvals, receipt) need the owner's SESSION token — acquired
-// interactively per run or from DECIDIO_SESSION_TOKEN, held in memory, NEVER written to disk.
-// What lands in .env as DECIDIO_API_TOKEN is the floor-limited AGENT token the runtime SDK
-// needs (it can call /agent/* and nothing else). A session-capable secret must never live in
-// an agent host's .env — that was the pre-publish design's hole.
-//
-// MESSAGE DISCIPLINE (founder bar 2026-08-29, from the Codex acceptance run): every failure
-// tells the developer WHAT happened, WHY, and the EXACT next command. Every success says what
-// changed, where, and what to do next. No stack traces for expected failures; no green ✔ for a
-// no-op (the replay-approve bug: the server's idempotent alreadyResolved was reported as a
-// fresh success — an authority CLI may never dress a no-op as an action).
 import { readFileSync, writeFileSync, existsSync, appendFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
@@ -34,8 +15,6 @@ const VERSION = (() => {
         return "unknown";
     }
 })();
-// ---- environment: load the CWD .env FIRST (Codex finding: init writes .env, but the next
-// command ignored it and pointed at localhost). Process env always wins — .env only fills gaps.
 function readEnvFile() {
     const out = {};
     if (existsSync(".env"))
@@ -47,9 +26,6 @@ function readEnvFile() {
     return out;
 }
 for (const [k, v] of Object.entries(readEnvFile())) {
-    // NEVER autoload the session token from disk: the whole design splits session (memory-only)
-    // from the floor-limited agent token (.env). Silently honoring a parked session token would
-    // reward exactly the credential-at-rest the split exists to prevent (guard catch 2026-08-29).
     if (k === "DECIDIO_SESSION_TOKEN") {
         console.log("⚠ ignoring DECIDIO_SESSION_TOKEN found in .env — session tokens belong in your shell or CI secret store, never on disk. Remove that line; export it in the shell instead.");
         continue;
@@ -57,17 +33,11 @@ for (const [k, v] of Object.entries(readEnvFile())) {
     if (process.env[k] === undefined)
         process.env[k] = v;
 }
-// `quickstart` is the zero-config guided tour: with no DECIDIO_API_URL anywhere it targets the
-// hosted sandbox (and says so); every other command keeps the localhost dev default.
 const IS_QUICKSTART = process.argv[2] === "quickstart";
 const API = (process.env.DECIDIO_API_URL ?? (IS_QUICKSTART ? "https://decidio-api.onrender.com" : "http://localhost:4000")).replace(/\/$/, "");
-// Token is read AT CALL TIME, not captured at import: init mints a fresh agent token mid-run and
-// its closing doctor must probe with THAT, not the pre-init env (round-3 Codex catch — the stale
-// capture made init's own doctor print "token: REJECTED" seconds after a successful mint).
 const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
-/** Fetch wrapper that turns transport failures into guidance instead of a stack trace. */
 async function api(path, init = {}, bearer) {
     const auth = bearer ?? TOKEN();
     let res;
@@ -102,10 +72,8 @@ function upsertEnv(updates) {
     const body = Object.entries(merged).map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
     writeFileSync(ENV_PATH, body);
 }
-/** Keep secrets out of git without nagging: append the two entries to .gitignore when they're
- *  not already covered. Creating the file in a non-git directory is harmless. */
 function ensureGitignore() {
-    const entries = [".env", ".decidio-pending/"];
+    const entries = [".env", ".env.quickstart", ".decidio-pending/"];
     const existing = existsSync(".gitignore") ? readFileSync(".gitignore", "utf8") : "";
     const missing = entries.filter((e) => !existing.split(/\r?\n/).some((l) => l.trim() === e || l.trim() === e.replace(/\/$/, "")));
     if (!missing.length)
@@ -113,12 +81,10 @@ function ensureGitignore() {
     appendFileSync(".gitignore", (existing && !existing.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n");
     log(`✔ added ${missing.join(" + ")} to .gitignore (your agent key and parked actions stay out of git)`);
 }
-// ---- interactive input (session sign-in) ---------------------------------------------------
 function ask(question, mute = false) {
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
         if (mute) {
-            // Hide password echo: after the prompt renders, swallow subsequent output writes.
             const anyRl = rl;
             const write = anyRl._writeToOutput?.bind(rl);
             anyRl._writeToOutput = (s) => { if (s.includes(question))
@@ -128,14 +94,9 @@ function ask(question, mute = false) {
             process.stdout.write("\n"); resolve(answer.trim()); });
     });
 }
-/** Owner SESSION token, memory-only. Sources in order: DECIDIO_SESSION_TOKEN env, interactive
- *  email+password (`/demo/login`), pasted sign-in link (`/demo/login-consume` — for the
- *  password-less accounts the welcome flow creates). Never persisted. */
 async function acquireSession(purpose) {
     if (process.env.DECIDIO_SESSION_TOKEN)
         return process.env.DECIDIO_SESSION_TOKEN;
-    // Same rule the server applies to resume URLs: credentials never ride plaintext http to a
-    // non-loopback host. Refuse before prompting, not after collecting a password.
     if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
         log(`✘ refusing to send sign-in credentials over plaintext http to ${API}.`);
         log(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
@@ -179,14 +140,10 @@ async function acquireSession(purpose) {
 }
 async function cmdInit(agentId) {
     log(`Registering agent "${agentId}" with Decidio at ${API}…`);
-    // CLIENT-SIDE KEYGEN: generate the Ed25519 keypair LOCALLY and register only the PUBLIC
-    // did:key. The private key NEVER crosses the wire — it goes straight to this host's env.
     const existingKey = readEnvFile().DECIDIO_AGENT_KEY;
     const sourceSystem = process.env.DECIDIO_SOURCE_SYSTEM || readEnvFile().DECIDIO_SOURCE_SYSTEM;
     const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
     const registerBody = JSON.stringify({ agentId, did: localDid, ...(sourceSystem ? { sourceSystem } : {}) });
-    // First try whatever bearer the env already carries (the local-dev / operator path — a static
-    // admin token, or dev-open auth). On 401/403 fall through to the self-serve session flow.
     let session = null;
     let r = await api("/api/agents/register", { method: "POST", body: registerBody });
     if (r.status === 401 || r.status === 403) {
@@ -197,10 +154,6 @@ async function cmdInit(agentId) {
     }
     let did, privateKey;
     if (r.status === 409) {
-        // Already registered to a server-held did. WITHOUT the original private key on this machine
-        // this is a HARD STOP, not a degraded continue (round-3 Codex catch: init used to write a
-        // keyless .env and print happy-path next steps — every request then routed unproven and
-        // execution evidence silently capped at agent_asserted).
         did = r.body?.did;
         if (existingKey) {
             log(`• "${agentId}" is already registered in this workspace (did ${did}) — reusing it with the DECIDIO_AGENT_KEY already in .env.`);
@@ -227,10 +180,6 @@ async function cmdInit(agentId) {
         log(`  Fix the cause above and re-run — init is safe to repeat.`);
         return 1;
     }
-    // Mint the runtime credential: the floor-limited AGENT token (can call /agent/* only). This is
-    // what .env gets — the session token stays in memory and dies with this process. On boxes
-    // without the tester-lab fence (plain local dev) the mint endpoint refuses; that's fine —
-    // local dev auths with its existing env and we say so instead of failing the init.
     let agentToken, workspaceId;
     const mintBearer = session ?? TOKEN();
     if (mintBearer) {
@@ -256,15 +205,12 @@ async function cmdInit(agentId) {
     if (did)
         envOut.DECIDIO_AGENT_DID = did;
     if (privateKey)
-        envOut.DECIDIO_AGENT_KEY = privateKey; // written locally; never left this host
+        envOut.DECIDIO_AGENT_KEY = privateKey;
     if (agentToken)
-        envOut.DECIDIO_API_TOKEN = agentToken; // the FLOOR-LIMITED token — never the session
+        envOut.DECIDIO_API_TOKEN = agentToken;
     if (workspaceId)
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     upsertEnv(envOut);
-    // The closing doctor (and anything else this process does) must see what init just wrote —
-    // OVERWRITE process.env with the fresh values (round-3 Codex catch: doctor probed with the
-    // stale pre-init token and reported the mint it just watched as REJECTED).
     for (const [k, v] of Object.entries(envOut))
         process.env[k] = v;
     log(`✔ wrote ${ENV_PATH} — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
@@ -274,7 +220,7 @@ async function cmdInit(agentId) {
     log("");
     log("Next: protect one function and watch it route. Two steps:");
     log("");
-    log("  1. Save this as quickstart.mjs (the same snippet as the README's step 3):");
+    log("  1. Save this as quickstart.mjs (the README's step-3 snippet — comments trimmed):");
     log("");
     log(`     import { guard } from "@decidio/sdk";`);
     log("");
@@ -304,28 +250,18 @@ async function cmdDoctor() {
     line(!!(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL), `API URL: ${API}${(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL) ? "" : "  (unset — defaulting to localhost; the hosted sandbox is https://decidio-api.onrender.com)"}`);
     line(!!(process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID), `agent id: ${process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID || "(unset — run: npx @decidio/sdk init <agent-name>)"}`);
     const secret = process.env.DECIDIO_WEBHOOK_SECRET || env.DECIDIO_WEBHOOK_SECRET;
-    line(!!secret, secret ? "webhook secret: set (durable resume will fail-closed verify)" : "webhook secret: MISSING — the resume webhook will fail closed (init generates one)");
-    // Signing key — REQUIRED to be ELIGIBLE for auto-approve. Whether anything auto-approves is
-    // the workspace policy's call, not this key's (Codex finding: the old wording claimed
-    // "auto-approve is in effect" while deny-by-default routed everything).
+    line(!!secret, secret ? "webhook secret: set — operator-only transport (inactive against the hosted sandbox; the poll worker guard.worker() is the self-serve resume path)" : "webhook secret: MISSING — the resume webhook (operator deployments) would fail closed; init generates one");
     const signing = (process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY) && (process.env.DECIDIO_AGENT_DID || env.DECIDIO_AGENT_DID);
     if (signing)
         log("✔ signing key: set — the agent can prove its identity, making it ELIGIBLE for policy auto-approve. Whether a rule matches is your workspace policy's decision; with no matching rule every request routes to a human (deny-by-default).");
     else
         log("⚠ signing key: MISSING (DECIDIO_AGENT_KEY/DID) — the agent can't prove identity, so EVERY request routes to a human. Run `npx @decidio/sdk init` to generate one.");
-    // Reachability and token role are SEPARATE checks (the old probe called any <500 green, so a
-    // wrong-kind token looked healthy). /api/health is unauthenticated truth about reachability;
-    // /api/records then classifies the token.
     const h = await api("/api/health", {}, "");
     line(h.status >= 200 && h.status < 300, `connectivity: API reachable (${h.status})`);
     const rec = await api("/api/records");
     if (rec.status >= 200 && rec.status < 300)
         log("✔ token scope: session/admin (init, approvals and receipt work from this env)");
     else if (rec.status === 401) {
-        // A 401 off the agent floor could also mean an INVALID token (Codex catch: don't
-        // false-green expiry). Disambiguate with a floor probe: a valid agent token gets 404 for an
-        // unknown decision (authorized, not found); an invalid one gets 401 again. A rejection here
-        // flips the overall verdict — "all green" after a red line was round 3's other doctor bug.
         const probe = await api("/agent/status/doctor-scope-probe");
         if (probe.status === 404)
             log("✔ token scope: agent floor — correct for the runtime SDK (approvals/receipt will ask you to sign in)");
@@ -340,8 +276,6 @@ async function cmdDoctor() {
     return ok ? 0 : 1;
 }
 async function cmdApprovals(sub, id, reason) {
-    // Approvals are a HUMAN act on the workspace — session scope, never the agent token. If the
-    // env's token is agent-floor (401 on /api/*), sign in interactively; memory-only as always.
     const jsonMode = sub === "--json";
     if (jsonMode)
         sub = undefined;
@@ -360,9 +294,6 @@ async function cmdApprovals(sub, id, reason) {
         }
         const r = await api(`/api/decisions/${encodeURIComponent(id)}/${sub === "approve" ? "approve" : "reject"}`, { method: "POST", body: JSON.stringify({ reason: reason ?? undefined }) }, bearer);
         if (r.status >= 200 && r.status < 300) {
-            // HONESTY over green checkmarks (Codex finding: the server resolves each decision exactly
-            // once and answers replays idempotently — a replay is a NO-OP and must read as one, never
-            // as a fresh approval). Non-zero exit so scripts can tell the difference.
             if (r.body?.alreadyResolved) {
                 log(`• ${id} was already resolved — nothing changed.`);
                 log(`  Decisions are single-use: a second ${sub} can never re-execute the action (that's the replay protection working).`);
@@ -392,7 +323,6 @@ async function cmdApprovals(sub, id, reason) {
     const cards = r.body?.cards ?? [];
     const pending = cards.filter((c) => c.isAgentRequest && c.status !== "sealed");
     if (jsonMode) {
-        // Stable machine output (round-3 ask): agents scripting the queue parse this, not prose.
         log(JSON.stringify(pending.map((c) => ({ decisionId: c.id, action: c.agentRequest?.action ?? null, amount: c.agentRequest?.amount ?? null, title: c.title ?? null })), null, 2));
         return 0;
     }
@@ -400,24 +330,24 @@ async function cmdApprovals(sub, id, reason) {
         log("No pending agent approvals. Trigger one from your protected function, then re-run this.");
         return 0;
     }
-    log(`Pending agent approvals (${pending.length}):`);
+    const myAgent = process.env.DECIDIO_AGENT_ID;
+    log(`Pending agent approvals (${pending.length})${myAgent ? ` — workspace-wide; "←" marks this directory's agent (${myAgent})` : ""}:`);
     for (const c of pending) {
         const ar = c.agentRequest ?? {};
-        log(`  ${c.id}  ${ar.action ?? "?"}${ar.amount != null ? `  $${Number(ar.amount).toLocaleString()}` : ""}  — ${c.title ?? ""}`);
+        const mine = myAgent && typeof c.title === "string" && c.title.startsWith(`${myAgent}:`);
+        log(`  ${c.id}  ${ar.action ?? "?"}${ar.amount != null ? `  $${Number(ar.amount).toLocaleString()}` : ""}  — ${c.title ?? ""}${mine ? "  ←" : ""}`);
     }
     log(`\nApprove:  npx @decidio/sdk approvals approve <id> [reason]`);
     log(`Reject:   npx @decidio/sdk approvals reject <id> [reason]`);
     return 0;
 }
-async function cmdReceipt(id) {
+async function cmdReceipt(id, jsonMode = false) {
     if (!id) {
         log("usage: npx @decidio/sdk receipt <decisionId>");
         log("  Downloads the decision's sealed Authority Receipt (a W3C Verifiable Credential) to a .json file.");
         log("  Find decision ids via `npx @decidio/sdk approvals` or in your Decidio app.");
         return 2;
     }
-    // Receipts are workspace data — session scope, like approvals. (The record-detail /verify
-    // route carries the credential; the plain record route does not — Codex finding.)
     let bearer;
     let r = await api(`/api/records/${encodeURIComponent(id)}/verify`);
     if (r.status === 401 || r.status === 403) {
@@ -437,28 +367,32 @@ async function cmdReceipt(id) {
         return 1;
     }
     const name = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
-    writeFileSync(name, JSON.stringify(r.body.credential, null, 2) + "\n");
-    log(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
-    // The credential seals at DECISION time (immutable), so execution evidence that arrived later
-    // lives on the record — surface the CURRENT tier here so the reader doesn't need a second
-    // lookup to see it (Codex catch).
+    const nextBytes = JSON.stringify(r.body.credential, null, 2) + "\n";
+    if (existsSync(name)) {
+        if (readFileSync(name, "utf8") !== nextBytes) {
+            log(`✘ ${name} already exists with DIFFERENT bytes — refusing to overwrite an audit artifact. Move it aside or delete it, then re-run.`);
+            return 1;
+        }
+        log(`• ${name} already exists (byte-identical — receipts are immutable); leaving it in place.`);
+    }
+    else {
+        writeFileSync(name, nextBytes);
+        log(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
+    }
     const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
     const conf = detail.body?.record?.confirmation;
+    if (jsonMode) {
+        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed }, null, 2));
+        return 0;
+    }
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
-    // Emit EXACTLY the deterministic command we document (round-4 catch: the README and this hint
-    // disagreed, and bare npx re-probes the registry) — the verifier ships INSIDE this package.
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     log(`    npx @decidio/sdk verify ${name}`);
     log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
     log(`    npx @decidio/sdk verify --issuer <did:key:...> ${name}`);
     return 0;
 }
-// ---- verify (embedded) ----------------------------------------------------------------------
-/** Duplicate-key-refusing parse — the SAME semantics as the decidio-verify CLI (RFC 8785 §3.1:
- *  duplicate keys make different parsers disagree on which value is real; refuse instead).
- *  Conformance-locked: the cross-language runner asserts this door refuses the same vectors for
- *  the same reasons as decidio-verify and python -m decidio.verify. */
 function parseReceiptStrict(text, file) {
     const value = JSON.parse(text);
     const stack = [];
@@ -508,6 +442,10 @@ function parseReceiptStrict(text, file) {
 }
 function cmdVerify(argsIn) {
     const issIdx = argsIn.indexOf("--issuer");
+    if (issIdx >= 0 && (argsIn[issIdx + 1] === undefined || argsIn[issIdx + 1].startsWith("--"))) {
+        log("✘ --issuer needs a did:key value.");
+        return 2;
+    }
     const expectedIssuer = issIdx >= 0 ? argsIn[issIdx + 1] : undefined;
     const files = argsIn.filter((a, i) => !a.startsWith("--") && !(issIdx >= 0 && i === issIdx + 1));
     if (!files.length) {
@@ -528,7 +466,7 @@ function cmdVerify(argsIn) {
         const res = verifyReceipt(vc, expectedIssuer);
         allOk = allOk && res.valid;
         log(`${res.valid ? "✔ VALID  " : "✘ INVALID"}  ${files[i]}`);
-        log(`    record: ${res.recordId ?? "?"}   issuer: ${res.issuer}`);
+        log(`    record: ${res.recordId ?? "?"}   issuer: ${res.issuer}${expectedIssuer ? "" : "  (unpinned — pass --issuer to bind to your workspace's DID)"}`);
         log(`    content-bound: ${res.contentBound}${res.reason ? `   reason: ${res.reason}` : ""}`);
     });
     if (vcs.length > 1) {
@@ -538,7 +476,6 @@ function cmdVerify(argsIn) {
     }
     return allOk ? 0 : 1;
 }
-// ---- quickstart (the guided two-minute tour) ------------------------------------------------
 async function cmdQuickstart() {
     const t0 = Date.now();
     log("Decidio quickstart — gate an action, route it to a human, execute on approval, hold the proof.");
@@ -547,9 +484,6 @@ async function cmdQuickstart() {
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
-    // 1. A collision-proof agent, registered fresh every run (round-4 ask: idempotent sample
-    //    registration). Key generated locally; floor-limited token minted; .env written so the
-    //    take-away snippet works in this directory afterward.
     const agentId = `quickstart-${randomBytes(2).toString("hex")}`;
     log(`① Registering agent "${agentId}" (fresh name each run — no collisions)…`);
     const { did, privateKeyBase64 } = generateKeypair();
@@ -568,9 +502,6 @@ async function cmdQuickstart() {
         DECIDIO_AGENT_KEY: privateKeyBase64, DECIDIO_API_TOKEN: mint.body.token,
         DECIDIO_WORKSPACE_ID: mint.body.workspaceId ?? "", DECIDIO_WEBHOOK_SECRET: readEnvFile().DECIDIO_WEBHOOK_SECRET || randomBytes(32).toString("hex"),
     };
-    // NEVER clobber a real agent's key (guard catch: keys never leave this machine — overwriting
-    // .env's DECIDIO_AGENT_KEY orphans that agent irrecoverably). A directory that already holds
-    // one gets a TOUR-SCOPED env file instead.
     let envFile = ENV_PATH;
     if (readEnvFile().DECIDIO_AGENT_KEY) {
         envFile = ".env.quickstart";
@@ -583,11 +514,11 @@ async function cmdQuickstart() {
     ensureGitignore();
     log(`  ✔ key generated locally (public half registered) · floor-limited token minted · ${envFile} written`);
     log("");
-    // 2. Gate a demo action — the same one line you'd wrap your real function with.
-    log(`② Gating a demo action with ONE line — guard.protect(payInvoice, …):`);
+    log(`② Gating a demo action — the tour runs this (blocking mode: watch it live):`);
     log("");
     log(`     const payInvoice = guard.protect(payInvoiceRaw,`);
-    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }));`);
+    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }),`);
+    log(`       { mode: "blocking" });   // your real agent typically omits this — durable + a worker`);
     log("");
     let decisionId = "";
     const cfg = {
@@ -609,7 +540,6 @@ async function cmdQuickstart() {
     log(`  ✔ $86,000 payInvoice ROUTED to a human (decision ${decisionId}) — this agent has no auto-approve rule,`);
     log(`    so deny-by-default sends everything to a person. Nothing executes until someone decides.`);
     log("");
-    // 3. The human moment — approve right here, or from the Decidio app.
     if (process.stdin.isTTY) {
         await ask(`③ YOU are the approver. Press Enter to approve it here (or approve it in your Decidio queue first, then Enter): `);
     }
@@ -622,7 +552,6 @@ async function cmdQuickstart() {
         return 1;
     }
     log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
-    // 4. The blocking wrapper wakes and runs the agent's own function.
     let result;
     try {
         result = await running;
@@ -633,7 +562,6 @@ async function cmdQuickstart() {
     }
     log(`  ✔ your function executed AFTER approval: ${JSON.stringify(result)}`);
     log("");
-    // 5. The proof: download the receipt and verify it offline, all in-process.
     log("④ Downloading the sealed Authority Receipt and verifying it OFFLINE…");
     const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
     if (!(rec.status >= 200 && rec.status < 300) || !rec.body?.credential) {
@@ -643,25 +571,24 @@ async function cmdQuickstart() {
     const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
     const v = verifyReceipt(rec.body.credential, undefined);
-    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding verified with NO network, no Decidio account)`);
+    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline; issuer UNPINNED — bind it with: npx @decidio/sdk verify --issuer <your workspace DID>)`);
     const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
     const tier = detail.body?.record?.confirmation?.status;
     if (tier)
-        log(`  ✔ execution evidence on the record: ${tier} — the wrapper's report was cryptographically bound to this agent`);
+        log(`  ✔ execution evidence on the record: ${tier} — the wrapper's signed report. (The receipt seals the DECISION; execution evidence accrues on the record — see the README.)`);
     log("");
     const secs = Math.round((Date.now() - t0) / 1000);
-    log(`Done in ${secs}s: gated → routed to a human → approved → executed once → sealed, verifiable proof in your hands.`);
+    log(`Done in ${secs}s: gated → routed to a human → approved → your function executed once → an authority-decision receipt you can verify offline.`);
     log("");
     log("Take it to your real agent — the .env here already works:");
     log(`  import { guard } from "@decidio/sdk";`);
     log(`  const doIt = guard.protect(doItRaw, (a) => ({ action: "yourAction", amount: a.amount, scope: "YourScope" }));`);
+    log(`  // production is DURABLE mode (default) + one worker: guard.worker();  // README has the full pattern`);
     log("");
-    log("Next: the README's 7-step quickstart (durable mode, workers, adapters) · your queue at your Decidio app.");
+    log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}  ·  Next: the README's 7-step quickstart (durable, workers, adapters).`);
     return v.valid ? 0 : 1;
 }
 function cmdDev(target, port) {
-    // Signal-only relay: receive Decidio's webhook here (a stable URL) and forward it to
-    // your local agent's resume listener. Useful when the agent isn't directly reachable.
     log(`decidio dev relay on http://localhost:${port}/decidio/resume → forwarding to ${target}`);
     createServer((req, res) => {
         if (req.method !== "POST") {
@@ -738,7 +665,10 @@ async function main(argv) {
         }
         case "doctor": return cmdDoctor();
         case "approvals": return cmdApprovals(a, b, rest.join(" ") || undefined);
-        case "receipt": return cmdReceipt(a);
+        case "receipt": {
+            const argsIn = argv.slice(3);
+            return cmdReceipt(argsIn.find((x) => !x.startsWith("-")), argsIn.includes("--json"));
+        }
         case "verify": return cmdVerify(argv.slice(3));
         case "dev": {
             const args = argv.slice(3);

package/dist/guard.d.ts

@@ -8,22 +8,14 @@ export interface GuardFacadeConfig {
     resumeUrl?: string;
     webhookSecret?: string;
     pendingDir?: string;
-    /** Local signing key (DECIDIO_AGENT_KEY) + public did (DECIDIO_AGENT_DID), from `init`.
-     *  When present the gate authorizes against a PROVEN identity, not a claimed label. */
     agentKey?: string;
     agentDid?: string;
-    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID). Bound into the signed proof (D-B3.6)
-     *  so a captured proof can't be replayed in another tenant. */
     workspaceId?: string;
-    /** Base URL of the Decidio app (DECIDIO_APP_URL) — used to deep-link a routed decision. */
     appUrl?: string;
     fetchImpl?: typeof fetch;
 }
 export interface ProtectOptions {
-    /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest/mcp)
-     *  live in @decidio/sdk/adapters and take the engine handle. */
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest" | "mcp";
-    /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
 }
 export declare class Guard {
@@ -31,13 +23,8 @@ export declare class Guard {
     resume?: ResumeController;
     constructor(config: GuardFacadeConfig, resume?: ResumeController);
     static fromEnv(): Guard;
-    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
     resumeHandler(): import("http").RequestListener;
-    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
     resumeFetchHandler(): (req: Request) => Promise<Response>;
-    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
-     *  any parked approval — so a suspended action survives a process restart. One line at startup.
-     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
     worker(opts?: {
         intervalMs?: number;
         timeoutMs?: number;
@@ -48,5 +35,4 @@ export declare class Guard {
     private ensureResume;
     protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
 }
-/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export declare const guard: Guard;

package/dist/guard.js

@@ -1,7 +1,3 @@
-// The Guard facade — `guard.protect(fn, describe)`, the one agnostic line (TS mirror
-// of decidio-guard Python). A thin layer over the verified primitives: durable mode
-// builds a resume controller and suspends; blocking mode polls (opt-in, loud). The
-// agent executes its own action; Decidio gates + records + signals — never executes.
 import { withApproval } from "./index.js";
 import { createDecidioResume, FilePendingStore } from "./resume.js";
 export class Guard {
@@ -26,13 +22,8 @@ export class Guard {
             appUrl: process.env.DECIDIO_APP_URL,
         });
     }
-    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
     resumeHandler() { return this.ensureResume().webhookHandler(); }
-    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
     resumeFetchHandler() { return this.ensureResume().fetchHandler(); }
-    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
-     *  any parked approval — so a suspended action survives a process restart. One line at startup.
-     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
     worker(opts) {
         return this.ensureResume().worker(opts);
     }
@@ -42,8 +33,6 @@ export class Guard {
             this.resume = createDecidioResume({
                 apiUrl: c.apiUrl, apiToken: c.apiToken, webhookSecret: c.webhookSecret,
                 resumeUrl: c.resumeUrl, store: new FilePendingStore(c.pendingDir ?? ".decidio-pending"),
-                // Carry the signing identity so the durable/cold confirm on resume is signed too (incl. the
-                // workspace binding — D-B3.6 — so a cold-resume confirm proof is tenant-scoped as well).
                 agentId: c.agentId, agentKey: c.agentKey, agentDid: c.agentDid, workspaceId: c.workspaceId,
                 fetchImpl: c.fetchImpl,
             });
@@ -52,9 +41,7 @@ export class Guard {
     }
     protect(fn, describe, opts) {
         if (opts?.adapter && opts.adapter !== "generic") {
-            // Engine adapters are bound explicitly via @decidio/sdk/adapters (they need the
-            // engine handle at call time). Surfaced as a clear error until wired in this build.
-            throw new Error(`[decidio] adapter "${opts.adapter}" must be bound via @decidio/sdk/adapters/${opts.adapter} (it needs the engine handle).`);
+            throw new Error(`[decidio] adapter "${opts.adapter}" must be bound via the @decidio/sdk/${opts.adapter} subpath (it needs the engine handle). See that adapter's exports.`);
         }
         const c = this.config;
         const base = {
@@ -64,13 +51,9 @@ export class Guard {
         if ((opts?.mode ?? "durable") === "blocking") {
             console.warn("[decidio] WARNING: blocking wait — only safe for short, watched approvals. " +
                 "Omit mode:\"blocking\" for durable async resume on real (minutes-to-days) approvals.");
-            // No resumeUrl on the blocking path — the server must not fire a webhook to an
-            // endpoint a blocking agent isn't serving; the poll is the only resume channel.
             return withApproval(fn, describe, base);
         }
-        // durable: refuse-don't-downgrade — always wire a resume transport, never silently block.
         return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume: this.ensureResume() });
     }
 }
-/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export const guard = Guard.fromEnv();

package/dist/index.d.ts

@@ -6,49 +6,22 @@ export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";
 export { generateKeypair, signBoundProof, signConfirm, canonicalize } from "./signing.js";
 export type { RequesterIdentity } from "./signing.js";
 export interface GuardConfig {
-    /** Base URL of the Decidio gate, e.g. "https://api.decidio.io". */
     apiUrl: string;
-    /** The agent identity registered with Decidio (onboarding wizard), e.g. "salesforce/SalesforceBot". */
     agentId: string;
-    /** Bearer token for the REST floor (a trusted, already-authenticated internal
-     *  caller). Lives ONLY in the agent host's environment — never in client code. */
     apiToken?: string;
-    /** Source system label sealed onto the receipt (e.g. "salesforce"). */
     sourceSystem?: string;
-    /** The agent's PRIVATE signing key (PKCS8 base64), generated locally by `init` and held
-     *  ONLY in the agent host's env as DECIDIO_AGENT_KEY. When set (with `agentDid`), the SDK
-     *  signs a request-bound identity proof on each authorize so the floor PROVES the requester
-     *  instead of trusting the label — required for a registered agent to auto-approve. */
     agentKey?: string;
-    /** The agent's PUBLIC did:key (the one registered with Decidio). Pairs with `agentKey`. */
     agentDid?: string;
-    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID, from the owner's agent-token mint).
-     *  Bound into the signed proof (D-B3.6) so a captured proof can't be replayed in another tenant.
-     *  For a tester's per-workspace agent token this is the tester's workspace id. */
     workspaceId?: string;
-    /** Poll cadence + ceiling while a routed action awaits human approval. Used ONLY
-     *  by the blocking transport (no `resume` configured). */
     pollIntervalMs?: number;
     pollTimeoutMs?: number;
-    /** Optional async notifier so a long human wait surfaces in your logs/UI. */
     onPending?: (info: {
         decisionId: string;
         receiptId: string;
         url: string | null;
     }) => void;
-    /** Base URL of the Decidio app (DECIDIO_APP_URL). When set, a routed action can say WHERE to
-     *  approve it — `<appUrl>/d/<decisionId>` opens that decision directly, on web or on the phone
-     *  build. This link used to be built only inside our own example, so a developer who pasted the
-     *  env block set DECIDIO_APP_URL and nothing ever read it. */
     appUrl?: string;
-    /** Durable async resume. When set, a routed action SUSPENDS (parks its args in the
-     *  store, throws DecidioSuspendedError) instead of blocking — the process may exit
-     *  and resume later via the controller's webhook handler or poll worker. This is
-     *  the production transport for real (minutes-to-days) human approvals. */
     resume?: ResumeController;
-    /** Callback URL Decidio POSTs the verdict to on approval (webhook transport).
-     *  Sent on /agent/authorize so the decision carries it. Falls back to
-     *  resume.resumeUrl. Omit when using the poll worker. */
     resumeUrl?: string;
     fetchImpl?: typeof fetch;
 }
@@ -56,9 +29,6 @@ export interface ApprovalContext {
     action: string;
     amount: number;
     scope?: string;
-    /** Optional human-facing DETAILS of the action (e.g. { Account, "Lead Source", Stage }) shown to
-     *  the approver as "what you're approving". Display-only — the policy decides on `amount`/`scope`,
-     *  never these. Residual-safe tokenized server-side before persistence. */
     context?: Record<string, string | number>;
 }
 export declare class DecidioBlockedError extends Error {
@@ -75,22 +45,11 @@ export declare class DecidioTimeoutError extends Error {
     decisionId: string;
     constructor(decisionId: string);
 }
-/** A transport failure with GUIDANCE instead of a raw undici stack (round-4 Codex catch: the CLI
- *  wrapped network errors kindly but the runtime leaked `TypeError: fetch failed`). Carries the
- *  endpoint, the operation, the underlying code, and the safety state a caller cares about most:
- *  whether anything could have executed. */
 export declare class DecidioNetworkError extends Error {
     endpoint: string;
     op: string;
     code: string | undefined;
     constructor(endpoint: string, op: string, code: string | undefined, cause: unknown);
 }
-/**
- * Wrap an async action behind the Decidio gate. `describe` extracts the approval
- * context (action, amount, scope) from the call arguments. Returns a function with
- * the SAME signature as `fn` — drop-in.
- */
-/** `<appUrl>/d/<decisionId>` — the deep link that opens this decision directly, on the web app or
- *  the phone build. Null when DECIDIO_APP_URL is not configured, never a half-built URL. */
 export declare function decisionUrl(appUrl: string | undefined, decisionId: string): string | null;
 export declare function withApproval<A extends any[], R>(fn: (...args: A) => Promise<R>, describe: (...args: A) => ApprovalContext, config: GuardConfig): (...args: A) => Promise<R>;