better-dsh 0.2.4 → 0.2.5-a

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

@@ -0,0 +1,165 @@
+<!--
+source: https://omp.sh/docs/subagent-authoring
+fetched: 2026-09-06
+-->
+
+# Authoring subagents
+
+> Define a named specialist in one Markdown file, give it only the tools it needs, and ask omp to use it by name.
+
+A custom subagent is useful when you repeat the same delegation: reviewing an API, checking migrations, researching a dependency, or making a tightly scoped kind of change. Give that work a stable name and instructions once, then ask omp to use the specialist whenever the need returns.
+
+## Create the smallest useful agent
+
+For a project-specific, read-only API reviewer, create `.omp/agents/api-reviewer.md`:
+
+```md
+---
+name: api-reviewer
+description: Review API changes for compatibility, missing tests, and contract drift.
+tools: [read, grep, glob]
+---
+
+Review the assigned API change.
+
+Check exported types, HTTP behavior, tests, and documented contracts. Report only concrete findings with file and line references. Do not edit files.
+```
+
+Only `name` and `description` are required. The Markdown body is the agent's durable instructions. This example grants an explicit read-only tool set rather than inheriting every tool available to the current session.
+
+Save the file, open `/agents`, and press <kbd>Ctrl</kbd>+<kbd>R</kbd>. Search for `api-reviewer` and confirm that the detail pane shows the expected file path. If it is disabled, press <kbd>Space</kbd> to enable it.
+
+Then ask naturally and use the exact name:
+
+```text
+Use the api-reviewer subagent to review the current branch. Keep it read-only and report actionable findings.
+```
+
+You do not need a special request format. Naming the agent is the clearest way to select it; its `description` also tells omp when the specialist is appropriate.
+
+## Choose where it lives
+
+| Scope | Location | Use it for |
+| --- | --- | --- |
+| Project | `<project>/.omp/agents/<name>.md` | Repository-specific conventions that should travel with the project. omp walks upward from the current directory and uses the nearest `.omp/agents` directory. |
+| User | `~/.omp/agent/agents/<name>.md` | Personal specialists available across projects. With a named profile, use `~/.omp/profiles/<profile>/agent/agents/`. |
+| OMP extension | `<extension-root>/agents/<name>.md` | Agents distributed with an OMP extension package. |
+| Claude marketplace plugin | `<plugin-root>/agents/<name>.md` | Agents supplied by an enabled Claude marketplace plugin. |
+
+For a given `name`, the first definition wins:
+
+1. the nearest project `.omp/agents` directory
+2. the active user's agents directory
+3. OMP extension roots, ordered by their configured source: command-line extensions, project extensions, user extensions, then installed npm/link plugins
+4. Claude marketplace plugins, project scope before user scope
+5. agents bundled with omp
+
+Names are matched exactly and are case-sensitive. Prefer lowercase kebab-case names. Within one directory, files are considered in filename order, so do not keep two definitions with the same `name`. A project or user definition can intentionally replace a plugin or bundled agent by reusing its name; `/agents` shows which file won.
+
+Direct `.claude/agents`, `.codex/agents`, and similar cross-tool directories are not scanned. Their frontmatter contracts are not interchangeable with omp's.
+
+## Write effective instructions
+
+Keep the body specific to the reusable role. State:
+
+- what the agent owns and what it must not do
+- the checks or workflow it should follow
+- the evidence expected in its answer
+- whether it may edit files
+- any project boundaries that remain true across assignments
+
+Put the changing work in your request, not in the definition. For example, keep “review API compatibility” in the file and put “review the pagination change on this branch” in the prompt. Avoid copying general project instructions into every agent; normal project context still applies.
+
+The `description` is a selection hint, not a second system prompt. Use concrete verbs, subject matter, and boundaries: “Review database migrations for unsafe locks and rollback gaps” is more useful than “A helpful database expert.”
+
+## Grant tools safely
+
+An explicit `tools` list is a capability boundary. Start with the smallest set that can complete the job:
+
+- investigation usually needs `read`, `grep`, and `glob`
+- add `lsp` when semantic code navigation is useful
+- add `edit` or `write` only when the agent is meant to change files
+- add `bash` only when it must run commands; shell access can also modify the workspace
+- add `web_search`, `browser`, `github`, or plugin/MCP tools only when external access is part of the role
+- add `task` only when this specialist must delegate further, and restrict `spawns` as well
+
+When `tools` is omitted, the agent inherits the parent session's available tools. That is convenient for a general-purpose worker but is usually too broad for a reviewer. omp automatically adds the private completion capability an agent needs; do not add it yourself.
+
+Isolation is chosen for an individual delegation, not in agent frontmatter. Ask for it explicitly when the agent will make risky or independent changes:
+
+```text
+Use the migration-fixer subagent in an isolated worktree to fix the failing migration test.
+```
+
+Isolation requires a supported Git checkout and configured task isolation. It separates filesystem changes; it does not make network, shell, or credential access harmless, so keep the tool grant narrow.
+
+## Frontmatter reference
+
+Frontmatter keys may use camelCase or kebab-case. These are the current public fields:
+
+| Field | Meaning |
+| --- | --- |
+| `name` | **Required.** Exact, case-sensitive identifier used to select the agent. |
+| `description` | **Required.** Short explanation of when this agent should be used. |
+| `tools` | CSV string or YAML list of allowed tool names. Omit to inherit the current session's tools. |
+| `model` | One model selector, a CSV string, or a YAML list tried in order. It may be a concrete selector such as `openai/gpt-5-mini` or a role alias such as `"@review"`. Omit to use normal inherited selection. |
+| `thinking-level` | `inherit`, `off`, `auto`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. The older `thinking` key is also accepted. Actual support is model-dependent. |
+| `spawns` | Agent names this agent may delegate to, as a CSV string or list; `*` allows any discovered agent. Omit for none. For compatibility, granting the `task` tool without this field implies `*`, so set this field explicitly. |
+| `autoload-skills` | Skill names to load before the first assignment, as CSV or a list. Unknown names are ignored. |
+| `read-summarize` | Set `false` when `read` must return verbatim code rather than structural summaries. Normally leave it enabled. |
+| `output` | JSON Schema for a structured result. Omit when a normal prose report is appropriate. |
+| `blocking` | Set `true` when callers should wait for this agent even if asynchronous delegation is enabled. Usually omit it. |
+| `prewalk` | `true` hands off to the model in the `smol` role at the first edit or write; a model selector or role alias chooses another target. Use it when a stronger model should inspect or plan before a cheaper model implements. |
+| `advisor` | `true` uses the configured `advisor` model role; a model selector or role alias chooses a specific advisor. Subagents otherwise run without an advisor. |
+
+There is no separate `role` field. Put a role alias in `model`, then map that alias in your user or project configuration. This keeps agent instructions stable while letting each environment choose the concrete model:
+
+```md
+---
+name: api-reviewer
+description: Review API changes for compatibility, missing tests, and contract drift.
+tools: [read, grep, glob]
+model: "@review"
+thinking-level: high
+---
+
+Review the assigned API change and report concrete findings with file and line references.
+```
+
+```yaml
+# ~/.omp/agent/config.yml, or the active profile's config.yml
+modelRoles:
+  review: openai/gpt-5.4
+```
+
+You can assign or change custom model roles from the Roles view in `/models`. The `/agents` hub also lets you override a discovered agent's model, prewalk target, or advisor without editing the shared definition; those per-agent settings take precedence over its frontmatter.
+
+## Reload and maintain definitions
+
+A delegation re-reads agent definitions before it starts, so a saved edit applies to the next use. The `/agents` screen has its own displayed snapshot; press <kbd>Ctrl</kbd>+<kbd>R</kbd> there after adding, renaming, or editing a file.
+
+For agents supplied by extensions or plugins, run `/reload-plugins` after installing or changing the package so omp reloads the whole plugin surface. Plain project and user Markdown edits do not require restarting omp.
+
+Treat project agents like code: review changes, keep descriptions accurate, and remove obsolete duplicate files. If you want editable copies of omp's bundled definitions as a starting point, run `omp agents unpack --project` or `omp agents unpack` for user scope; customize only the files you intend to override.
+
+## Troubleshooting
+
+**The agent is missing from `/agents`.** Press <kbd>Ctrl</kbd>+<kbd>R</kbd>, check that the file ends in `.md`, and confirm it is directly inside an `agents` directory. Verify that the frontmatter has non-empty string values for both `name` and `description`. Invalid YAML or missing required fields skips that file while discovery continues.
+
+**The wrong definition wins.** Inspect the source path in `/agents`, then check for the same exact `name` in a higher-precedence project or user directory. In a monorepo, remember that the nearest `.omp/agents` directory is the project source.
+
+**omp does not choose the agent.** Ask for it by exact name. Improve `description` with the task, subject, and boundary that distinguish it from other agents. Also verify in `/agents` that the agent is enabled.
+
+**The requested model does not resolve.** Open `/models` and confirm the concrete model or role alias is configured and authenticated. For fallback behavior, list more than one selector under `model`.
+
+**A tool is unavailable.** Add its exact registered name to `tools`, or remove the explicit list only if inheriting the full parent tool set is intentional. Plugin-provided tools also require the plugin to be enabled and reloaded.
+
+**An edit appears ignored.** Actual delegation reads fresh definitions, but the `/agents` inventory may still show its previous snapshot. Reload the hub. For an extension or plugin package, use `/reload-plugins` as well.
+
+## Related
+
+- [Subagents & Agent Hub](/docs/subagents) — delegate work and observe running agents.
+- [Agents & model roles](/docs/agents-and-roles) — choose whether to change behavior, routing, or the underlying model.
+- [Skills](/docs/skills) — reusable playbooks an agent can autoload.
+- [Plugins](/docs/plugins) — package and distribute agents with other capabilities.
+- [Settings](/docs/settings) — configure model roles and task isolation.

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

@@ -0,0 +1,149 @@
+<!--
+source: https://omp.sh/docs/subagents
+fetched: 2026-09-06
+-->
+
+# Subagents & Agent Hub
+
+> Delegate independent work to specialist sessions, watch it happen, and steer or stop each worker without leaving your main conversation.
+
+Subagents let omp split a larger job into focused child sessions. Use them when research, implementation, or review can proceed independently: you get parallel progress and specialist attention while the main session keeps responsibility for integration.
+
+Start by asking in ordinary language. State the outcome, the parts that may run in parallel, and any ownership or safety boundary:
+
+> Parallelize this migration. Give each worker a file-disjoint package, use isolated workspaces for edits, and have the main session integrate and verify the result.
+
+> Use the scout to map every authentication entry point, then use the security-reviewer to check the proposed fix. Do not edit during the research pass.
+
+> Have the designer implement the responsive states while a reviewer checks the existing accessibility behavior. Keep them off the same files.
+
+You do not need to describe omp's internal delegation protocol. The main session chooses the fan-out, gives each worker its assignment, and collects the results.
+
+## When delegation helps
+
+Good candidates have clear boundaries and can make progress without repeatedly asking another worker for unfinished information:
+
+- independent repository research, external API research, or competing investigations;
+- file-disjoint implementation across packages or features;
+- a specialist pass such as design, code review, or security review;
+- mechanical changes that can be divided by directory or generated artifact;
+- an independent review after the implementation is complete.
+
+Keep work in the main session when it is a small sequential change, when several steps must continuously modify the same file, or when each decision depends on the previous result. More workers do not make a dependency chain parallel, and overlapping writers create merge risk.
+
+A child session does **not** inherit the main conversation. omp passes the assignment and relevant shared context, while the child can see the allowed workspace and project instructions. When context is easy to miss, say so explicitly:
+
+> Delegate this, but tell every worker that `packages/api/schema.ts` is the source of truth and that generated files must not be edited.
+
+## Choose a specialist
+
+You may name a specialist in your prompt, or let omp choose. The current bundled set is:
+
+| Specialist | Use it for |
+| --- | --- |
+| `scout` | Fast, read-only repository exploration and compressed findings. |
+| `designer` | UI/UX implementation, accessibility, and visual refinement. |
+| `reviewer` | Evidence-backed correctness and quality review. |
+| `security-reviewer` | Read-only vulnerability discovery and security analysis. |
+| `librarian` | Source-verified research into external libraries and APIs. |
+| `task` | General multi-step work with the full available capability set. |
+| `sonic` | Strictly mechanical edits or data collection that need little reasoning. |
+
+For example: “Use the librarian to verify the upstream retry semantics,” “Ask the reviewer to inspect only the current diff,” or “Use sonic workers to update these file-disjoint fixtures.” Exact custom names are case-sensitive.
+
+Open `/agents` to inspect the available definitions, their source, whether they are enabled, and their model, prewalk, and advisor routing. Use <kbd>Ctrl</kbd>+<kbd>R</kbd> there after changing a definition on disk. To create or customize a specialist, see [Authoring subagents](/docs/subagent-authoring).
+
+If you are unsure whether to change a specialist definition or only the model behind it, see [Agents & model roles](/docs/agents-and-roles).
+
+## What you see while workers run
+
+Background delegation is enabled by default. The main transcript first reports which named workers started, then its task display updates with live activity. Completed results are delivered back into the main conversation; the main agent can summarize them, reconcile disagreements, and continue the job. `/jobs` prints a compact snapshot of background jobs, but Agent Hub is the detailed view.
+
+Press <kbd>Alt</kbd>+<kbd>A</kbd> to open **Agent Hub**. <kbd>Ctrl</kbd>+<kbd>S</kbd> opens the same view through the legacy session-observe binding. From an empty main editor, double-tapping <kbd>←</kbd> also opens it when the session has an agent to show. Run `/hotkeys` to confirm or remap the active chords.
+
+Each roster row shows a worker's status, assignment or current activity, model, age, token and request usage, tool-call count, active time, and cost when that data is available. The inspector adds the current tool, retry state, context-window usage, parent/child lineage, and any isolated-workspace patch or branch information. Press <kbd>t</kbd> to switch between a flat roster and the parent/child tree.
+
+| Control | Action |
+| --- | --- |
+| <kbd>j</kbd>/<kbd>k</kbd>, arrows, or wheel | Select a worker. |
+| <kbd>Enter</kbd> or click | Open its live or persisted transcript. Opening a parked worker revives it when possible. |
+| <kbd>Tab</kbd> | Show or hide the inspector on a narrow terminal. |
+| <kbd>PageUp</kbd>/<kbd>PageDown</kbd> | Scroll the inspector. |
+| <kbd>r</kbd> | Revive the selected parked worker. |
+| <kbd>x</kbd> | Abort if necessary, then kill and release the worker. This is immediate. |
+| <kbd>Esc</kbd> | Close the inspector, then Agent Hub. |
+
+Statuses have distinct meanings:
+
+- **running** — the worker is in an active turn;
+- **idle** — its turn finished, but its live session is still in memory for a follow-up;
+- **parked** — its session was saved to disk and can usually be revived;
+- **aborted** — it was stopped and is terminal, though its transcript remains available.
+
+Finished workers remain associated with the session. After resuming that session, Agent Hub discovers their persisted transcripts and restores their lineage.
+
+## Read, steer, follow up, or stop
+
+Open a worker from Agent Hub to focus its session. You can read its transcript and current tool activity, then type a normal message and press <kbd>Enter</kbd>:
+
+> Stop changing the API package. Finish only the client tests and report what remains.
+
+> Before you conclude, compare your finding with the generated schema and cite both files.
+
+A message to a running worker is steering and lands at a safe step boundary; a message to an idle worker starts a follow-up; a message to a parked worker revives it first. With an empty editor, press <kbd>Esc</kbd> or double-tap <kbd>←</kbd> to return to the main session. Returning does not interrupt the worker.
+
+Prefer a follow-up to the same worker when it already has the right context. Use <kbd>x</kbd> when its work is unsafe, out of scope, stuck, or no longer useful. Killing releases that worker instance, so start a new worker if more work is needed later.
+
+## Shared checkout or isolated workspace
+
+By default, subagents work in the same checkout as the main session. That is fast and lets everyone see current changes, but concurrent writers can overwrite assumptions or produce interleaved edits. Give non-isolated workers file-disjoint ownership and keep final integration in one place.
+
+For stronger edit separation, open `/settings`, choose the **Tasks → Isolation** group, and set **Isolation Mode** to **Auto**. Then ask for it directly:
+
+> Run the three implementation workers in isolated workspaces. Apply only successful changes and have the main session resolve integration conflicts.
+
+An isolated worker receives a filesystem clone or overlay selected for the platform. omp captures its changes and integrates them with the configured patch or branch strategy. Isolation requires a Git repository. The managed workspace normally lives under `~/.omp/wt`; `worktree.base` changes that location. With the defaults, successful changes are applied to the parent checkout as a patch.
+
+Isolation protects concurrent checkout edits; it is **not** a general security sandbox. A worker may still run commands, use networked tools, or affect external services allowed by its tool set and credentials. Isolated workers also cannot be revived after completion because their temporary workspace has been torn down; their transcript and patch metadata remain inspectable.
+
+Even isolated edits can conflict when integrated, especially when workers touch the same lines. Divide ownership first, review the resulting diff, and ask the main session to verify the combined behavior.
+
+## Cost, safety, and limits
+
+Every worker is a separate model session, so parallelism can multiply token use, provider requests, and cost. Agent Hub shows measured per-worker and aggregate usage. Start with the smallest useful fan-out, use `scout` or `sonic` only for work suited to them, and stop workers whose assignments have become obsolete. Advisor and prewalk routing may add model calls of their own.
+
+Subagents run headlessly and cannot pause for an interactive per-tool approval. Treat each assignment as delegated authority: restrict its scope, choose a read-only specialist where possible, avoid handing unrelated secrets or production operations to a worker, and supervise external side effects. Workspace isolation does not protect remote accounts or services.
+
+The important defaults are:
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `async.enabled` | `true` | Let ordinary workers continue in the background. |
+| `task.maxConcurrency` | `32` | Bound concurrently running workers; additional work queues. `0` is unlimited. |
+| `task.maxRecursionDepth` | `2` | Limit how deeply workers may delegate again. |
+| `task.softRequestBudget` | `200` | Ask a long-running worker to wrap up, then force a partial result at 1.5× the budget. `0` disables it. |
+| `task.maxRuntimeMs` | `0` | Hard per-worker wall-clock limit; `0` means no limit. |
+| `task.agentIdleTtlMs` | `420000` | Park an idle worker after seven minutes; `0` keeps it live until exit. |
+| `task.isolation.mode` | `none` | Enable isolated workspaces with `auto` or a specific backend. |
+| `task.isolation.apply` | `true` | Apply successful isolated changes to the parent checkout. |
+| `task.isolation.merge` | `patch` | Integrate isolated changes as patches rather than branches. |
+
+Use `/settings` for these controls and `/agents` for per-agent enablement and model routing. See [Settings](/docs/settings) for editing `~/.omp/agent/config.yml` directly.
+
+## Troubleshooting
+
+**omp keeps the work in the main session.** Ask explicitly: “Parallelize this with three file-disjoint workers,” or name the specialist. In `/settings`, **Prefer Task Delegation** can be changed from `default` to `preferred` or `always` when you want more aggressive delegation.
+
+**A named specialist is unknown or unavailable.** Open `/agents`, check the exact case-sensitive name, scope, and enabled state, then press <kbd>Ctrl</kbd>+<kbd>R</kbd> to reload definitions. A project definition takes precedence over a user or bundled definition with the same name.
+
+**A worker stays queued.** Running workers have reached `task.maxConcurrency`, or the model provider is rate-limiting requests. Reduce the fan-out, wait for a slot, or raise the limit cautiously.
+
+**Workers produce conflicting edits.** Stop overlapping writers, give each worker file-disjoint ownership, and retry with isolation enabled. Isolation reduces live-checkout interference but does not make overlapping patches merge cleanly.
+
+**Isolation is unavailable.** Confirm `task.isolation.mode` is not `none` and that omp is running in a Git repository. Isolation is not available in plan mode, which keeps delegated work read-only. If automatic integration fails, inspect the patch or branch information in Agent Hub before applying anything manually.
+
+**A finished worker cannot be revived.** Isolated workers are intentionally non-revivable after teardown, and killed or hard-aborted workers are terminal. Start a new worker with the old result summarized in its prompt. Ordinary parked workers can be revived with <kbd>r</kbd> or by opening and messaging them.
+
+**The result is partial or stopped.** Check the transcript for a soft request-budget notice, wall-clock timeout, provider error, or manual abort. Narrow the remaining assignment and follow up with the same ordinary worker when it is idle or parked; otherwise start a replacement.
+
+**Agent Hub appears empty.** It shows workers belonging to the current session. Resume the session that created them, or start a delegated task here. `/jobs` may still show recent background process records, but it is not a replacement for the worker transcript.

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

@@ -0,0 +1,230 @@
+<!--
+source: https://omp.sh/docs/themes
+fetched: 2026-09-06
+-->
+
+# Themes
+
+> Preview a bundled palette, follow your terminal’s dark or light appearance, or install a readable JSON theme of your own.
+
+Themes control the TUI’s text, backgrounds, borders, Markdown, syntax highlighting, diffs, input modes, status line, and symbols. The fastest way to choose one is `/settings`: open **Appearance**, then **Dark Theme** or **Light Theme**. Moving through the list previews each bundled or installed theme immediately. Press Enter to keep the highlighted theme, or Escape to restore the previous one.
+
+## Follow the terminal appearance
+
+omp does not have one fixed “system” palette. It keeps a dark-theme slot and a light-theme slot, then uses the slot matching the terminal background. The defaults are `titanium` for dark backgrounds and `light` for light backgrounds.
+
+Set both slots in `/settings`, or in the active agent configuration:
+
+```yaml
+# ~/.omp/agent/config.yml
+theme:
+  dark: titanium
+  light: light
+```
+
+omp determines the slot from the terminal-reported OSC 11 background, then `COLORFGBG`. On macOS under Zellij, where OSC 11 is unreliable, it can use the macOS appearance. If none is available, it chooses the dark slot. Appearance changes are reevaluated while the interactive TUI is running.
+
+The bundled list includes `dark`, `light`, `titanium`, terminal-oriented palettes such as `dark-terminal`, and many named dark and light palettes. Use the `/settings` list as the authoritative catalog for your installed version rather than copying a name from another release.
+
+## Create and install a custom theme
+
+A custom theme is one JSON file in the active agent directory:
+
+- default profile: `~/.omp/agent/themes/<name>.json`
+- named profile: `~/.omp/profiles/<profile>/agent/themes/<name>.json`
+- custom agent directory: `$PI_CODING_AGENT_DIR/themes/<name>.json`
+
+Project-local theme files are not scanned. The filename without `.json` is the selection name; use the same value for the JSON `name`. A bundled theme wins if its name collides with a custom file.
+
+Create the directory, then save the complete minimal theme below as `~/.omp/agent/themes/ink.json`:
+
+```sh
+mkdir -p ~/.omp/agent/themes
+```
+
+```json
+{
+  "name": "ink",
+  "vars": {
+    "fg": "#e6edf3",
+    "muted": "#8b949e",
+    "dim": "#6e7681",
+    "accent": "#79c0ff",
+    "green": "#56d364",
+    "red": "#ff7b72",
+    "yellow": "#e3b341",
+    "purple": "#d2a8ff",
+    "panel": "#161b22",
+    "selected": "#26364a",
+    "border": "#30363d"
+  },
+  "colors": {
+    "accent": "accent",
+    "border": "border",
+    "borderAccent": "accent",
+    "borderMuted": "border",
+    "success": "green",
+    "error": "red",
+    "warning": "yellow",
+    "muted": "muted",
+    "dim": "dim",
+    "text": "fg",
+    "thinkingText": "muted",
+
+    "selectedBg": "selected",
+    "userMessageBg": "panel",
+    "customMessageBg": "panel",
+    "toolPendingBg": "panel",
+    "toolSuccessBg": "#14251a",
+    "toolErrorBg": "#2d1719",
+    "statusLineBg": "panel",
+
+    "userMessageText": "fg",
+    "customMessageText": "fg",
+    "customMessageLabel": "accent",
+    "toolTitle": "fg",
+    "toolOutput": "muted",
+
+    "mdHeading": "accent",
+    "mdLink": "accent",
+    "mdLinkUrl": "muted",
+    "mdCode": "yellow",
+    "mdCodeBlock": "fg",
+    "mdCodeBlockBorder": "border",
+    "mdQuote": "muted",
+    "mdQuoteBorder": "border",
+    "mdHr": "border",
+    "mdListBullet": "accent",
+
+    "toolDiffAdded": "green",
+    "toolDiffRemoved": "red",
+    "toolDiffContext": "muted",
+
+    "syntaxComment": "muted",
+    "syntaxKeyword": "purple",
+    "syntaxFunction": "accent",
+    "syntaxVariable": "fg",
+    "syntaxString": "green",
+    "syntaxNumber": "yellow",
+    "syntaxType": "accent",
+    "syntaxOperator": "red",
+    "syntaxPunctuation": "muted",
+
+    "thinkingOff": "dim",
+    "thinkingMinimal": "muted",
+    "thinkingLow": "accent",
+    "thinkingMedium": "green",
+    "thinkingHigh": "yellow",
+    "thinkingXhigh": "purple",
+    "bashMode": "green",
+    "pythonMode": "yellow",
+
+    "statusLineSep": "dim",
+    "statusLineModel": "purple",
+    "statusLinePath": "accent",
+    "statusLineGitClean": "green",
+    "statusLineGitDirty": "yellow",
+    "statusLineContext": "accent",
+    "statusLineSpend": "muted",
+    "statusLineStaged": "green",
+    "statusLineDirty": "yellow",
+    "statusLineUntracked": "red",
+    "statusLineOutput": "fg",
+    "statusLineCost": "yellow",
+    "statusLineSubagents": "purple"
+  },
+  "symbols": {
+    "preset": "unicode"
+  }
+}
+```
+
+Open `/settings` after installing the file and select `ink` for **Dark Theme**. If the settings list was already open when you created the file, close and reopen it; restart omp if the new name still does not appear. To use a custom light palette, design it against a light terminal background and select it for **Light Theme** instead.
+
+## File format and color values
+
+`name` and `colors` are required. `vars`, `export`, and `symbols` are optional.
+
+Each color may be:
+
+- `"#RRGGBB"` for an RGB color;
+- an integer from `0` through `255` for an ANSI 256-color palette index;
+- the name of an entry in `vars` (references may be nested); or
+- `""` to use the terminal’s default foreground or background.
+
+Missing and circular variable references are errors. Hex colors are emitted as truecolor on capable terminals and converted to 256 colors otherwise. Numeric values always address the terminal’s 256-color palette, so their exact appearance depends on the terminal. The `dark-terminal` built-in is a useful compatibility starting point, while `""` lets the terminal own the base foreground or background.
+
+All of these `colors` keys are required except `thinkingMax`, which is optional and falls back to `thinkingXhigh`:
+
+| Area | Tokens |
+| --- | --- |
+| Core | `accent`, `border`, `borderAccent`, `borderMuted`, `success`, `error`, `warning`, `muted`, `dim`, `text`, `thinkingText` |
+| Backgrounds | `selectedBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `statusLineBg` |
+| Message and tool text | `userMessageText`, `customMessageText`, `customMessageLabel`, `toolTitle`, `toolOutput` |
+| Markdown | `mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet` |
+| Diff | `toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext` |
+| Syntax | `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation` |
+| Thinking and input modes | `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, optional `thinkingMax`, `bashMode`, `pythonMode` |
+| Status line | `statusLineSep`, `statusLineModel`, `statusLinePath`, `statusLineGitClean`, `statusLineGitDirty`, `statusLineContext`, `statusLineSpend`, `statusLineStaged`, `statusLineDirty`, `statusLineUntracked`, `statusLineOutput`, `statusLineCost`, `statusLineSubagents` |
+
+### Optional exports and symbol overrides
+
+HTML export colors can be supplied independently:
+
+```json
+"export": {
+  "pageBg": "#0d1117",
+  "cardBg": "#161b22",
+  "infoBg": "#26364a"
+}
+```
+
+Without them, omp derives export backgrounds from the theme. `symbols.preset` accepts `unicode`, `nerd`, or `ascii`; Nerd symbols require a Nerd Font. The global **Symbol Preset** setting overrides the theme’s preset. Advanced themes may also replace individual symbols and spinner frames:
+
+```json
+"symbols": {
+  "preset": "ascii",
+  "overrides": {
+    "status.success": "OK",
+    "nav.cursor": ">",
+    "boxRound.topLeft": "+"
+  },
+  "spinnerFrames": {
+    "status": [".", "o", "O", "o"],
+    "activity": [".", "..", "..."]
+  }
+}
+```
+
+Override keys use the UI symbol vocabulary, including `status.*`, `nav.*`, `tree.*`, `boxRound.*`, `boxSharp.*`, `sep.*`, `icon.*`, `thinking.*`, `md.*`, `lang.*`, `tab.*`, and `tool.*`. Unknown keys are ignored. `spinnerFrames` may instead be one non-empty string array applied to both spinners; in the object form, `status` and `activity` are independently optional, but at least one must be present and non-empty.
+
+## Reload and review readability
+
+Once an installed custom theme is active in an interactive session, omp watches that file. Saving valid JSON repaints the TUI after a short debounce; there is no reload command. A temporarily missing, malformed, or incomplete file leaves the last successfully loaded version on screen. Fix and save it again. Built-in themes are embedded and are not watched.
+
+Before keeping a theme, inspect normal conversation text, selected rows, Markdown links and code, pending/success/error tool blocks, diffs, syntax, every thinking level, bash and Python modes, and all status-line segments. In particular:
+
+- keep foreground/background contrast high, including muted text and selected rows;
+- make errors, warnings, and additions distinguishable by luminance as well as hue;
+- try both truecolor and a 256-color terminal if the theme will be shared;
+- choose `ascii` if border or icon glyphs render with the wrong width;
+- enable **Color Blind Mode** in `/settings` when useful. It shifts a hex `toolDiffAdded` green toward blue; it does not rewrite the rest of the palette.
+
+## Troubleshooting
+
+**The theme is not listed.** Check that the file is directly inside the active agent’s `themes` directory, ends in `.json`, and was present when the settings list was opened. A project `.omp/themes` directory is not a theme source.
+
+**A different theme loads.** Do not reuse a bundled name: bundled themes take precedence. Also check whether you changed the dark slot while omp currently detects a light background, or vice versa.
+
+**Selection reports missing colors.** Custom themes require the full token set above. `thinkingMax` alone is optional.
+
+**Selection reports an invalid color or variable.** Use `#RRGGBB`, `0`–`255`, `""`, or a resolvable `vars` name. Check JSON syntax, missing variables, and reference cycles.
+
+**Startup falls back to `dark`.** The configured theme could not be found or validated. Repair the selected file or choose a bundled theme in `/settings`; a failed initial load uses the built-in `dark` fallback.
+
+**A save does not repaint.** Live reload only watches the currently active custom file. Select it first, then save valid JSON. If an editor replaced or removed the file temporarily, save it once more after the final file exists.
+
+## Related
+
+- [Settings](/docs/settings) — configuration file locations and appearance settings.
+- [Plugins](/docs/plugins) — extension installation and other customization surfaces.