omakit 0.1.0 → 0.1.3

package/README.md

@@ -48,20 +48,18 @@ review writing. The rest of the benefit is the submitter's.
 
 ## Install
 
-On Omarchy, or any Arch:
-
-```bash
-yay -S omakit
-omakit setup
-```
-
-Anywhere with Node 22 or newer:
-
 ```bash
 npm install --global omakit
 omakit setup
 ```
 
+If `omakit` is not found afterwards, npm's global `bin` is not on your PATH
+(measured: a prefix of `~/.local/share/lerd/node-global` whose `bin` no shell
+searched). Run `"$(npm prefix --global)/bin/omakit" setup` once: it prints the
+one line that puts that directory on PATH for the shell in `$SHELL`, and the
+rc file to keep it in; `omakit doctor` reports the same as `omakit.path`.
+Nothing writes to your rc file.
+
 Or read what you run:
 
 ```bash
@@ -72,15 +70,16 @@ omakit setup
 
 | Needs | Why |
 | --- | --- |
-| Node 22 or newer | the tool is plain ESM with no dependencies and no build step. A stock Omarchy has it through `mise`, along with `git`, `yay`, `gh` and `ttfx` |
+| Node 22 or newer | the tool is plain ESM with no dependencies and no build step. A stock Omarchy has Node and npm through `mise`, along with `git`, `gh` and `ttfx` |
 | `git` | the pin, and reading a subject's tree at an exact commit |
 | network, once | `omakit pin`. After that, `submit` and `verify` on a local repository need none at all |
 | 15 MB on disk | the pinned checkout, in `$XDG_CACHE_HOME/omakit/marketplace`, or `~/.cache/omakit/marketplace` |
 
-Updates come from whichever installer you used: `omarchy-update` or `yay -Syu`
-for the package, `npm i -g omakit@latest` for npm, `omakit upgrade` for a
-clone. Nothing in omakit updates itself, and `omarchy-mise-install npm:omakit`
-would, so it is not the way in.
+`omakit upgrade` updates either install through the installer that made it:
+`npm` for the package, at the exact version the registry names, and a
+fast-forward for a clone. `omakit doctor` says when a newer version is
+published. Nothing in omakit fetches and runs its own replacement, and
+`omarchy-mise-install npm:omakit` would, so it is not the way in.
 
 ## Watch
 
@@ -110,7 +109,7 @@ omakit verify <plugin-repo>  # the official security baseline over the local tra
 omakit parity                # the baseline over GitHub versus the local transport, on real listings; writes the evidence
 omakit doctor                # what is installed, what is pinned, and what has moved
 omakit pin                   # what setup does for the pin, on its own
-omakit upgrade               # fast-forwards this checkout of omakit itself
+omakit upgrade               # updates omakit through its own installer: npm, or a fast-forward
 omakit help --agent          # the operating instructions, for the agent running this
 ```
 
@@ -129,11 +128,12 @@ There is nothing to authenticate. If you have `gh auth login` done, omakit
 reads that credential for GET requests and stores nothing; a token in
 `GH_TOKEN` or `GITHUB_TOKEN` reaches it the same way, because `gh` honours
 those itself. Without either, `watch` and `parity` share GitHub's
-60-requests-an-hour unauthenticated allowance, and `submit` and `verify` on a
-local repository do not touch the network at all (a `<url>@<sha>` target is
-fetched once, over git, into the cache). omakit reads no environment variable of its own,
-and `omakit doctor` names the credential source it found, or that it found
-none.
+60-requests-an-hour unauthenticated allowance; `submit` reads two things
+online, the subject's default-branch HEAD and the marketplace's current
+registry, and `--offline` turns both off; `verify` on a local repository does
+not touch the network at all (a `<url>@<sha>` target is fetched once, over
+git, into the cache). omakit reads no environment variable of its own, and
+`omakit doctor` names the credential source it found, or that it found none.
 
 Every colour omakit prints is an ANSI palette index, so your Omarchy theme
 decides what it looks like, and nothing is said by colour alone. What the
@@ -149,7 +149,11 @@ tags and the exact text of the five checklist items are all read from
 `.github/ISSUE_TEMPLATE/submit-plugin.yml` in a marketplace checkout pinned to an
 exact commit. The rendered body is then handed to the marketplace's own
 `parseCurrentSubmission` from that same commit. If it accepts the body here, it
-accepts it there.
+accepts it there. The one exception is data, not rules: the registry and the
+catalog that say which ids and repositories are already listed are read from
+the marketplace's current HEAD when the network is there, because the pin's
+copy is stale within hours (4,201 of 4,293 commits in 30 days touched only
+`registry.json`), and from the pin with `--offline`.
 
 The security baseline is the marketplace's own code, imported unmodified and run
 over a local snapshot with no network. Omakit adds no rule, renames no outcome,
@@ -169,18 +173,20 @@ move on its own. That distinction is now enforced rather than argued.
 **The tool:**
 
 ```bash
-omakit upgrade          # fast-forwards this checkout of omakit itself
+omakit upgrade          # the npm package, or a clone: through its own installer
 omakit upgrade --dry-run
 ```
 
-It refuses a dirty tree, a detached HEAD, a remote that is not this repository,
-and anything that is not a fast-forward, and it names what to run yourself in
-each case. It is not a self-updater of the kind this repository warns other
-people about: it fast-forwards a Git checkout you cloned, from the remote you
-cloned it from, and it touches nothing else. On a package install it says so and
-names the installer's own command: `npm i -g omakit@latest`, or
-`sudo pacman -Syu omakit` for the Arch package. `git -C ~/.local/share/omakit pull` still works
-and does the same thing.
+It is not a self-updater of the kind this repository warns other people
+about: it never fetches and runs its own replacement. On an npm install it asks
+the registry for the newest version and, if that is newer, runs the `npm` on
+PATH with frozen arguments (`npm install --global --ignore-scripts omakit@<that
+version>`, never `@latest`, never with sudo), and it refuses when the npm on
+PATH is not the one that installed it. On a clone it fast-forwards from the
+remote you cloned it from, and refuses a dirty tree, a detached HEAD, a remote
+that is not this repository, and anything that is not a fast-forward. In every
+refusal it names what to run yourself. `git -C ~/.local/share/omakit pull`
+still works on a clone and does the same thing.
 
 **The pin** does not move by itself, ever, and `omakit upgrade` does not move it
 either: a test asserts that its source does not so much as mention the pin or
@@ -188,7 +194,9 @@ the cache. Bumping it changes where the submission contract and the baseline
 policy are read from, and the procedure in
 [docs/UPSTREAM_CONTRACT.md](docs/UPSTREAM_CONTRACT.md) ends in re-proving
 transport parity and committing the evidence. `omakit doctor` tells you when the
-pin is behind the marketplace's current branch and then leaves it alone. That the
+pin is behind the marketplace's current branch, names which of the paths omakit
+reads actually changed (about 140 commits a day touch only `registry.json`, so
+"behind" alone would be true of every run), and then leaves it alone. That the
 pin can go stale unnoticed is the same defect class `omakit watch` reports, so it
 would be poor form to hide it here.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.1.0",
+  "version": "0.1.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, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

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

@@ -28,7 +28,14 @@ them. The failing checks print the controlled lists, read from the pinned form.
 
 Useful flags: `--notes` for the Maintainer notes field, `--suggest-tag` for the
 optional suggestion, `--name` when the manifest has no name, `--json` for a
-machine-readable result, `--offline` to skip the one check that needs the network.
+machine-readable result, `--offline` to skip the one check that needs the network
+and to read the listed ids from the pin instead of the marketplace's current HEAD.
+
+Never pass `--offline` to get around a listed id. `identity.available` reads the
+registry from HEAD because the pin's copy is stale within hours; a run that
+passes only against the pin describes a marketplace that no longer exists, and
+the marketplace will refuse the id anyway. If an id or repository is listed at
+HEAD, tell the owner and choose another id.
 
 ## Reading the result
 

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

@@ -35,6 +35,11 @@ it from the operator's `gh` login (which itself honours `GH_TOKEN` and
 `GITHUB_TOKEN`); without one it falls back to the public commit feed. Never ask the operator for a token: run
 `omakit doctor` and read the `github.auth` line, which names the source.
 
+If the diagnosis ends in a resubmission under a new id, run `omakit submit`
+online: never pass `--offline` to get around a listed id, because that reads
+the listed ids from the pin, which is stale within hours, and the marketplace
+refuses against its current registry.
+
 ## Acting on each verdict
 
 **`stale`.** The validated commit is behind the repository. Tell the owner plainly: the marketplace has not

package/tools/marketplace/README.md

@@ -14,7 +14,7 @@ local commit through the transport seam the marketplace tests itself
 | `preflight.mjs` | Translates that result into what it will cause on submission, using the pinned policy, and renders the marketplace's own report text with its attestation marker stripped and asserted absent. |
 | `yaml.mjs` | A deliberately small YAML reader for the pinned issue form. Accepts that subset and throws on anything else. |
 | `form.mjs` | The submission contract, read from the form and cross-checked against the marketplace's own constants. |
-| `registry.mjs` | The plugin-id and repository universe, and the reserved namespace, read from the pinned registry, catalog and catalog builder. |
+| `registry.mjs` | The plugin-id and repository universe: the reserved namespace from the pinned catalog builder, the listed and retired ids and listed repositories from `registry.json` and `site/catalog.json` at the marketplace's current HEAD when the network is there (cached under `$XDG_CACHE_HOME/omakit/registry/<commit>/`, never in the pin) and at the pin with `--offline`; `liveFileUrl()` is the only way to the raw file host, at a 40-character commit, for those two files. |
 | `tree.mjs` | The installable tree of a subject at one exact commit, from the Git object database. |
 | `plugin.mjs` | The root files the submission contract needs, and the declared plugin identity. |
 | `agent-control.mjs` | The recursive agent-control warning, and its remedy. |
@@ -24,6 +24,7 @@ local commit through the transport seam the marketplace tests itself
 | `github.mjs` | Read-only GitHub access. GET only. The credential is your `gh` login, read through one frozen `gh auth token` call, and is never written anywhere. |
 | `style.mjs` | The visual system, defined once: the palette, the status vocabulary, the block ramp, the columns, the motion budgets, and the composition helpers every command draws with. `docs/TUI.md` explains it. |
 | `report.mjs` | Text rendering of submit, watch and doctor for the agent that runs this tool, and the person reading over its shoulder. |
+| `path-hint.mjs` | Is `omakit` reachable as a bare command, and if not, the one line that makes it so for the install that is here: a symlink for a clone, the npm prefix's `bin` on PATH for a package, said for the shell in `$SHELL`. `setup` and `doctor` print it; nothing writes an rc file. |
 | `usage.mjs` | The help text, as data. |
 | `completion.mjs` | A completion script for bash, zsh or fish, derived from the help data and the pin's form: the subcommands and flags are read out of `COMMANDS`, the categories and tags out of the pinned submission form, and the script says which pin it came from. `setup` installs it for the shell in `$SHELL`, the one file this tool writes outside its own checkout. |
 | `banner.mjs` | The wordmark, on a bare `omakit` and in `setup` only. |
@@ -57,8 +58,10 @@ the registry recorded so the corpus always contains repositories that are not
 side rather than the findings themselves. The GitHub side uses whatever
 credential `github.mjs` resolves (a `gh` login, and only that), read-only.
 
-`parity` and `watch` are the only commands that reach the network, and they do it
-with Node's built-in `fetch`, which does not read proxy environment variables by
-default. Behind a proxy, run them with `NODE_USE_ENV_PROXY=1`. `submit` and
-`verify` need no network at all beyond fetching a reviewer-mode subject, and
-`tests/parity/offline.mjs` proves it.
+`parity`, `watch`, `doctor` and `submit` reach the network, with Node's
+built-in `fetch`, which does not read proxy environment variables by default.
+Behind a proxy, run them with `NODE_USE_ENV_PROXY=1`. `submit` reads two things
+online, the subject's default-branch HEAD and the marketplace's current
+registry, and `--offline` turns both off; `verify` needs no network at all
+beyond fetching a reviewer-mode subject, and `tests/parity/offline.mjs` proves
+it.

package/tools/marketplace/doctor.mjs

@@ -4,9 +4,10 @@
 // checkout, because the two things a person might want "upgraded" here are not
 // the same thing and only one of them may ever move on its own.
 //
-// The tool version belongs to the installer: Git for a checkout, npm for its
-// package, and pacman for the Arch package. A CLI that fetches and executes its
-// own replacement is the supply-chain shape this repository warns about.
+// The tool version belongs to the installer: `omakit upgrade` hands it to Git
+// for a checkout and to npm for its package, and names pacman for a distro
+// package. A CLI that fetches and executes its own replacement is the
+// supply-chain shape this repository warns about.
 //
 // The pin must not move by itself. Bumping it changes where the submission
 // contract is read from, and the procedure in docs/UPSTREAM_CONTRACT.md requires
@@ -16,13 +17,22 @@
 //
 // That the pin goes stale unnoticed is, of course, exactly the defect class
 // `omakit watch` exists to report. It would be poor form not to apply it here.
+//
+// And "behind" is not the same as "behind in something omakit reads". Measured
+// on 2026-09-13 (docs/MEASUREMENTS.md M7): 4,201 of the marketplace's 4,293
+// commits in 30 days touched only registry.json, which omakit now reads live,
+// while nothing under scripts/ or .github/ISSUE_TEMPLATE/ changed since the
+// pin. A doctor that only said "behind" would say it about every run. So it
+// compares each path in PIN_PATHS between the pin and HEAD, by tree or blob
+// id, and names the ones that moved.
 
 import { execFileSync } from "node:child_process"
 import { readFileSync } from "node:fs"
 import { join } from "node:path"
-import { MARKETPLACE_PIN, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
+import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
 import { credential, defaultBranchHead, getJson, UNAUTHENTICATED_LIMIT, GitHubError } from "./github.mjs"
-import { upgradeCommand } from "./upgrade.mjs"
+import { latestOnRegistry, upgradeCommand } from "./upgrade.mjs"
+import { pathHint } from "./path-hint.mjs"
 
 function tool(repoRoot) {
   try {
@@ -41,37 +51,91 @@ function version(command, args = ["--version"]) {
   }
 }
 
-async function latestOnRegistry(name) {
-  try {
-    const meta = await getJson(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`)
-    return meta?.version || null
-  } catch {
-    return null
+/** The object id a path has at a commit in the pinned checkout: a tree id for a directory, a blob id for a file. Local; a blob-filtered clone still has every tree. */
+function pinObjectId(pinDir, commit, path) {
+  return execFileSync("git", ["-C", pinDir, "rev-parse", `${commit}:${path}`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
+}
+
+/**
+ * Which of PIN_PATHS differ between the pin and `headCommit`. The pin side is
+ * read from the local checkout; the HEAD side walks the git-trees API from the
+ * exact commit, one read per tree on the way (three for PIN_PATHS as it
+ * stands), so a directory compares by its tree id and a file by its blob id,
+ * which is what "the blob at HEAD versus the blob at the pin" means for a
+ * directory that omakit reads whole. A path missing at HEAD counts as changed.
+ *
+ * `fetchJson` is injectable for tests; the default is the one GET call site.
+ */
+export async function changedPinPaths({ pinDir, headCommit, pinCommit = MARKETPLACE_PIN.commit, fetchJson = getJson }) {
+  const match = MARKETPLACE_PIN.repository.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)$/)
+  const trees = new Map()
+  const tree = async (sha) => {
+    if (!trees.has(sha)) {
+      const read = await fetchJson(`https://api.github.com/repos/${match[1]}/${match[2]}/git/trees/${sha}`)
+      if (!Array.isArray(read?.tree)) throw new GitHubError("head-unreadable", `the tree ${sha} at the marketplace's HEAD did not read as a tree`)
+      trees.set(sha, read.tree)
+    }
+    return trees.get(sha)
+  }
+  const headObjectId = async (path) => {
+    const segments = path.split("/")
+    let entries = await tree(headCommit)
+    let id = null
+    for (const [index, segment] of segments.entries()) {
+      const entry = entries.find((candidate) => candidate.path === segment)
+      if (!entry) return null
+      id = entry.sha
+      // Descend only on the way to a deeper segment: the path's own tree id
+      // is the comparison, and its contents need no read.
+      if (index < segments.length - 1) {
+        if (entry.type !== "tree") return null
+        entries = await tree(entry.sha)
+      }
+    }
+    return id
+  }
+  const changed = []
+  for (const pattern of PIN_PATHS) {
+    const path = pattern.replace(/^\/|\/$/g, "")
+    if (pinObjectId(pinDir, pinCommit, path) !== await headObjectId(path)) changed.push(pattern)
   }
+  return changed
 }
 
-/** Full pin evidence for machines; human output deliberately keeps short hashes. */
-export function pinFreshness(identity, head) {
+/**
+ * Full pin evidence for machines; human output deliberately keeps short
+ * hashes. `changedPaths` is the answer from changedPinPaths(); null when the
+ * comparison was not made, and then the detail says only that HEAD moved.
+ */
+export function pinFreshness(identity, head, changedPaths = null) {
   const current = head.commit === identity.commit
+  const branch = head.branch || "default"
+  const moved = changedPaths === null
+    ? ""
+    : changedPaths.length
+      ? `; changed since the pin: ${changedPaths.join(", ")}`
+      : "; every path omakit reads is unchanged since the pin"
   return {
     id: "pin.freshness",
     state: current ? "ok" : "advice",
     detail: current
-      ? `the pin is the marketplace's current ${head.branch || "default"}-branch HEAD`
-      : `the pin is ${identity.commit.slice(0, 7)}; the marketplace's ${head.branch || "default"} branch is now at ${head.commit.slice(0, 7)}`,
+      ? `the pin is the marketplace's current ${branch}-branch HEAD`
+      : `the pin is ${identity.commit.slice(0, 7)}; the marketplace's ${branch} branch is now at ${head.commit.slice(0, 7)}${moved}`,
     action: current ? null : "Bumping the pin is a deliberate change: docs/UPSTREAM_CONTRACT.md has the procedure, which ends in re-proving parity and committing its evidence. Nothing here does it for you.",
     evidence: {
       pinCommit: identity.commit,
       marketplaceHead: head.commit,
-      branch: head.branch || "default",
+      branch,
+      ...(changedPaths === null ? {} : { changedPaths: current ? [] : changedPaths }),
     },
   }
 }
 
 /**
- * @param {{ repoRoot: string, offline?: boolean }} options
+ * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null }} options
+ *   `env` and `npmPrefix` are injectable for tests of the PATH check.
  */
-export async function doctor({ repoRoot, offline = false, onPhase }) {
+export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix }) {
   // Optional: told what is being read while the network answers. Never
   // affects the result.
   const phase = onPhase || (() => {})
@@ -87,6 +151,16 @@ export async function doctor({ repoRoot, offline = false, onPhase }) {
   const self = tool(repoRoot)
   add("omakit.version", "info", `${self.name} ${self.version}`)
 
+  // Reachable as a bare command, or the one line that makes it so for this
+  // install (path-hint.mjs). Measured: an npm prefix whose bin is not on PATH
+  // installs a command nobody can run, and nothing said so.
+  const reach = pathHint({ repoRoot, entryPoint: join(repoRoot, "bin/omakit"), env, ...(npmPrefix ? { npmPrefix } : {}) })
+  add("omakit.path", reach.reachable ? "ok" : "advice",
+    reach.reachable
+      ? `\`omakit\` is reachable as a command from PATH (${reach.kind} install)`
+      : `${reach.reason}${reach.where ? ` Keep the line below in ${reach.where}.` : ""}`,
+    reach.reachable ? null : reach.line)
+
   const node = process.versions.node
   const major = Number(node.split(".")[0])
   add("node", major >= 22 ? "ok" : "problem", `node ${node}${self.engines ? ` (needs ${self.engines})` : ""}`,
@@ -112,7 +186,12 @@ export async function doctor({ repoRoot, offline = false, onPhase }) {
     phase("reading the marketplace's current default-branch HEAD")
     try {
       const head = await defaultBranchHead(MARKETPLACE_PIN.repository)
-      checks.push(pinFreshness(identity, head))
+      let changedPaths = []
+      if (head.commit !== identity.commit) {
+        phase("comparing each path omakit reads between the pin and HEAD")
+        changedPaths = await changedPinPaths({ pinDir: dir, headCommit: head.commit, pinCommit: identity.commit })
+      }
+      checks.push(pinFreshness(identity, head, changedPaths))
     } catch (error) {
       add("pin.freshness", "unknown", `could not read the marketplace's HEAD (${error.code || "error"})`,
         error.code === "network-unavailable" ? "Connect to the network, or pass --offline to skip the two checks that need it." : null,

package/tools/marketplace/path-hint.mjs

@@ -0,0 +1,53 @@
+// Is `omakit` reachable as a bare command, and if not, the one line that makes
+// it so, for the install that is actually here.
+//
+// Measured: after `npm install --global omakit` on a machine whose npm prefix
+// was ~/.local/share/lerd/node-global, the command was missing, because that
+// prefix's `bin` was not on PATH. `omakit setup` then printed the `ln -s` hint
+// written for a clone, which points at a bin/omakit that npm did not lay out
+// where the hint assumes. An npm install needs the npm prefix's `bin` on PATH,
+// and the way to say that depends on the shell in $SHELL. Nothing here writes
+// to an rc file: the line is printed, and adding it is the user's.
+
+import { existsSync } from "node:fs"
+import { basename, delimiter, join } from "node:path"
+import { installKind, npmGlobalPrefix } from "./upgrade.mjs"
+
+/** Is `name` reachable as a bare command, without asking a shell? */
+export function onPath(name = "omakit", env = process.env) {
+  return (env.PATH || "").split(delimiter).some((dir) => dir && existsSync(join(dir, name)))
+}
+
+/** The rc file each supported shell reads at start, for the person to add the line to. */
+const RC = Object.freeze({ bash: "~/.bashrc", zsh: "~/.zshrc" })
+
+/**
+ * @param {{ repoRoot: string, entryPoint: string, env?: object, npmPrefix?: () => string|null }} options
+ *   `npmPrefix` is injectable for tests; the default asks the npm on PATH.
+ * @returns {{ kind: "git"|"npm"|"distro", reachable: boolean, reason: string|null,
+ *             line: string|null, where: string|null }}
+ *   `line` is the command that puts `omakit` on PATH; `where` is the rc file
+ *   to keep it in, or null when the shell keeps it itself (fish) or is not
+ *   one of the three with a script.
+ */
+export function pathHint({ repoRoot, entryPoint, env = process.env, npmPrefix = npmGlobalPrefix }) {
+  const kind = installKind(repoRoot)
+  if (onPath("omakit", env)) return { kind, reachable: true, reason: null, line: null, where: null }
+  if (kind !== "npm") {
+    return { kind, reachable: false, reason: "`omakit` is not on your PATH yet.", line: `ln -s ${entryPoint} ~/.local/bin/omakit`, where: null }
+  }
+  const prefix = npmPrefix()
+  if (!prefix) {
+    return { kind, reachable: false, reason: "`omakit` is not on your PATH yet, and no `npm` is on PATH to ask where it was installed.", line: null, where: null }
+  }
+  const bin = join(prefix, "bin")
+  const shell = basename(env.SHELL || "")
+  const line = shell === "fish" ? `fish_add_path ${bin}` : `export PATH="${bin}:$PATH"`
+  return {
+    kind,
+    reachable: false,
+    reason: `\`omakit\` is not on your PATH yet: npm installed it under ${bin}, which your shell does not search.`,
+    line,
+    where: RC[shell] || null,
+  }
+}

package/tools/marketplace/registry.mjs

@@ -1,8 +1,7 @@
-// The plugin-id and repository universe, read from the pinned marketplace
-// checkout. Like the submission contract, nothing here is hardcoded: the
-// reserved namespace is read out of the marketplace's own catalog builder, the
-// listed ids out of the published catalog and the registry sources, and the
-// retired ids out of `registry.json`.
+// The plugin-id and repository universe. Like the submission contract, nothing
+// here is hardcoded: the reserved namespace is read out of the marketplace's
+// own catalog builder, the listed ids out of the published catalog and the
+// registry sources, and the retired ids out of `registry.json`.
 //
 // Measured reason these three checks exist (docs/MEASUREMENTS.md M2): the
 // marketplace refuses a submission whose id is already listed
@@ -13,15 +12,31 @@
 // median submission-to-publication time rose sevenfold between 2026-W33 and
 // 2026-W36, and it is knowable before submitting from data the marketplace
 // publishes.
+//
+// Two kinds of file, two sources (docs/MEASUREMENTS.md M7). The catalog
+// builder is code, and code is only ever read from the pin: it moves a few
+// times a month and must never be fetched and executed unreviewed. The
+// registry and the catalog are data, and the pin's copy of them is stale
+// within hours: registry.json changed in 4,201 of the marketplace's 4,293
+// commits in the 30 days to 2026-09-13, about 140 a day. So those two files
+// are read from the marketplace's current default-branch HEAD when the network
+// is there, at the exact commit `defaultBranchHead()` resolved so they cannot
+// disagree with each other, and from the pin when it is not or when the caller
+// asks for --offline. Every result says which, with the commit.
 
-import { readFileSync } from "node:fs"
-import { join } from "node:path"
-import { requirePin } from "./pin.mjs"
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
+import { defaultBranchHead, getJson } from "./github.mjs"
+import { omakitCacheDir } from "./paths.mjs"
 
 export const CATALOG_PATH = "site/catalog.json"
 export const REGISTRY_PATH = "registry.json"
 export const CATALOG_BUILDER_PATH = "scripts/build-catalog.mjs"
 
+/** The only two marketplace files ever read from HEAD. Everything else comes from the pin. */
+export const LIVE_PATHS = Object.freeze([REGISTRY_PATH, CATALOG_PATH])
+
 export class RegistryError extends Error {
   constructor(code, message) {
     super(message)
@@ -65,14 +80,168 @@ function repositorySlug(value) {
 }
 
 /**
- * @param {{ repoRoot?: string, pinDir?: string }} [options]
+ * The one URL shape a live registry file is read from: one of LIVE_PATHS at
+ * one explicit 40-character commit on the marketplace's raw file host. Never
+ * a branch name, so the two files always come from the same commit and the
+ * commit named in the output is the one they came from; never a path outside
+ * LIVE_PATHS, so nothing executable can arrive this way.
+ */
+export function liveFileUrl(commit, path) {
+  if (!/^[0-9a-f]{40}$/.test(String(commit))) {
+    throw new RegistryError("usage", `a live registry file is read at a 40-character commit, not "${commit}"`)
+  }
+  if (!LIVE_PATHS.includes(path)) {
+    throw new RegistryError("usage", `${path} is never read from HEAD; only ${LIVE_PATHS.join(" and ")} are`)
+  }
+  const raw = MARKETPLACE_PIN.repository.replace(/^https:\/\/github\.com\//, "https://raw.githubusercontent.com/")
+  return `${raw}/${commit}/${path}`
+}
+
+/** Where the live files for one commit are kept: beside the pin, never inside it. */
+export function liveCacheDir(commit, cacheRoot = omakitCacheDir("registry")) {
+  return join(cacheRoot, commit)
+}
+
+/** A cached commit is one whose meta.json, written last, names every file present. */
+function readCached(liveCache) {
+  try {
+    const meta = JSON.parse(readFileSync(join(liveCache, "meta.json"), "utf8"))
+    if (typeof meta.fetchedAt !== "string" || JSON.stringify(meta.paths) !== JSON.stringify(LIVE_PATHS)) return null
+    const files = {}
+    for (const path of LIVE_PATHS) files[path] = JSON.parse(readFileSync(join(liveCache, path), "utf8"))
+    return { fetchedAt: meta.fetchedAt, files }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * One directory per commit, the files first and meta.json last, so a run that
+ * dies mid-write leaves a directory readCached() does not accept. Older
+ * commits are removed: at about 140 registry commits a day, keeping every one
+ * would grow the cache by the measured 13 MB per run.
+ */
+function writeCached(cacheRoot, commit, fetchedAt, files) {
+  const liveCache = liveCacheDir(commit, cacheRoot)
+  rmSync(liveCache, { recursive: true, force: true })
+  for (const path of LIVE_PATHS) {
+    mkdirSync(dirname(join(liveCache, path)), { recursive: true })
+    writeFileSync(join(liveCache, path), JSON.stringify(files[path]))
+  }
+  writeFileSync(join(liveCache, "meta.json"), `${JSON.stringify({ commit, fetchedAt, paths: LIVE_PATHS }, null, 2)}\n`)
+  for (const entry of readdirSync(cacheRoot, { withFileTypes: true })) {
+    if (entry.isDirectory() && entry.name !== commit) rmSync(join(cacheRoot, entry.name), { recursive: true, force: true })
+  }
+}
+
+/**
+ * The registry and the catalog, from the marketplace's current default-branch
+ * HEAD when the network is there and from the pin when it is not. Never
+ * throws for a network reason: a HEAD that cannot be read falls back to the pin
+ * and says so in `reason`. The pinned checkout is never written to; a fetched
+ * pair is cached under `cacheRoot/<commit>/`.
+ *
+ * `resolveHead`, `fetchJson`, `cacheRoot` and `now` are injectable for tests;
+ * the defaults are the tool's one HEAD resolver and its one GET call site.
+ *
+ * @param {{ repoRoot?: string, pinDir?: string, offline?: boolean,
+ *           resolveHead?: (url: string) => Promise<{ commit: string }>,
+ *           fetchJson?: (url: string) => Promise<object>, cacheRoot?: string,
+ *           now?: () => string }} [options]
+ * @returns {Promise<{ source: "head"|"pin", commit: string, fetchedAt: string|null,
+ *                     reason: string|null, fallback: { what: string, code: string, message: string }|null,
+ *                     registry: object, catalog: object }>}
+ *   `reason` is the whole story, for `--json`; `fallback` is its parts, for
+ *   the one line a person reads (registrySourceDetail).
+ */
+export async function liveRegistry(options = {}) {
+  const pinDir = options.pinDir || requirePin(options.repoRoot).dir
+  const resolveHead = options.resolveHead || defaultBranchHead
+  const fetchJson = options.fetchJson || getJson
+  const cacheRoot = options.cacheRoot || omakitCacheDir("registry")
+  const now = options.now || (() => new Date().toISOString())
+  const fromPin = (reason, fallback = null) => ({
+    source: "pin",
+    commit: MARKETPLACE_PIN.commit,
+    fetchedAt: null,
+    reason,
+    fallback,
+    registry: readJson(pinDir, REGISTRY_PATH),
+    catalog: readJson(pinDir, CATALOG_PATH),
+  })
+  const failed = (what, error) => {
+    const code = error?.code || "error"
+    const message = String(error?.message || error)
+    return fromPin(`${what} (${code}): ${message}`, { what, code, message })
+  }
+  if (options.offline) return fromPin("--offline")
+
+  let commit
+  try {
+    commit = String((await resolveHead(MARKETPLACE_PIN.repository)).commit).toLowerCase()
+  } catch (error) {
+    return failed("HEAD unreadable", error)
+  }
+  if (commit === MARKETPLACE_PIN.commit) {
+    // HEAD is the pin, so the pin's files are HEAD's files: nothing to fetch.
+    return { ...fromPin(null), source: "head", fetchedAt: now() }
+  }
+
+  const cached = readCached(liveCacheDir(commit, cacheRoot))
+  if (cached) {
+    return { source: "head", commit, fetchedAt: cached.fetchedAt, reason: null, fallback: null, registry: cached.files[REGISTRY_PATH], catalog: cached.files[CATALOG_PATH] }
+  }
+
+  const files = {}
+  try {
+    for (const path of LIVE_PATHS) files[path] = await fetchJson(liveFileUrl(commit, path))
+  } catch (error) {
+    return failed(`registry at ${commit} unreadable`, error)
+  }
+  const fetchedAt = now()
+  try {
+    mkdirSync(cacheRoot, { recursive: true })
+    writeCached(cacheRoot, commit, fetchedAt, files)
+  } catch {
+    // A cache that cannot be written costs the next run a refetch, nothing else.
+  }
+  return { source: "head", commit, fetchedAt, reason: null, fallback: null, registry: files[REGISTRY_PATH], catalog: files[CATALOG_PATH] }
+}
+
+/**
+ * How a check names where its registry data came from. Short hash for the
+ * pin, which the docs name that way; the full commit for HEAD, which nothing
+ * else names.
+ *
+ * A fallback is one clause, not the whole story: the transport error's own
+ * parenthetical and its "while reading <path>" tail are dropped and the
+ * failure code takes their place, so the person reads
+ * "registry at the pin 38060f89; HEAD unreadable: github.com did not answer
+ * (network-unavailable)" on one line. Measured before this: the full text
+ * nested three sets of parentheses and wrapped to three lines at 80 columns.
+ * `--json` keeps the whole text under `registry.reason`.
+ */
+export function registrySourceDetail(live) {
+  if (live.source === "head") return `registry at ${live.commit}, read ${live.fetchedAt}`
+  const pin = `registry at the pin ${live.commit.slice(0, 8)}`
+  if (!live.fallback) return live.reason === "--offline" ? `${pin} (offline)` : pin
+  const { what, code, message } = live.fallback
+  const clause = message.replace(/ while reading .*$/, "").replace(/\s*\([^()]*\)\s*$/, "").trim()
+  const short = what.replace(/^registry at ([0-9a-f]{40}) unreadable$/, (_, sha) => `HEAD ${sha.slice(0, 7)} unreadable`)
+  return `${pin}; ${short}: ${clause} (${code})`
+}
+
+/**
+ * @param {{ repoRoot?: string, pinDir?: string, registry?: object, catalog?: object }} [options]
+ *   `registry` and `catalog` are the parsed files from liveRegistry(); without
+ *   them the pin's copies are read.
  * @returns {{ reservedPrefix: string, listedIds: Set<string>, retiredIds: Set<string>,
  *             listedRepositories: Set<string>, counts: object }}
  */
 export function idUniverse(options = {}) {
   const pinDir = options.pinDir || requirePin(options.repoRoot).dir
-  const catalog = readJson(pinDir, CATALOG_PATH)
-  const registry = readJson(pinDir, REGISTRY_PATH)
+  const catalog = options.catalog || readJson(pinDir, CATALOG_PATH)
+  const registry = options.registry || readJson(pinDir, REGISTRY_PATH)
 
   const listedIds = new Set()
   for (const plugin of Array.isArray(catalog.plugins) ? catalog.plugins : []) {

package/tools/marketplace/setup.mjs

@@ -11,8 +11,6 @@
 // and stops, which is the same contract every other command here keeps.
 
 import { execFileSync } from "node:child_process"
-import { existsSync } from "node:fs"
-import { delimiter, join } from "node:path"
 import { banner } from "./banner.mjs"
 import { credential, UNAUTHENTICATED_LIMIT } from "./github.mjs"
 import { ensurePin, marketplacePinDir, pinDiskUsage } from "./pin.mjs"
@@ -21,6 +19,7 @@ import { action, colourEnabled, GUTTER, mark, styler, wrap } from "./style.mjs"
 import { TAGLINE } from "./usage.mjs"
 import { installCompletion } from "./completion.mjs"
 import { submissionContract } from "./form.mjs"
+import { pathHint } from "./path-hint.mjs"
 
 function version(command) {
   try {
@@ -32,11 +31,6 @@ function version(command) {
   }
 }
 
-/** Is `omakit` reachable as a bare command, without asking a shell? */
-export function onPath(name = "omakit", env = process.env) {
-  return (env.PATH || "").split(delimiter).some((dir) => dir && existsSync(join(dir, name)))
-}
-
 /**
  * @param {{ repoRoot: string, entryPoint: string, stream?: NodeJS.WriteStream }} options
  */
@@ -101,9 +95,14 @@ export async function setup({ repoRoot, entryPoint, stream = process.stdout }) {
   for (const line of wrap("Every rule omakit checks is read from that checkout, at that exact commit. It never moves on its own. `omakit doctor` says when it is behind.", {}, c)) out(line)
   out()
 
-  if (!onPath()) {
-    step("info", "`omakit` is not on your PATH yet. This puts it there:")
-    fix(`ln -s ${entryPoint} ~/.local/bin/omakit`)
+  // The hint is for the install that is here: a symlink for a clone, the npm
+  // prefix's bin on PATH for a package, in the shell in $SHELL (path-hint.mjs).
+  const reach = pathHint({ repoRoot, entryPoint })
+  if (!reach.reachable) {
+    step("info", reach.line
+      ? `${reach.reason} This puts it there${reach.where ? `; keep it in ${reach.where}` : ""}:`
+      : reach.reason)
+    if (reach.line) fix(reach.line)
     out()
   }
 

package/tools/marketplace/submit.mjs

@@ -14,7 +14,7 @@
 import { resolveSubject, SubjectError } from "../subject/resolve.mjs"
 import { requirePin } from "./pin.mjs"
 import { submissionContract, resolveCategory, resolveTags } from "./form.mjs"
-import { idUniverse, checkIdentity, baselineFigures, figure } from "./registry.mjs"
+import { idUniverse, checkIdentity, baselineFigures, figure, liveRegistry, registrySourceDetail } from "./registry.mjs"
 import { readTree } from "./tree.mjs"
 import { inspectTree } from "./plugin.mjs"
 import { findAgentControl, REMEDY as AGENT_CONTROL_REMEDY } from "./agent-control.mjs"
@@ -48,7 +48,10 @@ function check(id, fields) {
 /**
  * @param {{ repoRoot: string, target: string, category?: string, tags?: string|string[],
  *           notes?: string, suggestedTag?: string, pluginName?: string,
- *           allowDirty?: boolean, offline?: boolean }} options
+ *           allowDirty?: boolean, offline?: boolean,
+ *           readRegistry?: typeof liveRegistry }} options
+ *   `readRegistry` is injectable for tests; the default reads the marketplace's
+ *   current HEAD, or the pin with `offline`.
  */
 export async function submitPreflight(options) {
   const { repoRoot } = options
@@ -60,8 +63,11 @@ export async function submitPreflight(options) {
   const { identity: pinIdentity } = requirePin(repoRoot)
   phase("reading the submission contract from the pin")
   const contract = await submissionContract({ repoRoot })
-  phase("reading the listed and retired plugin ids")
-  const universe = idUniverse({ repoRoot })
+  phase(options.offline ? "reading the listed and retired plugin ids from the pin" : "reading the marketplace's current registry")
+  const live = await (options.readRegistry || liveRegistry)({ repoRoot, offline: options.offline === true })
+  const universe = idUniverse({ repoRoot, registry: live.registry, catalog: live.catalog })
+  // The documented figures are the pin's by design: they are cited in prose
+  // that a test holds to the pin, so they never move between two runs.
   const figures = baselineFigures({ repoRoot })
 
   phase("resolving the subject commit")
@@ -145,11 +151,11 @@ export async function submitPreflight(options) {
   const identity = checkIdentity(universe, { id: tree.pluginId, repositoryUrl: subject.repository.url })
   checks.push(check("identity.available", {
     source: "marketplace-pin",
-    why: `The marketplace refuses \`plugin-id-listed\`, \`plugin-id-retired\`, \`reserved-plugin-id\` and \`submission-repository-listed\`. Checked here against ${universe.counts.listedIds} listed ids, ${universe.counts.retiredIds} retired ids and ${universe.counts.listedRepositories} listed repositories read from the pinned registry and catalog.`,
+    why: `The marketplace refuses \`plugin-id-listed\`, \`plugin-id-retired\`, \`reserved-plugin-id\` and \`submission-repository-listed\`. Checked here against ${figure(universe.counts.listedIds)} listed ids, ${figure(universe.counts.retiredIds)} retired ids and ${figure(universe.counts.listedRepositories)} listed repositories from the registry and catalog at the commit the detail names, and the reserved namespace from the pinned catalog builder. The registry is read from the marketplace's current HEAD when the network is there because the pin's copy is stale within hours: registry.json changed in 4,201 of the marketplace's 4,293 commits in the 30 days to 2026-09-13, about 140 a day (docs/MEASUREMENTS.md M7). Code and the form are only ever read from the pin.`,
     verdict: identity.ok,
-    detail: identity.ok
+    detail: `${identity.ok
       ? `id "${tree.pluginId}" is unused, outside the reserved ${universe.reservedPrefix}* namespace, and the repository is not listed`
-      : identity.problems.map((problem) => `${problem.code}: ${problem.detail}`).join("; "),
+      : identity.problems.map((problem) => `${problem.code}: ${problem.detail}`).join("; ")}; ${registrySourceDetail(live)}`,
     remedy: identity.ok ? null : "Choose an unused plugin id outside the reserved namespace.",
   }))
 
@@ -313,6 +319,12 @@ export async function submitPreflight(options) {
       commit: subject.commit,
       cleanTree: subject.clean,
     },
+    registry: {
+      source: live.source,
+      commit: live.commit,
+      fetchedAt: live.fetchedAt,
+      reason: live.reason,
+    },
     validationCommit: {
       local: subject.commit,
       defaultBranchHead: head?.commit || null,

package/tools/marketplace/upgrade.mjs

@@ -16,13 +16,16 @@
 // against.
 //
 // It is not a self-updater in the sense this repository warns other people
-// about. It does not fetch and execute arbitrary code: it fast-forwards a Git
-// checkout the user cloned themselves, from the remote they cloned it from, and
-// it refuses if any of that is not true.
+// about. It does not fetch and execute arbitrary code: it hands the update to
+// the installer that put the tool here. A Git checkout is fast-forwarded from
+// the remote it was cloned from; an npm install is reinstalled by the `npm` on
+// PATH, with frozen arguments, at the exact version the registry named, and
+// only when that version is newer. It refuses if any of that is not true.
 
 import { execFileSync } from "node:child_process"
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { join, resolve, sep } from "node:path"
+import { getJson } from "./github.mjs"
 import { progress } from "./progress.mjs"
 import { action, colourEnabled, GUTTER, mark, styler, verdict, wrap } from "./style.mjs"
 
@@ -40,11 +43,64 @@ export function installKind(repoRoot) {
 export function upgradeCommand(repoRoot, name = "omakit") {
   return {
     git: "omakit upgrade",
-    npm: `npm i -g ${name}@latest`,
+    npm: "omakit upgrade",
     distro: `sudo pacman -Syu ${name}`,
   }[installKind(repoRoot)]
 }
 
+/**
+ * The frozen shape of the one `npm` invocation this tool makes. The package
+ * spec appended to it is `<name>@<version>` with the version the registry just
+ * reported, never `latest`, so what is printed is what is run. No sudo, no
+ * script execution (`--ignore-scripts`), and tests/unit/read-only.test.mjs
+ * asserts that npm is spawned nowhere else and with nothing else.
+ */
+export const NPM_UPGRADE_ARGS = Object.freeze(["install", "--global", "--ignore-scripts", "--no-fund", "--no-audit"])
+
+/** The newest published version, or null when the registry did not answer. */
+export async function latestOnRegistry(name) {
+  try {
+    const meta = await getJson(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`)
+    return meta?.version || null
+  } catch {
+    return null
+  }
+}
+
+function installedVersion(repoRoot) {
+  try {
+    return JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).version || null
+  } catch {
+    return null
+  }
+}
+
+/** 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())
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The frozen shape of the one other question this tool asks npm: where its
+ * global prefix is, whose `bin` is where `npm install --global` put the
+ * `omakit` command. Read-only; tests/unit/read-only.test.mjs holds npm to
+ * this shape, `root --global` and the install above, and to this file.
+ */
+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())
+  } catch {
+    return null
+  }
+}
+
 function git(dir, args) {
   return execFileSync("git", ["-C", dir, ...args], {
     encoding: "utf8",
@@ -70,7 +126,7 @@ export function isExpectedRemote(url, expected = REPOSITORY) {
  *   a way to point the command at somebody else's repository, because nothing
  *   on the command line reaches it.
  */
-export async function upgrade({ repoRoot, stream = process.stdout, dryRun = false, expectedRemote = REPOSITORY }) {
+export async function upgrade({ repoRoot, stream = process.stdout, dryRun = false, expectedRemote = REPOSITORY, latest = latestOnRegistry, npmRoot = npmGlobalRoot, name = "omakit" }) {
   const c = styler(colourEnabled(stream))
   const out = (line = "") => stream.write(`${line}\n`)
   const lines = (list) => { for (const line of list) out(line) }
@@ -83,13 +139,10 @@ export async function upgrade({ repoRoot, stream = process.stdout, dryRun = fals
   const ok = (text) => out(`${mark("pass", c)}${wrap(text, { indent: GUTTER }, c).join("\n").trimStart()}`)
 
   if (!existsSync(join(repoRoot, ".git"))) {
-    const kind = installKind(repoRoot)
-    return refuse(
-      kind === "distro"
-        ? "this is a distro package under /usr, so omakit leaves upgrades to pacman."
-        : "this is an npm package install, so omakit leaves upgrades to npm.",
-      upgradeCommand(repoRoot),
-    )
+    if (installKind(repoRoot) === "distro") {
+      return refuse("this is a distro package under /usr, so omakit leaves upgrades to the package manager.", upgradeCommand(repoRoot))
+    }
+    return upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, refuse, note, ok, out, lines, c })
   }
 
   let remote
@@ -177,3 +230,60 @@ export async function upgrade({ repoRoot, stream = process.stdout, dryRun = fals
   lines(wrap("The marketplace pin did not move: this updated the tool, not the commit its rules are read from. `omakit doctor` says whether that pin is behind, and docs/UPSTREAM_CONTRACT.md says what moving it involves.", {}, c))
   return { ok: true, changed: true, from: before, to: after, commits: log.length }
 }
+
+/**
+ * The npm route. `latest` and `npmRoot` are injectable for the tests only, the
+ * way `expectedRemote` is: nothing on the command line reaches them.
+ */
+async function upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, refuse, note, ok, out, lines, c }) {
+  const root = resolve(repoRoot)
+  const globalRoot = npmRoot()
+  if (!globalRoot) {
+    return refuse("this is an npm package install, but no `npm` is on PATH to update it with.", `npm install --global ${name}@latest`)
+  }
+  if (root !== join(globalRoot, name)) {
+    return refuse(
+      `this omakit is installed at ${root}, but the npm on PATH installs global packages under ${globalRoot}. Updating with a different npm would leave this one where it is.`,
+      `npm install --global ${name}@latest`,
+    )
+  }
+  const current = installedVersion(root)
+  const spinner = progress({ stream: stream === process.stdout ? process.stderr : stream })
+  spinner.phase("asking the npm registry for the newest published version")
+  const newest = await latest(name)
+  spinner.done()
+  if (!newest) {
+    return refuse("the npm registry did not answer, so there is nothing to compare against.", "Connect to the network, then run `omakit upgrade` again.")
+  }
+  if (newest === current) {
+    ok(`already current at ${current}, the newest published version`)
+    out()
+    lines(wrap("The marketplace pin is a separate thing and is never touched here. `omakit doctor` says whether it is behind.", {}, c))
+    return { ok: true, changed: false, version: current }
+  }
+  const spec = `${name}@${newest}`
+  if (dryRun) {
+    note(`${newest} is published, this is ${current}; not applied (--dry-run)`)
+    out(`${" ".repeat(GUTTER)}${c("prose", `npm ${[...NPM_UPGRADE_ARGS, spec].join(" ")}`)}`)
+    out()
+    lines(action("omakit upgrade", c, { indent: 0 }))
+    return { ok: true, changed: false, version: current, available: newest }
+  }
+  spinner.phase(`npm install --global ${spec}`)
+  try {
+    execFileSync("npm", [...NPM_UPGRADE_ARGS, spec], { 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"
+    return refuse(`npm could not install ${spec}: ${reason.replace(/^npm (?:error|ERR!)\s*/, "")}`, `npm ${[...NPM_UPGRADE_ARGS, spec].join(" ")}`)
+  }
+  spinner.done()
+  const after = installedVersion(root)
+  if (after !== newest) {
+    return refuse(`npm finished, but ${root} reports ${after || "no version"} rather than ${newest}.`, `npm ${[...NPM_UPGRADE_ARGS, spec].join(" ")}`)
+  }
+  ok(`${current} to ${after}, through the npm that installed it`)
+  out()
+  lines(wrap("The marketplace pin did not move: this updated the tool, not the commit its rules are read from. `omakit doctor` says whether that pin is behind, and docs/UPSTREAM_CONTRACT.md says what moving it involves.", {}, c))
+  return { ok: true, changed: true, from: current, to: after }
+}

package/tools/marketplace/usage.mjs

@@ -72,9 +72,9 @@ export const COMMANDS = Object.freeze([
   {
     signature: "omakit upgrade [--dry-run]",
     lines: [
-      "Fast-forward this checkout of omakit itself. Refuses a dirty tree, an",
-      "unexpected remote and anything that is not a fast-forward. Never moves",
-      "the marketplace pin.",
+      "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.",
     ],
   },
   {
@@ -110,9 +110,10 @@ export const TARGET_NOTE = "<target> is a local Git repository path, or <https u
  */
 export const AUTHENTICATION = Object.freeze([
   "Read-only, and optional. omakit uses your `gh` login if you have one, and",
-  "otherwise goes unauthenticated. `submit` and `verify` need no network at",
-  `all; \`watch\` and \`parity\` are capped at ${UNAUTHENTICATED_LIMIT} requests an hour without a`,
-  "login. omakit never writes a credential anywhere.",
+  "otherwise goes unauthenticated. `verify` needs no network; `submit` reads",
+  "two things online and `--offline` turns both off; `watch` and `parity` are",
+  `capped at ${UNAUTHENTICATED_LIMIT} requests an hour without a login. omakit never writes a`,
+  "credential anywhere.",
 ])
 
 /**