@decidio/sdk 0.1.7 → 0.1.8

package/README.md

@@ -11,22 +11,29 @@ npx @decidio/sdk quickstart
 One command, guided: it registers a fresh agent (key generated locally), gates a demo action
 with the same one line you'll use on your real function, routes it to a human — **you** — lets
 you approve right there (or from your Decidio app), executes on approval, then downloads the
-sealed Authority Receipt and verifies it offline in front of you. Sign in when prompted, or
-export `DECIDIO_SESSION_TOKEN` for headless terminals. No config: with no `DECIDIO_API_URL` set
-it targets the hosted synthetic sandbox.
+sealed Authority Receipt and verifies it offline in front of you, pinned to your workspace's
+issuer. It mints a **7-day** tour token (`init` mints 90-day tokens — different jobs, different
+lifetimes) and ends by offering to clean itself up (`quickstart cleanup` works later too).
+Sign in when prompted. No config: with no `DECIDIO_API_URL` set it targets the hosted synthetic
+sandbox. Headless, the tour **stops at the routed decision** — approving is a human act, so it
+prints the approve command and exits rather than approve its own request (CI can pass
+`--auto-approve-demo`, which labels that authority as automated).
 
 ## Quickstart — seven steps to your first sealed receipt
 
 Under 30 minutes, no help needed. You'll need Node 20.6+, a terminal, and a Decidio workspace
 (request one at [decidioai.com](https://decidioai.com/#early-access) — the hosted sandbox is
-synthetic data, safe to experiment in).
+synthetic data, safe to experiment in). Lab workspaces have a **governed-action allowance**
+(currently 30 actions/hour); hitting it raises a typed `DecidioRateLimitError` naming the limit
+and reset time — nothing is routed or executed — and `tokens list` shows your remaining
+allowance any time.
 
 **PowerShell users** — the equivalents for every Bash idiom used below:
 
 ```powershell
 mkdir decidio-quickstart; cd decidio-quickstart          # instead of mkdir ... && cd ...
 $env:DECIDIO_API_URL = "https://decidio-api.onrender.com" # instead of export NAME=value
-$env:DECIDIO_SOURCE_SYSTEM = "salesforce"; npx @decidio/sdk init my-sf-agent
+$env:DECIDIO_AGENT_ID = "my-agent"; npx @decidio/sdk init
                                                           # instead of VAR=value npx ... (inline env)
 ```
 
@@ -37,13 +44,15 @@ mkdir decidio-quickstart && cd decidio-quickstart
 npm install @decidio/sdk
 ```
 
-**2. Point at your Decidio and register your agent**
+**2. Register your agent**
 
 ```bash
-export DECIDIO_API_URL=https://decidio-api.onrender.com   # the hosted sandbox
 npx @decidio/sdk init --unique my-agent   # --unique appends a random suffix: collision-proof
 ```
 
+Every CLI command talks to the hosted sandbox by default and announces its target host on
+stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another Decidio instead.
+
 `init` signs you into your workspace (email + password, or paste the sign-in link from your
 workspace email), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
 is sent), registers the agent, mints its **floor-limited API token** (limited to the agent runtime — request authorization, poll status, report signed confirmation; it cannot administer the workspace or approve anything — and your workspace session never touches the agent's disk), and writes `.env`.
@@ -89,11 +98,9 @@ node --env-file=.env quickstart.mjs
 A brand-new agent matches **no** auto-approve rule, so Decidio **routes every request to a
 human by default** — that is the point: nothing executes without either a named policy rule or
 a person. (Routing-by-default is distinct from a policy **block**, which refuses the action
-outright — no human can approve a blocked request.) The script prints the decision id and waits. (To later see a policy `proceed`,
-register a **new** agent in the sandbox's pre-policied lane — an existing agent's lane can't be
-changed: `DECIDIO_SOURCE_SYSTEM=salesforce npx @decidio/sdk init my-sf-agent`. That lane's
-named rule auto-approves amounts under $1M when the request carries the agent's signed
-identity proof, so even this $86k example would proceed there.)
+outright — no human can approve a blocked request. Policy `proceed` rules — named auto-approve
+for requests carrying the agent's signed identity proof — are configured per workspace by its
+owner.) The script prints the decision id and waits.
 
 **5. Approve it** — in a second terminal (same directory; replace `<decisionId>` with the id
 step 4 printed — angle brackets are placeholders, never typed literally). Approvals are a
@@ -142,6 +149,10 @@ The server caps the evidence at the weaker `agent_asserted`, and the SDK warns a
 time.) Immutable seal + accruing evidence is the design, not an omission — corrections and
 later facts supersede, they never rewrite.
 
+One sharing note: a receipt is **not a secret, but it is not metadata-free** — it names the
+action, amount limits, policy, agent and issuer identifiers, and the decision reason. Share it
+with auditors and counterparties deliberately, the way you would any business record.
+
 **7. Prove a replay is rejected:**
 
 ```bash
@@ -264,9 +275,15 @@ imports none of them. Each adapter's shipped `.d.ts` header documents its wiring
 - `doctor` — config, connectivity, and what your current token can do
 - `approvals [--mine] [--json]` / `approvals approve|reject <id> [reason]` — the human side, from your terminal (the list is workspace-wide; `--mine` narrows it to this directory's agent)
 - `receipt <id>` — download a sealed decision's Authority Receipt to a `.json` file
-- `verify [--issuer <did>] <file>...` — verify receipts offline (the canonical verifier; the standalone `@decidio/verify` package is the same implementation, for auditors who want zero Decidio dependency)
+- `verify [--issuer <did>] <file>...` — verify receipts offline (the canonical verifier; the standalone `@decidio/verify` package is the same implementation, for auditors who want zero Decidio dependency). Unknown flags are refused, never ignored.
+- `tokens list` / `tokens revoke <jti>` — see and kill agent tokens (values are never re-shown; the jti is the revocation handle). Each row carries its status — `active`, `expired`, or `REVOKED <date>` — so the list confirms the revocations it performs; re-revoking is an honest no-op (exit 1)
+- `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)
 - `dev [--target URL]` — local relay for the resume webhook (operator setups)
 
+The CLI's stream contract: **stdout carries results only** (safe to pipe — `--json` output is
+pure JSON); errors, usage guidance, and the per-run target-host announcement go to **stderr**.
+Exit codes: 0 success · 1 failure or honest no-op · 2 usage error.
+
 Commands that administer your workspace (`init`, `approvals`, `receipt`) use a **session**
 sign-in held in memory for that run. What lands on disk in `.env`: the agent's floor-limited
 API token, its locally-generated private signing key, and a webhook secret (used only in

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync } from "node:fs";
-import { randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync } from "node:fs";
+import { randomBytes, createHash } from "node:crypto";
 import { createServer } from "node:http";
+import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
 import { generateKeypair } from "./signing.js";
-import { withApproval } from "./index.js";
+import { withApproval, DecidioRateLimitError } from "./index.js";
 import { verifyReceipt } from "@decidio/verify";
 const VERSION = (() => {
     try {
@@ -27,32 +28,37 @@ function readEnvFile() {
 }
 for (const [k, v] of Object.entries(readEnvFile())) {
     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.");
+        console.error("⚠ 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;
     }
     if (process.env[k] === undefined)
         process.env[k] = v;
 }
-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(/\/$/, "");
+const API = (process.env.DECIDIO_API_URL ?? "https://decidio-api.onrender.com").replace(/\/$/, "");
 const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
+const err = (...a) => console.error(...a);
+let hostAnnounced = false;
 async function api(path, init = {}, bearer) {
+    if (!hostAnnounced) {
+        hostAnnounced = true;
+        err(`· decidio → ${API}${process.env.DECIDIO_API_URL ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
+    }
     const auth = bearer ?? TOKEN();
     let res;
     try {
         res = await fetch(API + path, { ...init, headers: { "content-type": "application/json", ...(auth ? { authorization: `Bearer ${auth}` } : {}), ...(init.headers ?? {}) } });
     }
     catch (e) {
-        log(`✘ could not reach Decidio at ${API} (${e?.cause?.code ?? e?.message ?? "network error"}).`);
+        err(`✘ could not reach Decidio at ${API} (${e?.cause?.code ?? e?.message ?? "network error"}).`);
         if (API.includes("localhost")) {
-            log(`  You're pointed at localhost — for the hosted sandbox run:`);
-            log(`    export DECIDIO_API_URL=https://decidio-api.onrender.com`);
-            log(`  (or put that line in .env), then re-run this command.`);
+            err(`  You're pointed at localhost — for the hosted sandbox run:`);
+            err(`    export DECIDIO_API_URL=https://decidio-api.onrender.com`);
+            err(`  (or put that line in .env), then re-run this command.`);
         }
         else {
-            log(`  Check your network, then re-run. If the URL is wrong, set DECIDIO_API_URL and retry.`);
+            err(`  Check your network, then re-run. If the URL is wrong, set DECIDIO_API_URL and retry.`);
         }
         process.exit(1);
     }
@@ -72,6 +78,14 @@ function writeSecretFile(path, body) {
         chmodSync(path, 0o600);
     }
     catch { }
+    if (process.platform === "win32") {
+        try {
+            execFileSync("icacls", [path, "/inheritance:r", "/grant:r", `${process.env.USERNAME ?? process.env.USER ?? ""}:F`], { stdio: "ignore" });
+        }
+        catch {
+            console.warn(`⚠ could not restrict ${path} to owner-only on this Windows volume — it keeps the directory's inherited permissions. For production, move these values to a secret manager.`);
+        }
+    }
 }
 function upsertEnv(updates) {
     const cur = readEnvFile();
@@ -103,14 +117,14 @@ function ask(question, mute = false) {
 }
 async function acquireSession(purpose) {
     if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
-        log(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
+        err(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
         log(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
         return null;
     }
     if (process.env.DECIDIO_SESSION_TOKEN)
         return process.env.DECIDIO_SESSION_TOKEN;
     if (!process.stdin.isTTY) {
-        log(`✘ ${purpose} needs a Decidio workspace sign-in, and this terminal can't prompt for one.`);
+        err(`✘ ${purpose} needs a Decidio workspace sign-in, and this terminal can't prompt for one.`);
         log(`  Fix: set DECIDIO_SESSION_TOKEN and re-run. To mint one:`);
         log(`    1. Request a sign-in link from your workspace's sign-in screen (or use your welcome email).`);
         log(`    2. POST its ?login= value — the response's "token" is your session token:`);
@@ -151,7 +165,7 @@ async function cmdInit(agentId, opts = {}) {
     const existingKey = existingEnv.DECIDIO_AGENT_KEY;
     const sourceSystem = process.env.DECIDIO_SOURCE_SYSTEM || existingEnv.DECIDIO_SOURCE_SYSTEM;
     if (existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId && !opts.force) {
-        log(`✘ this directory's .env already holds the key for a DIFFERENT agent ("${existingEnv.DECIDIO_AGENT_ID}").`);
+        err(`✘ this directory's .env already holds the key for a DIFFERENT agent ("${existingEnv.DECIDIO_AGENT_ID}").`);
         log(`  Registering "${agentId}" here would overwrite that key — and a private key that is`);
         log(`  overwritten is gone for good (it never left this machine). Nothing was written.`);
         log(`  Pick one:`);
@@ -179,7 +193,7 @@ async function cmdInit(agentId, opts = {}) {
         }
         else {
             const suggestion = `${agentId}-${randomBytes(2).toString("hex")}`;
-            log(`✘ "${agentId}" is already registered in this workspace, and its private key is not on this machine`);
+            err(`✘ "${agentId}" is already registered in this workspace, and its private key is not on this machine`);
             log(`  (keys never leave the machine that generated them — likely a previous run, or another directory).`);
             log(`  Nothing was written. Two ways forward:`);
             log(`    1. Fresh agent (most common): npx @decidio/sdk init ${suggestion}`);
@@ -193,11 +207,11 @@ async function cmdInit(agentId, opts = {}) {
         log(`✔ registered (did ${did}) — key generated locally; only the public half went to Decidio`);
     }
     else {
-        log(`✘ registration failed (${r.status}): ${JSON.stringify(r.body)}`);
+        err(`✘ registration failed (${r.status}): ${JSON.stringify(r.body)}`);
         log(`  Fix the cause above and re-run — init is safe to repeat.`);
         return 1;
     }
-    let agentToken, workspaceId;
+    let agentToken, workspaceId, tokenJti;
     const mintBearer = session ?? TOKEN();
     if (mintBearer) {
         const expiresInDays = opts.expiresDays ?? 90;
@@ -205,10 +219,11 @@ async function cmdInit(agentId, opts = {}) {
         if (mint.status >= 200 && mint.status < 300 && mint.body?.token) {
             agentToken = mint.body.token;
             workspaceId = mint.body.workspaceId;
+            tokenJti = mint.body.jti;
             log(`✔ minted the agent's API token — floor-limited: it can request authorization, poll status and report confirmation; it cannot administer the workspace or approve anything${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ` (${expiresInDays} days)`}`);
         }
         else if (session) {
-            log(`✘ could not mint the agent's API token (${mint.status}): ${JSON.stringify(mint.body)}`);
+            err(`✘ could not mint the agent's API token (${mint.status}): ${JSON.stringify(mint.body)}`);
             log(`  Without it the SDK has no runtime credential. Fix the cause above and re-run init — it's safe to repeat.`);
             return 1;
         }
@@ -228,6 +243,8 @@ async function cmdInit(agentId, opts = {}) {
         envOut.DECIDIO_API_TOKEN = agentToken;
     if (workspaceId)
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
+    if (tokenJti)
+        envOut.DECIDIO_TOKEN_JTI = tokenJti;
     ensureGitignore();
     if (opts.force && existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId) {
         const backup = `.env.${existingEnv.DECIDIO_AGENT_ID.replace(/[^\w.-]/g, "_")}.bak`;
@@ -270,10 +287,11 @@ async function cmdDoctor() {
     const env = readEnvFile();
     let ok = true;
     const line = (good, label) => { log(`${good ? "✔" : "✘"} ${label}`); ok = ok && good; };
-    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)"}`);
+    log(`✔ API URL: ${API}${(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL) ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
     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 — 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");
+    log(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: not set — only needed for the operator resume-webhook transport; the poll worker guard.worker() is the self-serve resume path (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).");
@@ -286,11 +304,13 @@ async function cmdDoctor() {
         try {
             const payload = JSON.parse(Buffer.from(tok.split(".")[1] ?? "", "base64url").toString("utf8"));
             if (typeof payload?.exp === "number") {
-                const days = Math.floor((payload.exp * 1000 - Date.now()) / 86_400_000);
-                if (days < 0)
+                const msLeft = payload.exp * 1000 - Date.now();
+                const days = Math.floor(msLeft / 86_400_000);
+                const left = msLeft < 86_400_000 ? `${Math.max(1, Math.floor(msLeft / 3_600_000))} hour(s)` : `${days} day(s)`;
+                if (msLeft < 0)
                     line(false, `agent token: EXPIRED ${-days} day(s) ago — re-run \`npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}\` to mint a fresh one.`);
                 else if (days <= 14)
-                    log(`⚠ agent token: expires in ${days} day(s) — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
+                    log(`⚠ agent token: expires in ${left} — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
                 else
                     log(`✔ agent token: valid for another ${days} days`);
             }
@@ -319,6 +339,16 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
     const mineOnly = !!flags.mine;
     if (sub?.startsWith("--"))
         sub = undefined;
+    if ((sub === "approve" || sub === "reject") && !id) {
+        err(`usage: npx @decidio/sdk approvals ${sub} <decisionId> [reason]`);
+        return 2;
+    }
+    if (mineOnly && !process.env.DECIDIO_AGENT_ID) {
+        err(`✘ --mine needs an agent identity, and there is no DECIDIO_AGENT_ID in this directory's .env or your environment.`);
+        err(`  Run this from your agent's directory (where init wrote .env), or drop --mine for the workspace-wide list.`);
+        return 2;
+    }
+    const decisionArg = id ?? "";
     let bearer;
     const probe = await api("/api/decisions/cards");
     if (probe.status === 401 || probe.status === 403) {
@@ -328,11 +358,7 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
         bearer = session;
     }
     if (sub === "approve" || sub === "reject") {
-        if (!id) {
-            log(`usage: npx @decidio/sdk approvals ${sub} <decisionId> [reason]`);
-            return 2;
-        }
-        const r = await api(`/api/decisions/${encodeURIComponent(id)}/${sub === "approve" ? "approve" : "reject"}`, { method: "POST", body: JSON.stringify({ reason: reason ?? undefined }) }, bearer);
+        const r = await api(`/api/decisions/${encodeURIComponent(decisionArg)}/${sub === "approve" ? "approve" : "reject"}`, { method: "POST", body: JSON.stringify({ reason: reason ?? undefined }) }, bearer);
         if (r.status >= 200 && r.status < 300) {
             if (r.body?.alreadyResolved) {
                 log(`• ${id} was already resolved — nothing changed.`);
@@ -340,7 +366,7 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
                 log(`  See its sealed record: npx @decidio/sdk receipt ${id}`);
                 return 1;
             }
-            log(`✔ ${sub}d ${id}${r.body?.resumeSignal ? ` — agent signalled (${r.body.resumeSignal.ok ? "ok" : r.body.resumeSignal.error})` : ""}`);
+            log(`✔ ${sub === "approve" ? "approved" : "rejected"} ${id}${r.body?.resumeSignal ? ` — agent signalled (${r.body.resumeSignal.ok ? "ok" : r.body.resumeSignal.error})` : ""}`);
             if (sub === "approve")
                 log(`  The agent's function runs next — a blocking call resumes now; a durable one when its worker or resume route picks this up.`);
             else
@@ -349,30 +375,30 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
             return 0;
         }
         if (r.status === 404) {
-            log(`✘ no decision "${id}" in this workspace — check the id (npx @decidio/sdk approvals lists pending ones).`);
+            err(`✘ no decision "${id}" in this workspace — check the id (npx @decidio/sdk approvals lists pending ones).`);
             return 1;
         }
-        log(`✘ ${sub} failed (${r.status}): ${JSON.stringify(r.body)}`);
+        err(`✘ ${sub} failed (${r.status}): ${JSON.stringify(r.body).slice(0, 300)}`);
         return 1;
     }
     const r = bearer ? await api("/api/decisions/cards", {}, bearer) : probe;
     if (!(r.status >= 200 && r.status < 300)) {
-        log(`✘ could not list approvals (${r.status}): ${JSON.stringify(r.body)}`);
+        err(`✘ could not list approvals (${r.status}): ${JSON.stringify(r.body).slice(0, 300)}`);
         return 1;
     }
     const cards = r.body?.cards ?? [];
     const pending = cards.filter((c) => c.isAgentRequest && c.status !== "sealed");
+    const myAgent = process.env.DECIDIO_AGENT_ID;
+    const isMine = (c) => !!myAgent && typeof c.title === "string" && c.title.startsWith(`${myAgent}:`);
+    const shown = mineOnly ? pending.filter(isMine) : pending;
     if (jsonMode) {
-        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));
+        log(JSON.stringify(shown.map((c) => ({ decisionId: c.id, action: c.agentRequest?.action ?? null, amount: c.agentRequest?.amount ?? null, title: c.title ?? null })), null, 2));
         return 0;
     }
     if (!pending.length) {
         log("No pending agent approvals. Trigger one from your protected function, then re-run this.");
         return 0;
     }
-    const myAgent = process.env.DECIDIO_AGENT_ID;
-    const isMine = (c) => !!myAgent && typeof c.title === "string" && c.title.startsWith(`${myAgent}:`);
-    const shown = mineOnly ? pending.filter(isMine) : pending;
     if (mineOnly && !shown.length) {
         log(`No pending approvals for "${myAgent}" (${pending.length} pending elsewhere in this workspace — drop --mine to see them).`);
         return 0;
@@ -388,9 +414,9 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
 }
 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.");
+        err("usage: npx @decidio/sdk receipt <decisionId>");
+        err("  Downloads the decision's sealed Authority Receipt (a W3C Verifiable Credential) to a .json file.");
+        err("  Find decision ids via `npx @decidio/sdk approvals` or in your Decidio app.");
         return 2;
     }
     let bearer;
@@ -403,26 +429,26 @@ async function cmdReceipt(id, jsonMode = false) {
         r = await api(`/api/records/${encodeURIComponent(id)}/verify`, {}, bearer);
     }
     if (r.status === 404) {
-        log(`✘ no sealed record for "${id}" in this workspace.`);
-        log(`  Receipts exist once a decision is SEALED (approved or rejected). Still pending? npx @decidio/sdk approvals`);
+        err(`✘ no sealed record for "${id}" in this workspace.`);
+        err(`  Receipts exist once a decision is SEALED (approved or rejected). Still pending? npx @decidio/sdk approvals`);
         return 1;
     }
     if (!(r.status >= 200 && r.status < 300) || !r.body?.credential) {
-        log(`✘ could not fetch the receipt (${r.status}): ${JSON.stringify(r.body).slice(0, 300)}`);
+        err(`✘ could not fetch the receipt (${r.status}): ${JSON.stringify(r.body).slice(0, 300)}`);
         return 1;
     }
     const name = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     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.`);
+            err(`✘ ${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.`);
+        (jsonMode ? err : 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)`);
+        (jsonMode ? err : 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;
@@ -502,7 +528,7 @@ function chainOf(vcs, expectedIssuer) {
     let prev = null;
     let anchor = "segment";
     for (let i = 0; i < vcs.length; i++) {
-        const r = verifyReceipt(vcs[i], expectedIssuer);
+        const r = verifyReceiptDoor(vcs[i], expectedIssuer);
         if (!r.valid)
             return { valid: false, length: i, reason: `receipt ${i} (${r.recordId ?? "?"}) invalid: ${r.reason}` };
         const cs = vcs[i]?.credentialSubject ?? {};
@@ -514,22 +540,61 @@ function chainOf(vcs, expectedIssuer) {
     }
     return { valid: true, length: vcs.length, anchor };
 }
+function verifyReceiptDoor(vc, expectedIssuer) {
+    const res = verifyReceipt(vc, expectedIssuer);
+    if (!res.valid && res.reason === "issuer DID is not the expected issuer") {
+        const cs = vc?.credentialSubject ?? {};
+        const derive = (canonical, prevHash) => createHash("sha256").update((prevHash ?? "") + canonical).digest("hex");
+        const bound = typeof cs.recordCanonical === "string" && typeof cs.contentHash === "string"
+            && derive(cs.recordCanonical, typeof cs.prevHash === "string" ? cs.prevHash : null) === cs.contentHash;
+        return { ...res, contentBound: bound, recordId: typeof cs.recordId === "string" ? cs.recordId : res.recordId, reason: "issuer DID is not the expected issuer (the receipt itself may be internally consistent — it was just not issued by who you pinned)" };
+    }
+    return res;
+}
 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;
+    let expectedIssuer;
+    const files = [];
+    for (let i = 0; i < argsIn.length; i++) {
+        const a = argsIn[i];
+        if (a === "--issuer") {
+            const v = argsIn[i + 1];
+            if (v === undefined || v.startsWith("-")) {
+                err("✘ --issuer needs a did:key value.");
+                return 2;
+            }
+            expectedIssuer = v;
+            i++;
+        }
+        else if (a.startsWith("--issuer=")) {
+            const v = a.slice("--issuer=".length);
+            if (!v) {
+                err("✘ --issuer needs a did:key value.");
+                return 2;
+            }
+            expectedIssuer = v;
+        }
+        else if (!a.startsWith("-")) {
+            files.push(a);
+        }
     }
-    const expectedIssuer = issIdx >= 0 ? argsIn[issIdx + 1] : undefined;
-    const files = argsIn.filter((a, i) => !a.startsWith("--") && !(issIdx >= 0 && i === issIdx + 1));
     if (!files.length) {
-        log("usage: npx @decidio/sdk verify [--issuer <did:key>] <receipt.json> [more.json ...]");
-        log("  Verifies Authority Receipts OFFLINE — signature, content binding, and (for several files) chain order.");
+        err("usage: npx @decidio/sdk verify [--issuer <did:key>] <receipt.json> [more.json ...]");
+        err("  Verifies Authority Receipts OFFLINE — signature, content binding, and (for several files) chain order.");
         return 2;
     }
+    const texts = [];
+    for (const f of files) {
+        try {
+            texts.push(readFileSync(f, "utf8"));
+        }
+        catch (e) {
+            err(`✘ cannot read ${f}: ${e?.code === "ENOENT" ? "no such file" : e?.message ?? e} (nothing was verified)`);
+            return 1;
+        }
+    }
     let vcs;
     try {
-        vcs = files.map((f) => parseReceiptStrict(readFileSync(f, "utf8"), f));
+        vcs = files.map((f, i) => parseReceiptStrict(texts[i], f));
     }
     catch (e) {
         log(`✘ INVALID  ${String(e?.message ?? e)}`);
@@ -537,7 +602,7 @@ function cmdVerify(argsIn) {
     }
     let allOk = true;
     vcs.forEach((vc, i) => {
-        const res = verifyReceipt(vc, expectedIssuer);
+        const res = verifyReceiptDoor(vc, expectedIssuer);
         allOk = allOk && res.valid;
         log(`${res.valid ? "✔ VALID  " : "✘ INVALID"}  ${files[i]}`);
         log(`    record: ${res.recordId ?? "?"}   issuer: ${res.issuer}${expectedIssuer ? "" : "  (unpinned — pass --issuer to bind to your workspace's DID)"}`);
@@ -550,11 +615,15 @@ function cmdVerify(argsIn) {
     }
     return allOk ? 0 : 1;
 }
-async function cmdQuickstart() {
+async function cmdQuickstart(opts = {}) {
     const t0 = Date.now();
     log("Decidio quickstart — gate an action, route it to a human, execute on approval, hold the proof.");
     log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : "  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)"}`);
     log("");
+    log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
+    log("  write .env (or .env.quickstart) + .gitignore entries · create one synthetic decision");
+    log("  and its sealed record (records are permanent by design). Cleanup offer at the end.");
+    log("");
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
@@ -563,30 +632,40 @@ async function cmdQuickstart() {
     const { did, privateKeyBase64 } = generateKeypair();
     const reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
     if (!(reg.status >= 200 && reg.status < 300)) {
-        log(`✘ registration failed (${reg.status}): ${JSON.stringify(reg.body)}`);
+        err(`✘ registration failed (${reg.status}): ${JSON.stringify(reg.body)}`);
         return 1;
     }
     const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "quickstart", expiresInDays: 7 }) }, session);
     if (!(mint.status >= 200 && mint.status < 300) || !mint.body?.token) {
-        log(`✘ token mint failed (${mint.status}): ${JSON.stringify(mint.body)}`);
+        err(`✘ token mint failed (${mint.status}): ${JSON.stringify(mint.body)}`);
         return 1;
     }
     const envOut = {
         DECIDIO_API_URL: API, DECIDIO_AGENT_ID: agentId, DECIDIO_AGENT_DID: reg.body?.did ?? did,
         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"),
+        DECIDIO_WORKSPACE_ID: mint.body.workspaceId ?? "",
+        ...(mint.body.jti ? { DECIDIO_TOKEN_JTI: mint.body.jti } : {}),
     };
     let envFile = ENV_PATH;
     if (readEnvFile().DECIDIO_AGENT_KEY) {
         envFile = ".env.quickstart";
-        writeFileSync(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
+        ensureGitignore();
+        if (existsSync(envFile)) {
+            const prev = readFileSync(envFile, "utf8");
+            const prevId = prev.match(/^DECIDIO_AGENT_ID=(.+)$/m)?.[1];
+            if (prevId && prevId !== agentId) {
+                writeSecretFile(".env.quickstart.bak", prev);
+                log(`  ✔ previous tour agent (${prevId}) backed up to .env.quickstart.bak — its key would otherwise be unrecoverable`);
+            }
+        }
+        writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
         log(`  ✔ this directory already has an agent in .env — tour credentials went to ${envFile} (your agent is untouched)`);
     }
     else {
+        ensureGitignore();
         upsertEnv(envOut);
     }
-    ensureGitignore();
-    log(`  ✔ key generated locally (public half registered) · floor-limited token minted · ${envFile} written`);
+    log(`  ✔ key generated locally (public half registered) · 7-day floor-limited token minted${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ""} · ${envFile} written`);
     log("");
     log(`② Gating a demo action — the tour runs this (blocking mode: watch it live):`);
     log("");
@@ -603,26 +682,50 @@ async function cmdQuickstart() {
     };
     const payInvoice = withApproval(async (inv) => ({ paid: true, id: inv.id }), (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }), cfg);
     const running = payInvoice({ id: "INV-2026-001", amount: 86_000 });
-    running.catch(() => { });
+    let earlyError;
+    running.catch((e) => { earlyError = e; });
     const waitStart = Date.now();
-    while (!decisionId && Date.now() - waitStart < 30_000)
+    while (!decisionId && !earlyError && Date.now() - waitStart < 30_000)
         await new Promise((r) => setTimeout(r, 250));
+    if (!decisionId && earlyError instanceof DecidioRateLimitError) {
+        err(`✘ this workspace's governed-action allowance is used up${earlyError.limit != null ? ` (${earlyError.limit} actions/hour on lab workspaces)` : ""}.`);
+        err(`  Nothing was routed or executed — the cap is the sandbox protecting itself, not a fault${earlyError.resetAt ? `. It resets ${earlyError.resetAt}` : ""}.`);
+        err(`  Re-run the tour after the reset (or talk to us about a production workspace).`);
+        return 1;
+    }
+    if (!decisionId && earlyError) {
+        err(`✘ the gate refused before routing: ${earlyError?.message ?? earlyError}`);
+        return 1;
+    }
     if (!decisionId) {
-        log("✘ the gate did not route within 30s — check connectivity (npx @decidio/sdk doctor) and re-run.");
+        err("✘ the gate did not route within 30s — check connectivity (npx @decidio/sdk doctor) and re-run.");
         return 1;
     }
     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("");
-    if (process.stdin.isTTY) {
+    const interactive = process.stdin.isTTY;
+    if (interactive) {
         await ask(`③ YOU are the approver. Press Enter to approve it here (or approve it in your Decidio queue first, then Enter): `);
     }
+    else if (opts.autoApproveDemo) {
+        log("③ --auto-approve-demo: approving with 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 {
-        log("③ Headless terminal — auto-approving with your session so the tour can continue.");
+        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:");
+        log("");
+        log(`     npx @decidio/sdk approvals approve ${decisionId}     (or approve it in your Decidio app)`);
+        log("");
+        log("   Then re-run the quickstart interactively to watch the whole loop — or, for CI, re-run");
+        log("   with --auto-approve-demo to let the tour approve itself under that explicit label.");
+        log(`   Tidy up this tour's agent + token any time: npx @decidio/sdk quickstart cleanup`);
+        process.exit(0);
     }
-    const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: "quickstart" }) }, session);
+    const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
     if (!(ap.status >= 200 && ap.status < 300)) {
-        log(`✘ approve failed (${ap.status}): ${JSON.stringify(ap.body)}`);
+        err(`✘ approve failed (${ap.status}): ${JSON.stringify(ap.body)}`);
         return 1;
     }
     log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
@@ -631,7 +734,7 @@ async function cmdQuickstart() {
         result = await running;
     }
     catch (e) {
-        log(`✘ the gated call did not complete: ${e?.message ?? e}`);
+        err(`✘ the gated call did not complete: ${e?.message ?? e}`);
         return 1;
     }
     log(`  ✔ your function executed AFTER approval: ${JSON.stringify(result)}`);
@@ -639,7 +742,7 @@ async function cmdQuickstart() {
     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) {
-        log(`✘ receipt fetch failed (${rec.status})`);
+        err(`✘ receipt fetch failed (${rec.status})`);
         return 1;
     }
     const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
@@ -663,8 +766,129 @@ async function cmdQuickstart() {
     log(`  // production is DURABLE mode (default) + one worker: guard.worker();  // README has the full pattern`);
     log("");
     log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}  ·  Next: the README's 7-step quickstart (durable, workers, adapters).`);
+    let doCleanup = false;
+    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)
+            log(`  Kept. Tidy up any time: npx @decidio/sdk quickstart cleanup`);
+    }
+    else if (opts.autoApproveDemo && !opts.keepAgent) {
+        doCleanup = true;
+        log(`\nAutomated run: cleaning the tour up (pass --keep-agent to keep the agent + token).`);
+    }
+    if (doCleanup)
+        await quickstartCleanup(session, envFile);
     return v.valid ? 0 : 1;
 }
+async function quickstartCleanup(session, envFile) {
+    const env = (() => {
+        const out = {};
+        if (existsSync(envFile))
+            for (const line of readFileSync(envFile, "utf8").split(/\r?\n/)) {
+                const m = line.match(/^\s*([A-Z_]+)=(.*)$/);
+                if (m)
+                    out[m[1]] = m[2];
+            }
+        return out;
+    })();
+    if (env.DECIDIO_TOKEN_JTI) {
+        const rev = await api(`/api/workspace/agent-token/${encodeURIComponent(env.DECIDIO_TOKEN_JTI)}`, { method: "DELETE" }, session);
+        if (rev.status >= 200 && rev.status < 300)
+            log(`  ✔ token revoked (jti ${env.DECIDIO_TOKEN_JTI})`);
+        else
+            log(`  ⚠ token revoke returned ${rev.status} — it still expires on its own within 7 days. List tokens: npx @decidio/sdk tokens list`);
+    }
+    else {
+        log(`  ⚠ no DECIDIO_TOKEN_JTI in ${envFile} (older tour) — revoke by hand: npx @decidio/sdk tokens list, then tokens revoke <jti>. It expires on its own within 7 days.`);
+    }
+    if (existsSync(envFile)) {
+        const TOUR_KEYS = new Set(["DECIDIO_API_URL", "DECIDIO_AGENT_ID", "DECIDIO_AGENT_DID", "DECIDIO_AGENT_KEY", "DECIDIO_API_TOKEN", "DECIDIO_WORKSPACE_ID", "DECIDIO_TOKEN_JTI"]);
+        const kept = readFileSync(envFile, "utf8").split(/\r?\n/).filter((line) => {
+            const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)=/);
+            return m ? !TOUR_KEYS.has(m[1]) : line.trim() !== "";
+        });
+        if (kept.length === 0) {
+            rmSync(envFile);
+            log(`  ✔ ${envFile} deleted (the agent's local key is gone — the registered agent is now inert)`);
+        }
+        else {
+            writeSecretFile(envFile, kept.join("\n") + "\n");
+            log(`  ✔ tour credentials removed from ${envFile} — its ${kept.length} other line${kept.length === 1 ? "" : "s"} untouched (the agent's local key is gone — the registered agent is now inert)`);
+        }
+    }
+    const tourAgent = env.DECIDIO_AGENT_ID;
+    if (tourAgent) {
+        const cards = await api("/api/decisions/cards", {}, session);
+        const stranded = (cards.body?.cards ?? []).filter((c) => c.isAgentRequest && c.status !== "sealed" && typeof c.title === "string" && c.title.startsWith(`${tourAgent}:`));
+        for (const c of stranded) {
+            log(`  ⚠ this tour's decision ${c.id} is still PENDING in your workspace queue — clear it with:`);
+            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).`);
+    return 0;
+}
+async function cmdTokens(sub, jti) {
+    if (sub !== "list" && sub !== "revoke") {
+        err("usage: npx @decidio/sdk tokens list");
+        err("       npx @decidio/sdk tokens revoke <jti>");
+        err("  Agent tokens are shown by jti (their revocation id) — the token VALUE is never shown again after minting.");
+        return 2;
+    }
+    if (sub === "revoke" && !jti) {
+        err("usage: npx @decidio/sdk tokens revoke <jti>   (find the jti with: npx @decidio/sdk tokens list)");
+        return 2;
+    }
+    let bearer;
+    let r = await api("/api/workspace/agent-token");
+    if (r.status === 401 || r.status === 403) {
+        const session = await acquireSession("Managing tokens");
+        if (!session)
+            return 1;
+        bearer = session;
+        if (sub === "list")
+            r = await api("/api/workspace/agent-token", {}, bearer);
+    }
+    if (sub === "revoke") {
+        const rev = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, bearer);
+        if (rev.status >= 200 && rev.status < 300) {
+            if (rev.body?.changed === false) {
+                log(`• ${jti} was already revoked — nothing changed.`);
+                log(`  Revocation is permanent; there is no re-revoke. See it: npx @decidio/sdk tokens list`);
+                return 1;
+            }
+            log(`✔ revoked ${jti} — the token is dead now (its agent stays registered; mint a new one with init).`);
+            return 0;
+        }
+        if (rev.status === 404) {
+            err(`✘ no token with jti "${jti}" — list them: npx @decidio/sdk tokens list`);
+            return 1;
+        }
+        err(`✘ revoke failed (${rev.status}): ${JSON.stringify(rev.body).slice(0, 300)}`);
+        return 1;
+    }
+    if (!(r.status >= 200 && r.status < 300)) {
+        err(`✘ could not list tokens (${r.status}): ${JSON.stringify(r.body).slice(0, 300)}`);
+        return 1;
+    }
+    const tokens = r.body?.tokens ?? r.body ?? [];
+    if (!Array.isArray(tokens) || !tokens.length) {
+        log("No agent tokens in this workspace.");
+        return 0;
+    }
+    const status = (t) => t.revokedAt ? `REVOKED ${String(t.revokedAt).slice(0, 10)}`
+        : (t.expiresAt && Date.parse(t.expiresAt) < Date.now()) ? "expired" : "active";
+    log(`Agent tokens (${tokens.length}):`);
+    for (const t of tokens)
+        log(`  ${t.jti}  ${status(t)}  agent=${t.agentId ?? "?"}  label=${t.label ?? ""}  expires=${t.expiresAt ?? "?"}`);
+    const al = r.body?.allowance;
+    if (al?.limit != null)
+        log(`\nGoverned-action allowance: ${al.remaining}/${al.limit} remaining this hour${al.resetAt ? ` (resets ${al.resetAt})` : ""}.`);
+    log(`\nRevoke one:  npx @decidio/sdk tokens revoke <jti>`);
+    return 0;
+}
 function cmdDev(target, port) {
     log(`decidio dev relay on http://localhost:${port}/decidio/resume → forwarding to ${target}`);
     createServer((req, res) => {
@@ -701,6 +925,13 @@ const USAGE = `decidio — the Decidio SDK command line
   in, or writes files unless you ask it to.)
 
   npx @decidio/sdk quickstart          the guided two-minute tour: gate → approve → execute → proof
+                                       (interactive: YOUR Enter is the approval. Headless it stops
+                                       at the routed decision; --auto-approve-demo for CI, labeled
+                                       automated; ends with a keep-or-cleanup choice)
+  npx @decidio/sdk quickstart cleanup  revoke the tour's token + delete its local credentials
+  npx @decidio/sdk tokens list         agent tokens with status (active/expired/REVOKED) by jti —
+                                       token values are never re-shown
+  npx @decidio/sdk tokens revoke <jti> kill a token now instead of waiting out its lifetime
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
                                        --unique  append a random suffix (collision-proof samples)
                                        --force   replace a different agent already in this .env
@@ -715,12 +946,15 @@ const USAGE = `decidio — the Decidio SDK command line
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
   npx @decidio/sdk --version           print the CLI version
 
+Every command talks to the hosted sandbox (https://decidio-api.onrender.com) unless
+DECIDIO_API_URL says otherwise; the target host is announced on stderr each run.
 Exit codes: 0 success · 1 failure or honest no-op (e.g. replay refused) · 2 usage error.
+Errors and usage go to stderr; stdout carries results only (safe to pipe).
 Docs: the README that shipped with this package (quickstart, durable resume, adapters).`;
 async function main(argv) {
     const [cmd, a, b, ...rest] = argv.slice(2);
     const wantsHelp = (s) => s === "help" || s === "--help" || s === "-h";
-    if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+    if (cmd === "--version" || cmd === "-v" || cmd === "-V" || cmd === "version") {
         log(VERSION);
         return 0;
     }
@@ -732,15 +966,80 @@ async function main(argv) {
         log(USAGE);
         return 0;
     }
+    const argsIn = argv.slice(3);
+    const KNOWN = {
+        quickstart: { flags: ["--auto-approve-demo", "--keep-agent"] },
+        init: { flags: ["--unique", "--force"], valued: ["--expires-days"] },
+        doctor: { flags: [] },
+        approvals: { flags: ["--json", "--mine"] },
+        receipt: { flags: ["--json"] },
+        verify: { flags: [], valued: ["--issuer"] },
+        tokens: { flags: [] },
+        dev: { flags: [], valued: ["--target", "--port"] },
+    };
+    const spec = KNOWN[cmd];
+    if (spec) {
+        const valued = spec.valued ?? [];
+        const positionals = [];
+        for (let i = 0; i < argsIn.length; i++) {
+            const a = argsIn[i];
+            if (!a.startsWith("--")) {
+                positionals.push(a);
+                continue;
+            }
+            if (valued.includes(a)) {
+                i++;
+                continue;
+            }
+            if (valued.some((v) => a.startsWith(v + "=")))
+                continue;
+            if (!spec.flags.includes(a)) {
+                err(`✘ unknown option "${a}" for \`${cmd}\` — refusing to guess (a flag you meant to matter must never be silently ignored).\n\n${USAGE}`);
+                return 2;
+            }
+        }
+        const MAX_POS = { quickstart: 1, init: 1, doctor: 0, receipt: 1, tokens: 2, dev: 0 };
+        const exemptTail = (cmd === "approvals" && (positionals[0] === "approve" || positionals[0] === "reject")) || cmd === "verify";
+        if (!exemptTail && cmd === "approvals" && positionals.length > 0) {
+            err(`✘ unknown approvals subcommand "${positionals[0]}" — use approve or reject (or no subcommand to list).`);
+            return 2;
+        }
+        if (!exemptTail && MAX_POS[cmd] !== undefined && positionals.length > MAX_POS[cmd]) {
+            err(`✘ unexpected argument "${positionals[MAX_POS[cmd]]}" for \`${cmd}\` — refusing to guess (an argument you meant to matter must never be silently ignored).\n\n${USAGE}`);
+            return 2;
+        }
+        if (cmd === "quickstart" && positionals.length === 1 && positionals[0] !== "cleanup") {
+            err(`✘ unknown quickstart subcommand "${positionals[0]}" — the only one is: npx @decidio/sdk quickstart cleanup`);
+            return 2;
+        }
+        if (cmd === "tokens" && positionals[0] === "list" && positionals.length > 1) {
+            err(`✘ unexpected argument "${positionals[1]}" for \`tokens list\` — it takes none (an argument you meant to matter must never be silently ignored).`);
+            return 2;
+        }
+    }
     switch (cmd) {
-        case "quickstart": return cmdQuickstart();
+        case "quickstart": {
+            if (argsIn.includes("cleanup")) {
+                const envFile = existsSync(".env.quickstart") ? ".env.quickstart"
+                    : (readEnvFile().DECIDIO_AGENT_ID ?? "").startsWith("quickstart-") ? ENV_PATH : undefined;
+                if (!envFile) {
+                    log("Nothing to clean up here: no .env.quickstart, and .env doesn't belong to a quickstart agent.");
+                    return 0;
+                }
+                const session = await acquireSession("Cleaning the quickstart up");
+                if (!session)
+                    return 1;
+                return quickstartCleanup(session, envFile);
+            }
+            return cmdQuickstart({ autoApproveDemo: argsIn.includes("--auto-approve-demo"), keepAgent: argsIn.includes("--keep-agent") });
+        }
         case "init": {
-            const argsIn = argv.slice(3);
             const unique = argsIn.includes("--unique");
             const expIdx = argsIn.indexOf("--expires-days");
-            const expRaw = expIdx >= 0 ? argsIn[expIdx + 1] : undefined;
-            if (expIdx >= 0 && (!expRaw || !/^\d+$/.test(expRaw) || Number(expRaw) < 1)) {
-                log("✘ --expires-days needs a positive whole number of days (e.g. --expires-days 30).");
+            const expEq = argsIn.find((x) => x.startsWith("--expires-days="));
+            const expRaw = expIdx >= 0 ? argsIn[expIdx + 1] : expEq ? expEq.slice("--expires-days=".length) : undefined;
+            if ((expIdx >= 0 || expEq) && (!expRaw || !/^\d+$/.test(expRaw) || Number(expRaw) < 1)) {
+                err("✘ --expires-days needs a positive whole number of days (e.g. --expires-days 30).");
                 return 2;
             }
             const nameArg = argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
@@ -751,25 +1050,38 @@ async function main(argv) {
         }
         case "doctor": return cmdDoctor();
         case "approvals": {
-            const argsIn = argv.slice(3);
             const positional = argsIn.filter((x) => !x.startsWith("-"));
             return cmdApprovals(positional[0], positional[1], positional.slice(2).join(" ") || undefined, { json: argsIn.includes("--json"), mine: argsIn.includes("--mine") });
         }
-        case "receipt": {
-            const argsIn = argv.slice(3);
-            return cmdReceipt(argsIn.find((x) => !x.startsWith("-")), argsIn.includes("--json"));
+        case "receipt": return cmdReceipt(argsIn.find((x) => !x.startsWith("-")), argsIn.includes("--json"));
+        case "verify": return cmdVerify(argsIn);
+        case "tokens": {
+            const positional = argsIn.filter((x) => !x.startsWith("-"));
+            return cmdTokens(positional[0], positional[1]);
         }
-        case "verify": return cmdVerify(argv.slice(3));
         case "dev": {
-            const args = argv.slice(3);
-            const flag = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+            const flag = (name) => {
+                const i = argsIn.indexOf(name);
+                if (i >= 0)
+                    return argsIn[i + 1];
+                const eq = argsIn.find((x) => x.startsWith(name + "="));
+                return eq ? eq.slice(name.length + 1) : undefined;
+            };
             const target = flag("--target") || process.env.DECIDIO_AGENT_RESUME_URL || "http://localhost:4100/decidio/resume";
-            const port = Number(flag("--port") || process.env.DECIDIO_DEV_PORT || 4099);
-            return cmdDev(target, port);
+            const portRaw = flag("--port") || process.env.DECIDIO_DEV_PORT || "4099";
+            if (!/^\d+$/.test(portRaw) || Number(portRaw) < 1 || Number(portRaw) > 65535) {
+                err(`✘ --port needs a number between 1 and 65535 (got "${portRaw}").`);
+                return 2;
+            }
+            if (!/^https?:\/\//.test(target)) {
+                err(`✘ --target needs an http(s) URL to forward the webhook to (got "${target}").`);
+                return 2;
+            }
+            return cmdDev(target, Number(portRaw));
         }
         default:
-            log(`✘ unknown command "${cmd}"\n\n${USAGE}`);
-            return 1;
+            err(`✘ unknown command "${cmd}"\n\n${USAGE}`);
+            return 2;
     }
 }
 main(process.argv).then((code) => { if (code !== 0)

package/dist/index.d.ts

@@ -45,6 +45,12 @@ export declare class DecidioTimeoutError extends Error {
     decisionId: string;
     constructor(decisionId: string);
 }
+export declare class DecidioRateLimitError extends Error {
+    limit: number | undefined;
+    remaining: number | undefined;
+    resetAt: string | undefined;
+    constructor(limit: number | undefined, remaining: number | undefined, resetAt: string | undefined, serverMessage?: string);
+}
 export declare class DecidioNetworkError extends Error {
     endpoint: string;
     op: string;

package/dist/index.js

@@ -32,12 +32,28 @@ export class DecidioTimeoutError extends Error {
     }
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class DecidioRateLimitError extends Error {
+    limit;
+    remaining;
+    resetAt;
+    constructor(limit, remaining, resetAt, serverMessage) {
+        super(`[decidio] governed-action rate limit reached${limit != null ? ` (${limit}/hour on this workspace)` : ""}${resetAt ? ` — resets ${resetAt}` : ""}. ` +
+            `${serverMessage ? serverMessage + " " : ""}Nothing was routed or executed; retry after the reset.`);
+        this.limit = limit;
+        this.remaining = remaining;
+        this.resetAt = resetAt;
+        this.name = "DecidioRateLimitError";
+    }
+}
 export class DecidioNetworkError extends Error {
     endpoint;
     op;
     code;
     constructor(endpoint, op, code, cause) {
         super(`[decidio] could not reach ${endpoint} during ${op}${code ? ` (${code})` : ""}. ` +
+            (/localhost|127\.0\.0\.1/.test(endpoint) && code === "ECONNREFUSED"
+                ? `A refused localhost connection usually means the SDK never saw your config: if your settings live in .env, run node with --env-file=.env (or export DECIDIO_API_URL — the hosted sandbox is https://decidio-api.onrender.com). `
+                : "") +
             `Nothing was executed locally and no verdict was received — if a request reached Decidio it is ` +
             `visible in your queue. Check the network/URL (DECIDIO_API_URL) and retry; retrying is safe ` +
             `(a retry creates a new request — it can never double-execute).`);
@@ -63,6 +79,10 @@ async function post(cfg, path, body) {
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
         body: JSON.stringify(body),
     });
+    if (res.status === 429) {
+        const b = await res.json().catch(() => null);
+        throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message);
+    }
     if (!res.ok)
         throw new Error(`decidio ${path} ${res.status}: ${await res.text().catch(() => "")}`);
     return res.json();

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.7
+  version: 0.1.8
   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.1.7",
+  "version": "0.1.8",
   "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",
@@ -81,7 +81,7 @@
     "prepublishOnly": "npm run typecheck && npm run build"
   },
   "dependencies": {
-    "@decidio/verify": "^0.1.3"
+    "@decidio/verify": "0.1.7"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {