omakit 0.5.1 → 0.6.1

package/tools/marketplace/pin.mjs

@@ -10,7 +10,7 @@
 // path outside it, because on a partial clone such a read would quietly reach
 // for the network instead of failing.
 import { execFileSync, spawnSync } from "node:child_process"
-import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { existsSync, readdirSync, readFileSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 import { omakitCacheDir } from "./paths.mjs"
 
@@ -83,7 +83,7 @@ function pinMigration(repoRoot, env = process.env) {
 }
 
 function git(dir, args, options = {}) {
-  return execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...options })
+  return execFileSync("git", ["-C", dir, ...args], { timeout: 300_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...options })
 }
 
 /** Identity of the checkout at `dir`: commit plus the policy constants read from the pinned source. */
@@ -127,35 +127,69 @@ function hasCommit(dir) {
   }
 }
 
+/** Is a process alive: signal 0 asks without sending; EPERM means it is there and somebody else's. */
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error.code === "EPERM"
+  }
+}
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/** How long a second first run waits for the first to finish fetching before it gives up: the fetch is about 2 s on the reference network, so this is generous. */
+export const PIN_WAIT_MS = 300_000
+
 /**
- * Reproducible setup: fetch exactly the pinned commit (depth 1) into
- * the XDG cache and check it out detached. Idempotent; never rewrites
- * an existing checkout that already sits at the pin.
- *
- * `log` is told what is happening as `{ state, text }`: a `pass` or `info`
- * line to keep, or `fetching` for the slow step about to start, which the CLI
- * draws as a progress line rather than a line of output.
+ * The lock beside the pin, `<dir>.lock/`, made atomically: `mkdir` without
+ * `recursive` fails with EEXIST when it is there, so exactly one process
+ * holds it. The holder writes its pid into it; a lock whose pid is gone is
+ * stale and is taken over. Returns `release()`, or null when another live
+ * process holds it.
  */
-export function ensurePin(repoRoot, log = () => {}, env = process.env) {
-  const migration = pinMigration(repoRoot, env)
-  if (migration) throw migration
-  const dir = marketplacePinDir(repoRoot, env)
-  if (existsSync(join(dir, ".git")) && hasCommit(dir)) {
-    const identity = readPinIdentity(dir)
-    if (identity.commit === MARKETPLACE_PIN.commit && !identity.dirty) {
-      log({ state: "pass", text: `marketplace pin ${identity.commit.slice(0, 7)} present at ${dir}` })
-      return { dir, identity, fetched: false }
+function claimLock(lockDir) {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      mkdirSync(lockDir)
+      writeFileSync(join(lockDir, "holder.json"), `${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`)
+      return () => rmSync(lockDir, { recursive: true, force: true })
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error
+      let holder = null
+      try {
+        holder = JSON.parse(readFileSync(join(lockDir, "holder.json"), "utf8")).pid
+      } catch {
+        holder = null
+      }
+      // A lock without a holder file yet is one being written this instant; a lock whose holder is dead is stale.
+      if (holder !== null && !alive(holder)) {
+        rmSync(lockDir, { recursive: true, force: true })
+        continue
+      }
+      return null
     }
-    if (identity.dirty) throw new PinError(`${dir} has local modifications; remove the directory and run again`)
-    log({ state: "info", text: `${dir} is at ${identity.commit}, not the pin` })
-  } else if (!existsSync(join(dir, ".git"))) {
-    mkdirSync(dir, { recursive: true })
-    execFileSync("git", ["init", "-q", dir], { encoding: "utf8" })
-    git(dir, ["remote", "add", "origin", MARKETPLACE_PIN.repository])
   }
+  return null
+}
+
+/**
+ * Fetch the pinned commit into a staging directory beside the pin, sparse
+ * and blob-filtered, and check it out detached. Written as plumbing rather
+ * than through `git sparse-checkout`, so the result does not depend on the
+ * git version's cone-mode defaults. `dir` here is the staging directory,
+ * and the sparse-checkout file is the one write beside the pin.
+ */
+function populatePin(dir, log) {
+  rmSync(dir, { recursive: true, force: true })
+  mkdirSync(dir, { recursive: true })
+  execFileSync("git", ["init", "-q", dir], { timeout: 60_000, encoding: "utf8" })
+  git(dir, ["remote", "add", "origin", MARKETPLACE_PIN.repository])
   log({ state: "fetching", text: `fetching the pinned marketplace checkout, ${MARKETPLACE_PIN.commit.slice(0, 7)}, about 15 MB` })
-  // Written as plumbing rather than through `git sparse-checkout`, so the
-  // result does not depend on the git version's cone-mode defaults.
   git(dir, ["config", "core.sparseCheckout", "true"])
   mkdirSync(join(dir, ".git/info"), { recursive: true })
   writeFileSync(join(dir, ".git/info/sparse-checkout"), `${PIN_PATHS.join("\n")}\n`)
@@ -174,8 +208,93 @@ export function ensurePin(repoRoot, log = () => {}, env = process.env) {
   git(dir, ["checkout", "-q", "--detach", MARKETPLACE_PIN.commit])
   const identity = readPinIdentity(dir)
   if (identity.commit !== MARKETPLACE_PIN.commit) throw new PinError(`checkout ended at ${identity.commit}`)
-  log({ state: "pass", text: `marketplace pin ${identity.commit.slice(0, 7)} (baseline ${identity.baselineVersion}, ${identity.enforcementMode}) at ${dir}, ${pinDiskUsage(dir)}` })
-  return { dir, identity, fetched: true }
+  return identity
+}
+
+/**
+ * Reproducible setup: fetch exactly the pinned commit (depth 1) into
+ * the XDG cache and check it out detached. Idempotent; never rewrites
+ * an existing checkout that already sits at the pin.
+ *
+ * Two first runs against one cache are serialised: the fetch goes into a
+ * staging directory (`<dir>.staging-<pid>`) under a lock (`<dir>.lock/`,
+ * made atomically), and the finished checkout is renamed into place, so
+ * the pin is either absent or whole and never a directory two `git init`s
+ * are racing in. A process that finds the lock held waits for the holder
+ * and then verifies what it left. Measured on 2026-09-19: two `omakit pin`
+ * against one empty cache ran `git init` in the same directory, and one
+ * died on "cannot copy .git/description: File exists"
+ * (docs/evidence/ux/2026-09-19-acceptance.json, finding 6).
+ *
+ * `log` is told what is happening as `{ state, text }`: a `pass` or `info`
+ * line to keep, or `fetching` for the slow step about to start, which the CLI
+ * draws as a progress line rather than a line of output. `populate` is the
+ * fetch step, injectable for the tests that prove the serialisation without
+ * a network.
+ */
+export function ensurePin(repoRoot, log = () => {}, env = process.env, { populate = populatePin, waitMs = PIN_WAIT_MS } = {}) {
+  const migration = pinMigration(repoRoot, env)
+  if (migration) throw migration
+  const dir = marketplacePinDir(repoRoot, env)
+  const present = () => {
+    if (!existsSync(join(dir, ".git")) || !hasCommit(dir)) return null
+    const identity = readPinIdentity(dir)
+    if (identity.dirty) throw new PinError(`${dir} has local modifications; remove the directory and run again`)
+    return identity
+  }
+  const found = present()
+  if (found && found.commit === MARKETPLACE_PIN.commit) {
+    log({ state: "pass", text: `marketplace pin ${found.commit.slice(0, 7)} present at ${dir}` })
+    return { dir, identity: found, fetched: false }
+  }
+  if (found) log({ state: "info", text: `${dir} is at ${found.commit}, not the pin` })
+  mkdirSync(dirname(dir), { recursive: true })
+  const lockDir = `${dir}.lock`
+  let release = claimLock(lockDir)
+  if (!release) {
+    // Another first run holds the lock: wait for it, then read what it left.
+    log({ state: "info", text: `another omakit is fetching the pin at ${dir}; waiting for it` })
+    const deadline = Date.now() + waitMs
+    while (existsSync(lockDir) && Date.now() < deadline) {
+      sleepMs(200)
+      // A holder that died mid-fetch leaves its lock; take it over.
+      release = claimLock(lockDir)
+      if (release) break
+    }
+    if (!release) {
+      const after = present()
+      if (after && after.commit === MARKETPLACE_PIN.commit) {
+        log({ state: "pass", text: `marketplace pin ${after.commit.slice(0, 7)} present at ${dir}, fetched by the other omakit` })
+        return { dir, identity: after, fetched: false, waited: true }
+      }
+      if (existsSync(lockDir)) throw new PinError(`another omakit has held the pin's lock at ${lockDir} for ${Math.round(waitMs / 1000)} s; if it is gone, remove the lock directory and run again`)
+      throw new PinError(`the other omakit left no pin at ${dir}; run \`omakit pin\` again`)
+    }
+  }
+  try {
+    // The lock is ours; the pin may have appeared while we waited for it.
+    const meanwhile = present()
+    if (meanwhile && meanwhile.commit === MARKETPLACE_PIN.commit) {
+      log({ state: "pass", text: `marketplace pin ${meanwhile.commit.slice(0, 7)} present at ${dir}, fetched by the other omakit` })
+      return { dir, identity: meanwhile, fetched: false, waited: true }
+    }
+    const staging = `${dir}.staging-${process.pid}`
+    try {
+      const identity = populate(staging, log)
+      // Into place in one rename; a checkout at another commit, or one that
+      // never got its HEAD, is moved aside first and removed after.
+      const aside = `${dir}.replaced-${process.pid}`
+      if (existsSync(dir)) renameSync(dir, aside)
+      renameSync(staging, dir)
+      rmSync(aside, { recursive: true, force: true })
+      log({ state: "pass", text: `marketplace pin ${identity.commit.slice(0, 7)} (baseline ${identity.baselineVersion}, ${identity.enforcementMode}) at ${dir}, ${pinDiskUsage(dir)}` })
+      return { dir, identity, fetched: true }
+    } finally {
+      rmSync(staging, { recursive: true, force: true })
+    }
+  } finally {
+    release()
+  }
 }
 
 /**
@@ -193,7 +312,7 @@ export function pinDiskUsage(dir, env = process.env) {
   // warned "cannot access '.git/index.lock'" over its momentary lock file
   // and exited 1, so doctor said "size unknown" for a checkout it had the
   // size of. Only a run that printed no total is unknown.
-  const result = spawnSync("du", ["-skH", dir], { encoding: "utf8", env, stdio: ["ignore", "pipe", "ignore"] })
+  const result = spawnSync("du", ["-skH", dir], { timeout: 60_000, encoding: "utf8", env, stdio: ["ignore", "pipe", "ignore"] })
   const output = String(result.stdout || "").trim().split(/\s+/)[0]
   if (result.error || !/^\d+$/.test(output)) return "size unknown"
   const mib = Number(output) / 1024
@@ -201,11 +320,37 @@ export function pinDiskUsage(dir, env = process.env) {
 }
 
 /** True when the checkout was fetched with only PIN_PATHS, as a fresh one is. */
-export function pinIsSparse(dir) {
+/**
+ * Whether the checkout is the sparse one `omakit pin` fetches: judged by
+ * what is on disk, the top-level entries being the pinned paths and
+ * nothing else, not by a git setting. Measured on 2026-09-19 by a first
+ * user whose freshly fetched pin was told it "predates the sparse fetch"
+ * and should be removed, because the answer came from `git config
+ * core.sparseCheckout` and that read failed on their machine while the
+ * tree itself was exactly the four pinned paths (docs/evidence/ux/
+ * 2026-09-19-first-user-test.json, finding 9). Returns the entries beyond
+ * the pin too, so doctor can name what a full checkout carries.
+ *
+ * @returns {{ sparse: boolean, extra: string[], sparseCheckoutConfig: boolean|null }}
+ */
+export function pinShape(dir) {
+  const pinned = new Set(PIN_PATHS.map((pattern) => pattern.replace(/^\//, "").split("/")[0]))
+  let entries = []
   try {
-    const enabled = execFileSync("git", ["-C", dir, "config", "--get", "core.sparseCheckout"], { encoding: "utf8" }).trim()
-    return enabled === "true"
+    entries = readdirSync(dir).filter((name) => name !== ".git")
   } catch {
-    return false
+    return { sparse: false, extra: [], sparseCheckoutConfig: null }
+  }
+  const extra = entries.filter((name) => !pinned.has(name)).sort()
+  let sparseCheckoutConfig = null
+  try {
+    sparseCheckoutConfig = execFileSync("git", ["-C", dir, "config", "--get", "core.sparseCheckout"], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() === "true"
+  } catch {
+    sparseCheckoutConfig = null
   }
+  return { sparse: entries.length > 0 && extra.length === 0, extra, sparseCheckoutConfig }
+}
+
+export function pinIsSparse(dir) {
+  return pinShape(dir).sparse
 }

package/tools/marketplace/setup.mjs

@@ -12,14 +12,14 @@
 // makes completions load, when a new shell has no loader. Everywhere else a
 // step that is the user's to take is printed as the command, and stops.
 
-import { execFileSync } from "node:child_process"
 import { banner } from "./banner.mjs"
+import { version } from "./doctor.mjs"
 import { credential, UNAUTHENTICATED_LIMIT } from "./github.mjs"
 import { ensurePin, marketplacePinDir, pinDiskUsage } from "./pin.mjs"
 import { progress } from "./progress.mjs"
-import { action, colourEnabled, GUTTER, mark, styler, wrap } from "./style.mjs"
+import { action, colourEnabled, GUTTER, mark, styler, verdict, wrap } from "./style.mjs"
 import { TAGLINE } from "./usage.mjs"
-import { installCompletion } from "./completion.mjs"
+import { completionInstall, installCompletion } from "./completion.mjs"
 import { appendLoaderBlock, completionWorks, loaderBlock, loaderBlockPresent, verifyCompletion } from "./completion-check.mjs"
 import { submissionContract } from "./form.mjs"
 import { pathHint } from "./path-hint.mjs"
@@ -51,8 +51,13 @@ export async function completionStep({ repoRoot, pin, version, stream = process.
     const contract = await submissionContract({ repoRoot })
     completion = installCompletion({ contract, pin, version, env })
   } catch (error) {
-    step("info", `tab completion was not installed: ${error.message}`)
-    return { state: "error", shell: null, rcAppended: false }
+    // A failed install is a failure, in setup's own verdict and in doctor's
+    // (measured on 2026-09-19: an EROFS here printed as `info`, setup ended
+    // READY, and doctor called the old script healthy; finding 8).
+    const target = completionInstall(env)
+    step("fail", `tab completion was not installed: ${error.message}${error.code ? ` (${error.code})` : ""}`)
+    if (target) fix(`Make ${target.display} writable (or remove the file there), then run \`omakit setup --completion\`; until then \`omakit doctor\` reports the script as stale.`)
+    return { state: "error", shell: target?.shell || null, rcAppended: false, error: error.message }
   }
   if (completion.state === "unsupported") {
     step("info", completion.shell
@@ -101,15 +106,6 @@ export async function completionStep({ repoRoot, pin, version, stream = process.
   return { state: "note", shell: completion.shell, rcAppended }
 }
 
-function version(command) {
-  try {
-    return execFileSync(command, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
-      .trim()
-      .split("\n")[0]
-  } catch {
-    return null
-  }
-}
 
 /**
  * @param {{ repoRoot: string, entryPoint: string, stream?: NodeJS.WriteStream, env?: object, yes?: boolean,
@@ -192,7 +188,7 @@ export async function setup({ repoRoot, entryPoint, stream = process.stdout, env
 
   // Tab completion, installed for the shell in $SHELL where that shell loads
   // it from, and then proven in a new shell (completionStep).
-  await completionStep({ repoRoot, pin: identity.commit, version: tool(repoRoot).version, stream, env, yes, askRc: true, input, verify })
+  const completion = await completionStep({ repoRoot, pin: identity.commit, version: tool(repoRoot).version, stream, env, yes, askRc: true, input, verify })
   out()
 
   out("Try it on a plugin you have checked out:")
@@ -200,5 +196,10 @@ export async function setup({ repoRoot, entryPoint, stream = process.stdout, env
   fix("omakit submit <plugin-repo> --category Widgets --tags bar,quickshell", 0)
   out()
   for (const line of wrap("It prints the issue title and body. It never posts anything.", {}, c)) out(line)
+  if (completion.state === "error") {
+    out()
+    for (const line of verdict("fail", "NOT READY", `tab completion was not installed (${completion.error}); everything else is in place.`, c)) out(line)
+    return { ok: false }
+  }
   return { ok: true }
 }

package/tools/marketplace/tree.mjs

@@ -7,7 +7,7 @@
 import { execFileSync } from "node:child_process"
 
 function git(dir, args, encoding = "utf8") {
-  return execFileSync("git", ["-C", dir, ...args], {
+  return execFileSync("git", ["-C", dir, ...args], { timeout: 60_000,
     encoding,
     maxBuffer: 256 * 1024 * 1024,
     stdio: ["ignore", "pipe", "pipe"],

package/tools/marketplace/upgrade.mjs

@@ -126,7 +126,7 @@ function installedVersion(repoRoot) {
 /** Where the `npm` on PATH installs global packages, or null when there is no npm. */
 function npmGlobalRoot() {
   try {
-    return resolve(execFileSync("npm", ["root", "--global"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim())
+    return resolve(execFileSync("npm", ["root", "--global"], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim())
   } catch {
     return null
   }
@@ -143,14 +143,14 @@ export const NPM_PREFIX_ARGS = Object.freeze(["prefix", "--global"])
 /** The `npm` on PATH's global prefix, or null when there is no npm. */
 export function npmGlobalPrefix() {
   try {
-    return resolve(execFileSync("npm", [...NPM_PREFIX_ARGS], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim())
+    return resolve(execFileSync("npm", [...NPM_PREFIX_ARGS], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim())
   } catch {
     return null
   }
 }
 
 function git(dir, args) {
-  return execFileSync("git", ["-C", dir, ...args], {
+  return execFileSync("git", ["-C", dir, ...args], { timeout: 300_000,
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
   }).trim()
@@ -190,7 +190,7 @@ function refreshCompletionWith(root, stream) {
   // past eighty columns in a sentence (measured in CI: 109).
   if (!existsSync(entryPoint)) return { ran: false, reason: "this install has no bin/omakit under its root" }
   try {
-    const out = execFileSync(process.execPath, [entryPoint, ...COMPLETION_REFRESH_ARGS], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+    const out = execFileSync(process.execPath, [entryPoint, ...COMPLETION_REFRESH_ARGS], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
     stream.write(out)
     return { ran: true, ok: true }
   } catch (error) {
@@ -348,7 +348,7 @@ async function upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, ref
   }
   spinner.phase(`npm install --global ${spec}`)
   try {
-    execFileSync("npm", [...NPM_UPGRADE_ARGS, spec], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+    execFileSync("npm", [...NPM_UPGRADE_ARGS, spec], { timeout: 600_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
   } catch (error) {
     spinner.done()
     const reason = String(error?.stderr || "").trim().split("\n").filter((line) => /^npm (?:error|ERR!)/.test(line)).pop() || "npm install failed"

package/tools/marketplace/usage.mjs

@@ -1,4 +1,7 @@
-// The help text, as data rather than one painted string.
+// The help text, as data rather than one painted string, in the order the
+// README tells it: build (add), check (inspect, verify, submit), track
+// (watch), prove (lab), then the rest; completion and COMMANDS.md follow
+// the same list.
 //
 // Kept as structure so it can be coloured without pattern-matching a paragraph,
 // and so the same words serve a terminal and a pipe. A signature is coloured by
@@ -10,44 +13,60 @@ import { MARKETPLACE_PIN } from "./pin.mjs"
 import { colourEnabled, paintProse, STEP, styler, withOutputStream, wrap } from "./style.mjs"
 
 /**
- * "Safe" means one thing, everywhere it appears: this runs on your own
- * machine, posts nothing, opens no issue and spends nobody's attention. It is
- * never a claim about the security of a plugin or a submission; the baseline's
- * outcome is reported verbatim and is never restated as one.
+ * The line under the wordmark says what the tool is for, and only that: the
+ * plumbing the review blocks on, shipped as tested files a plugin owns. It is
+ * never a claim about the security of a plugin or a submission; the
+ * baseline's outcome is reported verbatim and is never restated as one, and
+ * a block is described by what it does and what was measured.
  */
-export const TAGLINE = "the safe place to find out"
+export const TAGLINE = "the plumbing plugin reviews block most, built and tested once"
 
 /** The shells `omakit setup` installs tab completion for; completion.mjs holds the scripts. */
 export const COMPLETION_SHELLS = Object.freeze(["bash", "zsh", "fish"])
 
 export const COMMANDS = Object.freeze([
   {
-    signature: "omakit setup [--yes] [--completion]",
+    signature: "omakit add <block> [<plugin-dir>] [--update] [--json]",
     lines: [
-      "First run, in one command: check the environment, fetch the pinned",
-      "marketplace checkout, install tab completion and prove it in a new shell,",
-      "and say what to try first. Idempotent. When a new shell has no completion",
-      "loader it asks once before adding one guarded block to the rc file; --yes",
-      "answers for an agent. --completion is that step alone, never the question.",
+      "Copy a block into the plugin's omakit/ directory: `run` (Run.qml and the",
+      "supervisor it starts by absolute path) or `store` (Store.qml and its",
+      "helper, with run, which it uses), and NOTICE, each file with a header",
+      "naming the block, its version, the licence, the omakit commit and the",
+      "body's sha256. Writes those files and nothing else, never over a file",
+      "that is already there without --update, and never over a copy whose",
+      "body is not one omakit shipped: a modified block is the author's, and",
+      "the command says so and stops. docs/BLOCKS.md is the contract; each of",
+      "its lines cites how many review comments in one week asked for it (M13).",
     ],
   },
   {
-    signature: "omakit pin",
+    signature: [
+      "omakit inspect <target> [--full] [--json] [--out <file>] [--offline]",
+      "                        [--allow-dirty]",
+    ],
     lines: [
-      "Fetch or verify the pinned marketplace checkout in the user cache:",
-      "$XDG_CACHE_HOME/omakit/marketplace, or ~/.cache/omakit/marketplace.",
-      `Read-only, exact commit ${MARKETPLACE_PIN.commit}.`,
+      "What a plugin tree does, as observations: every process with its argv,",
+      "every host with its timeout and size-cap flags, every write with whether",
+      "it falls under a directory the plugin controls, every timer with its",
+      "interval, and the capabilities the marketplace baseline records. Below",
+      "the facts, the review classes the marketplace's human review raised,",
+      "each with its measured share, only where the tree shows the class.",
+      "Regular expressions over QML and shell, labelled observed; runs nothing",
+      "from the tree, decides nothing, exits 0 with a report and 2 when the",
+      "target cannot be read. The report opens with a size score, the share",
+      "of the tree's function lines in functions over the measured size,",
+      "placed among the listed trees' shares, 10.00 with no long function;",
+      "then what needs attention: functions over the measured size, longest",
+      "first, then the review classes by measured share, five sites each;",
+      "--full is every site with every qualifier; --json prints the document.",
     ],
   },
   {
-    signature: [
-      "omakit audit <plugin-id-or-dir> [--drift] [--json] [--out <file>] [--offline]",
-      "omakit audit [--drift] [--json] [--out <file>] [--offline]",
-    ],
+    signature: "omakit verify <target> [--allow-dirty] [--json] [--out <file>]",
     lines: [
-      "Compare every installed third-party plugin's running commit with the",
-      "exact commits the marketplace records as validated. Read-only. --drift",
-      "shows only rows that are not validated; --offline reads the pin.",
+      "The official marketplace security baseline over the local Git transport,",
+      "reported verbatim beside the pin identity. A report for a person; --json",
+      "prints the document itself, and --out writes it to a file.",
     ],
   },
   {
@@ -84,48 +103,63 @@ export const COMMANDS = Object.freeze([
     ],
   },
   {
-    signature: "omakit verify <target> [--allow-dirty] [--json] [--out <file>]",
+    signature: [
+      "omakit lab prove <suite> [--runs <n>] [--json] [--out <file>]",
+      "omakit lab inspect [--verify] [--json] [--out <file>]",
+      "omakit lab setup [--from <file>] [--toolchain <dir>] [--plugins] [--yes]",
+      "omakit lab prune [--keep-iso] [--records] [--yes] [--json]",
+    ],
     lines: [
-      "The official marketplace security baseline over the local Git transport,",
-      "reported verbatim beside the pin identity. A report for a person; --json",
-      "prints the document itself, and --out writes it to a file.",
+      "Prove a suite in a disposable Omarchy guest, never on the desktop: the",
+      "pinned 4.0.3 release booted from an immutable verified base, a fresh",
+      "overlay per run, the guest's installed omarchy package read and printed",
+      "before the suite, the document written with that identity. `prove` boots",
+      "nothing until the base, the host and the suite's files are there, and",
+      "names what is missing, what it takes, and the one command; it fetches",
+      "nothing. `inspect` is read-only: the pinned release, its exact size,",
+      "digest and signer, what is on disk and verified, what the host lacks.",
+      "`setup` is the only path that fetches bytes: one consent naming the",
+      "exact size and destination (--yes for an agent), a resumable GET of",
+      "the pinned URL or a copy of --from, verified against the pinned SHA-256",
+      "and the Omarchy signature before anything boots it, then one base built",
+      "by the pinned omarchy-iso toolchain, whose checkout --toolchain records",
+      "and which setup never fetches. `prune` frees the lab cache and says how",
+      "much. docs/LAB.md is the contract. Suites: run, store, weigh,",
+      "weigh-evidence.",
     ],
   },
   {
     signature: [
-      "omakit inspect <target> [--full] [--json] [--out <file>] [--offline]",
-      "                        [--allow-dirty]",
+      "omakit audit <plugin-id-or-dir> [--drift] [--json] [--out <file>] [--offline]",
+      "omakit audit [--drift] [--json] [--out <file>] [--offline]",
     ],
     lines: [
-      "What a plugin tree does, as observations: every process with its argv,",
-      "every host with its timeout and size-cap flags, every write with whether",
-      "it falls under a directory the plugin controls, every timer with its",
-      "interval, and the capabilities the marketplace baseline records. Below",
-      "the facts, the review classes the marketplace's human review raised,",
-      "each with its measured share, only where the tree shows the class.",
-      "Regular expressions over QML and shell, labelled observed; runs nothing",
-      "from the tree, decides nothing, exits 0 with a report and 2 when the",
-      "target cannot be read. The report opens with a size score, the share",
-      "of the tree's function lines in functions over the measured size,",
-      "placed among the listed trees' shares, 10.00 with no long function;",
-      "then what needs attention: functions over the measured size, longest",
-      "first, then the review classes by measured share, five sites each;",
-      "--full is every site with every qualifier; --json prints the document.",
+      "Compare every installed third-party plugin's running commit with the",
+      "exact commits the marketplace records as validated. Read-only. --drift",
+      "shows only rows that are not validated; --offline reads the pin.",
     ],
   },
   {
-    signature: "omakit help --agent",
-    lines: [
-      "The operating instructions for a coding agent, printed from skills/, so an",
-      "agent can read the contract out of the tool instead of the repository.",
+    signature: [
+      "omakit weigh <plugin-id-or-dir> [--runs <n>] [--window <s>] [--settle <s>]",
+      "                    [--yes] [--json] [--out <file>]",
+      "omakit weigh --all",
+      "omakit weigh --list [--json]",
     ],
-  },
-  {
-    signature: "omakit upgrade [--dry-run]",
     lines: [
-      "Update omakit through the installer that made it: npm, at the exact",
-      "version the registry names, or a fast-forward of a clone. Refuses",
-      "anything else, and never moves the marketplace pin.",
+      "What a plugin weighs on the shell, measured: the shell is restarted",
+      "without it and with it, several runs, and the difference is the weight,",
+      "with the baseline's own spread as the noise floor; memory is printed as",
+      "the shell's own startup variance, CPU and child processes as the weight.",
+      "The one command that changes your machine: it edits shell.json for the",
+      "duration, backs it up first, restores it on every exit path, and asks",
+      "before the first restart (--yes answers for you): about a minute per",
+      "restart, six restarts for one plugin at three runs. --all weighs every",
+      "enabled third-party plugin and is sized for a lab machine, not a working",
+      "desktop. Writes the document to --out, by default",
+      "$XDG_STATE_HOME/omakit/weigh/<date>.json, and ends with the sentence",
+      "for the plugin's README. --list is read-only: every installed plugin",
+      "and when it was last weighed, unweighed enabled plugins first.",
     ],
   },
   {
@@ -137,6 +171,32 @@ export const COMMANDS = Object.freeze([
       "checks at most once daily; DISABLE_UPDATE_NOTIFIER=1 disables notices.",
     ],
   },
+  {
+    signature: "omakit setup [--yes] [--completion]",
+    lines: [
+      "First run, in one command: check the environment, fetch the pinned",
+      "marketplace checkout, install tab completion and prove it in a new shell,",
+      "and say what to try first. Idempotent. When a new shell has no completion",
+      "loader it asks once before adding one guarded block to the rc file; --yes",
+      "answers for an agent. --completion is that step alone, never the question.",
+    ],
+  },
+  {
+    signature: "omakit pin",
+    lines: [
+      "Fetch or verify the pinned marketplace checkout in the user cache:",
+      "$XDG_CACHE_HOME/omakit/marketplace, or ~/.cache/omakit/marketplace.",
+      `Read-only, exact commit ${MARKETPLACE_PIN.commit}.`,
+    ],
+  },
+  {
+    signature: "omakit upgrade [--dry-run]",
+    lines: [
+      "Update omakit through the installer that made it: npm, at the exact",
+      "version the registry names, or a fast-forward of a clone. Refuses",
+      "anything else, and never moves the marketplace pin.",
+    ],
+  },
   {
     signature: "omakit parity [--count <n>] [--offset <n>] [--out <file>]",
     lines: [
@@ -145,26 +205,10 @@ export const COMMANDS = Object.freeze([
     ],
   },
   {
-    signature: [
-      "omakit weigh <plugin-id-or-dir> [--runs <n>] [--window <s>] [--settle <s>]",
-      "                    [--yes] [--json] [--out <file>]",
-      "omakit weigh --all",
-      "omakit weigh --list [--json]",
-    ],
+    signature: "omakit help --agent",
     lines: [
-      "What a plugin weighs on the shell, measured: the shell is restarted",
-      "without it and with it, several runs, and the difference is the weight,",
-      "with the baseline's own spread as the noise floor; memory is printed as",
-      "the shell's own startup variance, CPU and child processes as the weight.",
-      "The one command that changes your machine: it edits shell.json for the",
-      "duration, backs it up first, restores it on every exit path, and asks",
-      "before the first restart (--yes answers for you): about a minute per",
-      "restart, six restarts for one plugin at three runs. --all weighs every",
-      "enabled third-party plugin and is sized for a lab machine, not a working",
-      "desktop. Writes the document to --out, by default",
-      "$XDG_STATE_HOME/omakit/weigh/<date>.json, and ends with the sentence",
-      "for the plugin's README. --list is read-only: every installed plugin",
-      "and when it was last weighed, unweighed enabled plugins first.",
+      "The operating instructions for a coding agent, printed from skills/, so an",
+      "agent can read the contract out of the tool instead of the repository.",
     ],
   },
 ])