james.maesandClaude Fable 5.1
0d62416f08
The CLI ships for macOS and Windows and has Keychain and DPAPI keyring paths, but CI only ran Linux. qqq-orb 0.8.33 adds opt-in platform lanes to the cli profile, and the setup config's 0.8 track picks the release up by itself, so the manifest only needs platforms: [macos-arm64, windows-x64]. Rendered with the orb's generate_pipeline.py from v0.8.33 against this manifest: a push to main yields cli-macos-arm64, cli-windows-x64 and cli_verify_publish; the tag v1.8.0 yields the same in publish_release with the publish job requiring both lanes and bound to the registry context. ci-lanes.md now describes what runs (and that the lanes cover the Node packages' build, tests and lint, not the binaries or the TUI), keeping the 0.8.32 gap list and proposal as history. The runbook marks the orb item done, says a missing macOS or Windows resource class now holds a publish, and no longer claims the Windows lane runs verify-binary.ps1. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
qqq-cli documentation
Start with the repository README (install, a tour of the CLI and the terminal UI, compatibility) and TRY-IT.md (every command against the local QQQ sample server). Each package has its own README: cli, tui, core, ui-api-client, conformance.
Everything under docs/:
Using and integrating
| File | What it is |
|---|---|
| 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 | 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 | 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 | 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 | the GitHub release body for the release candidate cli-v1.0.0-rc.1, kept for history |
| 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/ | the complete QRun-IO/homebrew-tap repository, ready to copy: Formula/qqq.rb, README, LICENSE and its qqq-orb CI files |
| packaging/qqq.json | the Scoop manifest, copied to bucket/qqq.json in QRun-IO/scoop-bucket |
| ci-lanes.md | what CircleCI (the qqq-orb cli profile) runs: the Linux verify-and-publish job and the macOS arm64 and Windows x64 lanes, what is still outside CI, and the history of the orb changes |
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 | 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 | the input to that script: a copy of the Next UI acceptance matrix from qqq-frontend-next |
| 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 | 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, CONTRIBUTING.md,
SECURITY.md, and packages/core/src/extensions/README.md (the extension registry).