@augurworks/augur 0.15.1

package/scripts/ui-copy-lint.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * ui-copy-lint — the empty states are a ghost and ONE short line, in a human voice.
+ *
+ * WHY THIS EXISTS. Nothing in this repo has ever constrained the text of an empty state:
+ * no test, no script, no build assertion. Every commit that ever touched `emptyState` is
+ * build.js-only, including 607c3db6, which fixed a first sentence that described a page
+ * that does not exist. That bug was found by a person opening the page in a browser, and
+ * the fix left behind no mechanism that would find the next one. Meanwhile the copy grew:
+ * eight surfaces, two paragraphs each, a mean sentence of 49.8 words, and two of them
+ * naming another company's product. The instruction that reset it was
+ * "novels full of claudisms (em dashes, expressions, terrible)".
+ *
+ * WHAT IT CAN AND CANNOT DO. It cannot tell whether a sentence is TRUE — the false first
+ * sentence would have passed every rule below — and it cannot tell whether writing is
+ * good. It catches the specific tics that produced the last one, and the structural rule
+ * that keeps a surface from growing back into a novel: one paragraph, twenty words.
+ * Truth is still a review question, and the Tokens renderer carries a comment saying so
+ * for the three readers who land on its empty branch.
+ *
+ * WHAT IT READS. Two closed sets. The `emptyState(...)` call sites and the `addHint:`
+ * strings in build.js, which are the copy a person meets on a blank workspace. And the
+ * copy-bearing fields of src/mail.mjs — `subject:`, `footer:`, `detail:`, `message:` and
+ * every string a function returns — which are the copy a person meets in their inbox and
+ * the copy an operator meets beside the invite link. The mail file was written after this
+ * guard and so was never in front of it. That is the failure to watch for: a copy surface
+ * this file does not name is a copy surface nothing checks.
+ *
+ * THE MAIL EXTRACTOR IS FIELD-SHAPED, NOT A PARSER, AND THAT IS THE SAFE CHOICE. mail.mjs
+ * holds a regex containing a quote character and comments full of apostrophes, so a
+ * hand-rolled string tokenizer desynchronises on it and starts reporting a developer's
+ * prose as a user's — a wrong scan is worse than a narrow one. Only the DASH rule is
+ * applied there: the semicolon rule would fire on the inline CSS in the HTML mail shell,
+ * which is markup, not writing.
+ *
+ * Run: node scripts/ui-copy-lint.mjs [ROOT]   (exit 1 on any finding)
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = process.argv[2] || path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const BUILD = path.join(ROOT, "build.js");
+
+const MAX_WORDS = 20;      // A house sentence runs ~11 words; 20 is the ceiling, not the target.
+const MAX_PARAS = 1;       // The ghost does the explaining. A second paragraph is the novel growing back.
+const MAX_HINT_WORDS = 34; // A populated tab's caption may say a little more; it is read beside content.
+
+/** Pull the template literals passed to each `emptyState(` call, with their line numbers. */
+function emptyStateCalls(src) {
+  const out = [];
+  const NEEDLE = "emptyState(";
+  for (let i = src.indexOf(NEEDLE); i !== -1; i = src.indexOf(NEEDLE, i + 1)) {
+    // Skip a mention inside a comment or a name like `renderEmptyState(`.
+    const prev = src[i - 1];
+    if (prev && /[A-Za-z0-9_$]/.test(prev)) continue;
+    let d = 1, j = i + NEEDLE.length;
+    const paras = [];
+    while (j < src.length && d > 0) {
+      const c = src[j];
+      if (c === "(") d++;
+      else if (c === ")") d--;
+      else if (c === "`" && d === 1) {
+        // Read to the closing backtick, honouring escapes and ${...} spans.
+        let k = j + 1, lit = "";
+        while (k < src.length) {
+          if (src[k] === "\\") { lit += src[k + 1]; k += 2; continue; }
+          if (src[k] === "`") break;
+          if (src[k] === "$" && src[k + 1] === "{") {
+            let dd = 1; k += 2;
+            while (k < src.length && dd > 0) { if (src[k] === "{") dd++; else if (src[k] === "}") dd--; k++; }
+            lit += "X"; // an interpolation stands in as one word
+            continue;
+          }
+          lit += src[k]; k++;
+        }
+        paras.push(lit);
+        j = k;
+      }
+      j++;
+    }
+    out.push({ line: src.slice(0, i).split("\n").length, paras });
+  }
+  return out;
+}
+
+/** `addHint: "..."` — the caption on a POPULATED tier. */
+function addHints(src) {
+  const out = [];
+  const re = /addHint:\s*"((?:[^"\\]|\\.)*)"/g;
+  for (const m of src.matchAll(re)) {
+    out.push({ line: src.slice(0, m.index).split("\n").length, text: m[1].replace(/\\"/g, '"') });
+  }
+  return out;
+}
+
+/** The copy-bearing fields of src/mail.mjs, with their line numbers. A `subject:`,
+ *  `footer:`, `detail:` or `message:` key followed by a literal, and every literal a
+ *  function returns. No comment in that file contains either shape, so nothing here needs
+ *  a parser and nothing here mistakes a developer's sentence for a user's. */
+const LIT = String.raw`("(?:[^"\\]|\\.)*"|\x60(?:[^\x60\\]|\\.)*\x60)`;
+const MAIL_FIELDS = [
+  new RegExp(String.raw`\b(?:subject|footer|detail|message):\s*` + LIT, "g"),
+  new RegExp(String.raw`\breturn\s+` + LIT + String.raw`\s*;`, "g"),
+];
+function mailCopy(src) {
+  const out = [], seen = new Set();
+  for (const re of MAIL_FIELDS) {
+    for (const m of src.matchAll(re)) {
+      const line = src.slice(0, m.index).split("\n").length;
+      const key = line + "|" + m[1];
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ line, text: m[1].slice(1, -1) });
+    }
+  }
+  return out.sort((a, b) => a.line - b.line);
+}
+
+const stripTags = (s) => s.replace(/<[^>]+>/g, " ").replace(/&[a-z]+;/gi, " ").replace(/\s+/g, " ").trim();
+const words = (s) => stripTags(s).split(/\s+/).filter(Boolean).length;
+
+// The tics, each one quoted from the copy this replaced.
+const TICS = [
+  [/[—–]/, "an em or en dash. Standing instruction, given three times: use a comma or a full stop."],
+  [/;/, "a semicolon. It is the pivot the generated voice leans on, and it is close to absent from the writing this copy is meant to sound like."],
+  [/\bthe honest way\b/i, '"the honest way" — an epistemic flourish, not information.'],
+  [/\bwhich is the point\b/i, '"which is the point" — a closing clause that re-states the opening.'],
+  [/\bworth having\b/i, '"worth having".'],
+  [/\breads? as\b/i, '"reads as" — the house way of describing an impression. Say what it IS.'],
+  [/\bnot\s+[a-z][\w' ]{0,28},\s*(?:but|it is|these are|they are)\b/i, 'the "not X, it is Y" antithesis. Define positively.'],
+  [/<em>/i, "an <em>. That styling exists to make a quoted agent prompt liftable, and pasteable prompts are out."],
+  [/agents\/[\w-]+\.md|registry\.json|space\.json|component-meta\.json|skill\.json/, "a filename. This copy is for a person instructing an agent, and an agent finds the contract by reading the repo."],
+  [/&ldquo;|&rdquo;|“|”/, "a quoted incantation. No pasteable agent prompts in the UI."],
+];
+
+const findings = [];
+const push = (line, what, detail, text, file = "build.js") => findings.push({ line, what, detail, text, file });
+
+const src = fs.readFileSync(BUILD, "utf8");
+
+for (const call of emptyStateCalls(src)) {
+  if (call.paras.length > MAX_PARAS) {
+    push(call.line, "too many paragraphs",
+      `${call.paras.length} paragraphs; an empty state is ${MAX_PARAS}. The ghost above it is the explanation.`,
+      stripTags(call.paras[0]).slice(0, 80));
+  }
+  for (const p of call.paras) {
+    const n = words(p);
+    if (n > MAX_WORDS) push(call.line, "too long", `${n} words; the ceiling is ${MAX_WORDS}.`, stripTags(p).slice(0, 120));
+    for (const [re, why] of TICS) if (re.test(p)) push(call.line, "claudism", why, stripTags(p).slice(0, 120));
+  }
+}
+
+for (const h of addHints(src)) {
+  const n = words(h.text);
+  if (n > MAX_HINT_WORDS) push(h.line, "hint too long", `${n} words; the ceiling is ${MAX_HINT_WORDS}.`, stripTags(h.text).slice(0, 120));
+  for (const [re, why] of TICS) {
+    if (re.source.includes("em>") || re.source.includes("ldquo")) continue; // a hint carries no prompt
+    if (re.test(h.text)) push(h.line, "claudism", why, stripTags(h.text).slice(0, 120));
+  }
+}
+
+// ── the second surface: the mail a person receives, and the notice an operator reads ──
+const MAIL = path.join(ROOT, "src", "mail.mjs");
+const DASH = TICS[0];
+let mailRead = 0;
+if (fs.existsSync(MAIL)) {
+  const msrc = fs.readFileSync(MAIL, "utf8");
+  const strings = mailCopy(msrc);
+  mailRead = strings.length;
+  // Same refusal as below, for the same reason: a scan that found nothing because it
+  // looked at nothing is the failure this file exists to prevent.
+  if (!mailRead) {
+    console.log("ui-copy-lint: FAILED — src/mail.mjs exists but no subject/footer/detail/return copy was found in it. The extractor is broken, not the copy.");
+    process.exit(1);
+  }
+  for (const s of strings) {
+    if (DASH[0].test(s.text)) push(s.line, "claudism", DASH[1], s.text.slice(0, 120), "src/mail.mjs");
+  }
+}
+
+// A guard that finds nothing because it LOOKED at nothing is the failure mode this whole
+// file exists to prevent, so say what was read and refuse to pass on an empty scan.
+const scanned = emptyStateCalls(src).length;
+if (!scanned) {
+  console.log("ui-copy-lint: FAILED — found no emptyState() call sites in build.js. The extractor is broken, not the copy.");
+  process.exit(1);
+}
+
+if (!findings.length) {
+  console.log(`ui-copy-lint: OK — ${scanned} empty state(s), ${addHints(src).length} tier hint(s) and ${mailRead} mail string(s) read, all within one paragraph and ${MAX_WORDS} words`);
+  process.exit(0);
+}
+for (const f of findings) {
+  console.log(`${f.file}:${f.line}  [${f.what}]`);
+  console.log(`    ${f.detail}`);
+  console.log(`    ${f.text}`);
+}
+console.log(`\n${findings.length} finding(s) across ${scanned} empty state(s).`);
+console.log("This guard cannot tell whether a sentence is TRUE — the false first sentence that shipped here would have passed every rule above. That is still a review question.");
+process.exit(1);

package/scripts/watch.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// augur watch — save this draft folder on every burst of changes, until Ctrl-C. For people
+// editing by hand in an editor that runs no hooks. See docs/drafts-that-land.md §7.
+import { resolveOrigin, resolveToken } from "./lib/store.mjs";
+import { readState, unitClient, doSave, watchFolder } from "./lib/draft.mjs";
+
+const log = (m) => console.error(`\x1b[35m[watch]\x1b[0m ${m}`);
+const die = (m) => { console.error(`\x1b[31m[watch]\x1b[0m ${m}`); process.exit(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 });
+let running = false, again = false;
+async function save() {
+  if (running) { again = true; return; }
+  running = true;
+  try {
+    const r = await doSave({ client, dir });
+    if (!r.ok) log(`save refused: ${r.error || r.status}${r.error === "stale-draft" ? " — run `augur sync`" : ""}`);
+    else if (r.changed.length) log(`${r.changed.length} file(s) live at ${origin}${st.address}`);
+  } finally {
+    running = false;
+    if (again) { again = false; save(); }
+  }
+}
+log(`watching ${dir} — live at ${origin}${st.address} (Ctrl-C to stop)`);
+const w = watchFolder(dir, save);
+process.on("SIGINT", () => { w.close(); process.exit(0); });
+await save();

package/scripts/wrangler-preflight.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * wrangler-preflight — refuse a worker config that would open the site.
+ *
+ * WHY THIS IS NOT A STYLE CHECK. Pages and Workers invert request precedence. Pages runs
+ * the worker first and lets it decide what is public. Workers serves a matching static
+ * asset first and only invokes the worker on a miss, unless `run_worker_first = true`.
+ *
+ * The asset directory is `dist`, and `dist/__config/instance.json` holds the instance's
+ * user roster INCLUDING SEED PASSWORDS — build.js writes `users: IDENTITY` unstripped and
+ * says so in its own comment beside the write. `dist/admin/` is the admin page. In assets
+ * mode `dist` is every built page.
+ *
+ * So a config missing one line serves the roster and the admin panel to strangers, while
+ * every test in this repo stays green, both existing deploy gates stay green, and the
+ * shell's health check still answers "healthy" — because /_build.json is a static file
+ * that a bare host serves correctly with no worker running at all. Nothing else in this
+ * repo can tell those two deploys apart. That is what this script is for.
+ *
+ * ⚠️ WHERE IT ACTUALLY RUNS, because this header used to claim otherwise: NOT in `check`.
+ * The config it judges lives in a SHELL repo, and this repo has none, so there is nothing
+ * here for a repo-wide gate to read. It runs at `templates/shell/deploy.yml`, gating each
+ * shell's plain-Worker deploy with the wrangler.toml that shell actually holds, and in
+ * `test/wrangler-preflight.test.mjs` against fixtures. The consequence worth knowing: a
+ * green `check` in the engine says nothing about whether any instance's config is honest.
+ *
+ * WHAT IT DOES NOT DO: it does not parse TOML. Node has no TOML parser and this repo
+ * carries no dependencies for tooling (scripts/shell-lint.mjs works the same way). It is
+ * line-oriented, which means it can be fooled by a config written to fool it — an inline
+ * table, a multi-line array, a key inside a string. It is a floor under an honest config,
+ * not a proof against a hostile one. `scripts/frontdoor-parity.mjs` is what actually
+ * asks a running deployment whether a gated path is gated.
+ *
+ * Run: node scripts/wrangler-preflight.mjs -c <path/to/wrangler.toml>   (exit 1 on any finding)
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const argv = process.argv.slice(2);
+const cfgArg = argv[(argv.indexOf("-c") + 1) || (argv.indexOf("--config") + 1)] || argv[0];
+if (!cfgArg) {
+  console.error("usage: node scripts/wrangler-preflight.mjs -c <wrangler.toml>");
+  process.exit(2);
+}
+const CFG = path.resolve(cfgArg);
+if (!fs.existsSync(CFG)) {
+  console.error(`wrangler-preflight: no such config: ${CFG}`);
+  process.exit(2);
+}
+const SHELL = path.dirname(CFG);
+const raw = fs.readFileSync(CFG, "utf8");
+
+// Strip whole-line comments only. A `#` inside a quoted value is a legitimate character
+// (a password in a var, a fragment in a URL) and treating it as a comment is how a
+// 24-character secret became a 6-character one somewhere else in this project.
+const lines = raw.split(/\r?\n/).map((l) => (/^\s*#/.test(l) ? "" : l));
+const body = lines.join("\n");
+
+/**
+ * A value, with a TRAILING comment removed and a quoted `#` left alone.
+ *
+ * Both halves are load-bearing and they pull in opposite directions. The shipped
+ * template annotates almost every line (`binding = "ASSETS"   # the worker reads its own
+ * config through this`), so a reader that keeps the comment sees the binding as
+ * `"ASSETS" # the worker…` and refuses a correct config — and a guard that fires on the
+ * template it tells you to copy is a guard somebody deletes. But a `#` INSIDE a quoted
+ * value is a legitimate character, and treating it as a comment is how a 24-character
+ * secret became a 6-character one somewhere else in this project.
+ *
+ * So: a quoted value ends at its closing quote and whatever follows is a comment; an
+ * unquoted one ends at the first `#`.
+ */
+function stripTrailingComment(v) {
+  const q = /^\s*(["'])((?:\\.|(?!\1).)*)\1/.exec(v);
+  if (q) return q[2];
+  const hash = v.indexOf("#");
+  return (hash === -1 ? v : v.slice(0, hash)).trim();
+}
+
+/** A bare `key = value` at top level or inside the named table. */
+function valueOf(key, table = null) {
+  let cur = null;
+  for (const line of lines) {
+    const t = line.match(/^\s*\[\[?([^\]]+)\]\]?\s*$/);
+    if (t) { cur = t[1].trim(); continue; }
+    if (cur !== table) continue;
+    const m = line.match(new RegExp(String.raw`^\s*${key}\s*=\s*(.+?)\s*$`));
+    if (m) return stripTrailingComment(m[1]);
+  }
+  return null;
+}
+// `key` because the tables do not agree: KV, R2 and queues name theirs `binding`, and
+// Durable Objects name theirs `name`.
+const bindings = (table, key = "binding") => lines
+  .join("\n")
+  .split(/^\s*\[\[/m)
+  .filter((chunk) => chunk.startsWith(`${table}]]`))
+  .map((chunk) => (chunk.match(new RegExp(String.raw`^\s*${key}\s*=\s*["']([^"']+)["']`, "m")) || [])[1])
+  .filter(Boolean);
+
+const findings = [];
+const fail = (rule, detail) => findings.push({ rule, detail });
+
+// ── the headline rule ────────────────────────────────────────────────────────
+const assetsDir = valueOf("directory", "assets");
+const runWorkerFirst = valueOf("run_worker_first", "assets");
+if (assetsDir) {
+  const abs = path.resolve(SHELL, assetsDir);
+  const sensitive = ["__config/instance.json", "__config/routing.json", "admin/index.html"]
+    .filter((p) => fs.existsSync(path.join(abs, p)));
+  if (runWorkerFirst !== "true") {
+    fail("run-worker-first",
+      `[assets] run_worker_first is ${runWorkerFirst === null ? "not set" : runWorkerFirst}. Workers serves a matching asset BEFORE the worker runs, so the gate never executes.`
+      + (sensitive.length
+        ? `\n    The asset directory (${assetsDir}) currently contains: ${sensitive.join(", ")}.`
+        + "\n    __config/instance.json carries the user roster WITH SEED PASSWORDS. This config would publish it."
+        : `\n    The asset directory (${assetsDir}) is not built yet, so what it will contain could not be read — build first, or fix this anyway.`));
+  }
+  if (!fs.existsSync(path.join(abs, ".assetsignore")) && fs.existsSync(path.join(abs, "_worker.js"))) {
+    fail("assetsignore",
+      `${assetsDir}/_worker.js exists with no .assetsignore beside it. wrangler refuses to upload a Pages worker as an asset, and without the ignore file the deploy fails. build.js emits it; a stale dist does not have it.`);
+  }
+}
+if (!assetsDir) fail("assets", "no [assets] directory. The worker reads its own instance config through env.ASSETS and cannot start without it.");
+
+const nfh = valueOf("not_found_handling", "assets");
+if (nfh === "single-page-application") {
+  fail("not-found-handling",
+    'not_found_handling = "single-page-application" answers every unknown path with the index page at status 200. dist/404.html exists precisely so a miss is a miss; this turns every typo and every unpublished URL into a page that looks real.');
+}
+
+// ── bindings the worker cannot run without ───────────────────────────────────
+const kv = bindings("kv_namespaces");
+const r2 = bindings("r2_buckets");
+if (valueOf("binding", "assets") !== "ASSETS") fail("binding-assets", "[assets] binding must be \"ASSETS\" — src/_worker.js reads env.ASSETS by that name.");
+if (!kv.includes("COMMENTS")) fail("binding-comments", "no COMMENTS KV binding. Sessions, rosters, comments, pins and publish tokens all live there, and effectiveSecret fails CLOSED on a KV error, so nobody can sign in.");
+if (!r2.includes("BUNDLES")) fail("binding-bundles", "no BUNDLES R2 binding. Published content is served from the bundle store; without it the site has nothing in it.");
+
+// ── one workspace or many, and the pieces that have to agree ─────────────────
+// TENANT_HOST_SUFFIX is the switch: unset, the deployment serves the one workspace its
+// build named; set, the workspace comes from the Host header. The two halves are declared
+// in different tables, so it is easy to add one and not the other — and each half alone
+// fails in a way nobody would connect to this file.
+const suffix = valueOf("TENANT_HOST_SUFFIX", "vars");
+const dos = bindings("durable_objects.bindings", "name");
+if (suffix !== null && suffix.trim() !== "" && !dos.includes("TENANTS")) {
+  fail("tenants-binding",
+    `TENANT_HOST_SUFFIX = "${suffix}" makes the workspace come from the Host header, but there is no TENANTS Durable Object binding for those workspaces to live in. Every hostname would resolve to a workspace with nowhere to keep anything.`);
+}
+// A deployment that provisions workspaces furnishes each one from the seed pack in its own
+// asset bundle (`F-seed-pack-at-provision`). A worker deployed without one refuses every
+// provisioning (`seed-pack-unavailable`) — loud, but a signup door that refuses everybody
+// is still a broken signup door, and the build that forgot the pack is the one to stop.
+// build.js emits it on every engine-only build; a hand-rolled or stale dist does not have it.
+if (suffix !== null && suffix.trim() !== "" && dos.includes("TENANTS") && assetsDir) {
+  const abs = path.resolve(SHELL, assetsDir);
+  if (fs.existsSync(path.join(abs, "__config")) && !fs.existsSync(path.join(abs, "__seed", "pack.json"))) {
+    fail("seed-pack",
+      `${assetsDir} is built but carries no __seed/pack.json. This deployment provisions workspaces (TENANT_HOST_SUFFIX + TENANTS), and every provisioning furnishes the new workspace from that pack — without it the workspace object refuses every create with seed-pack-unavailable. Build with GV_ENGINE_ONLY=1 (which emits it), or GV_SEED_PACK=1.`);
+  }
+}
+if (suffix !== null && suffix.trim() === "") {
+  fail("tenants-suffix-empty",
+    'TENANT_HOST_SUFFIX is set to an empty string. That reads as "multi-workspace" to a person and as "single workspace" to the resolver. Delete the line, or give it the real suffix.');
+}
+
+// ── the jurisdiction a workspace object is addressed in ──────────────────────
+// A Durable Object's jurisdiction is chosen when the object is ADDRESSED, not when the
+// namespace is declared, so there is nothing in this file for the platform to check and
+// nothing in the platform for this file to read: `ns.idFromName(x)` and
+// `ns.jurisdiction("eu").idFromName(x)` are two different objects and a deployment picks
+// which by setting this variable or not. Storage belongs to an id, so the wrong choice is
+// not a bug that gets fixed later — it is a migration, and one nobody can do for a
+// workspace they cannot find.
+//
+// THIS LIST IS THE ENGINE'S COPY OF SOMEBODY ELSE'S, and it exists HERE and not in the
+// request path on purpose. In the worker the value is handed straight to the platform,
+// which is the only authority on what it accepts — a copy running on every request would
+// eventually refuse a jurisdiction that was added after it was written. A copy in a deploy
+// gate has the opposite failure: whoever hits a stale entry is a person, holding the repo,
+// one line from adding it, and in exchange a typo is caught before a single request rather
+// than by an outage. Measured against the platform: it accepts these four and refuses
+// everything else, case-sensitively, including the empty string.
+const JURISDICTIONS = ["eu", "fedramp", "fedramp-high", "us"];
+const jurisdiction = valueOf("TENANT_JURISDICTION", "vars");
+if (jurisdiction !== null && jurisdiction.trim() === "") {
+  fail("tenants-jurisdiction-empty",
+    'TENANT_JURISDICTION is set to an empty string, which the engine reads as "no jurisdiction" and a person reads as "restricted". Delete the line if this deployment places no restriction, or name the jurisdiction.');
+}
+if (jurisdiction !== null && jurisdiction.trim() !== "") {
+  const j = jurisdiction.trim();
+  if (!JURISDICTIONS.includes(j)) {
+    fail("tenants-jurisdiction-unknown",
+      `TENANT_JURISDICTION = "${j}" is not a jurisdiction the platform accepts (${JURISDICTIONS.join(", ")}) — and it is case-sensitive, so "EU" is not "eu". A value it refuses fails every request; a value it accepts but nothing else uses creates every workspace where nothing else is looking. If the platform has added one since this list was written, add it here.`);
+  }
+  if (!dos.includes("TENANTS")) {
+    fail("tenants-jurisdiction-binding",
+      `TENANT_JURISDICTION = "${j}" says where this deployment's workspace objects live, but there is no TENANTS Durable Object binding for them to live in. The variable does nothing here, which is the dangerous kind of nothing: adding the binding later would look like the jurisdiction had been in force all along.`);
+  }
+}
+
+// ── the entry ────────────────────────────────────────────────────────────────
+const main = valueOf("main");
+if (!main) fail("main", "no `main`. wrangler has no entry to bundle.");
+else if (!/src\/entry\.js$/.test(main)) {
+  fail("main", `main = "${main}". The deploy entry is src/entry.js — the file scripts/no-tenant-globals.mjs scans and the only one that may export a Durable Object class. Pointing main elsewhere silently un-scans the module graph.`);
+} else if (!fs.existsSync(path.resolve(SHELL, main))) {
+  fail("main", `main = "${main}" does not resolve from ${SHELL}. It is relative to this config, not to the engine.`);
+}
+
+// ── credentials that must never be a plaintext var ───────────────────────────
+let table = null;
+lines.forEach((line, i) => {
+  const t = line.match(/^\s*\[\[?([^\]]+)\]\]?\s*$/);
+  if (t) { table = t[1].trim(); return; }
+  const m = line.match(/^\s*([A-Z][A-Z0-9_]*)\s*=/);
+  if (!m) return;
+  const key = m[1];
+  if (key === "PUBLISH_BOOTSTRAP_TOKEN") {
+    fail("bootstrap-token", `line ${i + 1}: PUBLISH_BOOTSTRAP_TOKEN. It is compared as a bare string and answers with star scope — a plaintext credential that can overwrite every space's published content. It has no place on a live instance at all.`);
+  }
+  if (table === "vars" && /SECRET|TOKEN|PASSWORD|API_KEY/.test(key)) {
+    fail("secret-in-vars", `line ${i + 1}: ${key} under [vars]. [vars] is plaintext in a git repo. Use \`wrangler secret put ${key}\`.`);
+  }
+  if (key === "GV_KV_TOKEN") {
+    fail("kv-token", `line ${i + 1}: GV_KV_TOKEN short-circuits the env.COMMENTS binding and talks to the KV REST API with an account credential. It is a local-development escape hatch, not a deploy setting.`);
+  }
+});
+
+// `remote = true` sends a local dev binding to the PRODUCTION resource.
+lines.forEach((line, i) => {
+  if (/^\s*remote\s*=\s*true\s*$/.test(line)) {
+    fail("remote-binding", `line ${i + 1}: remote = true points this binding at the live resource. A local run then writes production comments, rosters and boards.`);
+  }
+});
+
+if (!findings.length) {
+  console.log(`wrangler-preflight: OK — ${path.basename(CFG)} runs the worker first, binds ASSETS + COMMENTS + BUNDLES, and carries no plaintext credential`);
+  process.exit(0);
+}
+for (const f of findings) {
+  console.log(`${path.relative(process.cwd(), CFG)}  [${f.rule}]`);
+  console.log(`    ${f.detail}`);
+}
+console.log(`\n${findings.length} finding(s). This is a floor under an honest config, not a proof: it is line-oriented and does not parse TOML. Ask a RUNNING deployment with scripts/frontdoor-parity.mjs.`);
+process.exit(1);

package/seed/CANON.md

@@ -0,0 +1,43 @@
+# The canon
+
+The screens and parts in this workspace that are meant to be **pulled by name** —
+"build it the way `invoice-detail` is built", "pull `invoice-list`,
+`invoice-detail` and `invoice-empty` and wire them together".
+
+A canonical name is a directory name, in one of four places at this root:
+
+| Where | What it holds |
+| --- | --- |
+| `base/<name>/` | one atom, every state on one page |
+| `components/<name>/` | one composed component |
+| `patterns/<name>/` | an arrangement several screens repeat |
+| `pages/<name>/` | a whole screen |
+
+Anything else is not the canon and is never what a bare name means: a folder under
+`<project>/prototypes/` is a working prototype, `playground/` is scratch.
+
+Names are lowercase and hyphenated, **subject first and qualifier last** —
+`invoice-list`, `invoice-detail`, `invoice-empty`, never `list-of-invoices` — so
+a directory listing sorts a subject's screens together and reads as a table of
+contents. The qualifier comes from one closed set:
+
+`-list` · `-detail` · `-new` · `-edit` · `-empty` · `-error` · `-loading` · `-confirm` · `-success`
+
+A name never carries a version, a date or a ticket id: it says what, never when.
+Every entry carries one sentence in `<meta name="description">` saying what it
+shows.
+
+**To pull `<name>`, look for `<name>/` in those four directories.** The entry
+page is `<tier>/<name>/index.html` and it opens on its own, from disk, with the
+workspace's design system already on it. That is the whole resolution rule, and
+it needs no tool.
+
+With the engine's CLI on hand, the same thing plus the description and the
+design-system assets each entry links:
+
+    augur canon find <name>      # → the tier, the folder, the entry, what it links
+    augur canon list             # → every canonical name and its description
+    augur canon save <path>      # → promote a working screen into the canon
+    augur canon check            # → names that will not be found the same way twice
+
+The full rules, with the reasoning, are the engine's `agents/canon.md`.

package/seed/README.md

@@ -0,0 +1,119 @@
+# The seed workspace
+
+What a brand-new hosted workspace contains on the day it is created. It is a
+complete, buildable space — a design system, six prototypes, a comment thread or
+two — copied wholesale into a tenant at provisioning, so the first thing a person
+sees is a working workspace rather than an empty one.
+
+The three prototypes under `start-here/` **are** the onboarding. There is no
+wizard to write instead: they teach the loop by being it, and the person who
+finishes them has a connected terminal, a design system they have already
+changed, and a comment they have already replied to.
+
+```
+seed/
+├── space.json                the workspace's contract with the build
+├── CANON.md                  how a canonical screen is named, for the agent that arrives cold
+├── registry.json             the design system's overlay catalog
+├── prototype-status.json     the dev-status chips
+├── threads.json              the comment threads that ship with the content
+├── skills/starter-ui/        the design system: tokens, components, one behaviour
+├── start-here/prototypes/
+│   ├── connect-your-terminal        the fork: one command, or fifteen minutes
+│   ├── set-up-your-design-system    the tokens, live, and how to make them yours
+│   └── sample-with-comments         a real screen with real pins on it
+└── worked-examples/prototypes/
+    ├── specimen-viewer              3D, from a pinned CDN script
+    ├── slide-deck                   a keyboard-driven deck
+    └── field-readings               charts with no chart library
+```
+
+## How it reaches a workspace
+
+It is built ONCE PER ENGINE PIN, not composed per signup. Every engine-only build
+(what a deploy shell runs) composes this tree with the real build — a child
+`build.js` over `seed/`, exactly what `augur publish` would run over a clone of it —
+and folds the result into one document, `dist/__seed/pack.json`, which ships inside
+the worker's own asset bundle and is sealed from the outside like `/__config/`
+(`scripts/lib/seed-pack-build.mjs`; `node scripts/build-seed-pack.mjs --print` shows
+what is in it).
+
+At provisioning, the workspace object writes that pack into its own segment of the
+bundle store FIRST — every blob, then `versions/1.json`, then `manifest.json`, as
+version 1 of the workspace's space — and only then commits the first admin, the
+threads and the version row in one transaction (`src/seed-pack.mjs`; the control
+plane asks for it with `seedPack: true` on `provision` and carries none of the
+content). Published content and the workspace's own rows live in two stores with no
+transaction between them, so the order is what makes it safe: a workspace the front
+door will serve is one whose commit landed, and an object left unprovisioned by a
+crash in between resolves to nobody, content or no content. There is no state where a
+workspace exists with an admin and no content.
+
+Every seed version is stamped as the platform's, never as a person's: `source` is
+the seed sentinel (`src/provenance.mjs`), `publishedBy` is the seed actor, each
+unit's `routing.unitSources` entry is the sentinel too, and no file carries an author
+id — the pack builder strips the git-derived stamp, so the engine's author is not the
+author of every workspace's welcome content.
+
+Three things are substituted on the way in:
+
+| What | Where | Substituted with |
+| --- | --- | --- |
+| The connect command | `CONNECT_COMMAND` in `start-here/prototypes/connect-your-terminal/index.html` | `npx augur connect --origin https://<label><suffix>`, the workspace's real address, filled the moment the page is published |
+| Comment timestamps | `at` in `threads.json` | the provisioning time, so day-one threads do not read as months old |
+| File timestamps | `editedAt` on every file in the manifest | the same provisioning time, all of them |
+
+The space id and name are the pack's own (`space.json` here): the workspace IS the
+space, and a workspace's label is its address, not its space id. The connect page
+falls back to deriving the command from the URL it is served on, so with no
+substitution it is never wrong, only less specific.
+
+**Start Here has to be the first card.** The gallery orders projects
+most-recently-worked-on first and falls back to A→Z, which is why the second
+folder is named `worked-examples` rather than `examples`: with one timestamp
+across the whole seed — what a single atomic write produces — Start Here leads
+and the examples follow. Provisioning stamps every file with the one provisioning
+instant, which is that single timestamp.
+
+## Rules for editing it
+
+- **Generic, always.** This ships from the engine to every workspace on every
+  instance. No instance, product, or personal names — CI scans this tree along
+  with the rest of the repo.
+- **The prototype contract holds** (`../agents/prototype-contract.md`):
+  self-contained static HTML, no build step, opens straight from disk, and a
+  one-line `<meta name="description">` that says what the page shows.
+- **Link the design system, do not copy it.** The canonical relative path
+  (`../../../skills/starter-ui/…`) resolves on disk and the build rewrites it for
+  the site, which is what keeps six prototypes wearing one system.
+- **A CDN script must be pinned to an exact version.** `specimen-viewer` is the
+  worked example: an immutable versioned URL, never a moving tag, and a visible
+  fallback when the network is not there.
+- **Copy is instruction, not decoration.** Every step says what you should see
+  when it worked, and every step that can fail carries its own way out.
+- **`CANON.md` is written by the tool, not by hand.** It is byte-for-byte the
+  `NOTE` string in `scripts/canon.mjs` — the same one `augur init` scaffolds and
+  `augur canon save` writes into a workspace that has none, so a hosted workspace
+  and a self-hosted one describe their names identically.
+  `test/canon-naming.test.mjs` fails when any of the three drift. Edit the string
+  and regenerate this copy; the rules it summarises live in `agents/canon.md`.
+- **The four canon tiers are ABSENT here, not empty.** There is no `base/`,
+  `components/`, `patterns/` or `pages/` in this tree, and adding one would be
+  wrong: a workspace's canon is what its own work promoted into it, so a seeded
+  canon would be six screens nobody chose claiming to be the ones worth copying.
+  `augur canon save` creates the tier directory on the first promotion. What the
+  seed ships instead is the SCHEME — `CANON.md` — so the canon a workspace grows
+  is named the same way as every other workspace's.
+
+## Working on it locally
+
+From this directory, with a raw engine clone around it:
+
+```bash
+GV_SPACES_ROOT="$PWD" node ../build.js
+```
+
+That composes the workspace into the engine's `dist/`, exactly as an instance
+would serve it — the galleries, the library tier derived from the skill, and the
+six prototypes. Each prototype also opens on its own by double-clicking its
+`index.html`.

package/seed/prototype-status.json

@@ -0,0 +1,9 @@
+{
+  "_comment": "Dev-status baseline per prototype, keyed <project>/<prototype>. Values: in-progress | dev-ready | ignore. Live chips cycle on click (KV) over this baseline.",
+  "start-here/connect-your-terminal": "dev-ready",
+  "start-here/set-up-your-design-system": "dev-ready",
+  "start-here/sample-with-comments": "in-progress",
+  "worked-examples/specimen-viewer": "dev-ready",
+  "worked-examples/slide-deck": "dev-ready",
+  "worked-examples/field-readings": "in-progress"
+}