omakit 0.1.2 → 0.1.4

package/README.md

@@ -2,6 +2,8 @@
   <img src="docs/media/banner.gif" alt="omakit" width="440">
 </p>
 
+[![Built for Omarchy](https://raw.githubusercontent.com/tcballard/omarchy-badges/85f859029e236e784e7b05ada6dbe73506d07a91/badges/v1/built-for-omarchy.svg)](https://github.com/tcballard/omarchy-badges)
+
 **Everything knowable about an Omarchy Quattro plugin submission, checked
 before you post it:** the tree, the manifest, the form, the commit, and the
 marketplace's own security baseline with its outcome reported as it is. A
@@ -53,6 +55,13 @@ 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
@@ -68,9 +77,10 @@ omakit setup
 | 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: `npm i -g omakit@latest` for
-the package, `omakit upgrade` for a clone; `omakit doctor` says when a newer
-version is published. Nothing in omakit updates itself, and
+`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
@@ -101,7 +111,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
 ```
 
@@ -120,11 +130,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
@@ -140,7 +151,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,
@@ -160,17 +175,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`. `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
@@ -178,7 +196,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.2",
+  "version": "0.1.4",
   "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

@@ -24,16 +24,30 @@ comes from `origin`. You supply the category and the tags, because nobody else
 can: they are an editorial choice about where the plugin belongs.
 
 If you do not know which category and tags are allowed, run the command without
-them. The failing checks print the controlled lists, read from the pinned form.
+them: that is a usage error (exit 2) whose message lists the controlled values,
+read from the pinned form, before any check runs. With `--json` the same lists
+come back under `usage`.
 
 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
 
 Exit code 0 means every blocking check passed and the output contains the issue
-title and body. Exit code 1 means it refused, and no body was produced.
+title and body. Exit code 1 means it refused, and no body was produced. Exit
+code 2 is a usage error: nothing was checked.
+
+A check drawn as `▒ ?` did not run because one it depends on failed; its detail
+names that check. It is not a failure of its own, and the closing refusal lists
+root causes only. Fix those.
 
 Each check names a source. `[marketplace-pin]` is the marketplace's own rule, read
 from a pinned checkout. `[omakit]` is this tool's own check, derived from public

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/cli.mjs

@@ -17,7 +17,8 @@ import { fileURLToPath } from "node:url"
 import { ensurePin, MARKETPLACE_PIN } from "./pin.mjs"
 import { marketplaceBaselineSection } from "./verify.mjs"
 import { resolveSubject, SubjectError } from "../subject/resolve.mjs"
-import { submitPreflight } from "./submit.mjs"
+import { missingSubmitFlags, submitPreflight } from "./submit.mjs"
+import { submissionContract } from "./form.mjs"
 import { validationWatch } from "./watch.mjs"
 import { renderSubmit, renderWatch, renderDoctor } from "./report.mjs"
 import { doctor } from "./doctor.mjs"
@@ -26,7 +27,7 @@ import { upgrade } from "./upgrade.mjs"
 import { progress } from "./progress.mjs"
 import { banner, bannerEnabled } from "./banner.mjs"
 import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.mjs"
-import { action, colourEnabled, GUTTER, mark, styler, wrap } from "./style.mjs"
+import { action, colourEnabled, GUTTER, labelled, mark, styler, wrap } from "./style.mjs"
 import { omakitCacheDir } from "./paths.mjs"
 import { parityOutput } from "./parity-output.mjs"
 
@@ -55,11 +56,12 @@ const REMEDY = Object.freeze({
 /**
  * Every failure, in one register, on stderr. `usage` errors carry the
  * signature that was expected, so the remedy is the reference and not a
- * restatement of the message.
+ * restatement of the message. `body` is extra labelled lines between the
+ * message and the arrow, for a usage error that has values to list.
  */
-function fail(code, message, exit = 1, remedy = REMEDY[code]) {
+function fail(code, message, exit = 1, remedy = REMEDY[code], body = () => []) {
   const c = styler(colourEnabled(process.stderr))
-  const lines = [`${mark("fail", c)}${c("name", code)}`, ...wrap(message, { indent: GUTTER }, c)]
+  const lines = [`${mark("fail", c)}${c("name", code)}`, ...wrap(message, { indent: GUTTER }, c), ...body(c)]
   if (remedy) lines.push(...action(remedy, c))
   process.stderr.write(`${lines.join("\n")}\n`)
   process.exit(exit)
@@ -96,6 +98,28 @@ function emit(args, text) {
 async function cmdSubmit(args) {
   const target = positionals(args)[0]
   if (!target) fail("usage", "submit needs a target: `omakit submit <target> --category <c> --tags <a,b>`", 2)
+  // A missing category or tag list is a usage error, decided before any check
+  // runs and before the spinner starts: nothing can be rendered without them,
+  // and the values the form accepts are the answer, read from the pin.
+  let usage = null
+  try {
+    usage = missingSubmitFlags(await submissionContract({ repoRoot: ROOT }), { category: option(args, "--category"), tags: option(args, "--tags") })
+  } catch (error) {
+    failFrom(error)
+  }
+  if (usage) {
+    if (args.includes("--json")) {
+      process.stdout.write(`${JSON.stringify({ usage }, null, 2)}\n`)
+      process.exit(2)
+    }
+    const flags = usage.missing.join(" and ")
+    fail("usage", `submit needs ${flags}: ${usage.missing.length === 1 ? "it is" : "they are"} an editorial choice nobody else can make, from the pinned form's own lists.`, 2,
+      `omakit submit ${target} --category <c> --tags <a,b>`,
+      (c) => [
+        ...labelled("categories", usage.categories.join(", "), c),
+        ...labelled(`tags, 1 to ${usage.maximumTags}`, usage.tags.join(", "), c),
+      ])
+  }
   const spinner = args.includes("--json") ? { phase: () => {}, done: () => {} } : progress()
   let result
   try {

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,
+  }
+}