Repository navigation
docs: refresh stale scale figures across the documentation - #1039
vernonstinebaker wants to merge 1 commit into
Conversation
Supersedes nullclaw#774. Every figure below was recomputed from source at main (5f1cade) rather than carried forward, because nullclaw#774's own numbers had themselves gone stale: it proposed 6,300+ tests against an actual 7,499, and ~2.7 MB for a binary that measures 4.66 MB. ## Scale figures - Source files 245 -> 293; src LOC ~204K -> ~290K; tests 5,640+ -> 7,499. - Providers: "50+ implementations (9 core + 41 compatible services)" -> 10 core implementations plus 110 OpenAI-compatible registry entries, counted from the `.{ .name = ... }` table in `src/providers/factory.zig`, which is the actual single source of truth for compatible providers. - Channels 17 -> 24; the architecture tables listed a partial set that omitted Teams, Max, WeChat/WeCom, and Weixin. Now labelled with the count and the omissions filled in. English and Chinese kept in sync. - Tools "30+" -> 40 registered implementations, counted from `tool_name` constants in `src/tools/`. ## Binary size — a real discrepancy, not just a stale number `README.md` and `CLAUDE.md` claimed 678 KB, and AGENTS.md set a sub-1 MB ReleaseSmall target. A host build measures 4,889,528 bytes (~4.66 MB, aarch64-macOS): zig build -Doptimize=ReleaseSmall && ls -l zig-out/bin/nullclaw That is roughly 7x the long-quoted figure and about 4.7x the stated target. All three now state the measured value, AGENTS.md marks the sub-1 MB goal as an open gap rather than a met constraint, and a verification command is included so the figure is re-checkable instead of asserted. This is a product-accuracy finding, not only a docs fix: the headline size claim has been wrong for a long time. Worth deciding separately whether to shrink the binary or restate the target. ## Keeping the numbers current The recurring failure is that these figures are hand-maintained and silently rot — nothing in CI checks them, which is also why nullclaw#774 went stale in the first place. AGENTS.md §1 now carries the exact commands used to derive each number, and all of them were confirmed to run as written. A repo-wide sweep confirms no remaining 5,640 / 5,300 / 678 KB / 0.15.x references in the touched files. Note for reviewers: the "last verified at 5f1cade" marker is the point at which these numbers stop being true. Please re-derive rather than increment them. Docs only, no code touched. `zig build test --summary all` 13/13 steps, 7490/7499 passed, 9 skipped, 0 failures, 0 leaks. `zig build -Doptimize=ReleaseSmall` and `zig fmt --check src/` both clean.
Merge order: #1040 first, then this one.This PR and #1040 edit the same
Sequence: merge #1040, then rebase this PR. The reason is not just the textual conflict — it is to avoid wasted work. If this PR lands first, it corrects numbers that #1040 then deletes. Landing #1040 first means this PR rebases onto a Action for whoever merges: merge #1040 first. This PR will need a rebase and its |
Supersedes #774. Credit to @telagod for the original audit — the premise was right and worth doing; the numbers had simply aged out, so everything here was re-derived from source at
main(5f1cade0) rather than carried forward.#774 proposed 6,300+ tests against an actual 7,499, and ~2.7 MB for a binary that measures 4.66 MB. Both are corrected below.
Scale figures
Provenance for each, all confirmed to run as written:
src/providers/factory.zigis the actual single source of truth for OpenAI-compatible providers. Counted asgrep -cE '\.\{ \.name = "' src/providers/factory.zig→ 110. The 10 core implementations are the real provider files, excluding composition wrappers (router.zig,reliable.zig) and shared helpers.grep -rhoE 'pub const tool_name = "[a-z0-9_]+"' src/tools/ | wc -l→ 40.src/channels/, excluding the*_ingress,*_api,*_presenter,outbox,dispatch, andexternal_protocolhelpers → 24. The architecture tables listed a partial set that silently omitted Teams, Max, WeChat/WeCom, and Weixin; those are now listed and the row is labelled with the count. English and Chinese updated together.git ls-filescross-checked againstfind; all three methods agree on 293 / 289,734.Binary size — a real discrepancy, not just a stale number
README.mdandCLAUDE.mdclaimed 678 KB, and AGENTS.md §2.2 set a sub-1 MB ReleaseSmall target. A host build measures:That is ~7x the long-quoted figure and ~4.7x the stated target. All three documents now state the measured value, AGENTS.md marks the sub-1 MB goal as an open gap rather than a met constraint, and the verification command is included so the number is re-checkable instead of asserted.
I'd treat this as a product-accuracy decision rather than a docs fix: either the binary gets smaller, or the target gets restated honestly. That's a separate conversation and I have not attempted either here — this PR only makes the documentation tell the truth about the current state.
Keeping the numbers current
The root cause of #774 going stale is that these figures are hand-maintained and nothing checks them. AGENTS.md §1 now carries the exact derivation commands, and a repo-wide sweep confirms no remaining
5,640/5,300/678 KB/0.15.xreferences in the touched files (AGENTS.md §7.6 treats a version-pin mismatch as a hard fail, so that was checked explicitly).For reviewers: the "last verified at
5f1cade0" marker is the point at which these stop being true. Please re-derive rather than increment.Validation
zig build test --summary all— 13/13 steps, 7490/7499 passed, 9 skipped, 0 failures, 0 leakszig build -Doptimize=ReleaseSmall— exit 0zig fmt --check src/— exit 0Not included
Deliberately split out to keep this reviewable: the
CLAUDE.mddeduplication from #775 (a 1-file architectural change that also needs the stale Zig 0.15.2 pin corrected). Separate PR follows.