From a full read of every doc in the repository (not a grep). No action taken — each of these is defensible as written, and which way to go is an editorial call about who the page is for. Filing so the decision is made once, deliberately, rather than re-litigated per PR.
The risk in every case is the same one this org has already been bitten by: a fact stated in N places is a fact that can be updated in N−1 of them.
1. The registry search path — docs/guides/artifacts.md:76-83 and docs/guides/fetch.md:9-16
The same four-slot list, worded differently.
The case for leaving it: artifacts.md opens by saying it "is what a consumer needs" and names fetch.md as "the normative contract underneath it." Making a consumer click through for something this basic is worse UX than repeating it.
The case against: if a slot is ever added, removed or reordered, both must change, and nothing enforces it.
My read: leave the list, but consider a test that asserts the two agree — the same shape as python/tests/test_parity.py asserting the manifest and bindings.md agree. Cheaper than choosing between UX and safety.
The "one error" message block (artifacts.md:162-172 vs fetch.md:125-135) is the same situation.
2. "Pre-1.0 / the ABI is frozen at revision 4" — README.md:176, docs/support.md:76-78, docs/limitations.md:67-71
Three near-verbatim copies, and one of them carries the revision number. When the ABI moves off 4, three files must move.
Complication: README.md is a registry landing page (crates.io / npm / PyPI / pkg.go.dev render it), where being self-contained genuinely matters and a relative link is dead. So the obvious "link to one canonical place" fix is wrong for at least one of the three.
3. "Over-accepts and over-rejects are both budgeted at zero" — README.md:154, docs/index.md:46, docs/limitations.md:61
Three statements of the same guarantee, plus overlapping bullet lists at README.md:151-156 and docs/index.md:44-49 covering the same four points in different words. Same landing-page complication as above.
4. The macOS float caveat — docs/support.md:22 and :74, again in docs/limitations.md:7-13
Twice within one file. This one I think is fine: :22 is a terse bullet inside the platform list and :74 is the full explanation, which is a summary-then-detail pattern, not an accident. Included for completeness.
What I would actually do
Nothing to 1 and 4. For 2 and 3, keep README.md self-contained because it is a registry page, and let docs/index.md and docs/limitations.md state the guarantee once between them. That is one file's worth of editing and removes the two copies most likely to drift silently — but it is a judgement about voice and audience, so it is yours.
From a full read of every doc in the repository (not a grep). No action taken — each of these is defensible as written, and which way to go is an editorial call about who the page is for. Filing so the decision is made once, deliberately, rather than re-litigated per PR.
The risk in every case is the same one this org has already been bitten by: a fact stated in N places is a fact that can be updated in N−1 of them.
1. The registry search path —
docs/guides/artifacts.md:76-83anddocs/guides/fetch.md:9-16The same four-slot list, worded differently.
The case for leaving it:
artifacts.mdopens by saying it "is what a consumer needs" and namesfetch.mdas "the normative contract underneath it." Making a consumer click through for something this basic is worse UX than repeating it.The case against: if a slot is ever added, removed or reordered, both must change, and nothing enforces it.
My read: leave the list, but consider a test that asserts the two agree — the same shape as
python/tests/test_parity.pyasserting the manifest andbindings.mdagree. Cheaper than choosing between UX and safety.The "one error" message block (
artifacts.md:162-172vsfetch.md:125-135) is the same situation.2. "Pre-1.0 / the ABI is frozen at revision 4" —
README.md:176,docs/support.md:76-78,docs/limitations.md:67-71Three near-verbatim copies, and one of them carries the revision number. When the ABI moves off 4, three files must move.
Complication:
README.mdis a registry landing page (crates.io / npm / PyPI / pkg.go.dev render it), where being self-contained genuinely matters and a relative link is dead. So the obvious "link to one canonical place" fix is wrong for at least one of the three.3. "Over-accepts and over-rejects are both budgeted at zero" —
README.md:154,docs/index.md:46,docs/limitations.md:61Three statements of the same guarantee, plus overlapping bullet lists at
README.md:151-156anddocs/index.md:44-49covering the same four points in different words. Same landing-page complication as above.4. The macOS float caveat —
docs/support.md:22and:74, again indocs/limitations.md:7-13Twice within one file. This one I think is fine:
:22is a terse bullet inside the platform list and:74is the full explanation, which is a summary-then-detail pattern, not an accident. Included for completeness.What I would actually do
Nothing to 1 and 4. For 2 and 3, keep
README.mdself-contained because it is a registry page, and letdocs/index.mdanddocs/limitations.mdstate the guarantee once between them. That is one file's worth of editing and removes the two copies most likely to drift silently — but it is a judgement about voice and audience, so it is yours.