james.maesandClaude Fable 5.1
4f41f41a05
scripts/update-packaging.mjs could not be shown to write zeros: run against the real cli-v1.0.0 SHA256SUMS from the all-zero placeholders at1bc4dddit fills correct values (reproduced in a clean worktree), and branch head8fc630dalready carried them. The old script was fragile, though: it read lines with split/reverse (a `*file` binary-mode name or a stray column would silently mis-key), never checked that a sum was 64 hex, accepted all-zero sums, did not check that any placeholder had actually matched, and wrote the formula before it knew the manifest would succeed. Now it parses `shasum -a 256` lines strictly, requires every target to be 64 lowercase hex and not all zeros, requires at least one url/sha256 pair and no unfilled sha256 left in the formula, computes both files first and writes only if everything passed, otherwise exits 1 with "nothing was written". Tested in scripts/update-packaging.test.mjs (fixture SHA256SUMS; run by `npm test` via `test:scripts`). Docs (packaging README, release runbook step 7, tap README) say to compare the diff with SHA256SUMS and that tap/bucket CI catches a wrong or zero sum only when its PR is opened and read. Ran against /Volumes/HD-2/Git.Local/QRun-IO/.worktrees/qqq-cli-release/dist/SHA256SUMS; the packaging files are unchanged from8fc630d, and each sum was checked by hand against it: darwin-arm64 5017a32ac5031d9146d541381099a959e5c19bbf04c48f725045d89d6007b211 darwin-x64 eb9b1d43d24b639118d94b175c343080a39ae9ba64c24645c1792ff3b16a37f1 linux-arm64 25f513bdda13bbe40cf536844eebc1e3a7e21cf7804024f25ebe7c42793d7ebc linux-x64 804d06cb7c0012c2f185ae5d94c6bb8f9e2482a440bb3c165361f1a14c941e41 windows-x64 cf418d7842a227cee412171878228004f9bc5098a272c64b89512d1e2d06a176 (linux musl sums are in SHA256SUMS but not used by the formula or manifest.) 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).