@letterstory/cli 0.70.2 → 0.71.0

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.2";
+export const VERSION = "0.71.0";
 
 // 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,7 +637,10 @@ 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,
-                                                       reading-list, pair, side-by-side, 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),

package/lib/commands/admin.mjs

@@ -7,7 +7,9 @@
 //   admin experiments list|show|new|update|note|started|spend|conclude|abandon …   (tuning:experiment)
 //   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|promote …   (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,15 +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>                         the blind queue (next pairs)
- *   admin tuning pick <comparison-id> --cell <key> --pick left|right|tie   record a blind pick
+ *   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 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
@@ -633,7 +658,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) => {
@@ -651,7 +676,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`);
 		}
@@ -670,24 +700,255 @@ async function cmdAdminTuning(ctx) {
 		case "comparison":
 			if (!id) throw new CliError("Usage: admin tuning comparison <id>");
 			return printResult(io, { ...flags, json: true }, await staffRequest(ctx, "GET", `${T}/comparisons/${id}`));
-		case "picks":
-			if (!id) throw new CliError("Usage: admin tuning picks <comparison-id>");
+		case "picks": {
+			if (!id) throw new CliError("Usage: admin tuning picks <comparison-id> [--criterion opening]");
+			const criterion = flagStr(flags.criterion);
+			const qs = criterion ? `?${new URLSearchParams({ criterion })}` : "";
 			return printResult(
 				io,
 				{ ...flags, json: true },
-				await staffRequest(ctx, "GET", `${T}/comparisons/${id}/picks`)
+				await staffRequest(ctx, "GET", `${T}/comparisons/${id}/picks${qs}`)
 			);
+		}
 		case "pick": {
 			const cell = flagStr(flags.cell);
 			const pick = flagStr(flags.pick);
+			const note = flagStr(flags.note);
+			const criterion = flagStr(flags.criterion);
 			if (!id || !cell || !["left", "right", "tie"].includes(pick ?? ""))
-				throw new CliError("Usage: admin tuning pick <comparison-id> --cell <key> --pick left|right|tie");
+				throw new CliError(
+					'Usage: admin tuning pick <comparison-id> --cell <key> --pick left|right|tie [--criterion opening] [--note "why"]'
+				);
 			return printResult(
 				io,
 				flags,
-				await staffRequest(ctx, "POST", `${T}/comparisons/${id}/picks`, { cell_key: cell, outcome: pick })
+				await staffRequest(ctx, "POST", `${T}/comparisons/${id}/picks`, {
+					cell_key: cell,
+					outcome: pick,
+					...(criterion ? { criterion } : {}),
+					...(note ? { note } : {}),
+				})
 			);
 		}
+		case "evals": {
+			const r = await staffRequest(ctx, "GET", `${T}/evals`);
+			if (json) return printResult(io, flags, r);
+			const rows = r.categories ?? [];
+			if (!rows.length) return io.log("(no categories)");
+			const cell = (v, w) => String(v ?? "—").padEnd(w);
+			io.log(
+				`${cell("id", 24)} ${cell("status", 10)} ${cell("layer", 10)} ${cell("lever", 30)} ${"n".padStart(4)} ${"agree".padStart(6)} ${cell("suggest", 10)} ${"ex".padStart(3)}`
+			);
+			for (const c of rows) {
+				const v = c.vetting ?? {};
+				io.log(
+					`${cell(c.id, 24)} ${cell(c.status, 10)} ${cell(c.layer, 10)} ${cell(c.lever || "—", 30)} ${String(v.n ?? 0).padStart(4)} ${String(v.agreement ?? "—").padStart(6)} ${cell(v.suggestion, 10)} ${String((c.examples ?? []).length).padStart(3)}`
+				);
+			}
+			return;
+		}
+		case "eval-add": {
+			const body = {
+				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),
+			};
+			const example = flagStr(flags.example);
+			if (
+				!body.id ||
+				!body.label ||
+				!body.how ||
+				!body.layer ||
+				!body.axis ||
+				!["local", "structural"].includes(body.locality ?? "")
+			)
+				throw new CliError(
+					'Usage: admin tuning eval-add --id … --label … --how … --layer … --lever … --locality local|structural --axis … [--example "span"]'
+				);
+			if (example) body.examples = [{ span: example, ...(flags.fix ? { fix: flagStr(flags.fix) } : {}) }];
+			const r = await staffRequest(ctx, "POST", `${T}/evals`, body);
+			return json ? printResult(io, flags, r) : io.log(`added ${r.category.id} (${r.category.status})`);
+		}
+		case "eval-set": {
+			const status = flagStr(flags.status);
+			const example = flagStr(flags.example);
+			if (!id || (!status && !example) || (status && !["confirmed", "rejected", "unvetted"].includes(status)))
+				throw new CliError(
+					'Usage: admin tuning eval-set <id> [--status confirmed|rejected|unvetted] [--example "span" [--fix "…"]]'
+				);
+			const patch = {};
+			if (status) patch.status = status;
+			if (example) {
+				// The PATCH replaces the whole list: read what is stored and append.
+				const current = (await staffRequest(ctx, "GET", `${T}/evals`)).categories?.find((c) => c.id === id);
+				if (!current) throw new CliError(`No category ${id} in the eval list`);
+				const fix = flagStr(flags.fix);
+				patch.examples = [...(current.examples ?? []), { span: example, ...(fix ? { fix } : {}) }];
+			}
+			const r = await staffRequest(ctx, "PATCH", `${T}/evals/${encodeURIComponent(id)}`, patch);
+			return json
+				? 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}`);
+			const ledger = read.ledger;
+			if (!ledger)
+				throw new CliError(
+					"This comparison has no ledger (not a Write comparison, or read before the diagnosis read existed)."
+				);
+			if (json) return printResult(io, flags, ledger);
+			const arm = (a) =>
+				`${a.arm}: ${a.read} read · floor ${a.floor ?? "—"} · ceiling ${a.ceiling ?? "—"} · local/pair ${a.local_per_pair ?? "—"} · structural/pair ${a.structural_per_pair ?? "—"}`;
+			io.log(arm(ledger.control));
+			io.log(arm(ledger.candidate));
+			io.log(`Δ floor ${ledger.delta.floor ?? "—"} · Δ ceiling ${ledger.delta.ceiling ?? "—"}`);
+			for (const a of [ledger.control, ledger.candidate]) {
+				io.log(`\n${a.arm} — by category (cost, pairs, lever):`);
+				for (const c of a.categories.slice(0, 12))
+					io.log(
+						`  ${c.category}${c.locality === "structural" ? " (structural)" : ""}  cost ${c.cost}  on ${c.pairs} pairs  → ${c.lever ?? "—"}${c.example ? `  e.g. “${String(c.example).slice(0, 90)}”` : ""}`
+					);
+			}
+			io.log("\nnext arm:");
+			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": {
 			if (!id) throw new CliError("Usage: admin tuning reading-list <comparison-id> [--n 10]");
 			const n = flagStr(flags.n);
@@ -698,6 +959,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>");
@@ -707,6 +1003,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(",")
@@ -1456,7 +1902,7 @@ async function cmdAdminTuning(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: admin tuning kernels|kernel|candidate|compare|comparisons|comparison|picks|pick|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/package.json

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