> Filed by Claude (Claude Code) on behalf of @whiskeytuesday, who hit this on their machine and reviewed this report before it was filed.

Follow-up to #7183, found while gathering diagnostics for it.

## Summary

Three commands ship in `bin/` upstream but are installed to `/usr/bin` by the `omarchy-settings` package, while the `omarchy` dispatcher only discovers commands in its own directory (`/usr/share/omarchy/bin`, from the `omarchy` package). All three are therefore unreachable through the CLI, and none appear in `omarchy commands --all`:

```
$ omarchy debug --no-sudo --print
Unknown Omarchy command: omarchy debug --no-sudo --print
$ echo $?
127

$ omarchy-debug --no-sudo --print   # works
```

| Command | Declared route (`# omarchy:examples=`) | `omarchy <route>` | In `commands --all` |
|---|---|---|---|
| `omarchy-debug` | `omarchy debug --print --no-sudo` | exit 127 | no |
| `omarchy-debug-idle` | `omarchy debug idle` | exit 127 | no |
| `omarchy-upload-log` | *(none)* | exit 127 | no |

The first two carry routing annotations declaring routes they can never serve.

## Why it matters

**1. The bug template asks every reporter for output from a command the docs spell as unreachable.** `.github/ISSUE_TEMPLATE/bug.yml` requests "the output of `omarchy-debug`". The hyphenated form works, so a reporter who copies it verbatim is fine — but anyone following the CLI convention used everywhere else gets `exit 127`.

**2. The bundled agent skill instructs agents to run the broken form.** `default/agents/skills/omarchy/` is shipped to installed systems and symlinked into `~/.claude/skills/`. On `master` it tells agents, in five places, to run `omarchy debug --no-sudo --print`:

```
SKILL.md:222       omarchy debug --no-sudo --print # Debug info (ALWAYS use these flags)
SKILL.md:228       **IMPORTANT:** Always run `omarchy debug` with `--no-sudo --print` flags ...
SKILL.md:234       omarchy debug --no-sudo --print
contributing.md:26 omarchy debug --no-sudo --print
contributing.md:28 # Interactive variant: `omarchy debug` offers to upload the log ...
```

An agent following the skill to diagnose a user's system gets `exit 127` and no diagnostics.

**Note for #6718:** that open PR rewrites the skill and removes these lines, but reintroduces the same broken invocation in the new text:

```diff
+   omarchy debug --no-sudo --print
+   The same diagnostic report is written to `/tmp/omarchy-debug.log`.
```

Worth fixing in the PR rather than after it merges.

## Root cause

`bin/omarchy` discovers commands by globbing its own directory:

```bash
OMARCHY_BIN_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
...
for file in "$OMARCHY_BIN_DIR"/omarchy-*; do
```

Diffing upstream `bin/` against the installed tree, exactly three files are relocated:

```
$ comm -23 <upstream bin/> <ls /usr/share/omarchy/bin>
omarchy-debug
omarchy-debug-idle
omarchy-upload-log

$ pacman -Qo /usr/bin/omarchy-debug
/usr/bin/omarchy-debug is owned by omarchy-settings 4.0.0-1
$ pacman -Qo /usr/share/omarchy/bin/omarchy-font-set
/usr/share/omarchy/bin/omarchy-font-set is owned by omarchy 4.0.0-1
```

## Possible fixes

Whichever matches the intent:

- Install these three into `/usr/share/omarchy/bin` alongside the rest so the dispatcher finds them (they'd remain on `PATH` via the same mechanism as other routed commands); or
- have the dispatcher also search a second directory; or
- if the split is deliberate and they are meant to stay unrouted, drop the `# omarchy:examples=omarchy debug ...` annotations and correct the skill and issue template to the hyphenated `omarchy-debug` form.

The last option is the smallest change and would resolve the agent-skill breakage on its own.

## System

AMD Ryzen 7 PRO 5850U, AMD Cezanne (Radeon Vega Mobile), Omarchy 4.0.0-1

| | |
|---|---|
| Omarchy | 4.0.0-1 (`omarchy` and `omarchy-settings` both 4.0.0-1) |
| Hyprland | 0.56.2 |
| Kernel | 7.1.8-arch1-3 |
| Machine | ThinkPad P14s Gen 2a |

Checked for duplicates in issues and PRs before filing; nothing found.