@decidio/sdk 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -4,6 +4,75 @@ Release notes for the client SDK. The Python package `decidio` ships the same ch
 version (the two are conformance-locked twins). Each entry names what changed, what a reader must do
 on upgrade, and what proved it.
 
+## 0.6.1 — the first-run fork, and the local demo's loose ends
+
+Two independent first-run reviews of 0.6.0 (grades B / A− overall) agreed on one thing: the hosted tour and the
+verifier earn trust, and the new local demo had polish debts. This release pays them and adds the one question a
+stranger's first minute was missing (founder ruling 2026-09-06).
+
+- **One question, then the thing you picked.** A bare `npx @decidio/sdk quickstart` (or a bare `npx @decidio/sdk`) on
+  a terminal with no sign-in asks: do you have a Decidio invite? `n` runs the local demo; `y` signs you in (the emailed
+  link) and asks what next: the two-minute tour, or wiring up your own agent (`init`). Every answer prints the exact
+  command it stands for, so the questions teach their own flags and you never need them twice. Nothing is stored;
+  Enter is not an answer; scripts and CI never see a question (they get today's text, which now also names `--demo`).
+  A signed-in `quickstart` runs straight away; the bare `npx @decidio/sdk` for a signed-in user skips the invite
+  question and asks only "what next?" - the bare command always leads somewhere, usage is a `--help` away. After
+  the sign-in step, the tour does not ask you to sign in again.
+- **Your agent's name has a real default.** `init` with no name used `my-agent`; it now uses this folder's name (or
+  the package name), slugified, and the fork explains what the name is for ("Requested by …", the key `.env` is
+  written under). Any name still works.
+- **A mark, not a banner:** the title lines carry the app's ✦ beside the name.
+- **Headless `--demo` leaves nothing behind** (review: Medium). The stop at the human moment used to exit inside the
+  tour, skipping the wrapper that removes the temporary folder - the mock key, mock token and journal stayed in the
+  temp dir, and the message pointed at the hosted tour's remedies (`approvals approve`, `quickstart cleanup`), which
+  cannot act on a stand-in that lives only in that process. The stop now returns through the wrapper, and says the
+  demo's truth: nothing executed, nothing kept, re-run interactively or with `--auto-approve-demo`.
+- **The demo receipt carries what the terminal claims** (review: Medium). Its canonical record now holds the real
+  amount and currency, the reason the decision arrived with (the automated flag names itself there, exactly as it does
+  in a hosted record's reason), and how it was decided (terminal, page, or the flag). The party stays tokenized, as
+  the real seal keeps it.
+- **`--demo --keep-agent` is refused** (both reviews: Low) - nothing of the demo's can be kept, and the flag used to
+  be accepted while the opposite happened. Exit 2, with the reason.
+- **A receipt the demo could not copy home is not a completed tour** (retest: Low): the temporary folder is kept and
+  named, and the run exits non-zero, instead of deleting the only copy and exiting 0.
+- **Words that were not true** (review: Low): the demo's Target line no longer says "nothing hosted" while the web
+  door uses a hosted relay; the automated line names the demo's mock credential, not "your session credential"; a
+  repeat run's ④ frame names the suffixed file that actually lands; the README no longer calls the sandbox "one shared
+  lab workspace" in two places while saying the opposite in a third.
+
+## 0.6.0 — `quickstart --demo`: the whole tour on your machine, no account
+
+An uninvited developer could not run the tour at all: a workspace needs an invite (no open signup, by ruling). A
+hosted sandbox was designed, red-teamed by the privacy council (BLOCK as written; eight design-level highs) and then
+costed against the alternatives: the cheapest, least-maintenance path for a stranger's first two minutes is a LOCAL
+demo with a hosted page for the phone moment. Founder ruling 2026-09-05.
+
+- **`npx @decidio/sdk quickstart --demo`** runs the SAME tour code against an in-process stand-in of the Decidio API
+  on 127.0.0.1 (`demo-gate.ts`, shipped in this package): register, mint, gate, route, approve or reject, execute
+  once, and a REAL Ed25519 receipt signed by a key generated for the run — verifiable offline with the shipped
+  verifier, and provably NOT the hosted issuer's (pinning it to the hosted DID fails). Nothing hosted, no account, no
+  workspace: the tour runs in a temporary folder and leaves exactly one file behind, the receipt (never over an
+  existing one). Its content says `recordSeries: local-demo`.
+- **The web and phone doors still work.** The stand-in asks a hosted RELAY (`POST /demo/relay`) for a code, a link to
+  the demo decision page (`app.decidioai.com/demo/<code>`) and a QR; the page shows the product's decision surface for
+  the tour's fixed scenario and writes one word — approve or reject — which the stand-in reads while the tour waits.
+  The relay holds no account, no record and no personal data; a code lives ten minutes, takes one verdict, and every
+  failure answers with one shape. Offline (relay unreachable) the tour is terminal-only and says so.
+- **Honesty is asserted, not hoped:** the frames say LOCAL DEMO; ④ says the issuer is a key this demo generated and
+  where real tours pin theirs; the smoke plants the forbidden phrases ("PINNED to your workspace issuer", "hosted
+  synthetic sandbox", "your trust anchor") and asserts the directory diff is the receipt alone; a decision made on the
+  page reaches the terminal with no keystroke. The sign-in dead end now offers `--demo`.
+- **On a phone the demo IS the phone app's screen.** A phone that opens the demo link (the QR, or the link on a phone)
+  lands on the phone build's own decision screen — the same Detail the installed app renders, with Approve and Reject
+  where they always are — not the desktop panel squeezed into a phone viewport (founder UAT round 2). It holds no
+  session and says LOCAL DEMO in one line; the decided moment says the terminal seals. Host-side only: nothing in this
+  package changed for it.
+- **The demo leaves your sign-in alone.** `quickstart --demo` never signs in, so its cleanup no longer ends a stored
+  sign-in that happens to be on the computer (it did, in the founder's UAT; the smoke now plants one and asserts it
+  survives, silently).
+- TypeScript CLI first — `npx @decidio/sdk quickstart` is where an uninvited developer arrives; the Python twin gains
+  `--demo` when asked for (the version bump is in lockstep).
+
 ## 0.5.0 — `verify` pins by default
 
 **Breaking, on purpose (founder ruling 2026-09-04, after the prodsec review of 0.4.3).** Every CLI verify door - `npx

package/README.md

@@ -9,7 +9,11 @@ is the two-minute tour, the sign-in and the token admin around it. Install, wrap
 ## The two-minute tour
 
 ```bash
-npx @decidio/sdk quickstart
+npx @decidio/sdk quickstart          # against your workspace (you need an invite - request one below)
+npx @decidio/sdk quickstart --demo   # no invite yet? the same tour on this machine, against a local stand-in of the API
+# Not sure? The bare command asks: with no sign-in on this computer it asks whether you have an
+# invite (n → the local demo; y → sign in, then the tour or your own agent). Every answer prints
+# the command it stands for, so you never need the questions twice.
 ```
 
 One command, guided: it registers a fresh agent (key generated locally), gates a demo action
@@ -136,8 +140,8 @@ the agent's floor-limited token — it cannot approve anything):
 
 ```bash
 npx @decidio/sdk approvals --mine        # see it pending (--mine narrows to THIS agent; the
-                                         # sandbox is one shared lab workspace, so the bare
-                                         # command lists every member's pending decisions)
+                                         # workspace is yours alone unless you invite others,
+                                         # so the bare command lists every pending decision in it)
 npx @decidio/sdk approvals approve <decisionId>
 ```
 
@@ -653,6 +657,7 @@ that fits every other confirm error.
 - `quickstart cleanup` — revoke the tour's token and delete its local credentials. What stays, honestly: sealed records (permanent by design) and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap) Also ends the stored sign-in.
 - **Update check.** Network commands ask the public npm registry once a day whether a newer version exists; if so, an interactive run asks `Upgrade now? [y/n]` first (`y` upgrades the way you installed - `npm i @decidio/sdk@latest` in the project for a local install, `-g` for a global one, and under `npx` it prints the `@latest` form - then re-runs your command once; `n` exits), a headless run prints the notice and continues (`DECIDIO_REQUIRE_LATEST=1` makes it exit). `DECIDIO_NO_UPDATE_CHECK=1` skips it. Nothing is sent to Decidio; `verify` never checks.
 - **The token recovery journal** (`.decidio-token-journal`, owner-only, gitignored; ids and timestamps, never a token value; append-only by the CLI's behaviour — not OS-enforced or tamper-evident). One JSON row per event: `minted` (a token was issued, written BEFORE its credential file), `retired how=persisted` (the credential file now holds it - the token is live and that file is its handle; not revoked), `retired how=revoked` (revoked server-side), `probe` (a durability check). `doctor` names rows still outstanding; `quickstart cleanup` sweeps them.
+- `quickstart --demo` — the same tour with no account: an in-process stand-in of the API on 127.0.0.1 (shipped in this package) answers every door, a key generated for the run signs a real receipt (its content says `local-demo`; pinning it to the hosted issuer fails), and the web/phone door is a hosted demo decision page reached through a one-word relay (no account, no record, ten minutes). Your folder gains exactly one file, the receipt. Offline, the tour is terminal-only and says so.
 - `quickstart --phone web` — the QR at the human step opens the phone web rendering even when the Decidio app is installed (by default it opens the app when there is one).
 - `login [email]` / `logout` — sign in ONCE (the CLI emails you a link; you paste it) and forget that sign-in on this computer (the session token itself stays valid until it expires (up to 30 days) — there is no server-side revocation yet). The session is stored in your user profile, owner-only, bound to the terminal window that created it, for 30 days; `DECIDIO_SESSION_TOKEN` in the environment outranks it (headless shells).
 - `dev [--target URL] [--port N]` — local relay for the resume webhook (operator setups)
@@ -745,7 +750,7 @@ the next reader grades a promise, not a moving target:
 
 ## Using this for real?
 
-The hosted sandbox is synthetic and shared. Production workspaces are per-tenant, with your own
+The hosted sandbox is synthetic data in a workspace of your own. Production workspaces are per-tenant too, with your own
 issuer key and receipts that verify offline against it.
 
 [decidioai.com](https://decidioai.com) · [Developer docs](https://decidioai.com/developers/) · [Request access](https://decidioai.com/#early-access)

package/dist/cli.d.ts

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 export type ApprovalAnswer = "approve" | "reject" | "again";
 export declare function approvalAnswer(answer: unknown): ApprovalAnswer;
+/** The agent id `init` uses when none is given: this folder's name (or the package name), slugified. "my-agent" told a
+ *  tester nothing; the folder they are in is the agent they are building (founder ruling 2026-09-06). */
+export declare function defaultAgentId(dir?: string): string;
 /** `decidio-receipt-<id>.json`, with every character outside [A-Za-z0-9_-] escaped as `~` + hex code point, so two
  *  distinct decision ids can never share a file (first-run review of 0.4.1: dots were STRIPPED, `a.b` and `ab`
  *  collided). `~` is outside the allowed set, so the escape is unambiguous. Exported for the smokes. */

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync, openSync, writeSync, fsyncSync, closeSync, renameSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync, openSync, writeSync, fsyncSync, closeSync, renameSync, mkdirSync, mkdtempSync, readdirSync, copyFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { homedir } from "node:os";
-import { join as joinPath, resolve as resolvePath, sep as pathSep } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { join as joinPath, resolve as resolvePath, sep as pathSep, basename } from "node:path";
 import { createServer } from "node:http";
 import { execFileSync, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
@@ -13,6 +13,7 @@ import { generateKeypair, assertSafeTransport, redactUrl } from "./signing.js";
 import { hardenFile } from "./resume.js";
 import { withApproval, DecidioRateLimitError, DecidioRejectedError, DecidioTimeoutError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify, pinRequiredMessage } from "@decidio/verify";
+import { startDemoGate } from "./demo-gate.js";
 const VERSION = (() => {
     try {
         return createRequire(import.meta.url)("../package.json").version;
@@ -65,7 +66,13 @@ if (!OFFLINE_CMD)
         if (process.env[k] === undefined)
             process.env[k] = v;
     }
-const API = (process.env.DECIDIO_API_URL ?? "https://decidio-api.onrender.com").replace(/\/$/, "");
+let API = (process.env.DECIDIO_API_URL ?? "https://decidio-api.onrender.com").replace(/\/$/, "");
+let DEMO = false;
+function enterDemo(url) { API = url; process.env.DECIDIO_API_URL = url; DEMO = true; }
+const pinWords = () => (DEMO ? "PINNED to this demo's own key" : "PINNED to your workspace issuer");
+const issuerNote = () => (DEMO
+    ? "· a key this demo generated for this run — real tours pin the host's published DID at https://decidio-api.onrender.com/api/did"
+    : `· your trust anchor — first seen over this signed-in connection; cross-check ${API}/api/did, then verify --issuer <did> <receipt.json>`);
 const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
@@ -399,6 +406,8 @@ function recordKindOf(credential) {
     }
 }
 function sessionReminder() {
+    if (DEMO)
+        return;
     log(`  ⚠ agent code launched from THIS terminal inherits your sign-in — run logout first (it forgets the sign-in here; the token itself stays valid until it expires); if you`);
     log(`    exported DECIDIO_SESSION_TOKEN, unset it ${dim("(bash/zsh: unset DECIDIO_SESSION_TOKEN · PowerShell: Remove-Item Env:DECIDIO_SESSION_TOKEN)")}`);
 }
@@ -407,6 +416,7 @@ const paint = (code, s) => (TTY_OUT ? `\x1b[${code}m${s}\x1b[0m` : s);
 const bold = (s) => paint("1", s);
 const dim = (s) => paint("2", s);
 const link = (url) => (TTY_OUT ? `\x1b]8;;${url}\x1b\\${url}\x1b]8;;\x1b\\` : url);
+const brand = () => `${paint("38;5;178", "✦")} ${paint("38;5;29", bold("Decidio"))}`;
 const FRAME_WIDTH = 84;
 const visibleLength = (s) => s.replace(/\x1b\[[0-9;]*m|\x1b\]8;;[^\x1b]*\x1b\\/g, "").length;
 function frameWidth(rows) {
@@ -564,6 +574,7 @@ async function loginFlow(purpose, emailArg) {
     }
     log(`  ✔ sign-in email requested for ${email} — check your inbox and spam; paste the link (or its login= code; single-use, 15 minutes)`);
     log(dim(`    invite-only lab: a link arrives only for an invited address — not invited yet? request access: decidioai.com/#early-access`));
+    log(dim(`    or see the whole story on this machine right now, no account: npx @decidio/sdk quickstart --demo`));
     const pasted = await ask("  link or code: ");
     if (!pasted) {
         log("  ✘ nothing pasted — re-run when you have the email.");
@@ -598,12 +609,79 @@ async function acquireSession(purpose) {
     if (!process.stdin.isTTY) {
         err(`✘ ${purpose} needs a Decidio workspace sign-in, and this terminal can't prompt for one.`);
         err(`  Fix: run \`npx @decidio/sdk login\` in an interactive terminal first (the sign-in is stored for this terminal),`);
-        err(`  or set DECIDIO_SESSION_TOKEN. To mint one by hand: request a sign-in link, then`);
+        err(`  or set DECIDIO_SESSION_TOKEN - or, with no account at all: npx @decidio/sdk quickstart --demo. To mint one by hand: request a sign-in link, then`);
         err(`    curl -X POST ${API}/demo/login-consume -H "content-type: application/json" -d '{"token":"<login value>"}'   # the response's "token"`);
         return null;
     }
     return loginFlow(purpose);
 }
+export function defaultAgentId(dir = process.cwd()) {
+    let name = "";
+    try {
+        const pkg = JSON.parse(readFileSync(joinPath(dir, "package.json"), "utf8"));
+        if (typeof pkg?.name === "string")
+            name = pkg.name.replace(/^@[^/]+\//, "");
+    }
+    catch { }
+    if (!name)
+        name = basename(dir);
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+    return slug || "my-agent";
+}
+async function firstRunFork(signedInAs = null) {
+    const pick = async (prompt, ok) => {
+        let a = "";
+        for (let i = 0; i < 3 && !ok.test(a); i++)
+            a = (await ask(i === 0 ? "  › " : `   Please answer ${prompt}: `)).trim().toLowerCase();
+        return ok.test(a) ? a : "";
+    };
+    log("");
+    if (signedInAs !== null) {
+        log(`  Signed in${signedInAs ? ` as ${signedInAs}` : ""} on this computer.`);
+    }
+    else {
+        log(`  Do you have a Decidio invite?   ${dim("[y/n]")}`);
+        log(`    ${bold("n")}   the local demo on this machine, no account          ${dim("npx @decidio/sdk quickstart --demo")}`);
+        log(`    ${bold("y")}   sign in to your workspace                           ${dim("npx @decidio/sdk login")}`);
+        const a = await pick("y or n", /^[yn]$/);
+        if (!a) {
+            log(`  No answer — nothing was done. Run either command above when you are ready.`);
+            return { kind: "stop", code: 1 };
+        }
+        if (a === "n") {
+            log(`  → running: npx @decidio/sdk quickstart --demo`);
+            log("");
+            return { kind: "demo" };
+        }
+        log(`  → running: npx @decidio/sdk login`);
+        const token = await loginFlow("Signing in");
+        if (!token)
+            return { kind: "stop", code: 1 };
+    }
+    log("");
+    log(`  What next?   ${dim("[1/2]")}`);
+    log(`    ${bold("1")}   the two-minute tour against your workspace         ${dim("npx @decidio/sdk quickstart")}`);
+    log(`    ${bold("2")}   wire up your own agent now (register, token, .env)  ${dim("npx @decidio/sdk init <agentId>")}`);
+    const b = await pick("1 or 2", /^[12]$/);
+    if (!b) {
+        log(`  No answer — you are signed in; run either command above when you are ready.`);
+        return { kind: "stop", code: 0 };
+    }
+    if (b === "1") {
+        log(`  → running: npx @decidio/sdk quickstart   ${dim("(signed in - it will not ask again)")}`);
+        log("");
+        return { kind: "tour" };
+    }
+    const def = defaultAgentId();
+    log(`  Your agent needs a name. It is how the workspace shows the request ("Requested by ${def.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}")`);
+    log(`  and the key .env is written under. Any name works; Enter takes the folder's.`);
+    const typed = (await ask(`  agent id [${def}]: `)).trim();
+    const agentId = typed || def;
+    log(`  → running: npx @decidio/sdk init ${agentId}   ${dim("(next time, skip the questions: run that directly)")}`);
+    log("");
+    return { kind: "init", agentId };
+}
+const forkApplies = () => !!(process.stdin.isTTY && process.stdout.isTTY) && !process.env.DECIDIO_SESSION_TOKEN && !loadSession();
 async function cmdLogin(emailArg) {
     try {
         assertSafeTransport(API, true);
@@ -984,7 +1062,10 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
     return 0;
 }
 export function receiptFileName(id) {
-    return `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, (c) => "~" + c.codePointAt(0).toString(16).padStart(2, "0"))}.json`;
+    const base = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, (c) => "~" + c.codePointAt(0).toString(16).padStart(2, "0"))}.json`;
+    if (DEMO_ORIGIN && DEMO_STAMP && existsSync(joinPath(DEMO_ORIGIN, base)))
+        return base.replace(/\.json$/, `.${DEMO_STAMP}.json`);
+    return base;
 }
 function writeReceiptFile(name, bytes, say = log) {
     if (existsSync(name)) {
@@ -1145,15 +1226,66 @@ function valuedOpt(args, flag) {
     const eq = args.find((x) => x.startsWith(flag + "="));
     return eq ? eq.slice(flag.length + 1) : undefined;
 }
+let DEMO_ORIGIN = null;
+let DEMO_STAMP = null;
 async function cmdQuickstart(opts = {}) {
+    if (!opts.demo)
+        return cmdQuickstartInner(opts);
+    if (opts.keepAgent) {
+        err(`✘ --keep-agent has nothing to keep under --demo: the demo's agent and token live in a temporary folder that is removed at the end (only the receipt stays).`);
+        err(`  Drop --keep-agent, or run the hosted tour (npx @decidio/sdk quickstart) where --keep-agent keeps a real agent + token.`);
+        return 2;
+    }
+    const relayBase = SHELL_ENV.DECIDIO_DEMO_RELAY_URL === undefined ? "https://decidio-api.onrender.com" : (SHELL_ENV.DECIDIO_DEMO_RELAY_URL || null);
+    const gate = await startDemoGate({ relayBase });
+    enterDemo(gate.url);
+    const origin = process.cwd();
+    const work = mkdtempSync(joinPath(tmpdir(), "decidio-demo-"));
+    DEMO_ORIGIN = origin;
+    DEMO_STAMP = String(Date.now());
+    process.chdir(work);
+    let code = 1;
+    let copyFailed = false;
+    try {
+        code = await cmdQuickstartInner(opts);
+    }
+    finally {
+        process.chdir(origin);
+        for (const f of readdirSync(work)) {
+            if (!/^decidio-receipt-.*\.json$/.test(f))
+                continue;
+            let target = joinPath(origin, f);
+            if (existsSync(target))
+                target = joinPath(origin, f.replace(/\.json$/, `.${Date.now()}.json`));
+            try {
+                copyFileSync(joinPath(work, f), target);
+                log(`  receipt kept here: ${target.slice(origin.length + 1)}   ${dim("(the demo's agent, token and files lived in a temporary folder, now removed)")}`);
+            }
+            catch (e) {
+                copyFailed = true;
+                err(`  ✘ could not copy the receipt into this folder (${e?.message ?? e}) — the temporary folder is KEPT so the receipt is not lost: ${joinPath(work, f)}`);
+            }
+        }
+        if (!copyFailed)
+            rmSync(work, { recursive: true, force: true });
+        await gate.close();
+        DEMO_ORIGIN = null;
+        DEMO_STAMP = null;
+    }
+    return copyFailed ? (code || 1) : code;
+}
+async function cmdQuickstartInner(opts = {}) {
     const t0 = Date.now();
     EXPLAIN = !!opts.explain;
     if (opts.phone !== undefined && opts.phone !== "app" && opts.phone !== "web") {
         err(`✘ --phone takes app (default: the QR opens the installed app when there is one) or web (the QR opens the phone web rendering, always).`);
         return 2;
     }
-    log(bold("Decidio quickstart") + " — gate an action, route it to a human, execute on approval, hold the proof.");
-    log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : dim("  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)")}`);
+    log(brand() + bold(" quickstart") + " — gate an action, route it to a human, execute on approval, hold the proof.");
+    if (DEMO)
+        log(`  Target: LOCAL DEMO — an in-process stand-in for the Decidio API on this machine (${API}). Only the web/phone door touches a hosted relay (one word, no account); nothing is kept but the receipt`);
+    else
+        log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : dim("  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)")}`);
     hostAnnounced = true;
     if (EXPLAIN) {
         log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
@@ -1163,12 +1295,16 @@ async function cmdQuickstart(opts = {}) {
         log("  · create one synthetic decision and its sealed record (records are permanent by design) · wait up to");
         log("  5 minutes for your y (approve) or n (reject) at the human step. Cleanup offer at the end.");
     }
+    else if (DEMO) {
+        log(dim("  Creates here: the receipt only (decidio-receipt-<id>.json). The demo's agent, token and working files live in a temporary"));
+        log(dim("  folder that is removed at the end; the web/phone door is a hosted demo page — nothing signs in, no record exists anywhere else."));
+    }
     else {
         log(dim("  Creates here: a synthetic agent + 7-day token (.env), .decidio-token-journal (revocation ids, no secrets), .gitignore entries incl."));
         log(dim("  .decidio-pending/ (the durable store), the receipt as decidio-receipt-<id>.json, one sealed record (permanent). --explain for the long form."));
     }
     log("");
-    const session = await acquireSession("The quickstart");
+    const session = DEMO ? "demo-session" : await acquireSession("The quickstart");
     if (!session)
         return 1;
     const prior = readEnvFile();
@@ -1180,7 +1316,8 @@ async function cmdQuickstart(opts = {}) {
         err(`✘ cannot reach ${API}${reach.status ? ` (HTTP ${reach.status})` : " (no response)"} — check the network (or DECIDIO_API_URL) and re-run. Nothing was written.`);
         return 1;
     }
-    ensureGitignore();
+    if (!DEMO)
+        ensureGitignore();
     let agentId = `quickstart-${randomBytes(5).toString("hex")}`;
     if (EXPLAIN)
         log(`  Registering agent "${agentId}"…`);
@@ -1304,7 +1441,7 @@ async function cmdQuickstart(opts = {}) {
     block("①", "Register a synthetic agent", [
         `${bold("agent")}    ${agentId}`,
         `${bold("key")}      generated locally · only the public half was registered`,
-        `${bold("token")}    7-day, floor-limited${mint.body.expiresAt ? ` · expires ${String(mint.body.expiresAt).slice(0, 10)}` : ""} · written to ${envFile}`,
+        `${bold("token")}    ${DEMO ? "demo token (one hour, this machine only)" : "7-day, floor-limited"}${mint.body.expiresAt ? ` · expires ${String(mint.body.expiresAt).slice(0, 10)}` : ""} · written to ${envFile}`,
     ]);
     if (EXPLAIN) {
         log(`  The tour runs exactly this, the BLOCKING primitive (your real agent uses guard.protect instead:`);
@@ -1364,10 +1501,12 @@ async function cmdQuickstart(opts = {}) {
         const plainLink = `${APP_URL}/queue?focus=${encodeURIComponent(decisionId)}`;
         const rows = [
             `${bold("here")}         Type y to approve or n to reject, then Enter   ${dim("(waits up to 5 minutes)")}`,
-            `${bold("web app")}      ${link(doorLink ?? plainLink)}   ${dim(doorLink ? "(one-time sign-in · 5 minutes)" : "(sign in there if it asks)")}`,
+            DEMO
+                ? (doorLink ? `${bold("web page")}     ${link(doorLink)}   ${dim("(the demo decision page · nothing signs in)")}` : `${bold("web page")}     ${dim("the web and phone doors need the internet — the demo relay was unreachable, so this run is terminal-only")}`)
+                : `${bold("web app")}      ${link(doorLink ?? plainLink)}   ${dim(doorLink ? "(one-time sign-in · 5 minutes)" : "(sign in there if it asks)")}`,
         ];
         if (qr) {
-            rows.push(`${bold("your phone")}   scan — the same one-time sign-in${opts.phone === "web" ? ", in the phone browser (--phone web)" : ": the Decidio app if it is installed, the browser if not"}`);
+            rows.push(DEMO ? `${bold("your phone")}   scan — the same demo decision page, in your phone's browser` : `${bold("your phone")}   scan — the same one-time sign-in${opts.phone === "web" ? ", in the phone browser (--phone web)" : ": the Decidio app if it is installed, the browser if not"}`);
             for (const l of qr.split("\n"))
                 if (l.trim().length)
                     rows.push("             " + l);
@@ -1406,26 +1545,52 @@ async function cmdQuickstart(opts = {}) {
             verdict = "again";
         if (verdict === "again" && !(earlyError instanceof DecidioTimeoutError)) {
             log(`③ No decision was made (no y or n answer), so the tour stops here rather than guess.`);
-            log(`   The request is still ROUTED and waiting in your queue - approve or reject it there, or re-run the tour.`);
-            log(`   NOTE: this tour's credentials are still live in ${envFile} (a 7-day token + the agent's key). Once you`);
-            log(`   have decided - or if you abandon the tour - remove them: npx @decidio/sdk quickstart cleanup`);
+            if (DEMO) {
+                log(`   Nothing executed and no receipt was written. Nothing is kept: the demo's agent, token and folder go now.`);
+                log(`   Re-run and answer y or n (or use the web page / QR).`);
+            }
+            else {
+                log(`   The request is still ROUTED and waiting in your queue - approve or reject it there, or re-run the tour.`);
+                log(`   NOTE: this tour's credentials are still live in ${envFile} (a 7-day token + the agent's key). Once you`);
+                log(`   have decided - or if you abandon the tour - remove them: npx @decidio/sdk quickstart cleanup`);
+            }
             log("");
             sessionReminder();
-            process.exit(3);
+            currentRl?.close();
+            stdinReadAbandoned = true;
+            return 3;
         }
         if (earlyError instanceof DecidioTimeoutError) {
             log(`③ the tour's blocking call gave up after 5 minutes while waiting for your answer, so your answer is NOT posted:`);
-            log(`   the request is still ROUTED in your queue - decide it there, or re-run the tour and answer within 5 minutes.`);
-            log(`   NOTE: this tour's credentials are still live in ${envFile} - remove them: npx @decidio/sdk quickstart cleanup`);
+            if (DEMO)
+                log(`   the demo ends here; nothing is kept (the demo's agent, token and folder go now). Re-run and answer within 5 minutes.`);
+            else {
+                log(`   the request is still ROUTED in your queue - decide it there, or re-run the tour and answer within 5 minutes.`);
+                log(`   NOTE: this tour's credentials are still live in ${envFile} - remove them: npx @decidio/sdk quickstart cleanup`);
+            }
             log("");
             sessionReminder();
-            process.exit(3);
+            currentRl?.close();
+            stdinReadAbandoned = true;
+            return 3;
         }
     }
     else if (opts.autoApproveDemo) {
-        log("③ --auto-approve-demo: approving with your session credential. This is AUTOMATED authority");
+        log(`③ --auto-approve-demo: approving with ${DEMO ? "the demo's mock credential (no account is involved)" : "your session credential"}. This is AUTOMATED authority`);
         log("   (a flag you passed, not a human decision in the moment) — fine for CI, not the real story.");
     }
+    else if (DEMO) {
+        log("③ This terminal can't put a human in the loop, and an approval IS a human act — the demo stops here");
+        log("   rather than approve its own request. Nothing executed, no receipt was written, and nothing is kept:");
+        log("   the demo's agent, token and working folder go now (the stand-in API lives only in this process).");
+        log("");
+        log("   Re-run in an interactive terminal and answer y or n there, on the web page or by QR — or, for CI:");
+        log("     npx @decidio/sdk quickstart --demo --auto-approve-demo     (the tour approves itself under that explicit label)");
+        log("");
+        log("   (exit 3 = the demo stopped at the human moment; deliberately not reported as a completed tour.)");
+        stdinReadAbandoned = true;
+        return 3;
+    }
     else {
         log("③ This terminal can't put a human in the loop, and an approval IS a human act — the tour");
         log("   stops here rather than approve its own request. The decision is routed and waiting —");
@@ -1447,7 +1612,8 @@ async function cmdQuickstart(opts = {}) {
         log(`   or if you abandon the tour — remove them: npx @decidio/sdk quickstart cleanup`);
         log("");
         sessionReminder();
-        process.exit(3);
+        stdinReadAbandoned = true;
+        return 3;
     }
     const rejected = verdict === "reject";
     if (rejected) {
@@ -1491,17 +1657,17 @@ async function cmdQuickstart(opts = {}) {
                     return failTour(1);
                 const issuer = rec.body?.issuer;
                 const v = verifyReceipt(rec.body.credential, issuer);
-                const kindLine = `${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", PINNED to your workspace issuer" : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
+                const kindLine = `${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", " + pinWords() : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
                 if (!v.valid || !issuer) {
                     log(`  ${kindLine}`);
                     err(`  ✘ the denial's receipt did not verify PINNED (${!issuer ? "no issuer DID from the server" : v.reason ?? "no reason given"}) — the tour did not complete.`);
                     return failTour(1);
                 }
                 block("④", "The record", [
-                    `✔ VALID — ${fname} ${dim("(signature + content binding, offline, PINNED to your workspace issuer)")}`,
+                    `✔ VALID — ${fname} ${dim(`(signature + content binding, offline, ${pinWords()})`)}`,
                     `${bold("decision")} payInvoice $86,000 · REJECTED · routed to a human by policy (no auto-approve rule for this agent)`,
                     `${bold("record")}   record kind: ${recordKindOf(rec.body.credential) ?? "?"} ${dim("— the denial is sealed too")}`,
-                    `${bold("issuer")}   ${issuer} ${dim(`· your trust anchor — first seen over this signed-in connection; cross-check ${API}/api/did, then verify --issuer <did> <receipt.json>`)}`,
+                    `${bold("issuer")}   ${issuer} ${dim(issuerNote())}`,
                 ], "bad");
                 denialVerified = true;
             }
@@ -1529,7 +1695,8 @@ async function cmdQuickstart(opts = {}) {
         }
         log("");
         sessionReminder();
-        log(`${bold("Where next")}  your queue ${link(APP_URL)} · README "Production mode: durable async resume" ${dim("· built by OmniTwin — decidioai.com/#early-access")}`);
+        if (!DEMO)
+            log(`${bold("Where next")}  your queue ${link(APP_URL)} · README "Production mode: durable async resume" ${dim("· built by OmniTwin — decidioai.com/#early-access")}`);
     }
     else {
         const ap = decidedOutside ? { status: 200, body: { alreadyResolved: true } } : await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
@@ -1565,7 +1732,7 @@ async function cmdQuickstart(opts = {}) {
             return failTour(1);
         const issuer = rec.body?.issuer;
         const v = verifyReceipt(rec.body.credential, issuer);
-        const kindLine = `${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", PINNED to your workspace issuer" : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
+        const kindLine = `${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", " + pinWords() : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
         if (!v.valid || !issuer)
             log(`  ${kindLine}`);
         if (!v.valid) {
@@ -1583,33 +1750,44 @@ async function cmdQuickstart(opts = {}) {
         const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
         const tier = detail.body?.record?.confirmation?.status;
         block("④", "The receipt", [
-            `✔ VALID — ${fname} ${dim("(signature + content binding, offline, PINNED to your workspace issuer)")}`,
+            `✔ VALID — ${fname} ${dim(`(signature + content binding, offline, ${pinWords()})`)}`,
             `${bold("decision")} payInvoice $86,000 · APPROVED · routed to a human by policy (no auto-approve rule for this agent)`,
             `${bold("record")}   record kind: ${recordKindOf(rec.body.credential) ?? "?"}${tier ? ` · evidence: ${tier}` : ""} ${dim("— the receipt seals the DECISION; execution evidence lives on the record")}`,
-            `${bold("issuer")}   ${issuer} ${dim(`· your trust anchor — first seen over this signed-in connection; cross-check ${API}/api/did, then verify --issuer <did> <receipt.json>`)}`,
+            `${bold("issuer")}   ${issuer} ${dim(issuerNote())}`,
         ], "good");
         const secs = Math.round((Date.now() - t0) / 1000);
         block("✔", `Done in ${secs}s`, [
             `${bold("gated")}        payInvoice $86,000 — ROUTED to a human as ${decisionId}`,
-            `${bold("decided")}      ${decidedOutside ? "approved in the web app (or on your phone)" : opts.autoApproveDemo ? "approved by --auto-approve-demo (automated, and labeled so on the record)" : "approved by you, here"}`,
+            `${bold("decided")}      ${decidedOutside ? "approved in the web app (or on your phone)" : opts.autoApproveDemo ? `approved by --auto-approve-demo (automated — the ${DEMO ? "receipt's reason says so" : "record's reason says so"})` : "approved by you, here"}`,
             `${bold("executed")}     your function ran once, AFTER approval`,
-            `${bold("receipt")}      VALID — verified offline, pinned to your workspace issuer (④ above)`,
+            `${bold("receipt")}      VALID — verified offline, pinned to ${DEMO ? "this demo's own key" : "your workspace issuer"} (④ above)`,
             dim("gated → routed to a human → approved → executed once → a receipt you can verify offline"),
         ], "good");
         log("");
-        log(bold("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" }));${dim("   // durable by default")}`);
-        log("");
-        if (EXPLAIN) {
-            log(`  The README's seven-step flow is this same blocking flow in your own code; if you keep this agent, its .env`);
-            log(`  already works here, so skip that flow's init step. Production is DURABLE mode (default) + one worker.`);
+        if (DEMO) {
+            log(bold("That was the mechanism — on this machine, against a stand-in. The product runs it against your workspace:"));
+            log(`  request access: decidioai.com/#early-access · have an invite? npx @decidio/sdk login, then npx @decidio/sdk quickstart`);
+            log("");
+        }
+        else {
+            log(bold("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" }));${dim("   // durable by default")}`);
+            log("");
+            if (EXPLAIN) {
+                log(`  The README's seven-step flow is this same blocking flow in your own code; if you keep this agent, its .env`);
+                log(`  already works here, so skip that flow's init step. Production is DURABLE mode (default) + one worker.`);
+            }
         }
         sessionReminder();
-        log(`${bold("Where next")}  your queue ${link(APP_URL)} · README "Production mode: durable async resume" ${dim("· built by OmniTwin — decidioai.com/#early-access")}`);
+        if (!DEMO)
+            log(`${bold("Where next")}  your queue ${link(APP_URL)} · README "Production mode: durable async resume" ${dim("· built by OmniTwin — decidioai.com/#early-access")}`);
     }
     let doCleanup = false;
-    if (interactive) {
+    if (DEMO) {
+        doCleanup = true;
+    }
+    else if (interactive) {
         const answer = await ask(`\nKeep this agent for development? [Enter = keep · c + Enter = clean up now]: `);
         doCleanup = answer.trim().toLowerCase() === "c";
         if (!doCleanup)
@@ -1757,7 +1935,7 @@ async function quickstartCleanup(session, envFile) {
         });
         if (kept.length === 0) {
             rmSync(envFile);
-            log(`  ✔ ${envFile} deleted (the agent's local key is gone — the registered agent is now inert)`);
+            log(`  ✔ ${envFile} deleted (the agent's local key is gone — ${DEMO ? "the temporary folder follows" : "the registered agent is now inert"})`);
         }
         else {
             writeSecretFile(envFile, kept.join("\n") + "\n");
@@ -1773,9 +1951,13 @@ async function quickstartCleanup(session, envFile) {
             log(`      npx @decidio/sdk approvals reject ${c.id} "quickstart cleanup"`);
         }
     }
-    log(`  • What remains, by design: the sealed decision record (records are permanent — that is the product)`);
-    log(`    and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap).`);
-    if (existsSync(JOURNAL_PATH))
+    if (DEMO)
+        log(`  • nothing remains: the demo's stand-in agent, token and files go with the temporary folder — only the receipt is kept`);
+    else {
+        log(`  • What remains, by design: the sealed decision record (records are permanent — that is the product)`);
+        log(`    and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap).`);
+    }
+    if (!DEMO && existsSync(JOURNAL_PATH))
         log(`  • Also kept: ${JOURNAL_PATH} — the ids and timestamps of what this directory minted and revoked (no secrets). Gitignored; owner-only where the OS supports it.`);
     if (existsSync(".decidio-pending")) {
         log(`  • Also kept: .decidio-pending/ — this agent's own execution ledger: whatever this agent parked (call arguments,`);
@@ -1783,6 +1965,8 @@ async function quickstartCleanup(session, envFile) {
         log(`    pending and you do not want the history, remove it:`);
         log(`      ${process.platform === "win32" ? "Remove-Item -Recurse .decidio-pending" : "rm -r .decidio-pending"}`);
     }
+    if (DEMO)
+        return 0;
     if (endSession())
         log(`  ✔ signed out — the stored sign-in is removed from this computer (the token itself stays valid until it expires; npx @decidio/sdk login to sign in again).`);
     else if (process.env.DECIDIO_SESSION_TOKEN)
@@ -1898,7 +2082,7 @@ function cmdDev(target, port) {
     }).listen(port, "127.0.0.1");
     return 0;
 }
-const USAGE = `decidio — the Decidio SDK command line
+const USAGE = `✦ Decidio — the SDK command line
 
   The wrapper IS the SDK: guard.protect(fn, describe) ships in this package (import { guard } from "@decidio/sdk").
   This command line is the tour, the sign-in, and the token admin around it.
@@ -1907,6 +2091,10 @@ const USAGE = `decidio — the Decidio SDK command line
 
       npx @decidio/sdk quickstart
 
+  With no sign-in on this computer it first asks ONE question - do you have an invite? - and, if you do,
+  what next: the tour, or wiring up your own agent. Every answer shows the command it stands for. The bare
+  npx @decidio/sdk on a terminal asks the same (skipping the invite question when you are signed in).
+
   It gates a demo action, routes it to YOU for approval, executes on your yes, and hands you a
   cryptographically verifiable receipt of the DECISION (execution evidence then accrues on the
   hosted record — the receipt seals who authorized what, not what ran afterward). Guided and
@@ -1923,7 +2111,9 @@ THE TOUR
                                        registration row and the permanent sealed record stay)
                                        (and end the stored sign-in)
   npx @decidio/sdk quickstart --auto-approve-demo   headless tour; cleans up after itself
-                                       (add --keep-agent to KEEP the tour agent + token)
+  npx @decidio/sdk quickstart --demo   the same tour against a LOCAL stand-in of the API — no account needed; the
+                                       web/phone door is a hosted demo page; the receipt is the one thing kept
+                                       (--keep-agent is refused here: nothing of the demo's can be kept)
 
 SIGN IN (once)
   npx @decidio/sdk login [email]       sign in ONCE: the CLI emails you a link, you paste it; the sign-in
@@ -1933,6 +2123,8 @@ SIGN IN (once)
 
 YOUR AGENT AND ITS TOKENS
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
+                                       (agentId defaults to this folder's name; any name works - it is how the
+                                       workspace shows the request and the key .env is written under)
                                        --unique  append a random suffix (collision-proof samples)
                                        --force   replace a different agent already in this .env
                                                  (its .env is backed up first)
@@ -2075,6 +2267,16 @@ async function main(argv) {
         log(VERSION);
         return 0;
     }
+    if (!cmd && process.stdin.isTTY && process.stdout.isTTY) {
+        log(brand() + " — gate an action, route it to a human, execute on approval, hold the proof.   " + dim("(npx @decidio/sdk --help for every command)"));
+        const stored = process.env.DECIDIO_SESSION_TOKEN ? "" : loadSession()?.email ?? null;
+        const pick = await firstRunFork(process.env.DECIDIO_SESSION_TOKEN ? "" : stored);
+        if (pick.kind === "stop")
+            return pick.code;
+        if (pick.kind === "init")
+            return cmdInit(pick.agentId, {});
+        return cmdQuickstart({ demo: pick.kind === "demo" });
+    }
     if (!cmd || wantsHelp(cmd)) {
         log(USAGE);
         return 0;
@@ -2089,7 +2291,7 @@ async function main(argv) {
     }
     const argsIn = argv.slice(3);
     const KNOWN = {
-        quickstart: { flags: ["--explain", "--auto-approve-demo", "--keep-agent"], valued: ["--phone"] },
+        quickstart: { flags: ["--explain", "--auto-approve-demo", "--keep-agent", "--demo"], valued: ["--phone"] },
         login: { flags: [] },
         logout: { flags: [] },
         init: { flags: ["--unique", "--force"], valued: ["--expires-days"] },
@@ -2185,7 +2387,18 @@ async function main(argv) {
                     return 1;
                 return quickstartCleanup(session, envFile);
             }
-            return cmdQuickstart({ autoApproveDemo: argsIn.includes("--auto-approve-demo"), keepAgent: argsIn.includes("--keep-agent"), explain: argsIn.includes("--explain"), phone: valuedOpt(argsIn, "--phone") });
+            const qopts = { demo: argsIn.includes("--demo"), autoApproveDemo: argsIn.includes("--auto-approve-demo"), keepAgent: argsIn.includes("--keep-agent"), explain: argsIn.includes("--explain"), phone: valuedOpt(argsIn, "--phone") };
+            if (!qopts.demo && !qopts.autoApproveDemo && forkApplies()) {
+                log(brand() + bold(" quickstart") + " — gate an action, route it to a human, execute on approval, hold the proof.");
+                const pick = await firstRunFork();
+                if (pick.kind === "stop")
+                    return pick.code;
+                if (pick.kind === "init")
+                    return cmdInit(pick.agentId, {});
+                if (pick.kind === "demo")
+                    qopts.demo = true;
+            }
+            return cmdQuickstart(qopts);
         }
         case "init": {
             const unique = argsIn.includes("--unique");
@@ -2198,7 +2411,7 @@ async function main(argv) {
             }
             const ddIdx = argsIn.indexOf("--");
             const nameArg = ddIdx >= 0 ? argsIn[ddIdx + 1] : argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
-            let name = nameArg ?? process.env.DECIDIO_AGENT_ID ?? "my-agent";
+            let name = nameArg ?? (process.env.DECIDIO_AGENT_ID || defaultAgentId());
             if (unique)
                 name = `${name}-${randomBytes(2).toString("hex")}`;
             return cmdInit(name, { force: argsIn.includes("--force"), expiresDays: expRaw ? Number(expRaw) : undefined });

package/dist/demo-gate.d.ts

@@ -0,0 +1,16 @@
+export interface DemoGate {
+    /** http://127.0.0.1:<port> — point the tour here. */
+    url: string;
+    /** The did:key of the key generated for THIS run (never the hosted issuer's). */
+    issuerDid: string;
+    /** Whether the hosted relay answered (the web/phone door exists) — null until session-link was asked. */
+    relayReachable: () => boolean | null;
+    close(): Promise<void>;
+}
+export interface DemoGateOptions {
+    /** Base URL of the hosted relay; null = offline (terminal-only). Default: the hosted sandbox API. */
+    relayBase?: string | null;
+    /** Milliseconds to wait for the relay on each call. */
+    relayTimeoutMs?: number;
+}
+export declare function startDemoGate(opts?: DemoGateOptions): Promise<DemoGate>;

package/dist/demo-gate.js

@@ -0,0 +1,170 @@
+import { createServer } from "node:http";
+import { createHash, generateKeyPairSync, randomBytes, sign as edSign } from "node:crypto";
+import { jcsCanonicalize } from "@decidio/verify";
+const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function b58(buf) {
+    const digits = [0];
+    for (const byte of buf) {
+        let carry = byte;
+        for (let i = 0; i < digits.length; i++) {
+            carry += digits[i] << 8;
+            digits[i] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let out = "";
+    for (const b of buf) {
+        if (b === 0)
+            out += B58[0];
+        else
+            break;
+    }
+    return out + digits.reverse().map((d) => B58[d]).join("");
+}
+const DECISION_ID = "D-DEMO-1";
+const D_NUMBER = "D·0001";
+export async function startDemoGate(opts = {}) {
+    const relayBase = opts.relayBase === undefined ? "https://decidio-api.onrender.com" : opts.relayBase;
+    const relayTimeoutMs = opts.relayTimeoutMs ?? 2000;
+    const issuerKey = generateKeyPairSync("ed25519");
+    const issuerRaw = Buffer.from(issuerKey.publicKey.export({ format: "der", type: "spki" })).subarray(-32);
+    const issuerDid = "did:key:z" + b58(Buffer.concat([Buffer.from([0xed, 0x01]), issuerRaw]));
+    const sealedAt = new Date().toISOString();
+    let verdict = null;
+    let decidedBy = "the human at the terminal";
+    let lastReason = "quickstart";
+    let relayCode = null;
+    let relayOk = null;
+    const relayFetch = async (path, init = {}) => {
+        if (!relayBase)
+            return null;
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), relayTimeoutMs);
+        try {
+            const r = await fetch(`${relayBase.replace(/\/$/, "")}${path}`, { ...init, signal: ctl.signal, headers: { "content-type": "application/json", ...(init.headers ?? {}) } });
+            if (r.status === 204)
+                return {};
+            if (!r.ok)
+                return null;
+            return await r.json().catch(() => ({}));
+        }
+        catch {
+            return null;
+        }
+        finally {
+            clearTimeout(t);
+        }
+    };
+    const issueReceipt = (kind) => {
+        const canonical = jcsCanonicalize({ accountableParty: "[PERSON_1]", action: "payInvoice", amount: 86000, currency: "USD", decidedBy, reason: lastReason, recordKind: kind, recordSeries: "local-demo" });
+        const contentHash = createHash("sha256").update(canonical, "utf8").digest("hex");
+        const context = ["https://www.w3.org/ns/credentials/v2"];
+        const doc = {
+            "@context": context,
+            type: ["VerifiableCredential", "DecidioAuthorityRecord"],
+            issuer: issuerDid,
+            validFrom: sealedAt,
+            credentialSubject: { id: `urn:decidio:decision:${DECISION_ID}`, recordId: DECISION_ID, dNumber: D_NUMBER, contentHash, prevHash: null, recordCanonical: canonical },
+        };
+        const cfg = {
+            "@context": context, type: "DataIntegrityProof", cryptosuite: "eddsa-jcs-2022",
+            created: sealedAt, verificationMethod: `${issuerDid}#${issuerDid.slice("did:key:".length)}`, proofPurpose: "assertionMethod",
+        };
+        const signingInput = Buffer.concat([
+            createHash("sha256").update(Buffer.from(jcsCanonicalize(cfg), "utf8")).digest(),
+            createHash("sha256").update(Buffer.from(jcsCanonicalize(doc), "utf8")).digest(),
+        ]);
+        return { ...doc, proof: { ...cfg, proofValue: "z" + b58(edSign(null, signingInput, issuerKey.privateKey)) } };
+    };
+    const server = createServer((req, res) => {
+        let raw = "";
+        req.on("data", (c) => (raw += c));
+        req.on("end", async () => {
+            let body;
+            try {
+                body = raw ? JSON.parse(raw) : undefined;
+            }
+            catch {
+                body = undefined;
+            }
+            const path = (req.url ?? "").split("?")[0];
+            const send = (o, status = 200) => { res.writeHead(status, { "content-type": "application/json" }); res.end(JSON.stringify(o)); };
+            try {
+                if (path === "/api/health")
+                    return send({ ok: true, demo: true });
+                if (path === "/api/did")
+                    return send({ did: issuerDid, method: "did:key", alg: "Ed25519", demo: true });
+                if (path === "/api/decisions/cards")
+                    return send({ cards: [] });
+                if (path === "/api/agents/register")
+                    return send({ agentId: body?.agentId, did: body?.did });
+                if (path === "/api/workspace/agent-token" && req.method === "POST")
+                    return send({ token: "demo-agent-token", workspaceId: "local-demo", jti: `jti-demo-${randomBytes(4).toString("hex")}`, expiresAt: new Date(Date.now() + 3_600_000).toISOString() });
+                if (path === "/api/workspace/agent-token" && req.method === "GET")
+                    return send({ tokens: [] });
+                if (/^\/api\/workspace\/agent-token\/[^/]+$/.test(path) && req.method === "DELETE")
+                    return send({ ok: true, changed: true });
+                if (path === "/agent/authorize") {
+                    verdict = null;
+                    return send({ decision: "route", decisionId: DECISION_ID, receiptId: "R-DEMO-1" });
+                }
+                if (path.startsWith("/agent/status/")) {
+                    if (!verdict && relayCode) {
+                        const r = await relayFetch(`/demo/relay/${relayCode}`);
+                        if (r && (r.verdict === "approve" || r.verdict === "reject")) {
+                            verdict = r.verdict;
+                            decidedBy = "the demo page (web or phone), through the relay";
+                            lastReason = "decided on the demo page";
+                        }
+                    }
+                    return send(verdict === "reject" ? { state: "rejected", reason: "quickstart: rejected by the approver" } : { state: verdict === "approve" ? "approved" : "pending" });
+                }
+                if (/^\/api\/decisions\/[^/]+\/(approve|reject)$/.test(path)) {
+                    const already = verdict !== null;
+                    verdict = path.endsWith("/reject") ? "reject" : "approve";
+                    if (!already) {
+                        lastReason = typeof body?.reason === "string" && body.reason ? body.reason : "quickstart";
+                        decidedBy = /automated/i.test(lastReason) ? "automated: the --auto-approve-demo flag (not a human in the moment)" : "the human at the terminal";
+                    }
+                    if (relayCode && !already)
+                        void relayFetch(`/demo/relay/${relayCode}`, { method: "PUT", body: JSON.stringify({ verdict }) });
+                    return send({ ok: true, decisionId: DECISION_ID, sealed: true, ...(already ? { alreadyResolved: true } : {}) });
+                }
+                if (path === "/agent/confirm")
+                    return send({ ok: true, confirmation: "application_confirmed", recordId: DECISION_ID });
+                if (path === "/demo/session-link") {
+                    const r = await relayFetch("/demo/relay", { method: "POST", body: JSON.stringify({ decisionId: DECISION_ID }) });
+                    if (r && typeof r.code === "string" && /^[0-9A-HJKMNP-TV-Z]{13}$/.test(r.code) && typeof r.link === "string" && /^https?:\/\//.test(r.link)) {
+                        relayCode = r.code;
+                        relayOk = true;
+                        return send({ status: "ok", link: r.link, qr: typeof r.qr === "string" ? r.qr : null, expiresAt: r.expiresAt ?? null });
+                    }
+                    relayOk = false;
+                    return send({ status: "unavailable", error: "the demo relay is unreachable — this run is terminal-only" }, 503);
+                }
+                if (/^\/api\/records\/[^/]+\/verify$/.test(path)) {
+                    const cred = issueReceipt(verdict === "reject" ? "denial" : "approval");
+                    return send({ dNumber: D_NUMBER, issuer: issuerDid, alg: "Ed25519", valid: true, signatureValid: true, contentBound: true, matchesRecord: true, payloadMatches: true, hash: cred.credentialSubject.contentHash, prevHash: null, credential: cred });
+                }
+                if (/^\/api\/records\/[^/]+$/.test(path))
+                    return send({ record: { confirmation: verdict === "approve" ? { status: "application_confirmed", confirmed: true } : { status: "pending", confirmed: false } } });
+                return send({ error: "not part of the local demo" }, 404);
+            }
+            catch (e) {
+                return send({ error: String(e?.message ?? e) }, 500);
+            }
+        });
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const port = server.address().port;
+    return {
+        url: `http://127.0.0.1:${port}`,
+        issuerDid,
+        relayReachable: () => relayOk,
+        close: () => new Promise((r) => { server.closeAllConnections(); server.close(() => r()); }),
+    };
+}

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.5.0   # tracks the SDK release - checked by packages/conformance/manifests.mjs
+  version: 0.6.1   # tracks the SDK release - checked by packages/conformance/manifests.mjs
   description: >
     Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
     receive the signed resume webhook when a routed action is decided. Every outcome seals a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.5.0"
+    "@decidio/verify": "0.6.1"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {