better-dsh 0.2.4 → 0.2.5

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

@@ -0,0 +1,225 @@
+<!--
+source: https://omp.sh/docs/code-intelligence
+fetched: 2026-09-06
+-->
+
+# Code intelligence
+
+> Give omp symbol-aware navigation, renames, fixes, and diagnostics through the language servers already used by your project.
+
+## Make code changes with semantic context
+
+Code intelligence lets omp ask a language server what a symbol means, where it is defined, which code refers to it, and which fixes are valid. That is safer than treating source code as plain text: a semantic rename can distinguish two same-named variables and update imports and re-exports across files.
+
+Usually, you only need to install the language server for your language, start `omp` from the project root, and ask for the outcome you want:
+
+```text
+Rename `issueToken` to `mintToken` across the project. Preview the language-server changes before applying them.
+```
+
+omp can also find definitions and implementations, inspect inferred types, list references, report diagnostics, apply server-provided fixes, and rename files while updating imports. For syntax-based changes that do not center on a symbol, use [structural edits](/docs/editing) instead.
+
+## What works automatically
+
+LSP support is enabled by default. omp checks its built-in server definitions and selects a server only when both of these are true:
+
+1. A matching project marker, such as `package.json`, `Cargo.toml`, or `go.mod`, exists directly in the directory where you launched omp.
+2. The server executable is available in a supported project-local bin directory or on `PATH`.
+
+Project-local executables take precedence. This includes locations such as `node_modules/.bin`, Python virtual-environment bin directories, Ruby binstubs, and a project `bin` directory for Go projects.
+
+Discovery does not walk to parent directories, and wildcard markers only inspect the launch directory. Start omp at the repository or package root that contains the marker.
+
+By default, detected servers are **lazy**: the welcome panel lists them as available, but omp waits until code intelligence or an edit to a matching file needs one before starting it. Servers are shared between omp sessions for the same project when the daemon broker is available; omp falls back to a private server if sharing is unavailable.
+
+In interactive mode, run `/session` to see the detected server names, file types, and startup state:
+
+| State | Meaning |
+| --- | --- |
+| `available` | Detected and ready to start on first use. |
+| `connecting` | Starting eagerly. |
+| `ready` | Eager startup completed. |
+| `error` | Startup failed; the line includes the failure when one is available. |
+
+## Ask in natural language
+
+Describe the result you want and point omp to a symbol or file when that removes ambiguity. You never need to supply protocol positions or LSP request details.
+
+| Goal | Example request |
+| --- | --- |
+| Understand a symbol | `Explain the inferred type of result in src/parser.ts and show me its definition.` |
+| Find impact | `Find every reference to PaymentGateway.authorize, including implementations, before changing it.` |
+| Rename safely | `Rename issueToken to mintToken across the project using code intelligence. Preview first.` |
+| Move a module | `Move src/auth/token.ts to src/security/token.ts and update imports through the language server.` |
+| Diagnose a file | `Ask the language server why src/server.ts is failing and explain the diagnostics.` |
+| Apply a fix | `Use the server's quick fix for the missing import in src/routes.ts, then check diagnostics again.` |
+| Inspect a contract | `Find every implementation of StorageAdapter and summarize how they differ.` |
+
+When a name appears more than once on a line, describe the occurrence in words, for example: “the second `parse` call on line 88.” omp resolves the exact source position.
+
+## What you see
+
+Navigation requests return source locations, signatures, types, or documentation that omp can explain in its response. Reference searches give it a project-wide impact list. Diagnostics include the server's severity, message, and location.
+
+For a rename, ask for a preview when you want to inspect the proposed files before anything changes. When applied, omp shows the normal changed-file and diff output. A semantic rename may update many files as one server-computed workspace change; if the server returns no valid rename, omp does not invent semantic edits.
+
+Language servers cannot reliably find dynamic string lookups, prose comments, generated code outside the workspace, or consumers in another package that is not part of the server workspace. After a broad change, ask omp to run the project's compiler and targeted tests as well as checking diagnostics.
+
+## Configure or override a server
+
+No configuration file is needed for a built-in server when its marker and executable are discoverable. First install the server in the project or on `PATH`, then restart omp from the project root.
+
+Use `<project>/.omp/lsp.json` for a project-specific override. For example, built-in definitions are merged by server name, so this changes only the `gopls` settings:
+
+```json
+{
+  "servers": {
+    "gopls": {
+      "settings": {
+        "gopls": {
+          "gofumpt": false,
+          "staticcheck": false
+        }
+      }
+    }
+  }
+}
+```
+
+Object-valued fields such as `settings`, `initOptions`, `capabilities`, and `workspaceReadyTimings` replace that whole field; they are not deep-merged. Include every value you want to retain inside the overridden object.
+
+To add a server that omp does not define, provide its command, handled extensions, and project markers:
+
+```yaml
+# <project>/.omp/lsp.yaml
+servers:
+  my-language-server:
+    command: my-language-server
+    args: ["--stdio"]
+    fileTypes: [".xyz"]
+    languageId: xyz
+    rootMarkers: [".xyz-project"]
+```
+
+The command may be a binary name resolved from project-local bins or `PATH`, or an absolute path. A new server missing `command`, `fileTypes`, or `rootMarkers` is ignored with a warning.
+
+To disable one built-in server for a project while leaving the others available:
+
+```json
+{
+  "servers": {
+    "eslint": {
+      "disabled": true
+    }
+  }
+}
+```
+
+After editing LSP configuration, start a new omp session for the clearest verification. Check the welcome panel or `/session`, then ask:
+
+```text
+Confirm which language server handles src/main.ts and check that file for diagnostics.
+```
+
+If you install a missing executable during an existing session, ask omp to reload all language servers and reread their configuration.
+
+## Choose where configuration lives
+
+omp reads JSON, YAML, and YML files named `lsp` or `.lsp`. Sources merge from lower to higher precedence:
+
+| Precedence | Locations |
+| --- | --- |
+| Lowest | `~/lsp.*` and `~/.lsp.*` |
+|  | LSP configuration supplied by installed plugins |
+|  | User configuration directories, including the active omp agent directory and supported Claude, Codex, and Gemini directories |
+|  | Launch-directory configuration directories such as `<cwd>/.omp`, `<cwd>/.claude`, `<cwd>/.codex`, and `<cwd>/.gemini` |
+| Highest | `<cwd>/lsp.*` and `<cwd>/.lsp.*` |
+
+For omp-owned configuration, prefer:
+
+- Project: `<project>/.omp/lsp.json`
+- User: `~/.omp/agent/lsp.json` for the default profile, or the active profile's agent directory
+
+At one location, precedence is `lsp.json`, `.lsp.json`, `lsp.yaml`, `.lsp.yaml`, `lsp.yml`, then `.lsp.yml`. Server entries merge shallowly by name. Servers not mentioned in an override retain their built-in definitions, and omp still filters the merged set by `disabled`, root markers, and executable availability.
+
+The top-level `servers` wrapper is optional, but do not mix wrapped and flat server entries. These forms are equivalent:
+
+```json
+{
+  "servers": {
+    "eslint": { "disabled": true }
+  },
+  "idleTimeoutMs": 300000
+}
+```
+
+```yaml
+eslint:
+  disabled: true
+idleTimeoutMs: 300000
+```
+
+An omitted, zero, or negative `idleTimeoutMs` leaves idle shutdown disabled.
+
+## LSP settings
+
+Open `/settings`, then use the **Files → LSP** group to change these interactively. Persistent settings can also go in user `~/.omp/agent/config.yml` or project `.omp/config.yml`; see [Settings](/docs/settings) for profiles and precedence.
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `lsp.enabled` | `true` | Enables symbol intelligence, LSP formatting, and LSP diagnostics. |
+| `lsp.lazy` | `true` | Starts a server only when a matching file operation needs it. Set `false` to warm detected servers in the background at interactive startup. |
+| `lsp.shared` | `true` | Shares one server per project through the daemon broker, with private-server fallback. |
+| `lsp.formatOnWrite` | `false` | Formats matching code after omp writes it. |
+| `lsp.diagnosticsOnWrite` | `true` | Returns diagnostics after file writes. |
+| `lsp.diagnosticsOnEdit` | `false` | Also returns diagnostics after incremental edits. |
+| `lsp.diagnosticsDeduplicate` | `true` | Suppresses diagnostics already shown for a file unless they changed. |
+
+For a one-off session with all LSP-backed behavior disabled, launch:
+
+```sh
+omp --no-lsp
+```
+
+## Server configuration reference
+
+A partial override of a built-in server may omit inherited fields. A new server needs the three required fields shown below.
+
+| Field | Type | Required for a new server | Purpose |
+| --- | --- | --- | --- |
+| `command` | string | Yes | Executable name or absolute path. |
+| `fileTypes` | string[] | Yes | Extensions handled by the server, including the leading dot. |
+| `rootMarkers` | string[] | Yes | Files or directories that identify the launch directory as a matching project; one-level wildcards are supported. |
+| `args` | string[] | No | Command-line arguments for the server process. |
+| `languageId` | string | No | Language identifier sent for opened files; inferred from the path when omitted. |
+| `initOptions` | object | No | Server-specific initialization options. |
+| `settings` | object | No | Server-specific workspace settings. |
+| `disabled` | boolean | No | Excludes this server when `true`. |
+| `warmupTimeoutMs` | number | No | Per-server eager-start timeout in milliseconds. |
+| `isLinter` | boolean | No | Marks a diagnostics/formatting-only server so it is not used for type intelligence. |
+| `capabilities` | object | No | Enables supported optional integrations: `flycheck`, `ssr`, `expandMacro`, `runnables`, and `relatedTests`. These are currently used for rust-analyzer. |
+| `workspaceReadyTimings` | object | No | Advanced rust-analyzer timing overrides: `timeoutMs`, `pollMs`, `settleMs`, and `statusRequestTimeoutMs`. |
+
+## Troubleshooting
+
+### No server appears in the welcome panel or `/session`
+
+- Launch omp from the directory containing the expected root marker; discovery does not search parents.
+- Confirm the binary is installed where omp can resolve it. For example, run `command -v rust-analyzer` or inspect the project's local bin directory.
+- Check that a custom server has non-empty `command`, `fileTypes`, and `rootMarkers` fields.
+- Check the config filename and syntax. Unreadable or invalid JSON/YAML is ignored so other sources can continue loading.
+- If several Python or JavaScript servers are installed, disable the ones you do not want so server selection is unambiguous.
+
+### A server is `available`, but nothing has started
+
+This is normal with `lsp.lazy: true`. Ask for a definition, references, rename, or diagnostics on a matching file. Set `lsp.lazy: false` if you prefer background startup when the interactive session opens.
+
+### Startup fails or diagnostics stay empty
+
+Ask omp to report which server it selected, reload it, and show the startup error. Verify the configured command and arguments outside omp. Also confirm that the file extension is in `fileTypes` and that the file belongs to the project described by the server's root marker.
+
+A server marked `isLinter` can provide formatting, diagnostics, and fixes but not definitions, references, or semantic renames. Compiler and test output may also catch workspace or build-system errors that an LSP does not report.
+
+### A rename is refused or misses text
+
+Built-ins, external declarations, generated files, and string-only property names may not be renameable. Ask omp to show references first, then use targeted or structural edits for non-semantic occurrences. Always review the diff and run the relevant compiler or tests after a cross-project rename.

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

@@ -0,0 +1,207 @@
+<!--
+source: https://omp.sh/docs/collab
+fetched: 2026-09-06
+-->
+
+# Collab
+
+> Invite a teammate into your live omp session to watch, prompt, and help steer the work securely.
+
+Collab is for working together **in the session you already have open**. Use it when a teammate should see the full context and live progress instead of receiving screenshots or a static export. The host's omp remains authoritative: the model and tools keep running on the host machine, while guests see the same transcript and status in their own omp or browser.
+
+## Share your current session
+
+In the interactive omp session you want to share, run:
+
+```text
+/collab
+```
+
+omp starts sharing and shows:
+
+- a terminal command such as `omp join "<room>.<secret>"`,
+- a clickable browser link,
+- a QR code for the browser link, and
+- a reminder that this first link allows guests to prompt the agent.
+
+Send **one complete link** to your teammate. The terminal and browser forms grant the same permissions. Keep omp running on the host machine; that machine continues to run the agent, model requests, and tools.
+
+Running `/collab` again while hosting reprints the full-control links and QR code. To see who is connected, run:
+
+```text
+/collab status
+```
+
+The participant list identifies the host and marks guests who joined view-only.
+
+## Share a view-only link
+
+Use a view-only link for reviews, demos, or anyone who should observe without steering the work:
+
+```text
+/collab view
+```
+
+This starts sharing if necessary, or prints the view-only links for an existing collab session. A viewer can see the prior transcript and live updates, including tool cards and subagent transcripts, but cannot prompt, interrupt, answer requests, or control subagents.
+
+A hosting session has both a full-control link and a view-only link. You can give different people different access without restarting it:
+
+```text
+/collab       # print the full-control link
+/collab view  # print the view-only link
+```
+
+## Join a session
+
+Choose any of these methods.
+
+### From an omp session
+
+Paste the link into the interactive TUI:
+
+```text
+/join "<link>"
+```
+
+Your current local session is set aside while you participate. When you leave—or when the host ends sharing—omp restores the session you were using before you joined.
+
+You cannot join while you are hosting or already connected as a guest. Run `/collab stop` or `/leave` first.
+
+### From a new terminal
+
+Start omp directly in the shared session:
+
+```bash
+omp join "<link>"
+```
+
+`omp join` requires an interactive terminal. Quote the link so your shell does not interpret characters such as `#`.
+
+### From a browser
+
+Open the browser link or scan its QR code. No omp installation is required. The page connects automatically and shows the transcript, streaming output, tool cards, participants, and subagents. A full-control browser link also enables the composer, interrupt button, subagent controls, and host questions; a view-only link clearly shows that it is read-only.
+
+After joining, omp loads the existing transcript before following live activity. A terminal guest also sees the host's session status, including working directory, model, context usage, and cost, but does not change into the host's directory.
+
+## Work together
+
+| Action | Host | Full-control guest | View-only guest |
+| --- | --- | --- | --- |
+| Read the existing and live transcript | Yes | Yes | Yes |
+| See tool activity and subagent transcripts | Yes | Yes | Yes |
+| Type a prompt for the agent | Yes | Yes | No |
+| Interrupt the current response with `Esc` | Yes | Yes | No |
+| Answer a host selection or editor request | Yes | Yes | No |
+| Inspect, message, stop, or revive host subagents | Yes | Yes | No |
+| Run host-local slash commands, shell commands, Python, or skills | Yes | No | No |
+
+Prompts from guests are labeled with their display name in the transcript. The name is attribution for people; it is not an authenticated identity and is not included as instructions to the model.
+
+When the agent asks the host to choose an option or edit text, every connected full-control guest may receive the same request. The first answer or cancellation settles it and dismisses the other copies.
+
+In the terminal, a full-control guest can press `Alt+A` to open Agent Hub and inspect the host's subagents, read their transcripts, send them a message, stop them, or revive them. These actions affect work running on the host. View-only guests can inspect the same subagent information but cannot change it.
+
+Host-only commands stay host-only, including `/model`, `/compact`, `/resume`, `/branch`, `!` shell commands, `$` Python, and skills. A terminal guest can still use these local commands without changing the host session:
+
+| Guest-local command | Purpose |
+| --- | --- |
+| `/dump`, `/export`, `/copy` | Copy or export what the guest can see |
+| `/help`, `/hotkeys` | Open local help |
+| `/theme`, `/settings` | Change settings on the guest machine; the host is unaffected |
+| `/collab` | Show the guest's collab status |
+| `/leave`, `/exit`, `/quit` | `/leave` restores the previous session; `/exit` and `/quit` close omp |
+
+## Leave, stop, and reconnect
+
+A guest leaves with:
+
+```text
+/leave
+```
+
+omp closes the shared view and restores that guest's previous local session. Leaving does not stop the host or disconnect anyone else. Browser guests use the page's leave control.
+
+The host ends sharing for everyone with either command:
+
+```text
+/collab stop
+```
+
+```text
+/leave
+```
+
+Guests see that the session ended and terminal guests return to their previous local sessions. Starting `/collab` again creates new links; old links do not join the new room.
+
+Transient network or relay interruptions reconnect automatically. omp displays a `reconnecting…` status and resynchronizes the shared session when the connection returns. If the room is gone, the host stopped, the key is invalid, or the relay rejects the connection permanently, the guest session ends instead; ask the host for a fresh link if they are still sharing.
+
+## Permissions and security
+
+Collab links are bearer secrets: **anyone who has a link receives that link's permissions**.
+
+- A full-control link contains the encryption key and a write token. Its holder can read the full transcript, submit prompts that cause the host's agent to act, interrupt work, answer requests, and control subagents.
+- A view-only link contains the encryption key without the write token. Its holder can read the same potentially sensitive session history but cannot steer it.
+- There is no account-based identity or approval prompt when someone uses a valid link. Participant display names can be chosen by the participant.
+
+All session content is end-to-end encrypted with AES-256-GCM before it reaches the relay. The relay cannot read prompts, transcripts, tool details, or keys. It can observe room identifiers, connection counts, encrypted frame sizes, and limited routing metadata. In browser links, the room link is carried in the URL fragment, which browsers do not send in HTTP requests.
+
+The relay does not make a full-control guest safe by itself. A guest prompt is executed by the agent on the **host machine** under the host's configured tool and approval policies. Before sharing, review the transcript for secrets and make sure the host's permissions are appropriate. Send view-only links by default when someone only needs to observe, and stop sharing when the collaboration is over.
+
+## Relay configuration
+
+Nothing needs configuring for the hosted service. By default, `/collab` uses `wss://my.omp.sh`, derives the matching browser UI, and uses your OS username as the participant name.
+
+For a one-time alternate relay, pass it when you start sharing. A hostname without a scheme uses secure WebSocket (`wss://`):
+
+```text
+/collab relay.example.com
+```
+
+To start with a view-only link through that relay:
+
+```text
+/collab view relay.example.com
+```
+
+For a persistent choice, use `/settings` in omp or run:
+
+```bash
+omp config set collab.relayUrl wss://relay.example.com
+omp config set collab.displayName "Ada"
+```
+
+Verify the effective values with:
+
+```bash
+omp config get collab.relayUrl
+omp config get collab.displayName
+```
+
+If the browser UI is hosted separately from the relay, configure its base URL too:
+
+```bash
+omp config set collab.webUrl https://collab.example.com
+```
+
+`collab.webUrl` must be an `http://` or `https://` URL without a query string or fragment. Non-local URLs must use HTTPS; plain HTTP is accepted only for localhost. The generated browser link still points back to the configured relay.
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `collab.relayUrl` | `wss://my.omp.sh` | Relay used when `/collab` has no relay argument |
+| `collab.webUrl` | empty | Browser UI base; empty derives it from the relay URL |
+| `collab.displayName` | empty | Participant name; empty falls back to the OS username, then `anonymous` |
+
+Relay URLs may use `wss://` or `https://`; omp normalizes both to a secure relay connection. Plain `ws://` or `http://` relay URLs are allowed only for `localhost`, `127.0.0.1`, or `::1` development endpoints. A custom endpoint must implement the omp collab relay service; an ordinary WebSocket server is not sufficient.
+omp does not currently distribute a production-ready relay server or standalone relay binaries for self-hosting. The source repository includes a WebSocket-only local development stand-in, but it does not serve the browser client and is not a replacement for the hosted service.
+
+## Troubleshooting
+
+| What you see | What to do |
+| --- | --- |
+| `No relay configured` | Set `collab.relayUrl` in `/settings`, run `omp config set collab.relayUrl wss://…`, or pass a relay to `/collab`. |
+| `Stop hosting first` | Run `/collab stop`, then join the other session. |
+| `Already in a collab session` | Run `/leave` before joining another link. |
+| The guest is read-only | The host shared `/collab view`; ask for the full-control link only if you should steer the session. |
+| Browser link opens but does not connect | Confirm the host is still sharing, use the entire current link, and check that a custom `collab.webUrl` serves the omp browser client over HTTPS. |
+| `omp join requires an interactive terminal` | Run it from a TTY, or open the browser link instead. |
+| The guest joins during a response but misses that response | Wait for the next update. If the response produced no update after the join, that one in-flight response may not render live; later transcript and session updates still synchronize. |

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

@@ -0,0 +1,169 @@
+<!--
+source: https://omp.sh/docs/commit
+fetched: 2026-09-06
+-->
+
+# Creating commits
+
+> Preview a Conventional Commit, let omp separate unrelated staged work into ordered atomic commits, and recover safely if a hook, model, or push fails.
+
+## When to use `omp commit`
+
+Use `omp commit` when the changes are ready but deciding commit boundaries and writing useful Conventional Commit messages would take more care than the final Git commands. The default workflow can keep related changes together, split unrelated files or hunks into atomic commits, order dependent commits, and update nearby changelogs.
+
+You need:
+
+- a Git repository with the changes you intend to commit;
+- Git author name and email configured;
+- an authenticated, available model in omp; and
+- any repository commit hooks in working order.
+
+For `--push`, the current branch must also have a usable upstream unless your Git configuration supplies one.
+
+## Preview first
+
+Stage the exact scope you want omp to consider, inspect it, and run a dry run:
+
+```sh
+git add src/widget.ts test/widget.test.ts
+git status --short
+omp commit --dry-run
+```
+
+The preview prints either a generated message or a numbered split plan with each commit's message and selected files or hunks. It does not create commits, push, or write changelog changes.
+
+`--dry-run` can still change the Git index: if the index is empty, `omp commit` runs the equivalent of `git add -A` before analysis. For the safest preview, stage the intended files yourself first. Use `git status --short` afterward if you started with an empty index.
+
+## Shortest successful workflow
+
+After reviewing the preview, create the commit or commits:
+
+```sh
+omp commit
+```
+
+To push only after every commit succeeds:
+
+```sh
+omp commit --push
+```
+
+A single-commit proposal is committed without an additional confirmation. An interactive split proposal asks you to confirm the complete plan before Git history is changed. Answer anything other than `y` or `yes` to abort the split. In a non-interactive shell, a valid split plan proceeds without that prompt. A dry run never asks for confirmation.
+
+`--push` does not add another confirmation. If there are no changes, `omp commit --push` still tries to push existing local commits; plain `omp commit` reports that there is nothing to commit.
+
+## Which changes are considered
+
+The index defines the boundary:
+
+- If anything is already staged, omp considers the staged changes only. Unstaged and untracked work remains outside the workflow.
+- If nothing is staged, omp stages all tracked modifications and deletions plus untracked, non-ignored files, as `git add -A` would.
+- Git-ignored files remain excluded.
+- Recognized dependency lock files are excluded from semantic analysis so generated content does not create false commit boundaries. They are still committed: a split plan attaches a lock file to the commit containing its matching manifest when possible, or to the last commit otherwise.
+
+The default workflow can divide changes at file or hunk boundaries. Every staged change must appear exactly once in a split plan, and a file cannot be assigned to multiple commits. Dependencies determine commit order; invalid dependencies and cycles are rejected before any commit is created. This means a dirty tree containing several unrelated tasks may become several ordered commits rather than one broad commit.
+
+If that is not what you want, stage a narrower set and preview again:
+
+```sh
+git reset
+git add src/widget.ts test/widget.test.ts
+omp commit --dry-run
+```
+
+`git reset` here only unstages changes; it does not discard the working-tree edits.
+
+## Messages and validation
+
+Generated headers use Conventional Commit form:
+
+`fix(parser): handled empty token streams`.
+
+Supported types are `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`, `style`, and `revert`. The optional scope is validated, the summary is normalized to remove a duplicate type prefix, must fit within 72 characters, and must begin with a past-tense verb. Type-specific checks reject clear mismatches such as `docs` without documentation files or `test` without test files. A message body, when present, is a short bullet list of important details. Invalid proposals are not executed.
+
+Warnings such as a vague phrase, an oversized detail list, or weak evidence for a `perf` type are shown before committing; they do not by themselves block a valid proposal.
+
+## Changelog updates
+
+Unless `--no-changelog` is set, omp looks upward from each changed file for the nearest `CHANGELOG.md`, stopping at the repository root. A changelog file already in the staged set does not cause another target search. For each detected, parseable changelog, omp proposes user-visible entries and merges them into the unreleased section, avoiding duplicate entries, then stages the updated changelog.
+
+In a split workflow, generated changelog files are placed in the last commit. Changelog updates are applied before the interactive split confirmation, so declining that confirmation can leave a changelog modified and staged even though no commit was created. Inspect `git status --short` and keep, unstage, or restore that file as appropriate.
+
+Previewing performs changelog analysis but does not write the file. Skip all automatic changelog detection and updates when the repository does not use this format or when you want to edit release notes yourself:
+
+```sh
+omp commit --dry-run --no-changelog
+omp commit --no-changelog
+```
+
+## Context, models, and the legacy workflow
+
+Add concise information that the diff cannot reveal with `--context` (or `-c`):
+
+```sh
+omp commit --dry-run --context "This fixes #418 and preserves the old wire format"
+```
+
+Select a primary model for this run with `--model` (or `-m`):
+
+```sh
+omp commit --model anthropic/claude-opus-4-5
+```
+
+Without `--model`, omp resolves the configured `commit` model role, then its normal role fallbacks. The current default workflow uses the configured `smol` role for its commit agent when that role is available, with the selected primary model as fallback. Model selectors can include the same provider, model, and thinking-level syntax used elsewhere in omp.
+
+The default is the current agentic workflow described above: it can inspect individual files and hunks, produce one commit or a validated dependency-ordered split, and fall back to a mechanical single commit if the agent fails. Use `--legacy` only when you specifically need the older deterministic orchestration:
+
+```sh
+omp commit --dry-run --legacy
+omp commit --legacy
+```
+
+The legacy workflow creates one model-generated commit, has no atomic split review, and has no mechanical fallback when model generation fails. It still follows the same staged-change, changelog, hook, dry-run, and push rules.
+
+## Failures and safe recovery
+
+Git hooks run normally for every generated commit. A refusing `pre-commit` or `commit-msg` hook prints the hook's own message and makes `omp commit` exit nonzero. Fix the reported problem rather than bypassing the hook, then inspect the repository before retrying:
+
+```sh
+git status --short
+git log -5 --oneline
+```
+
+For a single commit failure, the intended changes remain available and normally remain staged. For a split failure, commits completed before the failure remain in history; the currently failing group remains staged, and later groups remain in the working tree. omp reports how many commits were created and confirms that no changes were lost. Do not blindly restart the original full workflow. Fix the hook or files, commit or unstage the current group, then preview the remaining work again:
+
+```sh
+git status --short
+omp commit --dry-run
+omp commit
+```
+
+If a large or binary staged diff cannot be sliced safely, omp aborts before creating the split commits and advises committing the large file separately. Narrow the index, commit that file, then stage and preview the rest.
+
+A model or agent failure in the default workflow may create a mechanical single fallback commit and still exit nonzero. Therefore, **a nonzero exit does not always mean no commit was created**. Check `git log` and `git status`, review the fallback message and content, and amend or undo it with your normal non-destructive Git recovery process if it is unsuitable. The legacy workflow instead exits nonzero without a fallback commit when model generation fails.
+
+Push happens only after all requested commits have been created. If the remote rejects the push or no upstream exists, the local commits remain intact and omp exits nonzero. Repair the upstream or remote state, then push directly:
+
+```sh
+git push --set-upstream origin HEAD
+```
+
+Or, once the branch has a working upstream, let the clean-tree path retry the existing commits:
+
+```sh
+omp commit --push
+```
+
+After declining a split, a failed hook, a fallback, or a failed push, always use `git status` and `git log` as the source of truth before running `omp commit` again. Avoid `git reset --hard`: none of these failure paths require discarding working-tree changes.
+
+## Options
+
+| Option | Effect |
+| --- | --- |
+| `--dry-run` | Generates a message or split plan without committing, writing changelogs, or pushing. May stage all changes when the index starts empty. |
+| `--push` | Pushes after successful commit creation, or pushes existing commits when there is nothing new to commit. |
+| `--no-changelog` | Disables changelog detection and updates. |
+| `--context <text>`, `-c <text>` | Adds run-specific intent for message, split, and changelog decisions. |
+| `--model <selector>`, `-m <selector>` | Overrides primary model selection for this run. |
+| `--legacy` | Uses the older single-commit deterministic pipeline. |
+| `--help`, `-h` | Shows current command help. |