--- title: "Usuba Standard v0.1 | Usuba Docs" description: "Usuba Standard v0.1 is the public rulebook the Checker Scripts enforce — what a working Omarchy plugin is, rule by rule." canonical: "https://usuba.dev/docs/standard/" sourceKind: "rendered-html" --- # Usuba Standard v0.1 **Usuba Standard v0.1** is the rulebook the [Usuba Checker Scripts](/docs/checker/install/) enforce. It says what a working Omarchy plugin is. Every failure the Checker Scripts report starts with a rule id from this document, gives the reason, and ends with a `Fix:` hint. This page _is_ the rulebook, not a summary of one: the Checker Scripts are held to it, and you can hold the Checker Scripts to it. ## What it targets [Section titled “What it targets”](#what-it-targets) - **Omarchy 4.0.4-1**, shell tree byte-identical to `basecamp/omarchy` at the pinned snapshot. - **Quickshell on Qt 6.11**, as installed on the reference machine the Checker Scripts are calibrated against. A plugin that passes here is a plugin that loads and runs on that target. The standard claims nothing beyond it. ## Levels [Section titled “Levels”](#levels) Every rule has a level, and the level decides whether a finding fails the plugin. Level What it means **error** Always fails. **high** A heuristic finding that fails, reported as `heuristic/high` so a human can overrule it. **medium**, **low** Warnings only. They never fail a plugin. ## Rule families [Section titled “Rule families”](#rule-families) A rule id is `USB-`. The family says where the rule looks. Prefix Family Example `USB-T` Task contract: the answer is plugin files, not prose `USB-T03` Answer is files, not leaked reasoning `USB-M` Manifest: `manifest.json`, ids and entry points `USB-M02` Entry points are QML files `USB-Q` QML types and imports `USB-Q01` Every QML type resolves `USB-A` APIs: real types, members and signals only `USB-A01` Only real APIs are called `USB-B` Binaries and commands that must exist on the target `USB-B02` No X11-only tools `USB-F` Files the plugin ships and references `USB-F01` Referenced helper scripts are shipped `USB-J` JavaScript correctness inside QML `USB-J01` No undeclared identifiers `USB-S` Safety: writes, privilege, destructive commands `USB-S03` No clearly destructive commands `USB-H` Heuristics: real data and real behaviour `USB-H02` No hardcoded readings shown as live data `USB-R` Runtime: the plugin in a real Omarchy shell `USB-R03` Visible, legible, on-screen ## The rules [Section titled “The rules”](#the-rules) ### Task contract [Section titled “Task contract”](#task-contract) Rule Level What it checks `USB-T01` error The answer contains plugin code, not a manifest alone `USB-T02` error The file the task asked for is delivered, in full `USB-T03` error The answer is files, not leaked reasoning or self-correction ### Manifest [Section titled “Manifest”](#manifest) Rule Level What it checks `USB-M01` error `manifest.json` is valid JSON with an id `USB-M02` error Entry points are QML files `USB-M03` error The plugin ships QML `USB-M04` error The entry root is a shell surface `USB-M05` error The id is namespaced and not reserved ### QML types and imports [Section titled “QML types and imports”](#qml-types-and-imports) Rule Level What it checks `USB-Q01` error Every QML type resolves, against a positive allowlist `USB-Q02` error Every import exists `USB-Q03` error No Qt 5 APIs `USB-Q04` error Valid QML structure `USB-Q05` error A `QtObject` does not host child objects ### APIs [Section titled “APIs”](#apis) Rule Level What it checks `USB-A01` error Only real APIs are called `USB-A02` error Signal handlers name real signals `USB-A03` error QML types are not constructed with `new` `USB-A04` error Methods called on an id exist `USB-A05` error No Node, browser or C++ idioms in QML JavaScript `USB-A06` error `qs.Commons` members exist `USB-A07` error Only real `shell` members are used `USB-A08` medium Read-only bar facade properties are not assigned ### Binaries and commands [Section titled “Binaries and commands”](#binaries-and-commands) Rule Level What it checks `USB-B01` error Binaries in shell strings exist on the target `USB-B02` error No X11-only tools `USB-B03` error `hyprctl` and `hyprsunset` invocations are valid `USB-B04` error No `hyprctl reload` after `hyprctl keyword` `USB-B05` error `argv[0]` exists on the target `USB-B06` error CLI flags are real ### Shipped files [Section titled “Shipped files”](#shipped-files) Rule Level What it checks `USB-F01` error Referenced helper scripts are shipped ### JavaScript correctness [Section titled “JavaScript correctness”](#javascript-correctness) Rule Level What it checks `USB-J01` error No undeclared identifiers `USB-J02` error Commands never receive `undefined` `USB-J03` error No `Qt.resolvedUrl("~")` `USB-J04` error `argv` paths are local paths, not URLs `USB-J06` error Loader-passed properties are not read only in `onCompleted` ### Safety [Section titled “Safety”](#safety) Rule Level What it checks `USB-S01` high / medium Writes outside the plugin directory are flagged `USB-S02` high Privileged or remote-exec commands are flagged `USB-S03` error No clearly destructive commands ### Heuristics [Section titled “Heuristics”](#heuristics) Rule Level What it checks `USB-H01` high / medium Real data, not simulated `USB-H02` high / medium No hardcoded readings shown as live data `USB-H03` high / low Handlers do something besides `console.log` `USB-H04` high No demo click handlers `USB-H05` error Not a placeholder UI `USB-H06` error No placeholder data patterns `USB-H07` high No placeholder endpoints or credentials ### Runtime [Section titled “Runtime”](#runtime) Rule Level What it checks `USB-R01` error Loads and registers in the real shell `USB-R02` error No runtime JavaScript or QML errors `USB-R03` error Visible, legible, on-screen `USB-R04` error Runtime commands are valid ## How the Checker Scripts enforce it [Section titled “How the Checker Scripts enforce it”](#how-the-checker-scripts-enforce-it) Three passes, in order: 1. **Static checks.** Reads the plugin’s files against the type and member allowlists, which are generated from the Quickshell and Qt builds the runtime uses and from Omarchy’s own shell modules — so they move with the target, not with a hand-kept list. 2. **The task contract.** When a plugin was written by a model, the answer itself is checked: real files, the file that was asked for, and no leaked reasoning. 3. **The runtime probe.** Boots the real Omarchy shell — Quickshell on a headless compositor, inside a sandbox — loads the plugin, and watches what actually happens: load errors, JavaScript errors, and whether anything visible drew. Every rule above names its reason and a failing example in the canonical rule file, and every finding carries its rule id, so a result you disagree with is a result you can argue with. ## Version [Section titled “Version”](#version) Usuba Standard v0.1, dated 2026-10-13. It moves with the Checker Scripts: when a rule is added, or a level changes, this page and the version change with it. Last updated: Oct 13, 2026 [Previous Reading results](/docs/checker/reading-results/)[Next Model status](/docs/model/) Last updated: Oct 13, 2026 [Previous Reading results](/docs/checker/reading-results/)[Next Model status](/docs/model/)