better-dsh 0.2.4 → 0.2.5

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

@@ -0,0 +1,135 @@
+<!--
+source: https://omp.sh/docs/session-tree
+fetched: 2026-09-06
+-->
+
+# Session tree
+
+> Revisit an earlier turn, try a different direction, and keep the original conversation available.
+
+A conversation becomes a tree as soon as you revisit an earlier point and continue differently. omp keeps the path you already took and adds the new path beside it, so experimenting does not require deleting useful work.
+
+The smallest action is:
+
+```text
+/tree
+```
+
+Use the navigator to choose where you want to continue.
+
+## Read the tree
+
+`/tree` opens a full-session map. Rows are connected by tree lines, and sibling lines are alternative continuations from the same point.
+
+- An accent bullet marks every row on the **currently active path**.
+- The highlighted row is the point you are considering; it is not active until you press <kbd>Enter</kbd>.
+- User and assistant text identifies turns. Tool activity and session events can also appear, depending on the filter.
+- A label appears before its row and works like a durable bookmark.
+- Very deep indentation is compressed with an ellipsis so the message text remains readable.
+
+The default filter favors conversational entries. If a session looks unexpectedly sparse, press <kbd>Alt</kbd>+<kbd>A</kbd> to show everything. Type any part of a message, label, role, or tool snippet to narrow the map.
+
+```text
+• You: Investigate the failing build
+  • Assistant: The failure starts in authentication
+    ├─ • You: Patch the token refresh path
+    │    • Assistant: Tests now pass
+    └─ You: First check whether the cache is stale
+         Assistant: The cache is healthy
+```
+
+Here, the bullets show the active token-refresh path. The cache check is still present as another branch.
+
+## Continue from an earlier turn
+
+To revise a previous request without losing its original result:
+
+1. Run `/tree`.
+2. Highlight the earlier **user message**.
+3. Press <kbd>Enter</kbd>.
+4. omp moves to the point just before that message and restores the message—including its image attachments—as an editable draft.
+5. Change the draft and submit it.
+
+Submitting creates a new continuation beside the old one. The original message, its answer, and everything after it remain reachable in `/tree`.
+
+Selecting an assistant response instead lands immediately after that response and leaves the editor empty. Your next prompt continues from there. Selecting the current endpoint simply closes the navigator with an “Already at this point” status.
+
+Past interactive questions are recoverable too: selecting an earlier `ask` answer reopens the question UI, and a new answer becomes a sibling of the old answer.
+
+### Keep useful context from the path you leave
+
+When `branchSummary.enabled` is enabled, <kbd>Enter</kbd> offers three choices:
+
+- **No summary** — continue with only the context on the selected path.
+- **Summarize** — carry a generated recap of the path you are leaving into the new path.
+- **Summarize with custom prompt** — tell omp what the recap should preserve.
+
+Press <kbd>Shift</kbd>+<kbd>Enter</kbd> to summarize and switch without opening that choice. The recap belongs to the new path; it does not replace or delete the abandoned path. Press <kbd>Esc</kbd> while summarization is running to cancel and return to the tree.
+
+## `/tree`, `/branch`, or `/fork`?
+
+These controls preserve different amounts of history:
+
+| Control | Result | Best for |
+| --- | --- | --- |
+| `/tree` | Moves within the current session file. Your next submission adds an in-file alternative while every existing path remains in the same tree. | Exploring alternatives while keeping one navigable record. |
+| `/branch` | Follows **Double-Escape Action**. With the default **Tree** setting it opens the same in-file navigator as `/tree`. Set that action to **Branch** to choose an earlier user message and create a separate session containing only the path before it; the chosen message returns as a draft. | Choosing whether the branch command means in-file navigation or a clean session from an earlier decision point. |
+| `/fork` | Immediately clones the current session—including its current tree and artifacts—into a new session, then switches to the clone. It does not ask for an earlier turn. | Taking a full checkpoint before broad or risky experimentation. |
+
+A practical rule: use `/tree` when you want to compare paths in one map. To make `/branch` create a separate prefix session, open `/settings`, go to **Interaction → Input**, and set **Double-Escape Action** to **Branch**. Use `/fork` when you want a complete independent copy of everything as it stands now.
+
+That setting also controls what pressing <kbd>Esc</kbd> twice in an empty editor does: open the tree, open the branch picker, or do nothing.
+
+`/fork` requires a persisted session and cannot run while a response is streaming. It is unavailable for sessions started with `--no-session`.
+
+## Navigation controls
+
+| Key | Action |
+| --- | --- |
+| <kbd>↑</kbd> / <kbd>↓</kbd> | Move one visible row; wraps at the ends |
+| <kbd>Alt</kbd>+<kbd>↑</kbd> / <kbd>Alt</kbd>+<kbd>↓</kbd> | Jump to the previous or next user/assistant turn |
+| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> or <kbd>←</kbd> / <kbd>→</kbd> | Move one page |
+| <kbd>Home</kbd> / <kbd>End</kbd> | Jump to the first or last visible row |
+| Type | Search the visible tree; <kbd>Backspace</kbd> removes search characters |
+| <kbd>Enter</kbd> | Switch to the highlighted point |
+| <kbd>Shift</kbd>+<kbd>Enter</kbd> | Summarize the path being left, then switch |
+| <kbd>Shift</kbd>+<kbd>L</kbd> | Add, edit, or clear a label when search is empty |
+| <kbd>Ctrl</kbd>+<kbd>O</kbd> | Cycle filters forward |
+| <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>O</kbd> | Cycle filters backward |
+| <kbd>Alt</kbd>+<kbd>D</kbd>/<kbd>T</kbd>/<kbd>U</kbd>/<kbd>L</kbd>/<kbd>A</kbd> | Show default, no-tools, user-only, labeled-only, or all entries |
+| <kbd>Esc</kbd> or <kbd>Ctrl</kbd>+<kbd>C</kbd> | Clear an active search first; otherwise close the navigator |
+
+Use labels before a long experiment if you expect to return to a particular checkpoint. Later, <kbd>Alt</kbd>+<kbd>L</kbd> shows only labeled entries.
+
+## Persistence and compaction
+
+Completed turns and all branches are stored in the session journal. Normal tree navigation does not rewrite or erase earlier paths.
+
+The selected point becomes the active endpoint immediately. Your next submission, a branch summary, or the normal session-exit record stores an entry on that path, so resume follows it. If omp is killed before anything can be written after a navigation-only move, resume may return to the last endpoint already represented by the journal; reopen `/tree` and select the intended path again.
+
+[Compaction](/docs/compaction) changes what context is sent to the model on a path; it does not flatten the tree or delete the turns that produced the summary. A path through a compaction point uses that compacted context. Navigating to a point before it lets you continue from the earlier context, and other branches remain visible.
+
+Branch summaries and compaction summaries solve different problems:
+
+- A **branch summary** carries useful information across a deliberate switch to another path.
+- A **compaction summary** shortens an active path so the conversation can continue within the model's context window.
+
+## Recover from the wrong choice
+
+If you moved to the wrong point, do not recreate the conversation:
+
+1. Run `/tree` again.
+2. Search for distinctive text or press <kbd>Alt</kbd>+<kbd>L</kbd> to find a bookmark.
+3. Follow the tree lines to the endpoint of the original path.
+4. Select that endpoint with <kbd>Enter</kbd>.
+
+The original path becomes active again. If you already submitted on the wrong path, that new work also remains as a sibling; returning does not delete either side.
+
+For a stronger boundary before experimentation, use `/fork` first. You can then resume the original session independently through `/resume` if the experiment goes badly.
+
+## Related
+
+- [Sessions](/docs/sessions) — find, resume, branch, fork, and share sessions.
+- [Compaction](/docs/compaction) — how long active paths are summarized.
+- [Session format](/docs/session-format) — the public on-disk format for integrations.
+- [Handoff](/docs/handoff) — pass a structured session recap to a teammate.

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

@@ -0,0 +1,223 @@
+<!--
+source: https://omp.sh/docs/sessions
+fetched: 2026-09-06
+-->
+
+# Sessions
+
+> Your work is saved automatically. Resume it by project, split off an experiment, or share a copy without losing the original conversation.
+
+## Your work saves automatically
+
+Start omp normally and work:
+
+```sh
+cd ~/work/api
+omp
+```
+
+There is no Save command. omp records completed messages and tool activity in a session associated with the working directory. Quit and come back later with:
+
+```sh
+cd ~/work/api
+omp -c
+```
+
+`-c` continues this terminal's last session in the current directory. If that terminal breadcrumb is unavailable, omp uses the most recently modified session for the directory; if none exists, it starts a new one.
+
+Saving happens as entries complete. Text that is still streaming is not committed until the response finishes, so a hard crash can lose the partial response at the end while preserving the completed work before it. See [Crash recovery](#crash-recovery) for the safe way to continue.
+
+If you never want a local session record, launch with `omp --no-session`. That run cannot be resumed, deleted, or forked as a saved session. An explicit export or share still creates or uploads a separate copy.
+
+## Start, continue, or choose a session
+
+Use the action that matches what you know:
+
+| What you want | Action |
+| --- | --- |
+| Start unrelated work | `omp`, or `/new` inside omp |
+| Continue this terminal's latest work in the current directory | `omp -c` |
+| Choose from saved work | `omp -r`, or `/resume` inside omp |
+| Resume a known session | `omp -r <id-or-path>`, or `/resume <id>` |
+| Always continue the latest session on startup | Enable **Auto Resume** in `/settings`, or run `omp config set autoResume true` |
+
+`/new` starts a new saved session and leaves the current one available in the picker. It is different from `/clear`, which only resets the model's current conversation context while keeping the same session.
+
+### Use the session picker
+
+Run `omp -r` before startup, or enter `/resume` while omp is open. The picker begins with sessions for the current folder.
+
+- Type to search by title, session ID, project path, or conversation text. Search also finds prompts from deep in long sessions.
+- Press <kbd>↑</kbd>/<kbd>↓</kbd> and <kbd>Enter</kbd> to select.
+- Press <kbd>Tab</kbd> to switch between **current folder** and **all projects**. The all-projects view shows each session's working directory.
+- Pinned sessions appear first. Status text such as **interrupted**, **aborted**, or **error** helps identify an unfinished run.
+- Press <kbd>Delete</kbd>, or <kbd>Backspace</kbd> with an empty search box, to delete the highlighted session after confirmation.
+
+When you resume a session from another existing project, omp switches to the working directory recorded by that session. If the recorded directory no longer exists, an interactive launch offers to move the session into your current directory instead.
+
+Use `/session info` to see the current session's ID and file path. A short unique ID prefix is usually enough for `-r`, `/resume`, `/pin`, and `--fork`.
+
+## Make saved work easy to find
+
+### Name and pin
+
+Give important work a stable title instead of relying on its first-message preview:
+
+```text
+/rename Streaming importer investigation
+/pin
+```
+
+`/pin` toggles the current session at the top of resume lists. `/pin <session-id>` toggles another saved session without opening it. Pins follow a session if you move it to another project directory.
+
+### Move a session to another project
+
+If the conversation now belongs with a different checkout or worktree, move it rather than relying on the all-projects picker:
+
+```text
+/move ../api-v2
+```
+
+The target must be a directory. omp moves the saved session and its artifacts, updates its working directory, and makes it discoverable from the target project's resume list.
+
+### Delete
+
+Choose the command by what should happen next:
+
+| Action | Result |
+| --- | --- |
+| Delete in the resume picker | Deletes the highlighted session and its artifacts |
+| `/session delete` | Deletes the current session and returns to the picker |
+| `/drop` | Deletes the current session and immediately starts a new one |
+| `/new` | Keeps the current session and starts a new one |
+
+Deletion is destructive. Export or copy the JSONL file shown by `/session info` first if you might need it later.
+
+## Branch or fork?
+
+Both preserve the conversation you already have, but they organize the alternative differently.
+
+|  | Branch | Fork |
+| --- | --- | --- |
+| Command | `/branch` | `/fork` |
+| Saved as | Another path in the same session | A new saved session with a new ID |
+| What you choose | An earlier user message to revise and resend | The current state; no message picker |
+| Best for | Exploring alternatives that belong in one canonical history | A risky, disposable, or separately shareable line of work |
+| Return to the original | `/tree` within the session | `/resume` and select the parent session |
+
+`/branch` opens a user-message selector. Pick the prompt where the new direction should begin; omp rewinds to just before it and puts that prompt back in the editor so you can revise it. The abandoned continuation remains in the same session and can be revisited with `/tree`.
+
+`/fork` copies the current saved session and its artifacts into a new session, then continues in the copy. The parent remains unchanged and appears separately in the resume picker. To fork from an older point, first navigate or branch to that point, then run `/fork`.
+
+From the shell, fork a known saved session directly into the current project:
+
+```sh
+omp --fork <session-id>
+omp --fork ./received-session.jsonl
+```
+
+Use `/tree` to switch among paths kept inside one session. [Session tree](/docs/session-tree) explains navigation, labels, active paths, and exactly what branch and fork retain.
+
+## Export, share, and import
+
+### Export a local review copy
+
+`/export` writes a self-contained HTML view and opens it in your browser:
+
+```text
+/export
+/export ./review/importer-session.html
+```
+
+Export an existing JSONL file without opening an interactive session:
+
+```sh
+omp --export ./session.jsonl ./session.html
+```
+
+HTML is for reading, not for resuming. It can include conversation text, tool output, paths, and model context, so treat it as sensitive.
+
+### Share an encrypted link
+
+Run `/share` in the session, or share an existing saved session from the shell:
+
+```sh
+omp share <session-id-or-path>
+```
+
+The default flow encrypts the session snapshot in your client and uploads the encrypted blob. The decryption key is in the URL fragment and is not sent to the storage server. Secret redaction is enabled by default for configured secrets, but it is not a substitute for reviewing what you send: anyone with the complete link can read the snapshot. Large shares may be trimmed to fit the service limit, and a configured custom share handler may use a different destination and privacy model.
+
+Use `/handoff [focus]` before sharing when another person needs a concise statement of current state and next steps.
+
+### Continue an editable copy
+
+A share link or HTML export cannot be imported back into a live session. For an editable handoff, send the JSONL path reported by `/session info`; the receiver should fork it into their current project:
+
+```sh
+cd ~/work/api
+omp --fork ./received-session.jsonl
+```
+
+This creates a new local session and leaves the received file unchanged. `omp -r ./received-session.jsonl` instead opens that exact file and adopts its recorded working directory when it still exists.
+
+omp can also import local Claude Code or Codex history into a fresh omp session:
+
+```sh
+omp --from-claude
+omp --from-codex
+```
+
+Each command opens a source-specific picker. From an existing omp session, `/resume @claude` and `/resume @codex` open the same import choices.
+
+For tools that need the public JSONL structure rather than the product workflow, see [Session format](/docs/session-format).
+
+## Profiles, locations, and privacy
+
+Sessions are scoped in two layers:
+
+1. **Profile.**`omp --profile work` uses isolated settings, authentication, caches, and sessions. A resume picker only sees the active profile.
+2. **Working directory.** Inside a profile, omp groups sessions by project. The picker starts in the current-folder group; <kbd>Tab</kbd> reveals the profile's other projects.
+
+The usual default-profile location is `~/.omp/agent/sessions/`. A named profile normally uses `~/.omp/profiles/<name>/agent/sessions/`. XDG configuration and directory overrides can change those paths, so `/session info` is the authoritative location for the active session.
+
+Use `--session-dir <path>` when one launch must save and look up sessions in a specific directory. Reuse the same flag when resuming from that custom location. Prefer profiles when you want durable separation between clients, identities, or work contexts; prefer `/move` when only one conversation belongs to a different project.
+
+Saved JSONL files and artifacts are local, but they may contain prompts, source excerpts, tool results, file paths, and secrets printed by commands. Protect the session directory like source code and credentials. `--no-session` prevents the session record, but does not undo files changed by tools or copies you explicitly export or share.
+
+## Crash recovery
+
+After a terminal disconnect, process crash, or forced restart:
+
+1. Return to the same project and run `omp -c`.
+2. If that is not the right conversation, run `omp -r`, type a distinctive phrase, and check sessions marked **interrupted**.
+3. Read the last completed messages and any pending-tool warning before sending another prompt.
+4. Verify external side effects before asking omp to repeat a command. The transcript can show that a tool result was never recorded even when the command changed something outside omp.
+
+omp preserves completed entries before the crash and ignores an incomplete trailing record. It does not invent the missing result of an interrupted tool call or the unsaved tail of a streaming response.
+
+## Troubleshooting
+
+### The picker says there are no sessions
+
+- Press <kbd>Tab</kbd>; you may be viewing only the current folder.
+- Check that you launched with the same `--profile` as before.
+- If the session used `--session-dir`, pass that directory again.
+- Use `/session info` before leaving a session to capture its exact path.
+
+### `-c` opened the wrong work
+
+`-c` favors the last session associated with the current terminal, then the latest session for the directory. Use `omp -r` to choose explicitly, or `/rename` and `/pin` the session you return to often.
+
+### A known ID is not found
+
+Open `omp -r`, press <kbd>Tab</kbd>, and search the all-projects view. Use a longer ID prefix if several sessions begin alike. Profiles and custom session directories are separate search scopes; switch to the original profile or pass the original `--session-dir`.
+
+### Fork or delete is unavailable
+
+Forking requires persistence, so relaunch without `--no-session`. Deleting requires an actual saved file; a brand-new empty session may have nothing to delete yet. Wait for a streaming response to finish or abort it before moving, deleting, or forking.
+
+### The project directory was renamed or removed
+
+Resume by ID from an interactive terminal. omp offers to re-root a session whose recorded directory no longer exists into the current directory. For an existing but different project, resume it normally and use `/move <path>` when you intentionally want to reassign it.
+
+Command-line flags are listed in [CLI reference](/docs/cli), and all interactive commands are listed in [Slash commands](/docs/slash).

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

@@ -0,0 +1,290 @@
+<!--
+source: https://omp.sh/docs/settings
+fetched: 2026-09-06
+-->
+
+# Settings
+
+> Inspect, change, scope, and troubleshoot omp configuration without guessing which value wins.
+
+omp works without a config file: known settings fall back to built-in defaults (some optional values default to unset). Start a session and run `/settings` when you want to see the **effective** values for your current directory, search by name, and change the settings that have an interactive control. The panel marks values that differ from their built-in defaults.
+
+The panel saves changes to your active global or named-profile config and applies most UI and session behavior immediately. Use **Enter** or **Space** to change a value, type to search across tabs, and **Esc** to close. For a precise reset, a project-only change, or a setting not shown in the panel, use `omp config` or YAML as described below.
+
+A few useful defaults on a fresh install are:
+
+- dark theme `titanium` and light theme `light`
+- thinking level `high`
+- steering and follow-ups delivered `one-at-a-time`
+- immediate interruption when you steer a running turn
+- compaction and automatic image resizing enabled
+- named model-role changes saved globally (`modelRoleStorage: global`)
+- tool approval mode `yolo` unless a launch mode or runtime flag overrides it; review [Approvals](/docs/approvals) before changing policy
+
+Defaults can evolve. `omp config list` is the authoritative view of the keys and effective values in the version you are running.
+
+## Inspect, change, and reset from the shell
+
+Run these in the directory whose project settings you want included:
+
+```sh
+omp config list                              # every effective setting, type, and allowed enum values
+omp config list --json                       # machine-readable inventory
+omp config get theme.dark                    # one effective value
+omp config set theme.dark catppuccin-macchiato
+omp config set compaction.enabled false
+omp config reset theme.dark                  # write the built-in default to global config
+omp config path                              # print the active agent directory
+```
+
+`set` and `reset` write the global config for the active profile, not the project file. `reset` writes the schema default; it does **not** delete the key. If you want the key to inherit from another layer, remove it from the YAML file instead.
+
+Values are parsed by setting type:
+
+| Type | Shell input |
+| --- | --- |
+| Boolean | `true` / `false`, `yes` / `no`, `on` / `off`, or `1` / `0` |
+| Number | A finite number |
+| Enum | One exact value listed by `omp config list` |
+| Array | JSON, for example `omp config set disabledProviders '["ollama"]'` |
+| Record | JSON, for example `omp config set providers.maxInFlightRequests '{"anthropic":2}'` |
+| String | The remaining argument text, trimmed |
+
+Keys must be complete dotted paths: use `theme.dark`, not `theme`. Unknown keys and invalid CLI values fail without being saved. Human `config list` output masks configured credentials; `--json` omits their values and marks them redacted. `config get` is an explicit request for one value and therefore does **not** mask a credential.
+
+## Files and scopes
+
+| Scope | Location | Use it for | How to write it |
+| --- | --- | --- | --- |
+| Global | `~/.omp/agent/config.yml` | Your normal defaults across projects | `/settings`, `omp config set`, `omp config reset`, or an editor |
+| Named profile | `~/.omp/profiles/<name>/agent/config.yml` | Isolated settings, auth, sessions, and caches for a work/persona profile | Run under `omp --profile <name>` or set `OMP_PROFILE`, then use the same commands |
+| Project | `<cwd>/.omp/config.yml` | Repository-specific overrides that can be shared with the project | Edit the YAML file; settings discovery checks the current directory, not ancestors |
+| Config overlay | Any YAML file passed with `--config` or named in `PI_CONFIG_FILES` | Temporary, CI, secret, or experiment-specific overrides | Read-only layer for that process; never copied into persistent config |
+| Runtime | CLI flags and feature-specific environment overrides | One launch only | Never persisted |
+
+`omp config path` prints the active **agent directory**, so append `config.yml` when opening the file. An existing `config.yaml` is also accepted and updated in place. `PI_CODING_AGENT_DIR` relocates the default profile's agent directory; `PI_CONFIG_DIR` changes the normal `.omp` root name.
+
+A named profile replaces the ordinary global scope rather than inheriting its settings. To inspect one without entering a session, put the profile flag before the subcommand:
+
+```sh
+omp --profile work config path
+omp --profile work config list
+omp --profile work config set theme.dark titanium
+```
+
+`OMP_PROFILE` is the persistent environment equivalent; `PI_PROFILE` remains a legacy fallback. Keybindings are stored separately and have their own profile inheritance rules; see [Keybindings](/docs/keybindings#remap-shortcuts).
+
+### Project settings
+
+Create `.omp/config.yml` in the exact directory where you launch omp:
+
+Enabled compatibility providers can also contribute project-level settings from their own formats. They share the project layer; use `omp config get <key>` to inspect the merged result and [Context files](/docs/context-files) to control discovery sources.
+
+```yaml
+# <repo>/.omp/config.yml
+modelRoles:
+  default: anthropic/claude-sonnet-4-5
+
+disabledProviders:
+  - ollama
+
+compaction:
+  enabled: true
+  thresholdPercent: 80
+```
+
+`omp config set` does not write arbitrary project settings. Edit this file directly. The one interactive project write is a model-selector role assignment when `modelRoleStorage` is `project`; only `modelRoles` is updated there, and missing project roles continue to fall back to the global profile.
+
+Keep credentials out of committed project YAML. Prefer stored login credentials, environment variables, [secret references](/docs/secrets), or an untracked overlay.
+
+### One-shot overlays
+
+```sh
+omp --config ./local/ci.yml "diagnose this failure"
+omp --config ./base.yml --config ./experiment.yml "try this configuration"
+```
+
+Overlay paths are resolved from the working directory and `~` is expanded. Repeating `--config` is allowed; later files win. `PI_CONFIG_FILES` accepts a platform path list (`:` on Unix, `;` on Windows) and loads those files first, before explicit `--config` files.
+
+Overlays are strict: a missing file, malformed YAML, or document whose top level is not a mapping stops startup. They are not quarantined or silently ignored.
+
+## Precedence and merging
+
+From lowest to highest priority:
+
+```text
+built-in defaults
+  < active global/profile config
+  < project config
+  < PI_CONFIG_FILES overlays, in listed order
+  < --config overlays, in command-line order
+  < runtime flags and feature-specific environment overrides
+```
+
+Examples of runtime overrides include model-role flags such as `--model`, `--smol`, `--slow`, and `--plan`, approval flags, `--hide-thinking`, `--advisor`, `--no-pty`, and `--api-key`. Environment variables are not one universal settings layer: each owning feature decides whether its variable is an override or fallback. See the [environment variable reference](/docs/env).
+
+Mappings deep-merge; scalars and arrays replace:
+
+```yaml
+# global
+statusLine:
+  preset: default
+  transparent: false
+disabledProviders: [anthropic, openai]
+
+# project
+statusLine:
+  transparent: true
+disabledProviders: [groq]
+```
+
+Inside the project, `statusLine.preset` remains `default`, `transparent` becomes `true`, and `disabledProviders` is exactly `[groq]`. Higher arrays never append to lower arrays. This replacement rule also applies to `enabledModels`, `cycleOrder`, `extensions`, and every other array setting.
+
+## Validation, saving, and reloads
+
+- `/settings` constrains choices to the controls and values supported by the current build. Its changes update the running session and are saved in the background.
+- `omp config set` checks that the key exists and parses booleans, numbers, enums, arrays, and records before writing atomically.
+- A hand-edited YAML file must contain a mapping at its root. YAML parsing does not promise to catch every semantically wrong value, so use `/settings` or `omp config set` when possible and inspect the result with `omp config get <key>`.
+- On writable startup, invalid persistent global or native project YAML is moved beside the original as `*.broken-<timestamp>-<pid>-<id>`, then startup fails and reports both paths. Fix or restore the moved file; omp does not discard it.
+- Running sessions do not generally watch config files. `/settings` changes are live, but changes made by another `omp config` process or text editor reliably take effect on the next launch. Moving the session to another working directory reloads that directory's project layer; restart when model/provider discovery was already initialized.
+- Concurrent saves re-read the file under a lock and preserve unrelated external edits.
+
+There is no general `/reload-settings` command. `/reload-plugins` refreshes extension and discovery state, not arbitrary settings.
+
+## Common recipes
+
+### Set model roles
+
+Use `/settings` or the model selector for guided selection, and [Model roles](/docs/roles) for role behavior. YAML is useful when several roles change together:
+
+```yaml
+modelRoles:
+  default: anthropic/claude-sonnet-4-5
+  smol: anthropic/claude-haiku-4-5
+  slow: anthropic/claude-opus-4-6:high
+  plan: openai/gpt-5.3-codex:high
+  commit: anthropic/claude-haiku-4-5
+```
+
+Run `omp --list-models` to inspect the models available with your current providers and credentials.
+
+### Change queue behavior
+
+```yaml
+steeringMode: one-at-a-time  # or all
+followUpMode: one-at-a-time  # or all
+interruptMode: immediate     # or wait
+```
+
+See [Using omp](/docs/using) for how steering differs from follow-up prompts.
+
+### Set a theme and terminal behavior
+
+```yaml
+theme:
+  dark: catppuccin-macchiato
+  light: light
+terminal:
+  showImages: true
+tui:
+  hyperlinks: auto
+```
+
+See [Themes](/docs/themes) for built-in and custom palettes.
+
+### Limit a repository's providers
+
+```yaml
+# <repo>/.omp/config.yml
+disabledProviders:
+  - ollama
+  - openrouter
+```
+
+This project array replaces the global array. Provider ids and authentication live in [Providers](/docs/providers).
+
+### Configure safety-sensitive features
+
+Start from the interactive controls, then follow the dedicated guides rather than copying a broad policy blindly:
+
+- tool permission policy: [Approvals](/docs/approvals)
+- advisor review: [Advisor](/docs/advisor)
+- desktop automation: [Computer](/docs/computer)
+- security review: [Security](/docs/security)
+- prompt-triggered modes: [Magic keywords](/docs/magic-keywords)
+- pre-execution repository walks: [Prewalk](/docs/prewalk)
+
+### Configure compaction and memory
+
+```yaml
+compaction:
+  enabled: true
+  thresholdPercent: 80
+memory:
+  backend: off
+```
+
+Compaction has several strategies, thresholds, and background modes; see [Compaction](/docs/compaction). Memory backends and retention are covered in [Memory](/docs/memory).
+
+## Complete setting groups
+
+`/settings` is organized into the following current tabs and sections. This is the best place to browse without knowing a key name.
+
+| Tab | Sections |
+| --- | --- |
+| Appearance | Theme; Composer; Status Line; Display; Images |
+| Model | Thinking; Sampling; Prompt; Retry & Fallback; Advisor; Prewalk; Vision |
+| Interaction | Input; Approvals; Notifications; Speech; Collab; Magic Keywords; Startup & Updates; Power (macOS); Agent; Git |
+| Context | General; Compaction; Rules (TTSR); Experimental |
+| Memory | General; Auto-Learn; Mnemopi; Hindsight |
+| Files | Editing; Reading; Read Summaries; LSP |
+| Shell | Bash; Eval & Runtimes |
+| Tools | Available Tools; Todos; Grep & Browser; Computer; GitHub; Output Limits; Execution; Discovery & MCP; Extensions; Developer |
+| Tasks | Modes; Subagents; Isolation; Commands & Skills |
+| Providers | Services; Fireworks; Tiny Model; Protocol; Timeouts; Privacy |
+
+For exact key discovery, the family index below maps current namespaces to where users normally encounter them. Some families span more than one tab. Standalone keys are listed alongside namespaces. Use `omp config list` for every leaf key, effective value, type, and enum choices; add `--json` when you need descriptions in machine-readable output.
+
+- **Appearance:**`theme`, `symbolPreset`, `colorBlindMode`, `composer`, `statusLine`, `terminal`, `images`, `tui`, `display`, `showHardwareCursor`.
+- **Model:**`modelRoles`, `modelTags`, `modelProviderOrder`, `cycleOrder`, `modelRoleStorage`, `enabledModels`, `defaultThinkingLevel`, `hideThinkingBlock`, `proseOnlyThinking`, `omitThinking`, `externalThinking`, `model`, `inlineToolDescriptors`, `includeModelInPrompt`, `includeWorkspaceTree`, `personality`, sampling keys (`temperature`, `topP`, `topK`, `minP`, `presencePenalty`, `repetitionPenalty`, `textVerbosity`), `tier`, `retry`, `advisor`, `prewalk`, and model request `images` / `providers` options.
+- **Interaction:**`autoResume`, `power`, `git`, `steeringMode`, `followUpMode`, `interruptMode`, `loop`, `doubleEscapeAction`, `treeFilterMode`, `autocompleteMaxVisible`, `spelling`, `emojiAutocomplete`, `paste`, `startup`, `update`, `marketplace`, `magicKeywords`, `completion`, `error`, `ask`, `recap`, `collab`, `share`, `stt`, and interaction-related `tools` / `features`.
+- **Context:**`workspace`, `contextPromotion`, `extendedContext`, `compaction`, `snapcompact`, `branchSummary`, `ttsr`, plus context-related `tools` options.
+- **Memory:**`memory`, `autolearn`, `memories`, `mnemopi`, `hindsight`, and memory-model settings under `providers`.
+- **Files:**`edit`, `readLineNumbers`, `read`, and `lsp`.
+- **Shell:**`shellPath`, `bash`, `bashInterceptor`, `shellMinimizer`, `eval`, `python`, `ruby`, and `julia`.
+- **Tools:**`tools`, `todo`, `glob`, `grep`, `astGrep`, `astEdit`, `debug`, `launch`, `speechgen`, `generate_image`, `inspect_image`, `computer`, `checkpoint`, `fetch`, `vault`, `github`, `web_search`, `security`, `browser`, `async`, `irc`, `mcp`, `tasks`, `extensionHandlers`, and developer options under `dev`.
+- **Tasks:**`plan`, `goal`, `title`, `task`, `worktree`, `skills`, and `commands`.
+- **Providers and services:**`providers`, `provider`, `disabledProviders`, `secrets`, `live`, `tts`, `speech`, `codexResets`, `exa`, `searxng`, and auth-broker settings under `auth`.
+- **Advanced CLI/YAML-only families:**`extensions`, `disabledExtensions`, `commit`, `gc`, `thinkingBudgets`, plus advanced leaves under `statusLine`, `images`, `tui`, `retry`, `compaction`, `memories`, `autolearn`, `mnemopi`, `hindsight`, `bashInterceptor`, `shellMinimizer`, `eval`, `task`, and `skills`.
+
+Keybinding remaps do not live in this file: use `keybindings.yaml` as described in [Keybindings](/docs/keybindings#remap-shortcuts).
+
+## Troubleshooting
+
+### A project value is not taking effect
+
+1. Run `omp config get <key>` from the directory containing `.omp/config.yml`.
+2. Confirm the project file is in the process's exact working directory; omp does not search parent directories for native project settings.
+3. Check that a later `--config` overlay, `PI_CONFIG_FILES`, CLI flag, or feature environment variable is not winning.
+4. Remember that an array in the project replaces the whole global array.
+5. Restart if provider/model/tool discovery was already initialized.
+
+### `omp config set` changed the wrong file
+
+It always writes the active global/profile config. Run `omp config path` to identify that agent directory. Edit `<repo>/.omp/config.yml` directly for a project override.
+
+### `omp config reset` appears to do nothing
+
+`reset` writes the built-in default into the global file. A project, overlay, or runtime value can still win. Inspect with `omp config get <key>`, then remove or change the higher layer. To inherit instead of pinning the global default, delete the global YAML key manually.
+
+### Startup reports broken YAML
+
+Read the reported error and backup path. Persistent malformed YAML is moved to a unique `.broken-*` sibling before startup stops, preserving the original contents. Repair that backup into a mapping and restore it as `config.yml`. Overlay errors are not moved; fix the overlay in place.
+
+### A key is unknown or a value is rejected
+
+Run `omp config list`, copy the exact dotted key, and use one of the displayed enum values. Arrays and records passed to `set` must be valid JSON even though persistent files use YAML.
+
+### An edit is not visible in an existing session
+
+A separate shell command or editor does not push settings into an already-running session. Start a new session. If you used `/settings`, check whether a project, overlay, or runtime override has higher precedence than the global value you changed.