better-dsh 0.2.4 → 0.2.5

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

@@ -0,0 +1,120 @@
+<!--
+source: https://omp.sh/docs/tools
+fetched: 2026-09-06
+-->
+
+# Tools index
+
+> What omp can do, what is available by default, and where to turn capabilities and approvals on or off.
+
+## Ask for the outcome
+
+You normally do not choose or call a tool yourself. Tell omp what you want in ordinary language:
+
+```text
+Find where checkout retries are configured, change the default to three, and verify the behavior.
+```
+
+omp chooses the suitable search, editing, and execution capabilities. Name a capability only when you want to constrain the approach, such as “inspect this without running it,” “use the browser because the page requires sign-in,” or “do not use the shell.”
+
+Use `/tools` in a session to see the capabilities that are actually available to the current model and project. This is the authoritative live view: settings, installed programs, model support, task depth, custom tools, and connected MCP servers can all change it.
+
+## Control what is available
+
+- Open `/settings` and use **Tools → Available Tools** for persistent on/off switches. Related controls also live under **Files**, **Shell**, **Memory**, and **Tasks**. See [Settings](/docs/settings).
+- Start a restricted session with `omp --tools read,glob,grep`, or with no built-ins using `omp --no-tools`. A command-line restriction applies only to that session.
+- Use `omp --approval-mode always-ask`, `write`, or `yolo` for a session. The persistent equivalents are `tools.approvalMode` and per-capability `tools.approval.<name>` policies (`allow`, `prompt`, or `deny`). See [Approvals](/docs/approvals).
+- `tools.xdev` is on by default. It keeps less-frequently-used and dynamically discovered capabilities in an on-demand catalog rather than loading every description up front. Turning it off changes presentation, not what is permitted.
+
+The approval classes below describe potential impact:
+
+- **Read** inspects state without intentionally changing it.
+- **Write** can change files or durable user data.
+- **Exec** can run code, control a process, use a network account, or operate an application.
+- **Mixed** depends on the action. For example, GitHub reading is Read while checkout or push is Exec.
+
+The built-in approval mode currently defaults to `yolo`, which automatically allows all three classes. Choose `always-ask` if you want confirmation before Write and Exec actions, or deny a capability completely with a per-capability policy. A project, plugin, custom tool, or MCP server is still code you must trust; an approval prompt is not a sandbox.
+
+## Explore code, files, and information
+
+| Capability (selection name) | What you can ask for | Availability and prerequisites | Class | Configure / learn more |
+| --- | --- | --- | --- | --- |
+| Read files and resources (`read`) | Explain files or directories; extract text from documents, notebooks, archives, images, SQLite databases, supported internal URLs, and known web pages. | On by default. Web-page reading also requires `fetch.enabled` (on by default); SSH and some image/PDF processing can execute local helpers. | Read; some remote/conversion paths are Exec | [Working with files](/docs/files) |
+| Find paths (`glob`) | Locate files and directories by name or glob pattern. | On by default with `glob.enabled`. | Read | [Working with files](/docs/files) |
+| Search contents (`grep`) | Search local or supported remote content with regular expressions and context. | On by default with `grep.enabled`. | Read; SSH search is Exec | [Working with files](/docs/files) |
+| Search code structurally (`ast_grep`) | Find syntax shapes independent of whitespace and formatting. | Off by default; enable `astGrep.enabled`. | Read | [Structural edits](/docs/editing) |
+| Use language intelligence (`lsp`) | Find definitions and references, inspect symbols and diagnostics, apply code actions, and perform semantic renames. | On by default with `lsp.enabled`; the relevant language server must be installed or configured. `--no-lsp` disables it for a session. | Mixed: inspection is Read; fixes and renames are Write | [Code intelligence](/docs/code-intelligence) |
+| Understand images (`inspect_image`) | Describe or answer questions about a local image through a vision-capable model. | `inspect_image.mode` defaults to `auto`: exposed when the active model cannot inspect images natively. Set it to `on` or `off` explicitly. Requires an available vision model. | Read | [Settings](/docs/settings) |
+| Search the live web (`web_search`) | Research a topic and return current results with source links. | On by default with `web_search.enabled`; at least one configured search provider must be available. | Read | [Web & browser](/docs/web) |
+| Work with GitHub (`github`) | Read repositories, files, issues, PRs and diffs; search GitHub; check out PRs, push changes, and watch Actions. | Off by default; enable `github.enabled`. Requires the `gh` CLI and authentication for private or mutating operations. | Mixed: views/search are Read; checkout, push, and other account actions are Exec | [GitHub](/docs/github) |
+
+## Change code and run work
+
+| Capability (selection name) | What you can ask for | Availability and prerequisites | Class | Configure / learn more |
+| --- | --- | --- | --- | --- |
+| Make precise edits (`edit`) | Modify existing text files with checked, line-anchored patches. | On by default. | Write | [Working with files](/docs/files) |
+| Create or replace content (`write`) | Create or replace files and supported archive entries, or update supported SQLite rows and user-authored internal resources. | On by default. Also carries on-demand capability requests when `tools.xdev` is enabled. | Write; internal-resource updates may be treated as Read | [Working with files](/docs/files) |
+| Apply structural rewrites (`ast_edit`) | Preview syntax-aware codemods and then accept or reject them. | On by default with `astEdit.enabled`; ast-grep support must be available. A preview does not change files until approved. | Write | [Structural edits](/docs/editing) |
+| Run shell commands (`bash`) | Build, test, inspect Git state, run one-off programs, and interact with a terminal process. | On by default with `bash.enabled`; `--no-pty` disables interactive PTY execution. Long commands can move to the background automatically. | Exec | [Working with files](/docs/files) |
+| Compute in a persistent kernel (`eval`) | Analyze data or run iterative Python, JavaScript, Ruby, or Julia computations while preserving state between steps. | Python and JavaScript backends are allowed by default; Ruby and Julia are opt-in. At least one allowed runtime must be reachable. | Exec | [Working with files](/docs/files) |
+| Debug programs (`debug`) | Launch or attach a debugger, set breakpoints, step, and inspect threads, stack frames, scopes, and variables. | On by default with `debug.enabled`, but appears only when a suitable DAP adapter/configuration is available. | Mixed: inspection is Read; launch and process control are Exec | [Debugging](/docs/debugging) |
+| Automate a browser (`browser`) | Open interactive or JavaScript-heavy pages, use authenticated tabs, fill forms, click controls, and capture screenshots. | On by default with `browser.enabled`. omp can launch a browser or attach through CDP, the browser relay, or a supported cmux surface; relay use requires its browser extension. | Exec | [Web & browser](/docs/web) |
+| Control the desktop (`computer`) | Inspect screens and accessibility state, then operate host applications with keyboard and pointer input. | Off by default; enable `computer.enabled`. Requires the supported desktop helper and OS screen-recording/accessibility permissions. | Mixed: inspection is Read; input is Exec | [Computer control](/docs/computer) |
+| Scan for security findings (`security_scan`) | Plan and run native security checks and inspect published findings. | Off by default; enable `security.enabled`. Individual scanners may require their own installed binaries or credentials. | Exec | [Security](/docs/security) |
+| Generate or edit images (`generate_image`) | Create an image from a description or transform supplied images. | Off by default; enable `generate_image.enabled`. Requires credentials for a supported image provider. | Write | [Settings](/docs/settings) |
+| Generate speech (`tts`) | Turn text into an audio file with local speech generation or a configured voice provider. | Off by default; enable `speechgen.enabled`. The selected path may require a local model download or provider credentials. | Write | [Settings](/docs/settings) |
+
+## Coordinate, supervise, and recover
+
+| Capability (selection name) | What you can ask for | Availability and prerequisites | Class | Configure / learn more |
+| --- | --- | --- | --- | --- |
+| Answer a structured question (`ask`) | Let omp pause for a choice, confirmation, or missing detail when it cannot safely derive the answer. | On by default with `ask.enabled`; notification and timeout behavior are configurable. | Read | [Settings](/docs/settings) |
+| Track phases (`todo`) | Keep a visible multi-step checklist and mark work blocked, active, or complete. | On by default with `todo.enabled`; goal/subagent modes may use their own completion surface instead. | Read | [Subagents](/docs/subagents) |
+| Delegate work (`task`) | Fan independent work out to specialist subagents, optionally in isolated workspaces, and collect their results. | Available by default while `task.maxRecursionDepth` permits another level (default depth: 2). Agent definitions and spawn policy can further restrict choices. | Exec | [Subagents](/docs/subagents) |
+| Coordinate peers and processes (`hub`) | Message peer agents, follow or cancel background jobs, and supervise shared long-running processes such as dev servers and debuggers. | Available when collaboration is possible at the current task depth. Process supervision also depends on `launch.enabled` (on by default). | Mixed: status and peer messages are Read; starting or driving processes is Exec | [Subagents](/docs/subagents) |
+| Save and return to context (`checkpoint`, `rewind`) | Mark a conversational checkpoint and later return the session to it. | Both are off by default and enabled together with `checkpoint.enabled`; primarily available to top-level sessions. | Read | [Settings](/docs/settings) |
+
+## Remember and improve
+
+Memory is off by default. Choose a backend under `/settings` → **Memory** before expecting these capabilities in `/tools`.
+
+| Capability (selection name) | What you can ask for | Availability and prerequisites | Class | Configure / learn more |
+| --- | --- | --- | --- | --- |
+| Recall durable knowledge (`recall`) | Retrieve relevant facts or past lessons. | Available with the `hindsight` or `mnemopi` backend. | Read | [Memory](/docs/memory) |
+| Retain durable knowledge (`retain`) | Save a fact, decision, or lesson for future sessions. | Available with the `hindsight` or `mnemopi` backend. | Read under the memory service's own policy | [Memory](/docs/memory) |
+| Reflect across memories (`reflect`) | Synthesize or relate stored knowledge. | Available with the `hindsight` or `mnemopi` backend. | Read | [Memory](/docs/memory) |
+| Maintain Mnemopi memory (`memory_edit`) | Inspect, update, merge, or remove records in the local Mnemopi store. | Available only with the `mnemopi` backend. | Read under the memory subsystem's own policy | [Memory](/docs/memory) |
+| Capture a reusable lesson (`learn`) | Save a lesson and, when useful, turn it into a managed skill. | Off by default; requires `autolearn.enabled` and a `local`, `hindsight`, or `mnemopi` memory backend. | Mixed: memory-only capture can be Read; files or skills are Write | [Memory](/docs/memory) |
+| Maintain managed skills (`manage_skill`) | Create, improve, inspect, or retire auto-learned skills. | Off by default with `autolearn.enabled`; normally exposed only in a top-level session. | Write | [Skills](/docs/skills) |
+
+## Outcome-oriented built-in workflows
+
+These are user entry points rather than general-purpose tools, but they may use several capabilities above on your behalf.
+
+| Workflow | First action | What it does | Learn more |
+| --- | --- | --- | --- |
+| Code review | Run `/review`, then choose a base branch, uncommitted changes, a commit, a PR, or custom instructions. | Distributes a diff across reviewer agents and returns prioritized findings. | [Review](/docs/review) |
+| Commit | Run `omp commit`; add `--dry-run` when you only want a preview. | Analyzes changes, proposes conventional commit grouping and changelog updates, then commits; pushing is opt-in. | [Commit](/docs/commit) |
+| Goal mode | Run `/guided-goal` for an interview, or `/goal` when the objective is already clear. | Keeps working toward one durable, budgeted objective across turns. Its mode-only helper appears only while goal mode needs it. | [Goal mode](/docs/goal) |
+| Plan mode | Run `/plan` before asking for a risky or ambiguous implementation. | Restricts the planning phase to read-only exploration and presents a plan for review before execution. | [Plan mode](/docs/plan) |
+| Vibe mode | Run `/vibe [prompt]` to start direct persistent fast/good worker sessions. | Turns the main session into a director that starts, steers, verifies, and stops persistent workers. | [Vibe mode](/docs/vibe) |
+| Autoresearch | Add an `autoresearch.sh` benchmark harness to a clean Git worktree, then run `/autoresearch [goal]`. | Runs repeated benchmark-backed experiments on a dedicated `autoresearch/*` branch. Some reset/discard controls are destructive; review the dashboard and baseline first. | [Modes](/docs/modes) |
+
+Internal completion and reasoning helpers used by goal mode, subagents, or some model families are intentionally not user-selectable capabilities and are not shown as things to configure.
+
+## Add capabilities
+
+The live `/tools` list can contain more than the built-ins above:
+
+| Source | How it becomes available | Trust and configuration |
+| --- | --- | --- |
+| Custom tools | omp discovers user- or project-authored JavaScript/TypeScript tools when a session starts. | They run as your user. Review project code before loading it; see [Custom tools](/docs/custom-tools). |
+| MCP servers | Connected servers publish their own tools and resources; project `.mcp.json`/`mcp.json` discovery is allowed by default. | A server may reach external accounts or execute local code. Configure and authenticate it through [MCP](/docs/mcp). |
+| Extensions and plugins | Trusted extensions can register tools; plugins can bundle tools with commands, agents, rules, or server configuration. | Inspect the source and declared contents before enabling it; see [Extensions](/docs/extension-authoring) and [Plugins](/docs/plugins). |
+| Host applications | SDK, RPC, and ACP hosts can supply capabilities for their session. | Availability and approval are controlled by that host; see [SDK](/docs/sdk), [RPC](/docs/rpc), and [ACP](/docs/acp). |
+
+## Report a capability problem
+
+Automated tool QA (`xd://report_issue`) is on by default with `dev.autoqa`. When omp detects behavior that contradicts a capability's documented contract, it can record a report; the first report asks whether you consent to sharing it. Use `omp grievances` to inspect recorded reports, and change **Tools → Developer → Auto QA** in `/settings` to disable reporting. This support path does not give omp another way to modify your project.
+
+If a capability you expected is missing, check `/tools`, then its enable setting and prerequisite above. Restart the session after changing discovered tool, extension, plugin, or MCP configuration so the live catalog can be rebuilt.

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

@@ -0,0 +1,242 @@
+<!--
+source: https://omp.sh/docs/ttsr
+fetched: 2026-09-06
+-->
+
+# Time-Traveling Stream Rules
+
+> Stop a specific mistake while omp is generating it, inject the correction, and let the agent try again before the mistake takes effect.
+
+A **Time-Traveling Stream Rule (TTSR)** is a guardrail for a recognizable mistake in the agent's live output: a forbidden API in an edit, an unsafe shell fragment, or a recurring claim in prose. When the rule matches, omp can interrupt that response, show which rule fired, supply the rule's Markdown instructions, and restart generation with the correction in view.
+
+Use TTSR for guidance that is:
+
+- important only when a particular pattern appears;
+- specific enough to detect reliably; and
+- most useful *before* the proposed tool call runs.
+
+This is better than [always-on context](/docs/context-files) when the instruction is narrow or rarely relevant. Always-on context is better for conventions the agent must consider throughout every task, because TTSR is reactive: it cannot help until its condition appears.
+
+## Create the smallest useful rule
+
+From the project root, create `.omp/rules/no-box-leak.md`:
+
+```md
+---
+description: Prevent permanent Box::leak allocations in Rust edits
+condition: 'Box::leak\('
+scope:
+  - 'tool:edit(*.rs)'
+  - 'tool:write(*.rs)'
+---
+
+Do not introduce `Box::leak` in production Rust code. Keep ownership explicit;
+prefer `Arc<str>`, `Cow<'static, str>`, or a true process-lifetime singleton,
+then continue with the option that fits this code.
+```
+
+The filename becomes the rule name, `no-box-leak`. The frontmatter says *when and where* to react; the Markdown body says *why and what to do instead*. Keep the body short and actionable—the model receives it only when the rule fires.
+
+Save rules in one of these native locations:
+
+| Location | Use |
+| --- | --- |
+| `<project>/.omp/rules/<name>.md` or `.mdc` | Project rule; normally commit it with the repository. |
+| `~/.omp/agent/rules/<name>.md` or `.mdc` | Personal rule for every project. The directory follows the active profile and `PI_CODING_AGENT_DIR`. |
+
+Project and user rules are discovered when a session starts. Start a new session after adding or changing a file.
+
+## Test, inspect, and enable it
+
+Test a rule file in isolation before relying on discovery:
+
+```bash
+omp ttsr test \
+  --rule .omp/rules/no-box-leak.md \
+  --source tool --tool edit --path src/lib.rs \
+  'let value = Box::leak(Box::new(input));'
+```
+
+The report should list `no-box-leak` under triggered rules. The source, tool, and candidate path matter: they reproduce the context used by `scope` and `globs`. Other useful checks are:
+
+```bash
+# Show every active TTSR rule, its conditions, scope, and source file.
+omp ttsr list
+
+# Explain both matching and non-matching rules for a sample.
+omp ttsr test --verbose --source tool --tool edit --path src/lib.rs \
+  'let value = Box::leak(Box::new(input));'
+
+# Look for existing files that would match the rule.
+omp ttsr scan --rule .omp/rules/no-box-leak.md src/
+```
+
+`omp ttsr test src/lib.rs` also works: a recognized source-file extension implies a tool/edit context. Use explicit flags when diagnosing a path or scope mismatch. `--json` is available for scripting, and `--file -` reads a sample from stdin.
+
+TTSR is enabled by default. To enable it explicitly and inspect the effective value:
+
+```bash
+omp config set ttsr.enabled true
+omp config get ttsr.enabled
+```
+
+`omp config set` writes the active profile's global `~/.omp/agent/config.yml`. For a project-only override, edit `<project>/.omp/config.yml` instead. Inside omp, `/extensions` is another way to inspect discovered rules and their source paths.
+
+## What firing looks like
+
+With the default `interruptMode: always`, a matching response stops immediately. The TUI shows an **Injecting rule: no-box-leak** notification, the partial attempt is discarded by default, and the agent generates a replacement response using the rule body. A matching edit or write is stopped before that incomplete call executes.
+
+This is an interruption and retry, not a text replacement: the rule should explain the safe alternative rather than attempt to rewrite code itself. A narrowly placed trigger keeps the retry early and inexpensive.
+
+For a soft tool-specific nudge, set `interruptMode: never` on the rule. omp lets the matched tool finish and places the reminder alongside that tool's result for the agent's next step. On prose, `never` lets the response finish and follows it with the correction. Use this only when allowing the matched action to complete is safe.
+
+## Matching and scope
+
+`condition` is a JavaScript regular expression. It is evaluated against the accumulated content for each watched output surface, so it can match across streamed chunks. For `edit` and `write`, omp matches the source content being introduced rather than serialized command syntax. Other tools are matched against their streamed arguments.
+
+Prefer the smallest distinctive pattern:
+
+```yaml
+condition: 'Box::leak\('
+```
+
+Avoid a broad pattern such as `leak`, which also catches discussion, logs, and unrelated identifiers. YAML single quotes make regex backslashes easiest to read. Leading `(?i)`, `(?m)`, and `(?s)` flags are supported; otherwise use JavaScript regular-expression syntax.
+
+A rule may provide a string or a list for `condition`. Multiple regex conditions are alternatives: any one can trigger. `astCondition` provides the same OR behavior with ast-grep patterns. If both kinds are present, either kind can trigger after scope and path gates pass.
+
+With no `scope`, a rule watches assistant prose and every tool's arguments, but not thinking. An explicit scope replaces that default. Supported tokens are:
+
+| Scope token | Watches |
+| --- | --- |
+| `text` | Assistant prose. |
+| `thinking` | The model's thinking stream when the provider exposes one. |
+| `tool` or `toolcall` | Every tool. |
+| `tool:<name>` | One tool, for example `tool:bash`. Bare tool names such as `bash` are also accepted. |
+| `tool:<name>(<glob>)` | One tool only when its candidate path matches, for example `tool:edit(src/**/*.ts)`. |
+
+A comma-separated string and a YAML list are both accepted. Prefer a YAML list when combining scopes. Path globs match normalized paths and basenames. A top-level `globs` field is an additional path gate across all scopes; at least one candidate path must match it.
+
+AST matching is useful when formatting or identifier names make regex too fragile:
+
+```md
+---
+description: Reject TypeScript any assertions
+astCondition:
+  - '$VALUE as any'
+scope:
+  - 'tool:edit(*.ts)'
+  - 'tool:write(*.ts)'
+---
+
+Preserve the real type. Narrow or model it instead of asserting `any`.
+```
+
+`astCondition` works only on source-bearing edit/write content with a recognizable file extension. It examines content introduced by the call, not unchanged code elsewhere in the file. Test it with `--source tool` and `--path`.
+
+## Repeats, cooldowns, and precedence
+
+By default, each rule fires once per session. That fired state is saved with the session, so resuming does not unexpectedly re-arm it. To allow another injection after a cooldown, configure the global repeat policy:
+
+```bash
+omp config set ttsr.repeatMode after-gap
+omp config set ttsr.repeatGap 10
+```
+
+The gap counts completed turns, not seconds or stream fragments. All TTSR rules use this global repeat policy.
+
+Precedence is predictable:
+
+1. Rules named in `ttsr.disabledRules` are removed.
+2. A project native rule wins over a user native rule with the same filename-derived name; more generally, the first rule discovered for a name wins.
+3. A valid rule with `condition` or `astCondition` is a TTSR rule even if it also says `alwaysApply: true`; it is not also injected as always-on context.
+4. A rule's `interruptMode` overrides the global `ttsr.interruptMode`.
+5. If several eligible rules match the same output, omp can inject all distinct matches. If any matching rule requires interruption, the response is interrupted.
+
+Use unique, descriptive filenames to avoid accidental shadowing. Confirm the effective source with `omp ttsr list`.
+
+## Complete rule frontmatter
+
+All fields are optional except that a TTSR rule needs at least one usable `condition` or `astCondition`. String fields marked “list” also accept a single string.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `description` | string | Human-readable summary shown by rule inspection. Recommended. |
+| `condition` | string or string list | JavaScript regex alternatives. A legacy `ttsr_trigger` spelling is accepted, but use `condition` for new rules. |
+| `astCondition` | string or string list | ast-grep pattern alternatives for edit/write source content. |
+| `scope` | string or string list | Output surfaces and optional tool/path filters. Omit for `text` plus all tools, excluding thinking. |
+| `globs` | string or string list | Additional candidate-path gate. This does not replace `scope`. |
+| `interruptMode` | `always`, `prose-only`, `tool-only`, or `never` | Per-rule override for which matching surfaces abort immediately. |
+| `alwaysApply` | boolean | General rule metadata. A valid TTSR condition takes precedence, so combining them does not make the body always-on. |
+| For compatibility, a `condition` value that looks like a file glob (such as `*.rs`) is treated as shorthand for watching `edit` and `write` on that glob with a catch-all condition. Prefer an explicit regex plus `scope`; it makes the trigger's intent and test context clear. |  |  |
+
+The Markdown after frontmatter is the injected instruction. The rule name and source path come from discovery; do not put them in frontmatter.
+
+The complete global TTSR configuration is:
+
+```yaml
+ttsr:
+  enabled: true
+  contextMode: discard       # discard | keep
+  interruptMode: always      # always | prose-only | tool-only | never
+  repeatMode: once           # once | after-gap
+  repeatGap: 10              # completed turns
+  builtinRules: true
+  disabledRules: []          # filename-derived rule names
+```
+
+`contextMode: keep` retains the partial response before retry; `discard` removes it and is safer for most guardrails. `builtinRules: false` disables only omp's bundled TTSR rules, not your files. Disable one rule without deleting it with:
+
+```bash
+omp config set ttsr.disabledRules '["no-box-leak"]'
+```
+
+Start a new session after changing TTSR configuration so discovery and session state are unambiguous.
+
+## Safety and performance
+
+- Scope dangerous-action rules to the relevant tool and file type. Watching all prose and tools increases false positives and matching work.
+- Interrupt before the unsafe fragment is complete. A TTSR match cannot undo a tool call that already finished.
+- Keep regexes linear and specific. Avoid nested, ambiguous repetition such as `(.*)+`, which can become expensive as output grows.
+- Prefer `astCondition` for structural code rules, but constrain it by tool and extension; structural matching costs more than a simple regex.
+- Do not put secrets in rule bodies. The body is sent to the selected model when the rule fires and may be retained in the session.
+- Run `omp ttsr scan` before enabling a broad repository rule. Review matches rather than treating every textual occurrence as a violation.
+- Use `interruptMode: never` only when it is acceptable for the matched tool action to execute.
+
+## Troubleshooting
+
+### `omp ttsr list` does not show the rule
+
+- Confirm the file is `.md` or `.mdc` in `.omp/rules/` or the active profile's `rules/` directory.
+- Ensure frontmatter begins at the first line, has closing `---`, and contains a non-empty `condition` or `astCondition`.
+- Check `omp config get ttsr.enabled`, `omp config get ttsr.disabledRules`, and `omp config get ttsr.builtinRules`.
+- Look for another discovered rule with the same filename-derived name.
+- Start a new session after editing the file.
+
+### The isolated test does not trigger
+
+Run with `--verbose` and reproduce the live context exactly:
+
+```bash
+omp ttsr test --verbose --rule .omp/rules/no-box-leak.md \
+  --source tool --tool edit --path src/lib.rs 'Box::leak('
+```
+
+Check regex escaping, tool name, `scope`, top-level `globs`, and path extension. An AST rule without `--source tool` and a file extension cannot infer a language. Invalid regex and AST patterns are ignored rather than stopping session startup.
+
+### The test triggers but a live session does not
+
+The session may have loaded the previous file, the rule may already have fired under `repeatMode: once`, or the live action may use a different tool/path surface. Start a fresh session, inspect with `omp ttsr list`, and test with the same `--source`, `--tool`, and `--path`.
+
+### The rule fires too often
+
+Narrow `condition`, add a tool/path `scope`, or add `globs`. Use `ttsr.disabledRules` as an immediate off switch while revising it. Do not solve false positives by making the body vague—the trigger should identify the violation.
+
+### The partial response remains visible
+
+Check `omp config get ttsr.contextMode`. Set it back to `discard` for clean retries. Also check whether the rule or global `interruptMode` is `never` for that surface; non-interrupting matches intentionally allow the current response or tool to finish.
+
+## Related
+
+- [Context files](/docs/context-files) — guidance that belongs in every prompt.
+- [Hooks](/docs/hooks) — deterministic interception around tool execution.
+- [Skills](/docs/skills) — on-demand playbooks selected for a task.

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

@@ -0,0 +1,214 @@
+<!--
+source: https://omp.sh/docs/using
+fetched: 2026-09-06
+-->
+
+# Using omp
+
+> Run a complete interactive session: write a request, follow the work, answer decisions, steer or stop it, review changes, and resume safely.
+
+Bare `omp` opens the interactive terminal UI. This is the normal place to do day-to-day work: describe an outcome in ordinary language, let omp inspect and change the project, review what it did, then refine the result in the same conversation.
+
+If you have just finished [Quickstart](/docs/quickstart), start in a project and send one bounded request:
+
+```sh
+cd my-project
+omp
+```
+
+```text
+Find the refresh-token race, fix only the implementation and its focused tests, show me the diff, and run those tests. Do not commit.
+```
+
+Press <kbd>Enter</kbd>. You do not need a slash command or special prompt format for normal work.
+
+## A complete task, turn by turn
+
+A reliable interactive task usually follows this loop:
+
+1. **State the outcome and boundaries.** Name the bug or feature, important paths, anything that must not change, and the check that should pass.
+2. **Let omp investigate.** It will narrate progress and show each read, command, or change as a card in the transcript.
+3. **Intervene when needed.** Send a steering message while it works, answer a question, or reject an unsafe action.
+4. **Review evidence.** Expand tool cards and diffs. Check the changed paths, command exit status, test result, and final explanation.
+5. **Refine in the same session.** Say what is wrong or what remains: “Keep the public signature,” “Add the missing boundary case,” or “Revert the change to `cache.ts`.”
+
+File changes are applied to your working tree as omp works. They are not committed unless you ask for a commit. Your editor, `git diff`, and the transcript remain the final review surfaces.
+
+## Read the screen
+
+The exact colors and status-line layout depend on your theme and settings, but the interactive screen has three working regions:
+
+**Transcript**
+
+Your messages, assistant text and thinking, notices, questions, and tool cards. New activity appears at the bottom. A tool card shows what is pending, succeeded, failed, or was cancelled; edit cards include the affected path and a diff summary.
+
+**Composer**
+
+The bordered editor where you write the next prompt. Autocomplete, attachment chips, queued-message hints, and temporary dialogs appear around it. The hint line at the bottom of a picker or question shows the keys that apply to that focused surface.
+
+**Status line**
+
+The default layout shows the active model and thinking level, work mode, path, Git state, context use, cost, and session name. Narrow terminals omit or shorten segments. Plan, Goal, Vibe, Loop, Fast, collaboration, and related state appear here when relevant.
+
+The status line is not decoration: check it before assuming omp is in the wrong directory, using the wrong model, allowed to write, or out of context. Its presets and segments can be changed in `/settings`; see [Settings](/docs/settings) for the complete reference.
+
+## Compose, attach, and submit
+
+| You want to… | Do this |
+| --- | --- |
+| Send a prompt | Press <kbd>Enter</kbd>. |
+| Insert a newline | Press <kbd>Shift</kbd>+<kbd>Enter</kbd>, <kbd>Ctrl</kbd>+<kbd>J</kbd>, or <kbd>Alt</kbd>+<kbd>Enter</kbd>. Windows Terminal users should prefer <kbd>Alt</kbd>+<kbd>Enter</kbd>. |
+| Mention a project file | Type `@`, continue typing to fuzzy-search, then select the path. omp reads an `@path` mention into the turn automatically. |
+| Complete a path | Type part of a relative, parent, home, or absolute path and use the completion list. <kbd>Tab</kbd> accepts the highlighted completion. |
+| Attach an image | Paste with <kbd>Ctrl</kbd>+<kbd>V</kbd>, or drag or paste an image path. A chip in the composer confirms a pasted attachment. You can also mention `@path/to/image.png`; omp reads that file with the turn. |
+| Attach pasted text | Paste it normally. Multi-line or large pastes can collapse into a numbered paste chip so the editor stays readable; deleting the chip removes that attachment. |
+| Edit a long draft externally | Press <kbd>Ctrl</kbd>+<kbd>G</kbd> to open `$VISUAL`, falling back to `$EDITOR`, then save and close it to return the text to omp. |
+| Recover an earlier prompt | Press <kbd>Ctrl</kbd>+<kbd>R</kbd> to search prompt history. |
+
+You can combine prose, `@file` mentions, pasted text, and images in one prompt. Say what each attachment is for; a path by itself supplies context but not intent. For example:
+
+```text
+Compare @src/auth/refresh.ts with @test/auth/refresh.test.ts. The attached screenshot is the production error. Fix the race without changing the token format, then run the focused test.
+```
+
+Image input is normalized and resized by default. When the active model cannot accept images directly, omp normally asks a configured vision-capable model for a description instead. Image behavior is configurable under **Model → Vision** and **Appearance → Images** in `/settings`.
+
+## Follow the work and review cards
+
+Tool cards are the audit trail between your prompt and the final answer. Read the title first: it identifies the action, command, path, or remote resource. Then check its state and result.
+
+- Press <kbd>Ctrl</kbd>+<kbd>O</kbd> to expand or collapse tool output. Use it for a truncated command transcript or the complete visible diff.
+- Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>O</kbd> to hide or show tool activity when you want a prose-only view.
+- A successful card means that action completed, not that the whole task is correct. Check the final test or verification card separately.
+- A failed or cancelled card remains useful evidence. Read the error, then tell omp whether to retry, use another approach, or stop.
+- For edits, inspect the path and additions/removals. Ask for a correction immediately if the scope or behavior is wrong.
+
+For a deeper file-change workflow and safety settings, see [Working with files](/docs/files).
+
+## Answer approvals and questions
+
+If your approval mode or a per-tool policy requires confirmation, omp pauses before the action and shows what it wants to do. Read the command, target, diff preview, and reason rather than approving from the title alone. Select the offered allow or reject choice with the picker keys shown on screen. <kbd>Escape</kbd> cancels the prompt; no approval is inferred from dismissal.
+
+When omp needs product input, it may show a question dialog:
+
+- Use <kbd>Up</kbd>/<kbd>Down</kbd> to move and <kbd>Enter</kbd> to choose a single answer.
+- For a multi-select question, press <kbd>Space</kbd> to toggle choices, then <kbd>Enter</kbd> to advance.
+- Use the **Other** row to type a custom answer. Press `n` on a row when the dialog offers an explanatory note.
+- For several questions, <kbd>Tab</kbd>, <kbd>Shift</kbd>+<kbd>Tab</kbd>, or <kbd>Left</kbd>/<kbd>Right</kbd> changes tabs; review and submit on the final tab.
+- Press <kbd>Escape</kbd> to cancel rather than guess. You can then explain the missing constraint in the composer.
+
+The default **Yolo** approval mode permits normal read, write, and execution actions, so you may not see approval prompts. Choose **Always ask** in `/settings` under **Interaction → Approvals**, or launch with `omp --approval-mode always-ask`, when you want confirmation before writes and commands.
+
+## Steer, queue, stop, and continue
+
+You can type while omp is working. The submit key decides whether the message should affect the current turn or wait for the next one.
+
+| Action | Default key | Use it when… |
+| --- | --- | --- |
+| Steer the active turn | <kbd>Enter</kbd> | The current approach needs a correction: “Do not change the schema,” “Use the existing helper,” or “Stop after investigation.” |
+| Queue a follow-up | <kbd>Ctrl</kbd>+<kbd>Q</kbd> or <kbd>Ctrl</kbd>+<kbd>Enter</kbd> | The current task should finish first: “After that, explain the migration risk.” |
+| Return queued input to the composer | <kbd>Alt</kbd>+<kbd>Up</kbd> or <kbd>Shift</kbd>+<kbd>Up</kbd> | You queued the wrong text or want to edit pending messages. |
+| Interrupt the active operation | <kbd>Escape</kbd> | A turn, local shell/Python escape, retry, or other active operation should stop. |
+| Continue the prior intent | Send `.` or `c` | You interrupted at the right point and want omp to carry on without restating the task. |
+| Retry the last failed assistant turn | <kbd>Alt</kbd>+<kbd>R</kbd> | A provider or turn failed and the same request should be attempted again. |
+
+A steering message is for **now**; a follow-up is for **after the agent yields**. The pending-message strip shows what is queued. The `steeringMode`, `followUpMode`, and `interruptMode` settings control whether queued messages drain together or one at a time and whether steering interrupts immediately or waits.
+
+<kbd>Escape</kbd> is focus-sensitive. If autocomplete or a picker is open, the first press dismisses that surface. In the main composer it interrupts active work. It does not exit omp. In Loop mode it stops the current iteration while leaving Loop enabled; run `/loop` again to disable Loop. See [Run modes](/docs/modes) for the exact mode behavior.
+
+## Choose the model and thinking level
+
+Use the defaults until a task gives you a reason to change them. The active selection is always visible in the status line.
+
+| Control | Result |
+| --- | --- |
+| `/model` or <kbd>Alt</kbd>+<kbd>M</kbd> | Open the model hub and inspect or change persistent model-role assignments. |
+| `/switch` or <kbd>Alt</kbd>+<kbd>P</kbd> | Choose a temporary model for the current session without changing the saved role assignment. |
+| <kbd>Ctrl</kbd>+<kbd>P</kbd> / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> | Cycle forward or backward through the configured role-model order. |
+| <kbd>Shift</kbd>+<kbd>Tab</kbd> | Cycle the thinking effort supported by the active model, including Auto when configured. |
+| <kbd>Ctrl</kbd>+<kbd>T</kbd> | Show or hide thinking blocks in the transcript. This changes visibility, not the reasoning effort. |
+
+A higher thinking level can improve difficult reasoning but usually increases latency and token use. A model that does not support configurable thinking will say so instead of changing. When Auto is selected, the status line shows the resolved effort once the turn is classified.
+
+See [Model roles](/docs/roles) for persistent assignments, the quick-cycle order, and per-session overrides.
+
+Interactive work modes change how a turn behaves, not how you talk to omp. The status line tells you when one is active:
+
+- **Plan** explores and proposes without changing the working tree until you approve it. See [Plan mode](/docs/plan).
+- **Goal**, **Vibe**, **Prewalk**, **Loop**, **Fast**, and related controls are specialized workflows. Start with ordinary interactive turns and choose them deliberately from [Run modes](/docs/modes).
+- If omp unexpectedly refuses to edit or keeps going after a turn, check the mode segment first. Leave or disable that mode with its slash command rather than fighting it with repeated prompts.
+
+## Run a local command yourself
+
+A leading escape runs directly from the composer without asking the model to choose or invoke anything:
+
+```text
+! git status
+!! git diff --stat
+$ print(2 + 2)
+$$ import os; print(os.getcwd())
+```
+
+| Prefix | Behavior |
+| --- | --- |
+| `! command` | Run the command in your user shell, stream the result in the TUI, and include it in conversation context. |
+| `!! command` | Run and display it, but exclude its output from model context. |
+| `$ code` | Run Python in the session's shared Python kernel and include the result in context. A space after `$` is required, so prose such as `$HOME` remains prose. |
+| `$$ code` | Run Python and display it without adding the output to model context. |
+
+Press <kbd>Escape</kbd> to cancel a running shell or Python escape. A successful `! cd path` also moves omp's interactive working directory. These commands run with your local user permissions and can change files immediately; `!!` and `$$` exclude output from model context but are not a security sandbox.
+
+## Move around sessions without losing work
+
+You do not need to exit to change conversation state:
+
+| Command | What it is for |
+| --- | --- |
+| `/tree` | Move to an earlier message or another branch in the current session. Use it when a turn went sideways. |
+| `/branch` | Start an alternative thread from an earlier message in the same session file. |
+| `/fork` | Clone the conversation into a new session file before trying a separate approach. |
+| `/resume` | Open the session picker for this project. |
+| `/new` | Start a fresh session while keeping the current one on disk. |
+| `/session info` | Show the current session id, path, lineage, and statistics. |
+| `/compact` | Summarize older active context when the context meter is high while retaining navigable history. |
+
+The tree and session pickers display their own navigation hints. <kbd>Escape</kbd> clears an active search first, then closes the picker. Full branching, resume, export, and handoff behavior lives on [Sessions](/docs/sessions).
+
+## Exit and recover
+
+Use `/exit`, `/quit`, `/q`, or <kbd>Ctrl</kbd>+<kbd>D</kbd> for an orderly exit. <kbd>Ctrl</kbd>+<kbd>D</kbd> saves a non-empty unsent composer draft; resuming that session restores it once. <kbd>Ctrl</kbd>+<kbd>C</kbd> clears the composer, and a second press within half a second exits, so prefer <kbd>Ctrl</kbd>+<kbd>D</kbd> when you mean “leave and keep my draft.”
+
+From the same project directory, restart the most recent session with:
+
+```sh
+omp -c
+```
+
+Use `omp -r` for the project session picker. This is also the recovery path after SSH or terminal disconnects; the persisted transcript is replayed, including an in-flight tail when one is still being written.
+
+### Common stuck states
+
+| What you see | Recovery |
+| --- | --- |
+| Keystrokes move a list instead of editing the prompt | A picker, autocomplete menu, or question has focus. Read its footer or press <kbd>Escape</kbd> to close it. |
+| A queued message is wrong | Press <kbd>Alt</kbd>+<kbd>Up</kbd> or <kbd>Shift</kbd>+<kbd>Up</kbd>, edit the restored text, and submit again. |
+| The agent is taking the wrong path | Send a concrete steering message with <kbd>Enter</kbd>. If continuing would be harmful, press <kbd>Escape</kbd>, review what already changed, then give the correction. |
+| You stopped a good turn by accident | Send `.` or `c` to continue the previous intent. |
+| A response failed | Read the error card, then press <kbd>Alt</kbd>+<kbd>R</kbd> to retry or change the model with `/model`. |
+| Tool output or a diff looks incomplete | Press <kbd>Ctrl</kbd>+<kbd>O</kbd> to expand it. |
+| The terminal display is garbled after resize or reconnect | Press <kbd>Alt</kbd>+<kbd>L</kbd> to reset and repaint the display. |
+| omp will inspect but not edit | Check for Plan mode and the approval prompt or policy shown on screen. Approve the action, leave Plan, or adjust **Interaction → Approvals** deliberately. |
+| Context use is near its limit | Finish the current thought, then run `/compact`. See [Memory and compaction](/docs/memory). |
+| The terminal disconnected or omp exited | Return to the project directory and run `omp -c`; use `omp -r` if it was not the most recent project session. |
+| You cannot remember a shortcut | Run `/hotkeys`, then see [Keybindings](/docs/keybindings) for every action and remapping syntax. |
+
+## Keep the reference pages nearby
+
+This page covers the everyday journey. Use these for exhaustive details:
+
+- [Slash commands](/docs/slash) — every built-in command and alias.
+- [Keybindings](/docs/keybindings) — every default chord, focused-surface behavior, platform notes, and remapping.
+- [Settings](/docs/settings) — configuration locations, precedence, and every interactive option.
+- [Sessions](/docs/sessions) — resume, tree navigation, branching, forking, export, and sharing.
+- [Run modes](/docs/modes) — launch modes and interactive work controls.
+- [Working with files](/docs/files) — file, diff, approval, and verification workflows.