omakit 0.4.1 → 0.4.3

package/README.md

@@ -1,126 +1,66 @@
 <p align="center">
-  <img src="docs/media/banner.gif" alt="omakit" width="440">
+  <img src="https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/banner.gif" alt="omakit" width="440">
 </p>
 
-The safe place to find out: everything knowable about an Omarchy Quattro plugin submission before you post it, on your own machine. Agent-first, read-only against the marketplace, posts nothing, zero dependencies.
+The marketplace validates one exact commit of your plugin. Push a fix or comment "fixed", and nothing re-runs ([M6](docs/MEASUREMENTS.md#m6-the-validated-commit-falls-behind-silently-and-that-is-the-centre-of-this-tool)). omakit runs the marketplace's own checks locally, watches your submission and posts nothing.
 
 [![Built for Omarchy: App](https://raw.githubusercontent.com/tcballard/omarchy-badges/75975e5b5bf75e7ede3764bcd2950046f7abfe2c/badges/v1/omarchy-app.svg)](https://github.com/tcballard/omarchy-badges) [![npm version](https://img.shields.io/npm/v/omakit)](https://www.npmjs.com/package/omakit) [![CI status](https://img.shields.io/github/actions/workflow/status/mtolhuys/omakit/ci.yml?branch=main)](https://github.com/mtolhuys/omakit/actions/workflows/ci.yml) [![Socket](https://socket.dev/api/badge/npm/package/omakit)](https://socket.dev/npm/package/omakit)
 
-`omakit` is a zero-dependency Node CLI that checks an Omarchy Quattro plugin submission on your machine.
-It is for a coding agent or a person submitting a plugin.
-It never posts to the marketplace or writes into a plugin tree.
-
 ## Install
 
 ```bash
-npm install --global omakit
-omakit setup
+npm i -g omakit && omakit setup
+npx skills add mtolhuys/omakit
 ```
 
-See [docs/INSTALL.md](docs/INSTALL.md) for the clone route, PATH, requirements and upgrading.
+Runs where [Node 22+](package.json) and Git run; `weigh` and `audit` need a running Omarchy shell.
 
-## Commands
+Licence: [MIT](LICENSE).
 
-| Command | What it does |
-| --- | --- |
-| [`omakit setup`](docs/COMMANDS.md) | The environment, the pin, tab completion, and what to try first. |
-| [`omakit submit <plugin-repo>`](docs/SUBMIT.md) | Every check, the issue title and body; asks for a category and tags at a terminal. |
-| [`omakit watch [<issue-url>]`](docs/VALIDATION_WATCH.md) | Pick your marketplace issues, list them, or check all with `--all`. |
-| [`omakit verify <plugin-repo>`](docs/COMMANDS.md) | The official security baseline over the local transport; `--json` for the document. |
-| [`omakit parity`](docs/COMMANDS.md) | The baseline over GitHub versus the local transport, on real listings; writes the evidence. |
-| [`omakit audit [<plugin>]`](docs/AUDIT.md) | Installed third-party commits against the exact commits the marketplace validated. |
-| [`omakit weigh <plugin>`](docs/WEIGH.md) | What a plugin weighs on the shell, measured by restarting it without and with the plugin; asks first. |
-| [`omakit doctor`](docs/COMMANDS.md) | What is installed, what is pinned, and what has moved. |
-| [`omakit pin`](docs/COMMANDS.md) | What setup does for the pin, on its own. |
-| [`omakit upgrade`](docs/COMMANDS.md) | Updates omakit through its own installer: npm, or a fast-forward. |
-| [`omakit help --agent`](docs/COMMANDS.md) | The operating instructions, for the agent running this. |
-
-Normal terminal use also checks for a newer npm release at most once daily
-and shows the upgrade command. It installs nothing automatically; scripts
-and JSON stay quiet. `DISABLE_UPDATE_NOTIFIER=1` disables the notice, and
-`omakit doctor` checks explicitly. [Update behaviour](docs/INSTALL.md#updating).
-
-Terminal help and reports adapt to the available width, up to 120 columns
-for readability. Narrow windows wrap sooner; pipes and text files keep the
-stable eighty-column layout. JSON and exact issue bodies remain intact.
-
-### `submit`
+## `omakit submit <plugin-repo>`
 
-```bash
-omakit submit <plugin-repo> --category Widgets --tags bar,quickshell
-```
+![submit refusing a fixture plugin before any issue is posted](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/submit.gif)
 
-It decides whether the plugin is ready, refused, or already listed; [103 issues mention agent-control files that no automated check reports](docs/MEASUREMENTS.md).
+Checks the exact commit with the marketplace's own baseline and, when ready, prints the exact issue title and body for you to paste. The GIF shows a refusal with three blocking checks and their fixes.
 
-![omakit submit refusing a plugin with no license, a README that never says how to uninstall, and a reserved plugin id](docs/media/submit.gif)
+## `omakit watch --all`
 
-Read more: [docs/SUBMIT.md](docs/SUBMIT.md).
+![watch counts and two current issues, including human discussion](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/watch-all.gif)
 
-### `watch`
+Checks your submission commits and names the action that re-runs stale validation: edit the issue body. The GIF shows five CURRENT issues in the counts and the first two issues with a discussion; CURRENT means matching commits, not approval.
 
-```bash
-omakit watch <submission-issue-url>
-omakit watch --all
-omakit watch --list
-omakit watch                 # choose one or several issues at a terminal
-```
+## `omakit audit`
 
-It decides whether the marketplace validated the plugin's current commit; [73% of parked submissions have a HEAD the marketplace never saw](docs/MEASUREMENTS.md).
+![audit keeping drift rows and the DRIFT summary visible together](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/audit.gif)
 
-Account-wide discovery uses your signed-in `gh` account and reads your open marketplace issues. `--user <login>` reads another public account. Batch output includes baseline results, labels and the latest human discussion; `current` compares commits and does not imply approval or publication. Each command takes one snapshot and posts nothing.
+Compares your installed plugin commits with the marketplace's validated commits. The GIF shows drift rows first: on the author's desktop, 9 of 18 audited plugins ran commits the marketplace never validated.
 
-![omakit watch reporting that a validated commit has fallen behind](docs/media/watch.gif)
+## `omakit inspect <plugin-dir>`
 
-Read more: [docs/VALIDATION_WATCH.md](docs/VALIDATION_WATCH.md).
+![inspect showing a size score and the two review classes one fixture shows](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/inspect.gif)
 
-### `weigh`
+Reads a plugin's tree and prints what needs attention, biggest first: a size score (10 minus the mean rank of its functions among functions in listed plugins, [M12](docs/MEASUREMENTS.md#m12-how-long-a-plugins-functions-are-in-listed-trees)), the functions over what 90 of 100 listed functions stay under, then each review class the tree shows with the class's measured share of review findings ([M11](docs/MEASUREMENTS.md#m11-what-the-human-review-raises-by-class)) and up to five sites. No verdict, nothing run from the tree; `--full` is every site, `--json` the document. Over 18 listed plugins read at their validated commits, the extraction counted 515 process sites (57 QML `Process` blocks, 458 shell lines), 17 hosts, 63 writes and 40 timers, left 15 rows it could not resolve, and printed 73 pattern rows across 17 of the 18 ([record](docs/evidence/inspect/2026-09-15-listed-sample.json)).
 
-```bash
-omakit weigh <plugin-id-or-dir>
-```
-
-It measures what a plugin weighs on the shell, CPU and child processes, against a baseline taken the same minute; [in the lab, a 180 ms timer fixture measured 2.73% CPU above a 0.13% floor](docs/MEASUREMENTS.md).
-
-```text
-Weighs no CPU above the floor (0.13%) and runs 2 child processes using 8.2 MB and 0.1% CPU, on Omarchy 4.0.0.alpha, measured with omakit weigh on 2026-09-14
-```
+## `omakit weigh <plugin>`
 
-It restarts your shell and asks first. Memory is a shell fact; CPU and child processes are the weight.
+![completed three-run desktop weighing with baseline samples and the noise floor](https://raw.githubusercontent.com/mtolhuys/omakit/main/docs/media/weigh.gif)
 
-Read more: [docs/WEIGH.md](docs/WEIGH.md).
+Measures the shell with and without your plugin, reading Pss and CPU. The GIF shows three completed runs on the author's desktop, with baseline and plugin samples and a 0.33% CPU floor ([method](docs/WEIGH.md)).
 
 ## Evidence, not claims
 
-| Claim | Proof |
+| Measurement | Evidence |
 | --- | --- |
-| The local transport produces the marketplace's own result | 30 of 30 identical, [docs/evidence/parity/](docs/evidence/parity/) |
-| A local run touches no network | run inside `unshare -rn`, [docs/evidence/offline/](docs/evidence/offline/) |
-| The generated body is well formed | the marketplace's own parser, `tests/unit/issue.test.mjs` |
-| Nothing writes to the marketplace | `tests/unit/read-only.test.mjs`, over every source file |
-| No agent-control file can reach a plugin | `tests/unit/self-containment.test.mjs` |
-| `weigh` restores `shell.json` on every exit path, and runs a frozen list of Omarchy commands | `tests/unit/weigh.test.mjs` against a fake `/proc` and stub commands, `tests/unit/read-only.test.mjs` |
-| The GIFs above are real output | captures and renderer in [docs/media/](docs/media/) |
-
-Committed evidence records a digest of each side rather than the results themselves, because findings about a specific third-party plugin are not this project's to publish.
+| Baseline parity | 30/30 identical results, [recorded corpus](docs/evidence/parity/2026-09-12-local-vs-github-2.json), 2026-09-12 |
+| Stale validated commit | 326/519 readable comparisons stale (62.8%); 64/583 unknown, [2026-09-15 data](docs/evidence/staleness/2026-09-15.json) |
+| Registry churn | 4,201/4,293 registry-only commits in 30 days, 2026-09-13, [M7](docs/MEASUREMENTS.md#m7-the-registry-moves-by-the-hour-the-code-and-the-rules-move-by-the-week) |
+| GIFs are recorded output | 6 GIFs with [captures and scenes](docs/media/README.md) |
+| Posts nothing | 0 marketplace writes, [M10](docs/MEASUREMENTS.md#m10-readme-evidence-and-command-captures) |
+| Zero dependencies | 0 runtime and 0 development dependencies, counted in [package.json](package.json) |
 
 ## Documentation
 
-| Document | For |
-| --- | --- |
-| [docs/INSTALL.md](docs/INSTALL.md) | install details, PATH, requirements, upgrading, and what Socket reports and why |
-| [docs/HOW.md](docs/HOW.md) | what omakit is doing, why it uses Node, the baseline and check labels |
-| [docs/COMMANDS.md](docs/COMMANDS.md) | command details, authentication and network behaviour |
-| [docs/AUDIT.md](docs/AUDIT.md) | installed plugin drift against marketplace-validated commits, with JSON origins |
-| [docs/SUBMIT.md](docs/SUBMIT.md) | every check and what it decides |
-| [docs/WEIGH.md](docs/WEIGH.md) | what `weigh` measures, the noise floor, the `shell.json` mutation and its restore, and the JSON contract |
-| [docs/VALIDATION_WATCH.md](docs/VALIDATION_WATCH.md) | the validation watch: what the marketplace validated, and what moves it |
-| [docs/MEASUREMENTS.md](docs/MEASUREMENTS.md) | every number, its method and its limits |
-| [docs/UPSTREAM_CONTRACT.md](docs/UPSTREAM_CONTRACT.md) | the seam, the pin, the boundaries |
-| [docs/MARKETPLACE.md](docs/MARKETPLACE.md) | who this actually helps |
-| [docs/PALETTE.md](docs/PALETTE.md) | every installed Omarchy theme measured, and which palette index each role gets |
-| [docs/TUI.md](docs/TUI.md) | what the terminal shows, and why it looks that way |
-| [AGENTS.md](AGENTS.md) | changing this repository |
-
-MIT. Derived work built on public data from
-`omacom/omarchy-plugin-marketplace`; not affiliated with or endorsed by that
-project.
+- Using: [install](docs/INSTALL.md), [commands](docs/COMMANDS.md), [audience](docs/MARKETPLACE.md).
+- Checks and measurements: [submit](docs/SUBMIT.md), [inspect](docs/INSPECT.md), [watch](docs/VALIDATION_WATCH.md), [audit](docs/AUDIT.md), [evidence](docs/MEASUREMENTS.md).
+- Method docs: [how](docs/HOW.md), [weigh](docs/WEIGH.md), [upstream contract](docs/UPSTREAM_CONTRACT.md), [palette](docs/PALETTE.md), [terminal](docs/TUI.md).
+- Contributing: [repository rules](AGENTS.md), [releasing](docs/RELEASING.md), [media](docs/media/README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "The safe place to find out: everything knowable about an Omarchy Quattro plugin submission before you post it, on your own machine. Agent-first, read-only against the marketplace, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/skills/omarchy-plugin-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: omarchy-plugin-check
-description: Check an Omarchy Quattro plugin while building or changing it, before committing or pushing. Use whenever you create, edit, refactor or test an Omarchy plugin, when asked whether a plugin is marketplace-ready, or before any push to its default branch. Runs the marketplace's own security baseline and submission checks locally, read-only, and reports what the marketplace would refuse.
+description: Check an Omarchy Quattro plugin while building or changing it, before committing or pushing. Use whenever you create, edit, refactor or test an Omarchy plugin, when asked whether a plugin is marketplace-ready, or before any push to its default branch. Runs the marketplace's own security baseline and submission checks locally, read-only, reports what the marketplace would refuse, and lists what the tree does (processes, hosts, writes, timers) as observations beside the review classes a human reviewer raises most.
 ---
 
 # Checking a plugin while you build it
@@ -31,6 +31,62 @@ editorial choice about where the plugin belongs.
 needs the network and reads the listed ids from the pin. For the real
 submission, drop it, and use `skills/omarchy-plugin-submit/SKILL.md`.
 
+## Read what the tree does before a human does
+
+After the two commands above pass, and again whenever you add or change a
+`Process`, a `curl`, a `FileView`, a shell script or a `Timer`, run:
+
+```bash
+omakit inspect <path-to-the-plugin-repo> --json
+```
+
+`inspect` lists what the tree shows, in the order a reviewer reads it: every
+process with its argv and whether a deadline is observed for it, every host
+with its timeout and size-cap flags, every write with whether its path falls
+under a directory the plugin controls, every timer with its interval, and the
+baseline's capabilities. Below the facts, `patterns` holds one entry per
+review class the marketplace's human review has raised, only where the tree
+shows the class's precondition (a process with no deadline, a collector with
+no cap, a write under `/tmp`, `curl` without `-q`), with the class's measured
+share of review findings (`share`, from M11 of `docs/MEASUREMENTS.md`).
+`lookedFor` names the classes whose precondition was not observed.
+`size.over` lists the functions longer, more branched or deeper than 90 of
+100 functions in listed trees (the thresholds are in `size.thresholds`,
+from M12), longest first, each with its `percentile` among them, and
+`size.score` is 10 minus the mean percentile of every function in the
+tree. When the owner asks for simpler code, start with the top of
+`size.over`, and read the score before and after as the measure of the
+change; it is a position among listed plugins, not a grade, so never tell
+the owner a score is good or bad, only that it moved. Read
+the document, not the report: the report a person sees lists at most five
+sites per class and drops classes under five percent, `--full` prints every
+site, and `--json` carries all of it either way.
+
+How to read "observed". Every row is what regular expressions found in the
+text at `file:line`, never a runtime fact and never a verdict: `deadline
+observed` means a killing `Timer`, a `timeout` in argv or a destruction
+handler is in the file; `no cap observed` means the argv shows none of
+`head -c`, `--max-filesize` or `timeout`; `observed nothing of this kind`
+means the extraction found nothing, not that the tree is clean. A `▒ ?` row
+(`argvForm: "computed"`, `argv: null`) is a command the text does not show
+as a literal; do not guess it for the owner, read the file. `notVisible`
+names what the method cannot see (commands built at run time, values from
+variables or config, components outside the tree), and a tree that uses
+those has facts `inspect` did not list.
+
+What to do with a pattern row. It is not a marketplace rule and not a
+finding: the marketplace's automated baseline blocks, a maintainer reviews,
+and `inspect` only reports that the tree shows something reviewers have
+raised in about N of every 100 findings. Show the owner the row and the
+requirement in the reviewer's own terms from the M11 table (an absolute
+deadline, producer-side bounds, a private 0700 directory, `curl -q`, no
+secret in argv), and let the owner decide; never describe the row as a
+requirement the marketplace enforces, and never say "safe" or "clean" about
+a tree with no rows. The `supply-chain` row is the baseline's own finding
+restated with its evidence sites; the baseline result is what decides there.
+Exit status is 0 whenever a report was produced, so do not read the exit
+code as pass or fail; 2 means the target could not be read.
+
 ## If omakit is not installed
 
 ```bash
@@ -92,8 +148,8 @@ own words, and so should you.
 
 The marketplace validates the pushed default-branch HEAD, not whatever is
 checked out locally. Run the check on the commit that will be pushed, then
-commit and push before the real submission. Of the 464 submissions parked in
-their author's court, 73% have a HEAD the marketplace never saw; that is the
+commit and push before the real submission. On 2026-09-15, 326/519 readable author-fixes
+comparisons were stale, with 64 of 583 issues unknown; that is the
 round this loop is meant to prevent.
 
 ## When the plugin is ready

package/skills/omarchy-plugin-submit/SKILL.md

@@ -133,8 +133,8 @@ strip files from their tree on your own.
 
 **`submission.validation-commit`.** The marketplace validates the commit it
 resolves when the issue is opened or edited, which is the pushed default-branch
-HEAD, not whatever is checked out locally. Push first, then submit. 73% of submissions
-parked in their author's court have a HEAD the marketplace never saw.
+HEAD, not whatever is checked out locally. Push first, then submit. On 2026-09-15, 326/519 readable author-fixes comparisons were stale
+(62.8%), with 64 of 583 issues unknown.
 
 ## What the baseline result means
 

package/skills/omarchy-plugin-validation-watch/SKILL.md

@@ -18,10 +18,10 @@ the issue body**.
   submissions.
 
 So pushing a fix does nothing, and commenting "fixed in `abc123`" does nothing.
-Both feel like progress. Neither is. This is the single most common reason a
-submission sits still: of the 464 submissions parked in their author's court, 73%
-have a default-branch HEAD the marketplace never saw, and 82% of the authors whose
-push came after a review comment had also commented: engaged, and stuck.
+Both feel like progress. Neither is. The full author-fixes queue was measured on 2026-09-15: 326/519 readable
+comparisons were stale (62.8%), with 64 of 583 issues unknown. The older
+2026-09-12 sample found 68/93 readable issues stale (73.1%); that rate was
+not a measurement of all 464 issues in the queue.
 
 ## Check it
 

package/tools/inspect/contract.mjs

@@ -0,0 +1,245 @@
+// The JSON contract of docs/INSPECT.md, executable. `validateInspectDocument()`
+// returns every way a document departs from it, as sentences, and an empty
+// list when it does not. tests/unit/inspect.test.mjs holds every produced
+// document to it, so the prose and the code cannot drift apart unnoticed.
+//
+// Run as a program: `node tools/inspect/contract.mjs <document.json>` prints
+// the problems and exits 1 on any.
+
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+
+const ARGV_FORMS = new Set(["array", "string", "computed"])
+const DEADLINE_VIA = new Set(["timer-kill", "timeout-argv", "destruction", null])
+const COLLECTORS = new Set(["StdioCollector", "SplitParser", "none", "unknown"])
+const CONTROLLED = new Set(["observed", "not-observed", "unknown"])
+const DECLARED_IN = new Set(["qml", "shell"])
+const FILE_KINDS = ["qml", "js", "shell", "python", "other"]
+
+const isString = (value) => typeof value === "string"
+const isBool = (value) => typeof value === "boolean"
+const isInt = (value) => Number.isInteger(value)
+const nullOr = (test) => (value) => value === null || test(value)
+
+function site(value, at, problems) {
+  if (!value || typeof value !== "object") {
+    problems.push(`${at} is not a site`)
+    return
+  }
+  if (!isString(value.file)) problems.push(`${at}.file is not a string`)
+  if (!isInt(value.line) || value.line < 1) problems.push(`${at}.line is not a positive integer`)
+}
+
+function processRow(row, at, problems) {
+  site(row, at, problems)
+  if (!DECLARED_IN.has(row.declaredIn)) problems.push(`${at}.declaredIn is neither qml nor shell`)
+  if (!nullOr(isString)(row.id)) problems.push(`${at}.id is neither a string nor null`)
+  if (!ARGV_FORMS.has(row.argvForm)) problems.push(`${at}.argvForm is not array, string or computed`)
+  if (row.argvForm === "computed") {
+    if (row.argv !== null) problems.push(`${at}.argv is not null for a computed command`)
+    if (!isString(row.commandText)) problems.push(`${at}.commandText is not the expression text of a computed command`)
+  } else if (!Array.isArray(row.argv) || row.argv.some((word) => !isString(word))) problems.push(`${at}.argv is not a list of strings`)
+  if (!Array.isArray(row.expressions) || row.expressions.some((entry) => !isInt(entry?.index) || !isString(entry?.text))) problems.push(`${at}.expressions is not a list of { index, text }`)
+  if (row.argvForm === "array" && Array.isArray(row.argv)) {
+    for (const entry of row.expressions || []) if (row.argv[entry.index] !== entry.text) problems.push(`${at}.expressions[${entry.index}] does not name the argv element it stands for`)
+  }
+  for (const key of ["running", "detached", "shellWrapper"]) if (!isBool(row[key])) problems.push(`${at}.${key} is not a boolean`)
+  const deadline = row.deadline || {}
+  if (!isBool(deadline.observed)) problems.push(`${at}.deadline.observed is not a boolean`)
+  if (!DEADLINE_VIA.has(deadline.via)) problems.push(`${at}.deadline.via is not timer-kill, timeout-argv, destruction or null`)
+  if (deadline.observed !== (deadline.via !== null)) problems.push(`${at}.deadline.observed disagrees with deadline.via`)
+  if (!nullOr(isInt)(deadline.ms)) problems.push(`${at}.deadline.ms is neither an integer nor null`)
+  const output = row.output || {}
+  if (!COLLECTORS.has(output.collector)) problems.push(`${at}.output.collector is not StdioCollector, SplitParser, none or unknown`)
+  if (!isBool(output.capObserved)) problems.push(`${at}.output.capObserved is not a boolean`)
+  if (!nullOr(isString)(output.via)) problems.push(`${at}.output.via is neither a string nor null`)
+  if (output.capObserved !== (output.via !== null)) problems.push(`${at}.output.capObserved disagrees with output.via`)
+  if (row.pipedFrom !== null && (!isInt(row.pipedFrom?.line) || !isString(row.pipedFrom?.argv0))) problems.push(`${at}.pipedFrom is neither null nor { line, argv0 }`)
+}
+
+function host(row, at, problems) {
+  site(row, at, problems)
+  if (!isString(row.host) || !row.host) problems.push(`${at}.host is not a host name`)
+  if (row.scheme !== "http" && row.scheme !== "https") problems.push(`${at}.scheme is neither http nor https`)
+  if (!nullOr(isString)(row.tool)) problems.push(`${at}.tool is neither a string nor null`)
+  for (const key of ["timeout", "sizeCap"]) {
+    const flag = row[key] || {}
+    if (!isBool(flag.observed)) problems.push(`${at}.${key}.observed is not a boolean`)
+    if (!nullOr(isString)(flag.via)) problems.push(`${at}.${key}.via is neither a string nor null`)
+    if (flag.observed !== (flag.via !== null)) problems.push(`${at}.${key}.observed disagrees with ${key}.via`)
+  }
+  if (!Array.isArray(row.flags) || row.flags.some((flag) => !isString(flag))) problems.push(`${at}.flags is not a list of strings`)
+  if (!isBool(row.privateAddress)) problems.push(`${at}.privateAddress is not a boolean`)
+}
+
+function write(row, at, problems) {
+  site(row, at, problems)
+  if (!isString(row.path)) problems.push(`${at}.path is not a string`)
+  if (!nullOr(isString)(row.canonicalPath)) problems.push(`${at}.canonicalPath is neither a string nor null`)
+  if (!isString(row.via)) problems.push(`${at}.via is not a string`)
+  if (!CONTROLLED.has(row.controlledDirectory)) problems.push(`${at}.controlledDirectory is not observed, not-observed or unknown`)
+  if ((row.controlledDirectory === "observed") !== isString(row.controlledBy)) problems.push(`${at}.controlledBy names a directory exactly when controlledDirectory is observed`)
+  if (row.canonicalPath === null && row.controlledDirectory !== "unknown") problems.push(`${at}.controlledDirectory is decided for a path that could not be read`)
+  if (!isBool(row.temp)) problems.push(`${at}.temp is not a boolean`)
+  if (!nullOr(isString)(row.mode)) problems.push(`${at}.mode is neither a string nor null`)
+}
+
+function fn(row, at, problems) {
+  site(row, at, problems)
+  if (!isString(row.name) || !row.name) problems.push(`${at}.name is not a name`)
+  if (row.kind !== "function" && row.kind !== "handler") problems.push(`${at}.kind is neither function nor handler`)
+  for (const key of ["lines", "depth", "branches"]) if (!isInt(row[key]) || row[key] < 0) problems.push(`${at}.${key} is not a count`)
+  if (isInt(row.lines) && row.lines < 1) problems.push(`${at}.lines is under one`)
+  if (typeof row.percentile !== "number" || row.percentile < 0 || row.percentile > 100) problems.push(`${at}.percentile is not a rank between 0 and 100`)
+}
+
+function timer(row, at, problems) {
+  site(row, at, problems)
+  if (!nullOr(isString)(row.id)) problems.push(`${at}.id is neither a string nor null`)
+  if (!nullOr(isInt)(row.intervalMs)) problems.push(`${at}.intervalMs is neither an integer nor null`)
+  if (!nullOr(isString)(row.intervalText)) problems.push(`${at}.intervalText is neither a string nor null`)
+  if (row.intervalMs !== null && row.intervalText !== null) problems.push(`${at} has both an interval and an interval expression`)
+  for (const key of ["repeat", "running", "triggeredOnStart"]) if (!nullOr(isBool)(row[key])) problems.push(`${at}.${key} is neither a boolean nor null`)
+  if (!nullOr(isString)(row.startedBy)) problems.push(`${at}.startedBy is neither a string nor null`)
+}
+
+/**
+ * @param {object} document
+ * @param {{ patternIds?: string[], notVisible?: string[] }} [known] the ids
+ *   patterns.mjs defines and the fixed blind-spot list, when the caller has
+ *   them, so a pattern id the code does not define and a rewritten blind
+ *   spot are both problems.
+ * @returns {string[]} problems; empty when the document follows the contract
+ */
+export function validateInspectDocument(document, known = {}) {
+  const problems = []
+  if (!document || typeof document !== "object") return ["the document is not an object"]
+  if (!isString(document.omakit)) problems.push("omakit is not a string")
+  if (document.command !== "inspect") problems.push('command is not "inspect"')
+  if (!isString(document.method) || !/observed/.test(document.method)) problems.push("method is not the one sentence that says observed")
+  const subject = document.subject || {}
+  if (!isString(subject.dir)) problems.push("subject.dir is not a string")
+  if (!nullOr((value) => /^[0-9a-f]{40}$/.test(value))(subject.commit)) problems.push("subject.commit is neither a 40-character sha nor null")
+  if (!subject.repository || !nullOr(isString)(subject.repository.url)) problems.push("subject.repository.url is neither a string nor null")
+  const filesRead = subject.filesRead || {}
+  for (const kind of FILE_KINDS) if (!isInt(filesRead[kind]) || filesRead[kind] < 0) problems.push(`subject.filesRead.${kind} is not a count`)
+  for (const key of Object.keys(filesRead)) if (!FILE_KINDS.includes(key)) problems.push(`subject.filesRead.${key} is not a kind inspect reads`)
+
+  const observed = document.observed || {}
+  for (const [key, check] of [["processes", processRow], ["hosts", host], ["writes", write], ["timers", timer], ["functions", fn]]) {
+    if (!Array.isArray(observed[key])) {
+      problems.push(`observed.${key} is not a list`)
+      continue
+    }
+    for (const [index, row] of observed[key].entries()) check(row, `observed.${key}[${index}]`, problems)
+  }
+  const counts = document.counts || {}
+  if (!counts.processes || typeof counts.processes !== "object") problems.push("counts.processes is not the qml and shell split")
+  else {
+    for (const key of ["total", "qml", "shell"]) if (!isInt(counts.processes[key]) || counts.processes[key] < 0) problems.push(`counts.processes.${key} is not a count`)
+    if (counts.processes.total !== counts.processes.qml + counts.processes.shell) problems.push("counts.processes.total is not qml plus shell")
+    if (Array.isArray(observed.processes)) {
+      if (counts.processes.total !== observed.processes.length) problems.push("counts.processes.total is not the number of process rows")
+      if (counts.processes.qml !== observed.processes.filter((row) => row.declaredIn === "qml").length) problems.push("counts.processes.qml is not the number of qml process rows")
+    }
+  }
+  for (const key of ["hosts", "writes", "timers", "functions"]) {
+    if (!isInt(counts[key]) || counts[key] < 0) problems.push(`counts.${key} is not a count`)
+    else if (Array.isArray(observed[key]) && counts[key] !== observed[key].length) problems.push(`counts.${key} is not the number of ${key} rows`)
+  }
+  if (!isInt(counts.notResolvable) || (Array.isArray(document.notResolvable) && counts.notResolvable !== document.notResolvable.length)) problems.push("counts.notResolvable is not the number of notResolvable rows")
+  if (!Array.isArray(document.notResolvable)) problems.push("notResolvable is not a list")
+  else for (const [index, row] of document.notResolvable.entries()) {
+    site(row, `notResolvable[${index}]`, problems)
+    if (!isString(row.kind) || !isString(row.text)) problems.push(`notResolvable[${index}] lacks kind and text`)
+  }
+  // Every computed command is also a site the extraction could not read.
+  for (const row of Array.isArray(observed.processes) ? observed.processes : []) {
+    if (row.argvForm === "computed" && !(document.notResolvable || []).some((entry) => entry.kind === "command" && entry.file === row.file && entry.line === row.line)) {
+      problems.push(`observed.processes at ${row.file}:${row.line} is computed but not listed under notResolvable`)
+    }
+  }
+
+  const size = document.size
+  if (!size || typeof size !== "object") problems.push("size is missing")
+  else {
+    if (!isString(size.measurement) || !/^M\d+$/.test(size.measurement)) problems.push("size.measurement is not a measurement id")
+    for (const key of ["lines", "branches", "depth"]) if (!isInt(size.thresholds?.[key]) || size.thresholds[key] < 1) problems.push(`size.thresholds.${key} is not a count`)
+    if (!size.sample || !isInt(size.sample.trees) || !isInt(size.sample.functions)) problems.push("size.sample is not { trees, functions }")
+    const scorable = Array.isArray(observed.functions) && observed.functions.length > 0
+    if (size.score === null) {
+      if (scorable) problems.push("size.score is null for a tree with functions")
+    } else if (typeof size.score !== "number" || size.score < 0 || size.score > 10 || Math.abs(Math.round(size.score * 100) - size.score * 100) > 1e-6) problems.push("size.score is not a number from 0 to 10 with two decimals")
+    else if (!scorable) problems.push("size.score is set for a tree with no function")
+    else {
+      const expected = Math.round((10 - observed.functions.reduce((sum, row) => sum + row.percentile, 0) / observed.functions.length / 10) * 100) / 100
+      if (Math.abs(expected - size.score) > 0.011) problems.push(`size.score is ${size.score}; the mean rank of the functions says ${expected}`)
+    }
+    if (!Array.isArray(size.over)) problems.push("size.over is not a list")
+    else {
+      for (const [index, row] of size.over.entries()) {
+        fn(row, `size.over[${index}]`, problems)
+        if (size.thresholds && !(row.lines > size.thresholds.lines || row.branches > size.thresholds.branches || row.depth > size.thresholds.depth)) problems.push(`size.over[${index}] is under every threshold`)
+        if (index && size.over[index - 1].lines < row.lines) problems.push(`size.over[${index}] is longer than the one before it; the list is longest first`)
+      }
+      if (Array.isArray(observed.functions)) {
+        const listed = new Set(size.over.map((row) => `${row.file}:${row.line}`))
+        for (const row of observed.functions) {
+          const over = row.lines > size.thresholds?.lines || row.branches > size.thresholds?.branches || row.depth > size.thresholds?.depth
+          if (over && !listed.has(`${row.file}:${row.line}`)) problems.push(`observed.functions at ${row.file}:${row.line} is over a threshold but not under size.over`)
+        }
+      }
+    }
+  }
+  if (!Array.isArray(document.patterns)) problems.push("patterns is not a list")
+  else for (const [index, row] of document.patterns.entries()) {
+    const at = `patterns[${index}]`
+    if (!isString(row.id)) problems.push(`${at}.id is not a string`)
+    else if (known.patternIds && !known.patternIds.includes(row.id)) problems.push(`${at}.id ${row.id} is not a pattern patterns.mjs defines`)
+    if (!isInt(row.observedCount) || row.observedCount < 1) problems.push(`${at}.observedCount is not a positive count: a pattern is listed only where its precondition was observed`)
+    if (!Array.isArray(row.sites) || row.sites.length === 0) problems.push(`${at}.sites is not a non-empty list`)
+    else for (const [n, entry] of row.sites.entries()) site(entry, `${at}.sites[${n}]`, problems)
+    if (!isString(row.measurement) || !/^M\d+$/.test(row.measurement)) problems.push(`${at}.measurement is not a measurement id`)
+    if (typeof row.share !== "number" || !(row.share > 0 && row.share < 1)) problems.push(`${at}.share is not a share between 0 and 1`)
+    if (!isString(row.observation) || !/^observed /.test(row.observation)) problems.push(`${at}.observation does not start with the word observed`)
+    if (!isString(row.summary) || !row.summary || /\w:\d+/.test(row.summary)) problems.push(`${at}.summary is not the observation without its sites`)
+    if (/\b(?:missing|should|fix)\b/i.test(String(row.observation))) problems.push(`${at}.observation reads as a verdict`)
+  }
+  if (!Array.isArray(document.lookedFor) || document.lookedFor.some((id) => !isString(id))) problems.push("lookedFor is not a list of pattern ids")
+  else {
+    const listed = new Set((document.patterns || []).map((row) => row.id))
+    for (const id of document.lookedFor) {
+      if (listed.has(id)) problems.push(`lookedFor names ${id}, which is also under patterns`)
+      if (known.patternIds && !known.patternIds.includes(id)) problems.push(`lookedFor names ${id}, which patterns.mjs does not define`)
+    }
+    if (known.patternIds) {
+      for (const id of known.patternIds) if (!listed.has(id) && !document.lookedFor.includes(id)) problems.push(`pattern ${id} is neither under patterns nor under lookedFor`)
+    }
+  }
+  if (!Array.isArray(document.notVisible) || document.notVisible.some((line) => !isString(line))) problems.push("notVisible is not a list of sentences")
+  else if (known.notVisible && JSON.stringify(document.notVisible) !== JSON.stringify(known.notVisible)) problems.push("notVisible is not the fixed blind-spot list, verbatim")
+
+  const baseline = document.marketplaceBaseline
+  if (!baseline || typeof baseline !== "object") problems.push("marketplaceBaseline is missing")
+  else if (baseline.skipped === true) {
+    if (!isString(baseline.reason)) problems.push("marketplaceBaseline.reason is not a string")
+  } else {
+    if (!baseline.pin || !isString(baseline.pin.commit)) problems.push("marketplaceBaseline.pin.commit is not a string")
+    if (!isString(baseline.transport)) problems.push("marketplaceBaseline.transport is not a string")
+    if (!isBool(baseline.invoked)) problems.push("marketplaceBaseline.invoked is not a boolean")
+    if (!isString(baseline.statement)) problems.push("marketplaceBaseline.statement is not a string")
+    if (baseline.invoked && (!baseline.official || typeof baseline.official !== "object")) problems.push("marketplaceBaseline.official is missing for an invoked baseline")
+  }
+  return problems
+}
+
+const invoked = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+if (invoked) {
+  const input = process.argv[2]
+  if (!input) throw new Error("usage: node tools/inspect/contract.mjs <document.json>")
+  const problems = validateInspectDocument(JSON.parse(readFileSync(resolve(input), "utf8")))
+  for (const problem of problems) process.stdout.write(`${problem}\n`)
+  process.stdout.write(problems.length ? `${problems.length} problem(s)\n` : "ok: the document follows the contract in docs/INSPECT.md\n")
+  process.exit(problems.length ? 1 : 0)
+}