workpads.js

#!/usr/bin/env node

const fs = require("fs");
const path = require("path");
const http = require("http");
const net = require("net");
const { URL } = require("url");
const { spawnSync } = require("child_process");
const zlib   = require("zlib");
const crypto = require("crypto");
const WPCodec = require("@workpads/codec");

const ROOT = __dirname;
const DATA_DIR = path.join(ROOT, ".workpads");
const RECORDS_FILE = path.join(DATA_DIR, "records.json");
const STORAGE_POLICIES_FILE = path.join(DATA_DIR, "storage-policies.json");
const BROWSER_STATE_FILE = path.join(DATA_DIR, "browser-state.json");
const DEFAULT_TEMPLATE_PATH = path.join(
  ROOT,
  "templates",
  "runtime",
  "svc-basic.v1.json"
);
const DEFAULT_BASE_URL = "https://workpads.me/p";

// ── ANSI colour ───────────────────────────────────────────────────────────────
const TTY = process.stdout.isTTY;
const C = TTY ? {
  reset:  "\x1b[0m",
  bold:   "\x1b[1m",
  faint:  "\x1b[2m",
  signal: "\x1b[36m",   // teal  — IDs, URLs, codec info
  warm:   "\x1b[33m",   // amber — action numbers
  green:  "\x1b[32m",   // green — status / valid
  gold:   "\x1b[93m",   // gold  — warnings
  red:    "\x1b[31m",   // red   — errors
} : Object.fromEntries(
  ["reset","bold","faint","signal","warm","green","gold","red"].map(k => [k, ""])
);

function clr(k, t) { return C[k] + t + C.reset; }
function rule(w) { return "─".repeat(w || 66); }

function wrapIndent(text, indent, width) {
  const words = String(text || "").split(" ");
  const lines = [];
  let line = "";
  for (const w of words) {
    if (line && (indent + line + " " + w).length > width) {
      lines.push(indent + line);
      line = w;
    } else {
      line = line ? line + " " + w : w;
    }
  }
  if (line) lines.push(indent + line);
  return lines.join("\n");
}

function toNumber(value, fallback = 0) {
  const n = Number(value);
  return Number.isNaN(n) ? fallback : n;
}

function parseArgs(argv) {
  const args = { _: [] };
  for (let i = 0; i < argv.length; i += 1) {
    const part = argv[i];
    if (part.startsWith("--")) {
      const key = part.slice(2);
      const next = argv[i + 1];
      if (!next || next.startsWith("--")) {
        args[key] = true;
      } else {
        if (args[key] === undefined) {
          args[key] = next;
        } else if (Array.isArray(args[key])) {
          args[key].push(next);
        } else {
          args[key] = [args[key], next];
        }
        i += 1;
      }
    } else {
      args._.push(part);
    }
  }
  return args;
}

function ensureStore() {
  fs.mkdirSync(DATA_DIR, { recursive: true });
  if (!fs.existsSync(RECORDS_FILE)) {
    fs.writeFileSync(RECORDS_FILE, JSON.stringify([], null, 2));
  }
  if (!fs.existsSync(STORAGE_POLICIES_FILE)) {
    fs.writeFileSync(STORAGE_POLICIES_FILE, JSON.stringify({}, null, 2));
  }
}

function loadBrowserState() {
  ensureStore();
  if (!fs.existsSync(BROWSER_STATE_FILE)) return null;
  try {
    return JSON.parse(fs.readFileSync(BROWSER_STATE_FILE, "utf8"));
  } catch (_) {
    return null;
  }
}

function saveBrowserState(state) {
  ensureStore();
  fs.writeFileSync(BROWSER_STATE_FILE, JSON.stringify(state, null, 2));
}

function clearBrowserState() {
  try {
    if (fs.existsSync(BROWSER_STATE_FILE)) fs.unlinkSync(BROWSER_STATE_FILE);
  } catch (_) {}
}

function loadTemplate(templatePath = DEFAULT_TEMPLATE_PATH) {
  return JSON.parse(fs.readFileSync(templatePath, "utf8"));
}

function loadRecords() {
  ensureStore();
  return JSON.parse(fs.readFileSync(RECORDS_FILE, "utf8"));
}

function saveRecords(records) {
  ensureStore();
  fs.writeFileSync(RECORDS_FILE, JSON.stringify(records, null, 2));
}

function loadStoragePolicies() {
  ensureStore();
  return JSON.parse(fs.readFileSync(STORAGE_POLICIES_FILE, "utf8"));
}

function saveStoragePolicies(policies) {
  ensureStore();
  fs.writeFileSync(STORAGE_POLICIES_FILE, JSON.stringify(policies, null, 2));
}

function readKvFile(filePath) {
  const lines = fs
    .readFileSync(filePath, "utf8")
    .split("\n")
    .map((line) => line.trim())
    .filter((line) => line && !line.startsWith("#"));
  const out = {};
  for (const line of lines) {
    const idx = line.indexOf(":");
    if (idx < 0) continue;
    const key = line.slice(0, idx).trim();
    const value = line.slice(idx + 1).trim();
    if (!out[key]) out[key] = [];
    out[key].push(value);
  }
  return out;
}

function parseKvTemplate(filePath) {
  const parsed = readKvFile(filePath);
  const templateId = parsed.template_id && parsed.template_id[0];
  const version = toNumber(parsed.version && parsed.version[0], 1);
  const title = parsed.title && parsed.title[0];
  const variants = parsed.variants ? parsed.variants[0].split(",").map((v) => v.trim()).filter(Boolean) : [];
  const pads = parsed.pads ? parsed.pads[0].split(",").map((v) => v.trim()).filter(Boolean) : [];
  const fieldLines = parsed.field || [];
  const fields = fieldLines.map((line) => {
    const parts = line.split("|").map((x) => x.trim());
    const field = {
      id: parts[0],
      label: parts[1],
      type: parts[2],
      required: parts[3] === "required",
      max: null,
      pad: null,
      key: null
    };
    for (let i = 4; i < parts.length; i += 1) {
      const p = parts[i];
      if (p.startsWith("max=")) field.max = toNumber(p.slice(4), null);
      if (p.startsWith("pad=")) field.pad = p.slice(4);
      if (p.startsWith("key=")) field.key = p.slice(4);
    }
    return field;
  });
  return normalizeTemplate({
    template_id: templateId,
    version,
    title,
    variants,
    pads,
    fields
  });
}

function parseYamlTemplate(filePath) {
  const raw = fs.readFileSync(filePath, "utf8");
  const lines = raw.split("\n");
  const out = { variants: [], pads: [], fields: [] };
  let section = "";
  let currentField = null;

  function pushField() {
    if (!currentField) return;
    if (currentField.required === undefined) currentField.required = false;
    if (currentField.max !== undefined) currentField.max = toNumber(currentField.max, null);
    out.fields.push(currentField);
    currentField = null;
  }

  for (const line of lines) {
    const trimmed = line.trim();
    if (!trimmed || trimmed.startsWith("#")) continue;

    if (trimmed === "variants:") {
      pushField();
      section = "variants";
      continue;
    }
    if (trimmed === "pads:") {
      pushField();
      section = "pads";
      continue;
    }
    if (trimmed === "fields:") {
      pushField();
      section = "fields";
      continue;
    }

    if (section === "variants" && trimmed.startsWith("- ")) {
      out.variants.push(trimmed.slice(2).trim());
      continue;
    }
    if (section === "pads" && trimmed.startsWith("- ")) {
      out.pads.push(trimmed.slice(2).trim());
      continue;
    }

    if (section === "fields") {
      if (trimmed.startsWith("- ")) {
        pushField();
        currentField = {};
        const maybePair = trimmed.slice(2).trim();
        if (maybePair.includes(":")) {
          const idx = maybePair.indexOf(":");
          const k = maybePair.slice(0, idx).trim();
          const v = maybePair.slice(idx + 1).trim();
          currentField[k] = parseYamlScalar(v);
        }
        continue;
      }
      if (currentField && trimmed.includes(":")) {
        const idx = trimmed.indexOf(":");
        const k = trimmed.slice(0, idx).trim();
        const v = trimmed.slice(idx + 1).trim();
        currentField[k] = parseYamlScalar(v);
        continue;
      }
    }

    if (trimmed.includes(":")) {
      const idx = trimmed.indexOf(":");
      const key = trimmed.slice(0, idx).trim();
      const value = trimmed.slice(idx + 1).trim();
      out[key] = parseYamlScalar(value);
    }
  }

  pushField();
  return normalizeTemplate(out);
}

function parseYamlScalar(value) {
  if (value === "true") return true;
  if (value === "false") return false;
  if (/^\d+$/.test(value)) return toNumber(value, 0);
  return value.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
}

function normalizeTemplate(input) {
  const templateId = input.template_id || input.templateId;
  const version = toNumber(input.version, 1);
  const title = input.title;
  const variants = Array.isArray(input.variants) ? input.variants : [];
  const pads = Array.isArray(input.pads) ? input.pads : ["process", "actions", "details", "story"];
  const fields = Array.isArray(input.fields) ? input.fields : [];

  if (!templateId) throw new Error("Template missing template_id");
  if (!title) throw new Error("Template missing title");
  if (!Array.isArray(variants) || variants.length === 0) throw new Error("Template missing variants");
  if (!Array.isArray(fields) || fields.length === 0) throw new Error("Template missing fields");

  const compactKeys = {};
  const normalizedFields = fields.map((f) => {
    if (!f.id || !f.type || !f.label) {
      throw new Error(`Invalid field entry: ${JSON.stringify(f)}`);
    }
    const out = {
      id: f.id,
      label: f.label,
      type: f.type,
      required: Boolean(f.required),
      max: f.max === null || f.max === undefined ? null : toNumber(f.max, null),
      pad: f.pad || null
    };
    if (f.key) compactKeys[f.id] = f.key;
    return out;
  });

  return {
    templateId,
    version,
    title,
    variants,
    pads,
    compactKeys,
    fields: normalizedFields
  };
}

function parseTemplateFile(filePath, format) {
  if (format === "kv") return parseKvTemplate(filePath);
  if (format === "yaml") return parseYamlTemplate(filePath);
  throw new Error(`Unsupported format: ${format}`);
}

function parseKeyValuePairs(setValue) {
  if (!setValue) return [];
  if (Array.isArray(setValue)) return setValue;
  return [setValue];
}

// FLAGS3 field names — shorthand accepted in --set without namespace prefix
const FLAGS3_KEYS = ["context_label","tag","qty_unit","date_end","attachment","uid","url"];

function applySetPairs(record, pairs) {
  for (const pair of pairs) {
    const idx = pair.indexOf("=");
    if (idx < 0) continue;
    const key = pair.slice(0, idx).trim();
    const value = pair.slice(idx + 1).trim();
    if (key.startsWith("process.")) {
      record.process[key.replace("process.", "")] = value;
    } else if (key.startsWith("financial.")) {
      if (!record.financial) record.financial = {};
      record.financial[key.replace("financial.", "")] = value;
    } else if (key.startsWith("flags3.")) {
      if (!record.flags3) record.flags3 = {};
      record.flags3[key.replace("flags3.", "")] = value;
    } else if (key.startsWith("agreement.")) {
      if (!record.agreement) record.agreement = {};
      record.agreement[key.replace("agreement.", "")] = value;
    } else if (key === "details" || key === "story") {
      record[key] = value;
    } else if (key.startsWith("flags4.")) {
      if (!record.flags4) record.flags4 = {};
      record.flags4[key.replace("flags4.", "")] = value;
    } else if (FLAGS3_KEYS.includes(key)) {
      if (!record.flags3) record.flags3 = {};
      record.flags3[key] = value;
    } else if (FLAGS4_CONTACT_KEYS.includes(key) || FLAGS4_FINANCIAL_KEYS.includes(key)) {
      if (!record.flags4) record.flags4 = {};
      record.flags4[key] = value;
    } else {
      record.process[key] = value;
    }
  }
}

function flattenForCodec(record) {
  const flat = Object.assign({}, record.process || {});
  if (record.details) flat.details = record.details;
  if (record.story)   flat.story   = record.story;
  if (Array.isArray(record.actions) && record.actions.length > 0) flat.actions = record.actions;
  // FLAGS3 and FLAGS4 fields passed directly (codec picks up by name)
  if (record.flags3) Object.assign(flat, record.flags3);
  if (record.flags4) Object.assign(flat, record.flags4);
  return flat;
}

function unflattenFromCodec(flat) {
  const PROCESS_FIELDS = ["job","customer","date","location","meeting_time","start_time","end_time","customer_phone","worker"];
  const proc = {};
  PROCESS_FIELDS.forEach((k) => { if (flat[k] != null) proc[k] = flat[k]; });
  let actions = [];
  if (Array.isArray(flat.actions)) {
    actions = flat.actions;
  } else if (typeof flat.actions === "string" && flat.actions) {
    actions = flat.actions.split("\n").filter(Boolean).map((t) => ({ title: t, notes: "" }));
  }
  const flags3 = {};
  FLAGS3_KEYS.forEach((k) => { if (flat[k] != null) flags3[k] = flat[k]; });
  return {
    process: proc,
    actions,
    details: flat.details || "",
    story: flat.story || "",
    ...(Object.keys(flags3).length ? { flags3 } : {}),
  };
}

function normalizeRecordComments(record) {
  if (!Array.isArray(record.comments)) record.comments = [];
  record.comments = record.comments.map((c) => {
    if (typeof c === "string") {
      return { n: "", x: c, ts: new Date().toISOString() };
    }
    return {
      n: c.n || "",
      x: c.x || "",
      ts: c.ts || new Date().toISOString()
    };
  });
}

function buildShareLinkForRecord(record) {
  const flat = flattenForCodec(record);
  const link = WPCodec.encode(flat);
  return { link, bytes: Buffer.byteLength(link, "utf8") };
}

// ── Display helpers ───────────────────────────────────────────────────────────

function printResult(command, status, pairs) {
  const col = Math.max(...pairs.map(([k]) => k.length));
  console.log(`${command.padEnd(10)} ${status}`);
  pairs.forEach(([k, v]) => console.log(`  ${k.padEnd(col)} : ${v}`));
}

function resolveOutPath(arg) {
  return path.isAbsolute(arg) ? arg : path.join(process.cwd(), arg);
}

function newRecordId(records) {
  const seq = records.reduce((max, r) => Math.max(max, Number(r.seq || 0)), 0) + 1;
  return { id: `loc_${String(seq).padStart(6, "0")}`, seq };
}

function printHelp() {
  console.log(`Workpads CLI

Usage:
  workpads template:validate --file <path> --format kv|yaml
  workpads template:compile --file <path> --format kv|yaml --out <path>
  workpads template:show --template <template-id>
  workpads create --template svc-basic --variant plain --set process.job="Job title" [--business biz_001] [--storage-override ephemeral|stored]
  workpads edit --record <id> --set details="..." --add-action "Title|Notes" [--business biz_001] [--storage-override ephemeral|stored]
  workpads create --template svc-basic --set process.job="..." [--add-participant "Name|role|phone"]
                  [--amount 125.00 --direction O<O --currency GBP] [--tax-rate 200] [--expense-cat job-charge|cogs|running-cost]
  workpads edit   --record <id> [--add-participant "Name|role|phone"] [--amount <val>] [--set-financial-state paymentConfirmed]
  workpads share --record <id> [--trig <expr>] [--ctrig <expr>] [--draft] [--no-forward] [--ack] [--chain]
  workpads share --record <id> --encrypt <passphrase>               (#1ps/ AES-CTR full)
  workpads share --record <id> --partial-encrypt <passphrase>       (#1ph/ header clear)
  workpads share --record <id> --template-key <template-path>       (#1pt/ template-keyed)
  workpads share --record <id> --billboard                          (#1pb/ public)
  workpads share --record <id> --anon [--anon-alias "Local trader"] (#1pb/ anonymous)
  workpads share --record <id> --financial                          (#1pf/ financial presentation)
  workpads share --record <id> --bundle --template <path>           (data-sync bundle)
  workpads import --url <share-link> [--pass <passphrase>] [--template <path>]
  workpads render --record <id> [--json]
  workpads inspect --record <id> [--trig <expr>]
  workpads ctrig:eval --ctrig <expr|preset> [--record <id>] [--ctx key=value ...]
  workpads list:share --items "item1,item2,item3" [--label "My list"]
  workpads agreement:create --title "Job contract" --party "Alice" --worker "Bob" [--terms "..."] [--type service-contract] [--expiry 30] [--ctrig <expr>]
  workpads agreement:accept  --record <id> --name "Alice" [--role customer]
  workpads agreement:status  --record <id>
  workpads agreement:complete --record <id>
  workpads agreement:dispute  --record <id> [--reason "..."]
  workpads export --record <id> --out <path>
  workpads list [--json]
  workpads delete --record <id>
  workpads storage:get --business <id>
  workpads storage:set --business <id> --default ephemeral|stored [--ttl-hours N] [--allow-override true|false]
  workpads storage:resolve --business <id> [--override ephemeral|stored]
  workpads comment:add --record <id> --text "<comment>" [--name "<display>"]
  workpads comment:list --record <id>
  workpads comment:delete --record <id> --index <n>
  workpads dashboard [--json]
  workpads howto [--role owner|dispatcher|receiver|team|supervisor]
  workpads browser [--port 8787] [--ui latest|v1] [--auto-port true|false] [--max-port-tries 20]
  workpads browser:status
  workpads browser:stop

Notes:
  - Record store: .workpads/records.json
  - Base URL default: ${DEFAULT_BASE_URL}
`);
}

function checkPortAvailable(port) {
  return new Promise((resolve) => {
    const tester = net.createServer();
    tester.once("error", () => resolve(false));
    tester.once("listening", () => {
      tester.close(() => resolve(true));
    });
    tester.listen(port, "127.0.0.1");
  });
}

async function findAvailablePort(startPort, maxTries) {
  for (let i = 0; i < maxTries; i += 1) {
    const candidate = startPort + i;
    // eslint-disable-next-line no-await-in-loop
    const ok = await checkPortAvailable(candidate);
    if (ok) return candidate;
  }
  return null;
}

function printHowTo(role) {
  const sections = {
    owner: `OWNER: Set policy defaults
  node ./workpads.js storage:set --business biz_001 --default ephemeral --ttl-hours 24 --allow-override true
  node ./workpads.js storage:get --business biz_001`,
    dispatcher: `DISPATCHER: Create, edit, and share
  node ./workpads.js create --template svc-basic --variant plain --business biz_001 --set process.job="Replace faucet"
  node ./workpads.js edit --record loc_000001 --add-action "Arrive|Inspect site" --set details="Bring standard tools"
  node ./workpads.js share --record loc_000001`,
    receiver: `RECEIVER: Import and view
  echo "https://workpads.me/new#<payload>" | node ./workpads.js import
  node ./workpads.js render --record loc_000002`,
    team: `TEAM: Comment workflow
  node ./workpads.js comment:add --record loc_000001 --text "Parts delivered" --name "Alex"
  node ./workpads.js comment:list --record loc_000001`,
    supervisor: `SUPERVISOR: Daily dashboard
  node ./workpads.js list
  node ./workpads.js dashboard`
  };

  if (role) {
    const key = String(role).toLowerCase();
    if (!sections[key]) {
      throw new Error("Invalid --role. Expected owner|dispatcher|receiver|team|supervisor");
    }
    console.log(sections[key]);
    return;
  }

  console.log(
    [
      "WORKPADS HOW-TO",
      "",
      sections.owner,
      "",
      sections.dispatcher,
      "",
      sections.receiver,
      "",
      sections.team,
      "",
      sections.supervisor,
      "",
      "Docs:",
      "  - cli.md",
      "  - cheat-sheet.md"
    ].join("\n")
  );
}

function expandFromUrl(url) {
  const flat = WPCodec.decode(url);
  return unflattenFromCodec(flat);
}

function commandTemplateValidate(args) {
  const filePath = args.file;
  const format = args.format || "kv";
  if (!filePath) throw new Error("Missing --file");
  const full = path.isAbsolute(filePath) ? filePath : path.join(ROOT, filePath);
  if (!fs.existsSync(full)) throw new Error(`File not found: ${full}`);

  const normalized = parseTemplateFile(full, format);
  console.log(
    JSON.stringify(
      {
        ok: true,
        templateId: normalized.templateId,
        version: normalized.version,
        fields: normalized.fields.length
      },
      null,
      2
    )
  );
}

function commandTemplateCompile(args) {
  const filePath = args.file;
  const format = args.format || "kv";
  const outPath = args.out;
  if (!filePath) throw new Error("Missing --file");
  if (!outPath) throw new Error("Missing --out");
  const full = path.isAbsolute(filePath) ? filePath : path.join(ROOT, filePath);
  const outFull = path.isAbsolute(outPath) ? outPath : path.join(ROOT, outPath);
  const normalized = parseTemplateFile(full, format);
  fs.mkdirSync(path.dirname(outFull), { recursive: true });
  fs.writeFileSync(outFull, JSON.stringify(normalized, null, 2));
  console.log(`Compiled template -> ${outFull}`);
}

function commandTemplateShow(args) {
  const templateId = args.template || "svc-basic";
  const runtimePath = path.join(ROOT, "templates", "runtime", `${templateId}.v1.json`);
  if (!fs.existsSync(runtimePath)) throw new Error(`Template runtime file not found: ${runtimePath}`);
  console.log(fs.readFileSync(runtimePath, "utf8"));
}

// Parse "Name|role|phone|email" participant shorthand
function parseParticipant(str) {
  const ROLE_TYPES = { customer:0, worker:1, supplier:2 };
  const parts = String(str).split("|").map(s => s.trim());
  const name  = parts[0] || "";
  const role  = parts[1] || "customer";
  const phone = parts[2] || "";
  const email = parts[3] || "";
  const roleType = ROLE_TYPES[role] != null ? ROLE_TYPES[role] : 0;
  return { name, roleType, phone: phone||undefined, email: email||undefined,
           isSender: role === "worker" || role === "sender" };
}

function applyParticipants(record, addArgs) {
  if (!addArgs) return;
  const items = Array.isArray(addArgs) ? addArgs : [addArgs];
  if (!record.participants) record.participants = [];
  for (const item of items) record.participants.push(parseParticipant(item));
}

// FLAGS4 contact field names (when baseTemplate=3)
const FLAGS4_CONTACT_KEYS = ["website","social_handle","business_hours","alt_phone","meeting_location"];
// FLAGS4 financial field names (when baseTemplate=1 or 2)
const FLAGS4_FINANCIAL_KEYS = ["service_ref","expiry_date"];

function applyFinancialArgs(record, args) {
  const hasFinArgs = args.amount || args.direction || args["compound-line"] || args.domain;
  if (!hasFinArgs) return;
  if (!record.financial) record.financial = {};
  const f = record.financial;
  if (args.amount)      f.amount      = args.amount;
  if (args.direction)   f.direction   = args.direction;
  if (args.currency)    f.currency    = args.currency;
  if (args["decimal-pos"]) f.decimalPos = Number(args["decimal-pos"]);
  if (args["tax-rate"]) f.taxRate     = Number(args["tax-rate"]);
  if (args["tax-code"]) f.taxCode     = Number(args["tax-code"]);
  if (args["worker-amount"]) f.workerAmount = args["worker-amount"];
  if (args["expense-cat"])   f.expenseCat   = args["expense-cat"];
  if (args.subtype)          f.subtype      = Number(args.subtype);
  if (args.rounding)         f.rounding     = Number(args.rounding);
  if (args.qty)    { f.qtySplit = true; f.qty  = args.qty; }
  if (args.rate)   { f.qtySplit = true; f.rate = args.rate; }
  if (args.billed) f.billed = args.billed !== "false";
  if (args.domain) f.domain = Number(args.domain);
  // Compound lines: --compound-line "Label|amount[|type=N]" (repeatable)
  if (args["compound-line"]) {
    const lines = Array.isArray(args["compound-line"]) ? args["compound-line"] : [args["compound-line"]];
    f.compoundLines = (f.compoundLines || []).concat(lines.map(parseCompoundLine));
    // Total = sum of lines if not explicitly set
    if (!f.amount) {
      const total = f.compoundLines.reduce((s, l) => s + parseFloat(l.amount || 0), 0);
      f.amount = total.toFixed(2);
    }
  }
}

function commandCreate(args) {
  const template = loadTemplate();
  const records = loadRecords();
  const { id, seq } = newRecordId(records);
  const variant = args.variant || "plain";

  const record = {
    id,
    seq,
    templateId: args.template || template.templateId,
    variant,
    process: {},
    actions: [],
    details: "",
    story: "",
    comments: [],
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString()
  };
  normalizeRecordComments(record);

  // State-commit template variant
  if (args.template === "state-commit") {
    record.variant    = "state-commit";
    record.templateId = "state-commit";
    if (!record.financial) record.financial = {};
  }

  applySetPairs(record, parseKeyValuePairs(args.set));
  applyParticipants(record, args["add-participant"]);
  applyFinancialArgs(record, args);

  // State-commit extra financial flags
  if (record.variant === "state-commit" && args["commit-type"] != null)
    record.financial.scCommitType = Number(args["commit-type"]);
  if (record.variant === "state-commit" && args["period-type"] != null)
    record.financial.scPeriodType = Number(args["period-type"]);

  if (!record.process.job) {
    throw new Error("Missing required field: process.job");
  }
  const storage = resolveStorageDecision(args, null);
  if (storage) record.storage = storage;

  records.push(record);
  saveRecords(records);
  console.log(JSON.stringify(record, null, 2));
}

function commandEdit(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record = records.find((r) => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  normalizeRecordComments(record);

  applySetPairs(record, parseKeyValuePairs(args.set));
  applyParticipants(record, args["add-participant"]);
  applyFinancialArgs(record, args);

  if (args["add-action"]) {
    const [title, notes] = String(args["add-action"]).split("|");
    record.actions.push({ title: title || "", notes: notes || "" });
  }
  if (args["set-financial-state"]) {
    if (!record.financial) record.financial = {};
    record.financial[args["set-financial-state"]] = true;
  }
  const storage = resolveStorageDecision(args, record.storage && record.storage.businessId);
  if (storage) record.storage = storage;

  record.updatedAt = new Date().toISOString();
  saveRecords(records);
  console.log(JSON.stringify(record, null, 2));
}

// ── Wire helpers ──────────────────────────────────────────────────────────────

function toB64Url(buf) {
  return Buffer.from(buf).toString("base64")
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
}
function fromB64Url(str) {
  const padded = str + "==".slice(0, (4 - str.length % 4) % 4);
  return Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64");
}

// Get raw (decompressed) pads-v1 frame bytes for a flat record + opts
function getRawFrame(flat, opts) {
  const { compressed } = WPCodec.encodeBinary(flat, opts || {});
  return zlib.inflateRawSync(Buffer.from(compressed));
}

// ── Financial codec helpers ───────────────────────────────────────────────────

// I>O notation → codec bits
const IO_STATES = {
  "I<I":{ioDirection:0,ioTime:0,ioEffect:0}, "I>I":{ioDirection:0,ioTime:1,ioEffect:0},
  "I<O":{ioDirection:0,ioTime:0,ioEffect:1}, "I>O":{ioDirection:0,ioTime:1,ioEffect:1},
  "O<O":{ioDirection:1,ioTime:0,ioEffect:1}, "O>O":{ioDirection:1,ioTime:1,ioEffect:1},
  "O<I":{ioDirection:1,ioTime:0,ioEffect:0}, "O>I":{ioDirection:1,ioTime:1,ioEffect:0},
};
const IO_BY_BITS = {};
for (const [k,v] of Object.entries(IO_STATES)) {
  IO_BY_BITS[`${v.ioDirection}${v.ioTime}${v.ioEffect}`] = k;
}
// transaction-classification.md §7 worker UI labels
const IO_LABELS = {
  "I<I":"Payment received","I>I":"Invoice sent","I<O":"Refund given","I>O":"Credit note",
  "O<O":"Expense paid","O>O":"Bill received","O<I":"Reimbursed","O>I":"Reimbursement pending",
};

// 2-bit currency slot (setup byte) + optional extended byte
const CURRENCY_SLOT = { GBP:0, USD:1, EUR:2 };
function parseCurrencyOpts(code) {
  const up = String(code || "GBP").toUpperCase();
  if (CURRENCY_SLOT[up] !== undefined) return { currency: CURRENCY_SLOT[up] };
  return { currency: 3, currencyCode: up.codePointAt(0) & 0xFF };
}

// Expense category name → 2-bit fin_control value
const EXPENSE_CATS = {
  "job-charge":0, "charge":0, "billed":0,
  "cogs":1, "job-cost":1,
  "running-cost":2, "running":2, "overhead":2,
};

// Convert record.financial object → codec encodeFrame opts
function financialToCodecOpts(fin) {
  if (!fin || (fin.amount == null && fin.customerAmount == null && !fin.compoundLines)) return {};
  const io     = IO_STATES[fin.direction] || {};
  const dp     = fin.decimalPos != null ? Number(fin.decimalPos) : 2;
  const taxCode= fin.taxCode    != null ? Number(fin.taxCode)    : (fin.taxRate ? 1 : 0);
  const expCat = fin.expenseCat != null ? (EXPENSE_CATS[fin.expenseCat] ?? Number(fin.expenseCat)) : 0;
  const amt    = fin.amount     != null ? fin.amount : fin.customerAmount;
  const hasCompound = Array.isArray(fin.compoundLines) && fin.compoundLines.length > 0;
  return {
    domain: Number(fin.domain || 1),
    decimalPos: dp,
    ...parseCurrencyOpts(fin.currency),
    taxCode,
    ...(fin.taxRate   != null ? { taxRate:   Number(fin.taxRate)   } : {}),
    ...(fin.taxAmount != null ? { taxAmount: Number(fin.taxAmount) } : {}),
    ...(amt != null ? { customerAmount: amt } : {}),
    ...(fin.workerAmount != null ? { workerAmount: String(fin.workerAmount) } : {}),
    billed:       !!fin.billed,
    expenseCat:   expCat,
    qtySplit:     !!fin.qtySplit,
    ...(fin.qty  != null ? { qty:  String(fin.qty)  } : {}),
    ...(fin.rate != null ? { rate: String(fin.rate) } : {}),
    ...io,
    ioSubtype:    Number(fin.subtype  || 0),
    rounding:     Number(fin.rounding || 0),
    ...(hasCompound ? { compoundValue: true, compoundLines: fin.compoundLines } : {}),
    ...(fin.hasTotalSummary != null ? { hasTotalSummary: !!fin.hasTotalSummary } : {}),
    ...(fin.hasSubtotals    != null ? { hasSubtotals:    !!fin.hasSubtotals    } : {}),
  };
}

// Parse compound line shorthand: "Label|amount[|type=N][|qty=N|rate=N]"
function parseCompoundLine(str) {
  const CHARGE_TYPES = {
    custom:0, urgency:1, "after-hours":2, travel:3, delivery:4,
    "equipment-hire":5, materials:6, subcontractor:7, cancellation:8,
    deposit:9, credit:10, warranty:11, compliance:12, fx:13, processing:14, multi:15,
  };
  const parts = String(str).split("|").map(s => s.trim());
  const line  = { name: parts[0] || "", amount: parts[1] || "0" };
  for (let i = 2; i < parts.length; i++) {
    const kv = parts[i].split("=");
    if (kv[0] === "type")  line.lineType = CHARGE_TYPES[kv[1]] ?? Number(kv[1]);
    if (kv[0] === "qty")   line.qty      = kv[1];
    if (kv[0] === "rate")  line.rate     = kv[1];
    if (kv[0] === "tax")   line.taxMode  = Number(kv[1]);
  }
  return line;
}

// Build C-TRIG context from a stored record (for ctrig:eval --record)
function buildCTrigContext(record) {
  const p   = record.process   || {};
  const fin = record.financial || {};
  const ag  = record.agreement || {};
  return {
    has_phone:              !!(p.customer_phone),
    has_email:              false,
    has_uid:                !!(record.flags3 && record.flags3.uid),
    is_org:                 false,
    has_chain:              !!(record.chainParent),
    ack_received:           !!(record.ackReceived),
    date_reached:           p.date ? (new Date(p.date) <= new Date()) : false,
    payment_confirmed:      !!(fin.paymentConfirmed),
    ratification_complete:  ag.state === "active" || ag.state === "completed",
    marker_written:         !!(record.markerWritten),
    linked_record_exists:   !!(record.chainParent || record.linkedRecord),
    all_parties_acked:      Array.isArray(ag.parties) && ag.parties.length >= 2 && ag.parties.every(p => p.accepted),
    full_payment_confirmed: !!(fin.fullPaymentConfirmed),
    deposit_received:       !!(fin.depositReceived),
    partial_payment:        !!(fin.partialPayment),
  };
}

// ── Security wrapper (#1ps/) ──────────────────────────────────────────────────
// Spec: security-wrapper.md  Layers: AES-CTR-128 + preamble byte
// Omits SEED_POISON and FIELD_SCRAMBLE (preamble bits left 0; decoders must tolerate)

function secureEncode(frameBytes, passphrase) {
  const salt      = crypto.randomBytes(4);
  const master    = crypto.createHash("sha256")
    .update(Buffer.from(passphrase, "utf8")).update(salt).digest();
  const cipherKey = master.slice(0, 16);
  const iv        = Buffer.alloc(16); cipherKey.copy(iv); // iv = cipher_key (safe: salt ensures unique master)
  const deflated  = zlib.deflateRawSync(frameBytes);
  const cipher    = crypto.createCipheriv("aes-128-ctr", cipherKey, iv);
  const encrypted = Buffer.concat([cipher.update(deflated), cipher.final()]);
  const preamble  = 0x40 | (cipherKey[0] & 0x07); // AES=1, KEY_HINT=low3 of cipher_key[0]
  return "workpads.me/p#1ps/" + toB64Url(salt) + "." + toB64Url(Buffer.concat([Buffer.from([preamble]), encrypted]));
}

function secureDecode(url, passphrase) {
  const frag = url.slice(url.indexOf("#") + 1);
  if (!frag.startsWith("1ps/")) throw new Error("Not a #1ps/ secure URL");
  const payload = frag.slice(4);
  const dotIdx  = payload.indexOf(".");
  if (dotIdx < 0) throw new Error("#1ps/ URL missing '.' separator");
  const salt      = fromB64Url(payload.slice(0, dotIdx));
  const inner     = fromB64Url(payload.slice(dotIdx + 1));
  const preamble  = inner[0];
  const aesOn     = (preamble >> 6) & 1;
  if (!aesOn) throw new Error("AES bit not set in preamble — cannot decrypt");
  const keyHint   = preamble & 0x07;
  const master    = crypto.createHash("sha256")
    .update(Buffer.from(passphrase, "utf8")).update(salt).digest();
  const cipherKey = master.slice(0, 16);
  if ((cipherKey[0] & 0x07) !== keyHint) throw new Error("KEY_HINT mismatch — wrong passphrase?");
  const iv        = Buffer.alloc(16); cipherKey.copy(iv);
  const decipher  = crypto.createDecipheriv("aes-128-ctr", cipherKey, iv);
  const deflated  = Buffer.concat([decipher.update(inner.slice(1)), decipher.final()]);
  return zlib.inflateRawSync(deflated); // raw pads-v1 frame bytes
}

// #1ph/ — partial scramble: meta bytes left clear, rest AES-CTR
// Receiver sees BASE_TEMPLATE + DOMAIN before entering passphrase.
function partialSecureEncode(frameBytes, passphrase) {
  const salt      = crypto.randomBytes(4);
  const master    = crypto.createHash("sha256").update(Buffer.from(passphrase,"utf8")).update(salt).digest();
  const cipherKey = master.slice(0,16);
  const iv        = Buffer.alloc(16); cipherKey.copy(iv);
  // Clear header: meta1 always 1B; add meta2 if bit7 set; add setup+tx bytes if domain>0
  let clearLen = 1;
  if (frameBytes.length > 1 && (frameBytes[0] & 0x80)) {
    clearLen = 2;
    if (frameBytes.length > 3 && ((frameBytes[1] >> 2) & 0x3) > 0) clearLen = 4;
  }
  const clearHeader = frameBytes.slice(0, Math.min(clearLen, frameBytes.length));
  const inner       = frameBytes.slice(clearHeader.length);
  const deflated    = zlib.deflateRawSync(inner);
  const cipher      = crypto.createCipheriv("aes-128-ctr", cipherKey, iv);
  const encrypted   = Buffer.concat([cipher.update(deflated), cipher.final()]);
  const preamble    = 0x40 | (cipherKey[0] & 0x07);
  const combined    = Buffer.concat([Buffer.from([preamble]), clearHeader, encrypted]);
  return "workpads.me/p#1ph/" + toB64Url(salt) + "." + toB64Url(combined);
}

function partialSecureDecode(url, passphrase) {
  const frag    = url.slice(url.indexOf("#") + 1);
  if (!frag.startsWith("1ph/")) throw new Error("Not a #1ph/ URL");
  const payload = frag.slice(4);
  const dotIdx  = payload.indexOf(".");
  if (dotIdx < 0) throw new Error("#1ph/ URL missing '.' separator");
  const salt      = fromB64Url(payload.slice(0, dotIdx));
  const combined  = fromB64Url(payload.slice(dotIdx + 1));
  const preamble  = combined[0];
  const keyHint   = preamble & 0x07;
  const master    = crypto.createHash("sha256").update(Buffer.from(passphrase,"utf8")).update(salt).digest();
  const cipherKey = master.slice(0,16);
  if ((cipherKey[0] & 0x07) !== keyHint) throw new Error("KEY_HINT mismatch — wrong passphrase?");
  const iv = Buffer.alloc(16); cipherKey.copy(iv);
  // After preamble: clear_header bytes then encrypted payload
  // We need to determine clear_header length from meta1
  const afterPreamble = combined.slice(1);
  const meta1Byte     = afterPreamble[0];
  let clearLen = 1;
  if ((meta1Byte & 0x80) && afterPreamble.length > 1) {
    clearLen = 2;
    if (afterPreamble.length > 3 && ((afterPreamble[1] >> 2) & 0x3) > 0) clearLen = 4;
  }
  clearLen = Math.min(clearLen, afterPreamble.length);
  const clearHeader  = afterPreamble.slice(0, clearLen);
  const encryptedPart = afterPreamble.slice(clearLen);
  const decipher     = crypto.createDecipheriv("aes-128-ctr", cipherKey, iv);
  const deflated     = Buffer.concat([decipher.update(encryptedPart), decipher.final()]);
  const innerBytes   = zlib.inflateRawSync(deflated);
  return Buffer.concat([clearHeader, innerBytes]);
}

// #1pt/ — template-keyed: key = SHA-256(template_bytes || salt)[0:16]
// salt is random per-encode so same template → different keys across records
function templateKeyedEncode(frameBytes, templatePath) {
  const tmplBytes = fs.readFileSync(templatePath);
  const salt      = crypto.randomBytes(4);
  const cipherKey = crypto.createHash("sha256").update(tmplBytes).update(salt).digest().slice(0, 16);
  const iv        = Buffer.alloc(16); cipherKey.copy(iv);
  const deflated  = zlib.deflateRawSync(frameBytes);
  const cipher    = crypto.createCipheriv("aes-128-ctr", cipherKey, iv);
  const encrypted = Buffer.concat([cipher.update(deflated), cipher.final()]);
  const preamble  = 0x40 | (cipherKey[0] & 0x07);
  return "workpads.me/p#1pt/" + toB64Url(salt) + "." + toB64Url(Buffer.concat([Buffer.from([preamble]), encrypted]));
}

function templateKeyedDecode(url, templatePath) {
  const frag    = url.slice(url.indexOf("#") + 1);
  if (!frag.startsWith("1pt/")) throw new Error("Not a #1pt/ URL");
  const payload = frag.slice(4);
  const dotIdx  = payload.indexOf(".");
  if (dotIdx < 0) throw new Error("#1pt/ URL missing '.' separator");
  const salt      = fromB64Url(payload.slice(0, dotIdx));
  const tmplBytes = fs.readFileSync(templatePath);
  const cipherKey = crypto.createHash("sha256").update(tmplBytes).update(salt).digest().slice(0, 16);
  const iv        = Buffer.alloc(16); cipherKey.copy(iv);
  const inner     = fromB64Url(payload.slice(dotIdx + 1));
  const preamble  = inner[0];
  if ((cipherKey[0] & 0x07) !== (preamble & 0x07)) throw new Error("KEY_HINT mismatch — wrong template or salt?");
  const decipher  = crypto.createDecipheriv("aes-128-ctr", cipherKey, iv);
  const deflated  = Buffer.concat([decipher.update(inner.slice(1)), decipher.final()]);
  return zlib.inflateRawSync(deflated);
}

// ── Data Sync Bundle (workpads.me/sync#1pa/) ──────────────────────────────────
// Spec: data-sync-bundle.md
// Wire: [bundle_header] + items([type][u16 len][payload]) — then deflate + b64url

const BUNDLE_PREFIX = "workpads.me/sync#1pa/";

function encodeBundle(frameBytes, templateJson) {
  const parts = [];
  function pushItem(type, payload) {
    const len = Buffer.alloc(2);
    len.writeUInt16BE(payload.length, 0);
    parts.push(Buffer.from([type]), len, payload);
  }
  const itemCount = templateJson ? 2 : 1;
  parts.unshift(Buffer.from([(0x0 << 4) | itemCount])); // BUNDLE_TYPE=0, ITEM_COUNT
  if (templateJson) pushItem(0x01, Buffer.isBuffer(templateJson) ? templateJson : Buffer.from(JSON.stringify(templateJson), "utf8"));
  pushItem(0x04, frameBytes);
  const bundleBytes = Buffer.concat(parts);
  return BUNDLE_PREFIX + toB64Url(zlib.deflateRawSync(bundleBytes));
}

function decodeBundle(url) {
  const frag    = url.slice(url.indexOf("#") + 1);
  const payload = frag.replace(/^1pa\//, "");
  const bytes   = zlib.inflateRawSync(fromB64Url(payload));
  let pos = 0;
  const header     = bytes[pos++];
  const itemCount  = header & 0x0F;
  const result     = { template: null, frameBytes: null };
  for (let i = 0; i < itemCount; i++) {
    const type    = bytes[pos++];
    const len     = (bytes[pos] << 8) | bytes[pos + 1]; pos += 2;
    const payload = bytes.slice(pos, pos + len); pos += len;
    if (type === 0x01) result.template = JSON.parse(payload.toString("utf8"));
    if (type === 0x04) result.frameBytes = payload;
  }
  if (!result.frameBytes) throw new Error("Bundle contains no record item (type 0x04)");
  return result;
}

function commandShare(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record = records.find((r) => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);

  // Build codec opts from flags
  const trigOpts  = args.trig   ? compileTrig(args.trig)   : {};
  const ctrigOpts = args.ctrig  ? compileCTrig(args.ctrig) : {};
  const finOpts      = financialToCodecOpts(record.financial);
  const participants = Array.isArray(record.participants) ? record.participants : [];
  // Agreement records: force ACK_REQUEST, embed C-TRIG obligation in frame
  const agOpts = {};
  if (record.agreement) {
    agOpts.ackRequest = true;
    if (record.cTrigBytes && !ctrigOpts.hasTrigBlock) {
      agOpts.hasTrigBlock = true;
      agOpts.trigBytes    = record.cTrigBytes;
    }
  }
  // State Commit frame type
  if (record.templateId === "state-commit" || record.variant === "state-commit") {
    finOpts.baseTemplate = 5;
    finOpts.domain       = finOpts.domain || 1;
    if (record.financial) {
      finOpts.scCommitType    = Number(record.financial.scCommitType    || 0);
      finOpts.scPeriodType    = Number(record.financial.scPeriodType    || 0);
      finOpts.scChainComplete = !!record.financial.scChainComplete;
      finOpts.scDisputeFlag   = !!record.financial.scDisputeFlag;
      finOpts.scTotalAmount   = record.financial.amount || 0;
      finOpts.scLineCount     = Number(record.financial.lineCount || 0);
    }
  }
  const frameOpts = Object.assign({}, finOpts, agOpts, trigOpts, ctrigOpts, {
    ...(participants.length ? { participants } : {}),
    ...(args.draft           ? { draft: true }           : {}),
    ...(args["no-forward"]   ? { restrictForward: true } : {}),
    ...(args.ack             ? { ackRequest: true }       : {}),
    ...(args.chain           ? { chain: true }            : {}),
  });

  // Anonymous mode: strip sender identity, set DATA_SOURCE=11 in display_schema
  let flat = flattenForCodec(record);
  if (args.anon) {
    flat = Object.assign({}, flat);
    delete flat.worker;
    delete flat.customer_phone;
    if (args["anon-alias"]) flat.context_label = String(args["anon-alias"]);
    frameOpts.recipientType    = false;
    frameOpts.displayDataSource = 3; // DATA_SOURCE=11 (binary 11 = decimal 3)
  }

  // ── Binary .wpf file output
  if (args.out) {
    const { compressed, frameSize } = WPCodec.encodeBinary(flat, frameOpts);
    const tag    = Buffer.from("1pa", "ascii");
    const outBuf = Buffer.concat([tag, Buffer.from(compressed)]);
    const outPath = resolveOutPath(args.out);
    fs.mkdirSync(path.dirname(outPath), { recursive: true });
    fs.writeFileSync(outPath, outBuf);
    printResult("share", "OK", [
      ["record", record.id],
      ["job",    record.process.job || ""],
      ["file",   outPath],
      ["bytes",  `${outBuf.length}  (header: 3  frame: ${frameSize}  deflated: ${compressed.length})`],
      ["header", "1pa"],
      ...(args.trig   ? [["trig",   args.trig]]   : []),
      ...(args.ctrig  ? [["ctrig",  args.ctrig]]  : []),
    ]);
    return;
  }

  // ── Data Sync Bundle — template travels with record
  if (args.bundle) {
    const tmplArg = args.template || args.bundle;
    if (!tmplArg || tmplArg === true) throw new Error("--bundle requires --template <path> (or --bundle <path>)");
    const tmplPath = path.isAbsolute(tmplArg) ? tmplArg : path.join(process.cwd(), tmplArg);
    if (!fs.existsSync(tmplPath)) throw new Error(`Template file not found: ${tmplPath}`);
    const tmplJson  = JSON.parse(fs.readFileSync(tmplPath, "utf8"));
    const frameBytes = getRawFrame(flat, frameOpts);
    const url   = encodeBundle(frameBytes, tmplJson);
    const bytes = Buffer.byteLength(url, "utf8");
    printResult("share", "OK", [
      ["record",   record.id],
      ["job",      record.process.job || ""],
      ["url",      url],
      ["bytes",    String(bytes)],
      ["alg",      "bundle+deflate+b64url"],
      ["template", path.basename(tmplPath)],
      ...(args.trig   ? [["trig",   args.trig]]   : []),
      ...(args.ctrig  ? [["ctrig",  args.ctrig]]  : []),
    ]);
    return;
  }

  // ── Encrypted share (#1ps/)
  if (args.encrypt) {
    const passphrase = String(args.encrypt);
    if (passphrase.length < 4) throw new Error("--encrypt passphrase must be at least 4 characters");
    const frameBytes = getRawFrame(flat, frameOpts);
    const url   = secureEncode(frameBytes, passphrase);
    const bytes = Buffer.byteLength(url, "utf8");
    printResult("share", "OK", [
      ["record", record.id],
      ["job",    record.process.job || ""],
      ["url",    url],
      ["bytes",  String(bytes)],
      ["alg",    "pads-v1+AES-128-CTR+deflate+b64url"],
      ["tag",    "#1ps/"],
      ...(args.trig   ? [["trig",   args.trig]]   : []),
      ...(args.ctrig  ? [["ctrig",  args.ctrig]]  : []),
    ]);
    return;
  }

  // ── Billboard URL (#1pb/) — public, non-financial
  if (args.billboard || args.anon) {
    const { compressed } = WPCodec.encodeBinary(flat, frameOpts);
    const tag   = args.anon ? "#1pb/" : "#1pb/";
    const url   = "workpads.me/p" + tag + toB64Url(compressed);
    const bytes = Buffer.byteLength(url, "utf8");
    printResult("share", "OK", [
      ["record", record.id],
      ["job",    record.process.job || ""],
      ["url",    url],
      ["bytes",  String(bytes)],
      ["alg",    "pads-v1+deflate+b64url"],
      ["tag",    tag + (args.anon ? " (anonymous)" : " (public billboard)")],
      ...(args.anon && args["anon-alias"] ? [["alias", args["anon-alias"]]] : []),
      ...(args.trig   ? [["trig",   args.trig]]   : []),
      ...(args.ctrig  ? [["ctrig",  args.ctrig]]  : []),
    ]);
    return;
  }

  // ── Partial scramble (#1ph/) — header bytes clear, payload AES-CTR
  if (args["partial-encrypt"]) {
    const passphrase = String(args["partial-encrypt"]);
    if (passphrase.length < 4) throw new Error("--partial-encrypt passphrase must be >= 4 chars");
    const frameBytes = getRawFrame(flat, frameOpts);
    const url   = partialSecureEncode(frameBytes, passphrase);
    const bytes = Buffer.byteLength(url, "utf8");
    printResult("share", "OK", [
      ["record", record.id],
      ["job",    record.process.job || ""],
      ["url",    url],
      ["bytes",  String(bytes)],
      ["alg",    "pads-v1+AES-128-CTR(partial)+deflate+b64url"],
      ["tag",    "#1ph/ (partial scramble — header visible)"],
      ...(args.trig   ? [["trig",   args.trig]]   : []),
      ...(args.ctrig  ? [["ctrig",  args.ctrig]]  : []),
    ]);
    return;
  }

  // ── Template-keyed (#1pt/) — key derived from template file bytes
  if (args["template-key"]) {
    const tmplPath = path.isAbsolute(args["template-key"]) ? args["template-key"] : path.join(process.cwd(), args["template-key"]);
    if (!fs.existsSync(tmplPath)) throw new Error(`Template file not found: ${tmplPath}`);
    const frameBytes = getRawFrame(flat, frameOpts);
    const url   = templateKeyedEncode(frameBytes, tmplPath);
    const bytes = Buffer.byteLength(url, "utf8");
    printResult("share", "OK", [
      ["record",   record.id],
      ["job",      record.process.job || ""],
      ["url",      url],
      ["bytes",    String(bytes)],
      ["alg",      "pads-v1+AES-128-CTR(template-key)+deflate+b64url"],
      ["tag",      "#1pt/ (template-keyed)"],
      ["template", path.basename(tmplPath)],
      ...(args.trig   ? [["trig",   args.trig]]   : []),
      ...(args.ctrig  ? [["ctrig",  args.ctrig]]  : []),
    ]);
    return;
  }

  // ── Financial presentation (#1pf/) — invoice/statement display tag
  if (args.financial) {
    const { compressed } = WPCodec.encodeBinary(flat, frameOpts);
    const url   = "workpads.me/p#1pf/" + toB64Url(compressed);
    const bytes = Buffer.byteLength(url, "utf8");
    printResult("share", "OK", [
      ["record", record.id],
      ["job",    record.process.job || ""],
      ["url",    url],
      ["bytes",  String(bytes)],
      ["alg",    "pads-v1+deflate+b64url"],
      ["tag",    "#1pf/ (financial presentation)"],
      ...(args.trig   ? [["trig",   args.trig]]   : []),
      ...(args.ctrig  ? [["ctrig",  args.ctrig]]  : []),
    ]);
    return;
  }

  // ── Standard plain URL (#1pa/)
  const link  = WPCodec.encode(flat, frameOpts);
  const bytes = Buffer.byteLength(link, "utf8");
  const extras = [
    ...(args.trig              ? [["trig",             args.trig]]   : []),
    ...(args.ctrig             ? [["ctrig",            args.ctrig]]  : []),
    ...(record.financial       ? [["financial",        record.financial.direction || "domain=" + (record.financial.domain||1)]] : []),
    ...(participants.length    ? [["participants",     String(participants.length)]] : []),
    ...(args.draft             ? [["draft",            "yes"]]       : []),
    ...(args["no-forward"]     ? [["restrict-forward", "yes"]]       : []),
    ...(args.ack               ? [["ack",              "yes"]]       : []),
    ...(args.chain             ? [["chain",            "yes"]]       : []),
  ];
  printResult("share", "OK", [
    ["record", record.id],
    ["job",    record.process.job || ""],
    ["url",    link],
    ["bytes",  String(bytes)],
    ["alg",    "pads-v1+deflate+b64url"],
    ...extras,
  ]);
}

function commandImport(args) {
  let expanded, source, importMeta = {};

  if (args.file) {
    const filePath = path.isAbsolute(args.file) ? args.file : path.join(process.cwd(), args.file);
    if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);
    const buf = fs.readFileSync(filePath);
    if (buf.length < 4) throw new Error("File too short to be a valid .wpf");
    expanded = unflattenFromCodec(WPCodec.decodeBinary(buf));
    source = filePath;

  } else {
    let inputUrl = args.url;
    if (!inputUrl) {
      const stdin = fs.readFileSync(0, "utf8").trim();
      if (stdin) inputUrl = stdin;
    }
    if (!inputUrl) throw new Error("Missing --url or --file");
    if (inputUrl.indexOf("#") < 0) throw new Error("Invalid URL: missing # fragment");

    const frag = inputUrl.slice(inputUrl.indexOf("#") + 1);

    // ── Bundle URL (workpads.me/sync#1pa/)
    if (inputUrl.includes("sync#1pa/") || frag.startsWith("1pa/") && inputUrl.includes("/sync")) {
      const { frameBytes, template } = decodeBundle(inputUrl);
      const fakeUrl = "workpads.me/p#1pa/" + toB64Url(zlib.deflateRawSync(frameBytes));
      const flat = WPCodec.decode(fakeUrl);
      expanded = unflattenFromCodec(flat);
      if (template) {
        importMeta.bundledTemplate = template.templateId || template.title || "(unnamed)";
        // Install template to runtime dir if it has a templateId
        if (template.templateId) {
          const tmplOut = path.join(ROOT, "templates", "runtime", `${template.templateId}.v1.json`);
          fs.mkdirSync(path.dirname(tmplOut), { recursive: true });
          if (!fs.existsSync(tmplOut)) {
            fs.writeFileSync(tmplOut, JSON.stringify(template, null, 2));
            importMeta.templateInstalled = tmplOut;
          }
        }
      }
      source = inputUrl;

    // ── Encrypted URL (#1ps/)
    } else if (frag.startsWith("1ps/")) {
      if (!args.pass) throw new Error("#1ps/ encrypted URL requires --pass <passphrase>");
      const frameBytes = secureDecode(inputUrl, String(args.pass));
      const fakeUrl = "workpads.me/p#1pa/" + toB64Url(zlib.deflateRawSync(frameBytes));
      expanded = unflattenFromCodec(WPCodec.decode(fakeUrl));
      importMeta.decrypted = "yes (#1ps/)";
      source = inputUrl;

    // ── Partial scramble (#1ph/)
    } else if (frag.startsWith("1ph/")) {
      if (!args.pass) throw new Error("#1ph/ partial-encrypted URL requires --pass <passphrase>");
      const frameBytes = partialSecureDecode(inputUrl, String(args.pass));
      const fakeUrl = "workpads.me/p#1pa/" + toB64Url(zlib.deflateRawSync(frameBytes));
      expanded = unflattenFromCodec(WPCodec.decode(fakeUrl));
      importMeta.decrypted = "yes (#1ph/ partial)";
      source = inputUrl;

    // ── Template-keyed (#1pt/)
    } else if (frag.startsWith("1pt/")) {
      if (!args.pass && !args.template) throw new Error("#1pt/ template-keyed URL requires --template <path>");
      const tmplArg = args.template || args.pass;
      const tmplPath = path.isAbsolute(tmplArg) ? tmplArg : path.join(process.cwd(), tmplArg);
      if (!fs.existsSync(tmplPath)) throw new Error(`Template file not found: ${tmplPath}`);
      const frameBytes = templateKeyedDecode(inputUrl, tmplPath);
      const fakeUrl = "workpads.me/p#1pa/" + toB64Url(zlib.deflateRawSync(frameBytes));
      expanded = unflattenFromCodec(WPCodec.decode(fakeUrl));
      importMeta.decrypted = "yes (#1pt/ template-keyed)";
      source = inputUrl;

    // ── Option list (#l/)
    } else if (frag.startsWith("l/")) {
      const payload = frag.slice(2);
      const listBytes = zlib.inflateRawSync(fromB64Url(payload));
      const items = listBytes.toString("utf8").split("\n").filter(Boolean);
      expanded = {
        process: { job: "Option list (" + items.length + " items)" },
        actions: items.map(i => ({ title: i, notes: "" })),
        details: "", story: "",
      };
      importMeta.listImport = true;
      importMeta.itemCount  = items.length;
      source = inputUrl;

    // ── Standard URL (#1pa/, #1pb/, #1pf/, legacy)
    } else {
      expanded = expandFromUrl(inputUrl);
      source = inputUrl;
    }
  }

  const records = loadRecords();
  const { id, seq } = newRecordId(records);
  const now = new Date().toISOString();
  const imported = {
    id, seq,
    templateId: "svc-basic",
    variant: "plain",
    ...expanded,
    comments: [],
    createdAt: now,
    updatedAt: now,
    importedFromLink: true
  };
  normalizeRecordComments(imported);
  if (!imported.process.job) throw new Error("Imported payload missing required job field");
  records.push(imported);
  saveRecords(records);

  printResult("import", "OK", [
    ["id",       imported.id],
    ["job",      imported.process.job || ""],
    ["customer", imported.process.customer || ""],
    ["date",     imported.process.date || ""],
    ["source",   source.length > 60 ? source.slice(0, 57) + "..." : source],
    ...(importMeta.decrypted         ? [["decrypted",  importMeta.decrypted]]          : []),
    ...(importMeta.bundledTemplate   ? [["template",   importMeta.bundledTemplate]]   : []),
    ...(importMeta.templateInstalled ? [["installed",  importMeta.templateInstalled]] : []),
    ...(importMeta.listImport        ? [["list-items", String(importMeta.itemCount)]] : []),
  ]);
}

function commandRender(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record = records.find((r) => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);

  if (args.json) {
    console.log(JSON.stringify(record, null, 2));
    return;
  }

  const p = record.process || {};
  const HR = "── " + rule(63);
  const out = [];

  // ── Header
  out.push("");
  out.push("── " + clr("bold", "Workpads Record") + " " + rule(51));
  out.push("   " + clr("signal", record.id.padEnd(32)) + " " + clr("faint", record.templateId + " / " + (record.variant || "plain")));
  if (record.createdAt) {
    const created = record.createdAt.slice(0, 19).replace("T", " ");
    const updated = record.updatedAt ? record.updatedAt.slice(0, 19).replace("T", " ") : "";
    out.push("   " + clr("faint", "created") + "  " + created + (updated ? "   " + clr("faint", "updated") + "  " + updated : ""));
  }
  out.push(HR);

  // ── Process fields
  out.push("   " + clr("bold", "PROCESS"));
  const processFields = [
    ["job     ", p.job],
    ["customer", p.customer],
    ["date    ", p.date],
    ["location", p.location],
    ["meeting ", p.meeting_time],
    ["start   ", p.start_time],
    ["end     ", p.end_time],
    ["phone   ", p.customer_phone],
    ["worker  ", p.worker],
  ];
  for (const [label, val] of processFields) {
    if (!val) continue;
    if (label.trim() === "job" || label.trim() === "location" || label.trim() === "details") {
      out.push("   " + clr("faint", label) + "  " + wrapIndent(val, "            ", 70).trimStart());
    } else {
      out.push("   " + clr("faint", label) + "  " + val);
    }
  }

  // ── Actions
  if (Array.isArray(record.actions) && record.actions.length > 0) {
    out.push(HR);
    out.push("   " + clr("bold", "ACTIONS"));
    record.actions.forEach((a, i) => {
      const num = clr("warm", String(i + 1).padStart(2) + ".");
      out.push("   " + num + " " + (a.title || ""));
      if (a.notes) {
        out.push(wrapIndent(a.notes, "        ", 70));
      }
    });
  }

  // ── Details
  if (record.details) {
    out.push(HR);
    out.push("   " + clr("bold", "DETAILS"));
    out.push(wrapIndent(record.details, "   ", 70));
  }

  // ── Story
  if (record.story) {
    out.push(HR);
    out.push("   " + clr("bold", "STORY"));
    out.push(wrapIndent(record.story, "   ", 70));
  }

  // ── Comments
  const comments = Array.isArray(record.comments) ? record.comments.filter((c) => c.x) : [];
  if (comments.length > 0) {
    out.push(HR);
    out.push("   " + clr("bold", "COMMENTS"));
    comments.forEach((c) => {
      const ts = c.ts ? c.ts.slice(0, 10) : "";
      const name = c.n ? clr("signal", c.n) : "";
      const prefix = "   " + clr("faint", ts) + "  " + (name ? name + "  " : "");
      out.push(prefix + wrapIndent(c.x || "", "              ", 70).trimStart());
    });
  }

  // ── Financial
  if (record.financial) {
    const fin = record.financial;
    out.push(HR);
    out.push("   " + clr("bold", "FINANCIAL"));
    const dir   = fin.direction || "";
    const label = IO_LABELS[dir] || dir;
    if (label)            out.push("   " + clr("faint", "type     ") + "  " + label + (dir ? "  " + clr("faint", dir) : ""));
    const amt = fin.amount || fin.customerAmount;
    if (amt)              out.push("   " + clr("faint", "amount   ") + "  " + clr("signal", String(amt)) + "  " + (fin.currency || "GBP"));
    if (fin.workerAmount) out.push("   " + clr("faint", "cost     ") + "  " + fin.workerAmount + "  " + clr("faint", "(worker internal)"));
    if (fin.taxRate)      out.push("   " + clr("faint", "tax      ") + "  " + (fin.taxRate / 10).toFixed(1) + "%");
    if (fin.expenseCat)   out.push("   " + clr("faint", "category ") + "  " + fin.expenseCat);
    if (fin.qtySplit && fin.qty && fin.rate)
                          out.push("   " + clr("faint", "qty×rate ") + "  " + fin.qty + " × " + fin.rate);
    if (Array.isArray(fin.compoundLines) && fin.compoundLines.length) {
      out.push("   " + clr("faint", "lines    "));
      fin.compoundLines.forEach((l, i) =>
        out.push("   " + clr("warm", String(i + 1).padStart(3) + ".") + " " + (l.name || "").padEnd(20) + "  " + l.amount));
    }
  }

  // ── Participants
  if (Array.isArray(record.participants) && record.participants.length) {
    const ROLE_NAMES = ["customer","worker","supplier","extended"];
    out.push(HR);
    out.push("   " + clr("bold", "PARTICIPANTS"));
    record.participants.forEach(p => {
      const role = ROLE_NAMES[p.roleType] || "?";
      const sender = p.isSender ? clr("faint", " [sender]") : "";
      out.push("   " + (p.name || "?").padEnd(22) + role.padEnd(12) + (p.phone || "") + sender);
    });
  }

  // ── Agreement
  if (record.agreement) {
    const a = record.agreement;
    const stateColor = { active:"green", completed:"green", disputed:"red" }[a.state] || "warm";
    out.push(HR);
    out.push("   " + clr("bold", "AGREEMENT") + "  " + clr(stateColor, a.state || "proposed"));
    if (a.type)       out.push("   " + clr("faint", "type   ") + "  " + a.type);
    if (a.expiryDate) out.push("   " + clr("faint", "expiry ") + "  " + a.expiryDate);
    if (a.parties && a.parties.length) {
      const accepted = a.parties.filter(p => p.accepted).map(p => p.name).join(", ");
      const pending  = a.parties.filter(p => !p.accepted).map(p => p.name).join(", ");
      if (accepted) out.push("   " + clr("faint", "agreed ") + "  " + clr("green", accepted));
      if (pending)  out.push("   " + clr("faint", "pending") + "  " + clr("gold", pending));
    }
    if (a.ctrig) out.push("   " + clr("faint", "ctrig  ") + "  " + a.ctrig);
  }

  // ── Share footer
  const { link, bytes } = buildShareLinkForRecord(record);
  const shortUrl = link.length > 60 ? link.slice(0, 57) + "..." : link;
  out.push(HR);
  out.push("   " + clr("faint", "alg  ") + "  " + clr("green", "pads-v1+deflate+b64url") + "   " + clr("faint", "bytes") + "  " + bytes);
  out.push("   " + clr("faint", "url  ") + "  " + clr("faint", shortUrl));
  out.push("── " + rule(63));
  out.push("");

  console.log(out.join("\n"));
}

function commandExport(args) {
  if (!args.record) throw new Error("Missing --record");
  if (!args.out) throw new Error("Missing --out");

  const records = loadRecords();
  const record = records.find((r) => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);

  const outPath = path.isAbsolute(args.out) ? args.out : path.join(ROOT, args.out);
  const outDir = path.dirname(outPath);
  fs.mkdirSync(outDir, { recursive: true });
  fs.writeFileSync(outPath, JSON.stringify(record, null, 2));
  console.log(`Exported ${record.id} -> ${outPath}`);
}

function commandList(args) {
  const records = loadRecords();
  if (args.json) {
    console.log(JSON.stringify(records, null, 2));
    return;
  }

  if (records.length === 0) {
    console.log("No records.");
    return;
  }

  records
    .sort((a, b) => Number(a.seq || 0) - Number(b.seq || 0))
    .forEach((record) => {
      const job = (record.process && record.process.job) || "";
      const variant = record.variant || "plain";
      const storageMode = (record.storage && record.storage.mode) || "unset";
      const bytes = buildShareLinkForRecord(record).bytes;
      console.log(`${record.id}\t${variant}\t${storageMode}\t${bytes}\t${job}`);
    });
}

function commandDelete(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const index = records.findIndex((r) => r.id === args.record);
  if (index < 0) throw new Error(`Record not found: ${args.record}`);
  const [removed] = records.splice(index, 1);
  saveRecords(records);
  console.log(`Deleted ${removed.id}`);
}

function getBusinessStoragePolicy(policies, businessId) {
  if (!policies[businessId]) {
    policies[businessId] = {
      businessId,
      defaultMode: "ephemeral",
      defaultTtlHours: 24,
      allowOverride: true,
      updatedAt: new Date().toISOString()
    };
  }
  return policies[businessId];
}

function parseBool(value, fallback) {
  if (value === undefined) return fallback;
  if (value === true) return true;
  const v = String(value).toLowerCase();
  return v === "true" || v === "1" || v === "yes";
}

function normalizeMode(mode) {
  const out = String(mode || "").toLowerCase();
  if (out !== "ephemeral" && out !== "stored") {
    throw new Error(`Invalid mode: ${mode}. Expected ephemeral|stored`);
  }
  return out;
}

function resolveStorageDecision(args, businessIdHint) {
  const businessId = args.business || businessIdHint;
  const hasOverride = args["storage-override"] !== undefined;
  if (!businessId && !hasOverride) return null;
  if (!businessId && hasOverride) {
    throw new Error("Missing --business when using --storage-override");
  }

  const policies = loadStoragePolicies();
  const policy = getBusinessStoragePolicy(policies, businessId);
  saveStoragePolicies(policies);

  let mode = policy.defaultMode || "ephemeral";
  let source = "business-default";
  if (hasOverride) {
    const overrideMode = normalizeMode(args["storage-override"]);
    if (policy.allowOverride) {
      mode = overrideMode;
      source = "record-override";
    } else {
      source = "business-default-override-disabled";
    }
  }

  const ttlHours = mode === "ephemeral" ? Number(policy.defaultTtlHours || 24) : null;
  const resolvedAt = new Date().toISOString();
  const expiresAt =
    ttlHours !== null
      ? new Date(new Date(resolvedAt).getTime() + ttlHours * 60 * 60 * 1000).toISOString()
      : null;

  return {
    businessId,
    mode,
    ttlHours,
    source,
    resolvedAt,
    expiresAt
  };
}

function commandStorageGet(args) {
  const businessId = args.business;
  if (!businessId) throw new Error("Missing --business");
  const policies = loadStoragePolicies();
  const policy = getBusinessStoragePolicy(policies, businessId);
  saveStoragePolicies(policies);
  console.log(JSON.stringify(policy, null, 2));
}

function commandStorageSet(args) {
  const businessId = args.business;
  if (!businessId) throw new Error("Missing --business");
  if (!args.default) throw new Error("Missing --default");

  const policies = loadStoragePolicies();
  const policy = getBusinessStoragePolicy(policies, businessId);
  policy.defaultMode = normalizeMode(args.default);
  if (args["ttl-hours"] !== undefined) {
    const ttl = Number(args["ttl-hours"]);
    if (Number.isNaN(ttl) || ttl < 0) {
      throw new Error("Invalid --ttl-hours");
    }
    policy.defaultTtlHours = ttl;
  }
  policy.allowOverride = parseBool(args["allow-override"], policy.allowOverride);
  policy.updatedAt = new Date().toISOString();

  policies[businessId] = policy;
  saveStoragePolicies(policies);
  console.log(JSON.stringify(policy, null, 2));
}

function commandStorageResolve(args) {
  const businessId = args.business;
  if (!businessId) throw new Error("Missing --business");

  const policies = loadStoragePolicies();
  const policy = getBusinessStoragePolicy(policies, businessId);
  saveStoragePolicies(policies);

  let effectiveMode = policy.defaultMode || "ephemeral";
  let source = "business-default";
  let effectiveTtlHours =
    effectiveMode === "ephemeral" ? Number(policy.defaultTtlHours || 24) : null;
  if (args.override !== undefined) {
    const overrideMode = normalizeMode(args.override);
    if (policy.allowOverride) {
      effectiveMode = overrideMode;
      source = "record-override";
      effectiveTtlHours =
        effectiveMode === "ephemeral" ? Number(policy.defaultTtlHours || 24) : null;
    } else {
      source = "business-default-override-disabled";
    }
  }

  console.log(
    JSON.stringify(
      {
        businessId,
        effectiveMode,
        effectiveTtlHours,
        source
      },
      null,
      2
    )
  );
}

function commandCommentAdd(args) {
  if (!args.record) throw new Error("Missing --record");
  if (!args.text) throw new Error("Missing --text");
  const records = loadRecords();
  const record = records.find((r) => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  normalizeRecordComments(record);
  record.comments.push({
    n: args.name || "",
    x: String(args.text),
    ts: new Date().toISOString()
  });
  record.updatedAt = new Date().toISOString();
  saveRecords(records);
  console.log(JSON.stringify(record.comments, null, 2));
}

function commandCommentList(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record = records.find((r) => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  normalizeRecordComments(record);
  console.log(JSON.stringify(record.comments, null, 2));
}

function commandCommentDelete(args) {
  if (!args.record) throw new Error("Missing --record");
  if (args.index === undefined) throw new Error("Missing --index");
  const idx = toNumber(args.index, -1);
  if (idx < 0) throw new Error("Invalid --index");
  const records = loadRecords();
  const record = records.find((r) => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  normalizeRecordComments(record);
  if (idx >= record.comments.length) throw new Error("Comment index out of range");
  record.comments.splice(idx, 1);
  record.updatedAt = new Date().toISOString();
  saveRecords(records);
  console.log(JSON.stringify(record.comments, null, 2));
}

function commandDashboard(args) {
  const records = loadRecords();
  const sizes = records.map((r) => ({ id: r.id, bytes: buildShareLinkForRecord(r).bytes }));
  if (sizes.length === 0) {
    const empty = { count: 0, lowest: null, highest: null, average: 0 };
    console.log(args.json ? JSON.stringify(empty, null, 2) : "No records.");
    return;
  }
  const sorted = sizes.slice().sort((a, b) => a.bytes - b.bytes);
  const total = sorted.reduce((sum, it) => sum + it.bytes, 0);
  const avg = Math.round(total / sorted.length);
  const out = {
    count: sorted.length,
    lowest: sorted[0],
    highest: sorted[sorted.length - 1],
    average: avg
  };
  if (args.json) {
    console.log(JSON.stringify(out, null, 2));
    return;
  }
  console.log(`count=${out.count}`);
  console.log(`lowest=${out.lowest.id}:${out.lowest.bytes}`);
  console.log(`highest=${out.highest.id}:${out.highest.bytes}`);
  console.log(`average=${out.average}`);
}

function commandHowTo(args) {
  printHowTo(args.role);
}

function runCliSubcommand(argv) {
  const result = spawnSync(process.execPath, [__filename, ...argv], {
    encoding: "utf8"
  });
  if (result.status !== 0) {
    const message = (result.stderr || result.stdout || "Unknown CLI error").trim();
    throw new Error(message);
  }
  return {
    stdout: (result.stdout || "").trim(),
    stderr: (result.stderr || "").trim()
  };
}

function readJsonBody(req) {
  return new Promise((resolve, reject) => {
    let raw = "";
    req.on("data", (chunk) => {
      raw += chunk;
      if (raw.length > 2 * 1024 * 1024) {
        reject(new Error("Payload too large"));
      }
    });
    req.on("end", () => {
      if (!raw) {
        resolve({});
        return;
      }
      try {
        resolve(JSON.parse(raw));
      } catch (err) {
        reject(new Error("Invalid JSON body"));
      }
    });
    req.on("error", reject);
  });
}

function sendJson(res, status, payload) {
  res.writeHead(status, {
    "Content-Type": "application/json; charset=utf-8",
    "Cache-Control": "no-store"
  });
  res.end(JSON.stringify(payload));
}

function sendText(res, status, text, contentType = "text/plain; charset=utf-8") {
  res.writeHead(status, {
    "Content-Type": contentType,
    "Cache-Control": "no-store"
  });
  res.end(text);
}

function browserV1Html() {
  return `<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Workpads Browser</title>
  <link rel="stylesheet" href="/v1/app.css" />
</head>
<body>
  <main class="frame">
    <h1>Workpads Browser</h1>
    <p class="subtle">Simple local UI backed by <code>workpads browser</code>.</p>

    <section>
      <h2>Create Record</h2>
      <form id="create-form">
        <label>Job</label>
        <input id="job" required />
        <label>Location</label>
        <input id="location" />
        <label>Date (YYYY-MM-DD)</label>
        <input id="date" />
        <label>Details</label>
        <textarea id="details"></textarea>
        <label>Story</label>
        <textarea id="story"></textarea>
        <button type="submit">Create</button>
      </form>
    </section>

    <section>
      <h2>Import Link</h2>
      <form id="import-form">
        <input id="import-url" placeholder="https://workpads.me/new#..." />
        <button type="submit">Import</button>
      </form>
    </section>

    <section>
      <h2>Dashboard</h2>
      <pre id="dashboard"></pre>
    </section>

    <section>
      <h2>Records</h2>
      <div id="records"></div>
    </section>
  </main>

  <script src="/v1/app.js"></script>
</body>
</html>`;
}

function browserV1Css() {
  return `:root { color-scheme: light; }
* { box-sizing: border-box; font-family: system-ui, -apple-system, sans-serif; }
body {
  margin: 0;
  background: #fff;
  color: #111;
}
.frame {
  width: 100%;
  max-width: 600px;
  margin: 0 auto;
  padding: 16px;
}
h1 { margin: 0 0 12px; font-size: 1.5rem; }
h2 { margin: 0 0 8px; font-size: 1.05rem; }
section { margin-bottom: 20px; border-top: 1px solid #ddd; padding-top: 12px; }
label { display: block; margin: 8px 0 4px; font-size: 0.9rem; }
input, textarea, button {
  width: 100%;
  border: 1px solid #ccc;
  border-radius: 4px;
  padding: 8px;
  font-size: 0.95rem;
}
textarea { min-height: 64px; resize: vertical; }
button { margin-top: 10px; cursor: pointer; background: #f4f4f4; }
.subtle { color: #555; font-size: 0.9rem; }
.record { border: 1px solid #ddd; padding: 10px; border-radius: 4px; margin-bottom: 8px; }
.row { display: flex; gap: 8px; flex-wrap: wrap; }
.row button { width: auto; padding: 6px 10px; margin-top: 8px; }
pre { margin: 0; white-space: pre-wrap; border: 1px solid #ddd; padding: 8px; border-radius: 4px; }
code { background: #f4f4f4; padding: 1px 4px; border-radius: 4px; }`;
}

function browserV1Js() {
  return `async function api(path, opts = {}) {
  const res = await fetch(path, {
    headers: { "Content-Type": "application/json" },
    ...opts
  });
  const text = await res.text();
  let data = {};
  try { data = text ? JSON.parse(text) : {}; } catch (_) {}
  if (!res.ok) throw new Error(data.error || text || "Request failed");
  return data;
}

async function refresh() {
  const recordsRes = await api("/api/records");
  const dashRes = await api("/api/dashboard");
  document.getElementById("dashboard").textContent = JSON.stringify(dashRes, null, 2);
  const box = document.getElementById("records");
  box.innerHTML = "";
  for (const r of recordsRes.records) {
    const div = document.createElement("div");
    div.className = "record";
    const id = r.id;
    div.innerHTML = "<strong>" + id + "</strong><br/>"
      + "job: " + (r.process?.job || "") + "<br/>"
      + "variant: " + (r.variant || "plain") + "<br/>"
      + "storage: " + (r.storage?.mode || "unset");
    const row = document.createElement("div");
    row.className = "row";
    const shareBtn = document.createElement("button");
    shareBtn.textContent = "Share";
    shareBtn.onclick = async () => {
      const out = await api("/api/share", { method: "POST", body: JSON.stringify({ recordId: id }) });
      window.prompt("Share link", out.link);
      await refresh();
    };
    const delBtn = document.createElement("button");
    delBtn.textContent = "Delete";
    delBtn.onclick = async () => {
      await api("/api/records/" + encodeURIComponent(id), { method: "DELETE" });
      await refresh();
    };
    row.appendChild(shareBtn);
    row.appendChild(delBtn);
    div.appendChild(row);
    box.appendChild(div);
  }
}

document.getElementById("create-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const payload = {
    job: document.getElementById("job").value.trim(),
    location: document.getElementById("location").value.trim(),
    date: document.getElementById("date").value.trim(),
    details: document.getElementById("details").value.trim(),
    story: document.getElementById("story").value.trim()
  };
  await api("/api/records", { method: "POST", body: JSON.stringify(payload) });
  e.target.reset();
  await refresh();
});

document.getElementById("import-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const url = document.getElementById("import-url").value.trim();
  if (!url) return;
  await api("/api/import", { method: "POST", body: JSON.stringify({ url }) });
  e.target.reset();
  await refresh();
});

refresh().catch((err) => alert(err.message));`;
}

function browserHtml() {
  return `<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Workpads Browser</title>
  <link rel="stylesheet" href="/app.css" />
</head>
<body>
  <main class="frame">
    <h1>Workpads Browser</h1>
    <p>Local browser service for Workpads CLI. <a href="/v1/">Open pinned v1 UI</a>.</p>

    <section>
      <h2>Create</h2>
      <form id="create-form">
        <label>Job</label><input id="c-job" required />
        <label>Location</label><input id="c-location" />
        <label>Date</label><input id="c-date" />
        <label>Details</label><textarea id="c-details"></textarea>
        <label>Story</label><textarea id="c-story"></textarea>
        <button type="submit">Create Record</button>
      </form>
    </section>

    <section>
      <h2>Edit</h2>
      <form id="edit-form">
        <label>Record ID</label><input id="e-id" required placeholder="loc_000001" />
        <label>Set Pairs (one per line, ex: process.location=Dock 7)</label><textarea id="e-set"></textarea>
        <label>Add Action (Title|Notes)</label><input id="e-action" />
        <button type="submit">Apply Edit</button>
      </form>
    </section>

    <section>
      <h2>Share / Import</h2>
      <form id="share-form">
        <label>Record ID</label><input id="s-id" required placeholder="loc_000001" />
        <button type="submit">Generate Share Link</button>
      </form>
      <input id="share-link" readonly />
      <form id="import-form">
        <label>Paste Link</label><input id="i-url" placeholder="https://workpads.me/new#..." />
        <button type="submit">Import Link</button>
      </form>
    </section>

    <section>
      <h2>Comments</h2>
      <form id="comment-add-form">
        <label>Record ID</label><input id="cm-id" required />
        <label>Name (optional)</label><input id="cm-name" />
        <label>Text</label><input id="cm-text" required />
        <button type="submit">Add Comment</button>
      </form>
      <form id="comment-list-form">
        <label>Record ID</label><input id="cl-id" required />
        <button type="submit">List Comments</button>
      </form>
      <pre id="comments-output"></pre>
    </section>

    <section>
      <h2>Storage Policy</h2>
      <form id="storage-set-form">
        <label>Business</label><input id="st-business" value="biz_001" />
        <label>Default Mode</label><input id="st-mode" value="ephemeral" />
        <label>TTL Hours</label><input id="st-ttl" value="24" />
        <button type="submit">Set Policy</button>
      </form>
      <button id="storage-get-btn">Get Policy</button>
      <button id="storage-resolve-btn">Resolve (override stored)</button>
      <pre id="storage-output"></pre>
    </section>

    <section>
      <h2>Templates</h2>
      <button id="template-show-btn">Show svc-basic</button>
      <button id="template-validate-kv-btn">Validate KV</button>
      <button id="template-validate-yaml-btn">Validate YAML</button>
      <pre id="template-output"></pre>
    </section>

    <section>
      <h2>Dashboard</h2>
      <pre id="dashboard"></pre>
    </section>

    <section>
      <h2>Records</h2>
      <div id="records"></div>
    </section>
  </main>
  <script src="/app.js"></script>
</body>
</html>`;
}

function browserCss() {
  return `*{box-sizing:border-box;font-family:system-ui,-apple-system,sans-serif}
body{margin:0;background:#fff;color:#111}
.frame{width:100%;max-width:600px;margin:0 auto;padding:16px}
section{border-top:1px solid #ddd;padding-top:10px;margin-bottom:16px}
label{display:block;margin:8px 0 4px}
input,textarea,button{width:100%;padding:8px;border:1px solid #ccc;border-radius:3px}
button{margin-top:8px;background:#f4f4f4;cursor:pointer}
textarea{min-height:60px}
pre{border:1px solid #ddd;padding:8px;white-space:pre-wrap}
.record{border:1px solid #ddd;padding:8px;margin-bottom:8px}
.row{display:flex;gap:8px;flex-wrap:wrap}
.row button{width:auto;padding:6px 10px}`;
}

function browserJs() {
  return `async function api(path, opts = {}) {
  const res = await fetch(path, { headers: { "Content-Type": "application/json" }, ...opts });
  const text = await res.text();
  let data = {};
  try { data = text ? JSON.parse(text) : {}; } catch (_) {}
  if (!res.ok) throw new Error(data.error || text || "Request failed");
  return data;
}

function parseSetLines(text) {
  return String(text || "").split("\\n").map(s => s.trim()).filter(Boolean);
}

async function refresh() {
  const recordsRes = await api("/api/records");
  const dashRes = await api("/api/dashboard");
  document.getElementById("dashboard").textContent = JSON.stringify(dashRes, null, 2);
  const box = document.getElementById("records");
  box.innerHTML = "";
  for (const r of recordsRes.records) {
    const id = r.id;
    const div = document.createElement("div");
    div.className = "record";
    div.innerHTML = "<strong>" + id + "</strong><br/>job: " + (r.process?.job || "") + "<br/>variant: " + (r.variant || "plain") + "<br/>storage: " + (r.storage?.mode || "unset");
    const row = document.createElement("div");
    row.className = "row";
    const shareBtn = document.createElement("button");
    shareBtn.textContent = "Share";
    shareBtn.onclick = async () => {
      const out = await api("/api/share", { method: "POST", body: JSON.stringify({ recordId: id }) });
      document.getElementById("share-link").value = out.link || "";
      await refresh();
    };
    const delBtn = document.createElement("button");
    delBtn.textContent = "Delete";
    delBtn.onclick = async () => {
      await api("/api/records/" + encodeURIComponent(id), { method: "DELETE" });
      await refresh();
    };
    row.appendChild(shareBtn);
    row.appendChild(delBtn);
    div.appendChild(row);
    box.appendChild(div);
  }
}

document.getElementById("create-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  await api("/api/records", {
    method: "POST",
    body: JSON.stringify({
      job: document.getElementById("c-job").value.trim(),
      location: document.getElementById("c-location").value.trim(),
      date: document.getElementById("c-date").value.trim(),
      details: document.getElementById("c-details").value.trim(),
      story: document.getElementById("c-story").value.trim()
    })
  });
  e.target.reset();
  await refresh();
});

document.getElementById("edit-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  await api("/api/records/edit", {
    method: "POST",
    body: JSON.stringify({
      recordId: document.getElementById("e-id").value.trim(),
      set: parseSetLines(document.getElementById("e-set").value),
      addAction: document.getElementById("e-action").value.trim()
    })
  });
  await refresh();
});

document.getElementById("share-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const out = await api("/api/share", { method: "POST", body: JSON.stringify({ recordId: document.getElementById("s-id").value.trim() }) });
  document.getElementById("share-link").value = out.link || "";
  await refresh();
});

document.getElementById("import-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  await api("/api/import", { method: "POST", body: JSON.stringify({ url: document.getElementById("i-url").value.trim() }) });
  e.target.reset();
  await refresh();
});

document.getElementById("comment-add-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const out = await api("/api/comments/add", {
    method: "POST",
    body: JSON.stringify({
      recordId: document.getElementById("cm-id").value.trim(),
      name: document.getElementById("cm-name").value.trim(),
      text: document.getElementById("cm-text").value.trim()
    })
  });
  document.getElementById("comments-output").textContent = JSON.stringify(out, null, 2);
});

document.getElementById("comment-list-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const out = await api("/api/comments/list", { method: "POST", body: JSON.stringify({ recordId: document.getElementById("cl-id").value.trim() }) });
  document.getElementById("comments-output").textContent = JSON.stringify(out, null, 2);
});

document.getElementById("storage-set-form").addEventListener("submit", async (e) => {
  e.preventDefault();
  const out = await api("/api/storage/set", {
    method: "POST",
    body: JSON.stringify({
      business: document.getElementById("st-business").value.trim(),
      mode: document.getElementById("st-mode").value.trim(),
      ttl: document.getElementById("st-ttl").value.trim()
    })
  });
  document.getElementById("storage-output").textContent = JSON.stringify(out, null, 2);
  await refresh();
});

document.getElementById("storage-get-btn").addEventListener("click", async () => {
  const out = await api("/api/storage/get?business=" + encodeURIComponent(document.getElementById("st-business").value.trim()));
  document.getElementById("storage-output").textContent = JSON.stringify(out, null, 2);
});

document.getElementById("storage-resolve-btn").addEventListener("click", async () => {
  const out = await api("/api/storage/resolve?business=" + encodeURIComponent(document.getElementById("st-business").value.trim()) + "&override=stored");
  document.getElementById("storage-output").textContent = JSON.stringify(out, null, 2);
});

document.getElementById("template-show-btn").addEventListener("click", async () => {
  const out = await api("/api/template/show?template=svc-basic");
  document.getElementById("template-output").textContent = JSON.stringify(out, null, 2);
});
document.getElementById("template-validate-kv-btn").addEventListener("click", async () => {
  const out = await api("/api/template/validate", { method: "POST", body: JSON.stringify({ file: "./templates/svc-basic.kv", format: "kv" }) });
  document.getElementById("template-output").textContent = JSON.stringify(out, null, 2);
});
document.getElementById("template-validate-yaml-btn").addEventListener("click", async () => {
  const out = await api("/api/template/validate", { method: "POST", body: JSON.stringify({ file: "./templates/svc-basic.yaml", format: "yaml" }) });
  document.getElementById("template-output").textContent = JSON.stringify(out, null, 2);
});

refresh().catch((err) => alert(err.message));`;
}

async function handleBrowserApi(req, res, pathname) {
  try {
    const parsedUrl = new URL(req.url, "http://127.0.0.1");
    if (req.method === "GET" && pathname === "/api/health") {
      sendJson(res, 200, { ok: true });
      return;
    }
    if (req.method === "GET" && pathname === "/api/records") {
      const out = runCliSubcommand(["list", "--json"]);
      sendJson(res, 200, { records: JSON.parse(out.stdout || "[]") });
      return;
    }
    if (req.method === "POST" && pathname === "/api/records") {
      const body = await readJsonBody(req);
      const argv = ["create", "--template", "svc-basic", "--variant", "plain"];
      if (body.business) argv.push("--business", String(body.business));
      if (body.storageOverride) argv.push("--storage-override", String(body.storageOverride));
      if (body.job) argv.push("--set", `process.job=${body.job}`);
      if (body.location) argv.push("--set", `process.location=${body.location}`);
      if (body.date) argv.push("--set", `process.date=${body.date}`);
      if (body.details) argv.push("--set", `details=${body.details}`);
      if (body.story) argv.push("--set", `story=${body.story}`);
      const out = runCliSubcommand(argv);
      sendJson(res, 200, { record: JSON.parse(out.stdout || "{}") });
      return;
    }
    if (req.method === "POST" && pathname === "/api/records/edit") {
      const body = await readJsonBody(req);
      const argv = ["edit", "--record", String(body.recordId || "")];
      const setPairs = Array.isArray(body.set)
        ? body.set
        : body.set
        ? [String(body.set)]
        : [];
      setPairs.forEach((pair) => argv.push("--set", String(pair)));
      if (body.addAction) argv.push("--add-action", String(body.addAction));
      if (body.business) argv.push("--business", String(body.business));
      if (body.storageOverride) argv.push("--storage-override", String(body.storageOverride));
      const out = runCliSubcommand(argv);
      sendJson(res, 200, { record: JSON.parse(out.stdout || "{}") });
      return;
    }
    if (req.method === "DELETE" && pathname.startsWith("/api/records/")) {
      const id = decodeURIComponent(pathname.replace("/api/records/", ""));
      runCliSubcommand(["delete", "--record", id]);
      sendJson(res, 200, { ok: true });
      return;
    }
    if (req.method === "POST" && pathname === "/api/import") {
      const body = await readJsonBody(req);
      const out = runCliSubcommand(["import", "--url", String(body.url || "")]);
      sendJson(res, 200, { record: JSON.parse(out.stdout || "{}") });
      return;
    }
    if (req.method === "POST" && pathname === "/api/share") {
      const body = await readJsonBody(req);
      const out = runCliSubcommand(["share", "--record", String(body.recordId || "")]);
      sendJson(res, 200, {
        link: out.stdout,
        meta: out.stderr
      });
      return;
    }
    if (req.method === "GET" && pathname === "/api/dashboard") {
      const out = runCliSubcommand(["dashboard", "--json"]);
      sendJson(res, 200, JSON.parse(out.stdout || "{}"));
      return;
    }
    if (req.method === "POST" && pathname === "/api/comments/add") {
      const body = await readJsonBody(req);
      const argv = [
        "comment:add",
        "--record",
        String(body.recordId || ""),
        "--text",
        String(body.text || "")
      ];
      if (body.name) argv.push("--name", String(body.name));
      const out = runCliSubcommand(argv);
      sendJson(res, 200, { comments: JSON.parse(out.stdout || "[]") });
      return;
    }
    if (req.method === "POST" && pathname === "/api/comments/list") {
      const body = await readJsonBody(req);
      const out = runCliSubcommand(["comment:list", "--record", String(body.recordId || "")]);
      sendJson(res, 200, { comments: JSON.parse(out.stdout || "[]") });
      return;
    }
    if (req.method === "GET" && pathname === "/api/storage/get") {
      const business = parsedUrl.searchParams.get("business") || "";
      const out = runCliSubcommand(["storage:get", "--business", business]);
      sendJson(res, 200, JSON.parse(out.stdout || "{}"));
      return;
    }
    if (req.method === "POST" && pathname === "/api/storage/set") {
      const body = await readJsonBody(req);
      const argv = [
        "storage:set",
        "--business",
        String(body.business || ""),
        "--default",
        String(body.mode || "")
      ];
      if (body.ttl !== undefined && body.ttl !== "") argv.push("--ttl-hours", String(body.ttl));
      const out = runCliSubcommand(argv);
      sendJson(res, 200, JSON.parse(out.stdout || "{}"));
      return;
    }
    if (req.method === "GET" && pathname === "/api/storage/resolve") {
      const business = parsedUrl.searchParams.get("business") || "";
      const override = parsedUrl.searchParams.get("override");
      const argv = ["storage:resolve", "--business", business];
      if (override) argv.push("--override", override);
      const out = runCliSubcommand(argv);
      sendJson(res, 200, JSON.parse(out.stdout || "{}"));
      return;
    }
    if (req.method === "POST" && pathname === "/api/template/validate") {
      const body = await readJsonBody(req);
      const out = runCliSubcommand([
        "template:validate",
        "--file",
        String(body.file || ""),
        "--format",
        String(body.format || "kv")
      ]);
      sendJson(res, 200, JSON.parse(out.stdout || "{}"));
      return;
    }
    if (req.method === "GET" && pathname === "/api/template/show") {
      const template = parsedUrl.searchParams.get("template") || "svc-basic";
      const out = runCliSubcommand(["template:show", "--template", template]);
      sendJson(res, 200, JSON.parse(out.stdout || "{}"));
      return;
    }
    sendJson(res, 404, { error: "Not found" });
  } catch (err) {
    sendJson(res, 400, { error: err.message });
  }
}

async function commandBrowser(args) {
  const requestedPort = Number(args.port || 8787);
  const autoPort = parseBool(args["auto-port"], true);
  const maxPortTries = Number(args["max-port-tries"] || 20);
  let port = requestedPort;
  if (!Number.isInteger(port) || port <= 0) {
    throw new Error("Invalid --port");
  }
  const uiMode = String(args.ui || "latest").toLowerCase();
  if (uiMode !== "latest" && uiMode !== "v1") {
    throw new Error("Invalid --ui. Expected latest|v1");
  }
  if (!Number.isInteger(maxPortTries) || maxPortTries <= 0) {
    throw new Error("Invalid --max-port-tries");
  }

  const requestedAvailable = await checkPortAvailable(requestedPort);
  if (!requestedAvailable) {
    if (!autoPort) {
      throw new Error(
        `Port ${requestedPort} is already in use. Re-run with --auto-port true or choose --port <n>.`
      );
    }
    const fallback = await findAvailablePort(requestedPort + 1, maxPortTries);
    if (!fallback) {
      throw new Error(
        `No free port found after ${maxPortTries} attempts starting at ${requestedPort + 1}.`
      );
    }
    port = fallback;
  }

  const server = http.createServer(async (req, res) => {
    const parsed = new URL(req.url, `http://127.0.0.1:${port}`);
    const pathname = parsed.pathname;
    if (pathname.startsWith("/api/")) {
      await handleBrowserApi(req, res, pathname);
      return;
    }
    if (req.method === "GET" && (pathname === "/v1" || pathname === "/v1/")) {
      sendText(res, 200, browserV1Html(), "text/html; charset=utf-8");
      return;
    }
    if (req.method === "GET" && pathname === "/v1/app.css") {
      sendText(res, 200, browserV1Css(), "text/css; charset=utf-8");
      return;
    }
    if (req.method === "GET" && pathname === "/v1/app.js") {
      sendText(res, 200, browserV1Js(), "application/javascript; charset=utf-8");
      return;
    }
    if (req.method === "GET" && pathname === "/") {
      if (uiMode === "v1") {
        sendText(res, 200, browserV1Html(), "text/html; charset=utf-8");
      } else {
        sendText(res, 200, browserHtml(), "text/html; charset=utf-8");
      }
      return;
    }
    if (req.method === "GET" && pathname === "/app.css") {
      sendText(res, 200, browserCss(), "text/css; charset=utf-8");
      return;
    }
    if (req.method === "GET" && pathname === "/app.js") {
      sendText(res, 200, browserJs(), "application/javascript; charset=utf-8");
      return;
    }
    sendText(res, 404, "Not found");
  });

  server.on("error", (err) => {
    if (err && err.code === "EADDRINUSE") {
      console.error(`Error: Port ${port} is already in use on 127.0.0.1.`);
      console.error(`Try either:`);
      console.error(`  node ./workpads.js browser --auto-port true`);
      console.error(`  node ./workpads.js browser --port ${port + 1}`);
      console.error(`or stop existing service:`);
      console.error(`  node ./workpads.js browser:stop`);
      process.exit(1);
      return;
    }
    console.error(`Error: ${err.message || "Failed to start browser service"}`);
    process.exit(1);
  });

  server.listen(port, "127.0.0.1", () => {
    const state = {
      pid: process.pid,
      port,
      ui: uiMode,
      startedAt: new Date().toISOString(),
      url: `http://127.0.0.1:${port}`
    };
    saveBrowserState(state);
    if (port !== requestedPort) {
      console.log(
        `Workpads browser requested port ${requestedPort} was busy; started on ${port} instead.`
      );
    }
    console.log(`Workpads browser running at ${state.url} (ui=${uiMode})`);
  });

  const shutdown = () => {
    clearBrowserState();
    process.exit(0);
  };
  process.on("SIGINT", shutdown);
  process.on("SIGTERM", shutdown);
}

// ── TRIG compiler ─────────────────────────────────────────────────────────────

const TRIG_PAT = {
  show_always:0x00, always:0x00,
  known_contact_show:0x01, known_contact:0x01,
  has_app_show:0x02, has_app:0x02,
  code_verified_show:0x03, code_verified:0x03,
  human_show:0x04, human:0x04,
  known_or_app_show:0x05, known_or_app:0x05,
  known_and_app_show:0x06, known_and_app:0x06,
  always_blank:0x07,
  form_always:0x08, form:0x08,
  form_if_human:0x09,
  service_menu_always:0x0A, service_menu:0x0A,
  service_menu_known:0x0B,
};
const TRIG_PAT_BY_ID = ["show_always","known_contact_show","has_app_show","code_verified_show",
  "human_show","known_or_app_show","known_and_app_show","always_blank",
  "form_always","form_if_human","service_menu_always","service_menu_known"];
const TRIG_THEME = { neutral:0, warm:1, cool:2, dark:3 };
const TRIG_COND = {
  has_app:0, known_contact:1, code_verified:2, is_human:3, human:3,
  has_saved_record:4, org_match:5, has_template:6, daylight_hours:7,
  recent_contact:8, app_version_ok:9, reply_pending:10, location_near:11,
};
const TRIG_COND_BY_ID = ["has_app","known_contact","code_verified","is_human",
  "has_saved_record","org_match","has_template","daylight_hours",
  "recent_contact","app_version_ok","reply_pending","location_near"];
const TRIG_MODE = { card:0, list:1, form:2, minimal:3, ticker:4, blank:5, native:6 };
const TRIG_MODE_BY_ID = ["card","list","form","minimal","ticker","blank","native"];

function compileTrig(expr) {
  const s = String(expr).trim().toLowerCase().replace(/\s+/g," ");

  // ternary: "cond ? mode_true : mode_false"
  const tm = s.match(/^(\w+)\s*\?\s*(\w+)\s*:\s*(\w+)$/);
  if (tm) {
    const condId = TRIG_COND[tm[1]];
    if (condId == null) throw new Error(`Unknown TRIG condition: "${tm[1]}"\nValid: ${Object.keys(TRIG_COND).filter(k=>TRIG_COND[k]===TRIG_COND[k]).join(", ")}`);
    const modeTrue = TRIG_MODE[tm[2]];
    if (modeTrue == null) throw new Error(`Unknown TRIG display mode: "${tm[2]}"\nValid: ${Object.keys(TRIG_MODE).join(", ")}`);
    const modeFalseRaw = tm[3];
    const modeFalse = modeFalseRaw === "blank" ? 0xFF : modeFalseRaw === "native" ? 0xFE :
      (TRIG_MODE[modeFalseRaw] != null ? TRIG_MODE[modeFalseRaw] : null);
    if (modeFalse == null) throw new Error(`Unknown TRIG display mode: "${modeFalseRaw}"`);
    // header: VER=00, HAS_TERNARY=1, PROG_LEN=4 → 0x14
    return { hasTrigBlock: true, trigBytes: [0x14, 0x90, condId, modeTrue, modeFalse] };
  }

  // preset with theme: "human_show:warm"
  const ci = s.indexOf(":");
  if (ci !== -1) {
    const patName = s.slice(0, ci).trim(), themeName = s.slice(ci + 1).trim();
    const patId = TRIG_PAT[patName];
    if (patId == null) throw new Error(`Unknown TRIG pattern: "${patName}"`);
    const themeId = TRIG_THEME[themeName];
    if (themeId == null) throw new Error(`Unknown TRIG theme: "${themeName}"\nValid: neutral|warm|cool|dark`);
    return { hasTrigBlock: true, trigBytes: [patId, 0x10 | themeId] };
  }

  // preset name alone
  const patId = TRIG_PAT[s];
  if (patId != null) return { hasTrigBlock: true, trigBytes: [patId] };

  // raw hex bytes: "01 13" or "0113"
  const hexClean = s.replace(/0x/g,"").replace(/\s+/g,"");
  if (/^[0-9a-f]+$/.test(hexClean)) {
    if (hexClean.length % 2 !== 0) throw new Error("TRIG hex must have even number of digits");
    const bytes = [];
    for (let i = 0; i < hexClean.length; i += 2) bytes.push(parseInt(hexClean.slice(i, i+2), 16));
    if (bytes.length > 20) throw new Error("TRIG program max 20 bytes");
    return { hasTrigBlock: true, trigBytes: bytes };
  }

  throw new Error(
    `Cannot parse --trig: "${expr}"\n` +
    `Valid forms:\n` +
    `  preset name     e.g. human_show\n` +
    `  preset:theme    e.g. known_contact:dark\n` +
    `  cond ? m : m    e.g. "known_contact ? card : form"\n` +
    `  hex bytes       e.g. "14 90 01 00 ff"\n` +
    `Preset names: ${Object.keys(TRIG_PAT).filter((k,i,a)=>a.indexOf(k)===i).join(", ")}`
  );
}

// ── C-TRIG (chain obligation evaluator) ──────────────────────────────────────
// §5.1 direct condition IDs (0x00–0x0E)
const CTRIG_COND = {
  has_phone:0x00, has_email:0x01, has_worker_id:0x02, has_uid:0x03,
  is_org:0x04, is_verified:0x05, has_signature:0x06, has_chain:0x07,
  ack_received:0x08, payment_confirmed:0x09, date_reached:0x0A,
  ratification_complete:0x0B, marker_written:0x0C, linked_record_exists:0x0D,
  all_parties_acked:0x0E,
};
// Extended conditions: 0x1F [cat:4 id:4] — cat=1 financial
const CTRIG_COND_EXT = {
  full_payment_confirmed:0x12, partial_payment:0x11, overpayment:0x13,
  deposit_received:0x10,
};

// Named C-TRIG program presets
// Header byte: VER=00, MODE=1 (bit5), PROG_LEN bits 4-0
//   → 0x20 | progLen
const CTRIG_PROGRAMS = {
  // Release on ACK: if ack_received → COMPLETE
  release_on_ack:       [0x20 | 2, 0x08, 0xD0],
  // Deposit then complete: full_payment_confirmed → COMPLETE
  deposit_then_complete:[0x20 | 3, 0x1F, 0x12, 0xD0],
  // Payment then complete: payment_confirmed → RELEASE_AMT → COMPLETE
  payment_then_complete:[0x20 | 4, 0x09, 0x20, 0x00, 0xD0],
  // Marker write both parties: push ratification_complete, then write marker for role-1 and role-2
  write_marker_both:    [0x20 | 3, 0x0B, 0x71, 0x72],
  // Dispute path: date_reached without ack → DISPUTE
  dispute_on_overdue:   [0x20 | 4, 0x0A, 0x1B, 0x08, 0xE0],
};

function compileCTrig(expr) {
  const s = String(expr).trim().toLowerCase().replace(/\s+/g, " ");

  // named preset
  if (CTRIG_PROGRAMS[s]) {
    const prog = CTRIG_PROGRAMS[s];
    return { hasTrigBlock: true, trigBytes: prog };
  }

  // cond -> action  (e.g. "payment_confirmed -> complete")
  const am = s.match(/^(\w+)\s*->\s*(\w+)$/);
  if (am) {
    const condName = am[1], actName = am[2];
    let condBytes;
    if (CTRIG_COND[condName] != null) {
      condBytes = [CTRIG_COND[condName]];
    } else if (CTRIG_COND_EXT[condName] != null) {
      condBytes = [0x1F, CTRIG_COND_EXT[condName]];
    } else {
      throw new Error(`Unknown C-TRIG condition: "${condName}"\nValid: ${Object.keys(CTRIG_COND).concat(Object.keys(CTRIG_COND_EXT)).join(", ")}`);
    }
    const ACT = { complete:0xD0, dispute:0xE0, release_amt:0x20, marker_write:0x70,
                  require_ack:0x50, time_lock:0x60, assert_state:0x40 };
    const actByte = ACT[actName];
    if (actByte == null) throw new Error(`Unknown C-TRIG action: "${actName}"\nValid: ${Object.keys(ACT).join(", ")}`);
    const prog = [0x20 | (condBytes.length + 1), ...condBytes, actByte];
    return { hasTrigBlock: true, trigBytes: prog };
  }

  // raw hex
  const hexClean = s.replace(/0x/g, "").replace(/\s+/g, "");
  if (/^[0-9a-f]+$/.test(hexClean)) {
    if (hexClean.length % 2 !== 0) throw new Error("C-TRIG hex must have even number of digits");
    const bytes = [];
    for (let i = 0; i < hexClean.length; i += 2) bytes.push(parseInt(hexClean.slice(i, i + 2), 16));
    if (bytes.length > 33) throw new Error("C-TRIG program max 32 bytes + header");
    return { hasTrigBlock: true, trigBytes: bytes };
  }

  throw new Error(
    `Cannot parse --ctrig: "${expr}"\n` +
    `Valid forms:\n` +
    `  preset name        e.g. payment_then_complete\n` +
    `  cond -> action     e.g. "payment_confirmed -> complete"\n` +
    `  hex bytes          e.g. "22 09 20 d0"\n` +
    `Presets: ${Object.keys(CTRIG_PROGRAMS).join(", ")}\n` +
    `Conditions: ${Object.keys(CTRIG_COND).concat(Object.keys(CTRIG_COND_EXT)).join(", ")}`
  );
}

// C-TRIG evaluator (ctrig-evaluator-spec.md §11)
function evaluateCTrig(progBytes, ctx) {
  // progBytes[0] is header; program starts at progBytes[1]
  const prog = progBytes.slice(1);
  let ip = 0;
  const stack = [];

  function nextByte() {
    if (ip >= prog.length) throw new Error("C-TRIG: unexpected end of program");
    return prog[ip++];
  }

  function evalCond(id) {
    if (id === 0x1F) {
      // escape byte — next byte is extended condition
      const ext = nextByte();
      const extName = Object.keys(CTRIG_COND_EXT).find(k => CTRIG_COND_EXT[k] === ext);
      return ctx[extName || ("ext_" + ext.toString(16))] || false;
    }
    // extended condition range (0x10–0x1E) — emitted directly as PUSH_COND arg
    const extName = Object.keys(CTRIG_COND_EXT).find(k => CTRIG_COND_EXT[k] === id);
    if (extName) return ctx[extName] || false;
    const name = Object.keys(CTRIG_COND).find(k => CTRIG_COND[k] === id);
    return ctx[name || ("cond_" + id.toString(16))] || false;
  }

  const results = [];

  while (ip < prog.length) {
    const byte = nextByte();
    const op = (byte >> 4) & 0xF;
    const arg = byte & 0xF;

    switch (op) {
      case 0x1: { // PUSH_COND
        const condId = nextByte();
        stack.push(evalCond(condId));
        break;
      }
      case 0x2: { // RELEASE_AMT
        const amt = nextByte();
        results.push({ action: "release_amt", pct: amt });
        break;
      }
      case 0x3: { // TRIGGER_OBL
        results.push({ action: "trigger_obligation", id: arg });
        break;
      }
      case 0x4: { // ASSERT_STATE
        results.push({ action: "assert_state", state: arg });
        break;
      }
      case 0x5: { // REQUIRE_ACK
        results.push({ action: "require_ack", role: arg });
        break;
      }
      case 0x6: { // TIME_LOCK
        const days = nextByte();
        results.push({ action: "time_lock", days });
        break;
      }
      case 0x7: { // MARKER_WRITE
        results.push({ action: "marker_write", role: arg });
        break;
      }
      case 0x8: { // AND
        const b2 = stack.pop(), b1 = stack.pop();
        stack.push(!!(b1 && b2));
        break;
      }
      case 0x9: { // OR
        const b2 = stack.pop(), b1 = stack.pop();
        stack.push(!!(b1 || b2));
        break;
      }
      case 0xA: { // NOT
        stack.push(!stack.pop());
        break;
      }
      case 0xB: { // IF_THEN
        const cond = stack.pop();
        const thenByte = nextByte();
        if (cond) results.push({ action: "if_then_true", byte: thenByte });
        break;
      }
      case 0xC: { // BRANCH
        const offset = nextByte();
        const cond = stack.pop();
        if (!cond) ip += offset;
        break;
      }
      case 0xD: { // COMPLETE
        results.push({ action: "complete" });
        break;
      }
      case 0xE: { // DISPUTE
        results.push({ action: "dispute" });
        break;
      }
      case 0xF: { // VERSION
        // version declaration — skip operand byte
        nextByte();
        break;
      }
      default:
        // direct condition byte (op 0x0): treat byte as condition id
        stack.push(evalCond(byte));
        break;
    }
  }

  return { results, stack };
}

// ── Frame inspect helpers ─────────────────────────────────────────────────────

function hex2i(b)  { return "0x" + ("00"   + (b & 0xff).toString(16)).slice(-2); }
function bin8i(b)  { return ("00000000"    + (b & 0xff).toString(2)).slice(-8); }
function hexBufi(buf, max) {
  const n = Math.min(buf.length, max || 8);
  let s = "";
  for (let i = 0; i < n; i++) s += ("0" + buf[i].toString(16)).slice(-2);
  if (buf.length > n) s += "…";
  return s;
}

const FF_NAMES  = ["job","customer","date","location","meeting_time","start_time",
                   "end_time","customer_phone","worker","actions","details","story",
                   "_financial","ref_number","due_date","FLAGS3_PRESENT"];
const F3_NAMES  = ["context_label","tag","qty_unit","date_end","attachment","uid","url","FLAGS4_PRESENT"];
const BT_NAMES  = ["svc-basic","invoice","quote","contact","profile","state-commit","ext-A","ext-B"];
const DOMAIN_N  = ["none","invoice/expense","standard-ledger","hybrid"];

const INSPECT_FIELDS = [
  { id: "job",            bit:  0, type: "text"    },
  { id: "customer",       bit:  1, type: "text"    },
  { id: "date",           bit:  2, type: "date"    },
  { id: "location",       bit:  3, type: "text"    },
  { id: "meeting_time",   bit:  4, type: "time"    },
  { id: "start_time",     bit:  5, type: "time"    },
  { id: "end_time",       bit:  6, type: "time"    },
  { id: "customer_phone", bit:  7, type: "text"    },
  { id: "worker",         bit:  8, type: "text"    },
  { id: "actions",        bit:  9, type: "actions" },
  { id: "details",        bit: 10, type: "text"    },
  { id: "story",          bit: 11, type: "text"    },
  { id: "_financial",     bit: 12, type: "fin"     },
  { id: "ref_number",     bit: 13, type: "compact" },
  { id: "due_date",       bit: 14, type: "date"    },
];
const INSPECT_FIELDS3 = [
  { id: "context_label", bit: 0, type: "compact" },
  { id: "tag",           bit: 1, type: "compact" },
  { id: "qty_unit",      bit: 2, type: "compact" },
  { id: "date_end",      bit: 3, type: "date"    },
  { id: "attachment",    bit: 4, type: "text"    },
  { id: "uid",           bit: 5, type: "text"    },
  { id: "url",           bit: 6, type: "text"    },
];

function parseFrameBytes(fb) {
  const b   = Buffer.isBuffer(fb) ? fb : Buffer.from(fb);
  const items = [];
  let   pos   = 0;

  function rb()     { return b[pos++]; }
  function ru16()   { const v = ((b[pos] & 0xff) << 8) | (b[pos + 1] & 0xff); pos += 2; return v; }
  function rtext()  { const len = ru16(); const s = b.slice(pos, pos + len).toString("utf8"); pos += len; return { len, s }; }
  function rcomp()  { const len = rb();  const s = b.slice(pos, pos + len).toString("utf8"); pos += len; return { len, s }; }
  function rdate(compact) {
    if (compact) {
      const days = ru16();
      const d = new Date(Date.UTC(2000,0,1) + days * 86400000);
      return { enc: "uint16 days (epoch 2000-01-01)", val: d.getUTCFullYear() + "-" +
        String(d.getUTCMonth()+1).padStart(2,"0") + "-" + String(d.getUTCDate()).padStart(2,"0"), raw: days };
    }
    const { s } = rtext(); return { enc: "[uint16 len][UTF-8]", val: s };
  }
  function rtime(compact) {
    if (compact) {
      const m = ru16(); const h = Math.floor(m/60), mn = m%60;
      return { enc: "uint16 minutes", val: String(h).padStart(2,"0")+":"+String(mn).padStart(2,"0"), raw: m };
    }
    const { s } = rtext(); return { enc: "[uint16 len][UTF-8]", val: s };
  }
  function push(off, name, hex, bin, sub) { items.push({ offset: off, name, hex, bin, sub }); }

  // meta1
  const m1off = pos, m1 = rb();
  const META2 = (m1>>7)&1, EXT = (m1>>6)&1, BT = (m1>>3)&7;
  push(m1off, "meta1", hex2i(m1), bin8i(m1), [
    ["META2_PRESENT", META2, META2 ? "meta2 follows" : "absent"],
    ["EXT_TEMPLATE",  EXT,   EXT   ? "extended"      : "standard"],
    ["BASE_TEMPLATE", BT,    (BT_NAMES[BT]||"?")+" ("+BT+")"],
    ["ACK_REQUEST",   (m1>>2)&1, ((m1>>2)&1) ? "yes" : "no"],
    ["CHAIN",         (m1>>1)&1, ((m1>>1)&1) ? "yes" : "no"],
    ["RECIPIENT_TYPE", m1&1,      (m1&1)      ? "yes" : "no"],
  ]);

  // ext_template
  if (EXT) {
    const eo = pos, sig = BT;
    const extLen = sig===1?1 : sig===2?2 : sig===3?3 : sig===4?3 : 0;
    const extBytes = []; for (let i=0; i<extLen; i++) extBytes.push(rb());
    push(eo, "ext_template", hexBufi(Buffer.from(extBytes), 4), "",
      [["bytes", extLen, "ext-template ID ("+extLen+" byte"+( extLen!==1?"s":"")+")" ]]);
  }

  // meta2
  let compactTime = false, domain = 0, hasTrig = false, hasParticipants = false;
  if (META2) {
    const m2off = pos, m2 = rb();
    compactTime    = !!((m2>>6)&1);
    hasTrig        = !!((m2>>5)&1);
    hasParticipants= !!((m2>>4)&1);
    domain         = (m2>>2)&3;
    push(m2off, "meta2", hex2i(m2), bin8i(m2), [
      ["SELF_DESCRIBING", (m2>>7)&1, ((m2>>7)&1) ? "yes" : "no"],
      ["COMPACT_TIME",    compactTime?1:0, compactTime ? "binary date/time" : "text date/time"],
      ["HAS_TRIG",        hasTrig?1:0,     hasTrig        ? "yes" : "no"],
      ["PARTICIPANTS",    hasParticipants?1:0, hasParticipants ? "block follows" : "absent"],
      ["DOMAIN",          domain,          DOMAIN_N[domain]||"?"],
      ["DRAFT",           (m2>>1)&1,       ((m2>>1)&1)  ? "yes" : "no"],
      ["RESTRICT_FWD",    m2&1,             (m2&1)       ? "yes" : "no"],
    ]);
  }

  // financial context
  const isStateCommit = !EXT && BT === 5;
  let decimalPos = 0, sfPresent = false, sfIdx = 0;
  if (domain > 0 || isStateCommit) {
    const so = pos, sb = rb();
    decimalPos = (sb>>5)&7; const currency = (sb>>3)&3; const taxCode = (sb>>1)&3; sfPresent = !!(sb&1);
    const dpLabel = decimalPos===7 ? "flat uint24" : decimalPos+" decimal places";
    const curNames = ["GBP","EUR","USD","extended"];
    push(so, "setup_byte", hex2i(sb), bin8i(sb), [
      ["DECIMAL_POS", decimalPos, dpLabel],
      ["CURRENCY",    currency,   curNames[currency]||"?"],
      ["TAX_CODE",    taxCode,    taxCode===0 ? "none" : "code "+taxCode],
      ["SF_PRESENT",  sfPresent?1:0, sfPresent ? "scaling factor follows" : "no"],
    ]);
    if (currency === 3) { const co=pos, ce=rb(); push(co,"currency_ext",hex2i(ce),bin8i(ce),[["code",ce,"currency code "+ce]]); }
    if (sfPresent) {
      const sfo=pos, sfb=rb(); sfIdx=(sfb>>5)&7;
      push(sfo,"sf_byte",hex2i(sfb),bin8i(sfb),[
        ["SF_IDX",      sfIdx,        "×"+[1,10,100,1000,10000,100000,1000000,1000000000][sfIdx]],
        ["COMPOUND_VAL",(sfb>>4)&1,   ((sfb>>4)&1) ? "compound" : "simple"],
        ["QTY_COMPACT", (sfb>>3)&1,   ((sfb>>3)&1) ? "yes" : "no"],
        ["SPLIT_POINT", sfb&7,        (sfb&7)+""],
      ]);
    }
    // transaction byte
    const to=pos, tx=rb();
    if (isStateCommit) {
      push(to,"state_commit",hex2i(tx),bin8i(tx),[
        ["COMMIT_TYPE",   (tx>>6)&3, (tx>>6)&3+""],
        ["PERIOD_TYPE",   (tx>>4)&3, (tx>>4)&3+""],
        ["CHAIN_COMPLETE",(tx>>3)&1, ((tx>>3)&1)?"yes":"no"],
        ["DISPUTE_FLAG",  (tx>>2)&1, ((tx>>2)&1)?"yes":"no"],
      ]);
    } else if (domain === 2) {
      push(to,"transaction_byte",hex2i(tx),bin8i(tx),[
        ["ACCOUNT_PAIR",(tx>>4)&0xF, "pair "+((tx>>4)&0xF)],
        ["AP_DIRECTION",(tx>>3)&1,   ((tx>>3)&1)?"out":"in"],
        ["AP_STATUS",   (tx>>2)&1,   (tx>>2)&1+""],
        ["QTY_SPLIT",   (tx>>1)&1,   ((tx>>1)&1)?"yes":"no"],
        ["ROUNDING",    tx&1,        tx&1+""],
      ]);
    } else {
      const ioDir=(tx>>7)&1, ioTm=(tx>>6)&1, ioEff=(tx>>5)&1;
      const label=(ioDir?"O":"I")+(ioTm?"<":">")+( ioEff?"I":"O");
      push(to,"transaction_byte",hex2i(tx),bin8i(tx),[
        ["I/O_STATE",  (ioDir<<2)|(ioTm<<1)|ioEff, label],
        ["IO_SUBTYPE", (tx>>3)&3,  (tx>>3)&3+""],
        ["QTY_SPLIT",  (tx>>2)&1, ((tx>>2)&1)?"yes":"no"],
        ["ROUNDING",   tx&3,       tx&3+""],
      ]);
    }
    if (domain === 3 && !isStateCommit) {
      const ao=pos, ab=rb();
      push(ao,"account_pair_byte",hex2i(ab),bin8i(ab),[
        ["ACCOUNT_PAIR",   (ab>>4)&0xF, "pair "+((ab>>4)&0xF)],
        ["AP_DIRECTION",   (ab>>3)&1,   ((ab>>3)&1)?"out":"in"],
        ["AP_STATUS",      (ab>>2)&1,   (ab>>2)&1+""],
        ["AP_COMPLETENESS",(ab>>1)&1,   ((ab>>1)&1)?"complete":"partial"],
      ]);
    }
  }

  // field_flags
  const ffo = pos, ff = ru16();
  const activeBits = [];
  for (let i=0; i<16; i++) if (ff&(1<<i)) activeBits.push(i);
  push(ffo, "field_flags",
    "0x"+("0000"+ff.toString(16)).slice(-4),
    bin8i(ff>>8)+" "+bin8i(ff&0xff),
    activeBits.map((bit)=>["bit "+String(bit).padStart(2),1, FF_NAMES[bit]||("bit"+bit)])
  );

  // flags3
  let f3 = 0;
  if (ff & (1<<15)) {
    const f3o=pos; f3=rb();
    const f3bits = [];
    for (let i=0;i<8;i++) if (f3&(1<<i)) f3bits.push(["bit "+i,1,F3_NAMES[i]||("bit"+i)]);
    push(f3o,"flags3",hex2i(f3),bin8i(f3), f3bits.length?f3bits:[["(all absent)",0,""]]);
  }

  // flags4
  let f4 = 0;
  if (f3 & (1<<7)) {
    const f4o=pos; f4=rb();
    const f4bits = [];
    for (let i=0;i<8;i++) if (f4&(1<<i)) f4bits.push(["bit "+i,1,"flags4 bit "+i]);
    push(f4o,"flags4",hex2i(f4),bin8i(f4), f4bits.length?f4bits:[["(all absent)",0,""]]);
  }

  // data blocks
  for (const fd of INSPECT_FIELDS) {
    if (!(ff & (1<<fd.bit))) continue;
    const doff = pos;
    if (fd.type === "text") {
      const { s } = rtext();
      const preview = s.length > 48 ? s.slice(0,45)+"…" : s;
      push(doff, fd.id, hexBufi(b.slice(doff,pos),6), "", [
        ["enc", 0, "[uint16 len][UTF-8]"],
        ["val", 0, preview],
      ]);
    } else if (fd.type === "compact") {
      const { len, s } = rcomp();
      push(doff, fd.id, hexBufi(b.slice(doff,pos),6), "", [
        ["enc", 0, "[uint8 len][UTF-8]  len="+len],
        ["val", 0, s.length>48?s.slice(0,45)+"…":s],
      ]);
    } else if (fd.type === "date") {
      const r = rdate(compactTime);
      push(doff, fd.id, hexBufi(b.slice(doff,pos),4), "", [
        ["enc",0,r.enc], ["val",0,r.val],
      ]);
    } else if (fd.type === "time") {
      const r = rtime(compactTime);
      push(doff, fd.id, hexBufi(b.slice(doff,pos),4), "", [
        ["enc",0,r.enc], ["val",0,r.val],
      ]);
    } else if (fd.type === "actions") {
      const { s } = rtext();
      const lines = s ? s.split("\n") : [];
      const sub = [["enc",0,"[uint16 len][UTF-8 \\n-joined]  count="+lines.length]];
      lines.forEach((t,i)=>sub.push([String(i+1).padStart(2),0, t.length>45?t.slice(0,42)+"…":t]));
      push(doff,"actions",hexBufi(b.slice(doff,pos),6),"",sub);
    } else if (fd.type === "fin") {
      const fc = rb(); const custBit=(fc>>1)&1, workBit=fc&1;
      const billed=(fc>>7)&1, modeInd=(fc>>6)&1;
      const sub = [
        ["fin_control",0, hex2i(fc)+"  "+bin8i(fc)],
        ["BILLED",     billed, billed?"yes":"no"],
      ];
      if (modeInd) {
        sub.push(["MODE",        1,               "standard-ledger"]);
        sub.push(["ACCOUNT_PAIR",(fc>>2)&0xF,    "pair "+((fc>>2)&0xF)]);
      } else {
        const cat=(fc>>2)&3;
        sub.push(["MODE",       0, "invoice/expense"]);
        sub.push(["QTY_TYPE",   (fc>>5)&1, ((fc>>5)&1)?"time/hours":"units"]);
        sub.push(["EXPENSE_CAT",cat,["job-charge","job-cost/COGS","running-cost","RESERVED"][cat]]);
      }
      if (custBit) { const a=((b[pos]<<16)|(b[pos+1]<<8)|b[pos+2]); pos+=3; sub.push(["cust_amount",a,a+" (raw u24)"]); }
      if (workBit) { const a=((b[pos]<<16)|(b[pos+1]<<8)|b[pos+2]); pos+=3; sub.push(["work_amount",a,a+" (raw u24)"]); }
      push(doff,"_financial",hexBufi(b.slice(doff,pos),6),"",sub);
    }
  }

  // FIELDS3 data blocks
  for (const fd of INSPECT_FIELDS3) {
    if (!(f3 & (1<<fd.bit))) continue;
    const doff = pos;
    if (fd.type === "compact") {
      const { len, s } = rcomp();
      push(doff,fd.id,hexBufi(b.slice(doff,pos),6),"",[
        ["enc",0,"[uint8 len][UTF-8]  len="+len],["val",0,s.length>48?s.slice(0,45)+"…":s]]);
    } else if (fd.type === "text") {
      const { s } = rtext();
      push(doff,fd.id,hexBufi(b.slice(doff,pos),6),"",[
        ["enc",0,"[uint16 len][UTF-8]"],["val",0,s.length>48?s.slice(0,45)+"…":s]]);
    } else if (fd.type === "date") {
      const r = rdate(compactTime);
      push(doff,fd.id,hexBufi(b.slice(doff,pos),4),"",[["enc",0,r.enc],["val",0,r.val]]);
    }
  }

  if (hasParticipants) {
    items.push({ offset: pos, name: "participants", hex: "…", bin: "",
      sub: [["note",0,"participants block — not decoded; TRIG decode skipped"]] });
  } else if (hasTrig) {
    const toff = pos;
    const tlen = rb();
    const tsub = [["trig_len", tlen, tlen + " byte" + (tlen !== 1 ? "s" : "")]];
    if (tlen === 0) {
      tsub.push(["program", 0, "empty — shell defaults SHOW_ALWAYS NATIVE"]);
    } else if (tlen === 1) {
      const tok = rb();
      tsub.push(["mode",    0,   "Pattern token"]);
      tsub.push(["pattern", tok, TRIG_PAT_BY_ID[tok & 0x0F] || "0x"+tok.toString(16)]);
    } else if (tlen === 2) {
      const tok = rb(), thy = rb();
      if ((tok & 0xF0) === 0x00 && (thy & 0xF0) === 0x10) {
        tsub.push(["mode",    0,   "Pattern + theme"]);
        tsub.push(["pattern", tok, TRIG_PAT_BY_ID[tok & 0x0F] || "0x"+tok.toString(16)]);
        tsub.push(["theme",   thy & 0x0F, ["neutral","warm","cool","dark"][thy & 0x0F] || "?"]);
      } else {
        tsub.push(["byte_0", tok, hex2i(tok)]);
        tsub.push(["byte_1", thy, hex2i(thy)]);
      }
    } else {
      const hdr = rb();
      const ver  = (hdr >> 6) & 3;
      const mode = (hdr >> 5) & 1; // 0=display TRIG, 1=C-TRIG
      const progLen = hdr & 0x1F;

      if (mode === 1) {
        // C-TRIG (chain obligation evaluator)
        tsub.push(["mode",     0,       "C-TRIG (chain obligation evaluator)"]);
        tsub.push(["header",   hdr,     hex2i(hdr) + "  " + bin8i(hdr)]);
        tsub.push(["VER",      ver,     ver === 0 ? "v1" : "unknown"]);
        tsub.push(["PROG_LEN", progLen, progLen + " instr bytes"]);
        const progBytes = [];
        for (let i = 0; i < progLen && pos < toff + 1 + tlen; i++) progBytes.push(rb());
        tsub.push(["program",  0, progBytes.map(b => b.toString(16).padStart(2,"0")).join(" ")]);
        // Try to decode known opcodes
        for (let i = 0; i < progBytes.length; i++) {
          const b = progBytes[i];
          if (b === 0xD0) tsub.push(["opcode", b, "COMPLETE"]);
          else if (b === 0xE0) tsub.push(["opcode", b, "DISPUTE"]);
          else if (b === 0x70) tsub.push(["opcode", b, "MARKER_WRITE role=" + (b & 0xF)]);
          else if ((b >> 4) === 0x7) tsub.push(["opcode", b, "MARKER_WRITE role=" + (b & 0xF)]);
          else if ((b >> 4) === 0x5) tsub.push(["opcode", b, "REQUIRE_ACK role=" + (b & 0xF)]);
          else if ((b >> 4) === 0x6) tsub.push(["opcode", b, "TIME_LOCK days=" + (progBytes[++i] || "?")]);
          else if ((b >> 4) === 0x2) tsub.push(["opcode", b, "RELEASE_AMT pct=" + (progBytes[++i] || "?")]);
          else if (b === 0x1F && i + 1 < progBytes.length) {
            const ext = progBytes[++i];
            const extName = Object.keys(CTRIG_COND_EXT).find(k => CTRIG_COND_EXT[k] === ext) || ("ext_" + ext.toString(16));
            tsub.push(["cond_ext", ext, "PUSH_COND(ext) " + extName]);
          } else if (b <= 0x0E) {
            const cn = Object.keys(CTRIG_COND).find(k => CTRIG_COND[k] === b) || ("cond_" + b.toString(16));
            tsub.push(["cond", b, "PUSH_COND " + cn]);
          } else {
            tsub.push(["byte", b, hex2i(b)]);
          }
        }
      } else {
        // Display TRIG
        const hasTernaryBit = (hdr >> 4) & 1;
        tsub.push(["mode",        0,             "Display TRIG bytecode"]);
        tsub.push(["header",      hdr,           hex2i(hdr) + "  " + bin8i(hdr)]);
        tsub.push(["VER",         ver,           ver === 0 ? "v1" : "unknown"]);
        tsub.push(["HAS_TERNARY", hasTernaryBit, hasTernaryBit ? "yes" : "no"]);
        tsub.push(["PROG_LEN",    progLen & 0xF, (progLen & 0xF) + " instr bytes"]);
        if (hasTernaryBit && pos + 4 <= toff + 1 + tlen) {
          const op = rb();
          if (op === 0x90) {
            const condId = rb(), mTrue = rb(), mFalse = rb();
            const cn  = TRIG_COND_BY_ID[condId]  || "cond_" + condId;
            const mt  = TRIG_MODE_BY_ID[mTrue]   || "mode_" + mTrue;
            const mf  = mFalse === 0xFF ? "blank" : mFalse === 0xFE ? "native" : (TRIG_MODE_BY_ID[mFalse] || "mode_" + mFalse);
            tsub.push(["TERNARY", 0, cn + " ? " + mt + " : " + mf]);
          }
        }
      }
    }
    push(toff, "trig_block", hexBufi(b.slice(toff, toff + 1 + tlen), 6), "", tsub);
  }

  return { items, totalBytes: b.length };
}

function fmtInspect(record, trigOpts) {
  const flat = flattenForCodec(record);
  const { compressed, frameSize } = WPCodec.encodeBinary(flat, trigOpts || {});
  let frameBytes;
  try { frameBytes = zlib.inflateRawSync(Buffer.from(compressed)); }
  catch (e) { throw new Error("Frame decompress failed: " + e.message); }

  const { items } = parseFrameBytes(frameBytes);
  const out = [];
  const HR = "── " + rule(63);

  out.push("");
  out.push("── " + clr("bold", "Workpads Frame Inspect") + " " + rule(44));
  const job = (record.process && record.process.job) || "";
  out.push("   " + clr("signal", record.id.padEnd(18)) +
    clr("faint", "  compressed ") + clr("green", compressed.length + " B") +
    clr("faint", "  →  frame ") + clr("green", frameSize + " B"));
  if (job) out.push("   " + clr("faint", "job  ") + "  " + job);
  out.push(HR);

  const C_OFF = 4, C_NAME = 20, C_HEX = 12;
  out.push(
    "   " + clr("faint","OFF ".padEnd(C_OFF)) + "  " +
    clr("faint","BLOCK".padEnd(C_NAME)) + "  " +
    clr("faint","HEX".padEnd(C_HEX)) + "  " +
    clr("faint","BINARY")
  );
  out.push("   " + "─".repeat(C_OFF + 2 + C_NAME + 2 + C_HEX + 2 + 17));

  for (const item of items) {
    const offStr  = item.offset.toString(16).padStart(2,"0").toUpperCase();
    out.push(
      "   " + clr("warm",   offStr.padEnd(C_OFF))  + "  " +
               clr("bold",   item.name.padEnd(C_NAME)) + "  " +
               clr("signal", (item.hex||"").padEnd(C_HEX)) + "  " +
               clr("signal", item.bin||"")
    );
    if (Array.isArray(item.sub)) {
      for (let i = 0; i < item.sub.length; i++) {
        const [label, val, desc] = item.sub[i];
        const conn  = i === item.sub.length - 1 ? "└─" : "├─";
        const lStr  = String(label).padEnd(16);
        const vStr  = (val !== 0 && val !== "" && val != null) ? clr("signal", String(val).padEnd(4)) : "    ";
        out.push("        " + clr("faint", conn + " " + lStr) + vStr + "  " + clr("faint", desc||""));
      }
    }
    out.push("");
  }

  out.push(HR);
  out.push("   " + clr("faint","alg  ") + "  " + clr("green","pads-v1+deflate+b64url") +
    "   " + clr("faint","frame") + "  " + clr("signal", frameSize + " B") +
    "   " + clr("faint","compressed") + "  " + clr("signal", compressed.length + " B"));
  out.push("── " + rule(63));
  out.push("");
  return out.join("\n");
}

// ── #l/ List share ────────────────────────────────────────────────────────────
// Spec: security-wrapper.md §2 — standalone option list for form builder
function commandListShare(args) {
  if (!args.items) throw new Error("Missing --items");
  const items = String(args.items).split(",").map(s => s.trim()).filter(Boolean);
  if (!items.length) throw new Error("--items must contain at least one item");
  const payload = items.join("\n");
  const deflated = zlib.deflateRawSync(Buffer.from(payload, "utf8"));
  const url   = "workpads.me/p#l/" + toB64Url(deflated);
  const bytes = Buffer.byteLength(url, "utf8");
  const label = args.label ? String(args.label) : "";
  printResult("list:share", "OK", [
    ["items", String(items.length)],
    ...(label ? [["label", label]] : []),
    ["url",   url],
    ["bytes", String(bytes)],
    ["alg",   "deflate+b64url"],
    ["tag",   "#l/ (option list)"],
    ["list",  items.join(" | ")],
  ]);
}

// ── Agreement commands ────────────────────────────────────────────────────────
const AGREEMENT_TYPES = [
  "service-contract","nda","payment-plan","scope-of-work","employment","rental","custom",
];

function commandAgreementCreate(args) {
  if (!args.title && !args.set) throw new Error("Missing --title (or --set process.job=...)");
  const records = loadRecords();
  const { id, seq } = newRecordId(records);
  const aType      = args.type || "service-contract";
  const terms      = args.terms || "";
  const expiryDays = args.expiry ? parseInt(args.expiry) : 30;
  const expiryDate = new Date(Date.now() + expiryDays * 86400000).toISOString().slice(0, 10);

  const record = {
    id, seq,
    templateId: "agreement",
    variant: "agreement",
    process: {
      job:      args.title || "Agreement",
      customer: args.party || "",
      date:     new Date().toISOString().slice(0, 10),
    },
    story: terms,
    actions: [],
    details: args.description || "",
    flags3: {
      context_label: aType,
      uid:           id,
      ...(expiryDate ? { date_end: expiryDate } : {}),
    },
    agreement: {
      type:       aType,
      terms,
      state:      "proposed",
      parties:    [],
      expiryDate,
      commitType: 0,
    },
    comments: [],
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
  };

  applySetPairs(record, parseKeyValuePairs(args.set));

  if (args.party) {
    record.agreement.parties.push({ name: args.party, role: "customer", accepted: false });
  }
  const workerName = args.worker || args["my-name"];
  if (workerName) {
    record.agreement.parties.push({ name: workerName, role: "worker", accepted: true,
                                    acceptedAt: new Date().toISOString() });
  }

  if (args["ack-required"]) record.ackRequest = true;
  if (args.ctrig) {
    const { trigBytes } = compileCTrig(args.ctrig);
    record.cTrigBytes = trigBytes;
    record.agreement.ctrig = args.ctrig;
  }

  records.push(record);
  saveRecords(records);

  printResult("agreement:create", "OK", [
    ["id",      id],
    ["type",    aType],
    ["title",   record.process.job],
    ["state",   "proposed"],
    ["expiry",  expiryDate],
    ...(terms     ? [["terms",   terms.slice(0, 60) + (terms.length > 60 ? "…" : "")]] : []),
    ...(record.agreement.parties.length
        ? [["parties", record.agreement.parties.map(p => p.name + "(" + p.role + ")").join(", ")]]
        : []),
    ...(args.ctrig ? [["ctrig",  args.ctrig]] : []),
  ]);
}

function commandAgreementAccept(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record  = records.find(r => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  if (!record.agreement) throw new Error("Record is not an agreement");
  const name = args.name || "Unknown";
  const role = args.role || "customer";
  record.agreement.parties = record.agreement.parties || [];
  const existing = record.agreement.parties.find(p => p.name === name);
  if (existing) {
    existing.accepted = true;
    existing.acceptedAt = new Date().toISOString();
  } else {
    record.agreement.parties.push({ name, role, accepted: true, acceptedAt: new Date().toISOString() });
  }
  const allAccepted = record.agreement.parties.every(p => p.accepted);
  if (allAccepted && record.agreement.parties.length >= 2) {
    record.agreement.state = "active";
  } else if (record.agreement.state === "proposed") {
    record.agreement.state = "reviewed";
  }
  record.updatedAt = new Date().toISOString();
  saveRecords(records);
  printResult("agreement:accept", "OK", [
    ["id",    record.id],
    ["party", name],
    ["state", record.agreement.state],
    ["accepted-by", record.agreement.parties.filter(p => p.accepted).map(p => p.name).join(", ")],
  ]);
}

function commandAgreementStatus(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record  = records.find(r => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  if (!record.agreement) throw new Error("Record is not an agreement");
  const a = record.agreement;
  const HR = "── " + rule(63);
  const stateColor = { active:"green", completed:"green", disputed:"red" }[a.state] || "warm";
  const out = [""];
  out.push("── " + clr("bold", "Agreement") + " " + rule(54));
  out.push("   " + clr("signal", record.id) + "  " + clr("faint", a.type || ""));
  out.push("   " + clr("faint", "state  ") + "  " + clr(stateColor, a.state || "proposed"));
  if (a.expiryDate) out.push("   " + clr("faint", "expiry ") + "  " + a.expiryDate);
  out.push(HR);
  out.push("   " + clr("bold", "PARTIES"));
  for (const p of (a.parties || [])) {
    const status = p.accepted ? clr("green", "accepted") : clr("gold", "pending");
    out.push("   " + String(p.name || "?").padEnd(22) + (p.role || "").padEnd(12) + status);
  }
  if (a.terms) {
    out.push(HR);
    out.push("   " + clr("bold", "TERMS"));
    out.push(wrapIndent(a.terms, "   ", 70));
  }
  if (a.ctrig) {
    out.push(HR);
    out.push("   " + clr("bold", "C-TRIG OBLIGATION"));
    out.push("   " + clr("faint", a.ctrig));
  }
  out.push(HR); out.push("");
  console.log(out.join("\n"));
}

function commandAgreementComplete(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record  = records.find(r => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  if (!record.agreement) throw new Error("Record is not an agreement");
  record.agreement.state = "completed";
  record.agreement.completedAt = new Date().toISOString();
  record.updatedAt = new Date().toISOString();
  saveRecords(records);
  printResult("agreement:complete", "OK", [
    ["id",           record.id],
    ["state",        "completed"],
    ["completed-at", record.agreement.completedAt],
  ]);
}

function commandAgreementDispute(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record  = records.find(r => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  if (!record.agreement) throw new Error("Record is not an agreement");
  record.agreement.state = "disputed";
  record.agreement.disputeReason = args.reason || "";
  record.agreement.disputedAt    = new Date().toISOString();
  record.updatedAt = new Date().toISOString();
  saveRecords(records);
  printResult("agreement:dispute", "OK", [
    ["id",     record.id],
    ["state",  "disputed"],
    ["reason", args.reason || "(none given)"],
  ]);
}

function commandCTrigEval(args) {
  if (!args.ctrig) throw new Error("Missing --ctrig <program-or-preset>");

  // Start with record's real state if --record given, then overlay --ctx overrides
  let ctx = {};
  if (args.record) {
    const records = loadRecords();
    const record  = records.find(r => r.id === args.record);
    if (!record) throw new Error(`Record not found: ${args.record}`);
    ctx = buildCTrigContext(record);
  }
  if (args.ctx) {
    const pairs = Array.isArray(args.ctx) ? args.ctx : [args.ctx];
    for (const p of pairs) {
      const [k, v] = p.split("=");
      ctx[k.trim()] = v === undefined ? true : (v === "true" ? true : v === "false" ? false : v);
    }
  }

  const { trigBytes } = compileCTrig(args.ctrig);
  const { results, stack } = evaluateCTrig(trigBytes, ctx);

  const header  = trigBytes[0];
  const progLen = header & 0x1F;
  const mode    = (header >> 5) & 0x1;

  const trueConds = Object.entries(ctx).filter(([,v]) => v === true).map(([k]) => k);

  printResult("ctrig:eval", "OK", [
    ["program",   args.ctrig],
    ["header",    "0x" + header.toString(16).padStart(2,"0") + ` (MODE=${mode} PROG_LEN=${progLen})`],
    ["bytes",     trigBytes.map(b => b.toString(16).padStart(2,"0")).join(" ")],
    ["ctx-true",  trueConds.length ? trueConds.join(", ") : "(none)"],
    ...(args.record ? [["ctx-from", args.record]] : []),
    ["actions",   results.length ? results.map(r => JSON.stringify(r)).join(", ") : "(none triggered)"],
    ["stack",     stack.length ? "[" + stack.join(", ") + "]" : "(empty)"],
  ]);
}

function commandInspect(args) {
  if (!args.record) throw new Error("Missing --record");
  const records = loadRecords();
  const record = records.find((r) => r.id === args.record);
  if (!record) throw new Error(`Record not found: ${args.record}`);
  const trigOpts = args.trig ? compileTrig(args.trig) : null;
  console.log(fmtInspect(record, trigOpts));
}

function commandBrowserStatus() {
  const state = loadBrowserState();
  if (!state) {
    console.log("No browser state found.");
    return;
  }
  console.log(JSON.stringify(state, null, 2));
}

function commandBrowserStop() {
  const state = loadBrowserState();
  if (!state || !state.pid) {
    console.log("No running browser recorded.");
    return;
  }
  try {
    process.kill(Number(state.pid), "SIGTERM");
    clearBrowserState();
    console.log(`Stopped browser process ${state.pid}.`);
  } catch (err) {
    console.error(`Could not stop process ${state.pid}: ${err.message}`);
    console.error("Try manually:");
    console.error(`  lsof -nP -iTCP:${state.port || 8787} -sTCP:LISTEN`);
    console.error("  kill <PID>");
    process.exit(1);
  }
}

function main() {
  const args = parseArgs(process.argv.slice(2));
  const cmd = args._[0];
  if (!cmd || cmd === "help" || cmd === "--help") {
    printHelp();
    return;
  }

  if (cmd === "template:validate") return commandTemplateValidate(args);
  if (cmd === "template:compile") return commandTemplateCompile(args);
  if (cmd === "template:show") return commandTemplateShow(args);
  if (cmd === "create") return commandCreate(args);
  if (cmd === "edit") return commandEdit(args);
  if (cmd === "share") return commandShare(args);
  if (cmd === "import") return commandImport(args);
  if (cmd === "render")  return commandRender(args);
  if (cmd === "inspect") return commandInspect(args);
  if (cmd === "ctrig:eval") return commandCTrigEval(args);
  if (cmd === "list:share") return commandListShare(args);
  if (cmd === "agreement:create") return commandAgreementCreate(args);
  if (cmd === "agreement:accept") return commandAgreementAccept(args);
  if (cmd === "agreement:status") return commandAgreementStatus(args);
  if (cmd === "agreement:complete") return commandAgreementComplete(args);
  if (cmd === "agreement:dispute") return commandAgreementDispute(args);
  if (cmd === "export") return commandExport(args);
  if (cmd === "list") return commandList(args);
  if (cmd === "delete") return commandDelete(args);
  if (cmd === "storage:get" || cmd === "policy:get") return commandStorageGet(args);
  if (cmd === "storage:set" || cmd === "policy:set") return commandStorageSet(args);
  if (cmd === "storage:resolve" || cmd === "policy:resolve") return commandStorageResolve(args);
  if (cmd === "comment:add") return commandCommentAdd(args);
  if (cmd === "comment:list") return commandCommentList(args);
  if (cmd === "comment:delete") return commandCommentDelete(args);
  if (cmd === "dashboard") return commandDashboard(args);
  if (cmd === "howto") return commandHowTo(args);
  if (cmd === "browser") return commandBrowser(args);
  if (cmd === "browser:status") return commandBrowserStatus(args);
  if (cmd === "browser:stop") return commandBrowserStop(args);

  throw new Error(`Unknown command: ${cmd}`);
}

try {
  main();
} catch (err) {
  console.error(`Error: ${err.message}`);
  process.exit(1);
}