# qqq-cli documentation

Start with the [repository README](../README.md) (install, a tour of the CLI and the terminal UI,
compatibility) and [TRY-IT.md](../TRY-IT.md) (every command against the local QQQ sample server). Each
package has its own README: [cli](../packages/cli/README.md), [tui](../packages/tui/README.md),
[core](../packages/core/README.md), [ui-api-client](../packages/ui-api-client/README.md),
[conformance](../packages/conformance/README.md).

Everything under `docs/`:

## Using and integrating

| File | What it is |
|---|---|
| [extensions.md](extensions.md) | how the extension (QBit) OpenAPI documents are merged into the client document, which ones are in it, and how to rebuild it |
| [server-findings.md](server-findings.md) | UI API problems found in the QQQ server while building the clients: how to reproduce each, the client workaround, and the filed issue |

## Releasing and packaging

| File | What it is |
|---|---|
| [release-runbook.md](release-runbook.md) | from a green branch to a published release: checklist of what needs the maintainer, versions, release checks and binaries, signing, tags and npm, the GitHub release, Homebrew and Scoop, smoke tests, recovery |
| [release-notes/1.0.0.md](release-notes/1.0.0.md) | the GitHub release body for `cli-v1.0.0` (the release commands are in an HTML comment at the top) |
| [release-notes/1.0.0-rc.1.md](release-notes/1.0.0-rc.1.md) | the GitHub release body for the release candidate `cli-v1.0.0-rc.1`, kept for history |
| [packaging/README.md](packaging/README.md) | the install paths (curl installer, Homebrew, Scoop, npm), where the formula and manifest live, platform notes (Gatekeeper, SmartScreen, musl), and how the terminal UI is bundled |
| [packaging/homebrew-tap/](packaging/homebrew-tap/README.md) | the complete `QRun-IO/homebrew-tap` repository, ready to copy: `Formula/qqq.rb`, README, LICENSE (its old qqq-orb CI files were removed with CircleCI) |
| [packaging/qqq.json](packaging/qqq.json) | the Scoop manifest, copied to `bucket/qqq.json` in `QRun-IO/scoop-bucket` |
| [ci-lanes.md](ci-lanes.md) | what CI runs (the shared Gitea `node.yaml` workflow), what is outside CI, and the history of the retired CircleCI orb lanes |

`scripts/update-packaging.mjs` fills the version and checksums of the formula and manifest from a
release's `SHA256SUMS`.

## Parity with the web UI

| File | What it is |
|---|---|
| [parity/feature-matrix.md](parity/feature-matrix.md) | the CLI and TUI status (pass, n/a, blocked) of every row of the web UI's acceptance matrix; generated by `scripts/parity-matrix.py` and checked by the release gate |
| [parity/next-feature-matrix.md](parity/next-feature-matrix.md) | the input to that script: a copy of the Next UI acceptance matrix from `qqq-frontend-next` |
| [parity/CLI-PLAN.md](parity/CLI-PLAN.md) | the plan that took the CLI column to 1.0 parity, kept for history |

## Reviews

| File | What it is |
|---|---|
| [review-2026-10-31.md](review-2026-10-31.md) | the hardening review of the CLI and the kernel before 1.0: each finding, how it was reproduced, and its fix and test |

Elsewhere in the repository: [CHANGELOG.md](../CHANGELOG.md), [CONTRIBUTING.md](../CONTRIBUTING.md),
[SECURITY.md](../SECURITY.md), and `packages/core/src/extensions/README.md` (the extension registry).