Skip to content

docs: refresh stale scale figures across the documentation - #1039

Open
vernonstinebaker wants to merge 1 commit into
nullclaw:mainfrom
vernonstinebaker:docs/stats-refresh
Open

vernonstinebaker wants to merge 1 commit into
nullclaw:mainfrom
vernonstinebaker:docs/stats-refresh

Conversation

@vernonstinebaker

Copy link
Copy Markdown
Contributor

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

Was Now
Source files 245 293
src LOC ~204K ~290K
Tests 5,640+ 7,499
Providers 50+ (9 core + 41 compatible) 10 core + 110 compatible
Channels 17 24
Tools 30+ 40

Provenance for each, all confirmed to run as written:

  • Providers — src/providers/factory.zig is the actual single source of truth for OpenAI-compatible providers. Counted as grep -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.
  • Tools — grep -rhoE 'pub const tool_name = "[a-z0-9_]+"' src/tools/ | wc -l → 40.
  • Channels — one struct per channel under src/channels/, excluding the *_ingress, *_api, *_presenter, outbox, dispatch, and external_protocol helpers → 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.
  • Files/LOC — git ls-files cross-checked against find; all three methods agree on 293 / 289,734.

Binary size — a real discrepancy, not just a stale number

README.md and CLAUDE.md claimed 678 KB, and AGENTS.md §2.2 set a sub-1 MB ReleaseSmall target. A host build measures:

$ zig build -Doptimize=ReleaseSmall && ls -l zig-out/bin/nullclaw
-rwxr-xr-x  4889528  zig-out/bin/nullclaw        # ~4.66 MB, aarch64-macOS

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.x references 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 leaks
  • zig build -Doptimize=ReleaseSmall — exit 0
  • zig fmt --check src/ — exit 0
  • Docs only, 5 files, +42/−25. No code touched.

Not included

Deliberately split out to keep this reviewable: the CLAUDE.md deduplication from #775 (a 1-file architectural change that also needs the stale Zig 0.15.2 pin corrected). Separate PR follows.

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.
@vernonstinebaker

Copy link
Copy Markdown
Contributor Author

Merge order: #1040 first, then this one.

This PR and #1040 edit the same CLAUDE.md lines with opposite intent:

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 CLAUDE.md that no longer carries figures; its CLAUDE.md hunk then drops out as redundant, and what remains is purely the substantive part: AGENTS.md, README.md, and the docs/**/architecture.md tables — which is where those figures belong.

Action for whoever merges: merge #1040 first. This PR will need a rebase and its CLAUDE.md portion discarded. Do not merge these two in the other order, and do not resolve them silently — the two intents are incompatible.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant