@augurworks/augur 0.15.1

package/scripts/fork.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * augur fork — take your own copy of a published artifact, at a new URL.
+ *
+ *   augur fork /toolkit/map/ /toolkit/map-mine/
+ *   augur fork /toolkit/map/ /toolkit/map-mine/ --space alpha
+ *
+ * `F-fork-verb`. Divergence-then-convergence needs fork as a deliberate verb rather than as
+ * conflict cleanup or as "copy the folder and republish it". The copy is made in the
+ * MANIFEST — the blobs already exist, so a hundred-file prototype forks without uploading,
+ * downloading or hashing a byte — and the store remembers where it came from.
+ *
+ * ⚠️ IT NEEDS NO TREE, and that is the point. Every other publishing command starts from a
+ * folder on disk; this one is two paths and a token, so a workspace that has never had a
+ * repo can still say "give me my own copy of this". Nothing is written to your working
+ * directory, and nothing is read from it.
+ *
+ * ⚠️ THE COPY IS YOURS. It is stamped with you as its owner rather than inheriting the
+ * original's, so forking to get an editable copy cannot hand the fork the same restriction
+ * it was forked to escape. Lineage rides along as `forkedFrom {path, version}` naming a
+ * manifest version the store still holds — versions are never pruned, so the parent stays
+ * reachable even after the source moves on.
+ */
+import { target, apiClient, buildStamp, idsFromStamp } from "./lib/store.mjs";
+
+const log = (m) => console.error(`\x1b[36m[fork]\x1b[0m ${m}`);
+const die = (m) => { log(m); process.exit(1); };
+
+const args = process.argv.slice(2);
+const opt = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : null; };
+const positional = args.filter((a, i) => !a.startsWith("--") && args[i - 1] !== "--space");
+const [FROM, TO] = positional;
+if (!FROM || !TO) die("usage: augur fork <from-path> <to-path> [--space <id>]");
+
+let origin, token;
+try { ({ origin, token } = target()); } catch (e) { die(e.message); }
+const req = apiClient(origin, token);
+
+// Which workspace. Named, or the one the instance serves — asked of the public build stamp
+// rather than of a folder, because a forking publisher may have no folder.
+let space = opt("--space");
+if (!space) {
+  const ids = idsFromStamp(await buildStamp(origin)).filter((id) => id !== "_engine");
+  if (ids.length !== 1) die(`name the workspace: --space <${ids.join("|") || "id"}>`);
+  space = ids[0];
+}
+
+let res;
+try {
+  res = await (await req(`${space}/fork`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ from: FROM, to: TO }),
+  })).json();
+} catch (e) {
+  // The store's refusals are specific on purpose, so pass its words through rather than
+  // flattening them into "fork failed".
+  die(e.message.replace(/^POST \S+ → /, ""));
+}
+
+log(`\x1b[32mforked\x1b[0m ${res.from} → ${res.to}  (v${res.version})`);
+console.log(`${origin}${res.to}`);
+console.log(`\x1b[2m${res.files} file(s) aliased, ${res.blobsUploaded} blob(s) uploaded — `
+  + `forked from ${res.forkedFrom.path} at v${res.forkedFrom.version}\x1b[0m`);

package/scripts/freeze.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * augur freeze — make a workspace read-only while it is being moved.
+ *
+ *   augur freeze [--reason "…"]     stop accepting writes
+ *   augur freeze --status           is it frozen, and since when
+ *   augur thaw                      accept writes again, and print how long it lasted
+ *
+ * `MIG-cutover-freeze`. Moving a workspace is export → verify → cut the hostname over, and
+ * anything written to the OLD instance inside that window goes to a copy nobody will ever
+ * read again. Not lost noisily — lost the way a comment is lost when somebody posts it,
+ * watches it appear, and comes back tomorrow to a page that never had it.
+ *
+ * ONLY WRITES STOP. The other way to do this is pulling the route or the DNS record, which
+ * is simpler and takes READS down too: on a real workspace the copy and the verification
+ * are minutes, and minutes of dark site looks like an outage to everybody who is not
+ * migrating. Here the site stays up, a reader sees what was there, and somebody who tries
+ * to change something is told rather than quietly ignored. Signing in still works, because
+ * whoever is watching the migration has to be able to get in and look.
+ *
+ * THE DURATION IS THE POINT OF `thaw` PRINTING IT. A migration has to publish how long its
+ * window actually was — an instance being moved for somebody else has people planning
+ * around that number, and "about ten minutes" from memory is not a number.
+ */
+import { target, apiClient } from "./lib/store.mjs";
+
+const log = (m) => console.error(`\x1b[36m[freeze]\x1b[0m ${m}`);
+const die = (m) => { log(m); process.exit(1); };
+
+const args = process.argv.slice(2);
+const flag = (f) => args.includes(f);
+const opt = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : null; };
+// `augur thaw` and `augur freeze --thaw` are the same thing; the CLI exposes both because
+// one of them is what somebody types under pressure.
+const THAW = flag("--thaw") || /thaw/.test(process.env.AUGUR_CMD || "") || args[0] === "thaw";
+const STATUS = flag("--status");
+
+let origin, token;
+try { ({ origin, token } = target()); } catch (e) { die(e.message); }
+const req = apiClient(origin, token);
+
+const fmt = (ms) => {
+  if (ms == null) return "unknown";
+  const s = Math.round(ms / 1000);
+  return s < 90 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+};
+
+if (STATUS) {
+  const { freeze } = await (await req("_state/freeze")).json();
+  if (!freeze) { console.log(`${origin}  accepting writes`); process.exit(0); }
+  console.log(`${origin}  FROZEN since ${freeze.at} — ${freeze.reason}`
+    + `  (${fmt(Date.now() - Date.parse(freeze.at))} so far)`);
+  process.exit(0);
+}
+
+const res = await (await req("_state/freeze", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify(THAW
+    ? { thaw: true }
+    : { reason: opt("--reason") || "being moved to a new home" }),
+})).json();
+
+if (!res.ok) die(`${origin} refused: ${res.reason}`);
+
+if (THAW) {
+  log(`\x1b[32mthawed\x1b[0m — writes are accepted again`);
+  console.log(`${origin}  frozen for ${fmt(res.durationMs)}`);
+  console.log("\x1b[2mpublish that number with the migration — somebody planned around it\x1b[0m");
+} else {
+  log(`\x1b[33mfrozen\x1b[0m since ${res.since} — ${res.reason}`);
+  console.log(`${origin}  reads unaffected; every write is refused with a 503 that says why`);
+  console.log("\x1b[2mrun `augur thaw` when the cutover is done — nothing lifts this on its own\x1b[0m");
+}

package/scripts/frontdoor-parity.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * frontdoor-parity — ask a RUNNING deployment whether a gated path is gated.
+ *
+ * WHY. Nothing in this engine or any shell checks that. The shells' health canary curls
+ * /_build.json, which is a static file: a bare host with no worker running at all answers
+ * it correctly and reports "healthy". Every test in the suite drives the worker in
+ * process, so none of them can observe how the platform in front of it routes.
+ *
+ * That gap is survivable on Pages, where the worker runs first for every request by
+ * construction. It stops being survivable the moment an instance moves to a plain Worker,
+ * because there the platform serves a matching static asset FIRST unless
+ * `run_worker_first = true` — and the asset directory holds __config/instance.json, which
+ * carries the roster including seed passwords.
+ *
+ * THE DISCRIMINATOR, and it is the whole idea: ask for a file that EXISTS in the asset
+ * directory and is not meant to be public, then check the response is not that file. On a
+ * healthy instance /tenant-context.mjs answers with the gate's HTML, because the worker
+ * ran and decided. On a broken one it answers with `export const …`, because the platform
+ * served the file before the worker was ever invoked. Status codes cannot tell those
+ * apart — both are 200.
+ *
+ * WHAT IT CANNOT DO. It is a black-box prober: it can only see what a stranger sees. It
+ * says which checks it could not discriminate rather than counting them as passes — a
+ * gated instance answers every unknown path with the login page at 200, so the
+ * not-found check has nothing to compare against there and says so.
+ *
+ * Usage:
+ *   node scripts/frontdoor-parity.mjs <origin>                 assert the matrix
+ *   node scripts/frontdoor-parity.mjs <origin-a> <origin-b>    assert both, then diff them
+ *
+ * Exit 1 on any failure. Exit 2 on a usage or network error, which is not a pass.
+ */
+import crypto from "node:crypto";
+
+/**
+ * Bodies are not byte-stable across two requests for the same page, and the reason is not
+ * in this repo: Cloudflare's Email Address Obfuscation rewrites any address it finds in
+ * HTML into `<a data-cfemail="…">`, with a FRESH random key each response. Comparing raw
+ * bytes therefore reported every HTML path as a difference — including two fetches of one
+ * origin — which would have made the parity check pure noise on its first real use.
+ *
+ * Normalise it out, and nothing else. A comparator that strips more than it must is a
+ * comparator that stops noticing the difference it exists to find.
+ */
+function normalise(body) {
+  return body
+    .replace(/data-cfemail="[0-9a-f]+"/gi, 'data-cfemail=""')
+    .replace(/\/cdn-cgi\/l\/email-protection#[0-9a-f]+/gi, "/cdn-cgi/l/email-protection#");
+}
+const sha = (s) => crypto.createHash("sha256").update(normalise(s)).digest("hex").slice(0, 12);
+const isHtml = (b) => /^\s*<!doctype html/i.test(b);
+const looksLikeLoginPage = (b) => isHtml(b) && /type=["']password["']/i.test(b);
+
+/**
+ * SEALED: the path exists as a file in dist/ and must never come back as that file.
+ * `leaks` returns a reason when the body IS the file, i.e. when the worker did not run.
+ */
+const SEALED = [
+  ["/__config/instance.json", (b) => /"users"\s*:/.test(b) && "the instance roster (this file carries seed passwords)"],
+  ["/__config/routing.json", (b) => /"publicPrefixes"\s*:/.test(b) && "the routing document"],
+  ["/__manifests/_engine.json", (b) => /"files"\s*:/.test(b) && "an engine manifest"],
+  ["/_worker.js", (b) => /export\s+default|addEventListener\s*\(/.test(b) && "the worker source"],
+  ["/tenant-context.mjs", (b) => /export\s+(const|function)/.test(b) && "the tenant-context module"],
+  ["/tenant-cache.mjs", (b) => /export\s+(const|function)/.test(b) && "the tenant-cache module"],
+  ["/kv-codec.mjs", (b) => /export\s+(const|function)/.test(b) && "the KV codec module"],
+  ["/mail.mjs", (b) => /export\s+(const|function)/.test(b) && "the mail transport"],
+  ["/chrome/appchrome.mjs", (b) => /export\s+(const|function)/.test(b) && "the chrome renderer"],
+  ["/.assetsignore", (b) => /^_worker\.js/m.test(b) && "the deploy ignore list"],
+];
+
+/**
+ * ALIVE: must be the real thing. Without these the matrix would pass on a deployment that
+ * answered everything with a 404 — sealed, and also completely broken.
+ */
+const ALIVE = [
+  ["/_build.json", (b) => { try { return !!JSON.parse(b).engine.sha; } catch { return false; } }, "a build stamp naming an engine sha"],
+  ["/sw.js", (b) => /service worker/i.test(b) || /addEventListener/.test(b), "the service worker script"],
+  ["/", (b) => isHtml(b), "an HTML page"],
+];
+
+const BOGUS = "/__frontdoor-parity-probe-no-such-path";
+
+async function get(origin, path, method = "GET") {
+  const url = origin.replace(/\/$/, "") + path;
+  const res = await fetch(url, { method, redirect: "manual", headers: { "user-agent": "augur-frontdoor-parity" } });
+  const body = method === "HEAD" ? "" : await res.text();
+  return { status: res.status, ct: (res.headers.get("content-type") || "").split(";")[0].trim(), body, url };
+}
+
+async function probe(origin) {
+  const results = [];
+  const fail = (name, detail) => results.push({ ok: false, name, detail });
+  const pass = (name, detail) => results.push({ ok: true, name, detail });
+  const skip = (name, detail) => results.push({ skip: true, name, detail });
+
+  for (const [path, leaks] of SEALED) {
+    const r = await get(origin, path);
+    const why = leaks(r.body);
+    if (why) fail(`sealed ${path}`, `answered with ${why} (${r.status} ${r.ct}, ${r.body.length}B). The worker did not decide this request.`);
+    else pass(`sealed ${path}`, `${r.status} ${r.ct || "-"} — not the file`);
+  }
+
+  for (const [path, ok, expected] of ALIVE) {
+    const r = await get(origin, path);
+    if (r.status !== 200 || !ok(r.body)) fail(`alive ${path}`, `expected ${expected}, got ${r.status} ${r.ct} (${r.body.length}B)`);
+    else pass(`alive ${path}`, `${r.status} ${r.ct || "-"}`);
+  }
+
+  // not_found_handling. A gated instance answers every unknown path with the login page,
+  // and its root is that same page, so there is nothing here to discriminate — say so
+  // rather than counting it.
+  const root = await get(origin, "/");
+  const bogus = await get(origin, BOGUS);
+  if (looksLikeLoginPage(root.body)) {
+    skip("not-found", "this instance gates its root, so an unknown path and the root are the same page by design");
+  } else if (bogus.status === 200 && sha(bogus.body) === sha(root.body)) {
+    fail("not-found", `an unknown path returned the ROOT PAGE at 200. That is not_found_handling = "single-page-application"; every typo and every unpublished URL now looks real.`);
+  } else {
+    pass("not-found", `${bogus.status} and not the root page`);
+  }
+
+  // A HEAD must agree with the GET about whether the thing exists.
+  const headBuild = await get(origin, "/_build.json", "HEAD");
+  if (headBuild.status !== 200) fail("HEAD /_build.json", `${headBuild.status}, but GET answers 200`);
+  else pass("HEAD /_build.json", "200");
+
+  return results;
+}
+
+async function main() {
+  const origins = process.argv.slice(2).filter((a) => !a.startsWith("-"));
+  if (!origins.length) {
+    console.error("usage: node scripts/frontdoor-parity.mjs <origin> [origin-b]");
+    process.exit(2);
+  }
+
+  let failures = 0;
+  const bodies = [];
+  for (const origin of origins) {
+    console.log(`\n${origin}`);
+    let results;
+    try { results = await probe(origin); }
+    catch (e) { console.log(`  ERROR  ${e.message}`); process.exit(2); }
+    for (const r of results) {
+      if (r.skip) console.log(`  skip   ${r.name}  —  ${r.detail}`);
+      else if (r.ok) console.log(`  ok     ${r.name}  —  ${r.detail}`);
+      else { console.log(`  FAIL   ${r.name}`); console.log(`         ${r.detail}`); failures++; }
+    }
+    bodies.push({ origin, results });
+  }
+
+  // Parity. Two front doors onto ONE instance must answer identically; that is what makes
+  // a cutover checkable rather than hoped-for.
+  if (origins.length === 2) {
+    console.log(`\nparity  ${origins[0]}  vs  ${origins[1]}`);
+    const paths = ["/_build.json", "/sw.js", "/", ...SEALED.map(([p]) => p)];
+    for (const p of paths) {
+      const [a, b] = await Promise.all(origins.map((o) => get(o, p)));
+      // /_build.json carries a timestamp, so compare the engine sha rather than the bytes.
+      if (p === "/_build.json") {
+        const s = (x) => { try { return JSON.parse(x.body).engine.sha; } catch { return null; } };
+        if (s(a) !== s(b)) { console.log(`  FAIL   ${p}  engine sha differs: ${s(a)} vs ${s(b)}`); failures++; }
+        else console.log(`  ok     ${p}  same engine sha`);
+        continue;
+      }
+      if (a.status !== b.status || sha(a.body) !== sha(b.body)) {
+        console.log(`  FAIL   ${p}  ${a.status}/${sha(a.body)}  vs  ${b.status}/${sha(b.body)}`);
+        failures++;
+      } else console.log(`  ok     ${p}  ${a.status} identical`);
+    }
+  }
+
+  console.log(failures
+    ? `\nfrontdoor-parity: ${failures} FAILURE(S). A 'sealed' failure means the platform answered before the worker ran.`
+    : `\nfrontdoor-parity: OK — every sealed path was decided by the worker, and the site is actually serving`);
+  process.exit(failures ? 1 : 0);
+}
+
+main();

package/scripts/hook.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// augur hook <pre|post|install|remove|status>
+//
+// `pre` and `post` are what an agent tool runs around every file edit, with the tool's own
+// JSON on stdin (docs/drafts-that-land.md §7). Both answer with an exit code: 0 lets the
+// edit through, 2 refuses it and puts one sentence on stderr for the agent to read in its
+// next tool result. NOTHING ELSE EXITS NON-ZERO: an unreadable payload, a missing
+// registry, an exception — every accident exits 0 and says nothing, because the hook is
+// installed machine-wide and a bug here would take every editor down with it.
+//
+//   pre    refuse a write into a read-only copy, or into a shared checkout's prototype
+//   post   save the draft the edited file belongs to; refused saves fail with the reason
+//
+// `install|remove|status` manage the adapters — `augur open` installs them once.
+import fs from "node:fs";
+import { ADAPTERS, denyDecision, saveDecision, installAdapters, removeAdapters } from "./lib/adapters.mjs";
+import { registryList, readState, unitClient, doSave } from "./lib/draft.mjs";
+import { resolveToken } from "./lib/store.mjs";
+
+const event = process.argv[2];
+const refuse = (m) => { process.stderr.write(m + "\n"); process.exit(2); };
+
+if (event === "install" || event === "remove" || event === "status") {
+  const rows = event === "install" ? installAdapters() : event === "remove" ? removeAdapters() : installAdapters({ dryRun: true });
+  for (const r of rows) {
+    const verdict = event === "status" ? (r.result === "unchanged" ? "installed" : r.result === "absent" ? "absent" : "not installed") : r.result;
+    console.log(`${r.name}: ${verdict}${r.path ? ` (${r.path})` : ""}`);
+  }
+  process.exit(0);
+}
+if (event !== "pre" && event !== "post") {
+  console.error("usage: augur hook <pre|post|install|remove|status>");
+  process.exit(1);
+}
+if (process.env.AUGUR_HOOKS_OFF) process.exit(0);
+
+let payload = null;
+try { payload = JSON.parse(fs.readFileSync(0, "utf8")); } catch (e) { process.exit(0); }
+const adapter = ADAPTERS.find((a) => a.id === (process.env.AUGUR_ADAPTER || ADAPTERS[0].id)) || ADAPTERS[0];
+let p;
+try { p = adapter.payload(payload); } catch (e) { process.exit(0); }
+let registry = [];
+try { registry = registryList(); } catch (e) { registry = []; }
+
+if (event === "pre") {
+  let d;
+  try { d = denyDecision({ filePath: p.filePath, cwd: p.cwd, registry }); } catch (e) { process.exit(0); }
+  if (d && d.deny) refuse(d.reason);
+  process.exit(0);
+}
+
+// post
+let target;
+try { target = saveDecision({ filePath: p.filePath, cwd: p.cwd, registry }); } catch (e) { process.exit(0); }
+if (!target) process.exit(0);
+const st = readState(target.dir);
+if (!st) process.exit(0);
+const origin = st.origin;
+// `AUGUR_TOKEN` set — even to nothing — is the answer; otherwise the saved tokens.
+const token = process.env.AUGUR_TOKEN !== undefined ? process.env.AUGUR_TOKEN : resolveToken(origin);
+if (!token) refuse(`draft ${st.draftId} not saved: no publish token for ${origin} — run augur connect once, then save with augur save.`);
+const client = unitClient({ origin, token, space: st.space, session: st.session });
+const r = await doSave({ client, dir: target.dir });
+if (r.ok) process.exit(0);
+if (r.error === "stale-draft" || r.error === "stale-draft-revision") refuse(`draft ${st.draftId} not saved: it moved under you (another process saved to it) — run augur sync, then augur save.`);
+if (r.error === "network") refuse(`draft ${st.draftId} not saved: ${origin} is unreachable (${r.message}). Nothing is lost — the next save carries every change since.`);
+refuse(`draft ${st.draftId} not saved: ${r.error || r.status}${r.reason ? ` (${r.reason})` : ""}. Fix it and run augur save.`);

package/scripts/identity-rekey.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * augur identity-rekey — move a live workspace's IDENTITY documents onto the workspace
+ * segment, without an account credential.
+ *
+ *   augur identity-rekey                        what WOULD move (a dry run; the default)
+ *   augur identity-rekey --confirm <workspace>  move it
+ *   augur identity-rekey --confirm <ws> --families roster,publishTokens
+ *
+ * `B-identity-kv-write-segmentation`. The roster, the roles, the display names, the
+ * avatars, the icons, the invites, the last-seen stamps and the publish tokens now carry
+ * the workspace on a deployment that resolves one from the Host (`identityKey` in
+ * src/_worker.js). A deployment that starts WRITING `t/<workspace>/users:roster` does not
+ * thereby start reading what it wrote yesterday, and there is deliberately no read-through
+ * to the unsegmented key: it belongs to whichever workspace this deployment served before
+ * the segment existed, and nothing in the key says which. So a live workspace is MOVED,
+ * and this is the command that moves it.
+ *
+ * ⚠️ THE TWIN OF `augur bundle-rekey`, AND A SEPARATE COMMAND ON PURPOSE. That one asks
+ * "is my published content where I read it"; this one asks "is my roster". An operator
+ * moving content must not silently move the login gate's documents in the same breath,
+ * and the two have different things to check afterwards.
+ *
+ * ⚠️ IT IS A COPY AND NEVER A CUT, and here that matters more than it does for content:
+ * the unsegmented documents are what a per-family revert READS. Flip one word in
+ * `IDENTITY_TENANCY` back with the sources deleted and the revert is a rollback to the day
+ * of the cut, with everybody minted since gone.
+ *
+ * ⛔ `users:secrets` DOES NOT MOVE, because it is not segmented. A credential is
+ * account-level — one address, one password, several workspaces — and it belongs to
+ * `B-cross-workspace-signin`.
+ *
+ * ⚠️ IT IS CORRECT FOR EXACTLY ONE WORKSPACE PER DEPLOYMENT, and the worker refuses rather
+ * than trusting this script about it: a deployment already holding a second workspace
+ * answers `not-the-only-workspace`.
+ *
+ * RUN IT BEHIND A FREEZE (`augur freeze`). The `_state/*` routes are exempt from the
+ * freeze, so the move runs with no identity write racing it; reads and sign-in are
+ * unaffected, so the site stays up.
+ *
+ * ⚠️ AFTERWARDS, GIVE KV A MINUTE BEFORE BELIEVING A READ. A `kv.get` through the worker
+ * is cached for up to sixty seconds, so a key written by this command can answer as
+ * missing for that long — which reads exactly like a broken move. Re-check past the minute
+ * before concluding anything, or read the namespace directly.
+ *
+ * Exit 0 when the move is complete (or was already), 1 on a refusal.
+ */
+import { target, apiClient } from "./lib/store.mjs";
+
+const log = (m) => console.error(`\x1b[36m[identity-rekey]\x1b[0m ${m}`);
+const die = (m) => { log(m); process.exit(1); };
+
+const args = process.argv.slice(2);
+const opt = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : null; };
+const CONFIRM = opt("--confirm");
+const FAMILIES = (opt("--families") || "").split(",").map((s) => s.trim()).filter(Boolean);
+const MAX_PAGES = Number(opt("--max-pages")) > 0 ? Number(opt("--max-pages")) : 200;
+
+let origin, token;
+try { ({ origin, token } = target()); } catch (e) { die(e.message); }
+const req = apiClient(origin, token);
+
+const call = async (body) => {
+  const res = await req("_state/identity-rekey", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  let out;
+  try { out = await res.json(); } catch (e) { die(`${origin} answered ${res.status} with something that is not JSON`); }
+  if (!out.ok) {
+    if (out.reason === "not-the-only-workspace") {
+      die(`${origin} refused: this deployment already holds another workspace (${(out.others || []).join(", ")}).`
+        + ` An unsegmented identity document there belongs to nobody in particular, so nothing may claim it.`);
+    }
+    if (out.reason === "confirm-mismatch") die(`${origin} refused: --confirm must be "${out.expected}"`);
+    if (out.reason === "unknown-family") die(`${origin} refused: no such family (${(out.unknown || []).join(", ")})`);
+    die(`${origin} refused: ${out.reason}`);
+  }
+  return out;
+};
+
+const base = { ...(FAMILIES.length ? { families: FAMILIES } : {}) };
+
+const plan = await call(base);
+if (plan.reason === "no-segment") {
+  log(`${origin} serves one workspace and writes no segment — there is nothing to move.`);
+  process.exit(0);
+}
+log(`${origin} — workspace ${plan.workspace} → ${plan.segment}`);
+log(`families ${plan.families.join(", ")}; ${plan.considered} document(s) considered, ${plan.skipped} already there`);
+
+if (!CONFIRM) {
+  const left = plan.copied + plan.pending;
+  if (!left) { log("\x1b[32mnothing to move\x1b[0m — this workspace is already on the segment"); process.exit(0); }
+  log(`\x1b[33mwould copy ${left} document(s)\x1b[0m`);
+  for (const k of plan.keys) console.log(`  ${k}`);
+  if (plan.keys.length < left) console.log(`  … and ${left - plan.keys.length} more`);
+  console.log("\x1b[2mre-run with --confirm <workspace> to move them; nothing is ever deleted\x1b[0m");
+  process.exit(0);
+}
+
+let copied = 0, bytes = 0, pages = 0;
+for (;;) {
+  const out = await call({ ...base, confirm: CONFIRM });
+  copied += out.copied; bytes += out.bytes; pages++;
+  if (out.copied) log(`page ${pages}: ${out.copied} copied (${(bytes / 1e3).toFixed(1)} kB so far)`);
+  if (out.done) break;
+  if (pages >= MAX_PAGES) die(`stopped after ${MAX_PAGES} pages with work left — re-run to continue`);
+}
+log(`\x1b[32mdone\x1b[0m — ${copied} document(s) copied, ${(bytes / 1e3).toFixed(1)} kB`);
+console.log("\x1b[2mthe originals are untouched: this is a copy, and it is what the per-family revert reads\x1b[0m");

package/scripts/init.mjs

@@ -0,0 +1,122 @@
+// init.mjs — `augur init`: scaffold a new space in the current directory.
+//
+//   augur init [--id <id>] [--name "<name>"] [--origin https://…]
+//              [--project <folder>] [--prototype <name>]
+//
+// Writes the two files that make a directory a space the engine can build:
+// a `space.json` satisfying agents/space-json.md, and one starter prototype at
+// `<project>/prototypes/<name>/index.html`. Nothing else — a space needs no CI,
+// no secrets and no submodule mount (see templates/README.md).
+//
+// That nesting is not decoration: the build only finds prototypes one level down,
+// inside a top-level project folder (`<opportunity>/prototypes/<name>/` in
+// agents/prototype-contract.md). A `prototypes/` directory at the space root
+// discovers as zero prototypes and the build still reports success, which is a
+// quiet way to lose an afternoon — so the scaffold puts it where it is seen.
+//
+// Defaults come from the directory you run it in, so the common case is a bare
+// `augur init`. It refuses to overwrite an existing space.json or prototype:
+// re-running after filling one in is a no-op you can trust.
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { NOTE as CANON_NOTE } from "./canon.mjs";
+
+const log = (msg) => console.error(`\x1b[32m[init]\x1b[0m ${msg}`);
+const die = (msg) => { console.error(`\x1b[31m[init]\x1b[0m ${msg}`); process.exit(1); };
+const opt = (f) => { const i = process.argv.indexOf(f); return i > 0 ? process.argv[i + 1] : null; };
+
+const CWD = process.cwd();
+
+// `id` is the URL prefix and the manifest key, so it is the one field the build
+// constrains: lowercase [a-z0-9-]. Derive a legal one from the folder name rather
+// than making the common case ask a question.
+const slug = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+const title = (s) => s.split(/[-_\s]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+
+const id = slug(opt("--id") || path.basename(CWD));
+if (!id) die(`could not derive a space id from "${path.basename(CWD)}" — pass --id <id> (lowercase letters, digits, hyphens).`);
+
+const name = opt("--name") || title(id);
+const origin = (opt("--origin") || process.env.AUGUR_ORIGIN || "").replace(/\/+$/, "");
+const proto = slug(opt("--prototype") || "hello");
+const project = slug(opt("--project") || "hello");
+
+const spaceJsonPath = path.join(CWD, "space.json");
+const rel = path.join(project, "prototypes", proto, "index.html");
+const protoDir = path.join(CWD, project, "prototypes", proto);
+const protoPath = path.join(protoDir, "index.html");
+
+if (existsSync(spaceJsonPath)) die(`${path.relative(CWD, spaceJsonPath) || "space.json"} already exists — this is already a space. Nothing written.`);
+if (existsSync(protoPath)) die(`${rel} already exists. Pass --prototype <name> for a different starter.`);
+
+// Only the fields a new space actually needs. Every other key in
+// agents/space-json.md is optional and better added when it is wanted than
+// scaffolded as noise — `default: true` because a fresh space is a one-space
+// site until something else mounts beside it.
+const space = { id, name, default: true };
+// siteOrigin is what lets `augur connect`/`augur login` and `augur publish` work from a bare
+// clone with no deploy shell around it, so write it when we know it.
+if (origin) space.siteOrigin = origin;
+
+writeFileSync(spaceJsonPath, JSON.stringify(space, null, 2) + "\n");
+
+// The starter has to open over file:// with no build step (agents/prototype-contract.md),
+// so: no imports, no absolute paths, no fonts off the network. The description meta is
+// what the gallery card, the OG preview and the canvas insert-picker all read.
+const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${name}</title>
+<meta name="description" content="Starter prototype for the ${name} space — replace this with one sentence saying what it shows.">
+<style>
+  :root { color-scheme: light dark; }
+  body {
+    margin: 0; min-height: 100vh; display: grid; place-items: center;
+    font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    background: #f4efe6; color: #2c2150;
+  }
+  main { max-width: 34rem; padding: 2rem; }
+  h1 { font-size: 2rem; margin: 0 0 .5rem; letter-spacing: -.02em; }
+  p { margin: 0 0 1rem; }
+  code { background: rgba(44, 33, 80, .08); padding: .15em .4em; border-radius: 4px; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #17141f; color: #ece7dd; }
+    code { background: rgba(236, 231, 221, .12); }
+  }
+</style>
+</head>
+<body>
+<main>
+  <h1>${name}</h1>
+  <p>This file is <code>${rel}</code>. Edit it — it is
+     self-contained static HTML with no build step, so it opens straight from disk
+     and ships exactly as written.</p>
+  <p>When it works, ship it: on a workspace that serves drafts,
+     <code>augur open ${project}/${proto}</code> then <code>augur land</code>; otherwise
+     <code>augur ship</code>. Either way you get the live URL.</p>
+</main>
+</body>
+</html>
+`;
+
+mkdirSync(protoDir, { recursive: true });
+writeFileSync(protoPath, html);
+
+// The naming scheme travels WITH the workspace, because the agent that needs it is the one
+// that arrives cold — often with no engine clone beside it to read agents/canon.md from.
+// Written at birth rather than at the first promotion: an affordance nobody can see is one
+// nobody uses, and a workspace that has been worked in for a month is exactly the one whose
+// names have already drifted. Never overwritten — same rule as space.json.
+const canonPath = path.join(CWD, "CANON.md");
+const wroteCanon = !existsSync(canonPath);
+if (wroteCanon) writeFileSync(canonPath, CANON_NOTE);
+
+log(`space "${id}" scaffolded:`);
+log(`  space.json`);
+log(`  ${rel}`);
+if (wroteCanon) log(`  CANON.md`);
+if (!origin) log(`no siteOrigin set — add one to space.json (or pass --origin) so connect/login/publish work from this clone.`);
+log(`next: edit the prototype, then \`augur land\` (a workspace that serves drafts) or \`augur ship\`.`);

package/scripts/land.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// augur land [-m "note"] — replace the prototype's main with this draft. The real URL moves;
+// its address is the last line of stdout. Refused when main moved since the draft opened:
+// then `augur sync`, check the draft address, and land again. See docs/drafts-that-land.md.
+import { resolveOrigin, resolveToken } from "./lib/store.mjs";
+import { readState, unitClient, doLand } from "./lib/draft.mjs";
+
+const log = (m) => console.error(`\x1b[35m[land]\x1b[0m ${m}`);
+const die = (m) => { console.error(`\x1b[31m[land]\x1b[0m ${m}`); process.exit(1); };
+const argv = process.argv.slice(2);
+const i = argv.indexOf("-m");
+const note = i > -1 ? argv[i + 1] || "" : "";
+const dir = process.cwd();
+const st = readState(dir);
+if (!st) die("not a draft folder — run `augur open <prototype>` first.");
+const origin = st.origin || resolveOrigin();
+const token = resolveToken(origin);
+if (!token) die("no publish token — run `augur connect` once.");
+const client = unitClient({ origin, token, space: st.space, session: st.session });
+const r = await doLand({ client, dir, note });
+if (!r.ok) {
+  if (r.error === "main-moved") {
+    log(`main moved since this draft opened (now revision ${r.mainRevision}):`);
+    for (const c of r.changed || []) log(`  changed  ${c.path}${c.by ? `  by ${c.by}` : ""}`);
+    for (const p of r.removed || []) log(`  removed  ${p}`);
+    die("run `augur sync` to fold those in, check the draft address, then `augur land` again.");
+  }
+  if (r.error === "landing-in-progress") die("somebody is landing this prototype right now — try again in a few seconds.");
+  die(`land refused: ${r.error || r.status}`);
+}
+// The bytes are live; when `recorded` is false only the history entry is missing. Said out
+// loud because the next call adopts that landing as the instance's own, and nobody would
+// otherwise know a landing of theirs is not in the record.
+if (r.recorded === false) {
+  log(`landed (publish v${r.version})`);
+  log("this landing is live, but its history entry is missing — the next call adopts it without an author.");
+} else {
+  log(`landed as revision ${r.revision} (publish v${r.version})`);
+}
+console.log(r.url);