# Title

`omarchy install app` usage line points at the hyphenated form and obscures the two-arg shape, and `--help` on the direct binary is silently misread (systemic across identity-first commands)

# Body

Filing this as one report because I think the two symptoms share a root and probably a fix, but I'd rather sketch what I'm seeing than lobby for a particular resolution — several directions have real tradeoffs and I'm not sure which one you'd prefer.

## What I hit

Trying to install a package from the CLI, invoked in the natural routed form:

```
$ omarchy install app cowsay
Usage: omarchy-install-app <display-name> <packages>

$ omarchy-install-app cowsay
Usage: omarchy-install-app <display-name> <packages>

$ omarchy-install-app --help
Usage: omarchy-install-app <display-name> <packages>

$ omarchy-install-app -- cowsay
Usage: omarchy-install-app <display-name> <packages>

$ omarchy-install-app literally-anything
Usage: omarchy-install-app <display-name> <packages>
```

The routed `omarchy install app --help` does work (the dispatcher intercepts before exec) and prints the full metadata help. The two arguments are real — the intended shape is `omarchy install app 'Cowsay' cowsay` — but the failure cascade above hides that.

## Why the usage line makes this worse

Someone who ran the dispatched form (`omarchy install app cowsay`) reads the error message, sees `omarchy-install-app`, and immediately hypothesises "the hyphenated form matters — that's why my routed invocation didn't work." They then retype in the hyphen form, get the same error, and the actual signal — "there are TWO required positionals here, not one" — never registers. The two-arg shape is technically visible in `<display-name> <packages>` but it's competing with a stronger and wrong hypothesis about spelling.

Some possible directions:

- Speak in the invocation form the caller actually used (`omarchy install app` vs `omarchy-install-app`), so the error doesn't send them chasing the wrong hypothesis.
- Or, more assertively: don't mention the hyphenated form at all in user-facing output, on the principle that a naive user isn't supposed to know it exists — the dispatched form is the public interface, the hyphenated binary is an implementation detail.
- Always include a concrete example when erroring on args ("`omarchy install app 'Cowsay' cowsay`"), which kills the "wait, what's a display name" question at the same time.

The direct-invocation form of the second option is the one I'd lean toward personally, because if usage lines never show the hyphenated form, users never invoke the hyphenated form directly, and the `--help` problem below becomes a non-issue by construction.

## The `--help` behaviour is systemic across "identity-first" commands

Because most binaries let the dispatcher intercept `--help` and don't handle it themselves, any binary whose first positional is a required identity string reads `--help` as literal data. Spot-checked on `quattro` HEAD:

| Direct invocation | Result |
|---|---|
| `omarchy-install-app --help` | `Usage: omarchy-install-app <display-name> <packages>` |
| `omarchy-install-font --help` | `Usage: omarchy-install-font <display-name> <package> <family>` |
| `omarchy-install-and-launch --help` | `Usage: omarchy-install-and-launch …` |
| `omarchy-theme-set --help` | `Theme '--help' does not exist` |
| `omarchy-theme-remove --help` | `Error: Theme '--help' not found.` |
| `omarchy-font-set --help` | `Usage: omarchy-font-set <font-name>` |
| `omarchy-audio-tuning --help` | `Usage: omarchy-audio-tuning <on\|off\|status\|match\|fronted-sink> [--force]` |

The `omarchy-theme-*` ones are the sharpest example — they say `Theme '--help' does not exist`, which sounds like `--help` is being interpreted as a theme name that just happens not to be installed.

Rough count: 39 of 434 binaries have their own `--help` case; the remaining ~395 rely on the dispatcher. Only the identity-first subset produces this misleading shape, but that's still tens of scripts.

## The `--help` fix has real tradeoffs, so I'd rather ask than propose

A few directions I can see, none obviously right:

- **Per-binary shim** — add `[[ $1 == -h || $1 == --help ]] && exec omarchy <group> <name> --help` as the first line of each affected script. Reuses the dispatcher's help. Simple, but touches N files, and special-casing `--help` at every entry point is exactly the sort of thing that grows: does `--version` get the same treatment next? `--dry-run`? It could become a maintenance kitchen sink of "flags every binary must intercept."
- **Dispatcher-owned preamble** — a small sourced helper (`omarchy-common-header`?) that every binary starts with, which intercepts `--help` and any other future common flags. Centralises the concern but changes the "every bin script is standalone" property that keeps this codebase easy to read.
- **Don't fix `--help` on the direct binary at all** — commit to "the hyphenated form is not a supported user interface." Fix the usage lines to speak the dispatched form, and the problem becomes theoretical for anyone who doesn't already know the hyphenated form exists. Cheapest, most conservative, but leaves the failure mode intact for anyone who does know.
- **A dispatcher-side wrapper** — have the packaging install thin wrappers under `/usr/bin` that all call through `omarchy` rather than exec'ing the binary directly, so `--help` handling exists in exactly one place. Biggest change; probably not worth it just for this.

## One extra example of the same shape

`omarchy-agent-prompt --help` doesn't just print an error — it spawns a ghostty terminal and sends `--help` to the agent as the actual prompt text (which is why my survey caught `info: ghostty version=1.3.1-arch2 …` on stdout). Same identity-first pattern, just louder side effects: the "identity" here is a prompt sent to an LLM, and the wrapper starts a real terminal to run it. Worth including in whichever direction the fix takes.

## Recent adjacent work

- **PR #7843** (merged 2026-08-30) hardened shell-quoting in `install-app`, `install-font`, `install-and-launch`. Deliberately left the argument signature alone.
- **Issue #7127** — `omarchy theme remove` rejecting its own documented display name. Same class ("help/docs advertise a shape the script doesn't accept").

## System

Omarchy 4.0.1-1 (`omarchy` and `omarchy-settings` both 4.0.1-1). Checked source against `basecamp/omarchy` `quattro` HEAD; the two-arg guard is unchanged there.

Happy to draft a PR in whichever direction feels right — I just didn't want to pre-commit to one before hearing which end of the tradeoff you'd rather live with.