james.maesandClaude Fable 5.1
2f47ea4ce9
The sample server on 8077 still serves UI API 1.8.0, so the core document is now qqq's committed openapi.yaml at develop 7825261ab (UI API 1.10.0) instead of a live server, merged with each qbit's committed extension document at origin/develop (qbit-printing: origin/main, it has no develop). Collaboration now comes from develop, where per-session presence is merged; assistant moves to 1.7.0 and printing to 2.3.0. 222 operations, 156 from extensions. data-analysis 1.5.0 still carries FilterCriteria as it was before 1.9.0 (no `options`), which made the strict schema-equality rule fail the merge. merge-spec now accepts an extension's older copy of a schema (same schema minus later properties and enum values) and keeps the newer one with a warning; any other difference still fails. The client follows the UI API version, so it becomes 1.10.0 (UI_API_VERSION too). Servers on 1.9.0 now read tableVariant on writes, so the CLI's --variant note names the versions that ignore it. The "newer server" version tests move to 1.11.0. 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).