better-dsh 0.2.4 → 0.2.5-a

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

@@ -0,0 +1,151 @@
+<!--
+source: https://omp.sh/docs/acp
+fetched: 2026-09-06
+-->
+
+# ACP
+
+> Run the full omp agent inside an ACP-capable editor, with editor-aware files, terminals, session controls, and permission prompts.
+
+## Use omp from your editor
+
+[Agent Client Protocol (ACP)](https://agentclientprotocol.com) lets an editor host an omp conversation without embedding omp or adding an editor-specific plugin. Use it when you want to review changes, terminals, approvals, and session history beside your code while omp keeps its own models, credentials, settings, extensions, and skills.
+
+The editor starts omp as a child process. You do not run the ACP server in a separate terminal or connect it to a port.
+
+First, confirm that `omp` is available in the environment your editor will use:
+
+```sh
+command -v omp
+omp --version
+```
+
+Then configure the ACP client with these launch values:
+
+| Field | Value |
+| --- | --- |
+| Command | `omp` |
+| Arguments | `acp` |
+| Transport | stdio |
+| Session directory | The absolute path of the open project or workspace |
+
+`omp --mode acp` is equivalent, but `omp acp` is the recommended spelling for client configuration.
+
+## Connect Zed
+
+In Zed, run **agent: open settings**, open **External Agents**, choose **Add Agent → Add Custom Agent**, and add:
+
+```json
+{
+  "agent_servers": {
+    "Oh My Pi": {
+      "type": "custom",
+      "command": "omp",
+      "args": ["acp"]
+    }
+  }
+}
+```
+
+Start a new thread from the Agent Panel and select **Oh My Pi**. Zed owns the thread UI; omp owns the agent, provider connection, and model settings.
+
+If a GUI-launched Zed cannot find `omp`, replace `"omp"` with the absolute path printed by `command -v omp`. The same rule applies to other clients whose environment does not inherit your shell `PATH`.
+
+For another ACP client, create the equivalent custom-agent entry: spawn `omp` with the single argument `acp`, keep stdin and stdout connected to the ACP transport, and supply the workspace's absolute path when creating the session. Do not parse terminal UI output or launch `omp` without `acp`.
+
+## Authenticate and start a thread
+
+omp advertises **Use existing local credentials** to every ACP client. Those are the provider keys and OAuth sessions already available to omp; credentials configured only for your editor's built-in agent are not automatically shared.
+
+If the client offers **Set up Oh My Pi in terminal**, choose it to open omp's interactive provider setup. Otherwise:
+
+1. Run `omp` in a terminal.
+2. Enter `/login` or `/login <provider>` and finish authentication.
+3. Start a fresh ACP thread in the editor.
+
+See [Providers](/docs/providers) for credential sources and precedence. After connection, use the editor's session controls to select an available **Model** and **Thinking** level. The model list reflects what omp can use with its current credentials and configuration.
+
+Now prompt normally, for example:
+
+```text
+Rename issueToken to mintToken across this project, update every caller, and run the focused tests.
+```
+
+The response streams into the editor. In a capable client, omp reads through the editor's filesystem bridge, writes through the editor, and runs shell commands in client-side terminals. This keeps reads aligned with open buffers and lets the editor show touched locations and command output. If a client does not provide one of those ACP capabilities, omp falls back to the workspace filesystem or its local command runner for that capability.
+
+## Session controls
+
+An ACP thread is a normal persistent omp session. Depending on the client UI, you can reopen, resume, fork, or close sessions and see their stored title and working directory.
+
+The standard session controls are:
+
+- **Mode** — Default or Plan. Plan is available when `plan.enabled` is true, which is the default.
+- **Model** — any model currently available to omp.
+- **Thinking** — Off, Auto, or a level supported by the selected model.
+
+Choose **Plan** from the client's mode control when you want read-only investigation before edits. omp presents the finished plan for approval; dismissing or declining that prompt never grants write access. `/plan` is a TUI-only command and is not the way to enter plan mode over ACP. See [Plan mode](/docs/plan) for the workflow.
+
+Text-capable slash commands are advertised in the client's command menu. TUI-only commands such as `/login` and `/quit` are intentionally absent: authentication and process lifetime belong to the ACP host.
+
+## Permissions
+
+ACP adds an editor-side safety gate before:
+
+- shell commands;
+- file deletion;
+- file moves or renames, including destructive operations contained in a larger edit.
+
+The client can offer **Allow once**, **Always allow**, **Reject**, and **Always reject**. An “always” choice is cached only for the current session and for that operation category; it is not a permanent global setting. Ordinary reads and non-destructive file writes do not trigger this ACP-specific gate, though your normal omp approval settings still apply.
+
+A rejected, cancelled, or unsupported permission request fails closed. omp does not silently execute the operation.
+
+For a trusted unattended workspace, make the choice explicit in the client launch arguments:
+
+```json
+{
+  "command": "omp",
+  "args": ["acp", "--approval-mode", "yolo"]
+}
+```
+
+This skips omp and client permission prompts unless a per-tool policy is explicitly set to `prompt` or `deny`. Prefer the default prompted setup for interactive editor use. See [Settings](/docs/settings) for persistent `tools.approvalMode` and per-tool policies.
+
+## MCP and editor capabilities
+
+In ACP mode, the client owns MCP server configuration. omp accepts stdio, HTTP, and SSE MCP servers passed by the client when a session starts; it intentionally does not auto-discover omp's on-disk MCP configuration for that session. Configure a missing MCP server in the editor or ACP host, then start or reload the thread.
+
+omp also supports text, images, and embedded context supplied by the client. Whether your editor exposes attachments, session import, forks, Plan mode, terminals, or unsaved-buffer reads depends on the ACP capabilities and UI it implements.
+
+## Troubleshooting
+
+### `omp acp` appears to hang
+
+That is expected when you run it by hand: the process is waiting for ACP messages on stdin, and stdout is reserved for the protocol. Configure the editor to spawn it instead. Startup and transport diagnostics go to stderr, and omp logs are under `~/.omp/logs/`.
+
+In Zed, run **dev: open acp logs** to inspect the client side of the connection.
+
+### The editor reports `command not found`
+
+Run `command -v omp` in a terminal and use that absolute path as the custom agent's command. GUI applications often receive a smaller `PATH` than interactive shells. If the project is remote, install and authenticate omp in the environment where the ACP process actually runs.
+
+### The thread connects but no model works
+
+Open the terminal setup offered by the client, or run `omp` and `/login <provider>` outside the editor. Then create a new thread. Also check that provider credentials or environment variables are visible to the editor process; editor-native model credentials do not automatically configure omp.
+
+### Unsaved changes are missing or terminals open outside the editor
+
+The client may not advertise ACP filesystem or terminal support. Update or reconfigure the client. Without filesystem bridging, save buffers before asking omp to inspect them; without terminal bridging, commands use omp's local runner.
+
+### A permission prompt never completes
+
+The ACP client must render and answer permission requests. Cancelling the dialog or using a client that cannot answer rejects the operation. Use a current client, or deliberately configure an approval policy rather than assuming approval.
+
+### MCP tools are missing
+
+Configure the MCP server in the ACP client, not only in omp's local MCP files. Start a new thread so the client can pass the server configuration during session creation.
+
+## For ACP client implementers
+
+`omp acp` speaks ACP JSON-RPC over newline-delimited stdio. Keep stdout exclusively connected to the protocol and read diagnostics from stderr. A client can integrate progressively: basic prompting works first, while filesystem access, terminals, permission dialogs, images, embedded context, MCP servers, session history, mode selection, model selection, and thinking controls appear when the client implements the corresponding public ACP capabilities.
+
+The process advertises session creation plus list, load, resume, fork, and close support. Use the official [ACP specification](https://agentclientprotocol.com) for message schemas; omp does not require clients to understand its internal tools or private bridge payloads.

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

@@ -0,0 +1,185 @@
+<!--
+source: https://omp.sh/docs/advisor
+fetched: 2026-09-06
+-->
+
+# Advisor models
+
+> Add an optional reviewer model that watches omp's work, catches risky mistakes, and steers the main agent before they become expensive.
+
+## Add a second set of eyes
+
+An advisor is a separate model that reviews the main agent's work as the session unfolds. It can flag a missed requirement, a risky API, weak verification, or unnecessary complexity while the main agent still has a chance to correct course. Use one for long or high-stakes changes, unfamiliar repositories, security-sensitive work, or whenever independent review is worth more than maximum speed.
+
+The tradeoff is real: the advisor makes its own model requests, uses its own context, and is billed separately. A larger model may catch subtler problems but costs more; several advisors multiply that usage. Review normally happens in the background, but an important note can cause more main-agent work, and optional catch-up settings can add latency. For routine edits, leave it off or choose a fast, inexpensive reviewer.
+
+The smallest persistent setup is two entries in [`~/.omp/agent/config.yml`](/docs/settings):
+
+```yaml
+modelRoles:
+  advisor: anthropic/claude-sonnet-4-5:medium
+
+advisor:
+  enabled: true
+```
+
+Use any model selector available in your installation. Restart omp or start a new session after editing the file, then check it:
+
+```text
+/advisor status
+```
+
+With no `WATCHDOG.yml` roster, omp creates one default advisor using `modelRoles.advisor`. If the role does not resolve to an available, authenticated model, the feature is configured but cannot run.
+
+## What happens during a session
+
+The advisor follows new user prompts, main-agent responses, reasoning, and tool activity. Its default tools let it read and search the project, so it can verify claims instead of reviewing prose alone. It does not approve the main agent's actions and its advice is not automatically correct: the main agent is instructed to weigh each note against your request rather than obey it blindly.
+
+Accepted notes appear visibly in the session with one of three severities:
+
+| Severity | Meaning | What omp does |
+| --- | --- | --- |
+| `nit` | Cleanup, simplification, or a low-risk edge case. | Adds a non-interrupting aside at a safe boundary. |
+| `concern` | A material risk, missed constraint, or likely wrong direction. | Can steer work that is still running; a late note after a completed answer remains visible for the next turn. |
+| `blocker` | Continuing is likely to waste work or produce a broken result. | Can interrupt active work and can trigger follow-up even after a nominally completed answer. |
+
+Only a blocker may interrupt a partially completed review. Repeated or content-free notes are suppressed, and after an interrupt omp normally gives the main agent several turns before allowing another advisor interrupt. If you deliberately stop the agent, advisor notes stay visible instead of unexpectedly restarting it. In plan mode, notes are also shown for you to consider rather than steering the plan automatically.
+
+Treat a note as informed review, not a new user instruction. If the main agent rejects useful advice, refer to the visible note in your next prompt. If the advisor is creating noise, turn it off for the session or narrow its priorities in `WATCHDOG.md`.
+
+## Inspect and control it
+
+| Command | Result |
+| --- | --- |
+| `/advisor` | Toggle all configured advisors for this session. |
+| `/advisor on` | Enable or rebuild them for this session. This does not save `advisor.enabled`. |
+| `/advisor off` | Stop them for this session. This does not change your config file. |
+| `/advisor status` | Show each advisor's state, model, context use, token use, and cost. |
+| `/advisor dump` | Copy a compact advisor transcript to the clipboard. |
+| `/advisor dump raw` | Copy the full diagnostic dump, including instructions, thinking, and tool activity. Handle it as sensitive data. |
+| `/advisor configure` | Open the interactive editor for project- or user-level `WATCHDOG.yml`. TUI only. |
+
+A bare `/advisor` is a toggle, not a status command. Session toggles are temporary; edit [`config.yml`](/docs/settings) when you want the choice to persist.
+
+## Give the reviewer project-specific priorities
+
+Put reviewer-only guidance in `WATCHDOG.md`. This is the best place for architectural boundaries, dangerous APIs, recurring failure modes, and the evidence you expect before a change is called complete. It guides advisors without adding the same material to the main agent's ordinary context.
+
+```markdown
+# Review priorities
+
+Especially watch for:
+
+- Writes that bypass the durable queue in `src/jobs/`.
+- User-controlled text rendered without escaping.
+- Schema changes without a backwards-compatible rollout.
+- Claims of success that are not supported by a focused runtime check.
+```
+
+Keep it specific enough to change a review decision. General requests such as “write good code” add cost but little signal.
+
+omp loads every readable `WATCHDOG.md` on this path:
+
+1. the active user agent directory, normally `~/.omp/agent/WATCHDOG.md`;
+2. `WATCHDOG.md` and `.omp/WATCHDOG.md` in the current directory;
+3. the same two locations in each parent directory up to the Git root, or up to your home directory when there is no Git root.
+
+The user file is broad guidance. Project files are applied from outer directories toward the current directory, so narrower guidance is most prominent. Files accumulate rather than the nearest one replacing the others. You can also place a line such as `@review/security.md` in a watchdog file to import another file; relative paths resolve beside the importing file, and imports inside code spans or fenced code blocks remain literal.
+
+## Configure several specialist advisors
+
+Use `WATCHDOG.yml` or `WATCHDOG.yaml` when one reviewer is not enough. The file declares a roster; once any roster entries are discovered, that roster replaces the single default-advisor arrangement.
+
+```yaml
+instructions: |
+  Prefer fixes that preserve public APIs and keep tests focused.
+
+advisors:
+  - name: Architecture
+    enabled: true
+    model: anthropic/claude-sonnet-4-5:medium
+    tools: [read, grep, glob]
+    instructions: |
+      Watch module boundaries, dependency direction, and public API growth.
+
+  - name: Security
+    enabled: true
+    model: openai/gpt-5.5:high
+    tools: [read, grep, glob]
+    instructions: |
+      Trace untrusted input through authentication, storage, and rendering.
+
+  - name: Release
+    enabled: false
+    tools: []
+    instructions: |
+      Check migrations, compatibility, and rollback instructions.
+```
+
+| Field | Purpose |
+| --- | --- |
+| top-level `instructions` | Shared guidance added to every advisor from all discovered roster files. |
+| `name` | Required display name. Names also identify entries for precedence; punctuation and spacing normalize to a slug. |
+| `enabled` | Per-advisor switch. Defaults to `true`; `false` leaves the entry visible as paused. |
+| `model` | Optional model selector and thinking level. When omitted, the entry uses `modelRoles.advisor`. |
+| `tools` | Optional built-in tools. Omitted gives `read`, `grep`, and `glob`; `[]` gives no investigative tools. |
+| `instructions` | This advisor's specialization. It supports the same `@` imports as `WATCHDOG.md`. |
+
+Roster files use the same user, ancestor, current-directory, and `.omp/` discovery locations as `WATCHDOG.md`. All discovered files participate. Shared top-level instructions accumulate; when two entries normalize to the same name, the more specific project entry replaces the ancestor or user entry. Avoid defining the same name twice at the same directory level or keeping both `.yml` and `.yaml` variants there—the result is harder to reason about. Invalid YAML or an invalid schema is logged and that file is skipped rather than breaking the main session.
+
+### Tool grants are a security boundary
+
+The default `read`/`grep`/`glob` grant is appropriate for review. A roster may grant other built-ins, including `edit`, `write`, `bash`, `eval`, or `browser`. Those grants can change files, run commands, or send data through another service. Normal approval and per-tool policies still apply, but a permissive approval mode may not stop a bad action. Grant mutating or networked tools only to a model you trust and only when the specialist genuinely needs them.
+
+Unknown tool names are dropped with a warning. Check `/advisor status` and the logs after changing a roster rather than assuming a misspelled tool was granted.
+
+## Cost, latency, and supervision settings
+
+These optional settings belong in [`config.yml`](/docs/settings):
+
+```yaml
+advisor:
+  enabled: true
+  syncBacklog: "1"
+  immuneTurns: 3
+
+tier:
+  advisor: none
+```
+
+| Setting | Default | Use it for |
+| --- | --- | --- |
+| `advisor.syncBacklog` | `off` | `off` never waits for review catch-up. `"1"`, `"3"`, or `"5"` pauses the main agent for up to 30 seconds when review falls that many turns behind; `"1"` is the closest to synchronous review. Quote numeric values in YAML because these are enum strings. |
+| `advisor.immuneTurns` | `3` | Number of main-agent turns after an interrupt during which further concerns and blockers become non-interrupting asides. Use `0` for maximum supervision, or a larger value to reduce churn. |
+| `tier.advisor` | `none` | Service tier for advisor requests. `inherit` follows the main model's live provider-family tier; concrete tiers apply only where the provider supports them. |
+
+Even with catch-up enabled, advisor trouble does not permanently stall the main agent: catch-up waits are bounded and released on failure.
+
+## One-off and headless runs
+
+Enable review for one print-mode process without changing persistent settings:
+
+```sh
+omp -p --advisor "Audit this migration plan and report the safest rollout."
+```
+
+`--advisor` enables the configured default or roster for that process; it still needs resolvable advisor models and provider credentials. Print mode waits for final review before disposal so late notes are not silently lost, which can make the command finish later than an ordinary `-p` run. Use it selectively in automation and account for both the extra model cost and the longer completion time. See the [CLI reference](/docs/cli) for other launch flags.
+
+## Privacy and safety
+
+Enabling an advisor sends session material to the advisor model's provider. That includes your prompts, the main agent's output and reasoning, and relevant tool results; investigative tools can expose any files they read. Session-managed secrets are obfuscated before provider-bound advisor messages, but this is not a substitute for choosing a provider and model allowed to process the repository. A multi-provider roster may send the same project context to several vendors.
+
+Advisor turns and usage are recorded with the owning session so cost reporting and later inspection work. `/advisor dump raw` contains substantially more detail than the compact dump; review it before pasting it into an issue or chat. Turning the advisor off stops new reviews but does not erase already recorded session artifacts.
+
+omp rejects unsafe advisor output before it can dispatch tools or steer the main agent. This is defense in depth, not permission to grant broad tools: keep the least-privilege roster, retain normal approval policies, and inspect any proposed high-impact change yourself.
+
+## Troubleshooting
+
+- **“Advisor setting is enabled, but no model is assigned” / `no model`** — set `modelRoles.advisor`, or add a valid `model` to every enabled roster entry. Confirm the provider is installed and authenticated with `/model` and `/login`, then run `/advisor off` followed by `/advisor on`.
+- **An advisor shows `paused`** — its roster entry has `enabled: false`, or the subsystem is off for this session. Enable the entry in `WATCHDOG.yml` (or `/advisor configure`) and run `/advisor on`.
+- **An advisor shows `quota exhausted`** — its provider/account hit a usage limit after fallback recovery was unable to continue. Fix credentials, quota, or the model choice, then toggle the advisor off and on, reload configuration, or start a new session.
+- **An advisor shows `error`** — repeated or permanent request failures halted that reviewer so the main agent could continue. Check provider/model availability and logs, then use `/advisor off` and `/advisor on` to rebuild it.
+- **One roster member fails while others run** — entries are independent. Fix that member's model or enabled state; the rest can continue reviewing.
+- **Changes to `WATCHDOG.yml` do not appear** — check the filename and YAML shape, make sure omp is running in the project tree you intended, then restart omp after a manual file edit. Changes saved through `/advisor configure` apply immediately. A malformed file is skipped and reported in logs.
+- **Review is too expensive or distracting** — choose a cheaper model, reduce the roster, keep `syncBacklog: off`, raise `immuneTurns`, narrow watchdog instructions, or use `/advisor off` for routine work.
+- **A late concern did not restart the agent** — this is expected after a completed answer, after your deliberate interrupt, and in plan mode. The visible note is included when you continue with a new prompt or the continue shortcut.

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

@@ -0,0 +1,168 @@
+<!--
+source: https://omp.sh/docs/agents-and-roles
+fetched: 2026-09-06
+-->
+
+# Agents & model roles
+
+> Choose the model that runs work, the routing slot that selects it, and the reusable specialist that decides how the work is done.
+
+A **model**, a **role**, and an **agent** configure different layers:
+
+| Layer | What it is | Change it when… |
+| --- | --- | --- |
+| **Model** | A concrete provider/model, such as `anthropic/claude-sonnet-4-5` or `openai/gpt-5.4`. | You want different capability, latency, price, context size, or provider credentials. |
+| **Role** | A named routing slot, such as `default`, `smol`, or `slow`, that resolves to a model. | Several features should follow one model choice, or you want to change their model without editing every consumer. |
+| **Agent** | A reusable behavior profile: a name, instructions, allowed tools, and optional model, prewalk, and advisor preferences. | You want a repeatable specialist such as a reviewer, researcher, or designer—not merely a different model. |
+
+An agent can point at a role, and the role points at a model. For example, the `reviewer` agent normally uses `@slow`; changing the `slow` role changes the model used by future reviewer runs without changing what the reviewer does.
+
+## A simple workflow
+
+1. 
+2. 
+3. Use the librarian to verify the upstream API behavior, then summarize the source evidence.Ask the reviewer to inspect the current change for correctness. Do not edit files.Parallelize the UI polish and security check: use the designer for the interface and the security-reviewer for a read-only audit.
+  Ask omp in ordinary language to use the specialist by name:
+4. 
+
+You never need to describe omp's internal delegation protocol. Name the outcome and specialist, add scope or safety limits, and let the main session coordinate the work.
+
+## Open and navigate Agent Hub
+
+Press <kbd>Alt</kbd>+<kbd>A</kbd> to open Agent Hub. <kbd>Ctrl</kbd>+<kbd>S</kbd> opens the same view through the legacy session-observe binding.
+
+There is also a navigation gesture that is easy to miss:
+
+- From an **empty main-session editor**, press <kbd>←</kbd> twice. Agent Hub opens when the current session has a worker to show.
+- While **focused in a worker**, leave its editor empty and press <kbd>←</kbd> twice to return to the main session.
+
+Select a worker and press <kbd>Enter</kbd> to open its live or persisted transcript. A message sent there steers a running worker or follows up with an idle one. Agent Hub also shows status, resolved model, current activity, lineage, tokens, requests, tool calls, active time, and measured cost when available. Use <kbd>r</kbd> to revive a parked worker and <kbd>x</kbd> to kill one whose work should not continue.
+
+See [Subagents & Agent Hub](/docs/subagents) for statuses, isolation, steering, limits, and the complete control reference.
+
+## Choose a bundled agent
+
+These agents ship with omp:
+
+| Agent | Choose it for | Normal model route |
+| --- | --- | --- |
+| `scout` | Fast, read-only repository exploration and compressed findings. | `@smol` |
+| `designer` | UI/UX implementation, accessibility, and visual refinement. | `@designer` |
+| `reviewer` | Evidence-backed correctness, quality, and security review. | `@slow` |
+| `security-reviewer` | Read-only vulnerability discovery and security analysis. | The current session's model fallback |
+| `librarian` | Source-verified research into external libraries and APIs. | `@smol` |
+| `task` | General multi-step work with full available capabilities. | `@task` |
+| `sonic` | Strictly mechanical edits or data collection with little reasoning. | `@smol` |
+
+Use the narrowest suitable specialist. A read-only agent is safer for investigation; `task` is appropriate when no specialist fits; `sonic` is for mechanical work, not ambiguous design or review. Open `/agents` for the effective definitions in your installation because project and user agents can add names or replace bundled ones.
+
+## Choose a role
+
+Built-in roles route product features as well as agents:
+
+| Role | Work routed to it |
+| --- | --- |
+| `default` | Normal interactive work and the main-session default. |
+| `smol` | Fast, inexpensive utility work and the usual prewalk handoff target. |
+| `slow` | Thorough reasoning and review where extra latency is acceptable. |
+| `vision` | Image inspection by a vision-capable model. |
+| `plan` | Plan-mode architecture and review. |
+| `designer` | The bundled designer agent. |
+| `commit` | Commit-message generation. |
+| `tiny` | Very small background tasks such as titles, memory support, and speech cleanup. |
+| `task` | General subagent work. |
+| `advisor` | The independent model that reviews an opted-in session or worker. |
+
+Unassigned built-in roles are resolved automatically from available authenticated models. Assign a role in `/model` when you need stable behavior, cost, or provider choice. Changing the active model for the current conversation does not rewrite saved role assignments.
+
+The [Model roles](/docs/roles) page covers automatic selection, project storage, thinking levels, quick cycling, launch overrides, and retry fallback chains.
+
+## How an agent gets its model
+
+For an ordinary named worker, omp tries these sources in order:
+
+1. **Settings override** — `task.agentModelOverrides.<agent-name>`.
+2. **Agent default** — the agent's `model` frontmatter, which may contain one selector or an ordered list.
+3. **Normal fallback** — the parent session's active model, then its configured/default model fallback.
+
+A selector in either of the first two layers may be a concrete `provider/model` or a role alias such as `@slow`. Role aliases are expanded through `modelRoles` at launch.
+
+Use `task.agentModelOverrides` when you want to reroute an existing agent without copying or editing its definition. Prefer a role alias there when several agents or features should move together:
+
+```yaml
+modelRoles:
+  default: anthropic/claude-sonnet-4-5
+  smol: openai/gpt-4.1-mini
+  slow: openai/gpt-5.4:high
+  review: openai/gpt-5.4:high
+
+task:
+  agentModelOverrides:
+    reviewer: "@review"
+```
+
+With that configuration, `/model` controls which concrete model fills `review`, while `/agents` controls whether `reviewer` uses that role. A concrete model under `agentModelOverrides` bypasses the agent's frontmatter choice and does not move when a role is reassigned.
+
+## User and project agents
+
+Custom agent definitions are Markdown files with YAML frontmatter:
+
+- **User scope:**`~/.omp/agent/agents/*.md` is available across projects.
+- **Project scope:**`.omp/agents/*.md` belongs to the current project.
+
+`/agents` labels definitions as **Project**, **User**, or **Bundled**. Names are case-sensitive. When names collide, the project definition wins over the user definition, and a custom definition wins over the bundled definition. This makes it possible to tailor a standard name such as `reviewer` for one repository, but it can also explain why its behavior differs there.
+
+The model-related part of a definition can stay small:
+
+```md
+---
+name: release-auditor
+description: Check release readiness and report concrete blockers.
+tools: read, grep, glob, bash
+model: "@slow"
+prewalk: false
+advisor: "@advisor"
+---
+
+Inspect the assigned release scope. Report evidence and blockers; do not edit files.
+```
+
+Here `model` participates in the precedence above. `prewalk` and `advisor` provide defaults for this agent; `/agents` can override either without changing the file. Use **New agent** in `/agents` to begin a definition, or follow [Authoring subagents](/docs/subagent-authoring) for all supported frontmatter, tool restrictions, output shapes, skill loading, and validation.
+
+After editing an agent file while omp is running, return to `/agents` and press <kbd>Ctrl</kbd>+<kbd>R</kbd> to reload the list.
+
+## Per-agent prewalk and advisor controls
+
+Select an agent in `/agents` to configure four properties: enabled, model, prewalk, and advisor.
+
+- **Prewalk** starts the worker on its resolved model for planning and early implementation, then makes a one-time handoff to a faster or cheaper target. `on` uses `@smol`; `off` disables it; a model or role pattern chooses another target.
+- **Advisor** pairs that worker with an independent reviewer model. `on` uses `@advisor`; `off` disables it; a model or role pattern chooses another advisor.
+
+The corresponding settings override agent frontmatter and can be edited in `~/.omp/agent/config.yml`:
+
+```yaml
+task:
+  agentPrewalk:
+    task: "@smol"
+    reviewer: "off"
+  agentAdvisor:
+    reviewer: "on"
+    security-reviewer: "@slow"
+```
+
+Use `/settings` for broader defaults and limits. The **Generic Task Prewalk** setting (`task.prewalk`) affects the bundled `task` agent; per-agent choices in `/agents` still take precedence. See [Prewalk](/docs/prewalk), [Advisor](/docs/advisor), and [Settings](/docs/settings) for the full behavior of those systems.
+
+## Cost and troubleshooting
+
+Every worker is a separate model session. Parallel workers multiply provider requests and token use; an advisor adds its own review calls, and prewalk can use two models over one worker's lifetime. Agent Hub reports measured usage and cost when the provider exposes enough data. Start with the smallest useful fan-out, route lightweight work deliberately, and stop obsolete workers.
+
+If the result is not what you expected:
+
+- **Wrong behavior:** confirm the exact agent name and source in `/agents`. A project definition may be shadowing the user or bundled definition.
+- **Wrong model:** inspect the effective model in `/agents`, then check `task.agentModelOverrides`, the agent's `model` frontmatter, and the referenced role in `/model`, in that order. Also confirm that the selected provider is authenticated.
+- **Unknown or disabled agent:** check the case-sensitive name and enabled state, then press <kbd>Ctrl</kbd>+<kbd>R</kbd> after file changes.
+- **Prewalk or advisor does not start:** check the per-agent override first, then frontmatter, role assignment, model availability, and credentials. An unavailable prewalk target is skipped rather than failing the worker.
+- **Double-left does nothing:** empty the editor and confirm this session has a worker to show. <kbd>Alt</kbd>+<kbd>A</kbd> opens Agent Hub even when the roster is empty.
+- **Hub shows no worker:** Agent Hub is scoped to the current session. Return to or resume the session that launched the worker.
+
+For exhaustive behavior, continue with [Model roles](/docs/roles), [Subagents & Agent Hub](/docs/subagents), and [Authoring subagents](/docs/subagent-authoring).