omakit 0.1.9 → 0.2.1

package/README.md

@@ -2,51 +2,13 @@
   <img src="docs/media/banner.gif" alt="omakit" width="440">
 </p>
 
-[![Built for Omarchy: App](https://raw.githubusercontent.com/tcballard/omarchy-badges/75975e5b5bf75e7ede3764bcd2950046f7abfe2c/badges/v1/omarchy-app.svg)](https://github.com/tcballard/omarchy-badges)
+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.
 
-**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
-submission is judged at one exact commit and drifts from it the moment you
-push; `watch` says when that has happened. All of it runs on your own machine
-and publishes nothing: no issue, no comment, no label, nobody's attention spent
-until you choose to.
+[![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 submit refusing a plugin with no license, a README that never says how to uninstall, and a reserved plugin id](docs/media/submit.gif)
-
-The plugin above is refused for three things the marketplace itself refuses,
-and warned about a fourth: it ships instruction files an agent will read once
-installed. **103 marketplace issues mention exactly that, and no automated check
-reports it, so today an author finds out from a human review round.** It is a
-warning and not a refusal, because the marketplace does list plugins that ship
-them: 6 of 34 inspected do, at the commit that was listed.
-
-```bash
-omakit submit <plugin-repo> --category Widgets --tags bar,quickshell
-```
-
-Fifteen checks, each naming its source and, when it fails, the measured reason it
-exists. A blocking failure produces no submission body at all, because a refusal
-that still hands you the body is only a suggestion.
-
-## Why it exists
-
-Four numbers, all measured on public marketplace data on 2026-09-12. Method,
-limits and the rest of the figures: [docs/MEASUREMENTS.md](docs/MEASUREMENTS.md).
-
-| Measured | Consequence |
-| --- | --- |
-| 39 submissions fell out on the title prefix alone, and 11 more are malformed in the body, one by a single word | the format is generated from the pinned form and judged by the marketplace's own parser |
-| 1,215 of the 2,916 listings with a recorded baseline needed a human to look, because of a capability | the official baseline runs locally on the exact commit first, and names the capability |
-| 103 issues mention agent-control files, which no automated check reports | submit names every one with its remedy, before a reviewer has to |
-| 73% of parked submissions have a HEAD the marketplace never saw; 46% of the maintainer's own revalidation requests never produced one | a validation watch that names the one action which re-runs validation |
-
-It does not claim to unblock the maintainer. His review writing barely repeats,
-his median time from submission to publication is hours, and the queue waiting on
-him is a median half a day old. The honest size of what this saves him is the
-staleness paragraph he has written by hand on 358 issues, roughly 5.5% of his
-review writing. The rest of the benefit is the submitter's.
-[docs/MARKETPLACE.md](docs/MARKETPLACE.md) states that in full.
+`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
 
@@ -55,203 +17,65 @@ npm install --global omakit
 omakit setup
 ```
 
-If `omakit` is not found afterwards, npm's global `bin` is not on your PATH
-(measured: an npm global prefix under `~/.local/share` 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.
+See [docs/INSTALL.md](docs/INSTALL.md) for the clone route, PATH, requirements and upgrading.
 
-Or read what you run:
+## Commands
+
+| 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) | The commit the marketplace validated, against the plugin's current HEAD. |
+| [`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 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. |
+
+### `submit`
 
 ```bash
-git clone --depth 1 https://github.com/mtolhuys/omakit ~/.local/share/omakit
-ln -s ~/.local/share/omakit/bin/omakit ~/.local/bin/omakit
-omakit setup
+omakit submit <plugin-repo> --category Widgets --tags bar,quickshell
 ```
 
-| Needs | Why |
-| --- | --- |
-| 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` |
+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).
 
-`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.
+![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)
 
-## Watch
+Read more: [docs/SUBMIT.md](docs/SUBMIT.md).
 
-![omakit watch reporting that a validated commit has fallen behind](docs/media/watch.gif)
+### `watch`
 
 ```bash
 omakit watch <submission-issue-url>
 ```
 
-That submission passed validation and passed the security baseline with zero
-findings. It is stuck because the marketplace validated one exact commit, and
-the only action that makes it validate a newer one is editing the issue body. Pushing the fix does
-nothing. Commenting "fixed in `abc123`" does nothing. **73% of the 464
-submissions parked in their author's court have a default-branch HEAD the
-marketplace never saw.**
+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).
 
-## Commands
+![omakit watch reporting that a validated commit has fallen behind](docs/media/watch.gif)
+
+Read more: [docs/VALIDATION_WATCH.md](docs/VALIDATION_WATCH.md).
 
-Agent-first: the expected user is a coding agent submitting a plugin on an
-owner's behalf. Zero dependencies, plain ESM, one entry point, no build step.
+### `weigh`
 
 ```bash
-omakit setup                 # the environment, the pin, tab completion, and what to try first
-omakit submit <plugin-repo>  # every check, the issue title and body; asks for a category and tags at a terminal
-omakit watch <issue-url>     # the commit the marketplace validated, against the plugin's current HEAD
-omakit verify <plugin-repo>  # the official security baseline over the local transport; --json for the document
-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               # updates omakit through its own installer: npm, or a fast-forward
-omakit help --agent          # the operating instructions, for the agent running this
+omakit weigh <plugin-id-or-dir>
 ```
 
-![omakit setup checking the environment and fetching the pinned checkout](docs/media/setup.gif)
-
-`omakit setup` checks the environment, fetches the marketplace checkout that
-every rule is read from, installs tab completion for the shell you run it from
-(bash, zsh or fish, read from `$SHELL`), and tells you what to try first. It is
-idempotent. The fetch takes about 2 seconds and 15 MB, because it takes only the
-seven files omakit reads out of that repository rather than the 325 MB it is at
-that commit. The completion script knows the subcommands and their flags,
-completes a directory for `<target>`, and offers the categories and tags the
-pin's submission form actually has.
-
-`omakit verify` prints the official baseline result alone, with no Omakit
-check around it: the subject, the pin, the transport and what the local
-adapter assumes, then the marketplace's own outcome, each finding as a block
-with its rule id, whether it blocks publication under the pinned policy, the
-file and line, and the official text verbatim, then the marketplace's own
-statement. `--json` prints the document itself, unchanged from earlier
-releases, and `--out <file>` writes it; agents and the skills use those.
-
-`omakit submit` reads the marketplace's registry first, and a run has three
-outcomes. `READY`, exit 0: every blocking check passed and the title and body
-follow. `REFUSED`, exit 1: a blocking check failed and no body is produced.
-`LISTED`, exit 0: the plugin is already listed by its own repository (the
-manifest id is in the catalog, and the listing's repository is the subject's
-declared `origin`, compared as owner and name), so the submission form is not
-the route. Nothing is wrong and nothing was refused: `identity.available`
-passes with the listing's record (since when, which commit, verified or not),
-the five checks that exist only for the body are omitted, nothing is asked,
-and the closing block names the commit the marketplace lists, the local
-commit, whether they are the same, and the marketplace's verification form
-with the choice that lists a newer commit, read from the pin's
-`verify-plugin.yml`. Measured on 0.1.6: this state printed `FAIL
-identity.available`, `REFUSED`, and "Fix it, then run submit again" under a
-remedy that said there was nothing to submit. An id taken by another
-repository, a retired id or a reserved one is still refused. In `--json`, the
-outcome is `outcome: "ready" | "refused" | "listed"`, `ready` stays a boolean
-that is true for the first only, and a listed run carries a `listing` object.
-
-An unlisted plugin needs a category and tags, and they are an editorial
-choice nobody else can make: at a terminal it asks, once each, with the form's
-own lists numbered and the marketplace's own default for the manifest's kinds
-offered where it is on the list; in a pipe, from an agent, or with `--json` it
-is the usage error with the same lists, exit 2. A listed plugin is asked for
-neither. A `READY` or `REFUSED` report ends with the command line that repeats
-the run without asking, and `--json` carries it as `reproduce`.
-
-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; `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
-terminal shows and why is [docs/TUI.md](docs/TUI.md); which index each role
-gets, measured over all 32 installed themes, is
-[docs/PALETTE.md](docs/PALETTE.md).
-
-## What it is doing
-
-Nothing about the submission format is written down in this repository. The
-title prefix, the six form headings in order, the nine categories, the thirteen
-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. 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`.
+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).
 
-This is why the tool is Node: the marketplace's scanner, form parser and
-catalog builder are Node modules, and omakit runs them verbatim from the
-pinned commit instead of reimplementing their rules, where a different
-language would mean a copy that can drift.
-
-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,
-and never restates the result as a safety claim: the baseline does no data-flow
-analysis and is not a security review, and the output says so in the
-marketplace's own words.
-
-Every check is labelled. `[marketplace-pin]` is the marketplace's rule, read from
-the pin. `[omakit]` is this project's own check, derived from public issue data.
-Those are not marketplace policy and do not claim to be.
-
-## Updating
-
-Two different things could mean "upgrade" here, and only one of them may ever
-move on its own. That distinction is now enforced rather than argued.
-
-**The tool:**
-
-```bash
-omakit upgrade          # the npm package, or a clone: through its own installer
-omakit upgrade --dry-run
+```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
 ```
 
-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.
+It restarts your shell and asks first. Memory is a shell fact; CPU and child processes are the weight.
 
-**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
-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 in something omakit reads from it, names which paths changed,
-and then leaves it alone: `registry.json` and `site/catalog.json` moving is
-fine, because those are read live from HEAD (about 140 commits a day touch
-only `registry.json`, so "behind" alone would be true of every run); the
-marketplace's code or forms moving is a note, and what you can do about it
-is run `omakit upgrade`, since a newer omakit may already carry the new pin,
-and otherwise open an issue naming the paths. 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.
+Read more: [docs/WEIGH.md](docs/WEIGH.md).
 
 ## Evidence, not claims
 
-```bash
-npm test        # node --test, no dependencies; green from `git archive` too
-```
-
 | Claim | Proof |
 | --- | --- |
 | The local transport produces the marketplace's own result | 30 of 30 identical, [docs/evidence/parity/](docs/evidence/parity/) |
@@ -259,17 +83,20 @@ npm test        # node --test, no dependencies; green from `git archive` too
 | 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: findings about a specific third-party plugin are not this project's
-to publish.
+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.
 
 ## 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/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 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "omakit",
-  "version": "0.1.9",
-  "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.",
+  "version": "0.2.1",
+  "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",
   "keywords": [

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

@@ -0,0 +1,102 @@
+---
+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.
+---
+
+# Checking a plugin while you build it
+
+## Run this the way you run a test suite
+
+After every meaningful change to an Omarchy plugin, run both, from the
+plugin's repository root or with its path:
+
+```bash
+omakit verify <path-to-the-plugin-repo> --json
+omakit submit <path-to-the-plugin-repo> --category <category> --tags <a,b> --json --offline
+```
+
+`verify` is the marketplace's own security baseline over this exact commit,
+verbatim, with no Omakit check around it. `submit` is every pre-submission
+check the marketplace applies, rendered from the marketplace's own form and
+judged by the marketplace's own parser.
+
+**Always pass `--category` and `--tags`.** A run without them asks a person
+at a terminal, and an agent must never wait on a keyboard. If you do not know
+the allowed values, run once without them in a pipe or with `--json`: that is
+a usage error (exit 2) whose message lists the controlled values, read from
+the pinned form. Pick the category and tags with the owner; they are an
+editorial choice about where the plugin belongs.
+
+`--offline` belongs in this loop and nowhere else: it skips the one check that
+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`.
+
+## If omakit is not installed
+
+```bash
+npm install --global omakit   # Omarchy ships Node and npm through mise
+omakit doctor                 # node, git, the pin, the credential source, and whether omakit is on PATH
+```
+
+If `omakit` is not found after the install, run
+`"$(npm prefix --global)/bin/omakit" setup`: it prints the one line that puts
+npm's bin on PATH for the shell in `$SHELL`. Keep it current with
+`omakit upgrade`. The first `submit` or `verify` needs the pin: `omakit pin`
+fetches a sparse read-only checkout of one marketplace commit under
+`$XDG_CACHE_HOME/omakit/marketplace` (or `~/.cache/omakit/marketplace`).
+
+## Reading the result
+
+`submit --json` ends with `outcome`:
+
+- `ready`, exit 0: every blocking check passed. The plugin would be accepted
+  by the marketplace's automated checks as it is now.
+- `refused`, exit 1: a blocking check failed. `blocking` lists the root
+  causes; each check carries `detail`, `paths`, `remedy` and `why`.
+- `listed`, exit 0: the plugin is already listed by this repository.
+  `listing` names the reviewed commit and whether the local commit is it.
+
+Each check has a `verdict`: `pass`, `fail`, `unknown` (it could not run
+because a check it depends on failed; fix that one first) or `skipped` (not
+run under `--offline`). `severity` is `blocking` or `advisory`; an advisory
+check never turns `ready` into `refused`.
+
+Each check names a `source`. `marketplace-pin` is the marketplace's own rule,
+read from the pinned checkout. `omakit` is this tool's own check, derived
+from public issue data with the measurement in `why`. Never describe an
+`omakit` check to the owner as a marketplace requirement.
+
+Fix the cause the remedy names. Do not work around a check, do not strip files
+from the owner's tree on your own, and never change the plugin id to get past
+`identity.available` when the listing is this repository's own.
+
+## What the baseline result means
+
+`verify` and the `baseline.preflight` check report the official outcome:
+
+- `passed`: nothing in the baseline holds the plugin back.
+- `review-required`: no findings, but one or more of the seven capabilities is
+  present, so a maintainer must look at this exact commit. Not a defect; worth
+  explaining in the submission's `--notes` rather than hiding.
+- `needs-fixes`: findings, each with a rule id, the file, and the marketplace's
+  own remedy text. Only `sudoers-dangerous-passwordless-command` and
+  `privileged-process-control-from-shared-temp` block publication under the
+  current enforcement mode; the rest a maintainer may accept for that commit.
+  Fixing them first avoids a human round either way.
+
+Never restate any of this as a safety claim. The baseline performs no data-flow
+analysis and is not a security review; the output says so in the marketplace's
+own words, and so should you.
+
+## The commit rule
+
+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
+round this loop is meant to prevent.
+
+## When the plugin is ready
+
+Hand over to `skills/omarchy-plugin-submit/SKILL.md`. The owner decides
+whether to submit, and you never open the issue yourself.

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

@@ -32,6 +32,10 @@ omakit pin     # once, and after any pin change: fetches the pinned marketplace
 omakit submit <path-to-the-plugin-repo> --category <category> --tags <a,b>
 ```
 
+While a plugin is still being built or changed, run the check loop in
+`skills/omarchy-plugin-check/SKILL.md` instead; this skill is for the
+submission itself.
+
 The pin is a sparse read-only checkout of one marketplace commit under
 `$XDG_CACHE_HOME/omakit/marketplace` (or `~/.cache/omakit/marketplace`). Every
 rule is read from it; nothing about the format is written in the tool.

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

@@ -0,0 +1,128 @@
+---
+name: omarchy-plugin-weigh
+description: Weigh an Omarchy Quattro plugin on the shell, in CPU and child processes, by restarting the shell without it and with it. Use before a submission, after a change that adds a timer, a process or a file watcher, or when asked how heavy a plugin is. Restarts the person's shell, so it must never run without their explicit agreement.
+---
+
+# What a plugin weighs on the shell
+
+## The one thing to get right
+
+**This command restarts the shell.** `omakit weigh` measures a plugin by
+starting the person's `omarchy-shell` without the plugin and with it, several
+times, and it edits `~/.config/omarchy/shell.json` for the duration. Every
+other omakit command is read-only; this one is not. So:
+
+- Never run it with `--yes` unless the person has just agreed, in this
+  conversation, to have their shell restarted that many times. The command
+  prints the count and the estimated minutes before it asks; put those in
+  front of the person and wait for their answer.
+- Never run it while they are in the middle of something on that desktop.
+  The bar, every panel and every plugin go away and come back on each
+  restart, (1 + plugins) × runs times, and a restart costs about a minute
+  (a 30 s settle and a 15 s window after each). One plugin at three runs is
+  six restarts, about five minutes. `--all` is sized for a lab machine, not
+  a working desktop: 47 enabled plugins is 144 restarts and about two hours
+  at three runs, three and a half at five. Offer `--all` only for a machine
+  nobody is using.
+- Never run it on your own machine's shell as a stand-in for theirs. The
+  weight is the weight on the machine the plugin runs on.
+
+Without `--yes`, from a pipe or with `--json`, the command prints the plan
+and refuses with `█ NOT WEIGHED` (exit 2); nothing is touched. That refusal
+is the correct outcome of an agent running it unasked. The same word, with
+one sentence naming what is missing, is how it refuses an Omarchy it cannot
+weigh on: no `omarchy-shell` (an install older than the Quattro shell), no
+`omarchy-restart-shell`, no readable version, a shell that does not answer
+`ping`, or an IPC target without the four methods it relies on. Report that
+sentence to the person as it is; do not work around it.
+
+## When to run it
+
+- Before submitting: the README sentence it produces belongs in the
+  plugin's README, next to what the plugin does. The question a person
+  asks is how heavy it is; this answers it with a measurement.
+- After a change that adds a `Timer`, a `Process`, a `FileView` with
+  `watchChanges`, a `SystemClock`, or a `Connections` to a busy service. A
+  declared interval says nothing about what runs; this measures it.
+- When the owner asks how heavy the plugin is. Answer with the measured
+  figures and their noise floor, never with an estimate from the source.
+
+## Run it
+
+```bash
+omakit weigh <plugin-id-or-dir>                # one plugin, asks first
+omakit weigh <plugin-id-or-dir> --yes --json   # only after the person agreed
+omakit weigh --all --yes                       # every enabled third-party plugin
+```
+
+The plugin must be installed and enabled in the running shell: the
+measurement puts it back exactly where the person has it. A plugin of kind
+`bar` is refused (replacing the whole bar is not a weight), and so is a locked
+session. `--runs` (default 3), `--window` (default 15 s) and `--settle`
+(default 30 s) trade time for a lower noise floor; leave them at their
+defaults unless the floor is too high to answer the question.
+
+If `omakit` is not installed: `npm install --global omakit` (Omarchy ships
+Node and npm through mise), then `omakit doctor`. `weigh` needs no pin and no
+network.
+
+## Reading the verdicts
+
+The header prints the **noise floor** once: the spread of the baseline's
+own CPU across its runs. A plugin whose median CPU delta is not larger than
+that floor has **no measurable CPU**, in those words, and the row is `ok`.
+A row is `note` when CPU is above the floor, and `?` when no run of it
+completed.
+
+- `no measurable CPU` means the measurement cannot tell the plugin from
+  nothing at this run count and window. It does not mean zero. Say "no
+  measurable CPU against a floor of N%", with the number.
+- `above noise on CPU` is a measured weight. Report the median and its
+  spread, and the children line separately: a plugin that adds 0.1% in the
+  shell and runs a 40 MB helper weighs both.
+- **Memory is the shell's, not the plugin's, for now.** The memory delta is
+  printed with its spread, and the header labels it "within the shell's own
+  startup variance (N MB)". Never turn it into a sentence about the plugin
+  ("costs N MB", "under N MB"): the shell comes to rest on one of two
+  levels 35 MB apart after a restart, and that difference is not the
+  plugin's (`docs/MEASUREMENTS.md`, C1 and C2). If the owner asks about
+  memory, say exactly that and show the figure with the variance beside it.
+- A negative median is printed as measured. Do not round it to zero and do
+  not explain it away; it means the delta is inside the noise.
+- Never describe a weight as acceptable or unacceptable. The verdict is a
+  comparison with the floor; whether the number is fine is the owner's
+  call, made with the number in front of them.
+
+In `--json`, each row carries `verdict.memory` and `verdict.cpu`
+(`within-noise`, `above-noise`, `unknown`), `withinNoise` with the floors,
+the stats objects (`median`, `spread`, `min`, `max`, `runs`), and `origin`
+naming the `/proc` paths and the arithmetic. `config.md5Before` and
+`config.md5After` must be equal and `config.restored` true; if they are not,
+tell the person at once and name `config.backup`, which is kept. The full
+contract is `docs/WEIGH.md`.
+
+## What to paste into the README
+
+The last thing the command prints is the sentence, per plugin, and the path
+of the JSON that is its evidence:
+
+```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
+```
+
+Paste it as it is, under a heading such as "What it weighs", and keep the
+JSON with the plugin's evidence or link to it. It names the CPU floor even
+when the plugin is under it, and the child processes with their memory;
+it never names the shell's memory, and neither should you in that README.
+Re-run and replace the sentence after any change that adds a timer,
+a process or a watcher; a sentence measured on an older commit is a claim
+about a plugin that no longer exists.
+
+## What the measurement does not know
+
+Per-plugin memory inside the shell is knowable only by this A/B, because Qt
+allocates from shared heaps. RSS never falls when a plugin is unloaded and
+every bar widget rebuilds on any layout change, so nothing here measures a
+running shell before and after; both sides start fresh. The weight of a panel
+only while it is open, and any weight that depends on another plugin, are not
+measured. Do not extrapolate either.

package/tools/marketplace/README.md

@@ -28,12 +28,29 @@ local commit through the transport seam the marketplace tests itself
 | `report.mjs` | Text rendering of submit, watch, doctor and verify 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. |
+| `options.mjs` | Every option every command accepts, in one table, and the parser that reads a command line against it before anything runs; `tests/unit/options.test.mjs` holds the help signatures, and through them the completion scripts, to the table. |
 | `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. |
+| `completion-check.mjs` | Whether tab completion actually works: a frozen probe per shell run interactively, asking the loader to load `omakit` the way TAB does; the one marked block `setup` may append to an rc file after a yes, looked for by its marker first; the installed script's version and pin read from its first line; `doctor`'s `omakit.completion`; and the once-a-day stale notice. |
 | `banner.mjs` | The wordmark, on a bare `omakit` and in `setup` only. |
 | `effect.mjs` | The one text effect: the wordmark through `ttfx` where it is drawn, with frozen arguments, a hard budget, no colour of its own, and nothing at all when `ttfx` is not there. |
 | `progress.mjs` | The progress line, on stderr, only when a person is looking. |
 | `paths.mjs` | Omakit's cache directory, following XDG, and `withHomeAbbreviated()`: a path under `$HOME` written as `~/...` for a person, applied where doctor, setup and pin render text and never where a result is built, so `--json` keeps every path absolute. |
-| `cli.mjs` | The one entry point behind `bin/omakit`, and the one register every failure is reported in. `submit` exits on the outcome: 1 for `refused`, 0 for `ready` and `listed`. |
+| `cli.mjs` | The one entry point behind `bin/omakit`, and the one register every failure is reported in. `submit` exits on the outcome: 1 for `refused`, 0 for `ready` and `listed`. `weigh` confirms before its first restart and exits 130 when interrupted, after the restore. |
+
+`tools/weigh/` is `omakit weigh`, the one command that changes the user's own
+machine (docs/WEIGH.md):
+
+| File | Purpose |
+| --- | --- |
+| `weigh/commands.mjs` | The frozen table of Omarchy commands the measurement runs (`omarchy-shell`, `omarchy-restart-shell`, `omarchy plugin list`, `omarchy-plugin-catalog`, `qs list`, the session-lock check, `systemctl --user show-environment`, `getconf`), and the one spawn call site under `tools/weigh/`. |
+| `weigh/proc.mjs` | Reading `/proc`: `utime+stime` and `cutime+cstime` from `stat`, `VmRSS` from `status`, `Pss` from `smaps_rollup`, and a descendant walk by parent id, all against a root that tests point at a directory. |
+| `weigh/config.mjs` | Where `shell.json` is, the pure transform that removes a set of plugin ids from the effective configuration, the byte-for-byte backup, the restore and its md5 verification. |
+| `weigh/stats.mjs` | Median, spread, the stats object, and the within-noise comparison. |
+| `weigh/audit.mjs` | `planWeigh()` reads and decides (what runs, how many restarts, the estimate) and writes nothing; `measureWeigh()` restarts, samples and restores in a `finally`; `buildDocument()` turns the samples into the document. |
+| `weigh/contract.mjs` | The JSON contract of docs/WEIGH.md as a validator, run by the unit tests and by the lab over a real document. |
+| `weigh/list.mjs` | `weigh --list`: every installed plugin with its last weighing from the documents under the state directory, read-only, unweighed enabled plugins first. |
+| `weigh/report.mjs` | The confirmation and the report for a person, drawn with `style.mjs`; the README sentence and the evidence path come last. |
+| `weigh/confirm.mjs` | The one question, at a terminal, on stderr. |
 
 ```text
 omakit pin