hx-cli 0.1.4__tar.gz → 0.1.6__tar.gz

hx_cli-0.1.6/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+What shipped in each released version of HX, newest first.
+
+This file is the release record and part of the product: it ships inside the
+wheel, `hx changelog` prints it, and a session can answer "what's new?" or
+"which version added web search?" from it rather than from a guess. `hx docs`
+prints the manual next to it.
+
+The rules, enforced by `tests/test_docs.py` so a release cannot forget them:
+
+- Every released version has a `## [x.y.z] - YYYY-MM-DD` section here, and the
+  version in `src/hx/__init__.py` always has one. Bumping the version without
+  writing the section fails the suite before the tag exists.
+- Work that has landed but is not tagged lives under `## [Unreleased]`. At
+  release time that heading is renamed to the new version and dated, and a
+  fresh empty `## [Unreleased]` takes its place.
+- Entries say what a user can now do, in one line each, naming the command,
+  setting or key that reaches the feature. A changelog nobody can act on is a
+  git log with extra steps.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+the project follows [semantic versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.1.6] - 2026-09-10
+
+### Added
+
+- **Web search, over Tavily.** `WebSearch` returns ranked results with a
+  snippet each; `WebFetch` reads up to 5 URLs as markdown. Both are registered
+  only when a key resolves, so HX without one is unchanged and pays no
+  cached-prefix cost for a tool that would always fail. Set the key with
+  `hx auth set tavily`, or `TAVILY_API_KEY` / `HX_TAVILY_API_KEY` in the
+  environment. Credits spent are reported per call and per session.
+- **Corporate TLS support.** Certificates verify against the operating
+  system's trust store, `HX_CA_BUNDLE` (also `SSL_CERT_FILE`,
+  `REQUESTS_CA_BUNDLE`) names a CA file, and `HX_SSL_NO_VERIFY=1` turns
+  verification off with a warning every session. A TLS failure is now named in
+  one line at startup and in `/model` instead of showing up as an empty model
+  catalogue with no cause.
+- **Working-tree notices.** The git branch and files that changed on disk
+  outside the session are late-injected onto the newest user message, from one
+  `git status --porcelain=v2 --branch -z` per provider call, run in a worker
+  thread so it never blocks the UI. Off with
+  `"context": {"git_notices": false}` or `HX_GIT_NOTICES=0`.
+- **File checkpoints.** Write and Edit park a file's previous bytes in a
+  content-addressed store under the session directory, keyed to the position in
+  the transcript, so a rewind can undo edits and not just words. A file whose
+  bytes moved since HX wrote them is reported and left alone rather than
+  overwritten.
+- **`hx docs` and `hx changelog`.** The manual and this file, printed from the
+  installed package. `hx docs` with no argument lists the sections;
+  `hx docs credentials` prints one. `hx changelog 0.1.5` prints one release.
+  The system prompt points at both, so questions about HX itself are answered
+  from the shipped documentation.
+
+### Changed
+
+- The model catalogue keeps the last good copy when a refresh fails, and
+  records why it failed so `/model` can say so. The static routes (the Codex
+  models) are registered even when there is no cache file and no network.
+
+---
+
+## [0.1.5] - 2026-09-09
+
+### Added
+
+- **A ChatGPT Plus/Pro route.** Sign in with `hx auth login openai-codex` (or
+  `/login` in the TUI) and run `openai-codex/gpt-5.3-codex` against your
+  subscription instead of paying per token. OAuth with PKCE against
+  `auth.openai.com`, a loopback listener on port 1455, a paste-the-URL fallback
+  for SSH and `HX_LOGIN_DEVICE_CODE=1` for the device-code flow; access tokens
+  refresh themselves.
+- Credentials became one store per route in `~/.hx/auth.json` (mode 0600).
+  `hx auth` reports which routes have a credential and where it came from, and
+  `hx auth logout <provider>` forgets one.
+- `/model` offers only routes you are actually signed in to, so the picker
+  cannot select a model the session has no way to reach.
+
+The route serving a turn is decided by the model id alone: `openai-codex/*`
+goes to the subscription, everything else to OpenRouter.
+
+---
+
+## [0.1.4] - 2026-09-09
+
+### Fixed
+
+- TUI snapshot tests no longer embed the release version, so bumping the
+  version stopped failing the suite.
+
+---
+
+## [0.1.3] - 2026-09-09
+
+### Fixed
+
+- An exact slash command runs on the first `enter` instead of only selecting
+  itself in the completion list.
+
+---
+
+## [0.1.2] - 2026-09-09
+
+### Added
+
+- **Themes as data.** A theme is a JSON file - a `vars` block of colours and a
+  `colors` block mapping semantic roles onto them. Drop one in
+  `~/.hx/themes/mine.json` and `/theme mine` picks it up, no restart. Syntax
+  highlighting is theme-driven, and pi's theme files load unchanged.
+- **One keybinding registry.** Every key is defined once in `src/hx/keys.py`;
+  `/help`, the hints line and the README table all read from it, and any action
+  id can be rebound in `~/.hx/keybindings.json`. Conflicts and unknown ids are
+  reported at startup rather than silently resolved.
+- **A completion popup** above the prompt for `/` commands and `@` paths, with
+  fuzzy matching; `tab` cycles, `enter` accepts, `esc` dismisses.
+- **A readline-style prompt** with a kill ring (`ctrl+w`, `ctrl+u`, `ctrl+k`,
+  `ctrl+y`, `alt+y`), undo and redo.
+- **System clipboard support.** `ctrl+x` copies the selected message and
+  `/copy` the last reply, through `pbcopy`/`wl-copy`/`xclip`/`xsel` with an
+  OSC 52 fallback that also works over SSH.
+- The prompt is framed and the working status lives in its border.
+- `/exit` as an alias for `/quit`.
+
+### Fixed
+
+- Permission grants stay inside what the user actually approved.
+- A `/model` choice persists to user settings.
+- Slash commands run in a worker, so a slow one no longer blocks the UI.
+
+---
+
+## [0.1.0] - 2026-09-08
+
+First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/).
+
+### Added
+
+- **The agent loop**, streaming from OpenRouter with prefix caching, accurate
+  per-turn cost accounting and a stable request prefix.
+- **The tool suite**: Bash (with a background job runner), Read, Write, Edit,
+  Glob, Grep, TodoWrite and Task, with output capping that keeps the head and
+  tail of a large result and spills the rest to the session directory.
+- **The permission engine and OS sandbox.** `Tool(specifier)` rules where deny
+  beats ask beats allow, shell commands decomposed into their real segments
+  first, and Seatbelt on macOS / bubblewrap on Linux confining writes and
+  network. Modes cycle with `shift+tab`: `plan`, `default`, `acceptEdits`,
+  `bypass`.
+- **Context engineering**: late injection for per-turn state, compaction at 80%
+  of the window (or `/compact [focus]`), and cache breakpoints that only
+  advance once enough tokens have accumulated.
+- **Sessions**: persisted transcripts, `hx resume` / `/resume`, and a model-named
+  session title you can change with `/title`.
+- **Skills, subagents and MCP.** Skills are `SKILL.md` directories under
+  `.hx/skills/` or `~/.hx/skills/`, loaded on demand so a hundred installed
+  skills cost a hundred lines. Subagents (`explore`, `plan`, `general`, plus
+  your own in `.hx/agents/`) run in their own context and return one report.
+  MCP servers go in `.hx/mcp.json` or `hx mcp add`.
+- **The TUI**: transcript, status bar with token, cache and cost counters, todo
+  sidebar, model picker, command palette and per-tool renderers.
+- **Print mode** (`hx -p`), where stdout carries only the assistant's text, so
+  it pipes.
+- **Configuration** merged from defaults, `~/.hx/settings.json`,
+  `./.hx/settings.json`, `HX_*` environment variables and CLI flags, with
+  permission lists and prompt appends unioned rather than replaced.
+- `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
+  self-update, and `install.sh` bootstrapping uv with a pinned Python.
+
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/aletisunil/hx/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/aletisunil/hx/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/aletisunil/hx/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/aletisunil/hx/compare/v0.1.0...v0.1.2
+[0.1.0]: https://github.com/aletisunil/hx/releases/tag/v0.1.0

{hx_cli-0.1.4 → hx_cli-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.1.4
+Version: 0.1.6
 Summary: HX - a terminal coding agent
 Project-URL: Homepage, https://github.com/aletisunil/hx
 Project-URL: Issues, https://github.com/aletisunil/hx/issues
@@ -18,6 +18,7 @@ Requires-Dist: pydantic>=2.7
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.7
 Requires-Dist: textual>=0.85
+Requires-Dist: truststore>=0.10
 Provides-Extra: dev
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
@@ -79,16 +80,24 @@ export PATH="$(uv tool dir --bin):$PATH"
 
 Requires Python 3.11+. macOS and Linux. Update with `hx upgrade`.
 
-### The API key
+### Credentials
 
-On first run HX asks for an OpenRouter key and saves it to `~/.hx/auth.json`
-with mode 0600. Get one at <https://openrouter.ai/keys>.
+HX reaches models over two routes. Which one serves a turn is decided by the
+model id alone, so "what paid for that" is always answerable by reading it:
 
-To change it later, `/configure` inside the TUI, or from a shell:
+| Model id | Route | Billing |
+|---|---|---|
+| `anthropic/claude-sonnet-4.5`, `openai/gpt-5`, … | OpenRouter | per token, API key |
+| `openai-codex/gpt-5.3-codex` | ChatGPT Plus/Pro | your subscription |
+
+Credentials live in `~/.hx/auth.json`, mode 0600, one entry per route.
+
+**OpenRouter.** On first run HX asks for a key. Get one at
+<https://openrouter.ai/keys>. Change it later with `/configure` in the TUI, or:
 
 ```sh
-hx auth          # is a key set, and where does it come from?
-hx auth set      # paste a new one (hidden input)
+hx auth          # which routes have a credential, and where from
+hx auth set      # paste a new OpenRouter key (hidden input)
 hx auth clear    # remove the saved key
 ```
 
@@ -96,6 +105,89 @@ Resolution order is `HX_OPENROUTER_API_KEY`, then `OPENROUTER_API_KEY`, then
 the saved file. The environment wins, and both `/configure` and `hx auth` say
 so — otherwise saving a key while a variable is set looks like a no-op.
 
+**ChatGPT Plus/Pro.** Sign in over OAuth and run Codex models against your
+subscription instead of paying per token
+([OpenAI endorses this for OSS harnesses](https://developers.openai.com/community/codex-for-oss)):
+
+```sh
+hx auth login openai-codex      # or /login inside the TUI
+hx --model openai-codex/gpt-5.3-codex
+hx auth logout openai-codex
+```
+
+The browser opens to `auth.openai.com` and redirects to a loopback listener on
+port 1455. Over SSH that redirect cannot reach your machine, so paste the final
+URL into the prompt instead — or set `HX_LOGIN_DEVICE_CODE=1` for the
+device-code flow. Access tokens are refreshed automatically; `/model` only
+offers routes you are actually signed in to.
+
+**Web search.** Optional, and the one credential that is not a model route.
+It powers two tools:
+
+| Tool | Does |
+|---|---|
+| `WebSearch` | search the web, returning ranked results with a snippet each |
+| `WebFetch` | read up to 5 URLs, returned as markdown |
+
+[Tavily](https://app.tavily.com) bills per search rather than per token, so it
+works identically on both routes — including the ChatGPT subscription one,
+where a provider-native search tool is not on offer.
+
+Get a key at <https://app.tavily.com> — the free tier is 1000 searches a month
+and takes no card — then save it:
+
+```sh
+hx auth set tavily      # paste the key, hidden input, saved to ~/.hx/auth.json
+hx auth                 # confirm: `tavily  key tvly-a…f3d9  …/auth.json`
+hx auth clear tavily    # remove it again
+```
+
+Or keep it in the environment instead, which wins only when nothing is saved:
+
+```sh
+export TAVILY_API_KEY=tvly-...     # HX_TAVILY_API_KEY is read first
+```
+
+**Without a key, HX works exactly as before** — `WebSearch` and `WebFetch` are
+simply not registered, and `hx auth` says so:
+
+```
+tavily         not configured      WebSearch and WebFetch are off
+```
+
+There is no nag, no failing tool and no startup warning. Leaving them out is
+deliberate: an advertised tool that always fails still costs cached-prefix
+tokens every turn, and a model told "no key" just calls it again. Adding a key
+turns both on from the next `hx`; no other setting changes.
+
+Credits are reported per call and per session at the foot of every result —
+`[Tavily: 1 credit, 4 this session]`. A search costs 1 credit, `search_depth:
+"advanced"` costs 2, and fetching costs 1 per 5 URLs. Tavily's docs describe a
+`usage` field for this, but the live API does not send one, so HX prices every
+call from those published rates and marks the figure `~1` rather than passing
+an estimate off as measured. Check `app.tavily.com` for the authoritative
+number.
+
+Credits are *not* in the status bar's cost, which prices tokens: `/cost`
+under-reports a session that searched.
+
+**Behind a TLS-inspecting proxy.** HX verifies certificates against the
+operating system's trust store, so a corporate CA the machine already trusts
+needs no setup. When the CA lives only in a file, name it:
+
+```sh
+export HX_CA_BUNDLE=/path/to/corp-ca.pem   # SSL_CERT_FILE and REQUESTS_CA_BUNDLE also work
+```
+
+`HX_SSL_NO_VERIFY=1` turns verification off entirely; it prints a warning at
+startup every session, because it is not a fix. A TLS failure is reported in
+one line - `/model` and the startup notice both name the certificate problem
+rather than reporting an empty catalogue with no cause.
+
+There is no Claude Pro/Max route. Anthropic rejects OAuth tokens unless the
+request impersonates Claude Code, which HX will not do. Claude models stay
+available through OpenRouter.
+
 ---
 
 ## Running it
@@ -105,18 +197,54 @@ hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
 hx resume                   # resume the last session here
 hx resume <session-id>      # resume a specific one
+hx prompt                   # print the system prompt this directory would use
 hx --model openai/gpt-5     # override the model for one run
 hx --mode plan              # start read-only
 hx --cwd ../other-project   # run against a different directory
 hx --no-sandbox             # disable OS sandboxing (rules still apply)
+hx --system-prompt @p.md    # replace the system prompt for one run
+hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
-hx auth [set|clear]         # manage the API key
+hx auth [set|clear]         # manage the OpenRouter key
+hx auth login [provider]    # sign in (openrouter, openai-codex)
+hx auth logout <provider>   # forget a stored credential
+hx docs [section]           # the manual; no argument lists its sections
+hx changelog [version]      # what shipped in each version
 hx upgrade                  # update to the latest release
 ```
 
 Print mode is the scriptable one: stdout carries only the assistant's text, so
 it pipes cleanly.
 
+### The docs ship with the binary
+
+`README.md` and [`CHANGELOG.md`](CHANGELOG.md) are included in the wheel, so
+the installed tool can print the manual and the release record for the version
+you are actually running:
+
+```sh
+hx docs                     # the section titles
+hx docs credentials         # one section, printed whole
+hx docs --all               # the entire manual
+hx changelog                # every release, newest first
+hx changelog 0.1.5          # one release
+hx changelog unreleased     # what has landed since the last tag
+```
+
+The system prompt points a session at these two commands, so "how do I set the
+API key?" or "what changed in the last release?" is answered from the shipped
+documentation rather than from the model's recollection of some other version.
+The call still goes through the permission engine like any other command;
+allowlist it if you would rather not be asked:
+
+```jsonc
+{ "permissions": { "allow": ["Bash(hx docs:*)", "Bash(hx changelog:*)"] } }
+```
+
+`CHANGELOG.md` lists what each version added, and a release cannot skip it:
+`tests/test_docs.py` fails when `__version__` has no section (see
+[Releasing](#releasing)).
+
 ### Keys
 
 Every key below is defined once, in `src/hx/keys.py`. `/help`, the hints line
@@ -192,13 +320,18 @@ than being silently resolved.
 | `/model [query]` | pick a model; shows context window, price per Mtok, cache support |
 | `/models refresh` | re-fetch the catalogue |
 | `/configure` | session settings and the API key |
+| `/login [provider]` | sign in to a model route |
+| `/logout <provider>` | forget a stored credential |
 | `/mode [name]` | `plan`, `default`, `acceptEdits`, `bypass` |
 | `/permissions` | active rules and what is enforcing them |
 | `/context` | what is filling the context window |
 | `/cost` | tokens, cache savings, spend |
 | `/compact [focus]` | summarise older turns now |
 | `/clear` | fresh session, same directory |
-| `/resume` | reopen a previous session |
+| `/resume` | reopen a previous session, listed by name |
+| `/rewind` | go back to an earlier prompt, restoring the files HX changed |
+| `/title [text]` | show or set this session's name |
+| `/prompt` | the system prompt this session is running with |
 | `/todos` | toggle the sidebar |
 | `/skills` | installed skills |
 | `/agents` | subagent types |
@@ -226,8 +359,9 @@ Settings are JSON, merged lowest to highest:
 defaults  <  ~/.hx/settings.json  <  ./.hx/settings.json  <  HX_* env  <  CLI flags
 ```
 
-Permission rule lists are unioned across layers, so a project can add a deny
-rule without discarding yours. Everything else is replaced.
+Permission rule lists and `prompt.append` are unioned across layers, so a
+project can add a deny rule — or a line to the system prompt — without
+discarding yours. Everything else is replaced.
 
 ```jsonc
 {
@@ -238,6 +372,7 @@ rule without discarding yours. Everything else is replaced.
   "models": {
     "model": "anthropic/claude-sonnet-4.5",
     "subagent_model": null,           // defaults to "model"
+    "title_model": null,              // model that names sessions; defaults to "model"
     "max_tokens": 8192,
     "temperature": null
   },
@@ -255,20 +390,64 @@ rule without discarding yours. Everything else is replaced.
     "compact_at": 0.80,               // fraction of the window that triggers compaction
     "keep_recent_turns": 6,           // turns kept verbatim across a compaction
     "tool_output_char_cap": 25000,
-    "tool_output_line_cap": 2000
+    "tool_output_line_cap": 2000,
+    "git_notices": true               // late-inject the branch and outside file changes
   },
 
   "bash": {
     "timeout_seconds": 120,
     "max_timeout_seconds": 600,       // ceiling; caps what the model may ask for
     "shell": null                     // defaults to $SHELL
+  },
+
+  "prompt": {
+    "system": null,                   // replaces the built-in system prompt
+    "append": []                      // added after it; unioned across layers
   }
 }
 ```
 
 Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
-`HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_THEME`,
-`HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state.
+`HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_GIT_NOTICES`,
+`HX_THEME`, `HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state, `HX_TAVILY_API_KEY`
+for web search, and `HX_CA_BUNDLE` / `HX_SSL_NO_VERIFY` for TLS (see
+[Credentials](#credentials)).
+
+### The system prompt
+
+`hx prompt` prints the prompt this directory resolves to, with its source on
+stderr so stdout stays pipeable. `/prompt` shows the same thing inside a running
+session.
+
+The built-in prompt is `SYSTEM_PROMPT` in `src/hx/core/context.py`. It is
+replaced by the first of these that exists:
+
+| Source | Scope |
+|---|---|
+| `--system-prompt TEXT` or `@path`, or `prompt.system` | one run |
+| `./.hx/system-prompt.md` | this project |
+| `~/.hx/system-prompt.md` | you, everywhere |
+| the built-in prompt | fallback |
+
+Appended text is added after whichever prompt won, in this order:
+`~/.hx/system-prompt-append.md`, `./.hx/system-prompt-append.md`, then each
+`--append-system-prompt` value (and `prompt.append`) in the order given. Nothing
+appended is ever discarded by a later layer.
+
+This is a different lever from `HX.md`: `HX.md` describes *the project* and is
+injected as its own context section, while these files change *the agent's
+instructions*. Both are read once at startup and frozen, because they sit above
+the first cache breakpoint — an override edited mid-session applies on the next
+run, and `/prompt` says so when it spots one.
+
+### Sessions are named
+
+After the first exchange, HX asks the model for a short name for the session and
+writes it to `~/.hx/sessions/<id>/meta.json`, so `/resume` lists work rather
+than timestamps. It is one small call — cap 32 output tokens, `models.title_model`
+if you want a cheaper model for it — and it is counted in `/cost` like any other.
+If the call fails the session is still named, from your first message. `/title
+<text>` renames it.
 
 ### Themes
 
@@ -298,14 +477,17 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | Path | What |
 |---|---|
 | `~/.hx/settings.json` | your settings |
-| `~/.hx/auth.json` | API key, mode 0600 |
+| `~/.hx/auth.json` | API keys and logins, mode 0600 |
 | `~/.hx/models.json` | cached model catalogue, refreshed daily |
 | `~/.hx/themes/` | your themes, one JSON file each |
 | `~/.hx/keybindings.json` | your key overrides |
+| `~/.hx/system-prompt.md` | your system prompt, replacing the built-in one |
+| `~/.hx/system-prompt-append.md` | text appended to whichever prompt is in force |
 | `~/.hx/sessions/` | transcripts, spilled tool output, subagent sessions |
 | `~/.hx/skills/`, `~/.hx/agents/` | your skills and agents |
 | `./.hx/settings.json` | project settings, checked in if you like |
 | `./.hx/mcp.json` | project MCP servers |
+| `./.hx/system-prompt.md`, `./.hx/system-prompt-append.md` | project prompt overrides |
 | `./.hx/skills/`, `./.hx/agents/` | project skills and agents |
 | `./HX.md` | project instructions, loaded into every session |
 
@@ -347,10 +529,31 @@ assembled in a fixed order and never mutated mid-session. Cache breakpoints sit
 at the end of that static block and at a rolling point before the recent turns,
 which only advances once enough tokens have accumulated behind it.
 
-**Late injection** carries everything that changes per turn — the todo list,
-files that changed on disk since HX read them — on the tail of the newest user
-message rather than in the prefix. Stale copies are stripped and regenerated
-each turn, so six todo updates leave one copy in context, not six.
+**Late injection** carries everything that changes per turn - the todo list,
+files that changed on disk since HX read them, the git branch and any file the
+working tree gained or lost outside the session - on the tail of the newest
+user message rather than in the prefix. Stale copies are stripped and
+regenerated each turn, so six todo updates leave one copy in context, not six.
+
+**Working-tree notices** come from one `git status --porcelain=v2 --branch -z`
+per provider call, run without a shell and bounded by a two-second timeout. It
+runs in a worker thread, as every injector does: a turn makes one of these per
+tool round-trip, and on the event loop a slow repository would freeze the UI
+each time. A file HX has already read is left to the stale-file notice, so no
+path is reported twice; outside a repository the watcher disables itself for
+the session. Turn it off with `"context": {"git_notices": false}`.
+
+**Rewind** (`/rewind`) picks an earlier prompt and takes the session back to
+it: the transcript is cut there and every file HX wrote after it is restored
+from a content-addressed snapshot taken before each Write and Edit. A file
+someone else changed in the meantime is reported and left alone, and shell
+commands are outside the scheme - the report says so rather than implying the
+tree was fully returned. The prompt that was cut comes back in the input box,
+because a rewind is usually the first half of saying it differently. Nothing is
+deleted from the session file: the rewind is one more append, and replaying the
+file reproduces the state - which is also how an undone compaction gives its
+messages back. The cost ledger is deliberately not rewound; those tokens were
+spent.
 
 **Compaction** fires at 80% of the window, or on `/compact [focus]`. Older
 turns are replaced by a structured summary; the recent turns and the todo list
@@ -433,12 +636,20 @@ uv run mypy                  # strict
 uv run hx                    # run from the checkout
 ```
 
-Tests marked `live` hit the real OpenRouter API and cost money:
+Tests marked `live` hit a real API. The OpenRouter ones cost money:
 
 ```sh
-OPENROUTER_API_KEY=... uv run pytest -m live
+OPENROUTER_API_KEY=... uv run pytest -m live tests/test_live.py
+
+# the Codex route draws on your ChatGPT subscription instead
+hx auth login openai-codex
+uv run pytest -m live tests/test_live_codex.py
 ```
 
+They are the only place the wire formats, streaming, tool use and a genuine
+cache hit are proven against a real service; everything else runs against the
+scripted provider.
+
 Tests marked `sandbox` exercise the real OS sandbox and are skipped where no
 backend exists.
 
@@ -453,10 +664,12 @@ uv run pytest tests/tui/test_snapshots.py --snapshot-update
 
 ```
 src/hx/
-  cli.py config.py paths.py frontmatter.py
+  cli.py config.py paths.py frontmatter.py git.py
   core/         loop, context assembly, compaction, late injection, sessions, usage
-  providers/    OpenRouter, the model catalogue, a scripted provider for tests
-  tools/        Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task, output capping
+  auth/         credential store, OAuth flows, per-route resolution
+  providers/    OpenRouter, Codex, the model catalogue, a scripted provider for tests
+  tools/        Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task, WebSearch,
+                WebFetch, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
   skills/ agents/ mcp/
   keys.py       keybinding registry: ids, defaults, descriptions, user overrides
@@ -486,10 +699,18 @@ One-time setup:
 Each release:
 
 ```sh
-# bump __version__ in src/hx/__init__.py, commit
+# 1. move CHANGELOG.md's [Unreleased] entries under the new version, dated,
+#    and leave a fresh empty [Unreleased] behind
+# 2. bump __version__ in src/hx/__init__.py
+# 3. uv run pytest tests/test_docs.py     # the version must have a section
+git commit -am "release: X.Y.Z"
 git tag v$(uv run hx --version | cut -d' ' -f2) && git push origin main --tags
 ```
 
+Step 1 is not optional and is not a convention: `tests/test_docs.py` fails the
+whole suite when `__version__` has no `CHANGELOG.md` section, so a release that
+skips it cannot get past CI to the `publish` job.
+
 The `publish` job runs only on `refs/tags/v*` and only after lint, the test
 matrix, and an install-script run in a clean Debian container have passed. It
 builds with `uv build` and uploads via OIDC.
@@ -509,9 +730,12 @@ streaming with prefix caching and accurate cost accounting, session persistence
 and resume, the tool suite, the permission engine and OS sandbox, late
 injection, compaction, output capping, skills, subagents, MCP, and the TUI.
 
+Two routes to a model: an OpenRouter API key, or a ChatGPT Plus/Pro
+subscription over OAuth. The model id decides which.
+
 Published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/), released
 from CI on a tag.
 
-The one thing still unproven is a live OpenRouter call: the `live` tests exist
-and cover the wire format, tool use and a genuine cache hit, but they need a
-key and are deselected by default.
+The one thing still unproven in CI is a live call on either route: the `live`
+tests exist and cover both wire formats, tool use, reasoning replay and a
+genuine cache hit, but they need a credential and are deselected by default.