better-dsh 0.2.4 → 0.2.5

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

@@ -0,0 +1,195 @@
+<!--
+source: https://omp.sh/docs/compaction
+fetched: 2026-09-06
+-->
+
+# Compaction
+
+> Keep long omp sessions useful: let automatic context maintenance run, or recover deliberately with /compact, /handoff, and /shake.
+
+Long sessions eventually contain more text than a model can consider at once. omp keeps the work moving by compacting older context while preserving the recent conversation. You normally do not need to do anything: automatic compaction is enabled by default.
+
+Start with:
+
+```text
+/context
+```
+
+This shows how much of the active model's context window is in use and how much room remains before automatic maintenance. Keep working normally unless omp has lost an important detail, the context is dominated by bulky output, or you want to choose what survives.
+
+## What automatic compaction does
+
+As the context approaches the active model's limit, omp first removes stale file reads, empty searches, and other bulky results that are safe to elide. It then tries the configured maintenance methods in order. The default order is:
+
+1. provider-native server compaction, when the active route supports it;
+2. **snapcompact**, which archives older history into dense images for a vision-capable model;
+3. a structured **handoff** summary;
+4. **shake**, which removes recoverable command, search, and file-output bulk without a summarization request;
+5. **soft** compaction, which summarizes older history with a model.
+
+An unavailable or failed method advances to the next one. The default order therefore works across text-only and vision-capable models without model-specific configuration.
+
+Whichever method succeeds, the active model keeps the recent tail of the conversation and receives a compact replacement for older context. Exact wording from the older turns is no longer in the model's live window, but normal compaction does not delete the original session record.
+
+Automatic maintenance can happen:
+
+- after a successful response crosses the threshold;
+- between model requests during a long turn involving many commands or file reads;
+- after a context-overflow or incomplete-output response, followed by a retry;
+- while idle, but only when idle compaction is explicitly enabled.
+
+By default, omp can prepare a summary shortly before the threshold so the visible pause is smaller. After threshold maintenance it continues the work automatically. Overflow and incomplete-output recovery retry the interrupted work instead.
+
+### What you see
+
+The TUI shows a status such as `Auto server compaction…`, `Auto-snapcompact…`, `Auto-handoff…`, or `Auto-shake…`. Press `Esc` to cancel it. Text entered while compaction is running waits until maintenance finishes.
+
+After a summarizing method succeeds, the transcript is rebuilt around a slim divider such as `soft-compacted`, `remote-compacted`, or `handed-off`, usually with a token reduction such as `256K→20K`. Pre-compaction history is collapsed by default. Press `Ctrl+O` to expand the summary at the divider.
+
+Automatic shake instead reports `Auto-shake completed` and replaces eligible heavy regions with short placeholders. With `compaction.autoContinue: true` (the default), threshold-triggered maintenance continues without waiting for another prompt.
+
+## Choose a manual recovery path
+
+Use the least destructive command that matches the problem:
+
+| Situation | Command | Visible result |
+| --- | --- | --- |
+| The session is healthy, but you want more room or want to emphasize particular decisions | `/compact [focus]` | Older context becomes a compact summary/archive, a compaction divider appears, and omp waits for your next instruction. |
+| The next phase needs a structured account of goals, decisions, progress, and next steps | `/handoff [focus]` | omp shows `Generating handoff…`, then replaces older live context with the handoff document and reports `Context handed off and compacted in place`. |
+| Large command output, file contents, generated blocks, images, or stored reasoning are crowding out the conversation | `/shake [elide | images |
+| Nothing is wrong | Do nothing | Automatic maintenance runs at the configured threshold. |
+
+### `/compact`: the normal manual choice
+
+Run `/compact` to compact now using the first usable configured manual method:
+
+```text
+/compact
+```
+
+Add focus instructions when older context contains several threads and one matters most:
+
+```text
+/compact Preserve the API decisions, unresolved test failure, and exact next steps. Treat benchmark experiments as disposable.
+```
+
+You can select a one-off method without changing settings:
+
+| Syntax | Use it when |
+| --- | --- |
+| `/compact soft [focus]` | You want a conventional model-written summary and optionally want to direct it. |
+| `/compact remote [focus]` | You want provider-native OpenAI-compatible compaction when available; it falls back to soft compaction. |
+| `/compact snapcompact` | You want local image archival with a vision-capable model and no summarization request. It does not accept focus text. |
+
+Manual `/compact` works even when automatic compaction is disabled. If a response is currently running, the command aborts that response before compacting. During the operation the TUI shows `Compacting context… (esc to cancel)`; after success, the divider and reduced context usage confirm the result.
+
+### `/handoff`: preserve structured project state
+
+Use `/handoff` when a generic conversation summary is too loose—for example, before moving from investigation to implementation or when a long task has many decisions and dependencies:
+
+```text
+/handoff Focus on the accepted design, files already changed, verification still needed, and known risks.
+```
+
+Despite the name, the manual command currently **compacts the current session in place**. It does not open a successor session and does not save a Markdown handoff file by default. Wait for the current response to finish, or abort it, before running `/handoff`. See [Handoff](/docs/handoff) for the handoff document's contents and automatic handoff behavior.
+
+### `/shake`: remove bulk without summarizing the conversation
+
+`/shake` defaults to `elide`:
+
+```text
+/shake
+```
+
+It replaces eligible command, search, and file-read output plus large fenced or XML-like blocks with short placeholders. In a persisted session, omp also saves the removed regions as a session artifact when possible; the placeholder includes an `artifact://…` recovery reference. If a removed result becomes important later, ask omp to recover the named region from that reference.
+
+The targeted variants are more destructive:
+
+| Command | Removes | Recovery |
+| --- | --- | --- |
+| `/shake elide` | Eligible heavy results and large blocks | Original regions are saved to an artifact when the session can persist one. |
+| `/shake images` | Image blocks from the session | No recovery artifact is created. |
+| `/shake thinking` | Stored reasoning blocks | No recovery artifact is created. |
+
+Use image or thinking removal only after that material is no longer needed. A result such as `Nothing to shake`, `No images found`, or `No thinking blocks found` is a successful no-op, not an error.
+
+## Configuration
+
+The defaults are appropriate for most users. Change them through `/settings`, shell commands such as `omp config set`, or YAML in `~/.omp/agent/config.yml` (an existing `config.yaml` is also honored). Project overrides can live in `<project>/.omp/config.yml`.
+
+For example, this opts into idle maintenance while keeping the normal automatic behavior:
+
+```yaml
+compaction:
+  enabled: true
+  idleEnabled: true
+  idleThresholdTokens: 200000
+  idleTimeoutSeconds: 300
+```
+
+Verify effective values from your shell:
+
+```bash
+omp config get compaction.enabled
+omp config get compaction.methodOrder
+omp config get compaction.thresholdPercent
+```
+
+Inside a session, run `/context` to verify the resulting threshold and available slack.
+
+### Settings reference
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `compaction.enabled` | `true` | Enables automatic maintenance. Manual `/compact`, `/handoff`, and `/shake` remain available when false. |
+| `compaction.methodOrder` | `[remote, snapcompact, handoff, shake, soft]` | Ordered automatic fallback list. Supported values are `remote`, `snapcompact`, `handoff`, `shake`, and `soft`. |
+| `compaction.thresholdTokens` | `-1` | Fixed trigger when greater than zero. It takes precedence over `thresholdPercent`. |
+| `compaction.thresholdPercent` | `-1` | Percentage trigger when greater than zero. `-1` uses reserve-based automatic sizing. Values are clamped to 1–99%. |
+| `compaction.reserveTokens` | unset | Headroom used by reserve-based sizing. When unset, omp normally reserves the larger of 16,384 tokens or 15% of the model window; small windows fall back to the proportional reserve. |
+| `compaction.keepRecentTokens` | `20000` | Target amount of recent conversation retained verbatim after summarizing compaction. |
+| `compaction.midTurnEnabled` | `true` | Allows maintenance at safe boundaries during a long turn involving many commands or file reads. |
+| `compaction.asyncEnabled` | `true` | Prepares eligible summarization shortly before the threshold to reduce the pause when compaction commits. |
+| `compaction.autoContinue` | `true` | Continues automatically after post-turn threshold maintenance. Set false when a scripted or headless run should stop there. |
+| `compaction.idleEnabled` | `false` | Enables maintenance while the session is idle. |
+| `compaction.idleThresholdTokens` | `200000` | Minimum context size for idle maintenance. |
+| `compaction.idleTimeoutSeconds` | `300` | Idle time before maintenance is considered. |
+| `compaction.handoffSaveToDisk` | `false` | Saves documents generated by **automatic** handoff to disk. It does not make manual `/handoff` save a file. |
+| `compaction.supersedeReads` | `true` | Elides older copies of file contents after the same file is read again, when caching conditions permit. |
+| `compaction.dropUseless` | `true` | Elides consumed output that carries no useful context, such as empty searches or timed-out waits. |
+| `compaction.remoteEndpoint` | unset | Uses a custom OpenAI-compatible remote compaction endpoint. Most users should leave this unset. |
+| `compaction.remoteStreamingV2Enabled` | `true` | Uses streaming remote compaction on compatible routes. |
+| `compaction.v2RetainedMessageBudget` | `64000` | Caps the recent-message budget retained by streaming remote compaction. |
+
+`display.collapseCompacted` is a related appearance setting. It defaults to `true`, hiding pre-compaction history from the live transcript while leaving the summary divider visible. Set it to `false` if you prefer the full stored transcript inline.
+
+## Troubleshooting
+
+### Automatic compaction did not run
+
+1. Run `/context`. Maintenance does not run merely because a session feels long; the estimated usage must cross the resolved threshold.
+2. Check `omp config get compaction.enabled` and `omp config get compaction.methodOrder`.
+3. If you expected idle maintenance, remember that `compaction.idleEnabled` defaults to `false` and the session must exceed `idleThresholdTokens` for at least `idleTimeoutSeconds`.
+4. If one method is unavailable, let the fallback list proceed. A text-only model, for example, cannot use snapcompact but can continue to handoff, shake, or soft compaction.
+
+### `/compact` says the session is too small or already compacted
+
+`Nothing to compact (session too small)` means there is not enough older context to replace. `Already compacted` means no substantial new history exists beyond the latest boundary. Continue working and try again later; no recovery is required.
+
+### Snapcompact fails
+
+Snapcompact requires a vision-capable active model and text its bundled image font can represent. Use `/compact soft` for a predictable text summary. `/compact remote` is another option when the current provider supports server compaction.
+
+### Context is still too large
+
+Run `/context` to identify whether messages or bulky historical results dominate. Use `/shake` first for heavy output; use `/compact soft` when the conversation itself is large. If this repeats, lower `compaction.thresholdPercent`, reduce `compaction.keepRecentTokens`, or choose a model with a larger context window rather than waiting for overflow.
+
+### An important old detail is missing
+
+Press `Ctrl+O` on the compaction divider to inspect the generated summary. Normal compaction preserves the underlying session history, so use the [session tree](/docs/sessions) to revisit or branch from an earlier point. For future manual compactions, include explicit focus instructions or use `/handoff` for a more structured continuation. Content removed by `/shake images` or `/shake thinking` is not preserved in a recovery artifact.
+
+## Related
+
+- [Handoff](/docs/handoff) — structured continuation summaries and automatic handoff behavior.
+- [Sessions](/docs/sessions) — stored history, resume, branches, and the session tree.
+- [Settings](/docs/settings) — configuration files, precedence, `/settings`, and `omp config`.
+- [Memory](/docs/memory) — durable facts across sessions; separate from context compaction.

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

@@ -0,0 +1,224 @@
+<!--
+source: https://omp.sh/docs/computer
+fetched: 2026-09-06
+-->
+
+# Computer control
+
+> Let omp inspect and operate real desktop applications through screenshots, native input, and the operating system accessibility tree.
+
+## Control the desktop, not just a web page
+
+Computer control lets omp work with the desktop you are looking at: IDEs, terminals, office applications, browser chrome, native dialogs, and system settings. It can inspect windows and displays, take screenshots, use native accessibility controls, click, type, scroll, press shortcuts, and read or replace clipboard text.
+
+It is disabled by default because it can see private screen content and act in real applications. A mistaken click can affect an account, send a message, change a setting, or overwrite data. Enable it only when you need native desktop access, and keep an approval boundary around actions that change anything.
+
+For a cautious one-session trial, start omp in the desktop session you want it to control and enter:
+
+```text
+/computer on
+/computer status
+```
+
+Then make an inspection-only request in normal language:
+
+```text
+Inspect the currently focused application and tell me its window title and
+visible controls. Do not click, type, change the clipboard, or grant permissions.
+```
+
+You never need to invoke the computer-control machinery yourself. Describe the target, the result you want, what omp may change, and where it must stop.
+
+## Browser or computer control?
+
+Use the narrowest surface that can finish the task.
+
+| Need | Use |
+| --- | --- |
+| Read or interact with a web page through DOM and web accessibility information | [Browser control](/docs/web) |
+| Work in a Chromium tab, including an authenticated Chrome tab connected through the browser relay | [Browser control](/docs/web) |
+| Operate a native app, browser toolbar, file picker, system dialog, or the desktop itself | Computer control |
+| Interact with a web app whose controls are not usable through the page structure | Try browser control first; use computer control only when pixels or native chrome are required |
+
+Browser control understands page elements and stays within the selected browser tab. Computer control sees OS windows and screen pixels; it does not have a web page DOM. A browser window is just another desktop window to it. For forms and authenticated sites, browser control is usually more precise and exposes less of the surrounding desktop.
+
+## Enable it safely
+
+`/computer on` enables computer control only for the current session. `/computer off` removes it from the active tool set immediately. To make it available in future sessions, use **Tools → Available Tools → Computer** in `/settings`, or edit `~/.omp/agent/config.yml`:
+
+```yaml
+computer:
+  enabled: true
+  display: all
+  maxWidth: 3840
+  maxHeight: 2400
+
+tools:
+  approval:
+    computer: prompt
+```
+
+This policy asks before every computer-control run. It is a good first configuration because enabling the capability does not silently authorize its use.
+
+If you want inspection to proceed without prompts while still confirming input-capable runs, remove the per-tool override and set the global approval mode to `write`:
+
+```yaml
+tools:
+  approvalMode: write
+```
+
+In that mode, omp can perform a run it has classified as inspection-only, while desktop input and mutation require confirmation. The mode applies to other tools too. A per-tool `computer: allow`, `prompt`, or `deny` overrides the global mode; use `deny` when desktop control must remain blocked even if someone enables it for the session. Avoid `allow` and `--yolo` on a desktop that contains valuable accounts or data.
+
+Changes made with `/computer` are temporary and do not rewrite the config file. Start a new session after editing a settings file. See [Settings](/docs/settings) for config locations and precedence.
+
+### Limit what screenshots include
+
+The default `display: all` creates a composite of every display. That is convenient, but it may expose unrelated windows and increases image size. Ask omp to list connected display names and IDs without taking action, then replace `all` with the native ID you want to expose.
+
+`maxWidth` and `maxHeight` cap screenshot dimensions. Their defaults are 3840 × 2400. Some model transports apply a smaller coordinate-safe limit automatically. Lower values reduce transferred image detail; they do not change which windows are visible within the selected display.
+
+There is no backend setting. omp selects the native backend for the operating system and desktop session.
+
+## Grant operating-system permissions
+
+Enablement in omp and permission from the operating system are separate gates. Grant only the capabilities you intend to use.
+
+### macOS
+
+Open **System Settings → Privacy & Security** and grant:
+
+- **Screen Recording** to capture displays and windows.
+- **Accessibility** to inspect accessibility controls and send native input.
+
+Grant the entries macOS presents for the application that launches omp, such as your terminal or IDE. Fully quit and reopen that launching application after changing either permission, then start omp again. A capture can work while clicks fail when Screen Recording is granted but Accessibility is not.
+
+### Linux on X11
+
+Run omp inside the logged-in graphical session with access to the intended `DISPLAY`. Capture and input require a readable X11 display with RandR and XTEST. Semantic accessibility requires the desktop's AT-SPI service. There is normally no omp-specific permission dialog; missing session services appear as unavailable capabilities.
+
+### Linux on Wayland
+
+Native input uses the desktop's RemoteDesktop portal, or an administrator-provided `LIBEI_SOCKET`. The portal asks for permission lazily when input is first needed. That grant is not persisted by omp and closes with the desktop-control session; an inspection-only accessibility request does not open the input portal.
+
+Released omp binaries do not include Wayland ScreenCast/PipeWire capture, so screenshots report unavailable on those builds. A custom build with Wayland screencast support uses the compositor's ScreenCast portal. AT-SPI can still provide window and control information when the application exposes it.
+
+Wayland compositors do not let omp activate an arbitrary background window. Focus the target yourself when native input is required, or ask omp to use an available accessibility action.
+
+### Windows
+
+Windows x64 uses native display and window capture, Win32 input, and UI Automation accessibility. Run omp in the interactive desktop session that contains the target applications. The current backend reports capture, input, and accessibility availability through `/computer status`; there is no omp backend selector to configure.
+
+## Ask for a desktop task
+
+A useful request names the application or window, states the allowed changes, and places a boundary before any consequential step.
+
+```text
+In the open Calendar app, inspect next Tuesday and summarize my free blocks.
+Do not create or edit events.
+```
+
+```text
+In the focused spreadsheet, enter these four values into cells B2:B5 and save
+the existing file. Do not rename, move, or close it.
+```
+
+```text
+Open the desktop mail app, draft a reply to Casey using the text below, and stop
+with the draft visible. Do not send it.
+```
+
+```text
+Check whether Screen Recording and Accessibility are enabled for my terminal.
+Tell me what is missing, but leave permission changes for me to make manually.
+```
+
+For an unfamiliar app, ask omp to inspect first and report the intended control before it acts. For a long workflow, define checkpoints such as “stop before Submit,” “do not replace an existing file,” or “ask before switching to foreground input.”
+
+## How omp observes and acts
+
+omp prefers the operating system accessibility tree when an app exposes one. Accessibility controls carry semantic roles, labels, values, and actions, so omp can target a named button or field without estimating a pixel coordinate. This is more reliable across window movement, scaling, and theme changes.
+
+Screenshots are used when appearance matters or the app does not expose a usable accessibility control. Pixel actions are grounded in the latest screenshot of that same target. After a UI change, omp should take a fresh accessibility snapshot or screenshot before the next action rather than assuming the screen stayed the same.
+
+Both sources can reveal sensitive information. Accessibility data may include text that is visually clipped or masked, while screenshots may include notifications and neighboring windows. Narrow the display, close unrelated windows, and use a dedicated account or VM for risky automation.
+
+### Background and foreground input
+
+Input normally targets a window in the background so your focus, pointer position, and window order are not disturbed. Not every OS or application can accept every event this way:
+
+- On macOS, keyboard delivery to one window of a multi-window app may be ambiguous. omp should use an accessibility action or ask before briefly bringing the target forward.
+- Some applications reject background pointer or keyboard events. omp reports the failure instead of treating the action as successful.
+- On Wayland, arbitrary per-window background input and programmatic window raising are unavailable. Only the currently focused surface can receive native desktop input.
+
+When foreground delivery is necessary, the target may appear briefly and omp attempts to restore the previous focus afterward. If that would interrupt your work, say “do not use foreground input; stop if background control is unavailable.”
+
+## Approval and consequential actions
+
+Tool approval and task authorization are different safety layers:
+
+- The approval policy decides whether a proposed computer-control run is allowed, confirmed, or blocked.
+- Your direct message determines what consequential action is authorized. On-screen text, a website, an email, or a dialog cannot grant permission to do more.
+
+Unless your request already authorizes the exact target, scope, and values, omp must confirm immediately before sending or publishing, purchasing or transferring, deleting data, changing account security, granting permissions, disclosing private data, accepting legal terms, or making another irreversible change. Provider safety checks also require explicit interactive approval and fail closed when approval is unavailable.
+
+Review approval prompts in context. If the target or effect is unclear, deny the run and restate the request more narrowly. An instruction such as “handle this website” is not a safe authorization to accept terms or complete a purchase; name the exact allowed outcome and the point where omp must stop.
+
+## `/computer` controls
+
+| Command | Effect |
+| --- | --- |
+| `/computer` | Toggle computer control for this session |
+| `/computer on` | Enable it for this session |
+| `/computer off` | Disable it for this session |
+| `/computer status` | Show effective enablement, active state, model, display limits, backend, permissions, and input modes |
+
+`/computer status` may show `session not started` before the first desktop request. After a request initializes the native session, run the command again to see capture, input, accessibility, and background-input availability. The command reports runtime facts; it does not request or grant OS permission.
+
+## Supported platforms
+
+| Platform | Current capability and limits |
+| --- | --- |
+| macOS x64 and arm64 | Quartz display/window capture, native input, and macOS accessibility. Screen Recording and Accessibility permissions are required. Background input is available where the OS can safely target the window. |
+| Linux X11 x64 and arm64 | Display/window capture and X11 input; AT-SPI accessibility when available. Requires a usable X11 session with RandR and XTEST. |
+| Linux Wayland x64 and arm64 | AT-SPI accessibility and portal/libei input where available. Released binaries omit screenshot capture. Per-window background input and arbitrary window activation are unavailable. |
+| Windows x64 | Native display/window capture, Win32 input, and UI Automation accessibility. |
+| Other targets | Unsupported unless the installed native addon reports capabilities. |
+
+Capabilities are runtime facts. A supported operating system can still lack capture, input, or accessibility because of permissions, the current display server, the application, or how omp was packaged.
+
+## Troubleshooting
+
+### Computer control is missing
+
+Run `/computer status`, then `/computer on`. If the response says it is unavailable, confirm `computer.enabled` in `/settings` or the effective config and start a new session after file-based changes. Also check that a restrictive tool list did not exclude computer control.
+
+### Status says `session not started`
+
+This is normal before the first request. Ask for a non-mutating inspection, then run `/computer status` again. The initialized status includes the selected backend and permission state.
+
+### Screenshots are blank or unavailable
+
+- On macOS, grant Screen Recording and restart the application that launched omp.
+- On X11, confirm omp is running in the intended graphical session and can access `DISPLAY`.
+- On released Wayland builds, screenshot capture is unavailable by design; use accessibility inspection where possible or use an X11 session.
+- If the wrong monitor appears, ask omp to list displays, set `computer.display` to the intended ID, and begin a new session after editing the config file.
+
+### omp can inspect but cannot click or type
+
+On macOS, check Accessibility permission. On Wayland, accept the RemoteDesktop portal when input is first needed, or arrange `LIBEI_SOCKET`; focus the target before requesting native input. On every platform, `/computer status` distinguishes capture, input, and accessibility permission.
+
+### Background input is unavailable
+
+Ask omp to use the app's accessibility control. If that is not possible, explicitly allow foreground input, or focus the window yourself on Wayland. Do not assume a rejected background action landed.
+
+### The wrong control was targeted
+
+Ask omp to stop, inspect the window again, and identify the semantic control before retrying. If the app has no useful accessibility information, request a new screenshot of the same window. Do not reuse positions after the window moves, resizes, changes content, or switches displays.
+
+### Accessibility information is empty or stale
+
+The application may not expose its controls through the OS accessibility service, or that service may be unavailable. Confirm Accessibility or AT-SPI support, then ask omp for a fresh inspection. Fall back to screenshots only when the target is visually unambiguous.
+
+### Wayland asks again for input permission
+
+That is expected. omp does not persist the RemoteDesktop portal grant; it ends when the desktop-control session closes.

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

@@ -0,0 +1,184 @@
+<!--
+source: https://omp.sh/docs/context-files
+fetched: 2026-09-06
+-->
+
+# Context files
+
+> Give omp durable project instructions with AGENTS.md, then layer global, sticky, or system-level guidance only when you need it.
+
+## Give omp the project rules once
+
+Put an `AGENTS.md` in your repository root. omp loads it automatically and applies it throughout the session, so you do not have to repeat build commands, conventions, or safety boundaries in every prompt.
+
+```md
+# Project instructions
+
+## Build and test
+- Install dependencies with `bun install`.
+- Run unit tests with `bun test`.
+- Run the app with `bun run dev`.
+
+## Conventions
+- Keep public API changes backward compatible.
+- Never edit generated files under `src/generated/`.
+- Before finishing, run the narrowest test that covers the change.
+```
+
+Start omp anywhere inside the repository and ask normally:
+
+```text
+Fix the failing invoice test and follow the repository instructions.
+```
+
+Use `AGENTS.md` for facts and constraints that should guide most work in that directory tree. Keep it short and concrete: every loaded instruction consumes context.
+
+## Supported files
+
+All instruction files are plain Markdown. They do not require frontmatter or a configuration entry.
+
+### Native omp files
+
+| File | Recommended project location | User-wide location | Behavior |
+| --- | --- | --- | --- |
+| `AGENTS.md` | `<repo>/AGENTS.md` | `~/.omp/agent/AGENTS.md` | Normal standing instructions. Standalone project files compose across directory levels. |
+| `AGENTS.md` | `<repo>/.omp/AGENTS.md` | `~/.omp/agent/AGENTS.md` | omp-specific alternative. At a given directory level it takes priority over compatible context-file providers. |
+| `RULES.md` | `<repo>/.omp/RULES.md` | `~/.omp/agent/RULES.md` | Sticky, always-apply rules. User and project files can both apply. |
+| `APPEND_SYSTEM.md` | `<launch-directory>/.omp/APPEND_SYSTEM.md` | `~/.omp/agent/APPEND_SYSTEM.md` | Adds text to omp's built-in system instructions. Prefer this to replacing them. |
+| `SYSTEM.md` | `<launch-directory>/.omp/SYSTEM.md` | `~/.omp/agent/SYSTEM.md` | Replaces omp's built-in instruction body. Project scope wins over user scope. Use only for a deliberately different agent persona. |
+
+`~/.omp/agent/` is the default user-wide directory. With a named profile, the equivalent directory is `~/.omp/profiles/<profile>/agent/`. A custom omp configuration root changes the prefix in the same way.
+
+For `SYSTEM.md` and `APPEND_SYSTEM.md`, the most predictable setup is to launch omp from the directory containing `.omp/`. Their direct CLI search checks project files first, in this order:
+
+1. `<launch-directory>/.omp/`
+2. `<launch-directory>/.claude/`
+3. `<launch-directory>/.codex/`
+4. `<launch-directory>/.gemini/`
+
+If none exists, omp checks the corresponding user directories in the same order: the active omp profile's `agent/` directory, the active Claude configuration directory, `~/.codex/`, then `~/.gemini/`. It uses the first matching filename. Enabled discovery providers can supply additional `SYSTEM.md` locations only when that direct search found nothing; `APPEND_SYSTEM.md` uses only the direct search.
+
+`--system-prompt` and `--append-system-prompt` take priority over discovered files; each accepts either literal text or a readable file path.
+
+`SYSTEM.md` removes the built-in behavioral and tool-usage guidance, but omp still supplies project context, rules, and environment information around it. `APPEND_SYSTEM.md` preserves the built-in guidance and is therefore the safer default.
+
+### Compatible context files
+
+omp can reuse instruction files from other agent ecosystems. These are context-file sources, not additional formats: their contents are still Markdown.
+
+| Provider ID | Project source | User-wide source | Project discovery |
+| --- | --- | --- | --- |
+| `native` | nearest `.omp/AGENTS.md` | active omp profile's `AGENTS.md` | Walks upward to the repository root and uses the nearest `.omp` configuration directory. |
+| `claude` | `.claude/CLAUDE.md` | active Claude configuration directory's `CLAUDE.md` | Launch directory only. |
+| `agents` | `.agent/AGENTS.md` or `.agents/AGENTS.md` | `~/.agent/AGENTS.md` or `~/.agents/AGENTS.md` | Walks from the launch directory to the repository root. `.agent` wins over `.agents` at the same level. |
+| `codex` | — | `~/.codex/AGENTS.md` | User-wide only. |
+| `gemini` | `.gemini/GEMINI.md` | `~/.gemini/GEMINI.md` | Launch directory only. |
+| `opencode` | — | `~/.config/opencode/AGENTS.md` | User-wide only. |
+| `github` | `.github/copilot-instructions.md` | `~/.copilot/copilot-instructions.md` | Launch directory only. `COPILOT_HOME` can relocate the user source. |
+| `agents-md` | `AGENTS.md` | — | Walks upward from the launch directory. |
+
+`COPILOT_CUSTOM_INSTRUCTIONS_DIRS` can also name comma-separated directories whose `AGENTS.md` files are considered user-wide GitHub Copilot context.
+
+Cursor rules, Cline rules, `*.instructions.md`, and similar path-specific rule files are discovered as **rules**, not as general context files. They appear separately in `/extensions` and apply according to their own conditions.
+
+## Discovery and scope
+
+omp resolves context from the session's working directory.
+
+For the recommended standalone `AGENTS.md` layout, it walks upward and loads every applicable file. In a repository nested under your home directory, the scan may continue above the Git root to pick up workspace instructions, but stops before treating `~/AGENTS.md` as project context. Outside that case, the repository root is the boundary.
+
+For example, starting omp in `repo/packages/api` can load:
+
+```text
+~/.omp/agent/AGENTS.md       user-wide
+~/work/AGENTS.md             enclosing workspace
+~/work/repo/AGENTS.md        repository
+~/work/repo/packages/api/AGENTS.md
+```
+
+The files are presented from most general to most local, so the nearest project instructions have the final, most specific position. This makes a monorepo layout useful:
+
+- put shared commands and policies at the repository root;
+- put package-specific commands in a nested `AGENTS.md`;
+- avoid copying the root file into every package.
+
+Changes are picked up when omp rebuilds a new session. After editing an instruction file, use `/new` or restart omp before relying on the new text.
+
+### What wins at the same scope
+
+Only one context-file provider survives for each user-wide scope and each project directory depth. Provider priority is:
+
+1. `native`
+2. `claude`
+3. `agents`, then `codex`
+4. `gemini`
+5. `opencode`
+6. `github`
+7. `agents-md`
+
+This means `<repo>/.omp/AGENTS.md` shadows `<repo>/AGENTS.md` at the same repository level; they are not concatenated. Do not create both unless that shadowing is intentional. Standalone `AGENTS.md` files at different ancestor levels have different scopes and therefore compose normally.
+
+User-wide context follows the same provider priority and contributes at most one general context file. `RULES.md` is separate: the user-wide rule and nearest project `.omp/RULES.md` both load when present. For `SYSTEM.md` and `APPEND_SYSTEM.md`, one discovered file is selected, with project scope ahead of user scope and omp's `.omp` location ahead of compatible config directories.
+
+## Import shared instructions
+
+Use an `@path` token to include another file without copying it:
+
+```md
+# Project instructions
+
+@docs/agent/testing.md
+@docs/agent/style.md
+```
+
+Import behavior is predictable:
+
+- a relative path is resolved from the file containing the import, not from omp's working directory;
+- `~/...` resolves from your home directory, and absolute paths are accepted;
+- `@` must begin a line or follow whitespace, so email addresses and `git@github.com` are left alone;
+- imports inside inline code or fenced code blocks are left as examples rather than expanded;
+- nested imports are followed for at most five hops;
+- cycles are stopped, and an unreadable import remains visible as its original `@path` token.
+
+Imported text is inserted at the token's position. Use imports for small shared policies, not for large generated documents.
+
+## Verify what loaded
+
+1. Start omp from the directory where you intend to work.
+2. Enter `/extensions` in the interactive session.
+3. Select the relevant provider tab and inspect **Context Files**. The dashboard shows the source path, whether it is enabled, and whether a higher-priority file shadowed it.
+4. After changing a file, use `/new` or restart omp, reopen `/extensions`, and confirm the expected path is active.
+
+You can also ask:
+
+```text
+Summarize the repository instructions that apply to this task and name their source files.
+```
+
+The `/extensions` dashboard is the authoritative check; the summary is useful for confirming that the instruction itself is clear.
+
+## Troubleshooting
+
+### The file does not appear
+
+- Check the exact capitalization: the supported names are case-sensitive on case-sensitive filesystems.
+- Confirm omp was launched from the intended directory. Providers marked “Launch directory only” do not walk to a parent repository.
+- Make sure the file is readable Markdown, then start a new session.
+- For `.omp/AGENTS.md` and `.omp/RULES.md`, inspect the nearest `.omp` directory first. A nearer project configuration directory defines the native project scope.
+- If a named profile is active, check its profile-specific `agent/` directory instead of the default `~/.omp/agent/`.
+
+### The file appears as shadowed
+
+A higher-priority provider supplied a context file at the same scope. The inspector names both sources. Remove the duplicate, move genuinely narrower instructions into a nested directory, or disable the unwanted provider from `/extensions`.
+
+Provider switches persist through the `disabledProviders` setting. Common IDs are listed in the table above; disabling `agents-md`, for example, stops standalone `AGENTS.md` discovery while leaving `.omp/AGENTS.md` available.
+
+### Sticky rules are missing
+
+`RULES.md` must be in the active user `agent/` directory or in the nearest project `.omp/` directory. The `--no-rules` flag disables `RULES.md` and all other discovered rules for that run.
+
+### An import remains as `@path`
+
+Resolve the path relative to the importing file, check file permissions, and make sure the token is outside inline or fenced code. A cycle or a chain beyond five recursive hops also leaves an import unexpanded.
+
+See [CLI reference](/docs/cli) for prompt and rule flags, [Settings](/docs/settings) for `disabledProviders`, and `/extensions` for discovered conditional rule files.