better-dsh 0.2.4 → 0.2.5

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

@@ -0,0 +1,175 @@
+<!--
+source: https://omp.sh/docs/github
+fetched: 2026-09-06
+-->
+
+# GitHub
+
+> Review issues and pull requests, search GitHub, work on PRs safely, and follow Actions from an omp prompt.
+
+## Work with GitHub from a prompt
+
+Use omp to investigate issues, review pull requests, search repositories, create or update a PR branch, and watch GitHub Actions without copying everything into the chat. omp uses the GitHub CLI (`gh`), so it sees the same repositories and permissions as your signed-in GitHub account.
+
+Start by installing and authenticating `gh`, then enable the GitHub capability:
+
+```sh
+gh auth login
+gh auth status
+omp config set github.enabled true
+```
+
+You can also open `/settings` in an omp session and turn on **Tools → Available Tools → GitHub CLI**. `github.enabled` is off by default. If the capability is still unavailable in an already-running session, start a new session after enabling it.
+
+Then ask for the outcome you want:
+
+> Review PR #482. Summarize the behavior change, identify risky code paths, and call out missing tests. Do not check it out or modify anything.
+
+omp shows the GitHub data it read, links back to the source item, and asks for the appropriate approval before a GitHub operation. It does not store a separate GitHub token in `~/.omp`; authentication remains managed by `gh`.
+
+## Common workflows
+
+Run omp from a checkout whose `origin` points to GitHub when you want short issue or PR numbers to mean that repository. Outside a checkout, name the repository in your request, such as `owner/repo`.
+
+### Investigate issues
+
+Ask omp to read an issue and its discussion, connect it to the code, or compare it with related reports:
+
+> Read issue #731, trace the affected code in this checkout, and explain the most likely root cause. Do not change files yet.
+
+> Find open `bug` issues in `acme/payments` updated in the last two weeks. Group duplicates and recommend the three highest-impact fixes.
+
+The built-in GitHub capability reads and searches issues. It does not provide dedicated issue creation, editing, commenting, or closing operations. If omp proposes a separate shell-based `gh` command for such a write, that command is governed by your normal shell approval policy.
+
+### Review pull requests
+
+A review can stay remote: omp reads the PR metadata, discussion, changed-file list, and either individual file diffs or the complete diff.
+
+> Review PR #482 without checking it out. Focus on authentication regressions, unsafe error handling, and whether the tests cover failure paths.
+
+> Compare PRs #482 and #497. Explain which approach better preserves the public API and why.
+
+For a pull request in another repository, be explicit:
+
+> Review `acme/widgets` PR 482 and summarize unresolved review concerns.
+
+### Work on a PR in an isolated worktree
+
+When local execution or edits are necessary, ask omp to check out the PR. The GitHub integration creates a dedicated git worktree rather than switching or overwriting your current working tree. It reports the worktree path in the result.
+
+> Check out `acme/widgets` PR 482 in a dedicated worktree, run the targeted tests, fix the failing redirect test, and show me the diff. Do not commit or push yet.
+
+> Commit the approved changes and push them back to PR 482's source branch, then watch its CI.
+
+PR branches are named `pr-<number>`. Worktrees normally live under `~/.omp/wt`; `OMP_WORKTREE_DIR` overrides that location, followed by the `worktree.base` setting. Existing matching worktrees are reused. If a local `pr-<number>` branch points at a different commit, checkout stops instead of resetting it unless you explicitly authorize a forced reset.
+
+Pushing is deliberately constrained: omp can use the GitHub PR push workflow only for a branch previously acquired through its PR checkout workflow. This preserves the PR head repository, branch, and fork metadata and prevents an arbitrary local branch from being mistaken for a PR branch. A push can still fail when the PR author disabled maintainer edits or your GitHub account lacks permission.
+
+### Open a pull request
+
+Ask omp to create a PR from the current branch after you have reviewed and committed the changes:
+
+> Create a draft PR from the current branch into `main`. Fill the title and body from the commits, add the `bug` label, and request review from `octocat`. Show me the URL.
+
+Or supply the wording yourself:
+
+> Open a PR titled “Fix login redirect after SSO” with a concise summary and test plan. Target `main` and leave it as a draft.
+
+Creating the PR is a remote write and requires execution approval under the normal approval policy.
+
+### Search GitHub
+
+omp can search issues, pull requests, code, commits, and repositories. State the scope and filters in normal language; GitHub search qualifiers are also useful when you already know them.
+
+> Search this repository for open PRs mentioning token rotation, created since 2026-07-01.
+
+> Search code across the `acme` organization for calls to `legacyAuthenticate(` and list the repositories and paths.
+
+> Find Rust repositories in the `acme` organization pushed in the last month that mention WebAuthn.
+
+Issue, PR, code, and commit searches default to the current GitHub checkout when you omit a scope. Repository search is global unless your request includes an `org:`, `user:`, or similar GitHub qualifier. Search results are concise and capped, so ask omp to narrow the query rather than expecting an exhaustive export.
+
+### Watch GitHub Actions
+
+Ask omp to follow all workflow runs associated with the current `HEAD`, or give it a run URL:
+
+> Watch GitHub Actions for the current HEAD. If a job fails, summarize the failure and show me where the full logs were saved.
+
+> Watch `https://github.com/acme/widgets/actions/runs/123456789` until it finishes.
+
+The result updates while jobs run. A failed job is reported quickly with a log tail; full failed-job logs are saved as a session artifact and referenced in the response. When watching the current commit, omp waits for all discovered workflows and performs an extra check before declaring success so a slightly later workflow is not missed.
+
+## Paste GitHub references into a prompt
+
+`pr://` and `issue://` are optional, user-facing references. Paste one into a prompt when a bare number would be ambiguous or when you want a specific view. You do not need to invoke a file-reading command yourself.
+
+| Reference | Meaning |
+| --- | --- |
+| `issue://731` | Issue 731 in the current checkout's GitHub repository, including comments. |
+| `issue://acme/widgets/731` | Fully qualified issue. |
+| `issue://731?comments=0` | Issue without its discussion thread. |
+| `pr://482` | PR 482 in the current repository, including comments and reviews. |
+| `pr://acme/widgets/482` | Fully qualified PR. |
+| `pr://482/diff` | Changed-file list. |
+| `pr://482/diff/3` | Diff for the third file in that list; indices are 1-based. |
+| `pr://482/diff/all` | Complete unified diff. |
+| `issue://?state=open&label=bug&limit=20` | Recent matching issues in the current repository. |
+| `pr://acme/widgets?state=merged&author=octocat&limit=20` | Matching PRs in a named repository. |
+
+List references default to open items and 30 results. `limit` must be positive and is capped at 100. Issue lists accept `open`, `closed`, or `all`; PR lists also accept `merged`. Lists may be filtered by one `author` and one `label`.
+
+Examples:
+
+> Explain the user-visible impact of `pr://acme/widgets/482/diff/all` and identify migration risks.
+
+> Triage `issue://?state=open&label=regression&limit=20` against the current code.
+
+In the interactive editor, typing a standalone `#482` offers both a PR and an issue completion because GitHub shares the number space. Type `pr #482` or `issue #482` to constrain the completion.
+
+These references work through omp's GitHub-backed reading support and do not depend on the broader `github.enabled` toggle. They still require `gh` to be installed, authenticated, and able to access the repository.
+
+## Approvals, isolation, and cached data
+
+GitHub access follows three visible boundaries:
+
+- **GitHub permissions:** omp can access only what the active `gh` account can access. It cannot bypass organization SSO, repository permissions, branch protection, or fork restrictions.
+- **Operation approval:** repository reads, searches, and Actions watches request read approval; PR creation, checkout, and push request execution approval. Your active approval mode determines whether omp pauses for confirmation.
+- **Local isolation:** PR checkout creates or reuses a dedicated worktree. It does not switch the branch in your current working tree. Checkout changes local git state; PR creation and push change GitHub.
+
+Single issue and PR views and PR diffs are cached by default in `~/.omp/cache/github-cache.db`. The cache may contain private issue bodies, comments, reviews, review comments, and diffs. Rows are separated by a fingerprint of the active GitHub credential, but the database is still local sensitive data and should be protected like the rest of your account cache.
+
+Fresh entries are reused for 5 minutes. Older entries are returned while omp refreshes them in the background, and entries older than 7 days are discarded. To avoid persistent GitHub view caching:
+
+```sh
+omp config set github.cache.enabled false
+```
+
+## Settings reference
+
+Defaults work after `gh` authentication except that the broader GitHub capability must be enabled.
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `github.enabled` | `false` | Enables GitHub repository, file, search, PR worktree/push/create, and Actions workflows. |
+| `github.cache.enabled` | `true` | Caches rendered single-issue, single-PR, and PR-diff views locally. |
+| `github.cache.softTtlSec` | `300` | Time during which a cached view is returned without a network refresh. |
+| `github.cache.hardTtlSec` | `604800` | Maximum age retained for a cached view. |
+| `worktree.base` | unset | Base for omp-managed worktrees; unset normally resolves to `~/.omp/wt`. `OMP_WORKTREE_DIR` takes precedence. |
+
+Inspect the effective values with `omp config get <setting>`, or see [Settings](/docs/settings) for config files and precedence.
+
+## Troubleshooting
+
+**GitHub workflows are unavailable.** Run `gh --version`. The capability is not exposed when `gh` is missing from `PATH`. Then verify `omp config get github.enabled` prints `true`; start a new omp session if you enabled it after the session began.
+
+**Authentication fails.** Run `gh auth status`, then `gh auth login` if necessary. For a private or organization repository, confirm that the selected account has access and that any required SSO authorization is active.
+
+**omp cannot determine the repository.** Start omp in a git checkout with a GitHub remote, or include `owner/repo` in your request. Prefer a fully qualified reference such as `pr://acme/widgets/482` when several repositories are in play.
+
+**A PR or issue view looks stale.** Views may be served from the local cache. Recent writes through omp invalidate relevant cached views, but changes made elsewhere can remain fresh for up to the 5-minute soft TTL. Retry after refresh, lower `github.cache.softTtlSec`, or disable the cache when every read must hit GitHub.
+
+**PR checkout refuses an existing branch.** A local `pr-<number>` branch already points somewhere else. Ask omp to explain the mismatch before authorizing a forced reset; do not force it if the branch contains work you need.
+
+**Push is rejected.** Confirm that omp originally checked out this PR into its dedicated worktree, that your account can update the PR head branch, and that fork maintainer edits are allowed. Branch protection and required reviews still apply.
+
+**No Actions runs appear.** Make sure the commit has been pushed and that the requested repository and branch are correct. If you know the run, paste its full GitHub Actions URL instead of asking omp to infer it from the local `HEAD`.

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

@@ -0,0 +1,156 @@
+<!--
+source: https://omp.sh/docs/goal
+fetched: 2026-09-06
+-->
+
+# Goal mode
+
+> Give omp one durable objective and let it keep working across turns, with a token budget and controls for supervision.
+
+Goal mode is for work that is too large for one turn but has a clear finish line: a repository-wide migration, a sustained test-and-fix cycle, or a release checklist with several dependent steps. You state the objective once; omp keeps taking the next useful step until it verifies the work as complete, you pause or drop the goal, or its budget stops further work.
+
+Start with a bounded, testable objective:
+
+```text
+/goal Migrate the importer to streaming. Update every caller and user-facing documentation, preserve current error behavior, and finish only after the importer tests and typecheck pass.
+/goal budget 200000
+```
+
+The status line shows that goal mode is active, and omp continues after each productive turn instead of waiting for another prompt. Stay available for risky decisions, review the work as it develops, and use `/goal show` to check status and usage.
+
+> **A token budget is a safety boundary, not a definition of success.** When the budget is exhausted, the goal becomes `budget-limited` and omp wraps up what it knows. The objective is still unfinished unless goal mode explicitly reports completion.
+
+## Choose the right kind of task
+
+Goal mode works well when:
+
+- the desired end state and verification commands are known;
+- progress may require many edits, tool runs, or retries;
+- omp can make routine decisions without asking after every step; and
+- you can express safety boundaries up front.
+
+Use a normal prompt for a focused change that should fit in one turn. Use [Plan mode](/docs/plan) when you want to review an approach before any implementation. Do not leave a goal unattended for production changes, destructive operations, credential work, or ambiguous product decisions; require confirmation for those actions in the objective.
+
+A strong objective names the deliverables, evidence of completion, and prohibited shortcuts. For example:
+
+```text
+/goal Remove the legacy session API and migrate all callers. Keep the public behavior compatible, do not change the database schema, run the focused session tests and typecheck, and report any callers that cannot be migrated safely.
+```
+
+If the finish line is not yet clear, let omp interview you first:
+
+```text
+/guided-goal I need to make authentication safer before launch
+```
+
+`/guided-goal [rough objective]` asks clarifying questions in the normal chat, turns your answers into a concrete objective, and then starts goal mode. With plain `/goal`, omit the objective to open a multiline editor.
+
+## Supervise an active goal
+
+In the interactive TUI, an active goal automatically continues after a short idle pause. Typing a prompt, attaching an image, or interrupting gives you control before the next turn begins. You can steer the work with an ordinary message at any time:
+
+```text
+Before continuing, keep the existing wire format and add a regression test for malformed frames.
+```
+
+Use these commands to inspect and control the current session's goal:
+
+| Command | What it does |
+| --- | --- |
+| `/goal` | Opens the management menu for the active or paused goal. With no existing goal, opens the objective editor. |
+| `/goal show` | Shows the objective, status, tokens used and remaining, and active time. |
+| `/goal pause` | Stops automatic continuation but keeps the objective and accounting in the session. |
+| `/goal resume` | Resumes a paused goal and schedules its next continuation. |
+| `/goal budget <N>` | Sets a positive-integer total token budget. Existing usage is retained. |
+| `/goal budget off` | Removes the token cap. Existing usage is retained. |
+| `/goal set <objective>` | Starts a goal, or replaces an active goal with a new objective and fresh counters. A replacement also clears the old budget. |
+| `/goal drop` | Permanently stops the current goal after confirmation. There is no separate `/goal stop` command. |
+
+Press `Esc` to interrupt the current turn. An interrupted active goal is saved as paused, so inspect the partial work and run `/goal resume` only when it is safe to continue.
+
+A paused goal must be resumed before its budget can be changed. It also cannot be silently overwritten: resume it and use `/goal set …`, or drop it before starting a different objective.
+
+## Set and interpret a budget
+
+Goal mode has **no token cap by default**. For supervised work, set one soon after starting:
+
+```text
+/goal budget 100000
+```
+
+`N` is the total budget for the current goal, not an amount added to its remaining balance. Changing the budget preserves accumulated usage. The count includes input tokens, output tokens, and cache-write tokens; cache-read tokens are excluded. A turn can cross the exact boundary before accounting catches up, so treat the value as a guardrail rather than a precise hard stop or spending limit.
+
+When used tokens reach the cap:
+
+1. Status changes from `active` to `budget-limited`.
+2. omp sends one wrap-up turn asking for progress, remaining work, and blockers rather than starting more substantive work.
+3. Automatic continuation stops, but the goal remains attached to the session.
+
+Check the state before deciding what to do:
+
+```text
+/goal show
+```
+
+If the objective is still worth pursuing, set a new total greater than the displayed usage, or remove the cap:
+
+```text
+/goal budget 250000
+# or
+/goal budget off
+```
+
+That returns a budget-limited goal to active work. If you do not want more work, use `/goal pause` to preserve it for later or `/goal drop` to end it. Never interpret `budget-limited`, a wrap-up response, silence, or a provider error as completion.
+
+## What completion means
+
+Goal mode asks omp to complete only after checking every deliverable against the current repository state. On success, you see **Goal mode completed**, automatic continuation ends, and the completion record includes the objective and tracked usage in the session history.
+
+This is stronger than merely reaching the end of a turn, but it is not a substitute for your review. Read the final evidence, inspect important changes, and run any release or production checks that require human authority. If the final response lists remaining work or blockers, the task is not complete even if the response sounds conclusive.
+
+## Persistence and recovery
+
+The objective, status, budget, token usage, and active time are stored with the session as work proceeds. Compaction does not discard the goal. Switching away from and back to the same session in a running TUI preserves an active goal; reopening a persisted session from a cold start restores an active goal as **paused** so it cannot resume unattended. Use `/goal show`, review the working tree, then `/goal resume`.
+
+Explicitly paused goals remain available in the session until resumed or dropped. Dropping removes the live goal record, while accumulated usage remains in the session log. Completion clears the live mode and writes a completion record.
+
+Use this recovery checklist when work stops unexpectedly:
+
+| What you see | What to do |
+| --- | --- |
+| `paused` after `Esc`, an interrupted turn, or reopening the session | Inspect partial changes and logs, then run `/goal resume`. |
+| `budget-limited` | Run `/goal show`; raise the total above tokens used or use `/goal budget off`. |
+| `active`, but no automatic next turn | Submit or clear any draft/image waiting in the composer. If the previous continuation made no actionable progress, send a normal message such as “Continue the goal from the last verified step.” |
+| Repeated provider or command failure | Pause the goal, fix credentials/environment or refine the objective, then resume. Drop and restart only when you intentionally want fresh counters. |
+| “Exit plan mode first” or “Exit vibe mode first” | Finish or exit that mode; plan, vibe, and goal modes are mutually exclusive. |
+| “Goal mode is disabled” | Enable `goal.enabled`, then retry `/goal`. |
+
+Automatic continuation is currently an interactive-mode behavior. Loop mode also takes control of automatic submissions, so do not combine `/loop` with a goal when you expect goal-driven continuation.
+
+## Configuration
+
+No configuration is required: goal mode, its footer status, and interactive continuation are enabled by default. Change them in **Settings → Tasks → Modes** or in `~/.omp/agent/config.yml`:
+
+```yaml
+goal:
+  enabled: true
+  statusInFooter: true
+  continuationModes:
+    - interactive
+```
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `goal.enabled` | `true` | Allows `/goal` and `/guided-goal` to create per-session goals. |
+| `goal.statusInFooter` | `true` | Shows goal token usage alongside the goal indicator in the status line. |
+| `goal.continuationModes` | `["interactive"]` | Enables automatic between-turn continuation in the interactive TUI. Remove `interactive` to require manual prompts. |
+
+Verify the effective values from the shell:
+
+```bash
+omp config get goal.enabled
+omp config get goal.statusInFooter
+omp config get goal.continuationModes
+```
+
+See [Settings](/docs/settings) for file precedence and configuration commands, and [Slash commands](/docs/slash) for the complete command index.

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

@@ -0,0 +1,139 @@
+<!--
+source: https://omp.sh/docs/handoff
+fetched: 2026-09-06
+-->
+
+# Handoff
+
+> Turn a long working session into a focused continuation brief without leaving the session.
+
+Handoff gives omp a clean, task-oriented context when a conversation has accumulated too much history. It summarizes the work completed so far, the decisions that matter, and what should happen next, then compacts that summary into the **current session**.
+
+Run it when you want the next turn to continue from a deliberate checkpoint:
+
+```text
+/handoff
+```
+
+While omp prepares the handoff, the status line shows `Generating handoff… (esc to cancel)`. On success, the conversation is rebuilt around a `handed-off` divider and omp reports `Context handed off and compacted in place`.
+
+> Despite the name, `/handoff` does not create, fork, or switch to another session. Your session ID, name, branch, and saved session stay the same.
+
+## Handoff or compact?
+
+Both commands reduce the model's active context in place and retain a recent tail of the conversation. Choose based on what you want the replacement context to emphasize.
+
+| Choose | When you want | Outcome |
+| --- | --- | --- |
+| `/handoff` | A work-focused continuation brief: goal, progress, decisions, constraints, and next steps | omp generates that brief, uses it as the summary of older context, and marks the point as `handed-off` |
+| [`/compact`](/docs/compaction) | General context reduction, or control over the compaction method such as `soft`, `remote`, or `snapcompact` | omp uses the selected compaction method and marks the corresponding compaction point |
+| Neither | The current context is still useful and comfortably within the model's limit | Keep working; automatic context maintenance is enabled by default |
+
+Use `/handoff` before changing work phases, returning after a long pause, or preserving a precise implementation/debugging checkpoint. Use `/compact` when the priority is simply freeing context. If you actually want a separate session, use the session controls described in [Sessions](/docs/sessions).
+
+## Focus the continuation
+
+Add plain-language focus instructions after the command:
+
+```text
+/handoff Focus on the migration plan, decisions already made, and callers that still need updating.
+```
+
+The focus changes what the brief emphasizes; it does not become a new user task and does not create a new session. Without a focus, omp chooses the important continuation details from the conversation.
+
+Good focus instructions name the work that must survive the reduction:
+
+```text
+/handoff Preserve the test failure, hypotheses ruled out, and the next two debugging steps.
+```
+
+```text
+/handoff Emphasize the approved API shape and unresolved compatibility risk.
+```
+
+Wait for the current response to finish before running the command. If you need to stop that response, abort it first, then enter `/handoff`.
+
+## What changes on screen
+
+A successful handoff changes the context used for future model turns:
+
+- Older context is replaced by the generated handoff brief.
+- Recent messages remain verbatim. The retained amount is controlled by `compaction.keepRecentTokens`, which defaults to `20000`.
+- Todos and other live session UI are refreshed.
+- The same session continues; there is no resume or load step.
+
+By default, pre-handoff history is collapsed out of the live transcript and the recent tail appears after a divider similar to:
+
+```text
+──────── handed-off · 180K→24K · ctrl+o ────────
+```
+
+Press <kbd>Ctrl</kbd>+<kbd>O</kbd> to expand the divider and read the generated brief. Set `display.collapseCompacted: false` if you prefer to keep the full saved transcript inline around compaction dividers. Collapsing affects the display, not the persisted session history.
+
+Your next prompt can immediately continue the work:
+
+```text
+Continue with the first remaining migration caller.
+```
+
+## Cancel or recover from a failure
+
+Press <kbd>Esc</kbd> while `Generating handoff…` is visible to cancel. omp shows `Handoff cancelled`, leaves the current context unmodified, and keeps you in the same session.
+
+Other preconditions and errors are also non-destructive:
+
+| Message | Meaning and next action |
+| --- | --- |
+| `Wait for the current response to finish or abort it before handing off.` | Let the response finish, or abort it, then retry. |
+| `Nothing to hand off (no messages yet)` | There are fewer than two messages to summarize. Continue the conversation first. |
+| `Nothing to hand off (already compacted)` | No older context remains to replace. Continue working before trying again. |
+| `Compaction already in progress` | Wait for the active automatic or manual compaction to finish. |
+| `Handoff failed: No model selected for handoff` | Select a model, then retry. |
+| `Handoff failed: No API key for …` | Authenticate the active provider, then retry. |
+| `Handoff failed: …` | The provider or generation failed. The original context remains active; retry after resolving the reported error. |
+
+An empty generated brief is treated as a failure, not as a cancellation. omp automatically retries transient provider failures, but if the final attempt fails it displays the real error and does not commit a partial handoff.
+
+## Automatic handoff
+
+Manual `/handoff` always requests the handoff workflow; it does not depend on automatic compaction being enabled or on `compaction.methodOrder`.
+
+For automatic use, enable compaction and put `handoff` early in the ordered fallback list. The default order is:
+
+```text
+remote → snapcompact → handoff → shake → soft
+```
+
+That means another available method may run before handoff. If automatic handoff cannot run or fails, omp tries the next configured method. When the input has already overflowed the model's context, omp normally skips starting a new handoff request because the same oversized input could not be summarized; an already-prepared speculative handoff may still be applied.
+
+Open `/settings` and use **Context → Compaction**, or add a global or project override to `config.yml`:
+
+```yaml
+compaction:
+  enabled: true
+  methodOrder: [handoff, remote, snapcompact, shake, soft]
+  handoffSaveToDisk: true
+```
+
+`handoffSaveToDisk` adds a timestamped `handoff-*.md` file to the persisted session's artifact directory **only for automatic handoffs**. Manual `/handoff` stores the result as the session's compaction summary but does not write the extra Markdown file.
+
+## Relevant settings
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `compaction.enabled` | `true` | Enables automatic context maintenance. It does not disable manual `/handoff`. |
+| `compaction.methodOrder` | `[remote, snapcompact, handoff, shake, soft]` | Chooses and orders automatic maintenance methods. Put `handoff` first to prefer it. |
+| `compaction.keepRecentTokens` | `20000` | Approximate recent context retained verbatim after handoff or compaction. |
+| `compaction.thresholdPercent` | `-1` | Automatic-maintenance threshold as a percentage; `-1` uses the reserve-based default. |
+| `compaction.thresholdTokens` | `-1` | Fixed automatic-maintenance token limit; a non-default value overrides the percentage. |
+| `compaction.asyncEnabled` | `true` | May prepare an LLM-backed summary, including handoff, shortly before the threshold so it can be applied quickly. |
+| `compaction.handoffSaveToDisk` | `false` | Writes an extra Markdown artifact for automatic handoffs in persisted sessions only. |
+| `display.collapseCompacted` | `true` | Collapses replaced history in the live TUI; turn it off to keep the full transcript inline. |
+
+See [Settings](/docs/settings) for configuration locations, scopes, and precedence.
+
+## Related
+
+- [Compaction](/docs/compaction) — compaction methods, thresholds, and recovery behavior
+- [Sessions](/docs/sessions) — create, fork, resume, and switch sessions
+- [Plan mode](/docs/plan) — create an implementation plan before preserving the checkpoint