better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/plugins.md

@@ -0,0 +1,287 @@
+<!--
+source: https://omp.sh/docs/plugins
+fetched: 2026-09-06
+-->
+
+# Plugins
+
+> Install, inspect, pause, update, and remove trusted bundles of omp capabilities without managing every file by hand.
+
+Plugins add capabilities to omp as one managed unit. A plugin may contain extension code, skills, slash commands, hooks, custom tools, agents, rules, prompts, or MCP/LSP/DAP configuration. Use one when you want to install and manage a collection of related behavior together.
+
+Start by seeing what is already installed. Before adding anything, inspect its publisher and source:
+
+```sh
+omp plugin list
+omp plugin install --dry-run '@scope/plugin@1.2.3'
+omp plugin install '@scope/plugin@1.2.3'
+omp plugin list
+```
+
+`--dry-run` previews npm, Git, and local-path installs without installing the target. It does **not** apply to marketplace installs; evaluate those at project scope instead. A successful install prints the resolved name and version. Start a new omp session to load all of the plugin's behavior, or follow [Reload an active session](#reload-an-active-session).
+
+> **Plugins are trusted code, not a sandbox.** Project scope limits where a marketplace plugin is discovered; it does not limit what that plugin can read, write, execute, or send over the network.
+
+## Choose an install source
+
+`omp plugin install` accepts these source forms:
+
+| Source | Example | Where it is installed |
+| --- | --- | --- |
+| npm package or version | `omp plugin install '@scope/plugin@1.2.3'` | User plugin directory |
+| Git shorthand, optionally pinned | `omp plugin install 'github:org/repo#v1.4.0'` | User plugin directory |
+| Full Git URL | `omp plugin install 'https://github.com/org/repo.git#v1.4.0'` | User plugin directory |
+| Local directory | `omp plugin install ./path/to/plugin` | Symlinked into the user plugin directory |
+| Marketplace entry | `omp plugin install --scope project plugin-name@marketplace-name` | User scope by default, or project scope |
+
+Git shorthands also support `gitlab:`, `bitbucket:`, `codeberg:`, `sourcehut:`, and `srht:`. Full HTTPS, SSH, `git://`, and `git+…` URLs are accepted. Quote sources containing `#`, `[` or `]` so your shell does not interpret them.
+
+The shorter `omp install <source>` command is a convenience wrapper around `omp plugin install` and `omp plugin link`. The `omp plugin …` form is used throughout this page because it exposes the complete management surface.
+
+For a local plugin under development, these are equivalent:
+
+```sh
+omp plugin install ./my-plugin
+omp plugin link ./my-plugin
+```
+
+Source edits remain visible through the symlink, but an already running omp session still needs a reload or restart before every changed capability is active.
+
+## Install from a marketplace
+
+A marketplace is a catalog of plugins, not a plugin itself. Add a catalog, inspect its entries, then install an entry by its full `name@marketplace` ID:
+
+```sh
+omp plugin marketplace add anthropics/claude-plugins-official
+omp plugin marketplace list
+omp plugin discover claude-plugins-official
+omp plugin install --scope project plugin-name@claude-plugins-official
+omp plugin list
+```
+
+Supported catalog sources include:
+
+- GitHub shorthand such as `owner/repo`
+- HTTP(S), SSH, or Git repository URLs
+- a direct HTTP(S) URL ending in `.json`
+- local directories such as `./catalog`, `~/catalog`, or `/absolute/catalog`
+
+Git and local catalogs use `.omp-plugin/marketplace.json`, falling back to the Claude Code-compatible `.claude-plugin/marketplace.json`. See [Marketplaces](/docs/marketplace) for catalog browsing, source formats, and publishing.
+
+### User and project scope
+
+Scope applies only to marketplace installs:
+
+- `--scope user` is the default and makes the plugin available across projects.
+- `--scope project` records it in the nearest project `.omp/plugins/installed_plugins.json` and makes it available in that project.
+- npm, Git, and linked local plugins use the user plugin directory; passing `--scope` for them is ignored with a warning.
+
+An enabled project install shadows an enabled user install with the same `name@marketplace` ID. A disabled project install does not hide the enabled user install. If the same plugin is installed in both scopes, pass `--scope user` or `--scope project` when upgrading, disabling, enabling, or uninstalling that copy.
+
+Project scope is useful for keeping a project's dependency set separate. It is **not** a security boundary: the plugin still runs with the same OS permissions as omp.
+
+## Inspect, disable, and enable
+
+List before changing state so you use the installed package name or full marketplace ID:
+
+```sh
+omp plugin list
+omp plugin list --json
+```
+
+The human-readable list separates npm/link plugins from marketplace plugins. It shows versions, enabled state and optional features for npm/link plugins; marketplace rows include scope and whether a project copy shadows a user copy. Inside a session, `/plugins` or `/plugins list` provides a shorter view.
+
+Disable a plugin when you want to stop loading it without deleting its files or settings:
+
+```sh
+# npm, Git, or linked plugin; state is user-wide
+omp plugin disable @scope/plugin
+omp plugin enable @scope/plugin
+
+# marketplace plugin
+omp plugin disable --scope project plugin-name@marketplace-name
+omp plugin enable --scope project plugin-name@marketplace-name
+```
+
+Inside an interactive session, `/plugins disable` and `/plugins enable` manage marketplace plugins:
+
+```text
+/plugins disable --scope project plugin-name@marketplace-name
+/plugins enable --scope project plugin-name@marketplace-name
+```
+
+Run `/reload-plugins` afterward, or restart omp. Disabling reduces future loading; it cannot undo actions code already performed in the current process.
+
+Some npm/link plugins declare optional features. Inspect and change those independently of the whole-plugin enabled state:
+
+```sh
+omp plugin features @scope/plugin
+omp plugin features @scope/plugin --enable search,web
+omp plugin features @scope/plugin --disable web
+omp plugin features @scope/plugin --set search
+```
+
+At install time, quote the feature selector:
+
+```sh
+omp plugin install '@scope/plugin[search,web]'
+omp plugin install '@scope/plugin[*]'
+omp plugin install '@scope/plugin[]'
+```
+
+No brackets uses the plugin's defaults; `[*]` enables every declared feature and `[]` enables none of the optional features.
+
+## Update plugins
+
+Update behavior depends on the source.
+
+### Marketplace plugins
+
+Refreshing a marketplace updates only its catalog. Upgrade is the separate step that replaces installed plugin code:
+
+```sh
+omp plugin marketplace update marketplace-name
+omp plugin upgrade --scope project plugin-name@marketplace-name
+```
+
+Omit the marketplace name to refresh all catalogs. Omit the plugin ID from `omp plugin upgrade` to upgrade all installed marketplace plugins:
+
+```sh
+omp plugin marketplace update
+omp plugin upgrade
+```
+
+When one marketplace plugin exists in both scopes, omitting `--scope` upgrades both copies. Bulk upgrade may partially succeed if one entry fails, so read every result and run `omp plugin list` afterward.
+
+### npm and Git plugins
+
+There is no generic `omp plugin update` command for npm or Git installs. Reinstall the version or ref you intend to run:
+
+```sh
+omp plugin install '@scope/plugin@1.3.0'
+omp plugin install 'github:org/repo#v1.5.0'
+```
+
+For a linked local plugin, update its source directory yourself; the symlink does not need reinstalling. Pin npm versions and Git tags or commits when reproducibility matters.
+
+## Remove a plugin
+
+Preview removal, then uninstall by the name shown in `omp plugin list`:
+
+```sh
+omp plugin uninstall --dry-run @scope/plugin
+omp plugin uninstall @scope/plugin
+```
+
+For a marketplace plugin, use its full ID and specify the copy when necessary:
+
+```sh
+omp plugin uninstall --dry-run --scope project plugin-name@marketplace-name
+omp plugin uninstall --scope project plugin-name@marketplace-name
+```
+
+Uninstalling removes that plugin registration and installed files for the selected scope. Removing a marketplace catalog is different: it removes the catalog and its cache but does not uninstall plugins already installed from it.
+
+```sh
+omp plugin marketplace remove marketplace-name
+```
+
+Restart omp after removing executable plugin behavior, or reload the active session as described below.
+
+## Reload an active session
+
+Shell commands change plugin state on disk; they do not rebuild an omp process that is already running. Interactive marketplace changes also require an explicit refresh.
+
+Run:
+
+```text
+/reload-plugins
+```
+
+This refreshes plugin discovery, skills, slash commands, agent definitions, capability caches, and MCP connections in the active session. Restart omp for newly installed or changed extension modules, hooks, or executable custom tools, because those initialized runtime components are not fully rebuilt in place. When in doubt, restart.
+
+## Check health and settings
+
+If a plugin is installed but missing from `omp plugin list`, fails to load, or points at a deleted local path, run the non-mutating health check first:
+
+```sh
+omp plugin doctor
+```
+
+After reading its findings, `omp plugin doctor --fix` can attempt repairs. Use `--json` when another program needs to consume the result.
+
+Plugins may declare typed settings. Inspect the declared keys before setting one:
+
+```sh
+omp plugin config list @scope/plugin
+omp plugin config get @scope/plugin apiKey
+omp plugin config set @scope/plugin apiKey value
+omp plugin config delete @scope/plugin apiKey
+omp plugin config validate
+```
+
+Add `-l` or `--local` to `config list`, `get`, `set`, or `delete` to use the current project's setting overrides. A manifest marking a setting as secret masks its display; it does not turn an untrusted plugin into trusted code.
+
+## Trust checklist
+
+A plugin can run extension modules in omp's process, register hooks around prompts and tool activity, expose executable tools, start MCP/LSP/DAP processes, and receive configured credentials. Treat installation like running code from that source.
+
+Before installing or upgrading:
+
+1. Verify the publisher, repository, and exact npm version, Git ref, or marketplace entry.
+2. Read extension entry points, hooks, executable tools/scripts, and MCP/LSP/DAP configuration.
+3. Review dependency and source changes between the installed and proposed versions.
+4. Prefer a pinned npm version, Git tag, commit, or marketplace version.
+5. Use project scope to limit discovery while evaluating a marketplace plugin, but do not mistake it for sandboxing.
+6. Disable or uninstall anything you no longer trust, then restart omp.
+
+Adding a marketplace does not execute its plugins, but the catalog controls where later installs and upgrades fetch code. Trust both the catalog maintainer and each plugin source.
+
+## Plugins, extensions, and marketplaces
+
+| Term | What it is | How users manage it |
+| --- | --- | --- |
+| **Plugin** | An installable unit that can bundle several omp capabilities | `omp plugin install`, `list`, `disable`, `upgrade`, and `uninstall` |
+| **Extension** | Runtime TypeScript/JavaScript code that registers behavior with omp | Load directly for one session or from config, or ship it inside a plugin |
+| **Marketplace** | A catalog that names plugins and points to their sources | `omp plugin marketplace …` or `/marketplace …` |
+
+A plugin does not have to contain an extension module; it may contain only declarative surfaces such as skills or MCP configuration. Conversely, you can load an extension directly without installing it as a managed plugin. See [Authoring extensions](/docs/extension-authoring) for that runtime API.
+
+## Command reference
+
+| Command | Purpose |
+| --- | --- |
+| `omp plugin list [--json]` | List npm/link and marketplace plugins |
+| `omp plugin install [--dry-run] [--force] <source>[features] …` | Install npm, Git, local, or marketplace sources; `--dry-run` is not supported for marketplace entries |
+| `omp install <source> …` | Convenience form of plugin install/link |
+| `omp plugin link <path>` | Symlink a local plugin for development |
+| `omp plugin disable <name> …` / `enable <name> …` | Persist whole-plugin enabled state |
+| `omp plugin features <name> [--enable list] [--disable list] [--set list]` | Inspect or select optional npm/link plugin features |
+| `omp plugin uninstall [--dry-run] <name> …` | Remove installed plugins |
+| `omp plugin upgrade [name@marketplace] [--scope user\|project]` | Upgrade one or all marketplace plugins |
+| `omp plugin marketplace add <source>` | Add a marketplace catalog |
+| `omp plugin marketplace list` | List configured catalogs |
+| `omp plugin marketplace update [name]` | Refresh one or all catalogs without upgrading plugins |
+| `omp plugin marketplace remove <name>` | Remove a catalog, not its installed plugins |
+| `omp plugin discover [marketplace]` | List marketplace entries |
+| `omp plugin doctor [--fix] [--json]` | Check plugin installation health |
+| `omp plugin config <list\|get\|set\|delete> <name> … [-l]` | Manage declared plugin settings |
+| `omp plugin config validate` | Validate settings for every installed plugin |
+
+Use `--scope user|project` only with marketplace install, enable, disable, upgrade, and uninstall operations. `/marketplace help` shows the equivalent in-session marketplace commands.
+
+## For plugin authors
+
+Users should not need to understand manifests to manage plugins. Authors of npm or linked omp packages declare runtime entry points in `package.json` under `omp` (legacy `pi` is also accepted):
+
+```json
+{
+  "name": "@acme/omp-review",
+  "version": "1.0.0",
+  "omp": {
+    "extensions": ["./src/index.ts"]
+  }
+}
+```
+
+A package can also use conventional `skills/`, `commands/`, `hooks/`, `tools/`, `rules/`, `prompts/`, and `agents/` directories plus `.mcp.json` or `mcp.json`. Optional `features` and typed `settings` belong in the `omp` manifest because the management commands above read them. See [Authoring extensions](/docs/extension-authoring) for the public extension API and [Marketplaces](/docs/marketplace) for catalog manifests.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/prewalk.md

@@ -0,0 +1,122 @@
+<!--
+source: https://omp.sh/docs/prewalk
+fetched: 2026-09-06
+-->
+
+# Prewalk
+
+> Let a capable model investigate and begin a change, then hand the same session to a faster or cheaper model for implementation.
+
+## Plan with strength, implement with speed
+
+Prewalk is a one-time model handoff inside a normal omp session. Start on the model you trust to understand an unfamiliar repository, identify risks, and organize the work. Once that model has made a todo list and begun changing the project, omp switches the current session to a faster or cheaper target model to continue the implementation.
+
+A useful first run is:
+
+```sh
+omp --model @slow --prewalk-into @smol
+```
+
+Then describe the complete outcome as usual. The conversation, repository context, todos, and changes stay in the same session; prewalk changes the model doing the remaining work, not the task.
+
+This can reduce cost and latency on changes where planning is difficult but execution is routine. It is a tradeoff, not a free quality improvement: the target model still has to understand the planner's todos, adapt when implementation reveals a bad assumption, test the result, and finish cleanup. Keep one capable model throughout when the work requires repeated design decisions, subtle debugging, or high-risk edits.
+
+## Enable it and choose the target
+
+Prewalk is disabled by default. Arm it for one new session with `--prewalk`:
+
+```sh
+omp --prewalk
+```
+
+This uses the model assigned to the `smol` role. To make the choice predictable, assign that role in `/model` under **Roles**, or configure it in `~/.omp/agent/config.yml`:
+
+```yaml
+modelRoles:
+  smol: anthropic/claude-haiku-4-5
+```
+
+To choose a different target for one launch, pass a role alias or model selector to `--prewalk-into`. This flag also arms prewalk, so `--prewalk` is not required alongside it.
+
+```sh
+omp --prewalk-into @smol
+omp --prewalk-into openai/gpt-5-mini
+```
+
+Use a full `provider/model-id` when you need a stable exact choice. A configured role can also carry a thinking level, and a model selector may include one, such as `provider/model-id:medium`. omp resolves the target using the same role and model-matching rules as other model controls.
+
+For persistent opt-in, set:
+
+```sh
+omp config set prewalk.enabled true
+```
+
+The equivalent YAML is:
+
+```yaml
+prewalk:
+  enabled: true
+```
+
+With the setting enabled, each fresh session is armed and targets `@smol`. Use `--prewalk-into <model-or-role>` to override that target for a launch, or `--no-prewalk` to keep a particular session on its starting model:
+
+```sh
+omp --no-prewalk
+```
+
+`--no-prewalk` cannot be combined with `--prewalk` or `--prewalk-into`. The persistent setting does not automatically arm a restored conversation; pass `--prewalk` explicitly if you want a handoff while continuing one.
+
+## Recognize the handoff
+
+An armed prewalk lets the starting model investigate and establish the implementation plan first. When todos are available, the first completed file edit starts the handoff. The edit itself is made by the starting model; the target model receives the same session and continues from there.
+
+You will see notices that make the lifecycle explicit:
+
+- **Armed** — identifies the resolved target and says omp is waiting for the todo list and first edit or write.
+- **Switched** — identifies the target and reports that the switch followed the first edit or write.
+- **Nothing to switch** — the target model and thinking level already match the active session, so omp disarms prewalk instead of performing a no-op.
+
+The handoff waits if the model is still only reading, searching, or discussing an approach. If todos are available but no project file has yet been changed, it remains armed. In configurations where todos are unavailable, the first completed file edit can hand off directly.
+
+Prewalk is one-shot. After the switch it is no longer armed, and later edits do not cause more model changes. The target becomes the current model for the remainder of the live session, but the switch does not rewrite your saved model-role settings. The model indicator and the switch notice show which model is currently active.
+
+## Arm it in an active session
+
+Run `/prewalk` to arm a handoff without restarting or changing `prewalk.enabled`:
+
+```text
+/prewalk
+```
+
+The command resolves `@smol`, checks that it is usable, and displays the target when it arms successfully. It does not accept a target argument; use `--prewalk-into` when starting omp if you need another target.
+
+If prewalk is already armed, `/prewalk` keeps the existing target rather than replacing it. After a handoff has happened, you can choose another current model with the normal model controls and run `/prewalk` again to create another one-shot handoff.
+
+## Choose where to spend model quality
+
+A good prewalk target is authenticated, quick, inexpensive, and reliable at the languages and tools the task needs. Compare the expected savings with the cost of repairing a weak implementation:
+
+| Work shape | Suggested choice |
+| --- | --- |
+| Broad investigation followed by repetitive call-site updates | Strong starter, fast target |
+| Clear plan followed by routine tests or mechanical edits | Strong starter, cheap target |
+| Security-sensitive migration or behavior with hidden invariants | Keep the capable model active |
+| Debugging where each result changes the next hypothesis | Usually skip prewalk |
+| Small, obvious edit | Start on the inexpensive model directly; prewalk adds little |
+
+A stronger planner should leave specific, ordered todos and begin with a representative edit. If the target frequently has to rediscover constraints, use a more capable target or do not hand off.
+
+## Prewalk and subagents
+
+This page describes the main session handoff. A task subagent is a separate delegated run with its own context and model selection; arming the main session does not mean every subagent will prewalk. Configure subagent prewalk separately only when you use delegated agents and want the same plan-then-switch pattern inside those runs. See [Subagents](/docs/subagents).
+
+## Troubleshooting
+
+- **No armed notice appears at startup** — prewalk is off unless `prewalk.enabled` is `true` or the launch includes `--prewalk` or `--prewalk-into`. A restored session does not inherit automatic arming from the setting; pass the flag explicitly.
+- **`Warning: prewalk disabled — model … not found`** — the target role or selector did not resolve. Check the effective `smol` assignment in `/model`, or use a full selector returned by `omp models find <name>`.
+- **`Warning: prewalk disabled — no API key for …`** — authenticate the target provider or select a model whose provider is already configured. omp continues startup with prewalk unarmed.
+- **`/prewalk` reports a model or API-key error** — `/prewalk` always uses `@smol`. Fix that role or its provider credentials; to use another target, restart with `--prewalk-into`.
+- **It is armed but has not switched** — let the starting model finish investigation, create its todos, and begin the first project edit. Read-only work and discussion do not consume the handoff.
+- **The first edit happened but no switch followed** — check whether the edit failed, whether the target already matched the current model and thinking level, or whether the visible notice says prewalk was disabled during target resolution.
+- **`/prewalk` says it is already armed for another model** — the existing one-shot target is preserved. Let it hand off, or start a new session with the desired `--prewalk-into` target.
+- **Quality drops after the switch** — choose a stronger target, assign more appropriate thinking effort, or use `--no-prewalk` for tasks whose design continues throughout implementation.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/prompt-templates.md

@@ -0,0 +1,149 @@
+<!--
+source: https://omp.sh/docs/prompt-templates
+fetched: 2026-09-06
+-->
+
+# Prompt templates
+
+> Turn a Markdown prompt into a reusable slash command for yourself or a project.
+
+## Create your first template
+
+A prompt template saves instructions you use repeatedly and exposes them as a slash command. Use one for a consistent review checklist, a release summary, a test plan, or any other task that does not need custom program logic.
+
+Create `.omp/prompts/review-change.md` in the project where you want to use the command:
+
+```md
+---
+description: Review one area of this project for correctness
+---
+
+Review the code related to $1.
+
+Focus on: $@[2:].
+
+Report concrete findings first, with file and line references. Then list any
+remaining risks or missing tests. Do not change files.
+```
+
+Start a new omp session in that project, then type:
+
+```text
+/review-change authentication "error handling and tests"
+```
+
+The filename creates the `/review-change` command. omp expands `$1` to `authentication`, expands `$@[2:]` to `error handling and tests`, and sends the resulting Markdown as your message. The `description` appears beside the command in `/` autocomplete.
+
+Use `.omp/prompts/` for prompts shared with a project. For a command available in every project, save the same Markdown file under `~/.omp/agent/prompts/` instead.
+
+## Pass arguments
+
+Arguments follow the command name. Spaces and tabs separate arguments; matching single or double quotes keep text together and the quote characters are removed.
+
+```text
+/review-change payments "retry behavior" tests
+```
+
+| Syntax | Value in this example |
+| --- | --- |
+| `$1`, `$2`, … | `payments`, `retry behavior`, … |
+| `$@` or `$ARGUMENTS` | `payments retry behavior tests` |
+| `$@[2]` or `$@[2:]` | All arguments from the second: `retry behavior tests` |
+| `$@[2:1]` | One argument starting at the second: `retry behavior` |
+
+Indexes are one-based. A missing positional argument, an out-of-range slice, or a non-positive slice index expands to an empty string.
+
+The argument parser does not have a backslash escape syntax. If an argument contains spaces, wrap it in the other quote style rather than trying to escape the surrounding quote. Empty quoted arguments are discarded.
+
+If the template has no argument placeholder, omp does not throw the supplied text away. It appends the joined arguments to the prompt after a blank line:
+
+```md
+Summarize the requested part of this project.
+```
+
+Invoking `/summarize src/auth` sends the template followed by `src/auth`.
+
+## Use Handlebars interpolation
+
+After replacing the `$…` placeholders, omp renders the result as a Handlebars template. The most useful values are:
+
+| Syntax | Meaning |
+| --- | --- |
+| `{{arg 1}}` | First parsed argument; `arg` is one-based |
+| `{{arguments}}` or `{{ARGUMENTS}}` | All parsed arguments joined with spaces |
+| `{{args}}` | The parsed argument array, useful in blocks and helpers |
+| `{{default (arg 1) "current branch"}}` | A fallback when the first argument is absent |
+| `{{#if args}}…{{else}}…{{/if}}` | Conditional content based on whether arguments were supplied |
+
+For example:
+
+```md
+---
+description: Draft a test plan for a feature
+---
+
+Draft a test plan for {{default (arg 1) "the current change"}}.
+{{#if args}}
+Additional context: {{arguments}}
+{{/if}}
+```
+
+Shell-style substitution happens first and Handlebars rendering happens second. Argument values containing `$1`, `$@`, or `$ARGUMENTS` are not recursively substituted. A template that uses either style of inline argument placeholder does not also receive the automatic argument suffix.
+
+For ordinary reusable prompts, prefer the `$1` and `$@` forms: they are shorter and make the invocation easy to understand. Use Handlebars only when you need defaults or conditional sections.
+
+## Add a description
+
+Only `description` has special meaning in an omp prompt template's YAML frontmatter:
+
+```md
+---
+description: Explain a failing test and propose the smallest fix
+---
+```
+
+Put frontmatter at the beginning of the file. If `description` is absent, omp uses the first non-empty body line, truncated to 60 characters, in autocomplete. The command name always comes from the Markdown filename; a frontmatter `name` field does not rename it.
+
+## Discovery and naming
+
+At session startup, omp recursively discovers Markdown files in these locations:
+
+| Scope | Directory | Autocomplete source label |
+| --- | --- | --- |
+| User | `~/.omp/agent/prompts/**/*.md` | `(user)` or `(user:subdirectory)` |
+| Project | `<working-directory>/.omp/prompts/**/*.md` | `(project)` or `(project:subdirectory)` |
+
+Only the final filename becomes the command name. Both `.omp/prompts/frontend/review.md` and `.omp/prompts/backend/review.md` define `/review`, not namespaced commands. Give every template a unique filename even when you organize files into subdirectories.
+
+Prompt templates are Markdown prompts, not executable command modules. If a command needs to run custom program logic or display its own UI, build an [extension](/docs/extension-authoring) instead.
+
+## Precedence
+
+omp loads user templates before project templates and uses the first matching name. As a result, `~/.omp/agent/prompts/review.md` wins over `.omp/prompts/review.md`. This differs from many project-overrides-user configuration systems, so unique names are the safest choice.
+
+Other slash-command types resolve before prompt templates. A built-in, extension command, custom command, skill command, or file-based slash command with the same name wins; the conflicting prompt template is omitted from autocomplete.
+
+## Reload after editing
+
+Prompt templates are read when the session starts. omp does not watch these files, and `/reload-plugins` does not reload them. After creating, renaming, or editing a template, exit and start a new `omp` session in the intended working directory.
+
+## Troubleshooting
+
+### The command is missing from autocomplete
+
+- Confirm the file ends in `.md` and is under `.omp/prompts/` for the current working directory or `~/.omp/agent/prompts/` for your user.
+- Start a new session after changing the file.
+- Check for another template with the same filename. A user template wins over a project template.
+- Try a more distinctive filename in case a built-in, skill, extension, custom, or file-based command already owns the name.
+- Check the session logs for a prompt-template warning. Invalid YAML frontmatter or an unreadable file can prevent that template from loading.
+
+### Arguments expand unexpectedly
+
+- Quote an argument that contains spaces: `/review-change auth "error handling"`.
+- Do not rely on backslash escapes inside quoted arguments; they are treated literally rather than as an escape mechanism.
+- Remember that `$@` includes every argument, including `$1`. Use `$@[2:]` for only the remainder.
+- Add an explicit placeholder if you need to control where arguments appear. Without one, omp appends them after the template body.
+
+### The project template does not override my user template
+
+This is the current precedence rule: user templates load first. Rename one of the files, or remove the user-level duplicate, then start a new session.