@letterstory/cli 0.70.5 → 0.72.1

package/README.md

@@ -362,6 +362,12 @@ letterstory admin tuning comparison <id>               # per-measure verdicts (b
 letterstory admin tuning picks <id>                    # the blind queue; then: admin tuning pick <id> --cell <key> --pick left|right|tie
 letterstory admin tuning reading-list <id> --n 10      # your next blind pairs as links (Text A / Text B), to read off the screen; pick in the console
 letterstory admin tuning pair <id> --cell <key>        # one pair named: live and candidate, both texts, the measures per arm (a key reads every pair)
+letterstory admin tuning bank                                     # the eval bank: every eval (rules and drafts), instances, labels
+letterstory admin tuning bank-pool <eval-id>                      # draw an eval's pool from our shipped runs and the human corpus
+letterstory admin tuning bank-judge <eval-id> --prompt-file judge.md --mode score --threshold 4   # a judge version (or --live: the rule's own)
+letterstory admin tuning bank-score <eval-id> --version 2         # score it over the pool; prints agreement on held-out labels
+letterstory admin tuning bank-try <eval-id> --version 2           # the judge as a trial rule in candidates, and a comparison against live
+letterstory admin tuning invite --email editor@example.com        # invite an editor (Pick and Eval bank only); `people`, `revoke <id>`
 letterstory admin tuning side-by-side <id>,<id>,<id> [--cell <key>]   # several writers as one board: each one's measures against live; with --cell, every writer's text on that input
 letterstory admin tuning candidates --kernels all --patch '{"writer":"echo/echo"}' --note "Echo"   # the same change as a candidate of each kernel
 letterstory admin tuning session-new --title "Echo round 1" --kernel Hazel --input-file brief.md --kind outline [--version 22] [--versions 23,29]   # --versions: saved candidates, a trial each

package/lib/cli.mjs

@@ -56,7 +56,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.70.5";
+export const VERSION = "0.72.1";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value.
@@ -293,7 +293,7 @@ Connectors:
                                                        [--confirm-missing-target] re-publish even though
                                                        the item was deleted/unpublished on the provider
   connectors status --connector <connector> --publish-id <id>
-  connectors pull [--collection <uuid>] [--provider <webflow|framer|sanity|contentful>]
+  connectors pull [--collection <uuid>] [--provider <webflow|framer|sanity|contentful|github>]
                                                        Pull existing posts FROM a connected CMS into a
                                                        collection, reconciling (adopt/update/create/orphan).
                                                        --collection for a bound collection, --provider to
@@ -302,7 +302,10 @@ Connectors:
                                                        Save + validate CMS credentials. framer also needs
                                                        --project-url (+ [--no-auto-deploy]); sanity needs
                                                        --project-id [--dataset]; contentful needs --space-id
-                                                       [--environment].
+                                                       [--environment]; github takes a personal access
+                                                       token (Contents + Pull requests read/write) — its
+                                                       "mappings" are publish targets (repo, branch, path)
+                                                       and a publish opens a PR (live once merged).
   connectors disconnect --provider <p>                 Forget a CMS connection (keeps imported posts)
   connectors connections                               Show connection status for every provider
   connectors mappings --provider <p>                   List the org's field mappings for a provider
@@ -505,7 +508,7 @@ Collection onboarding (your OWN blog, on your org's domain — no provisioning):
                                                        Import the existing blog from its sitemap
                                                        (auto-discovered from the org's domain unless
                                                        --sitemap pins one) OR from a connected CMS with
-                                                       --cms <webflow|framer|sanity|contentful>, then
+                                                       --cms <webflow|framer|sanity|contentful|github>, then
                                                        derive content areas + series, build the topic
                                                        map, bind SEO demand, and stock Headlines & Queue.
                                                        Omit --collection to create a fresh one (--name,
@@ -634,13 +637,16 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                                                        registry the Pipeline tab draws (JSON).
   admin tuning <sub> …                                 The console's loop over a staff key: kernels,
                                                        candidate, compare, comparisons, picks, pick,
-                                                       ledger, reading-list, pair, side-by-side,
-                                                       evals, eval-add, eval-set, promote,
+                                                       ledger, reading-list, finalists,
+                                                       finalists-queue, pair, side-by-side,
+                                                       evals, eval-add, eval-set, proposals,
+                                                       propose-eval, capture-eval, reject-eval, promote,
                                                        sessions, session-new, propose, trial-add,
                                                        trial-run, trial-save, the Write input bank
                                                        (inputs, input, inputs-harvest, input-save),
                                                        screens (screen-new, screens, screen,
-                                                       screen-advance),
+                                                       screen-advance), the bake-off (bakeoff,
+                                                       bakeoff-pick, bakeoff-merge),
                                                        and the arena, shredder
                                                        and enhancer twins (every flag is listed in
                                                        cli/lib/commands/admin.mjs).

package/lib/commands/admin.mjs

@@ -8,6 +8,8 @@
 //   admin tuning-context [--q "<question>"]                                         (tuning:experiment)
 //   admin tuning-import <brief-results.json> [--experiment <id>]                    (tuning:experiment)
 //   admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|criteria|promote …   (tuning:experiment)
+//   admin tuning evals|eval-add|eval-set|proposals|propose-eval|capture-eval|reject-eval …    (tuning:experiment)
+//     (propose-eval --fix "…" files the reader's rewrite; the diff is classified to a lever, or to a schema gap: kind lever)
 //   admin evals scoreboard|cases|runs|run|triage|guard|retire …                      (fleet:read / tuning:experiment)
 //   admin crm import|capture|signals|record|signal|accounts|account|score|slack-channels|link-slack|white-glove|set-white-glove|churn|record-churn|undo-churn|onboard|onboarding|retry-onboarding|onboard-plan|payment-link …  (crm:read / crm:write)
 //   admin replays [--org <id>] [--target <id>] [--status …] [--limit n]                (fleet:read)
@@ -40,7 +42,7 @@ import { flagStr, flagNum, flagBool, flagList, printResult, compact, ok } from "
 import { watchDomainJob } from "./onboard.mjs";
 
 const SEER_MODES = ["suggest", "skip"];
-const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
+const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful", "github"];
 
 function staffKeyFrom(flags) {
 	const key = flagStr(flags["staff-key"]) || process.env.LETTERSTORY_STAFF_API_KEY || null;
@@ -439,20 +441,38 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning kernels                                       every catalog kernel, live version, writer, candidates
  *   admin tuning kernel <service-kernel-id> [--version N|live]  one version's file (JSON)
  *   admin tuning candidate <service-kernel-id> --file f.json [--note "…"]   save a file as a candidate version
- *   admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>]   start a comparison
+ *   admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>] [--pairs 20]   start a comparison (--pairs caps it: breadth at 10–20, depth at the full 66)
  *                        (Hazel:23@22 reads v23 against the test version v22 instead of live; it cannot promote)
  *   admin tuning comparisons | comparison <id>                list / read one (per-measure verdicts)
  *   admin tuning picks <comparison-id> [--criterion opening]   the blind queue (next pairs); with a criterion, the pairs not yet read for it (Eye Test mode)
  *   admin tuning pick <comparison-id> --cell <key> --pick left|right|tie [--criterion opening] [--note "why"]   record a blind pick (the note is the reader's reason; a criterion pick steers the next arm, never promotion)
  *   admin tuning criteria                                      the Eye Test's criteria: id, label and the question each asks of a pair
- *   admin tuning ledger <comparison-id>                        the defect ledger: per arm, what the diagnosis read named, the floor and the ceiling, the candidate's next arm
+ *   admin tuning loop                                          where the loop stands: what waits at each station, and where to go next
+ *   admin tuning ledger <comparison-id>                        the defect ledger: per arm, what the diagnosis read named, the floor and the ceiling, the candidate's next arm; then the reader edits per arm by lever, and the schema gaps
  *   admin tuning evals                                         the eval list: every defect category with its status and the picks' agreement (n, agreement, suggestion)
  *   admin tuning eval-add --id … --label … --how … --layer … --lever … --locality local|structural --axis … [--example "span"]   add a category (starts unvetted)
  *   admin tuning eval-set <id> [--status confirmed|rejected|unvetted] [--example "span" [--fix "…"]]   confirm / reject (a person's call), or add an example
+ *   admin tuning proposals [--status proposed|captured|rejected]   the eval proposals: spans readers marked in a pair's text with their words, and what became of each
+ *   admin tuning propose-eval --span "…" --comment "…" [--fix "…"] [--comparison <id> --cell <key> --side control|candidate] [--kind narrow|wide]   mark a span as an eval (no --side from a blind read); --fix is the reader's rewrite, classified to a lever (or a schema gap: kind lever)
+ *   admin tuning capture-eval <proposal-id> --as category --id … --label … --how … --layer … --lever … --locality local|structural --axis …   capture it into the eval list, the span (and its fix) as the category's example (appends when the id exists)
+ *   admin tuning capture-eval <proposal-id> --as rule          file it as narrow; the rule itself is written in the kernels rule lab
+ *   admin tuning capture-eval <proposal-id> --as lever [--note "…"]   file it as a schema gap: an edit no kernel-file lever can produce, for the kernels repo
+ *   admin tuning reject-eval <proposal-id>                      a span that was not an eval after all
  *   admin tuning reading-list <comparison-id> [--n 10]          your next blind pairs as links, to read off the screen
+ *   admin tuning finalists [--limit 10]                        the finalists feed: done, gates clean, no craft loss, not yet decided by the picks; ranked by the objective's order
+ *   admin tuning finalists-queue [--n 10]                      your next blind pairs round-robin across the finalists (a key reads the queue of the person who owns it; recording a pick still needs a person)
  *   admin tuning archive <comparison-id> [--undo]               take a read comparison out of the working list (or back); the record stays
  *   admin tuning comparisons [--archived only|all]              the list; archived ones only when asked
  *   admin tuning pair <comparison-id> --cell <key>             one pair named: live and candidate, both texts, the measures per arm
+ *   admin tuning bank                                          the eval bank: every eval (rules and drafts), instances, labels
+ *   admin tuning bank-eval <eval-id>                           one eval: its standing, judge versions and the report (JSON)
+ *   admin tuning bank-draft --name "…" --shape '<regex>' [--flags i]   a draft eval, not a rule yet
+ *   admin tuning bank-shape <eval-id> --shape '<regex>'|--rule [--flags i]   widen or narrow the pool's shape (--rule: back to the rule's own)
+ *   admin tuning bank-pool <eval-id> [--per-source 150] [--days 14]   draw the pool from our shipped runs and the human corpus
+ *   admin tuning bank-judge <eval-id> --live | --prompt-file f.md [--model m] [--mode score|same] [--threshold 4] [--context paragraph|sentence] [--examples id,id]
+ *   admin tuning bank-score <eval-id> --version N             score a judge version over the pool (call again for more than 600)
+ *   admin tuning bank-try <eval-id> --version N [--kernels Hazel,Aspen]   the judge as a trial rule in candidates, and a comparison against live
+ *   admin tuning people | invite --email e [--note "…"] | revoke <id>   who an admin invited into the console as an editor
  *   admin tuning side-by-side <id>,<id>[,…] [--cell <key>]     several comparisons as one board: each writer's measures against live, and one input's texts
  *   admin tuning candidates --kernels Hazel,Aspen|all --patch '{…}' [--base N] [--note "…"]   the same changes as a candidate of each kernel
  *   admin tuning promote <experiment-id> --versions <service-kernel-id>:<version>,…   promote from a "ship" decision
@@ -485,6 +505,15 @@ async function cmdAdminTuningContext(ctx) {
  *   admin tuning screens | screen <id>                         list / one screen: per candidate, each measure against the Base, with its noise
  *   admin tuning screen-advance <id>                           queue what the caps allow now (the cron does it every minute)
  *
+ * The bake-off: a screen's versions graded item by item against the checklist (the eval list's
+ * confirmed and unvetted categories, and the craft axes commitment / economy / movement), the winner
+ * per item tallied across the inputs, and a merge that composes the best of each into one candidate.
+ * Deterministic; a person overrides a grade and confirms the merge, which is a hypothesis until the
+ * eye test confirms it.
+ *   admin tuning bakeoff <screen-id> [--regrade]                 the winners table: item, trusted, leader, wins per version, graded; then the conflicts a merge would meet
+ *   admin tuning bakeoff-pick <screen-id> --input <key> --item <category:id|axis:id> --winner <version|none>   a person's grade on one input and item (replaces the machine's)
+ *   admin tuning bakeoff-merge <screen-id> [--resolve item=version,…] [--note "…"] [--compare 10]   save the merged file as a candidate of the base kernel (never live); --compare starts a comparison against live on that many pairs
+ *
  * Research (Phase 3): our arena's versions as files, research comparisons, the deploy split.
  *   admin tuning arenas | arena <version-id>                   our arena's versions / one version's file and diff
  *   admin tuning arena-candidate --patch '{…}' | --file f.json [--of <version-id>] [--note "…"]   save a candidate
@@ -638,7 +667,7 @@ async function cmdAdminTuning(ctx) {
 			const list = flagList(flags.candidates);
 			if (!title || !list?.length)
 				throw new CliError(
-					'Usage: admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>]'
+					'Usage: admin tuning compare --title "…" --candidates Hazel:21,Aspen:20 [--experiment <id>] [--pairs 20]'
 				);
 			// kernel:version, or kernel:version@control to read it against a test version instead of live.
 			const candidates = list.map((item) => {
@@ -656,7 +685,12 @@ async function cmdAdminTuning(ctx) {
 				ctx,
 				"POST",
 				`${T}/comparisons`,
-				compact({ title, candidates, experiment_id: flagStr(flags.experiment) })
+				compact({
+					title,
+					candidates,
+					experiment_id: flagStr(flags.experiment),
+					pairs: flags.pairs !== undefined ? Number(flags.pairs) : undefined,
+				})
 			);
 			return json ? printResult(io, flags, r) : io.log(`comparison ${r.comparison?.id ?? r.id ?? ""} started`);
 		}
@@ -769,12 +803,117 @@ async function cmdAdminTuning(ctx) {
 				? printResult(io, flags, r)
 				: io.log(`${r.category.id}: ${r.category.status}, ${(r.category.examples ?? []).length} examples`);
 		}
+		case "proposals": {
+			const status = flagStr(flags.status);
+			if (status && !["proposed", "captured", "rejected"].includes(status))
+				throw new CliError("Usage: admin tuning proposals [--status proposed|captured|rejected]");
+			const qs = status ? `?${new URLSearchParams({ status })}` : "";
+			const r = await staffRequest(ctx, "GET", `${T}/proposals${qs}`);
+			if (json) return printResult(io, flags, r);
+			const rows = r.proposals ?? [];
+			if (!rows.length) return io.log("(no proposals)");
+			for (const p of rows) {
+				const where = [p.cell_key, p.side].filter(Boolean).join(" / ") || "—";
+				const edit =
+					p.fix != null
+						? `\n    → "${p.fix}"  [${p.edit_class ?? "?"} → ${p.lever ?? "no lever: schema gap"}]`
+						: "";
+				io.log(
+					`${p.id}  ${p.status.padEnd(9)} ${p.kind.padEnd(6)} ${where}${p.category_id ? ` → ${p.category_id}` : ""}\n    "${p.span}"${edit}${p.comment ? `\n    ${p.comment}` : ""}`
+				);
+			}
+			return;
+		}
+		case "propose-eval": {
+			const span = flagStr(flags.span);
+			const side = flagStr(flags.side);
+			const kind = flagStr(flags.kind);
+			if (
+				!span ||
+				(side && !["control", "candidate"].includes(side)) ||
+				(kind && !["narrow", "wide"].includes(kind))
+			)
+				throw new CliError(
+					'Usage: admin tuning propose-eval --span "…" --comment "…" [--fix "…"] [--comparison <id> --cell <key> --side control|candidate] [--kind narrow|wide]'
+				);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/proposals`,
+				compact({
+					span,
+					comment: flagStr(flags.comment),
+					fix: flagStr(flags.fix),
+					comparison_id: flagStr(flags.comparison),
+					cell_key: flagStr(flags.cell),
+					side,
+					kind,
+				})
+			);
+			if (json) return printResult(io, flags, r);
+			const p = r.proposal;
+			const edit = p.fix != null ? ` — ${p.edit_class}: ${p.lever ?? "no lever maps: a schema gap"}` : "";
+			return io.log(`proposed ${p.id} (${p.kind})${edit}`);
+		}
+		case "capture-eval": {
+			const as = flagStr(flags.as);
+			const usage =
+				'Usage: admin tuning capture-eval <proposal-id> --as category --id … --label … --how … --layer … --lever … --locality local|structural --axis … | --as rule | --as lever [--note "…"]';
+			if (!id || !["category", "rule", "lever"].includes(as ?? "")) throw new CliError(usage);
+			let body = { as };
+			if (as === "lever") body = compact({ as, note: flagStr(flags.note) });
+			if (as === "category") {
+				const category = {
+					id: flagStr(flags.id),
+					label: flagStr(flags.label),
+					how: flagStr(flags.how),
+					layer: flagStr(flags.layer),
+					lever: flagStr(flags.lever) ?? "",
+					locality: flagStr(flags.locality),
+					axis: flagStr(flags.axis),
+				};
+				if (
+					!category.id ||
+					!category.label ||
+					!category.how ||
+					!category.layer ||
+					!category.axis ||
+					!["local", "structural"].includes(category.locality ?? "")
+				)
+					throw new CliError(usage);
+				body = { as, category };
+			}
+			const r = await staffRequest(ctx, "POST", `${T}/proposals/${id}/capture`, body);
+			return json
+				? printResult(io, flags, r)
+				: io.log(
+						`captured ${r.proposal.id} as ${r.proposal.kind}${r.category ? ` → ${r.category.id} (${(r.category.examples ?? []).length} examples)` : r.proposal.kind === "lever" ? "; a schema gap, filed for the kernels repo" : "; write the rule in the kernels rule lab"}`
+					);
+		}
+		case "reject-eval": {
+			if (!id) throw new CliError("Usage: admin tuning reject-eval <proposal-id>");
+			const r = await staffRequest(ctx, "POST", `${T}/proposals/${id}/reject`, {});
+			return json ? printResult(io, flags, r) : io.log(`rejected ${r.proposal.id}`);
+		}
 		case "criteria": {
 			const r = await staffRequest(ctx, "GET", `${T}/comparisons/criteria`);
 			if (json) return printResult(io, flags, r);
 			for (const c of r.criteria ?? []) io.log(`${c.id.padEnd(12)} ${c.label.padEnd(12)} ${c.question}`);
 			return;
 		}
+		case "loop": {
+			const r = await staffRequest(ctx, "GET", `${T}/loop`);
+			if (json) return printResult(io, flags, r);
+			io.log(`propose   ${r.propose.running} running`);
+			io.log(`read      ${r.read.settled_unread} settled, unread`);
+			io.log(`eye test  ${r.eye_test.finalists} finalists, ${r.eye_test.pairs_to_read} pairs to read`);
+			io.log(
+				`evals     ${r.evals.proposals_waiting} proposals waiting, ${r.evals.unvetted} unvetted, ${r.evals.suggested} with a suggestion${r.evals.reachable ? "" : " (the eval list could not be read)"}`
+			);
+			io.log(`promote   ${r.promote.promotable} won their picks`);
+			io.log(`\nnext: ${r.next}`);
+			return;
+		}
 		case "ledger": {
 			if (!id) throw new CliError("Usage: admin tuning ledger <comparison-id>");
 			const read = await staffRequest(ctx, "GET", `${T}/comparisons/${id}`);
@@ -800,6 +939,23 @@ async function cmdAdminTuning(ctx) {
 			if (!ledger.next_arm.length) io.log("  nothing local recurs on two pairs or more");
 			for (const n of ledger.next_arm)
 				io.log(`  ${n.instruction}${n.patch ? `  patch ${JSON.stringify(n.patch)}` : ""}`);
+			const edits = read.edits;
+			if (edits) {
+				io.log("\nreader edits:");
+				for (const side of ["control", "candidate"]) {
+					const a = edits[side];
+					io.log(`  ${side}: ${a.n} edit${a.n === 1 ? "" : "s"}`);
+					for (const l of a.by_lever) {
+						const ex = l.examples[0];
+						io.log(
+							`    ${l.lever}  ${l.edit_class}  n ${l.n}${ex ? `  e.g. “${String(ex.span).slice(0, 60)}” → “${String(ex.fix ?? "").slice(0, 60)}”` : ""}`
+						);
+					}
+				}
+				io.log(
+					`  unmapped (schema gaps): ${edits.unmapped}${edits.unplaced ? `  · unplaced: ${edits.unplaced}` : ""}`
+				);
+			}
 			return;
 		}
 		case "reading-list": {
@@ -812,6 +968,41 @@ async function cmdAdminTuning(ctx) {
 			);
 			return json ? printResult(io, flags, r) : io.log(r.text);
 		}
+		case "finalists": {
+			const limit = flagNum(flags.limit);
+			const qs = limit ? `?${new URLSearchParams({ limit: String(limit) })}` : "";
+			const r = await staffRequest(ctx, "GET", `${T}/finalists${qs}`);
+			if (json) return printResult(io, flags, r);
+			const rows = r.finalists ?? [];
+			if (!rows.length)
+				return io.log(
+					"(no finalists: nothing done with the gates clean and no craft loss that the picks have not decided)"
+				);
+			const cell = (v, w) => String(v ?? "—").padEnd(w);
+			const delta = (x) => (x == null ? "—" : x > 0 ? `+${x}` : String(x));
+			io.log(
+				`${"#".padStart(2)} ${cell("id", 8)} ${cell("title", 40)} ${cell("quality", 12)} ${"Δceil".padStart(6)} ${cell("in band", 12)} ${cell("latency", 12)} ${"picks".padStart(6)}  why`
+			);
+			rows.forEach((f, i) =>
+				io.log(
+					`${String(i + 1).padStart(2)} ${cell(f.id.slice(0, 8), 8)} ${cell(String(f.title).slice(0, 40), 40)} ${cell(f.quality, 12)} ${delta(f.ceiling_delta).padStart(6)} ${cell(f.in_band, 12)} ${cell(f.latency, 12)} ${`${f.picks.read}/${f.picks.target}`.padStart(6)}  ${f.why}`
+				)
+			);
+			return;
+		}
+		case "finalists-queue": {
+			const n = flagNum(flags.n);
+			const qs = n ? `?${new URLSearchParams({ limit: String(n) })}` : "";
+			const r = await staffRequest(ctx, "GET", `${T}/finalists/queue${qs}`);
+			if (json) return printResult(io, flags, r);
+			const pairs = r.pairs ?? [];
+			if (!pairs.length) return io.log("(nothing to read blind across the finalists)");
+			pairs.forEach((p, i) => {
+				const link = `${ctx.client.url}/superadmin/tuning?${new URLSearchParams({ tab: "compare", comparison: p.comparison_id, view: "read" })}`;
+				io.log(`${i + 1}. ${p.title}\n   ${p.cell_key}\n   ${link}`);
+			});
+			return;
+		}
 		case "pair": {
 			const cell = flagStr(flags.cell);
 			if (!id || !cell) throw new CliError("Usage: admin tuning pair <comparison-id> --cell <key>");
@@ -821,6 +1012,156 @@ async function cmdAdminTuning(ctx) {
 				await staffRequest(ctx, "GET", `${T}/comparisons/${id}/pair?${new URLSearchParams({ cell })}`)
 			);
 		}
+		case "bank": {
+			const r = await staffRequest(ctx, "GET", `${T}/bank`);
+			if (json) return printResult(io, flags, r);
+			for (const e of r.evals)
+				io.log(
+					`${e.id} [${e.status}${e.kind ? `, ${e.kind}` : ""}] ${e.name} — ${e.items} instances, ${e.labelled} labelled`
+				);
+			return;
+		}
+		case "bank-eval": {
+			if (!id) throw new CliError("Usage: admin tuning bank-eval <eval-id>");
+			return printResult(
+				io,
+				{ ...flags, json: true },
+				await staffRequest(ctx, "GET", `${T}/bank/${encodeURIComponent(id)}`)
+			);
+		}
+		case "bank-draft": {
+			const name = flagStr(flags.name);
+			const shape = flagStr(flags.shape);
+			if (!name || !shape)
+				throw new CliError("Usage: admin tuning bank-draft --name \"…\" --shape '<regex>' [--flags i]");
+			return printResult(
+				io,
+				flags,
+				await staffRequest(ctx, "POST", `${T}/bank`, compact({ name, shape, flags: flagStr(flags.flags) }))
+			);
+		}
+		case "bank-shape": {
+			const shape = flagBool(flags.rule) ? null : flagStr(flags.shape);
+			if (!id || shape === undefined)
+				throw new CliError("Usage: admin tuning bank-shape <eval-id> --shape '<regex>'|--rule [--flags i]");
+			return printResult(
+				io,
+				flags,
+				await staffRequest(ctx, "PATCH", `${T}/bank/${encodeURIComponent(id)}`, {
+					shape,
+					...compact({ flags: flagStr(flags.flags) }),
+				})
+			);
+		}
+		case "bank-pool": {
+			if (!id) throw new CliError("Usage: admin tuning bank-pool <eval-id> [--per-source 150] [--days 14]");
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/bank/${encodeURIComponent(id)}/pool`,
+				compact({ per_source: flagNum(flags["per-source"]), days: flagNum(flags.days) })
+			);
+			if (json) return printResult(io, flags, r);
+			io.log(`${r.added} new instances.`);
+			for (const [src, s] of Object.entries(r.stats))
+				io.log(
+					`${src}: ${s.matches} matches in ${s.textsWithMatch} of ${s.texts} texts (${s.perText} a text, ${Math.round(100 * s.share)}% of texts)`
+				);
+			return;
+		}
+		case "bank-judge": {
+			if (!id)
+				throw new CliError(
+					"Usage: admin tuning bank-judge <eval-id> --live | --prompt-file f.md [--model m] [--mode score|same] [--threshold 4] [--context paragraph|sentence] [--examples id,id]"
+				);
+			const file = flagStr(flags["prompt-file"]);
+			const body = flagBool(flags.live)
+				? { from_live: true }
+				: compact({
+						prompt: file ? readFileSync(file, "utf8") : flagStr(flags.prompt),
+						model: flagStr(flags.model),
+						mode: flagStr(flags.mode),
+						threshold: flagNum(flags.threshold),
+						context: flagStr(flags.context),
+						example_item_ids: flagStr(flags.examples)
+							?.split(",")
+							.map((x) => x.trim())
+							.filter(Boolean),
+						note: flagStr(flags.note),
+					});
+			return printResult(
+				io,
+				flags,
+				await staffRequest(ctx, "POST", `${T}/bank/${encodeURIComponent(id)}/judges`, body)
+			);
+		}
+		case "bank-score": {
+			const version = flagNum(flags.version);
+			if (!id || !version) throw new CliError("Usage: admin tuning bank-score <eval-id> --version N");
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/bank/${encodeURIComponent(id)}/judges/${version}/score`,
+				{}
+			);
+			if (json) return printResult(io, flags, r);
+			const read = r.report.judges.find((j) => j.version === version);
+			io.log(`scored ${r.scored} (${r.failed} failed).`);
+			if (read)
+				io.log(
+					`v${version} on ${read.held_out.n} held-out labels: agreement ${read.held_out.agreement ?? "—"}, precision ${read.held_out.precision ?? "—"}, recall ${read.held_out.recall ?? "—"}; cuts ours ${read.cut_rate.ours ?? "—"}, human ${read.cut_rate.human ?? "—"}${read.calibrates ? " — calibrates a trial" : ""}`
+				);
+			return;
+		}
+		case "bank-try": {
+			const version = flagNum(flags.version);
+			if (!id || !version)
+				throw new CliError("Usage: admin tuning bank-try <eval-id> --version N [--kernels Hazel,Aspen]");
+			const kernels = flagStr(flags.kernels)
+				?.split(",")
+				.map((x) => x.trim())
+				.filter(Boolean);
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/bank/${encodeURIComponent(id)}/judges/${version}/trial`,
+				compact({ kernels, title: flagStr(flags.title) })
+			);
+			if (json) return printResult(io, flags, r);
+			io.log(`comparison ${r.comparison_id}: ${r.candidates.map((c) => `${c.kernel} v${c.version}`).join(", ")}`);
+			if (r.refused.length)
+				io.log(`refused: ${r.refused.map((x) => `${x.kernel ?? "?"}: ${x.error}`).join("; ")}`);
+			return io.log(
+				`${ctx.client.url}/superadmin/tuning?${new URLSearchParams({ tab: "compare", comparison: r.comparison_id })}`
+			);
+		}
+		case "people": {
+			const r = await staffRequest(ctx, "GET", `${T}/people`);
+			if (json) return printResult(io, flags, r);
+			for (const p of r.people)
+				io.log(
+					`${p.id} ${p.email} ${p.role} — ${p.revoked_at ? "revoked" : p.signed_in ? "signed in" : "invited"}${p.invite_link ? ` ${p.invite_link}` : ""}`
+				);
+			return;
+		}
+		case "invite": {
+			const email = flagStr(flags.email);
+			if (!email) throw new CliError('Usage: admin tuning invite --email e [--note "…"]');
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/people`,
+				compact({ email, role: "editor", note: flagStr(flags.note) })
+			);
+			if (json) return printResult(io, flags, r);
+			return io.log(
+				`invited ${r.person.email} as an editor${r.invite_link ? `: ${r.invite_link}` : ""}${r.email_sent ? " (emailed)" : ""}`
+			);
+		}
+		case "revoke": {
+			if (!id) throw new CliError("Usage: admin tuning revoke <person-id>");
+			return printResult(io, flags, await staffRequest(ctx, "DELETE", `${T}/people/${id}`));
+		}
 		case "side-by-side": {
 			const ids = (id ?? "")
 				.split(",")
@@ -1202,6 +1543,98 @@ async function cmdAdminTuning(ctx) {
 				? printResult(io, flags, r)
 				: io.log(`queued ${r.queued} run(s)${r.waiting ? `; waiting: ${r.waiting}` : ""}`);
 		}
+		// --- The bake-off: a screen's versions graded item by item, the winners table, the merge ---
+		case "bakeoff": {
+			if (!id) throw new CliError("Usage: admin tuning bakeoff <screen-id> [--regrade]");
+			const r = await staffRequest(
+				ctx,
+				"GET",
+				`${T}/screens/${id}/bakeoff${flagBool(flags.regrade) ? "?regrade=1" : ""}`
+			);
+			if (json) return printResult(io, flags, r);
+			io.log(
+				`bake-off ${r.screen.title}: v${r.versions.join(", v")} on ${r.inputs.length} input(s); leader ${r.leader === null ? "none" : `v${r.leader}`}`
+			);
+			if (r.unversioned.length) io.log(`left out (not a saved version): ${r.unversioned.join(", ")}`);
+			io.log("");
+			io.log(
+				`${"item".padEnd(32)} ${"trusted".padEnd(8)} ${"leader".padEnd(7)} ${r.versions.map((v) => `v${v}`.padStart(6)).join("")}  graded`
+			);
+			for (const row of r.table)
+				io.log(
+					`${row.item.id.padEnd(32)} ${(row.trusted ? "yes" : "no").padEnd(8)} ${(row.leader === null ? "—" : `v${row.leader}`).padEnd(7)} ${r.versions.map((v) => String(row.wins[v] ?? 0).padStart(6)).join("")}  ${row.graded}`
+				);
+			io.log("");
+			io.log(
+				r.conflicts_if_merged.length
+					? `conflicts if merged: ${r.conflicts_if_merged.map((c) => `${c.path} ← ${c.candidates.map((x) => `${x.item} v${x.version}`).join(" | ")}`).join("; ")}`
+					: "conflicts if merged: none"
+			);
+			return;
+		}
+		case "bakeoff-pick": {
+			const input = flagStr(flags.input);
+			const item = flagStr(flags.item);
+			const winner = flagStr(flags.winner);
+			if (!id || !input || !item || !winner)
+				throw new CliError(
+					"Usage: admin tuning bakeoff-pick <screen-id> --input <key> --item <category:id|axis:id> --winner <version|none>"
+				);
+			const winnerVersion = winner === "none" ? null : Number(winner);
+			if (winnerVersion !== null && !(Number.isInteger(winnerVersion) && winnerVersion > 0))
+				throw new CliError("--winner is a version number, or none");
+			const r = await staffRequest(ctx, "POST", `${T}/screens/${id}/bakeoff/pick`, {
+				input_key: input,
+				item_id: item,
+				winner_version: winnerVersion,
+			});
+			if (json) return printResult(io, flags, r);
+			const row = r.read.table.find((x) => x.item.id === item);
+			return io.log(
+				`graded ${item} on ${input}: ${winnerVersion === null ? "none" : `v${winnerVersion}`}${row ? ` · leader now ${row.leader === null ? "none" : `v${row.leader}`}` : ""}`
+			);
+		}
+		case "bakeoff-merge": {
+			if (!id)
+				throw new CliError(
+					'Usage: admin tuning bakeoff-merge <screen-id> [--resolve item=version,…] [--note "…"] [--compare 10]'
+				);
+			const resolve = {};
+			for (const pair of flagList(flags.resolve).flatMap((x) =>
+				x
+					.split(",")
+					.map((y) => y.trim())
+					.filter(Boolean)
+			)) {
+				const [item, version] = pair.split("=").map((x) => x.trim());
+				const v = Number(version);
+				if (!item || !(Number.isInteger(v) && v > 0))
+					throw new CliError(`--resolve: "${pair}" is not item=version`);
+				resolve[item] = v;
+			}
+			const compare = flags.compare === undefined ? undefined : { pairs: flagNum(flags.compare) ?? 10 };
+			const r = await staffRequest(
+				ctx,
+				"POST",
+				`${T}/screens/${id}/bakeoff/merge`,
+				compact({
+					resolve: Object.keys(resolve).length ? resolve : undefined,
+					note: flagStr(flags.note),
+					compare,
+				})
+			);
+			if (json) return printResult(io, flags, r);
+			io.log(
+				`merged from v${r.base} → candidate v${r.version}${r.comparison_id ? ` · comparison ${r.comparison_id}` : ""}`
+			);
+			for (const p of r.provenance)
+				io.log(`  ${p.applied ? "applied" : `skipped (${p.skipped})`}  ${p.item}  ${p.path}  from v${p.from}`);
+			if (r.conflicts.length)
+				io.log(
+					`conflicts left (the base's value kept): ${r.conflicts.map((c) => `${c.path} ← ${c.candidates.map((x) => `${x.item} v${x.version}`).join(" | ")}`).join("; ")}`
+				);
+			return;
+		}
 		// --- Research: our arena's versions, research comparisons, the deploy split ---
 		case "arenas": {
 			const r = await staffRequest(ctx, "GET", `${T}/arena-files`);
@@ -1570,7 +2003,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|ledger|evals|eval-add|eval-set|reading-list|pair|side-by-side|candidates|base-kernels|base-versions|sessions|session|session-new|propose|trial-add|trial-run|trial-save|promote|arenas|arena|arena-candidate|arena-dials|comparison-extend|research-compare|research-inputs|research-split|research-standing|promote-arena|shred-compare|shred-inputs|shred-split|shred-standing|shredders|shredder|shredder-candidate|promote-shredder|enhance-compare|enhance-inputs|enhance-split|enhance-standing|enhancers|enhancer|enhancer-candidate|promote-enhancer (see --help)"
+				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|loop|ledger|evals|eval-add|eval-set|proposals|propose-eval|capture-eval|reject-eval|reading-list|finalists|finalists-queue|pair|bank|bank-eval|bank-draft|bank-shape|bank-pool|bank-judge|bank-score|bank-try|people|invite|revoke|side-by-side|candidates|base-kernels|base-versions|sessions|session|session-new|propose|trial-add|trial-run|trial-save|promote|arenas|arena|arena-candidate|arena-dials|comparison-extend|research-compare|research-inputs|research-split|research-standing|promote-arena|shred-compare|shred-inputs|shred-split|shred-standing|shredders|shredder|shredder-candidate|promote-shredder|enhance-compare|enhance-inputs|enhance-split|enhance-standing|enhancers|enhancer|enhancer-candidate|promote-enhancer (see --help)"
 			);
 	}
 }

package/lib/commands/connectors.mjs

@@ -5,7 +5,7 @@
 import { CliError } from "../client.mjs";
 import { printResult, ok, argsFromFlags } from "./shared.mjs";
 
-const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
+const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful", "github"];
 const PUBLISH_CONNECTORS = ["webflow", "framer", "google_docs", "contentful", "github"];
 
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.
@@ -121,7 +121,7 @@ async function connectorsPull(ctx) {
 	// or both (--provider wires an unbound --collection first). At least one required.
 	const args = argsFromFlags(ARGS.import_from_cms, flags);
 	if (!args.collection_id && !args.provider) {
-		throw new CliError("Pass --collection <id> and/or --provider <webflow|framer|sanity|contentful>");
+		throw new CliError("Pass --collection <id> and/or --provider <webflow|framer|sanity|contentful|github>");
 	}
 	const result = await client.callTool("import_from_cms", args);
 	ok(

package/lib/commands/onboard.mjs

@@ -66,7 +66,7 @@ import {
 const COVER_STYLES = ["editorial_image", "full_ai", "line_art"];
 const DOMAIN_MODES = ["subdomain", "buy_now", "connect_later"];
 const SEER_MODES = ["suggest", "skip"];
-const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful"];
+const CMS_PROVIDERS = ["webflow", "framer", "sanity", "contentful", "github"];
 const APPROVAL_MODES = ["autopilot", "review_window", "manual"];
 
 // How every tool this module calls gets its arguments — see `argsFromFlags` in shared.mjs.

package/lib/commands/phantom.mjs

@@ -73,6 +73,12 @@ export const ARGS = {
 				theme: "theme",
 				customer_ref: { flag: "customer-ref" },
 				collection_id: { flag: "collection" },
+				redesign: { flag: "redesign", type: "bool", negate: "no-redesign" },
+				// `--layout none` clears the choice (the site's theme then suggests one).
+				layout: {
+					value: (flags) =>
+						flags.layout === undefined ? undefined : flags.layout === "none" ? null : String(flags.layout),
+				},
 			},
 		},
 		collection: { value: (flags) => readJsonObjectFlag(flags, "collection-config") },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.70.5",
+	"version": "0.72.1",
 	"description": "Spin up and manage Letterstory phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",