gh-glance 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,200 @@
+# Changelog
+
+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.3.0] - 2026-08-03
+
+The dashboard stops being read-only: you can now move through the table and open
+what you are looking at. The rest of the release is the audit backlog `0.2.0`
+deferred — a configuration surface, structural refactors, and the first tests
+that drive the real binary under a terminal.
+
+### Added
+
+- **Row selection, scrolling, and opening items in a browser.** `↑`/`↓` or
+  `j`/`k` move a cursor, `PgUp`/`PgDn` move a page, and `Enter` opens the
+  selected run, issue or pull request. The cursor tracks the item rather than
+  the row position, so it stays put as new rows arrive above it rather than
+  drifting every few seconds. The marker is a plain `>` sharing the existing
+  icon column, so it survives `NO_COLOR` and costs no width.
+- **Flags: `--repo`, `--refresh`, `--tab`, `--verbose`.** The tool still takes no
+  arguments by default. `--repo owner/name` watches a repository you have not
+  cloned, and works from any directory. `--refresh` sets the active-tab interval
+  between 2 and 3600 seconds — below two a fetch cannot finish before the next
+  tick, so the value would silently stop being real, and it is refused rather
+  than accepted. `--tab` picks the starting tab. An unrecognised flag still
+  exits 2 rather than being ignored.
+- **`--verbose`** writes one line per `gh` invocation to stderr with its duration
+  and outcome, for attaching to a bug report. It refuses to start while stderr
+  is still a terminal, because the log would otherwise be drawn over the
+  dashboard.
+- A pty end-to-end harness (`npm run test:pty`). It drives the real binary under
+  a pseudo-terminal against a fixture `gh`, and asserts the things unit tests
+  structurally cannot reach: that the alternate screen is entered and left
+  exactly once, that the cursor is restored, that the final frame is exactly as
+  tall as the terminal and never wider, that a narrow pane still draws its
+  chrome, that signal exit codes are 143/130/129, and that nothing is left on
+  the primary buffer afterwards. It runs in CI as an advisory check.
+
+### Changed
+
+- **Terminal traffic roughly halved.** The renderer now updates only the lines
+  that changed instead of rewriting the whole viewport: measured 13,918 bytes
+  down to 6,799 on a settled 80x24 pane.
+- Rows are memoised and the spinner frame is no longer handed to the three tabs
+  that ignore it, so a running workflow animates one glyph instead of
+  reconciling every row ten times a second.
+- The Actions tab count carries a `!` when the newest run failed, so "is CI red"
+  is answerable from any tab rather than only from that one.
+- The status bar's key hints are plain ASCII. The arrows, return symbol and
+  box-drawing separator it used are East-Asian-Ambiguous, which the renderer
+  measures as two columns each — enough to overflow an 80-column terminal once
+  selection added a hint.
+- The four fetchers are driven by one registry rather than four near-identical
+  functions, colours are named rather than repeated as literals, and the
+  terminal-size hook is extracted. No behaviour changed.
+- Installing from a git URL or a local directory no longer writes git hooks.
+- `develop` is now PR-only, admin-enforced, with eight required checks. Its
+  previous protection required an approving review that a solo maintainer could
+  not give, so every commit had been landing as a direct push and the required
+  checks gated nothing.
+
+### Fixed
+
+- **`kill` no longer erases your terminal scrollback.** On `SIGTERM`, `SIGINT`
+  and `SIGHUP` the dashboard handed the terminal back to the primary buffer and
+  the renderer then repainted onto it — preceded by an erase-scrollback escape,
+  so a `kill` threw away the terminal history and left a dead dashboard frame
+  behind. Measured at 2,728 bytes on an 80x24 pane. Quitting with `q`, `Esc` or
+  `Ctrl+C` was never affected. Found by the new pty harness; present since
+  before 0.2.0.
+
+## [0.2.0] - 2026-08-03
+
+First release. `0.1.0` was never published to any registry and was never
+tagged, so this is the first version with an artifact behind it.
+
+The bulk of this entry comes from a pre-launch audit that found 118 issues
+across architecture, the `gh` data layer, rendering, performance, release
+engineering, security, QA and UX. What follows is what changed as a result.
+
+### Security
+
+- **Sanitize untrusted GitHub text at the data boundary.** Every string the tool
+  displays — issue and PR titles, run titles, branch names, advisory summaries —
+  is chosen by whoever opens the issue or pull request. Ink strips CSI sequences
+  but deliberately preserves OSC, SGR and bare C0 control characters, so OSC 8
+  hyperlinks (an attacker-chosen clickable URL with no visual tell), carriage
+  returns (which overwrite the row above, and could blank a critical alert),
+  bells and newlines all reached the terminal. A single multi-line title could
+  evict other rows out of the pane entirely. Control characters are now replaced
+  at the point the JSON is parsed. Emoji, ZWJ sequences, CJK, combining marks,
+  right-to-left text and the tool's own Nerd Font glyphs are unaffected.
+- **Remote values can no longer crash the render.** Severity and status strings
+  were used directly as object keys, so a code-scanning alert with a severity of
+  `constructor` returned a function where a colour was expected and took the
+  whole dashboard down — inside the alternate screen, so the stack trace was
+  wiped on the way out. Lookups now ignore inherited keys, and each row is
+  wrapped in an error boundary.
+- Enabled private vulnerability reporting. `SECURITY.md` told reporters to use
+  it while it was switched off, so the documented disclosure path accepted
+  nothing.
+
+### Fixed
+
+- **A stalled `gh` no longer wedges a tab forever.** Subprocess calls had no
+  timeout, and the in-flight guard was only cleared when the promise settled —
+  which a hung child never does. That tab then stopped refreshing for the life
+  of the process while the spinner kept insisting it was working. All calls now
+  carry a timeout, a kill signal, a 16 MiB output buffer and an abort signal.
+- **Errors are readable.** The error formatter checked a property Node never
+  sets, so every failure rendered as the entire reconstructed command line —
+  roughly 150 characters of JSON field names — against a layout that reserved
+  one row for it, overflowing the frame and making the screen flash on every
+  redraw. It now shows the first line of stderr, and error and note lines are
+  pinned to the single row they are budgeted.
+- **A parse failure no longer reports "no runs".** The payload cache was written
+  before parsing, so a malformed response was cached, its error was cleared on
+  the next tick, and the retry was skipped — leaving the tab confidently empty
+  forever. The cache is written only after a successful parse.
+- **Security failures are no longer misreported as configuration.** Any failure
+  on the code-scanning or secret-scanning endpoints — expired token, rate limit,
+  network — was reported as "not enabled". Only a genuine 403/404 says that now;
+  everything else surfaces as itself, and unavailable sources back off instead
+  of being re-asked on every refresh.
+- **Counts stopped lying.** Issues, pull requests and alerts are all capped by
+  the fetch, but only the Actions tab said so. Every tab now marks a truncated
+  count, and a tab whose fetches are failing is marked in the tab bar rather
+  than showing a frozen number at full confidence.
+- **Rows are sorted by what matters.** Security alerts were ordered by which
+  endpoint answered first, which put secret-scanning alerts — always critical —
+  last, below the fold. They now sort by severity. Issues and pull requests were
+  returned oldest-created-first while the age column showed the update time, so
+  the column could not be read and truncation dropped recently-active items;
+  both now sort by update time.
+- **A crash is visible.** Uncaught errors were drawn into the alternate screen
+  and then erased by the exit handler, so the tool vanished with exit code 0.
+  Crashes now restore the screen first, print a stack trace, and exit non-zero.
+  Interrupts exit 130/143 instead of 0.
+- **Narrow panes work.** Below about 61 columns the fixed columns overflowed the
+  frame, rows wrapped and the screen repainted in full every frame; in the band
+  just above that the frame looked correct while the title column silently
+  rendered empty. Narrow panes now drop columns instead, keeping the frame, tab
+  bar and status line on screen.
+- Missing or malformed timestamps rendered as `NaNd ago`; they now render as a
+  dash.
+- `GH_FORCE_TTY`, which many people export in their shell profile, made `gh`
+  emit coloured JSON that could not be parsed, breaking all four tabs at once.
+  The environment passed to `gh` is now neutralized for display variables only.
+- A missing `gh` or a directory that is not a repository produced four copies of
+  a raw subprocess error inside the alternate screen, which was then erased on
+  exit. Both are now caught before the dashboard starts, with an actionable
+  message and a non-zero exit.
+
+### Added
+
+- `q` and `Esc` quit; `r` refreshes the current tab immediately.
+- `GH_GLANCE_ICONS=unicode` swaps the Nerd Font Octicons for plain ASCII, so the
+  tool is usable without a Nerd Font. The previous advice was to edit the source
+  — which would not survive an update once installed as a package.
+- `GH_GLANCE_NO_ANIMATION=1` freezes the spinner, for a pane that sits in
+  peripheral vision for hours.
+- A severity column on the Security tab. Severity had been carried by the shield
+  icon's colour alone, which made critical and high indistinguishable and
+  erased the distinction entirely under `NO_COLOR` or for a colour-blind reader.
+- A staleness marker once the visible tab's data is old enough to mislead.
+- Screen-reader labels on the status icons, which otherwise announce as nothing.
+- A unit test suite on Node's built-in runner — no framework, no build step.
+  Before this, no function in the file was executed by any check.
+- `release.yml`, which publishes with provenance from a verified tag.
+
+### Changed
+
+- **Node 22 is now the minimum.** Ink and two of its dependencies already
+  required it while the package claimed 20.19, so installs on the advertised
+  floor emitted engine warnings. Node 20 reached end of life on 2026-04-30.
+- Background tabs refresh every 60 seconds rather than every 20. Steady-state
+  polling had been consuming 40-50% of an hourly GitHub API rate limit for a
+  single pane; the visible tab is unchanged at 5 seconds.
+- The spinner animates on first load and while a run is executing, rather than
+  on every fetch. The previous behaviour kept a 10 fps redraw loop alive
+  permanently, costing roughly 44 MB of terminal writes per idle hour.
+- `--version` and `--help` no longer load the rendering stack: 0.27s and 94 MB
+  down to 0.04s and 49 MB.
+- Secondary text uses the terminal's own dim attribute rather than a fixed
+  colour chosen for dark themes, so it is readable on light backgrounds too.
+- The age column is labelled `UPDATED`, which is what it has always shown.
+- CI runs the test suite, no longer stops the matrix at the first failure,
+  asserts exit codes rather than just non-zero, and pins every action to a
+  commit SHA.
+
+### Removed
+
+- 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.3.0]: https://github.com/juan294/gh-glance/releases/tag/v0.3.0
+[0.2.0]: https://github.com/juan294/gh-glance/releases/tag/v0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juan294
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# gh-glance
+
+<a href="https://chapa.thecreativetoken.com/u/juan294">
+  <img src="https://chapa.thecreativetoken.com/u/juan294/badge.svg" alt="juan294's Chapa Impact Badge" width="100%" />
+</a>
+
+[![CI](https://github.com/juan294/gh-glance/actions/workflows/ci.yml/badge.svg?branch=develop&event=push)](https://github.com/juan294/gh-glance/actions/workflows/ci.yml?query=branch%3Adevelop+event%3Apush)
+[![CodeQL](https://github.com/juan294/gh-glance/actions/workflows/codeql.yml/badge.svg?branch=develop&event=push)](https://github.com/juan294/gh-glance/actions/workflows/codeql.yml?query=branch%3Adevelop+event%3Apush)
+![Node.js](https://img.shields.io/badge/Node.js-22%2B-43853d)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+A live-refreshing GitHub dashboard that fits in a narrow terminal pane --
+**Actions, Issues, Pull Requests, and Security alerts**, one tab at a time,
+refreshing every 5 seconds with no flicker.
+
+Built for pairing with a terminal multiplexer/workspace tool (e.g. a sidebar
+pane next to your editor) where you want an always-on glance at repo activity
+without switching to the browser.
+
+```
+╭─ Actions ────────────────────────────────────────────────────────────────╮
+│     TITLE                    WORKFLOW   BRANCH         TIME    UPDATED   │
+│ ──────────────────────────────────────────────────────────────────────── │
+│ >+  ci: pin actions to comm… #443 CI    develop        1m20s   2d ago    │
+│  x  fix: restore the primar… #442 Code… develop        1m28s   2d ago    │
+│  !  chore: bump dependencies #441 CI    dependa…int-10 56h49m  2d ago    │
+│  -  docs: update the readme  #440 CI    develop        15s     3d ago    │
+│                                                                          │
+│                                                                          │
+╰───────────────────────────────────────────────────────────────── 4 of 4 ─╯
+[1:Actions (4)]   2:Issues (3)    3:PRs (2)    4:Security (0)
+⠋ Fetching            Move: jk | 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
+> 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.
+
+<!-- contract:allow-emoji -- the check/cross above stand in for Nerd Font
+     Octicons the app actually draws; they are literal examples, not decoration. -->
+
+---
+
+## Why
+
+GitHub's own web UI already shows all of this. `gh-glance` exists for the
+moment you don't want to alt-tab to a browser tab to check whether CI is
+still red, whether someone commented on your PR, or whether Dependabot found
+something new -- it's meant to sit in a corner of your terminal and just be
+current.
+
+## Features
+
+- **Actions** -- recent workflow runs: status, title, workflow, branch,
+  elapsed time, age
+- **Issues** -- open issues: title, author, first label, age
+- **Pull Requests** -- open PRs: title, author, branch, review status
+  (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.
+  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 bottom of the pane alongside the
+  status line, 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
+- 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
+- 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
+- Enters the terminal's alternate screen buffer on launch (like `lazygit`,
+  `htop`, `vim`) so the shell prompt that launched it stays out of view, and
+  is restored cleanly on exit
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) `>=22` (Ink requires it; Node 20 is end-of-life)
+- The [`gh` CLI](https://cli.github.com/) `>=2.20`, authenticated (`gh auth login`)
+- A terminal font with [Nerd Font](https://www.nerdfonts.com/) glyphs (for the
+  status icons to render correctly -- without one, they'll show as blank
+  boxes; see [Icons without a Nerd Font](#icons-without-a-nerd-font))
+
+## Install
+
+```bash
+git clone https://github.com/juan294/gh-glance.git
+cd gh-glance
+npm install
+npm link   # makes the `gh-glance` command available globally
+```
+
+(Not yet published to npm -- clone + `npm link` is the current install path.)
+
+`npm link` is what puts `gh-glance` on your `PATH`; it symlinks the global
+bin at your Node version's `bin/` directory through to this checkout:
+
+```
+<node>/bin/gh-glance -> <node>/lib/node_modules/gh-glance -> /path/to/your/clone
+```
+
+Because the link resolves to the clone rather than to a copy, you can move
+or rename the directory and the command keeps working. Two things do break
+it, and both are fixed by re-running `npm link` from the clone:
+
+- switching Node versions (nvm/fnm install their own global `bin/`)
+- setting up on a fresh machine, or after `npm unlink -g gh-glance`
+
+### Using it as a workspace pane
+
+`gh-glance` takes no arguments and infers the repo from the working
+directory, so it drops straight into a pane definition of whatever
+workspace tool you use. With [summon](https://github.com/juan294/summon),
+that's a one-line pane in a layout file:
+
+```
+pane.enhance=gh-glance
+```
+
+Point the pane at the bare command rather than an absolute path to
+`index.mjs` -- resolving through `PATH` is what lets the clone move without
+every layout needing an edit.
+
+## Usage
+
+Run it from inside any locally cloned GitHub repository:
+
+```bash
+gh-glance
+```
+
+It infers the repository from the current directory's git remote, the same
+way `gh` itself does -- no flags or config needed.
+
+```bash
+gh-glance --help      # usage and keybindings
+gh-glance --version   # print the version
+```
+
+It's an interactive full-screen dashboard, so it exits with an error if
+stdout isn't a terminal rather than streaming redraw frames into a pipe.
+
+### Keybindings
+
+| Key | Action |
+|---|---|
+| `1` `2` `3` `4` | Jump to Actions / Issues / Pull Requests / Security |
+| `←` / `→` | Previous / next tab |
+| `Tab` / `Shift+Tab` | Next / previous tab |
+| `↑` / `↓` or `j` / `k` | Move the cursor between rows |
+| `PgUp` / `PgDn` | Move a page at a time |
+| `Enter` | Open the selected item in your browser |
+| `r` | Refresh the current tab now |
+| `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.
+
+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`
+rather than advertising keys that would do nothing.
+
+## Configuration
+
+`gh-glance` still takes no arguments by default, so it drops straight into a
+pane definition. Flags are there when you want them:
+
+| Flag | Effect |
+|---|---|
+| `-R`, `--repo owner/name` | Watch a specific repository instead of the current directory's. Works from anywhere -- you do not need a local clone. |
+| `--refresh <seconds>` | Active-tab poll interval, 2-3600, default 5. Background tabs stay at 12x this. |
+| `--tab <name>` | Start on `actions`, `issues`, `prs` or `security`. |
+| `--verbose` | Log one line per `gh` call to stderr, with timing and outcome. stderr must be redirected: `gh-glance --verbose 2>gh-glance.log`. |
+
+An unrecognised flag exits 2 rather than being ignored, so a typo fails loudly.
+
+Environment variables work too, and the flags take precedence:
+
+| Variable | Effect |
+|---|---|
+| `GH_REPO=owner/name` | Watch a specific repository instead of the current directory's |
+| `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 |
+| `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. |
+
+## Rate limit
+
+The visible tab refreshes every 5 seconds; the other three refresh every 60
+seconds, purely to keep their counts honest. That works out at roughly 500
+REST requests an hour, about 10% of the 5,000/hour authenticated limit — so
+leaving a pane open all day does not exhaust the budget your other `gh`
+commands share.
+
+## Limitations
+
+
+- **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.
+- 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.
+- 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.
+- The Actions **TIME** column measures from the run's start to its last update.
+  `gh` exposes no completion timestamp, so a workflow that was re-run later
+  reports the span up to the re-run rather than its original duration.
+- macOS/Linux terminals with ANSI + alternate-screen-buffer support. Not
+  tested on Windows -- `npm` will not stop you installing it there, but the
+  alternate-screen handling is unverified.
+
+### Icons without a Nerd Font
+
+The status icons are Octicon glyphs from the [Nerd
+Fonts](https://www.nerdfonts.com/) private-use-area range. If your terminal
+font isn't a Nerd Font they render as blank boxes -- which would leave status
+carried by the colour of a blank box, and by nothing at all under `NO_COLOR`.
+
+Set `GH_GLANCE_ICONS=unicode` for plain ASCII equivalents:
+
+```bash
+GH_GLANCE_ICONS=unicode gh-glance
+```
+
+They are deliberately single-cell ASCII rather than prettier symbols like `✓`
+and `✗`, because those are East-Asian-Ambiguous width and render two cells wide
+in some terminals, which would shift every column to their right.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| `the gh CLI is not installed` | Install it from [cli.github.com](https://cli.github.com), then `gh auth login`. |
+| `not inside a git repository` | Run it from a cloned GitHub repository, or set `GH_REPO=owner/name`. |
+| Status icons are blank boxes | Your terminal font is not a Nerd Font. Use `GH_GLANCE_ICONS=unicode`. |
+| Security tab shows a "not enabled" note | Code scanning and secret scanning need GitHub Advanced Security. Dependabot alerts work independently. A genuine auth or network failure shows the real error instead. |
+| A tab's count is red | That tab's last fetch failed. The error itself is shown when you switch to it. |
+| `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. |
+| `--verbose` refuses to start | stderr is still your terminal, where the log would draw over the dashboard. Redirect it to a file. |
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Security
+
+See [SECURITY.md](./SECURITY.md).
+
+## License
+
+[MIT](./LICENSE)