docs: correct CLAUDE.md against the tree

[svc-finitelabs]

Part of AGENT-44 (audit the CLAUDE.md files that exist). One PR per repo.

Provenance matters for reading this diff. Only the ### typecheck section was
touched in the 2026-08-08 sweep; it verifies clean. Everything else in the file
dates to January and had not been revisited in six months, and that is where
all the findings are.

Wrong

1. A tests/ directory that has never existed. The file sends readers to
   tests/test_bit16.lua, test_bit32.lua, test_bit64.lua. There is no
   tests/ directory; every module carries an embedded selftest() driven by
   run_tests.sh. Highest-impact item here, since it is three dead paths.

2. "Each bit module provides the same API" — it does not, in both directions.
   mask is bit16/bit32 only and bit64 has none; to_unsigned is bit32 only.
   Meanwhile bit64's own surface (new, is_int64, to_hex, to_number,
   from_number, eq, is_zero, and the aliases xor/shr/lsl/asr) was
   entirely undocumented. For a library that four other repos vendor, that is the
   most consequential gap after the next item.

3. The documented 64-bit literal is rejected by the code.

   local value = {0x12345678, 0x9ABCDEF0}   -- as documented

   bit64.new attaches a private metatable and bit64.is_int64 tests for it, so
   this bare literal raises "Value is not a valid Int64HighLow pair" from
   to_number. The repo's own selftest asserts that error. The subtle part, now
   documented: the bitwise ops index [1]/[2] directly and so accept the
   literal, while the accessors reject it — the two paths diverge silently until
   something raises.

4. Benchmark iterations: documented as "modules use 10000", actually 100000.

5. CI section omitted typecheck (while line 122 of the same file asserted
   "Part of check, so CI enforces it"), named the wrong trigger branches, and
   said the test job runs make test-matrix when it runs make test-all.

Imprecise

• _compat dispatches on a capability probe, not a version. It compiles
  a & b and checks fn(0xFFFFFFFF, 0xFFFFFFFF) == 0xFFFFFFFF. The reason is an
  outside fact the file omitted and the source comment carries: LuaJIT rolling
  releases from 2026 parse a & b but return signed 32-bit, so a syntax test
  would misroute them into the native branch and skip to_unsigned(). Also
  require("bit") is tried before bit32, so a 5.1 install with LuaBitOp
  takes the LuaJIT path and reports is_luajit = true.
• raw_* "behave identically to regular operations" on non-LuaJIT — only for
  in-range inputs. The wrapped versions also mask their arguments; the raw ones do
  not.
• .stylua.toml does not exist. The values are right but live as Makefile CLI
  flags, and cover src/ only. The annotations are LuaCATS, not LuaDoc — which
  the file's own typecheck section already called LuaCATS.

Added

make check as the actual gate, and an explicit line that make all is
format lint test build and is not it. Also that the local test-matrix
omits LuaJIT 2.0 while CI covers it, so a green local matrix is the weaker signal.

Two changes inside the shared typecheck block

Both apply to the sibling repos too; flagging them rather than burying them.

1. The grep had nowhere to run. It targets
   script/core/diagnostics/*.lua with no indication those paths are inside a
   lua-language-server source checkout rather than this repo. Run at the repo root
   it matches nothing. Now says so.
2. Dropped the cross-repo survey. The block asserted which other repos are
   indifferent to runtime.version (naming lua-noiseprotocol, lua-bthome-ble,
   lua-protobuf). That is a claim about three other trees, in a public repo, that
   rots on their commits and not this one's. Kept the observed behaviour — the pin
   is load-bearing here because of the math.pow and unpack shims — and
   dropped the attribution.

Verification

• make typecheck with the CI-pinned lua-language-server 3.19.0: clean.
• Every API name and error string asserted in the rewrite was read out of the
  source, including the bit64 function list and the selftest that pins the
  Int64 error.
• Not run: make test, make build. No Lua source changed.

[derek-miller]

Approving. I checked this against the tree rather than reading it, because a wrong CLAUDE.md misleads every future session silently — and the corrections here are exactly the class that was doing that.

Verified accurate:

• No tests/ directory. Confirmed absent; the old tree diagram invented three files.
• mask is bit16/bit32 only, to_unsigned is bit32 only. Enumerated all three modules — correct, and this is the most useful fix in the PR. The old "each module provides the same API" was actively wrong, and the failure mode is a nil-index at runtime.
• raw_* in bit32 and bit64, none in bit16. Both expose all ten.
• bit64 aliases xor/shr/lsl/asr exist (bit64.lua:379-388).
• The Int64 error string "Value is not a valid Int64HighLow pair" matches bit64.lua:337.
• check: format-check lint typecheck and all: format lint test build — the warning that all is not a substitute for check is right, and worth stating since all looks like the bigger target.
• Benchmarks: 3 warmup, default 100, modules pass 100000. The old doc said 10000; it is 100000.
• CI: workflow name is Lua Tests, LLS pinned to 3.19.0, jobs run make check and make test-all.
• stylua has no config file — invoked as --indent-type Spaces --column-width 120 --line-endings Unix src/ from the Makefile, and luacheck src/, so "src only" is right.
• The local/CI matrix asymmetry is real and I would not have guessed it. run_tests_matrix.sh pins 5.1.5 5.2.4 5.3.6 5.4.8 luajit-2.1-dev; CI runs 5.1-5.4 plus luajit-2.0 and 2.1. So "a green local matrix is a weaker signal than a green CI one" is precisely true, and that is the kind of thing people learn the hard way.

Twice I thought you had it wrong and I was the one who was wrong. I read bit32 as exposing only raw_add, and bit64 as having no compat aliases — both because I grepped for ^function and missed that those are plain assignments. Worth recording only because it is a reason to trust the rest: the claims that looked most falsifiable held up under a second, better check.

The two rewrites that add the most:

The _compat section going from a version table to "probes behaviour, not version" is the substantive one. The old text described a version ladder that is not what the code does, and the LuaJIT-2026 detail — parses a & b but returns signed 32-bit, so a compile-only test routes it into the native branch and skips to_unsigned() — is the reason the probe has to exist. That belongs in a file agents read before touching _compat.

The Int64 metatable note is the other. "The bitwise operations index [1]/[2] directly and so happen to accept a bare literal; the accessors do not" describes a genuine trap: a bare {hi, lo} works until it suddenly doesn't, and the divergence is silent until an accessor raises.

LuaDoc → LuaCATS is also correct, given typecheck runs lua-language-server.