hx-cli 0.1.8__tar.gz → 0.2.0__tar.gz

{hx_cli-0.1.8 → hx_cli-0.2.0}/.github/workflows/ci.yml

@@ -21,8 +21,16 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
-        python: ["3.11", "3.12"]
+        # Every supported minor on Linux catches version bugs; macOS runs the
+        # floor and the ceiling only, to catch platform bugs without paying for
+        # the full OS x version grid.
+        os: [ubuntu-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python: "3.11"
+          - os: macos-latest
+            python: "3.14"
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4

{hx_cli-0.1.8 → hx_cli-0.2.0}/CHANGELOG.md

@@ -28,6 +28,162 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.0] - 2026-09-14
+
+### Changed
+
+- The interface is drawn into your terminal's own scrollback instead of taking
+  over the screen. Finished output belongs to the terminal: scroll it, select
+  it with the mouse, copy it, pipe it, and it is still there after HX exits.
+  `/fullscreen` takes the whole window back for anyone who preferred it that
+  way - the prompt pinned to the bottom row, the transcript scrolling above it
+  with `pgup`, `pgdn`, `ctrl+home` and `ctrl+end` - and writes the choice to
+  `tui.fullscreen` for the next session. On either screen the prompt and the
+  status bar sit on the bottom row from the first frame - a conversation that
+  does not fill the window is padded above the dock, not below it, and rows a
+  closing picker gives back open above it too. The slash-command and `@`-path
+  completion lists draw above the prompt for the same reason: under it, every
+  keystroke that changed the number of matches moved the prompt and the status
+  bar with it. Exiting erases the whole interface - banner, conversation and
+  dock - and puts the shell prompt back on the row HX started on, rather than
+  leaving a dead prompt box and a status bar on screen above it, from either
+  screen: quitting out of `/fullscreen` also takes away the frame that was
+  parked underneath it.
+- Approving a tool call is now a framed prompt with one option per line, each
+  saying what it does - `always allow` states that it writes a rule to
+  `.hx/settings.local.json`. `y`/`s`/`a`/`n` still answer in one keystroke,
+  `esc` denies, and the arrow keys work for anyone who wants to read first.
+  The command shown is the one that will run, `$` and all. When two subagents
+  stop at an approval at once, the older one holds the keyboard and the other
+  says it is waiting rather than offering keys that would answer the first.
+- Your theme reaches the whole interface. Links, list bullets, block quotes,
+  horizontal rules and inline code in the model's replies now follow the
+  palette instead of a hard-coded set of colours, and headings are visibly
+  different from each other.
+- Multi-line output from `/help`, `/cost`, `/status` and the rest lines up
+  under its own first line instead of at two different indents.
+- The todo list is a block in the conversation rather than a sidebar, and
+  `/todos` and `ctrl+t` show it. A scrollback-native interface has no second
+  column to put a sidebar in.
+- Mouse selection is the terminal's, across the whole session including what
+  has scrolled off, rather than HX's own within the visible screen.
+- Text HX did not write - a file a tool read, a command's output, the model's
+  reply, a paste into the prompt - is drawn as plain text. Escape sequences in
+  it are removed rather than sent on to your terminal, so a file cannot set
+  your clipboard, rename your window, hide a link behind different words, or
+  erase what is already on screen by being read.
+- `/clear` now clears the screen and the scrollback above it, instead of
+  emptying the transcript and leaving the last session on screen. Terminals
+  that do not implement scrollback erasure - macOS Terminal.app - clear the
+  screen only.
+- `/model`, the command palette and every other picker are sized to the
+  terminal rather than to a fixed eight rows, so a tall window shows a long
+  list instead of leaving two thirds of itself empty.
+- `ctrl+z` suspends HX to the background and resuming redraws it; `ctrl+home`
+  and `ctrl+end` reach the ends of the conversation; `ctrl+_` undoes in the
+  prompt. All three were listed in `/help` and bound to nothing.
+- `ctrl+p` and `ctrl+l` are named in the hints line under the prompt, which is
+  where the keys a session offers are supposed to be discoverable.
+- A block drawn against the prompt no longer closes itself with a second rule,
+  which left a rule, a blank line and another rule under every picker and under
+  every approval. Whichever block ends up against the dock lets the dock's own
+  rule close it, and takes its own back as soon as something lands underneath.
+- The installer now opens with a terminal boot animation that draws and lights
+  the HX mark, with a clean static version for CI and redirected output.
+
+---
+
+## [0.1.9] - 2026-09-11
+
+### Changed
+
+- Project instructions live in `AGENTS.md`, the cross-agent standard, instead
+  of `HX.md`. A repo already carrying an `AGENTS.md` for another coding agent
+  is understood by HX with no extra file; `/init` writes one. `HX.md` and
+  `.hx/HX.md` are no longer read - rename yours.
+- Python 3.13 and 3.14 are supported in fact, not just by the `>=3.11` floor.
+  CI runs the suite on every supported minor, so installing on a current
+  interpreter is covered by a test run rather than by hope.
+
+### Fixed
+
+- `/model` lists the Codex models your ChatGPT account can actually run. HX
+  shipped a hard-coded pair — `gpt-5.3-codex` and its spark — that the backend
+  now refuses outright, so a paid subscription offered two models and both
+  failed. Signing in fetches the account's own list instead; `/models refresh`
+  asks again, and the last shipped list stands in when the fetch cannot happen.
+- A Codex model that the account is refused now says so in terms you can act
+  on. The backend answers with a 400 naming the model, which reads as a bad
+  model id. The message now says entitlement is per model and per account, and
+  points at `/models refresh` to get the list that is true for your account.
+- `hx auth` names the plan behind a ChatGPT login (`signed in (plus)`), and
+  `/login` says when it is a free one, since Codex is documented as needing a
+  paid plan. Neither blocks a model: entitlement is per model, and the fetched
+  catalogue is what decides it, so HX reports the plan and lets the backend
+  answer.
+- `/model` says what pays for each model. Subscription models showed
+  `$0.00/$0.00`, indistinguishable from a free OpenRouter one; they now read
+  `subscription`. The status bar tags them too — `gpt-5.6-terra (sub)`.
+- `/resume` counts prompts, not wire-format records. A session you sent one
+  prompt to listed as "31 msgs"; it now reads `1 prompt · 31 msgs`, and `/cost`
+  says "17 API requests across 1 prompt" so the two numbers reconcile.
+- The status bar follows the branch. It read `git HEAD` once at startup, so
+  checking out in an IDE or another terminal left it showing a branch you had
+  left; it now re-reads on a timer, worktrees included.
+- Selecting assistant prose or a tool block with the mouse copies it. Textual
+  can only extract text from widgets that render plain text, so dragging over
+  those blocks highlighted them and copied nothing.
+- Copying goes through `pbcopy`/`wl-copy`/`xclip` before OSC 52. Textual's own
+  copy is OSC 52 only, which macOS Terminal ignores and iTerm2 ships disabled,
+  so `ctrl+c` on a selection silently did nothing there.
+- The prompt names the steer key the way your keyboard does. It read
+  `alt+enter` everywhere, while `/help` two keystrokes away read `option+enter`
+  on macOS - the same key, spelled two ways in one window. It now comes from
+  the keybinding registry, so it follows the platform and follows a rebind.
+- `ctrl+c` reaches the copy at all. The prompt holds focus for the whole session
+  and binds that key itself, so a transcript selection was never what it
+  copied. It now copies the selection when there is one, and clears the prompt
+  when there is not, exactly as before.
+
+### Added
+
+- `models.codex_models` in settings adds Codex model ids to the `/model`
+  picker, on top of the ones fetched for your account — for an id the backend
+  serves but does not advertise, or a machine that cannot reach it.
+  `{"models": {"codex_models": ["gpt-5.6-terra"]}}` adds your own.
+- `/effort` picks how hard the current model thinks, from the levels that model
+  actually offers, and the status bar shows the depth in force next to the
+  model — `gpt-5.6-terra (sub) · high`. It applies to the next turn and is
+  saved for later sessions. Switching models re-resolves it, so a choice the
+  new model cannot reach shows as the depth it will really run at.
+- `models.reasoning_effort` sets how hard a reasoning model thinks —
+  `none` through `ultra`. Left unset, each Codex model runs at the default its
+  own catalogue entry names (`low` on GPT-6 Astra, `medium` on GPT-5.6 Terra)
+  instead of one fixed depth for every model. A value is clamped to what the
+  chosen model advertises, so `max` runs at `xhigh` on GPT-5.5 rather than
+  being refused.
+- `/mouse [on|off]` hands drag-selection back to your terminal, for when you
+  want its own selection rather than HX's. Holding alt/option while dragging
+  does the same thing without the toggle.
+
+### Changed
+
+- "Always allow" grants move out of your repository. They were written to
+  `./.hx/settings.local.json`, with a `./.hx/.gitignore` added to hide them —
+  two files of HX's in your checkout. They now live in
+  `~/.hx/projects/<project>/settings.local.json`, still scoped to the project,
+  and an existing local file is migrated on the next run.
+- Grants that much older versions appended to `./.hx/settings.json` — the file
+  a project checks in — are lifted into that same local file on the next run,
+  and HX says which ones it moved. Only `allow` moves; a project's `deny` and
+  `ask` stay shared. It happens once, so a rule you later write there by hand
+  is left alone, and an emptied `./.hx` is removed.
+- HX no longer rewrites `./.hx/settings.json` at all. Its one remaining writer
+  there, the startup pass that widens stale whole-command rules, now reports
+  them and leaves the file to its owner.
+
+---
+
 ## [0.1.8] - 2026-09-10
 
 ### Fixed
@@ -234,7 +390,9 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/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.8...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/aletisunil/hx/compare/v0.1.9...v0.2.0
+[0.1.9]: https://github.com/aletisunil/hx/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/aletisunil/hx/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/aletisunil/hx/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/aletisunil/hx/compare/v0.1.5...v0.1.6

{hx_cli-0.1.8 → hx_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.1.8
+Version: 0.2.0
 Summary: HX - a terminal coding agent
 Project-URL: Homepage, https://github.com/aletisunil/hx
 Project-URL: Issues, https://github.com/aletisunil/hx/issues
@@ -11,29 +11,32 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Requires-Dist: click>=8.1
 Requires-Dist: httpx>=0.27
+Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: pydantic>=2.7
+Requires-Dist: pygments>=2.17
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: rich>=13.7
-Requires-Dist: textual>=0.85
 Requires-Dist: truststore>=0.10
+Requires-Dist: wcwidth>=0.2.13
 Provides-Extra: dev
 Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pyte>=0.8; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
-Requires-Dist: pytest-textual-snapshot>=1.0; extra == 'dev'
 Requires-Dist: pytest>=8.2; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
-Requires-Dist: textual-dev>=1.5; extra == 'dev'
 Requires-Dist: types-pygments; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # HX
 
-A terminal coding agent. Python core, Textual TUI, OpenRouter for models.
+A terminal coding agent. Python core, its own terminal renderer, OpenRouter for
+models.
 
 HX runs in your project directory, reads and edits your code, runs commands in
 a sandboxed shell, and shows you what every turn costs.
@@ -88,7 +91,7 @@ model id alone, so "what paid for that" is always answerable by reading it:
 | 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 |
+| `openai-codex/gpt-5.6-terra` | ChatGPT Plus/Pro | your subscription |
 
 Credentials live in `~/.hx/auth.json`, mode 0600, one entry per route.
 
@@ -111,7 +114,7 @@ subscription instead of paying per token
 
 ```sh
 hx auth login openai-codex      # or /login inside the TUI
-hx --model openai-codex/gpt-5.3-codex
+hx --model openai-codex/gpt-5.6-terra
 hx auth logout openai-codex
 ```
 
@@ -121,6 +124,67 @@ 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.
 
+`hx auth` names the account's plan next to the login, because "which account is
+this and what is it paying for" is otherwise a JWT to decode by hand:
+
+```sh
+hx auth
+# openrouter     key sk-or-…8abd     ~/.hx/auth.json
+# openai-codex   signed in (plus)    ~/.hx/auth.json
+```
+
+Codex is documented as requiring a paid ChatGPT plan, and HX says so when the
+login is on a free one. It does not refuse to try: the plan on the credential
+has been observed deciding nothing — the backend refuses every Codex model on a
+`plus` account with the same error it gives a `free` one — so the switch is
+allowed and the backend's own answer is what reports the problem.
+
+**If every Codex model is refused**, the error says so in those terms: it is
+the account that is being refused, not the model, and a different model id will
+not help. Check that the subscription is active and Codex is enabled for the
+account at <https://chatgpt.com/codex>, and that the official Codex CLI can
+reach it at all.
+
+**Which Codex models you get** is decided by your ChatGPT account, not by HX.
+Signing in fetches the account's own list from the Codex backend, and `/model`
+offers exactly that; `/models refresh` asks again. Entitlement is per model —
+the same `plus` account can run `gpt-5.6-sol` and be refused `gpt-5.3-codex` —
+so a model the picker does not list is one the subscription does not cover.
+
+**How hard they think** comes from the same fetch. Each Codex model publishes
+its own reasoning levels and its own default — GPT-6 Astra starts at `low`,
+GPT-5.6 Terra at `medium` — and HX asks for the model's default rather than one
+fixed depth. `/effort` changes it:
+
+```
+/effort            # pick from the levels this model offers
+/effort high       # none | minimal | low | medium | high | xhigh | max | ultra
+/effort default    # back to the model's own default
+```
+
+It takes effect on the next turn, is saved to `~/.hx/settings.json` for later
+sessions, and shows on the status bar next to the model — `gpt-5.6-terra (sub)
+· high`. Levels differ per model, so a choice is clamped to what the current
+one offers: `max` runs at `xhigh` on GPT-5.5 rather than being refused, and the
+bar shows what is actually happening. Set it by hand instead with:
+
+```jsonc
+// ~/.hx/settings.json
+{ "models": { "reasoning_effort": "high" } }
+```
+
+When the model list cannot be fetched (no network, an old cache), HX falls back
+to the models it last shipped. To add an id the backend does not advertise:
+
+```jsonc
+// ~/.hx/settings.json
+{ "models": { "codex_models": ["gpt-5.6-terra"] } }
+```
+
+They join the `/model` picker on the next start. HX cannot ask how large an
+unknown model's context window is, so it assumes a conservative 200k — that
+costs an accurate context gauge, not the use of the model.
+
 **Web search.** Optional, and the one credential that is not a model route.
 It powers two tools:
 
@@ -256,20 +320,20 @@ be rebound (see [Keybindings](#keybindings)).
 | `enter` | send |
 | `ctrl+j` | newline (also `shift+enter`) |
 | `esc` | interrupt the current turn |
-| `ctrl+c` | clear the prompt; twice on an empty prompt exits |
+| `ctrl+c` | copy the selected text; with nothing selected, clear the prompt (twice on an empty prompt exits) |
 | `ctrl+d` | exit, when the prompt is empty |
 | `ctrl+z` | suspend to the background |
 | `shift+tab` | cycle permission mode |
 | `ctrl+p` | command palette |
 | `ctrl+l` | model picker |
 | `ctrl+o` | expand tool output (also `ctrl+r`) |
-| `ctrl+t` | toggle the todo sidebar |
+| `ctrl+t` | show the current plan |
 | `ctrl+x` | copy the selected message to the clipboard |
 | `ctrl+up` | previous message |
 | `ctrl+down` | next message |
-| `pgup` | scroll the transcript up |
-| `pgdn` | scroll the transcript down |
-| `ctrl+home` | jump to the start of the transcript |
+| `pgup` | scroll the transcript up (fullscreen; otherwise your terminal scrolls) |
+| `pgdn` | scroll the transcript down (fullscreen; otherwise your terminal scrolls) |
+| `ctrl+home` | jump to the start: the viewport in fullscreen, the first message otherwise |
 | `ctrl+end` | jump back to the newest output |
 | `@path` | complete a file path |
 | `!command` | run a shell command directly, no model turn |
@@ -281,7 +345,8 @@ The prompt is a readline-style editor: `ctrl+a`/`ctrl+e` for line start and end,
 `ctrl+b`/`ctrl+f` by character, `alt+b`/`alt+f` by word, `ctrl+w` and `alt+d` to
 kill a word, `ctrl+u` and `ctrl+k` to kill to the start or end of a line, then
 `ctrl+y` to yank it back and `alt+y` to walk further down the kill ring.
-`ctrl+z` undoes, `ctrl+shift+z` redoes.
+`ctrl+_` undoes, `ctrl+shift+z` redoes - `ctrl+z` belongs to the shell, and
+suspends HX.
 
 Typing `/` or `@` opens a completion list above the prompt; `tab` cycles it,
 `enter` accepts, `esc` dismisses.
@@ -293,10 +358,13 @@ HX writes through the platform's own clipboard tool first (`pbcopy`, `wl-copy`,
 `xclip`, `xsel`) and falls back to OSC 52, which is also always sent over SSH so
 the text lands on the machine you are actually sitting at.
 
-Because `ctrl+c` clears the prompt, drag-selecting in the transcript is your
-terminal's own selection rather than the TUI's — use your terminal's copy key
-for that. HX does not emit OSC 133 prompt markers yet, so shell-integration
-features that jump between prompts will not see HX's messages.
+Drag-select in the transcript and `ctrl+c` copies the selection — assistant
+prose and tool output included. With nothing selected, `ctrl+c` keeps its usual
+meaning and clears the prompt. See [Selecting and copying
+text](#selecting-and-copying-text) for the terminal's own selection.
+
+HX does not emit OSC 133 prompt markers yet, so shell-integration features that
+jump between prompts will not see HX's messages.
 
 #### Keybindings
 
@@ -319,6 +387,7 @@ than being silently resolved.
 |---|---|
 | `/model [query]` | pick a model; shows context window, price per Mtok, cache support |
 | `/models refresh` | re-fetch the catalogue |
+| `/effort [level]` | how hard a reasoning model thinks, from the levels it offers |
 | `/configure` | session settings and the API key |
 | `/login [provider]` | sign in to a model route |
 | `/logout <provider>` | forget a stored credential |
@@ -332,17 +401,71 @@ than being silently resolved.
 | `/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 |
+| `/todos` | show the current plan |
 | `/skills` | installed skills |
 | `/agents` | subagent types |
 | `/mcp` | server status |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
 | `/copy` | copy the last reply to the clipboard |
-| `/init` | generate an `HX.md` for the project |
+| `/fullscreen [on\|off]` | take the whole window, with the prompt pinned to the bottom |
+| `/mouse [on\|off]` | mouse reporting, and with it your terminal's own text selection |
+| `/init` | generate an `AGENTS.md` for the project |
 | `/help` | list commands and keys |
 | `/quit` | exit (also `/exit`, `/q`) |
 
+### The two screens
+
+By default HX draws into your terminal's own scrollback. Finished output belongs
+to the terminal while the session runs: it scrolls it, selects it, copies it and
+pipes it. Nothing is repainted above the fold, so a long session costs the same
+to draw as a short one.
+
+The prompt and the status bar still open on the bottom row of the window: a
+conversation too short to fill the screen is padded above them rather than
+below, so the dock stays where you last saw it instead of creeping down the
+screen a block at a time. The padding is gone by the time the terminal starts
+scrolling.
+
+Leaving takes the whole interface off the screen: the banner, the conversation
+and the dock are erased and your shell prompt comes back on the row HX started
+on, the terminal as it was found. The erase stops at the top of the window -
+lines that had already scrolled above it stay in your scrollback, because the
+only sequence that reaches them takes everything the terminal remembers,
+including what was there before HX ran. `/clear` is the command that asks for
+that.
+
+`/fullscreen` switches to the alternate screen instead - the whole window, the
+prompt pinned to the bottom row, the transcript scrolling above it with `pgup`,
+`pgdn`, `ctrl+home` and `ctrl+end`. The trade is the thing the default was
+chosen for: the alternate screen is not scrollback, so your terminal cannot
+scroll or select it, and it is gone when HX exits. `/fullscreen off` gives it
+back, and either way the choice is written to `tui.fullscreen` for the next
+session. Quitting from fullscreen leaves the same clean terminal as quitting
+from the default screen: the alternate screen goes, and so does the frame HX
+had drawn underneath it before the switch.
+
+`/clear` wipes the screen and the scrollback above it. Terminals that do not
+implement scrollback erasure - macOS Terminal.app is the one people hit - clear
+the screen only, and the old conversation stays above it until you clear it the
+terminal's own way (`cmd+k`).
+
+### Selecting and copying text
+
+Drag to select and `ctrl+c` to copy. HX copies through `pbcopy`, `wl-copy` or
+`xclip` first and falls back to OSC 52, so it works in terminals that ignore
+OSC 52 - macOS Terminal ignores it outright, and iTerm2 ships with it off. The
+notice says which mechanism took the text, so a copy that did nothing says so.
+
+While HX is running, the terminal reports mouse events to it, which means the
+terminal's *own* click-and-drag selection is unavailable. Two ways around that:
+
+* Hold `alt`/`option` while dragging. Most terminals - macOS Terminal, iTerm2,
+  GNOME Terminal - take that as "this drag is mine", and you get the native
+  selection without changing anything.
+* `/mouse off` turns mouse reporting off for the session. Native selection comes
+  back everywhere, and HX stops seeing scroll and clicks until `/mouse on`.
+
 ### Steering a running turn
 
 Type while HX is working and `enter` queues the message: it runs when the turn
@@ -373,18 +496,27 @@ collapses after an edit is the visible symptom of a broken prefix.
 Settings are JSON, merged lowest to highest:
 
 ```
-defaults  <  ~/.hx/settings.json  <  ./.hx/settings.json  <  ./.hx/settings.local.json  <  HX_* env  <  CLI flags
+defaults  <  ~/.hx/settings.json  <  ./.hx/settings.json  <  ~/.hx/projects/<project>/settings.local.json  <  HX_* env  <  CLI flags
 ```
 
 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.
 
-`./.hx/settings.json` is the project's shared file, yours to check in.
-`./.hx/settings.local.json` is this machine's, and it is where HX writes
-anything it decides on your behalf - an "always allow" grant, for one. HX adds
-a `.hx/.gitignore` covering it the first time it writes there, so your grants
-stay out of the repo.
+`./.hx/settings.json` is the project's shared file, yours to check in, and
+nothing writes to it but you — HX only ever reads it. Versions before the local
+layer existed did append grants there; those are lifted out into the file below
+on the next run, once, and a rule you put back by hand afterwards stays put.
+Only `allow` moves: a project's `deny` and `ask` are the guardrails it shares,
+and HX never wrote them.
+
+Anything HX decides on your behalf - an "always allow" grant, for one - goes in
+`~/.hx/projects/<project>/settings.local.json` instead. Still per project,
+because a grant is: allowing `pytest` in one repo should not allow it
+everywhere. But under your home rather than in the checkout, so HX never leaves
+a file in your repository for you to find in a diff. If an older version
+already wrote `./.hx/settings.local.json`, it is moved there on the next run,
+along with the `.hx/.gitignore` it added to hide it.
 
 ```jsonc
 {
@@ -397,7 +529,9 @@ stay out of the repo.
     "subagent_model": null,           // defaults to "model"
     "title_model": null,              // model that names sessions; defaults to "model"
     "max_tokens": 8192,
-    "temperature": null
+    "temperature": null,
+    "reasoning_effort": null,         // Codex route: null = the model's own default
+    "codex_models": []                // extra Codex ids, e.g. ["gpt-5.6-terra"]
   },
 
   "permissions": {
@@ -429,7 +563,8 @@ stay out of the repo.
   },
 
   "tui": {
-    "enterWhileBusy": "queue"         // queue | steer - what enter does mid-turn
+    "enterWhileBusy": "queue",        // queue | steer - what enter does mid-turn
+    "fullscreen": false               // true takes the whole window (see /fullscreen)
   }
 }
 ```
@@ -461,7 +596,7 @@ Appended text is added after whichever prompt won, in this order:
 `--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
+This is a different lever from `AGENTS.md`: `AGENTS.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
@@ -512,14 +647,14 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | `~/.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/settings.local.json` | this machine's project settings, never checked in - where "always allow" lands |
+| `~/.hx/projects/<project>/settings.local.json` | this machine's settings for one project - where "always allow" lands |
+| `./.hx/settings.json` | project settings, checked in if you like — read by HX, never written |
 | `./.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 |
+| `./AGENTS.md` | project instructions, loaded into every session |
 
-`HX.md` is the place for things a newcomer would get wrong: how to run the
+`AGENTS.md` is the place for things a newcomer would get wrong: how to run the
 tests, conventions, what not to touch. `/init` writes a first draft. It is
 loaded once per session and frozen, so it costs one prefix, not one per turn.
 
@@ -701,7 +836,8 @@ src/hx/
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
   skills/ agents/ mcp/
   keys.py       keybinding registry: ids, defaults, descriptions, user overrides
-  tui/          Textual app, commands, per-tool renderers, widgets
+  term/         the renderer: raw mode, input decoding, the differ, the screen
+  tui/          views, commands, per-tool renderers, themes
     themes/     the shipped palettes, as JSON
 ```
 
@@ -737,11 +873,13 @@ 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.
+skips it cannot get past CI to the `publish` job. The file ships inside the
+wheel and `hx changelog` prints it, so a version with no section there reaches
+users as a blank release.
 
 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.
+suite and an install-script run in a clean Debian container have passed. It builds with
+`uv build` and uploads via OIDC.
 
 To check a build before tagging: