docs+test(readme): pin canonical authoringMetaV2 word descriptions into the README

[thedavidmeister]

Summary

• Embeds each word's canonical authoringMetaV2() description verbatim into the README under its word heading, replacing the hand-written one-line summaries. The description strings are the canonical statement of each word's input ordering ("the vault contract address and the amount of shares/assets as a float") and decimals/rounding semantics, so the README now carries the single-source-of-truth prose instead of a hand-kept paraphrase.
• Adds ERC4626WordsReadmeDescriptions.t.sol: decodes LibERC4626SubParser.authoringMetaV2() and asserts the README contains every description, after newline normalisation so markdown hard-wrapping of the quoted paragraphs cannot defeat the containment check. The source is the oracle — a description edit in authoringMetaV2() (input order, decimals, rounding) that is not mirrored into the README fails CI, and vice versa. The test contains no expected description literals.
• Adds { access = "read", path = "README.md" } to foundry.toml fs_permissions (identical hunk to open PR test(readme): assert README documents both ERC4626 word names #185 so the two merge cleanly).

Relationship to #185: the human rework note on #185 split issue #133 into legs — #185 (Refs #133) covers the word-names leg; this PR covers the remaining input-ordering and decimals-semantics legs by pinning the full canonical descriptions.

Docs + test + config only; no src/ change, no bytecode change, no pointer/meta regeneration, no redeploy required.

Closes #133

QA

• Discriminating tests: testReadmeContainsEveryAuthoringMetaWordDescription — fails on base (base README lacks the canonical description paragraphs; corrupting one character of a quoted paragraph reproduces the base condition and fails with README must contain the canonical description of word 0). testContainsBytesDiscriminates / testNormalizeNewlines — pin the helper edges whose silent failure would make the main check vacuous (verified by mutants below).
• Mutations applied (each killed, then restored; full suite run per probe):
  • README quoted desc[0]: convertToAssets → convertToAssetz → killed by main test (only failure, diagnostic word index).
  • LibERC4626SubParser.sol desc[0]: input order swapped to "the amount of shares as a float and the vault contract address" (README untouched) → killed by main test; no other test in the 141-test suite failed, i.e. description drift was previously invisible to the suite.
  • LibERC4626SubParser.sol desc[1]: "respects the asset and share token decimals" → "ignores..." → killed by main test (word 1).
  • test normalizeNewlines: 0x0A → 0x0B (LF normalisation disabled) → killed by testNormalizeNewlines AND the main test (proves the README really is hard-wrapped and that the main test fails without normalisation).
  • foundry.toml: README fs_permissions line removed → main test fails loudly with vm.readFile: ... not allowed, never a silent pass.
  • test containsBytes: inner mismatch check disabled (vacuous-true) → killed by testContainsBytesDiscriminates ("corrupted needle must not match"); the main test PASSED under this mutant, demonstrating the self-test is necessary.
  • test containsBytes: outer loop <= → < (end-of-haystack off-by-one) → killed by testContainsBytesDiscriminates ("match at end of haystack must be found").
• Oracle: description strings decoded from LibERC4626SubParser.authoringMetaV2() via abi.decode(..., (AuthoringMetaV2[])) — the same bytes that flow into the on-chain/metaboard meta. The test carries no expected word/description literals.
• Category check: issue Word names, input ordering, and decimal semantics are duplicated in the README as a second hand-maintained source the meta consumer reads #133 names three drift legs (word names, input ordering, decimals semantics). Names leg = open PR test(readme): assert README documents both ERC4626 word names #185 (Refs Word names, input ordering, and decimal semantics are duplicated in the README as a second hand-maintained source the meta consumer reads #133, human-directed split). This PR pins input ordering + decimals/rounding semantics via verbatim canonical descriptions. Residual, disclosed honestly: the README usage tables and rain examples remain human paraphrase adjacent to the pinned canonical text — they can still be edited independently, but the enforced canonical prose now sits directly beside them, and every enforcement failure mode probed above fails loud rather than silently green. Baseline 139/139 green before the change; 141/141 green after.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[coderabbitai]

Warning

Review limit reached

@thedavidmeister, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 42 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0f4736a7-6dd1-4ded-8383-40b93e342f6f

📥 Commits

Reviewing files that changed from the base of the PR and between eb66648 and d8e0813.

📒 Files selected for processing (3)

• README.md
• foundry.toml
• test/src/concrete/ERC4626WordsReadmeDescriptions.t.sol

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 2026-07-16-issue-133-readme-canonical-descriptions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thedavidmeister]

🤖 ai:vetter
Reviewed d8e0813: ready — closes #133 (remaining legs per human split note on #185: input-ordering + decimals prose) — README paragraphs verified verbatim against authoringMetaV2() source oracle, containment test discriminating and self-pinned, QA mutation claims spot-checked
cost 236 — verbatim-mirror test, helper-logic read

[thedavidmeister]

🤖 ai:vetter
vet-protocol 4
lens source@d8e081334729efb06dcdb3c825540a55d6a84392 + audit skill invoked at pr:259
Reviewed d8e0813: needs-work — linkage: Closes #133 must be Refs #133 (weaken_closes) — the diff pins the input-ordering + decimals legs via verbatim authoringMetaV2 descriptions (oracle non-circular, helpers fail-closed) but a word RENAME still ships a stale README at this head: nothing added here reads meta[i].word, and the names→README pin lives only in open PR #185, so closing #133 now closes it with its own minimum ask (names containment) not on main
cost 233 — source-oracle README containment test