gh-glance 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,213 @@ All notable changes to this project are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-08-04
+
+Findings from a cross-functional audit, filtered hard: everything that would
+have added a release gate, a branch-protection rule or more test-harness
+machinery was rejected outright. What is left is behaviour you can see.
+
+### Added
+
+- **`?` shows the keys without leaving the dashboard.** Paging, `j`/`k`,
+  `Shift+Tab` and the cursor timeout existed only in `--help` and the README --
+  and because this is a full-screen app, reading `--help` meant quitting it
+  first. Any key closes the overlay. `--help`, the overlay and the status-bar
+  hints are now generated from one table, so a binding cannot go missing from one
+  of them.
+- **The panel names the repository** when it was chosen explicitly through
+  `--repo` or `GH_REPO` -- `╭─ Actions · acme/widget ─`. With several panes open,
+  or after changing directory, nothing on screen said which repository a pane was
+  watching. Dropped before the tab name when the pane is too narrow for both.
+- **`--doctor` reports API budget**: REST and GraphQL headroom straight from
+  GitHub, plus what this configuration will actually spend per hour. The steady
+  cost is not small and was invisible -- roughly 2,200 REST requests an hour at
+  the default refresh with the Security tab open, about 44% of a personal token's
+  allowance, and `--refresh 2` projects past the limit outright. `gh api
+  rate_limit` does not itself count against the limit.
+- **Native test coverage is measured and reported.** `npm run test:coverage`
+  runs the unit suite under Node's built-in coverage, and a nightly workflow
+  publishes the figure to the portfolio endpoint. The delivery script fails
+  closed on purpose: every input is required and a parse failure is an error
+  rather than a reported zero, so a broken producer cannot quietly claim perfect
+  coverage. Not wired into branch protection -- it reports, it does not gate.
+- **A first-run hint when icons may be blank.** Without a Nerd Font every status
+  icon renders as an empty box, which reads as a broken program rather than a
+  missing font, and the fix was documented only in places you had to quit to
+  read. Shown for the second the first fetch takes, and only when the Nerd glyphs
+  are actually in use.
+
+### Fixed
+
+- **The `stale` indicator no longer fires on a repository that is simply quiet.**
+  Freshness was recorded only when the payload *changed*, and the whole point of
+  the poll loop is that an unchanged payload short-circuits before that write --
+  so on any calm repo the timestamp froze and the status bar accrued a growing
+  `stale 2h13m` while every poll was succeeding on schedule. It now records the
+  last successful *poll*. The warning fired loudest in the one state that was
+  completely healthy, which is the fastest way to teach someone to ignore it.
+- **A tab whose fetch keeps failing no longer animates forever.** `setData` only
+  runs on success, so a tab that never succeeded stayed in its first-load state
+  permanently: the spinner ran at full rate for the life of the process while the
+  body rendered "loading actions…" directly above the error explaining that it had
+  failed. Measured at 7.8% of a core and 9.8 MB/hr of terminal writes,
+  indefinitely, triggered by something as ordinary as closing a laptop lid.
+  Motion now means "still working"; the error line means "not working".
+- **`Enter` is guarded against key repeat.** Holding it down spawned a
+  `gh <kind> view --web` per repeat event -- roughly thirty a second -- each
+  opening another browser tab. The `r` key beside it had this guard all along.
+- **The status bar adapts to narrow panes.** It was the only band that did not:
+  the table swaps to a compact header, the tab bar to short labels, the panel
+  edges drop their labels, and the status bar just let ink truncate. Because each
+  hint truncates individually the loss was silent -- at 45 columns the bar read
+  `Move: | Open:  | Refresh |Quit:…`, dropping the arrows, `Refresh`'s key, and
+  most of `Quit`, which is the one hint someone stuck in a full-screen app needs.
+  It now falls back to `↑↓ Ent r q`, which keeps every key.
+- **`--doctor` no longer prints the value of environment variables it was never
+  told about.** It discovers every `GH_*`/`GITHUB_*` variable that is set, and
+  printed the value of any whose *name* did not end in `_TOKEN`/`_SECRET`/
+  `_PASSWORD`/`_KEY` -- so `GH_APP_PEM` (an entire RSA private key) and
+  `GITHUB_OAUTH` were reproduced in full, in the one report that says it is safe
+  to paste into a bug report. Printing a value is now opt-in and the list is
+  curated; anything discovered reports `set` or `not set`.
+- **`--doctor --verbose` produces the log it advertises.** argv was applied to
+  runtime state in two places and they had drifted, so the doctor path silently
+  dropped `--verbose`, `--refresh` and `--tab`. There is one application site now.
+- **The 60s cursor clear no longer costs you your place.** Clearing the selection
+  left the scroll offset behind, and the next arrow key seeded from the top of the
+  list -- so scrolling to row 80 of 150, reading for a minute and pressing down
+  put you back at row 1, with no scroll animation to notice. Movement now seeds
+  from what is on screen.
+- **`safe()` sanitizes non-string input.** It returned early for anything that
+  was not a string, skipping both the control-character strip and the length
+  clamp -- the guarantee was being provided by GitHub's schema rather than by the
+  function that claims to provide it.
+- **The `!` "CI is red" marker stays in the tab bar**, where a label anchors it,
+  instead of also being interpolated into the frame's bottom edge as `4 of 4!`.
+- **A blind Security tab no longer reports a confident zero.** When all three
+  alert endpoints fail -- an expired SAML session, a token without
+  `security_events`, an org OAuth restriction -- the tab rendered
+  `4:Security (0)`, byte-identical to a genuinely clean repository, on the one
+  surface where a false all-clear is the worst available answer. It now reads
+  `(?)`. A repository that simply has Advanced Security switched off is a
+  different thing and stays quiet, because that is an answer rather than an
+  absence of one.
+- **A failing tab backs off instead of re-spawning `gh` every tick.** The three
+  list tabs had no backoff at all, so a wedged tab launched a subprocess every
+  five seconds indefinitely -- 720 an hour against a token already refusing --
+  and rate limiting was deliberately excluded from the ladder that did exist,
+  which had it backwards: GitHub's secondary limiter keys on sustained rate
+  against a limited *token*, so hammering can turn a self-clearing limit into a
+  longer block that also hits `git push`. Measured: two `gh run list` calls in
+  forty seconds where there were eight. The `r` key bypasses and clears the
+  backoff, because a refresh that silently declines to refresh would be worse
+  than no key at all.
+- **Errors on the Actions, Issues and PR tabs say what to do.** They rendered raw
+  `gh` stderr while the Security tab one across had been classifying the same
+  failures into remedies all along. An expired token now reads "GitHub
+  authorization failed -- try `gh auth login` or `gh auth refresh`". Unclassified
+  failures still show their real message: inventing a remedy for something
+  nobody recognised would be worse than showing what happened.
+- **Bidi override characters are stripped from remote text.** `U+202A`-`U+202E`
+  and the isolates measure as zero columns, so they cost no width and survived
+  truncation -- one `RLO` in an issue title makes the rest of that cell render
+  reversed on any terminal with bidi reordering, which is the same "the row does
+  not show its data" failure the control-character strip already prevents.
+  Deleted rather than replaced with a space, because they measure zero and a
+  space would shift every cell to its right. Genuine RTL, `LRM`, emoji, ZWJ
+  sequences and CJK are untouched.
+- **`REPO_PATTERN` rejects `owner/..`.** It reached the API path, and `gh`
+  forwards the dot segment unnormalized, so GitHub resolved it to a different
+  endpoint than the one intended. Names that merely contain or start with a dot
+  -- `owner/.github` -- are still valid.
+- **Backoff deadlines use a monotonic clock.** They measure elapsed time, and a
+  laptop resume or an NTP step could hold an alert source in backoff for an hour
+  of apparent time that never passed. Staleness deliberately stays on wall-clock
+  time, because a sleep gap is exactly what it exists to report.
+- **A crash no longer orphans `gh` children.** The handlers exited without
+  unmounting, so the cleanup that aborts in-flight subprocesses never ran. Both
+  the crash output and the `--verbose` log are now redacted, like `--doctor`
+  already was -- all three are artifacts users are told to attach to bug reports,
+  and `gh` error messages quote the URL they failed on.
+
+### Changed
+
+- **The spinner runs at 200ms rather than 100ms.** It is the single largest CPU
+  term in the app, because every frame makes ink rebuild and diff the whole
+  output string: measured 7.8% of a core at 100ms against 3.9% at 200ms, on a
+  0.33% idle floor. The motion is load-bearing -- it is the only thing separating
+  an executing run from a queued one -- so it is slowed, never stopped.
+- **Only an executing Actions row receives the spinner frame.** It went to every
+  visible row, so a prop changing several times a second defeated row
+  memoisation for all of them: 7,960 row renders over 20 seconds against 238.
+- **The panel names the repository** when it was chosen explicitly via `--repo`
+  or `GH_REPO` -- `╭─ Actions · acme/widget ─`. With several panes open, or after
+  changing directory, nothing on screen said which repository a pane was watching.
+  It is dropped before the tab name when the pane is too narrow for both.
+- **Column density is decided per tab.** One global breakpoint meant the widest
+  tab decided for the narrowest: Pull requests needs 61 columns and Security only
+  44, so Security dropped two columns a full 17 columns before it had to. Only
+  one tab is on screen at a time, so there is nothing to be inconsistent with.
+- **Below 24 columns the pane says "too narrow"** instead of rendering a table
+  that cannot fit. Under that width even the compact columns overflow, which
+  hard-wraps every row and drives ink into repainting the whole screen each
+  frame -- reachable just by dragging a sidebar narrow. Widening recovers
+  immediately.
+- **The Security tab collapses its not-enabled notes into one line.** Each
+  unavailable alert source took a full row above the column header, so any
+  repository without Advanced Security permanently spent two rows -- about a
+  tenth of a twenty-row pane -- restating a fact that will never change, on the
+  tab meant to make real alerts stand out. Failures that are not "not enabled"
+  keep their own lines, because those are actionable and transient.
+- **Alert ordering is pinned rather than left to each endpoint's default.**
+  Severity ranking runs over one page, so the page boundary decides what can be
+  ranked at all -- a critical alert sitting past it was never fetched, and the
+  pane showed "100+" with a screen of moderates. Newest-first at least makes the
+  cut deterministic.
+- **`-v` is no longer an alias for `--version`.** This CLI also has `--verbose`,
+  so `gh-glance -v 2>log` -- what you type when you want the log -- printed a
+  version string and exited 0. The argv surface exists to make typos fail loudly,
+  and this was the one flag that failed quietly. `--version` is unaffected.
+
+### Documentation
+
+- **Corrected a claim this project made about itself in 0.4.0 and repeated in the
+  0.4.1 release notes.** The status bar's `↑↓` glyphs were described as "a
+  deliberate, tested exception" whose double-width rendering "fails loudly" under
+  `npm run test:pty`. No such assertion exists or could: each hint truncates
+  individually, so the failure mode is silent text loss rather than overflow, and
+  at 80 columns the panel border is 79 cells against a 54-cell status bar, so the
+  bar never sets the maximum a width check would measure. The glyphs are fine;
+  the guarantee was not real, and a comment asserting coverage that does not
+  exist is worse than an acknowledged gap.
+- The README no longer claims every run state has a distinct glyph under
+  `NO_COLOR`. Timed-out, action-required and running share one, as do skipped,
+  neutral, stale and queued. The tab bar's `!` marker is what actually answers
+  "is CI red" without colour, and it does.
+- `eslint.config.js` no longer describes an inline `exhaustive-deps` suppression
+  that has never existed; the rule is now an error, which it can be precisely
+  because there is nothing to suppress.
+
+## [0.4.1] - 2026-08-04
+
+Two fixes to the interactive surface: a selection marker that outlived its
+usefulness, and a key hint that named the wrong keys.
+
+### Fixed
+
+- **The row cursor clears itself after 60s without movement.** Once you pressed
+  a movement key the selection marker stayed on screen until you quit, so a pane
+  left in the corner of a screen sat there marked at something you had stopped
+  caring about an hour ago. Any movement key rearms the timer; expiry clears the
+  cursor on every tab, not just the visible one.
+- **The `Move` hint in the status bar reads `↑↓` rather than `jk`.** The hints
+  are otherwise strictly width-1 ASCII, because East-Asian-Ambiguous glyphs
+  measure as two columns in ink's width model and overflowed an 80-column
+  terminal once before. The arrow pair is a deliberate exception: the pty suite
+  asserts the rendered frame stays inside the terminal width, so a font that
+  renders them double-width fails there loudly instead of shifting columns
+  silently.
+
 ## [0.4.0] - 2026-08-04
 
 Correctness on GitHub Enterprise and Enterprise Managed Users tenants, and a
@@ -309,6 +516,8 @@ engineering, security, QA and UX. What follows is what changed as a result.
 - The `main` field from `package.json`. It advertised the file as importable,
   but importing it took over the terminal or exited the host process.
 
+[0.5.0]: https://github.com/juan294/gh-glance/releases/tag/v0.5.0
+[0.4.1]: https://github.com/juan294/gh-glance/releases/tag/v0.4.1
 [0.4.0]: https://github.com/juan294/gh-glance/releases/tag/v0.4.0
 [0.3.1]: https://github.com/juan294/gh-glance/releases/tag/v0.3.1
 [0.3.0]: https://github.com/juan294/gh-glance/releases/tag/v0.3.0

package/README.md

@@ -30,17 +30,19 @@ without switching to the browser.
 │                                                                          │
 │                                                                          │
 ╰───────────────────────────────────────────────────────────────── 4 of 4 ─╯
-⣾ Fetching            Move: jk | Open: Ent | Refresh: r | Quit: q
+⣾ Fetching  Move: ↑↓ | Open: Ent | Refresh: r | Quit: q
 ```
 
 > Captured from a real run at 76 columns with `GH_GLANCE_ICONS=unicode`, so the
 > status icons render in a browser. With a Nerd Font (the default) they are
 > Octicon glyphs instead.
 >
-> The `>` on the first row is the cursor. Two more markers appear when they
+> The `>` on the first row is the cursor. Three more markers appear when they
 > apply: a `+` after a tab's count means the list was truncated by the fetch
-> limit, and a `!` after the Actions count means the newest run failed — so
-> "is CI red" is answerable without switching to that tab.
+> limit, a `!` after the Actions count means the newest run failed — so "is CI
+> red" is answerable without switching to that tab — and a `?` in place of the
+> Security count means its endpoints could not be read, which is not the same
+> as there being nothing to report.
 
 <!-- contract:allow-emoji -- the check/cross above stand in for Nerd Font
      Octicons the app actually draws; they are literal examples, not decoration. -->
@@ -64,20 +66,26 @@ current.
   (approved / changes requested / pending), age
 - **Security** -- open Dependabot alerts: package, summary, age, sorted with the
   most severe first and with severity spelled out in its own column, not carried
-  by colour alone.
+  by colour alone. One page of 100 newest alerts is fetched and ranked, so on a
+  repository with more open alerts than that the ranking covers the newest 100
+  rather than everything -- the `+` marker on the count is what tells you.
   Code scanning and secret scanning alerts are included too, on repos/plans
   that have GitHub Advanced Security enabled -- see [Limitations](#limitations).
 - Tab bar with live counts, pinned to the top of the pane above a divider,
   switchable via `1`-`4`, arrow keys, or `Tab`/`Shift+Tab`
 - `lazygit`-style panel frame: the tab name sits in the top border, the
   visible-of-total row count in the bottom
-- A spinning `Fetching` indicator while a refresh is in flight, so the pane
-  says when it's working without spending a line on it
+- A `Fetching` indicator that brightens on every refresh and animates during the
+  first load or while a workflow run is executing, so the pane says when it's
+  working without spending a line on it
 - Status icons are real GitHub Octicons (via the Nerd Font glyph set), not emoji
   -- with a plain-ASCII fallback for terminals without one
-- Readable without colour: severity has its own column, run states have distinct
-  glyphs, and the active tab is bracketed, so `NO_COLOR=1` and colour-vision
-  deficiency both stay navigable
+- Readable without colour: severity has its own column, a failing newest run puts
+  a `!` on the Actions tab, and the active tab is bracketed, so `NO_COLOR=1` and
+  colour-vision deficiency both stay navigable. Run-state *glyphs* are not all
+  distinct -- timed-out, action-required and running share one, as do skipped,
+  neutral, stale and queued -- so the tab marker, not the row icon, is what
+  answers "is CI red" without colour
 - Says when it is stale rather than showing old data silently, and marks a tab
   whose last refresh failed
 - Adapts row count to the terminal pane's height live, on resize
@@ -187,11 +195,19 @@ stdout isn't a terminal rather than streaming redraw frames into a pipe.
 | `PgUp` / `PgDn` | Move a page at a time |
 | `Enter` | Open the selected item in your browser |
 | `r` | Refresh the current tab now |
+| `?` | Show the keys without leaving the dashboard (any key closes it) |
 | `q` / `Esc` / `Ctrl+C` | Quit |
 
 The cursor tracks the *item*, not the row position, so it stays on what you
 selected as new rows arrive above it. `Enter` works on Actions, Issues and Pull
-Requests; the Security tab has no per-alert `gh` command to open.
+Requests; the Security tab has no per-alert `gh` command to open. It clears
+itself after 60s with no cursor movement, so a pane left idle in the corner of
+a screen doesn't sit there marked forever -- and the next arrow key picks up
+from what is on screen rather than jumping back to the top of the list.
+
+When the repository was chosen explicitly, with `--repo` or `GH_REPO`, the panel
+says so: `╭─ Actions · acme/widget ─`. That is what tells two side-by-side panes
+apart. It is dropped before the tab name when the pane is too narrow for both.
 
 If `gh-glance` is started without an interactive stdin (for example with stdin
 redirected), the key handlers cannot run and the status bar shows only `Quit: ^C`
@@ -221,7 +237,7 @@ Environment variables work too, and the flags take precedence:
 | `GH_TOKEN`, `GH_ENTERPRISE_TOKEN`, `GH_CONFIG_DIR` | Not read by `gh-glance` -- passed through to `gh` untouched, along with the proxy variables. `gh-glance` handles no credentials of its own |
 | `GH_GLANCE_ICONS=unicode` | Plain ASCII status icons, for terminals without a Nerd Font |
 | `GH_GLANCE_NO_ANIMATION=1` | Freeze the spinner — no motion at all |
-| `NO_COLOR=1` | Disable colour. Status stays readable: severity has its own column, run states have distinct glyphs, and the active tab is bracketed |
+| `NO_COLOR=1` | Disable colour. Status stays readable: severity has its own column, a failing newest run puts a `!` on the Actions tab, and the active tab is bracketed. Note that run-state glyphs are not all distinct -- see the feature list above |
 | `INK_SCREEN_READER=true` | Switch the renderer to a linear, unthrottled mode. The status icons carry text labels for it, but this path has not been tested against a real screen reader — treat it as unverified rather than supported. |
 
 ## GitHub Enterprise and EMU
@@ -265,36 +281,55 @@ gh-glance --doctor > report.txt
 
 Collects, in one plain-text block: the `gh-glance`, Node and `gh` versions;
 which hosts `gh` is authenticated for; how the repository target resolved and
-from where; the relevant environment variables; and one probe per endpoint with
-the exact argv it sent, its outcome, and how any error was classified
-(`unavailable`, `rate-limited`, `auth-problem` or `other`).
+from where; your remaining REST and GraphQL budget plus what this configuration
+will spend per hour; the relevant environment variables; and one probe per
+endpoint with the exact argv it sent, its outcome, and how any error was
+classified (`unavailable`, `rate-limited`, `auth-problem` or `other`).
+
+Add `--verbose` to get a log of every `gh` call it makes alongside the report.
 
 It exits 0 and prints a report even when `gh` is missing or you are outside a
 git repository -- those are conditions worth reporting rather than failing on --
 and it works through a pipe, unlike the dashboard itself.
 
-**Tokens are never printed.** Token-valued environment variables are reported
-as `set` or `not set` and never by value, not even a prefix; anything
-token-shaped anywhere in the captured text is replaced; proxy and remote URL
-credentials are stripped to scheme and host; and no API response bodies are
-included, only their sizes. The report is safe to attach to a bug report.
+**Values are printed only for variables on a short curated list** -- the ones
+that are the thing being diagnosed, like `GH_HOST`, `GH_REPO` and `NO_COLOR`.
+Everything else it finds, including any `GH_*`/`GITHUB_*` variable it was never
+told about, is reported as `set` or `not set` and never by value. On top of
+that: anything token-shaped anywhere in the captured text is replaced, proxy and
+remote URL credentials are stripped to scheme and host, and no API response
+bodies are included, only their sizes. The report is safe to attach to a bug
+report, and the same redaction covers the `--verbose` log and the message
+printed if `gh-glance` crashes.
 
 ## Rate limit
 
 The visible tab refreshes every 5 seconds; the other three refresh every 60
 seconds, purely to keep their counts honest.
 
-With Actions, Issues or Pull Requests as the visible tab that works out at
-roughly 1,000 REST requests an hour — about 20% of the 5,000/hour
-authenticated limit. The Security tab is the expensive one, because it is
-three endpoints rather than one: watching it costs roughly 2,300 an hour,
-just under half the budget.
-
-Two things pull the real number down. An endpoint that is not enabled for the
-repository — code scanning and secret scanning without Advanced Security —
-backs off after its first refusal rather than being re-asked every tick, which
-removes two of the Security tab's three calls. And `--refresh` scales the
-whole figure: doubling the interval halves it.
+The tabs do not all draw on the same budget. Actions and Security spend REST
+calls; Issues and Pull Requests are sorted with `--search`, which routes them
+through GraphQL instead — a separate 5,000/hour allowance. With the default
+5-second refresh:
+
+| Visible tab | REST / hour | GraphQL / hour |
+|---|---|---|
+| Actions | ~900 | ~240 |
+| Issues or Pull Requests | ~240 | ~1,560 |
+| Security | ~2,220 | ~240 |
+
+Security is the expensive one because it is three endpoints rather than one,
+and watching it costs just under half the REST budget. You do not have to take
+these figures on trust: `gh-glance --doctor` reports your actual remaining
+budget alongside what your configuration projects, which matters on a GitHub
+Enterprise tenant where the ceiling may not be 5,000 at all.
+
+Two things pull the real number down. Any endpoint that fails in a way
+`gh-glance` recognises backs off instead of being re-asked every tick — a
+feature that is not enabled for the repository retries on a ladder up to an
+hour, an authorization failure every 30 seconds, a rate limit every minute.
+Pressing `r` clears that backoff and retries immediately. And `--refresh`
+scales the whole figure: doubling the interval halves it.
 
 So a pane left open all day shares the budget with your other `gh` commands
 rather than exhausting it, but it is not free, and parking it on the Security
@@ -306,19 +341,29 @@ tab is the case worth knowing about.
 - **Security tab**: code scanning and secret scanning alerts require [GitHub
   Advanced Security](https://docs.github.com/en/code-security/getting-started/github-security-features).
   On repos/plans without it, `gh-glance` doesn't crash or spam errors -- it
-  shows a one-line note per unavailable feature and still displays whatever
-  it *can* get (Dependabot alerts work independently of GHAS). If your repo
-  has GHAS enabled, those alerts just show up automatically -- no
-  configuration needed.
+  says so in a single collapsed line -- `Code scanning, Secret scanning: not
+  enabled here` -- and still displays whatever it *can* get (Dependabot alerts
+  work independently of GHAS). If your repo has GHAS enabled, those alerts just
+  show up automatically -- no configuration needed.
+
+  If the alert endpoints cannot be read at all -- an expired SAML session, a
+  token without `security_events`, an org OAuth restriction -- the tab count
+  shows `?` rather than a number. A blind Security tab and a clean one are not
+  the same thing, and reporting `0` for both would be the worst available
+  answer on that particular surface.
 - Scrolling moves through what was fetched, not through everything on GitHub.
   Issues and Pull Requests fetch 150, so there is real range there. Actions
   deliberately fetches about a screenful -- its cost is linear in the number of
   runs requested -- so scrolling that tab has little to move through. The count
   in the bottom edge always says how much you are seeing out of how much was
   fetched.
-- **Minimum width.** Below about 61 columns the table drops to a compact layout
-  (icon, title, and one other column) so the frame, tab bar and status line stay
-  on screen. Below about 24 columns it will not lay out sensibly.
+- **Minimum width.** Each tab drops to a compact layout (icon, title, and one
+  other column) at its own threshold, so a narrow pane keeps as much as that
+  particular tab can fit: Security holds its full set down to 44 columns,
+  Issues to 50, Actions to 56, Pull Requests to 61. Below 24 columns nothing
+  useful fits, so the pane says `too narrow` and keeps the frame, tab bar and
+  quit hint; widening it recovers immediately. The status bar has its own
+  breakpoint and drops to bare keys (`↑↓ Ent r q`) rather than truncating.
 - Issues and pull requests are fetched 150 at a time and alerts 100 at a time.
   A count is shown as `n+` when it was truncated, so the number is never
   presented as exact when it is not.
@@ -361,10 +406,13 @@ in some terminals, which would shift every column to their right.
 | `none of the git remotes ... point to a known GitHub host` | `gh` is not authenticated for that host. Run `gh auth login --hostname <host>`. |
 | Security tab empty on an enterprise host, other tabs fine | The alert endpoints were sent to the wrong host. Use `--repo host/owner/name` or set `GH_HOST` -- a host-qualified `GH_REPO` alone does not route them. |
 | Tabs start failing after working for a while | The enterprise SAML session lapsed. Re-authorize in the browser; the dashboard recovers within about 30 seconds. Run `gh-glance --doctor` to confirm. |
-| A tab's count is red | That tab's last fetch failed. The error itself is shown when you switch to it. |
+| A tab's count is red | That tab's last fetch failed. The error itself is shown when you switch to it, translated into what to do about it where `gh-glance` recognises the failure. |
+| Security tab shows `?` instead of a number | The alert endpoints could not be read at all -- an expired SAML session, a token without `security_events`, or an org OAuth restriction. `?` means "unknown", not "zero"; run `gh-glance --doctor` to see which probe failed and how it was classified. |
+| A failing tab seems to have stopped retrying | It backs off deliberately, rather than re-spawning `gh` every five seconds against an endpoint that is refusing. Press `r` to clear the backoff and retry now. |
+| `unknown argument: -v` | `-v` used to mean `--version` and no longer does, because this CLI also has `--verbose`. Use `--version` or `--verbose` explicitly. |
 | `stale 2m` in the status bar | The visible tab has not refreshed successfully for a while — usually a network drop. |
 | It exits immediately when piped | Intentional. It is a full-screen dashboard, not a reporting command. |
-| It stopped updating and you cannot tell why | Run `gh-glance --verbose 2>gh-glance.log`, reproduce, then read the log: one line per `gh` call with its duration and outcome. Attach it to a bug report. |
+| It stopped updating and you cannot tell why | Run `gh-glance --verbose 2>gh-glance.log`, reproduce, then read the log: one line per `gh` call with its duration and outcome. It is redacted the same way `--doctor` is, so it is safe to attach to a bug report. `--doctor --verbose` logs the probes too. |
 | `--verbose` refuses to start | stderr is still your terminal, where the log would draw over the dashboard. Redirect it to a file. |
 
 ## Contributing