{"owner":"modem-dev","repo":"hunk","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# hunk agent notes\n\n## purpose\n\n- Terminal-first diff viewer for understanding coding-agent changesets.\n- Product target is \"modern desktop diff tool in a terminal\", not a pager-style TUI.\n\n## major dependencies\n\n- [Bun](https://bun.sh) runtime and package manager\n- [OpenTUI](https://github.com/anomalyco/opentui) React terminal UI framework\n- [Pierre](https://www.npmjs.com/package/@pierre/diffs) diff engine and terminal renderer\n\n## architecture\n\n```text\nCLI input\n  -> parse runtime + config-backed view options\n  -> normalize into one Changeset / DiffFile model\n  -> App shell coordinates state, layout, and review navigation\n  -> pane components render review UI\n  -> Pierre-backed terminal renderer draws diff rows\n```\n\n### shared review seam\n\nReview core serves multiple surfaces: TUI today; web, API, and agent/runtime consumers later. Do\nnot recreate semantic review behavior in a surface:\n\n```text\nDiffFile[] -> projectReviewDocument -> ReviewDocumentV1 -> ReviewStore\nReviewIntent + caller facts -> planReviewIntent -> ReviewAction[] -> reducer -> surface projection\n```\n\n- **Model:** `src/core/review/{types,document,identity}.ts` owns the ordered, JSON-safe document.\n  File order is review/sidebar order; use `key` (referenced as `fileKey` elsewhere),\n  `contentIdentity`, and `sourceIdentity` (cached source text additionally requires\n  `sourceAttested`) — not runtime IDs or indexes — across reloads/surfaces.\n- **Shared derivations:** `geometry.ts`, `expansion.ts`, `anchors.ts`, `stml.ts`, and\n  `contentManifest.ts` own ranges, gaps, source splitting, note targets/ownership, tag roles, and\n  parity manifests. Consume them; never re-derive those facts in a renderer.\n- **State:** `state.ts` is semantic state; `actions.ts` transitions; `reducer.ts` pure/no-I/O;\n  `selectors.ts` shared policies; `store.ts` synchronous observable storage. New cross-surface\n  operations start as intents. Callers supply mutable-note IDs/timestamps; core derives identities.\n- **Surfaces/publishers:** `useTerminalReview.ts` is the TUI adapter and\n  `reviewNoteMapping.ts` is terminal-only. Rows, measurement, scrolling, layout, themes, DOM\n  mechanics, and source I/O stay local. `useHunkSessionBridge.ts` publishes the current terminal\n  session export; `registration.ts` builds its metadata/initial snapshot and `bridge.ts` receives\n  agent commands. This broker export is not a full `ReviewState` mirror.\n- **Future consumers:** Web/API consumers reuse the model, derivations, state, intents, and then\n  the producer/protocol tier (see Phases 2–3 in `docs/browser-review-rebuild.md` for modules and\n  status). Never build a parallel protocol. Keep presentation/client-local state local;\n  host/extension commands need explicit remote capabilities.\n- **Conformance:** `test/review-conformance/` has hand-authored semantic fixtures and currently\n  covers core plus terminal render planning. Every new semantic consumer registers its real\n  projection and runs the whole corpus. `scripts/source-boundaries.test.ts` keeps the seam\n  renderer/platform-free; its Node-debt list is shrink-only and tombstone lists append-only. A\n  repaid seam finding deletes copies, adds a file or banned-symbol tombstone and adversarial\n  fixture, registers consumers, and updates `docs/browser-review-seam-audit.md`.\n\n- CLI entrypoints: `diff`, `show`, `stash show`, `patch`, `pager`, `difftool`.\n- All input sources normalize into one internal changeset model.\n- Bundled VCS implementations live under `src/extensions/default/vcs/<provider>/` and consume the\n  public extension contract; `src/app` composes their registrations into the provider-neutral\n  core VCS catalog. Do not add provider commands, spawning, or source readers under `src/core`.\n- Pager mode has two paths: full diff UI for patch-like stdin, plain-text fallback for non-diff pager content.\n- View defaults are layered through built-ins, user config, repo `.hunk/config.toml`, command sections, pager sections, and CLI flags.\n- `hunk daemon serve` runs one loopback daemon that brokers agent commands to many live Hunk sessions. Normal Hunk sessions should auto-start and register with that daemon when session brokering is enabled. Keep it local-only and session-brokered rather than opening per-TUI ports. The daemon also mirrors each session's current review publication (generation plus resource catalog) and reads bulky content — patch text, canonical files, source — back as bounded, digest-verified resource chunks instead of holding it in the registration. Order publications with `classifyReviewPublication` and assemble chunks with `ReviewChunkAssembler`; do not add a second acceptance rule or a second assembly loop. The same daemon serves each session's review over HTTP (`src/session/broker/browserReviewServer.ts`): loopback and same-origin only, no CORS, and every route authorized by a per-session capability the session mints and publishes only the digest of. That surface is transport and authorization — its routes, capability grammar, SSE event contract, and error messages are the browser-safe modules `src/session/review{HttpProtocol,EventProtocol,ErrorCatalog}.ts`, and its semantic answers come from the producer through the existing intent path.\n- Extensions come in two tiers — user TypeScript extensions and the bundled tier in `src/extensions/default/` — running through one per-extension API object and registry (`src/extensions/runExtension.ts`, resolved via `src/extensions/apply.ts`). Every shipped VCS backend and the built-in sidebar are bundled extensions registering through the public API; that dogfooding keeps `hunkdiff/extension` honest. Hard rules: `src/extension-api/types.ts` stays import-free (declaration emission publishes whatever it reaches; `scripts/check-pack.ts` gates it); `src/extensions/default/vcs/` loads from VCS adapter resolution and must stay renderer-free (the sidebar loads separately via `getBundledSidebarView`); repo-local `.hunk/extensions/` never executes without the trust prompt; bundled extensions stay loaded under `--no-extensions`. The full architecture — host-served runtime modules, sidebar pane model, command dispatch, VCS detection ordering, conversion boundaries — is mapped in `docs/extension-architecture.md` and documented in depth by the module headers it names; the authoring guide is `docs/extensions.md`, and `skills/hunk-extensions/SKILL.md` is the agent-facing map of those touchpoints.\n- Agent rationale is optional sidecar JSON matched onto files/hunks.\n- The order of `files` in the sidecar is intentional. Hunk uses that order for the sidebar and main review stream.\n- Prefer one source of truth for each user-visible behavior. When rendering, navigation, scrolling, or note placement share the same model, derive them from the same planning layer rather than maintaining parallel implementations.\n- When UI behavior depends on derived structure or metrics, make that structure explicit in helper modules and reuse it across rendering and interaction code instead of re-deriving it ad hoc in multiple places.\n- If a new implementation makes an older path obsolete, remove the dead path instead of keeping two overlapping systems around.\n\n## architectural rules\n\n- Keep the app review-first: the main pane is a single top-to-bottom stream of all visible file diffs.\n- The sidebar is for navigation. Selecting a file jumps to that file in the main review stream; it should not collapse the main pane to one file.\n- Keep Pierre as the diff engine and renderer foundation. Do not switch the main renderer back to OpenTUI's built-in `<diff>` widget.\n- Keep split and stack views terminal-native and driven from the same normalized diff model.\n- Preserve mouse + keyboard parity for primary actions.\n- Keep the chrome restrained: top menu bar, minimal borders, no redundant metadata headers.\n\n## component guidance\n\n- `App` should remain the orchestration shell for app state, navigation, layout mode, theme, filtering, and pane coordination.\n- Pane rendering should live in dedicated components.\n- Confirmation prompts with a small set of choices should reuse `ConfirmDialog` (body rows plus a clickable key-legend action row) instead of composing `ModalFrame` with a hand-rolled footer; keyboard handling for its actions stays in `useAppKeyboardShortcuts`.\n- New UI work should extend existing components or add new ones, not grow `App` back into a monolith.\n- Shared formatting, ids, and small derivations belong in helper modules, not repeated inline.\n- Prefer one implementation path per feature instead of separate \"old\" and \"new\" codepaths that duplicate behavior.\n- When refactoring logic that spans helpers and UI components, add tests at the level where the user-visible behavior actually lives, not only at the lowest helper layer.\n\n## theme guidance\n\n- Built-in themes live in `src/ui/themes/<theme-id>.ts`; register them in `src/ui/themes.ts` `THEMES` to control menu/cycle order.\n- When adding or renaming a built-in theme, update config validation, OpenTUI theme exports, docs/README examples, changelog, and tests that assert theme order.\n- Keep official palette tokens separate from Hunk's semantic `AppTheme` mapping, and cover non-trivial derived colors with tests.\n\n## testing\n\n- Colocate unit tests with the code they cover (`src/core/foo.ts` + `src/core/foo.test.ts`, `src/ui/AppHost.*.test.tsx`, `src/ui/lib/*.test.ts`).\n- Put shared unit-test helpers in `test/helpers/`.\n- Name test helpers so they explicitly include `Test` and are clearly test-only (`createTestDiffFile`).\n- Use repo-level `test/` directories by intent:\n  - `test/cli/` for black-box CLI contract coverage.\n  - `test/session/` for daemon/session integration and end-to-end flows.\n  - `test/pty/` for PTY-backed live UI integration tests.\n  - `test/review-conformance/` for the shared review model's golden fixtures and per-consumer conformance suites.\n  - `test/smoke/` for opt-in terminal transcript smoke coverage.\n\n## code comments\n\n- Add short JSDoc-style comments to functions and helpers.\n- Write header comments in active voice: the first sentence says what the module or function\n  does (\"Applies one action to the review state and returns the next state.\"), followed by its\n  invariants. Avoid passive or self-important framing (\"The one place where…\", \"the single\n  source of truth for…\") — name the behavior, not the architecture's opinion of itself.\n- Add inline comments for intent, invariants, or tricky behavior that would not be obvious to a fresh reader.\n- Skip comments that only narrate what the code already says.\n\n## naming\n\n- Prefer names that match the role the code plays in the product and architecture.\n- Use `layout` for structural placement or arrangement data.\n- Use `geometry` for aggregate spatial data used by rendering, scrolling, or interaction.\n- Use `bounds` for one concrete visible extent within a larger structure.\n\n## review behavior\n\n- Default behavior is a multi-file review stream in sidebar order.\n- Layout modes: `auto`, `split`, `stack`.\n- `auto` should choose split on wide terminals and stack on narrow ones.\n- Explicit `split` and `stack` choices override responsive `auto` layout selection.\n- `[` and `]` navigate hunks across the full review stream. Do not reintroduce `j`/`k` hunk navigation unless the user asks.\n- Agent context belongs beside the code, not hidden in a separate mode or workflow.\n- Agent notes are hunk-specific: show notes for the selected hunk, render them in the diff flow near the annotated row, and keep a clear spatial relationship to the code they explain.\n- Keep note behavior explicit. If the UI intentionally prioritizes one note, one selection, or one active target, encode that as a named policy rather than scattering array-index assumptions through the codebase.\n- STML markup notes (experimental) live in `src/ui/lib/stml/`. The layout engine is deliberately a deterministic line layout, not OpenTUI flexbox: the row-windowed review stream needs exact note heights before mount, so `(markup, width)` must always produce the same lines. Colors stay symbolic until render time so measurement never needs a theme. Do not \"simplify\" this into flexbox renderables, and keep note-card geometry in `agentNoteGeometry` as the single source for rendering, measurement, and agent-facing width reporting.\n- If you choose to use a local sidecar for temporary review context, keep it concise and review-oriented: one changeset summary, file summaries in narrative order, and a few hunk-level annotations with real rationale.\n- If a local sidecar is present, its file order is intentional, but the visible note UI should stay hunk-note driven rather than showing generic file or changeset explainer cards.\n- `hunk diff` working-tree reviews include untracked files by default. Use `--exclude-untracked` if you explicitly want tracked changes only.\n- Agents review via `skills/hunk-review/SKILL.md` using `hunk session *` commands; do not run interactive TUI commands directly.\n- `skills/hunk-review/SKILL.md` is generated. Edit `src/hunk-review/skillDocument.ts`, `src/session/agent/surface.ts`, or `src/session/agent/errors.ts`, then run `bun run generate:skill`; never hand-edit the skill file.\n\n## commands\n\n- install deps: `bun install`\n- run from source: `bun run src/main.tsx -- diff`\n- review a commit from source: `bun run src/main.tsx -- show HEAD~1`\n- fast smoke test: `bun run src/main.tsx -- diff /tmp/before.ts /tmp/after.ts`\n- typecheck: `bun run typecheck`\n- tests: `bun test`\n- PTY integration tests: `bun run test:integration`\n- TTY smoke test: `bun run test:tty-smoke`\n- format: `bun run format`\n- lint: `bun run lint`\n- build binary: `bun run build:bin`\n- install binary: `bun run install:bin`\n\n## binary notes\n\n- Installed `hunk` is a compiled snapshot, not linked to source.\n- After source changes, rebuild/reinstall with `bun run install:bin`.\n- For rendering verification, prefer a real TTY smoke run over redirected stdout capture.\n\n## verification\n\n- For rendering changes: run `bun run typecheck`, `bun test`, `bun run test:integration`, `bun run test:tty-smoke`, and do one real TTY smoke run on an actual diff.\n- For interaction, layout, scrolling, navigation, windowing, or other terminal-native behavior: add or update PTY integration coverage in `test/pty/*-integration.test.ts` and run it with `bun run test:integration`.\n- For CLI, config, or pager work: make sure the relevant source invocation still works (`diff`, `show`, `patch`, or `pager`).\n- Preserve current interaction model unless the user asks to change it explicitly.\n\n## cross-platform support\n\n- Hunk should work on macOS, Linux, and Windows. Keep tests and CI portable unless a case is explicitly Unix-only (PTY/TTY smoke coverage is Unix-only).\n- In tests, avoid hard-coded POSIX paths, separators, shell syntax, and filenames invalid on Windows; use Node path helpers for real filesystem paths while preserving user-provided/protocol paths when pass-through is intentional.\n- If Windows-only Bun behavior appears around timers, sockets, or line endings, prefer a small compatibility fix or a narrowly scoped skip with a comment over broadening Unix assumptions.\n\n## releases\n\n- Use Changesets for user-visible release notes. Add a `.changeset/*.md` entry with `bun run changeset` instead of editing `CHANGELOG.md` directly.\n- Target the public `hunkdiff` package in changesets. Use `patch` for fixes and small behavior changes, `minor` for new user-facing features, and `major` for breaking changes.\n- For maintenance-only PRs that should not appear in release notes, add an empty changeset with `bun run changeset -- --empty`.\n- Keep the top-level `CHANGELOG.md` as the released changelog artifact. It is updated during release prep with `bun run release:version`, not by normal feature/fix PRs.\n- Use the released changelog section as the starting point for the GitHub release body.\n- GitHub releases should follow this format:\n\n  ```md\n  ## What's Changed\n\n  - <change title> by @<author> in <PR URL>\n  - ...\n\n  **Full Changelog**: https://github.com/modem-dev/hunk/compare/<previous-tag>...<new-tag>\n  ```\n\n- Do not rely blindly on autogenerated GitHub release notes. After publishing, verify the release body and edit it if needed.\n- Prefer `gh release create/edit --notes-file` for multi-line release notes so the exact body is reviewed before posting.\n- After publishing, verify npm packages and GitHub release assets point at the new version. For Homebrew, Hunk is distributed through `Homebrew/homebrew-core`; do not open manual simple version-bump PRs yourself. Let Homebrew Autobump create the `hunk <version>` PR, then verify it merges and `brew install hunk` resolves to the new version. Only use `brew bump-formula-pr hunk --version <version>` if Homebrew maintainers request a manual bump or Autobump stalls unexpectedly.\n- For mise, verify with `MISE_AQUA_BAKED_REGISTRY=false mise latest hunk`. mise resolves Hunk through the community `aqua:modem-dev/hunk` entry, bakes an aqua registry snapshot into each of its own releases (`aqua.baked_registry`, default true), and caches downloaded registry sources for a week (`aqua.registry_cache_ttl`), so a default check can report stale registry data unrelated to our release; `mise cache clear` forces a refresh.\n- For patch releases and backports, list only changes actually present between the previous tag and the new tag on that release branch.\n- Prefer concise, user-visible entries over internal refactors unless the refactor changes user-visible behavior.\n- Keep each changeset summary to one concise user-facing sentence; put implementation detail in the PR or supporting docs.\n\n## repo notes\n\n- Local review artifacts are ignored on purpose. Leave them alone unless the user explicitly wants them updated, and do not commit them.\n- Keep this doc short and architectural. Fresh-context agents can discover file paths themselves.\n\n## commits\n\nCommit titles should follow Conventional Commits. Format: `<type>[scope]: <description>`. Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `build`. Use `!` or `BREAKING CHANGE:` footer for breaking changes. Description should explain the \"why\", not just the \"what\".\n"},"files":{"AGENTS.md":"# hunk agent notes\n\n## purpose\n\n- Terminal-first diff viewer for understanding coding-agent changesets.\n- Product target is \"modern desktop diff tool in a terminal\", not a pager-style TUI.\n\n## major dependencies\n\n- [Bun](https://bun.sh) runtime and package manager\n- [OpenTUI](https://github.com/anomalyco/opentui) React terminal UI framework\n- [Pierre](https://www.npmjs.com/package/@pierre/diffs) diff engine and terminal renderer\n\n## architecture\n\n```text\nCLI input\n  -> parse runtime + config-backed view options\n  -> normalize into one Changeset / DiffFile model\n  -> App shell coordinates state, layout, and review navigation\n  -> pane components render review UI\n  -> Pierre-backed terminal renderer draws diff rows\n```\n\n### shared review seam\n\nReview core serves multiple surfaces: TUI today; web, API, and agent/runtime consumers later. Do\nnot recreate semantic review behavior in a surface:\n\n```text\nDiffFile[] -> projectReviewDocument -> ReviewDocumentV1 -> ReviewStore\nReviewIntent + caller facts -> planReviewIntent -> ReviewAction[] -> reducer -> surface projection\n```\n\n- **Model:** `src/core/review/{types,document,identity}.ts` owns the ordered, JSON-safe document.\n  File order is review/sidebar order; use `key` (referenced as `fileKey` elsewhere),\n  `contentIdentity`, and `sourceIdentity` (cached source text additionally requires\n  `sourceAttested`) — not runtime IDs or indexes — across reloads/surfaces.\n- **Shared derivations:** `geometry.ts`, `expansion.ts`, `anchors.ts`, `stml.ts`, and\n  `contentManifest.ts` own ranges, gaps, source splitting, note targets/ownership, tag roles, and\n  parity manifests. Consume them; never re-derive those facts in a renderer.\n- **State:** `state.ts` is semantic state; `actions.ts` transitions; `reducer.ts` pure/no-I/O;\n  `selectors.ts` shared policies; `store.ts` synchronous observable storage. New cross-surface\n  operations start as intents. Callers supply mutable-note IDs/timestamps; core derives identities.\n- **Surfaces/publishers:** `useTerminalReview.ts` is the TUI adapter and\n  `reviewNoteMapping.ts` is terminal-only. Rows, measurement, scrolling, layout, themes, DOM\n  mechanics, and source I/O stay local. `useHunkSessionBridge.ts` publishes the current terminal\n  session export; `registration.ts` builds its metadata/initial snapshot and `bridge.ts` receives\n  agent commands. This broker export is not a full `ReviewState` mirror.\n- **Future consumers:** Web/API consumers reuse the model, derivations, state, intents, and then\n  the producer/protocol tier (see Phases 2–3 in `docs/browser-review-rebuild.md` for modules and\n  status). Never build a parallel protocol. Keep presentation/client-local state local;\n  host/extension commands need explicit remote capabilities.\n- **Conformance:** `test/review-conformance/` has hand-authored semantic fixtures and currently\n  covers core plus terminal render planning. Every new semantic consumer registers its real\n  projection and runs the whole corpus. `scripts/source-boundaries.test.ts` keeps the seam\n  renderer/platform-free; its Node-debt list is shrink-only and tombstone lists append-only. A\n  repaid seam finding deletes copies, adds a file or banned-symbol tombstone and adversarial\n  fixture, registers consumers, and updates `docs/browser-review-seam-audit.md`.\n\n- CLI entrypoints: `diff`, `show`, `stash show`, `patch`, `pager`, `difftool`.\n- All input sources normalize into one internal changeset model.\n- Bundled VCS implementations live under `src/extensions/default/vcs/<provider>/` and consume the\n  public extension contract; `src/app` composes their registrations into the provider-neutral\n  core VCS catalog. Do not add provider commands, spawning, or source readers under `src/core`.\n- Pager mode has two paths: full diff UI for patch-like stdin, plain-text fallback for non-diff pager content.\n- View defaults are layered through built-ins, user config, repo `.hunk/config.toml`, command sections, pager sections, and CLI flags.\n- `hunk daemon serve` runs one loopback daemon that brokers agent commands to many live Hunk sessions. Normal Hunk sessions should auto-start and register with that daemon when session brokering is enabled. Keep it local-only and session-brokered rather than opening per-TUI ports. The daemon also mirrors each session's current review publication (generation plus resource catalog) and reads bulky content — patch text, canonical files, source — back as bounded, digest-verified resource chunks instead of holding it in the registration. Order publications with `classifyReviewPublication` and assemble chunks with `ReviewChunkAssembler`; do not add a second acceptance rule or a second assembly loop. The same daemon serves each session's review over HTTP (`src/session/broker/browserReviewServer.ts`): loopback and same-origin only, no CORS, and every route authorized by a per-session capability the session mints and publishes only the digest of. That surface is transport and authorization — its routes, capability grammar, SSE event contract, and error messages are the browser-safe modules `src/session/review{HttpProtocol,EventProtocol,ErrorCatalog}.ts`, and its semantic answers come from the producer through the existing intent path.\n- Extensions come in two tiers — user TypeScript extensions and the bundled tier in `src/extensions/default/` — running through one per-extension API object and registry (`src/extensions/runExtension.ts`, resolved via `src/extensions/apply.ts`). Every shipped VCS backend and the built-in sidebar are bundled extensions registering through the public API; that dogfooding keeps `hunkdiff/extension` honest. Hard rules: `src/extension-api/types.ts` stays import-free (declaration emission publishes whatever it reaches; `scripts/check-pack.ts` gates it); `src/extensions/default/vcs/` loads from VCS adapter resolution and must stay renderer-free (the sidebar loads separately via `getBundledSidebarView`); repo-local `.hunk/extensions/` never executes without the trust prompt; bundled extensions stay loaded under `--no-extensions`. The full architecture — host-served runtime modules, sidebar pane model, command dispatch, VCS detection ordering, conversion boundaries — is mapped in `docs/extension-architecture.md` and documented in depth by the module headers it names; the authoring guide is `docs/extensions.md`, and `skills/hunk-extensions/SKILL.md` is the agent-facing map of those touchpoints.\n- Agent rationale is optional sidecar JSON matched onto files/hunks.\n- The order of `files` in the sidecar is intentional. Hunk uses that order for the sidebar and main review stream.\n- Prefer one source of truth for each user-visible behavior. When rendering, navigation, scrolling, or note placement share the same model, derive them from the same planning layer rather than maintaining parallel implementations.\n- When UI behavior depends on derived structure or metrics, make that structure explicit in helper modules and reuse it across rendering and interaction code instead of re-deriving it ad hoc in multiple places.\n- If a new implementation makes an older path obsolete, remove the dead path instead of keeping two overlapping systems around.\n\n## architectural rules\n\n- Keep the app review-first: the main pane is a single top-to-bottom stream of all visible file diffs.\n- The sidebar is for navigation. Selecting a file jumps to that file in the main review stream; it should not collapse the main pane to one file.\n- Keep Pierre as the diff engine and renderer foundation. Do not switch the main renderer back to OpenTUI's built-in `<diff>` widget.\n- Keep split and stack views terminal-native and driven from the same normalized diff model.\n- Preserve mouse + keyboard parity for primary actions.\n- Keep the chrome restrained: top menu bar, minimal borders, no redundant metadata headers.\n\n## component guidance\n\n- `App` should remain the orchestration shell for app state, navigation, layout mode, theme, filtering, and pane coordination.\n- Pane rendering should live in dedicated components.\n- Confirmation prompts with a small set of choices should reuse `ConfirmDialog` (body rows plus a clickable key-legend action row) instead of composing `ModalFrame` with a hand-rolled footer; keyboard handling for its actions stays in `useAppKeyboardShortcuts`.\n- New UI work should extend existing components or add new ones, not grow `App` back into a monolith.\n- Shared formatting, ids, and small derivations belong in helper modules, not repeated inline.\n- Prefer one implementation path per feature instead of separate \"old\" and \"new\" codepaths that duplicate behavior.\n- When refactoring logic that spans helpers and UI components, add tests at the level where the user-visible behavior actually lives, not only at the lowest helper layer.\n\n## theme guidance\n\n- Built-in themes live in `src/ui/themes/<theme-id>.ts`; register them in `src/ui/themes.ts` `THEMES` to control menu/cycle order.\n- When adding or renaming a built-in theme, update config validation, OpenTUI theme exports, docs/README examples, changelog, and tests that assert theme order.\n- Keep official palette tokens separate from Hunk's semantic `AppTheme` mapping, and cover non-trivial derived colors with tests.\n\n## testing\n\n- Colocate unit tests with the code they cover (`src/core/foo.ts` + `src/core/foo.test.ts`, `src/ui/AppHost.*.test.tsx`, `src/ui/lib/*.test.ts`).\n- Put shared unit-test helpers in `test/helpers/`.\n- Name test helpers so they explicitly include `Test` and are clearly test-only (`createTestDiffFile`).\n- Use repo-level `test/` directories by intent:\n  - `test/cli/` for black-box CLI contract coverage.\n  - `test/session/` for daemon/session integration and end-to-end flows.\n  - `test/pty/` for PTY-backed live UI integration tests.\n  - `test/review-conformance/` for the shared review model's golden fixtures and per-consumer conformance suites.\n  - `test/smoke/` for opt-in terminal transcript smoke coverage.\n\n## code comments\n\n- Add short JSDoc-style comments to functions and helpers.\n- Write header comments in active voice: the first sentence says what the module or function\n  does (\"Applies one action to the review state and returns the next state.\"), followed by its\n  invariants. Avoid passive or self-important framing (\"The one place where…\", \"the single\n  source of truth for…\") — name the behavior, not the architecture's opinion of itself.\n- Add inline comments for intent, invariants, or tricky behavior that would not be obvious to a fresh reader.\n- Skip comments that only narrate what the code already says.\n\n## naming\n\n- Prefer names that match the role the code plays in the product and architecture.\n- Use `layout` for structural placement or arrangement data.\n- Use `geometry` for aggregate spatial data used by rendering, scrolling, or interaction.\n- Use `bounds` for one concrete visible extent within a larger structure.\n\n## review behavior\n\n- Default behavior is a multi-file review stream in sidebar order.\n- Layout modes: `auto`, `split`, `stack`.\n- `auto` should choose split on wide terminals and stack on narrow ones.\n- Explicit `split` and `stack` choices override responsive `auto` layout selection.\n- `[` and `]` navigate hunks across the full review stream. Do not reintroduce `j`/`k` hunk navigation unless the user asks.\n- Agent context belongs beside the code, not hidden in a separate mode or workflow.\n- Agent notes are hunk-specific: show notes for the selected hunk, render them in the diff flow near the annotated row, and keep a clear spatial relationship to the code they explain.\n- Keep note behavior explicit. If the UI intentionally prioritizes one note, one selection, or one active target, encode that as a named policy rather than scattering array-index assumptions through the codebase.\n- STML markup notes (experimental) live in `src/ui/lib/stml/`. The layout engine is deliberately a deterministic line layout, not OpenTUI flexbox: the row-windowed review stream needs exact note heights before mount, so `(markup, width)` must always produce the same lines. Colors stay symbolic until render time so measurement never needs a theme. Do not \"simplify\" this into flexbox renderables, and keep note-card geometry in `agentNoteGeometry` as the single source for rendering, measurement, and agent-facing width reporting.\n- If you choose to use a local sidecar for temporary review context, keep it concise and review-oriented: one changeset summary, file summaries in narrative order, and a few hunk-level annotations with real rationale.\n- If a local sidecar is present, its file order is intentional, but the visible note UI should stay hunk-note driven rather than showing generic file or changeset explainer cards.\n- `hunk diff` working-tree reviews include untracked files by default. Use `--exclude-untracked` if you explicitly want tracked changes only.\n- Agents review via `skills/hunk-review/SKILL.md` using `hunk session *` commands; do not run interactive TUI commands directly.\n- `skills/hunk-review/SKILL.md` is generated. Edit `src/hunk-review/skillDocument.ts`, `src/session/agent/surface.ts`, or `src/session/agent/errors.ts`, then run `bun run generate:skill`; never hand-edit the skill file.\n\n## commands\n\n- install deps: `bun install`\n- run from source: `bun run src/main.tsx -- diff`\n- review a commit from source: `bun run src/main.tsx -- show HEAD~1`\n- fast smoke test: `bun run src/main.tsx -- diff /tmp/before.ts /tmp/after.ts`\n- typecheck: `bun run typecheck`\n- tests: `bun test`\n- PTY integration tests: `bun run test:integration`\n- TTY smoke test: `bun run test:tty-smoke`\n- format: `bun run format`\n- lint: `bun run lint`\n- build binary: `bun run build:bin`\n- install binary: `bun run install:bin`\n\n## binary notes\n\n- Installed `hunk` is a compiled snapshot, not linked to source.\n- After source changes, rebuild/reinstall with `bun run install:bin`.\n- For rendering verification, prefer a real TTY smoke run over redirected stdout capture.\n\n## verification\n\n- For rendering changes: run `bun run typecheck`, `bun test`, `bun run test:integration`, `bun run test:tty-smoke`, and do one real TTY smoke run on an actual diff.\n- For interaction, layout, scrolling, navigation, windowing, or other terminal-native behavior: add or update PTY integration coverage in `test/pty/*-integration.test.ts` and run it with `bun run test:integration`.\n- For CLI, config, or pager work: make sure the relevant source invocation still works (`diff`, `show`, `patch`, or `pager`).\n- Preserve current interaction model unless the user asks to change it explicitly.\n\n## cross-platform support\n\n- Hunk should work on macOS, Linux, and Windows. Keep tests and CI portable unless a case is explicitly Unix-only (PTY/TTY smoke coverage is Unix-only).\n- In tests, avoid hard-coded POSIX paths, separators, shell syntax, and filenames invalid on Windows; use Node path helpers for real filesystem paths while preserving user-provided/protocol paths when pass-through is intentional.\n- If Windows-only Bun behavior appears around timers, sockets, or line endings, prefer a small compatibility fix or a narrowly scoped skip with a comment over broadening Unix assumptions.\n\n## releases\n\n- Use Changesets for user-visible release notes. Add a `.changeset/*.md` entry with `bun run changeset` instead of editing `CHANGELOG.md` directly.\n- Target the public `hunkdiff` package in changesets. Use `patch` for fixes and small behavior changes, `minor` for new user-facing features, and `major` for breaking changes.\n- For maintenance-only PRs that should not appear in release notes, add an empty changeset with `bun run changeset -- --empty`.\n- Keep the top-level `CHANGELOG.md` as the released changelog artifact. It is updated during release prep with `bun run release:version`, not by normal feature/fix PRs.\n- Use the released changelog section as the starting point for the GitHub release body.\n- GitHub releases should follow this format:\n\n  ```md\n  ## What's Changed\n\n  - <change title> by @<author> in <PR URL>\n  - ...\n\n  **Full Changelog**: https://github.com/modem-dev/hunk/compare/<previous-tag>...<new-tag>\n  ```\n\n- Do not rely blindly on autogenerated GitHub release notes. After publishing, verify the release body and edit it if needed.\n- Prefer `gh release create/edit --notes-file` for multi-line release notes so the exact body is reviewed before posting.\n- After publishing, verify npm packages and GitHub release assets point at the new version. For Homebrew, Hunk is distributed through `Homebrew/homebrew-core`; do not open manual simple version-bump PRs yourself. Let Homebrew Autobump create the `hunk <version>` PR, then verify it merges and `brew install hunk` resolves to the new version. Only use `brew bump-formula-pr hunk --version <version>` if Homebrew maintainers request a manual bump or Autobump stalls unexpectedly.\n- For mise, verify with `MISE_AQUA_BAKED_REGISTRY=false mise latest hunk`. mise resolves Hunk through the community `aqua:modem-dev/hunk` entry, bakes an aqua registry snapshot into each of its own releases (`aqua.baked_registry`, default true), and caches downloaded registry sources for a week (`aqua.registry_cache_ttl`), so a default check can report stale registry data unrelated to our release; `mise cache clear` forces a refresh.\n- For patch releases and backports, list only changes actually present between the previous tag and the new tag on that release branch.\n- Prefer concise, user-visible entries over internal refactors unless the refactor changes user-visible behavior.\n- Keep each changeset summary to one concise user-facing sentence; put implementation detail in the PR or supporting docs.\n\n## repo notes\n\n- Local review artifacts are ignored on purpose. Leave them alone unless the user explicitly wants them updated, and do not commit them.\n- Keep this doc short and architectural. Fresh-context agents can discover file paths themselves.\n\n## commits\n\nCommit titles should follow Conventional Commits. Format: `<type>[scope]: <description>`. Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `build`. Use `!` or `BREAKING CHANGE:` footer for breaking changes. Description should explain the \"why\", not just the \"what\".\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# hunk agent notes\n\n## purpose\n\n- Terminal-first diff viewer for understanding coding-agent changesets.\n- Product target is \"modern desktop diff tool in a terminal\", not a pager-style TUI.\n\n## major dependencies\n\n- [Bun](https://bun.sh) runtime and package manager\n- [OpenTUI](https://github.com/anomalyco/opentui) React terminal UI framework\n- [Pierre](https://www.npmjs.com/package/@pierre/diffs) diff engine and terminal renderer\n\n## architecture\n\n```text\nCLI input\n  -> parse runtime + config-backed view options\n  -> normalize into one Changeset / DiffFile model\n  -> App shell coordinates state, layout, and review navigation\n  -> pane components render review UI\n  -> Pierre-backed terminal renderer draws diff rows\n```\n\n### shared review seam\n\nReview core serves multiple surfaces: TUI today; web, API, and agent/runtime consumers later. Do\nnot recreate semantic review behavior in a surface:\n\n```text\nDiffFile[] -> projectReviewDocument -> ReviewDocumentV1 -> ReviewStore\nReviewIntent + caller facts -> planReviewIntent -> ReviewAction[] -> reducer -> surface projection\n```\n\n- **Model:** `src/core/review/{types,document,identity}.ts` owns the ordered, JSON-safe document.\n  File order is review/sidebar order; use `key` (referenced as `fileKey` elsewhere),\n  `contentIdentity`, and `sourceIdentity` (cached source text additionally requires\n  `sourceAttested`) — not runtime IDs or indexes — across reloads/surfaces.\n- **Shared derivations:** `geometry.ts`, `expansion.ts`, `anchors.ts`, `stml.ts`, and\n  `contentManifest.ts` own ranges, gaps, source splitting, note targets/ownership, tag roles, and\n  parity manifests. Consume them; never re-derive those facts in a renderer.\n- **State:** `state.ts` is semantic state; `actions.ts` transitions; `reducer.ts` pure/no-I/O;\n  `selectors.ts` shared policies; `store.ts` synchronous observable storage. New cross-surface\n  operations start as intents. Callers supply mutable-note IDs/timestamps; core derives identities.\n- **Surfaces/publishers:** `useTerminalReview.ts` is the TUI adapter and\n  `reviewNoteMapping.ts` is terminal-only. Rows, measurement, scrolling, layout, themes, DOM\n  mechanics, and source I/O stay local. `useHunkSessionBridge.ts` publishes the current terminal\n  session export; `registration.ts` builds its metadata/initial snapshot and `bridge.ts` receives\n  agent commands. This broker export is not a full `ReviewState` mirror.\n- **Future consumers:** Web/API consumers reuse the model, derivations, state, intents, and then\n  the producer/protocol tier (see Phases 2–3 in `docs/browser-review-rebuild.md` for modules and\n  status). Never build a parallel protocol. Keep presentation/client-local state local;\n  host/extension commands need explicit remote capabilities.\n- **Conformance:** `test/review-conformance/` has hand-authored semantic fixtures and currently\n  covers core plus terminal render planning. Every new semantic consumer registers its real\n  projection and runs the whole corpus. `scripts/source-boundaries.test.ts` keeps the seam\n  renderer/platform-free; its Node-debt list is shrink-only and tombstone lists append-only. A\n  repaid seam finding deletes copies, adds a file or banned-symbol tombstone and adversarial\n  fixture, registers consumers, and updates `docs/browser-review-seam-audit.md`.\n\n- CLI entrypoints: `diff`, `show`, `stash show`, `patch`, `pager`, `difftool`.\n- All input sources normalize into one internal changeset model.\n- Bundled VCS implementations live under `src/extensions/default/vcs/<provider>/` and consume the\n  public extension contract; `src/app` composes their registrations into the provider-neutral\n  core VCS catalog. Do not add provider commands, spawning, or source readers under `src/core`.\n- Pager mode has two paths: full diff UI for patch-like stdin, plain-text fallback for non-diff pager content.\n- View defaults are layered through built-ins, user config, repo `.hunk/config.toml`, command sections, pager sections, and CLI flags.\n- `hunk daemon serve` runs one loopback daemon that brokers agent commands to many live Hunk sessions. Normal Hunk sessions should auto-start and register with that daemon when session brokering is enabled. Keep it local-only and session-brokered rather than opening per-TUI ports. The daemon also mirrors each session's current review publication (generation plus resource catalog) and reads bulky content — patch text, canonical files, source — back as bounded, digest-verified resource chunks instead of holding it in the registration. Order publications with `classifyReviewPublication` and assemble chunks with `ReviewChunkAssembler`; do not add a second acceptance rule or a second assembly loop. The same daemon serves each session's review over HTTP (`src/session/broker/browserReviewServer.ts`): loopback and same-origin only, no CORS, and every route authorized by a per-session capability the session mints and publishes only the digest of. That surface is transport and authorization — its routes, capability grammar, SSE event contract, and error messages are the browser-safe modules `src/session/review{HttpProtocol,EventProtocol,ErrorCatalog}.ts`, and its semantic answers come from the producer through the existing intent path.\n- Extensions come in two tiers — user TypeScript extensions and the bundled tier in `src/extensions/default/` — running through one per-extension API object and registry (`src/extensions/runExtension.ts`, resolved via `src/extensions/apply.ts`). Every shipped VCS backend and the built-in sidebar are bundled extensions registering through the public API; that dogfooding keeps `hunkdiff/extension` honest. Hard rules: `src/extension-api/types.ts` stays import-free (declaration emission publishes whatever it reaches; `scripts/check-pack.ts` gates it); `src/extensions/default/vcs/` loads from VCS adapter resolution and must stay renderer-free (the sidebar loads separately via `getBundledSidebarView`); repo-local `.hunk/extensions/` never executes without the trust prompt; bundled extensions stay loaded under `--no-extensions`. The full architecture — host-served runtime modules, sidebar pane model, command dispatch, VCS detection ordering, conversion boundaries — is mapped in `docs/extension-architecture.md` and documented in depth by the module headers it names; the authoring guide is `docs/extensions.md`, and `skills/hunk-extensions/SKILL.md` is the agent-facing map of those touchpoints.\n- Agent rationale is optional sidecar JSON matched onto files/hunks.\n- The order of `files` in the sidecar is intentional. Hunk uses that order for the sidebar and main review stream.\n- Prefer one source of truth for each user-visible behavior. When rendering, navigation, scrolling, or note placement share the same model, derive them from the same planning layer rather than maintaining parallel implementations.\n- When UI behavior depends on derived structure or metrics, make that structure explicit in helper modules and reuse it across rendering and interaction code instead of re-deriving it ad hoc in multiple places.\n- If a new implementation makes an older path obsolete, remove the dead path instead of keeping two overlapping systems around.\n\n## architectural rules\n\n- Keep the app review-first: the main pane is a single top-to-bottom stream of all visible file diffs.\n- The sidebar is for navigation. Selecting a file jumps to that file in the main review stream; it should not collapse the main pane to one file.\n- Keep Pierre as the diff engine and renderer foundation. Do not switch the main renderer back to OpenTUI's built-in `<diff>` widget.\n- Keep split and stack views terminal-native and driven from the same normalized diff model.\n- Preserve mouse + keyboard parity for primary actions.\n- Keep the chrome restrained: top menu bar, minimal borders, no redundant metadata headers.\n\n## component guidance\n\n- `App` should remain the orchestration shell for app state, navigation, layout mode, theme, filtering, and pane coordination.\n- Pane rendering should live in dedicated components.\n- Confirmation prompts with a small set of choices should reuse `ConfirmDialog` (body rows plus a clickable key-legend action row) instead of composing `ModalFrame` with a hand-rolled footer; keyboard handling for its actions stays in `useAppKeyboardShortcuts`.\n- New UI work should extend existing components or add new ones, not grow `App` back into a monolith.\n- Shared formatting, ids, and small derivations belong in helper modules, not repeated inline.\n- Prefer one implementation path per feature instead of separate \"old\" and \"new\" codepaths that duplicate behavior.\n- When refactoring logic that spans helpers and UI components, add tests at the level where the user-visible behavior actually lives, not only at the lowest helper layer.\n\n## theme guidance\n\n- Built-in themes live in `src/ui/themes/<theme-id>.ts`; register them in `src/ui/themes.ts` `THEMES` to control menu/cycle order.\n- When adding or renaming a built-in theme, update config validation, OpenTUI theme exports, docs/README examples, changelog, and tests that assert theme order.\n- Keep official palette tokens separate from Hunk's semantic `AppTheme` mapping, and cover non-trivial derived colors with tests.\n\n## testing\n\n- Colocate unit tests with the code they cover (`src/core/foo.ts` + `src/core/foo.test.ts`, `src/ui/AppHost.*.test.tsx`, `src/ui/lib/*.test.ts`).\n- Put shared unit-test helpers in `test/helpers/`.\n- Name test helpers so they explicitly include `Test` and are clearly test-only (`createTestDiffFile`).\n- Use repo-level `test/` directories by intent:\n  - `test/cli/` for black-box CLI contract coverage.\n  - `test/session/` for daemon/session integration and end-to-end flows.\n  - `test/pty/` for PTY-backed live UI integration tests.\n  - `test/review-conformance/` for the shared review model's golden fixtures and per-consumer conformance suites.\n  - `test/smoke/` for opt-in terminal transcript smoke coverage.\n\n## code comments\n\n- Add short JSDoc-style comments to functions and helpers.\n- Write header comments in active voice: the first sentence says what the module or function\n  does (\"Applies one action to the review state and returns the next state.\"), followed by its\n  invariants. Avoid passive or self-important framing (\"The one place where…\", \"the single\n  source of truth for…\") — name the behavior, not the architecture's opinion of itself.\n- Add inline comments for intent, invariants, or tricky behavior that would not be obvious to a fresh reader.\n- Skip comments that only narrate what the code already says.\n\n## naming\n\n- Prefer names that match the role the code plays in the product and architecture.\n- Use `layout` for structural placement or arrangement data.\n- Use `geometry` for aggregate spatial data used by rendering, scrolling, or interaction.\n- Use `bounds` for one concrete visible extent within a larger structure.\n\n## review behavior\n\n- Default behavior is a multi-file review stream in sidebar order.\n- Layout modes: `auto`, `split`, `stack`.\n- `auto` should choose split on wide terminals and stack on narrow ones.\n- Explicit `split` and `stack` choices override responsive `auto` layout selection.\n- `[` and `]` navigate hunks across the full review stream. Do not reintroduce `j`/`k` hunk navigation unless the user asks.\n- Agent context belongs beside the code, not hidden in a separate mode or workflow.\n- Agent notes are hunk-specific: show notes for the selected hunk, render them in the diff flow near the annotated row, and keep a clear spatial relationship to the code they explain.\n- Keep note behavior explicit. If the UI intentionally prioritizes one note, one selection, or one active target, encode that as a named policy rather than scattering array-index assumptions through the codebase.\n- STML markup notes (experimental) live in `src/ui/lib/stml/`. The layout engine is deliberately a deterministic line layout, not OpenTUI flexbox: the row-windowed review stream needs exact note heights before mount, so `(markup, width)` must always produce the same lines. Colors stay symbolic until render time so measurement never needs a theme. Do not \"simplify\" this into flexbox renderables, and keep note-card geometry in `agentNoteGeometry` as the single source for rendering, measurement, and agent-facing width reporting.\n- If you choose to use a local sidecar for temporary review context, keep it concise and review-oriented: one changeset summary, file summaries in narrative order, and a few hunk-level annotations with real rationale.\n- If a local sidecar is present, its file order is intentional, but the visible note UI should stay hunk-note driven rather than showing generic file or changeset explainer cards.\n- `hunk diff` working-tree reviews include untracked files by default. Use `--exclude-untracked` if you explicitly want tracked changes only.\n- Agents review via `skills/hunk-review/SKILL.md` using `hunk session *` commands; do not run interactive TUI commands directly.\n- `skills/hunk-review/SKILL.md` is generated. Edit `src/hunk-review/skillDocument.ts`, `src/session/agent/surface.ts`, or `src/session/agent/errors.ts`, then run `bun run generate:skill`; never hand-edit the skill file.\n\n## commands\n\n- install deps: `bun install`\n- run from source: `bun run src/main.tsx -- diff`\n- review a commit from source: `bun run src/main.tsx -- show HEAD~1`\n- fast smoke test: `bun run src/main.tsx -- diff /tmp/before.ts /tmp/after.ts`\n- typecheck: `bun run typecheck`\n- tests: `bun test`\n- PTY integration tests: `bun run test:integration`\n- TTY smoke test: `bun run test:tty-smoke`\n- format: `bun run format`\n- lint: `bun run lint`\n- build binary: `bun run build:bin`\n- install binary: `bun run install:bin`\n\n## binary notes\n\n- Installed `hunk` is a compiled snapshot, not linked to source.\n- After source changes, rebuild/reinstall with `bun run install:bin`.\n- For rendering verification, prefer a real TTY smoke run over redirected stdout capture.\n\n## verification\n\n- For rendering changes: run `bun run typecheck`, `bun test`, `bun run test:integration`, `bun run test:tty-smoke`, and do one real TTY smoke run on an actual diff.\n- For interaction, layout, scrolling, navigation, windowing, or other terminal-native behavior: add or update PTY integration coverage in `test/pty/*-integration.test.ts` and run it with `bun run test:integration`.\n- For CLI, config, or pager work: make sure the relevant source invocation still works (`diff`, `show`, `patch`, or `pager`).\n- Preserve current interaction model unless the user asks to change it explicitly.\n\n## cross-platform support\n\n- Hunk should work on macOS, Linux, and Windows. Keep tests and CI portable unless a case is explicitly Unix-only (PTY/TTY smoke coverage is Unix-only).\n- In tests, avoid hard-coded POSIX paths, separators, shell syntax, and filenames invalid on Windows; use Node path helpers for real filesystem paths while preserving user-provided/protocol paths when pass-through is intentional.\n- If Windows-only Bun behavior appears around timers, sockets, or line endings, prefer a small compatibility fix or a narrowly scoped skip with a comment over broadening Unix assumptions.\n\n## releases\n\n- Use Changesets for user-visible release notes. Add a `.changeset/*.md` entry with `bun run changeset` instead of editing `CHANGELOG.md` directly.\n- Target the public `hunkdiff` package in changesets. Use `patch` for fixes and small behavior changes, `minor` for new user-facing features, and `major` for breaking changes.\n- For maintenance-only PRs that should not appear in release notes, add an empty changeset with `bun run changeset -- --empty`.\n- Keep the top-level `CHANGELOG.md` as the released changelog artifact. It is updated during release prep with `bun run release:version`, not by normal feature/fix PRs.\n- Use the released changelog section as the starting point for the GitHub release body.\n- GitHub releases should follow this format:\n\n  ```md\n  ## What's Changed\n\n  - <change title> by @<author> in <PR URL>\n  - ...\n\n  **Full Changelog**: https://github.com/modem-dev/hunk/compare/<previous-tag>...<new-tag>\n  ```\n\n- Do not rely blindly on autogenerated GitHub release notes. After publishing, verify the release body and edit it if needed.\n- Prefer `gh release create/edit --notes-file` for multi-line release notes so the exact body is reviewed before posting.\n- After publishing, verify npm packages and GitHub release assets point at the new version. For Homebrew, Hunk is distributed through `Homebrew/homebrew-core`; do not open manual simple version-bump PRs yourself. Let Homebrew Autobump create the `hunk <version>` PR, then verify it merges and `brew install hunk` resolves to the new version. Only use `brew bump-formula-pr hunk --version <version>` if Homebrew maintainers request a manual bump or Autobump stalls unexpectedly.\n- For mise, verify with `MISE_AQUA_BAKED_REGISTRY=false mise latest hunk`. mise resolves Hunk through the community `aqua:modem-dev/hunk` entry, bakes an aqua registry snapshot into each of its own releases (`aqua.baked_registry`, default true), and caches downloaded registry sources for a week (`aqua.registry_cache_ttl`), so a default check can report stale registry data unrelated to our release; `mise cache clear` forces a refresh.\n- For patch releases and backports, list only changes actually present between the previous tag and the new tag on that release branch.\n- Prefer concise, user-visible entries over internal refactors unless the refactor changes user-visible behavior.\n- Keep each changeset summary to one concise user-facing sentence; put implementation detail in the PR or supporting docs.\n\n## repo notes\n\n- Local review artifacts are ignored on purpose. Leave them alone unless the user explicitly wants them updated, and do not commit them.\n- Keep this doc short and architectural. Fresh-context agents can discover file paths themselves.\n\n## commits\n\nCommit titles should follow Conventional Commits. Format: `<type>[scope]: <description>`. Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `build`. Use `!` or `BREAKING CHANGE:` footer for breaking changes. Description should explain the \"why\", not just the \"what\".\n","category":"root","tokens":4553}]}