docs+fix: audit the documentation against the code, and make attribution correct - #348
Merged
Merged
Conversation
…ion correct Three separate strands, all found by checking claims against the code rather than against other documents. DOCUMENTATION. 109 audited findings across docs/, landing/ and the root files. The ones worth naming, because a reader was being told something false: - Workspace Control was documented as off by default, and on the public site that was framed as a safety assurance. It ships on, and its surface includes reading and steering other conversations. - The documented procedure for clearing Biorouter's data did not clear it. It named the config directory for chats and logs, which live under the data and state directories, and on Linux it used a capitalisation that matches nothing on a case-sensitive filesystem. - Auto Visualiser was described as 33 tools rendering figures inline in the chat. It advertises three tools covering 32 figure kinds, and figures open in the side panel. - The privacy page stated "the screenshot is of the whole display, not of one window". screen_capture takes a display or a window_title, so the advice was right and the stated mechanism was false. - RELEASE.md documented a headless-linux phase and a verify script that do not exist, and the three BUILDING documents left a reader with a build that could not complete. The landing site's own consistency guard had been failing for three releases (34 failures). It is now clean. Six of those failures were the guard itself, which asserted sidebar rows named Chat, History and Apps that the app has never had; it now derives the list from AppSidebar.tsx. ATTRIBUTION. Three licence gaps, all of which were shipping: - The Windows package redistributed llama.cpp binaries with no MIT notice, because the Windows release archive carries no LICENSE while the macOS and Linux ones do. Packaging now fetches it from the pinned build and refuses to package without it. - Four of the seven JavaScript and CSS assets inlined into every Auto Visualiser figure carried no notice of any kind. Every version was confirmed by checksum against upstream rather than read off a banner. - The root LICENSE carried only Block, Inc.'s copyright. Biorouter is a fork of Goose and the licence said so while the copyright line did not. Apache-2.0 s4 permits adding ours alongside; removing theirs would violate it. Goose ships no NOTICE, so s4(d) imposes nothing, and the new root NOTICE is practice rather than obligation. FIXES. Each has a regression test that was watched failing against the old code: - The Windows assisted updater told users to extract a zip while the downloader had already switched to preferring Biorouter-Setup-<ver>.exe. The dialog branched on process.platform when it needed to branch on the artifact. - --max-turns announced a default of 1000 while DEFAULT_MAX_TURNS is 100, and biorouter configure pre-filled 1000 as the current value, so accepting that dialog silently wrote 1000 and raised the real limit tenfold. - Mermaid shipped as 10.9.0 vendored and a floating mermaid@11 on the CDN, so the same diagram rendered two ways inside one app and the CDN version moved with no commit. Both are now 11.17.2, pinned exactly, with chart.js, d3 and d3-sankey pinned exactly too (chart.js@4 had already drifted to 4.5.1 against a vendored 4.5.0). A drift guard reads each version out of the shipped bytes and refuses a floating pin. - Pinning exactly would have broken every Mermaid figure already in a user's history, because the desktop rewriter matched CDN URLs by exact string and artifacts render under default-src 'none'. The rewriter is now version tolerant per package, anchored to the jsdelivr origin and the full path. - render_class_diagram's from/to were documented only as "first" and "second". Inheritance reads the opposite way round to every other relation type, which is Mermaid's grammar, so the contract is now stated in both the struct and the model-facing tool description. Also adds a landing phase to scripts/release.sh. Nothing in that script touched landing/, which is why the site sat three releases behind. It runs after publish and refuses to run before, because the site's versions are fallbacks for when GitHub is unreachable and must name a release that exists.
`NodeJS.Platform` is a global namespace eslint's `no-undef` does not know in this file's environment, so CI's zero-warning lint failed on it while a file-scoped lint run passed. `typeof process.platform` says the same thing and stays inside a binding eslint already has.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three strands, all found by checking claims against the code rather than against other documents.
Documentation
109 audited findings across
docs/,landing/and the root files. The ones worth naming, because a reader was being told something false:screen_capturetakes a display or awindow_title, so the advice was right and the stated mechanism was false. A reader who checked it would have discarded the whole warning.RELEASE.mddocumented aheadless-linuxphase and a verify script that do not exist, and the three BUILDING documents left a reader with a build that could not complete.The landing site's own consistency guard had been failing for three releases (34 failures). It is now clean. Six of those were the guard itself, which asserted sidebar rows named
Chat,HistoryandAppsthat the app has never had; it now derives the list fromAppSidebar.tsx.Attribution
Three licence gaps, all of which were shipping:
LICENSEwhile the macOS and Linux ones do, so the filter that "included LICENSE" included nothing. Packaging now fetches it from the pinned build and refuses to package without it.LICENSEcarried only Block, Inc.'s copyright. Biorouter is a fork of Goose and the licence said so while the copyright line did not. Apache-2.0 §4 permits adding ours alongside; removing theirs would violate it. Goose ships noNOTICE, so §4(d) imposes nothing, and the new rootNOTICEis practice rather than obligation.Fixes
Each has a regression test that was watched failing against the old code.
Biorouter-Setup-<ver>.exe. The dialog branched onprocess.platformwhen it needed to branch on the artifact.--max-turnsannounced a default of 1000 whileDEFAULT_MAX_TURNSis 100, andbiorouter configurepre-filled 1000 as the current value, so accepting that dialog silently wrote 1000 and raised the real limit tenfold.mermaid@11on the CDN, so the same diagram rendered two ways inside one app and the CDN version moved with no commit. Both are now 11.17.2 pinned exactly, withchart.js,d3andd3-sankeypinned too (chart.js@4had already drifted to 4.5.1 against a vendored 4.5.0). A drift guard reads each version out of the shipped bytes and refuses a floating pin.default-src 'none'. Found by an adversarial reviewer after the first version passed every required test. The rewriter is now version tolerant per package, anchored to the jsdelivr origin and the full path, proven against 30 hostile URLs and 10 hostile tag shapes.render_class_diagram'sfrom/towere documented only as "first" and "second". Inheritance reads the opposite way round to every other relation type, which is Mermaid's grammar, so the contract is now stated in both the struct and the model-facing tool description.Also adds a
landingphase toscripts/release.sh. Nothing in that script touchedlanding/, which is why the site sat three releases behind. It runs after publish and refuses to run before, because the site's versions are fallbacks for when GitHub is unreachable and must name a release that exists.Verification
cargo test --workspace --lib --binsvitest run(excl. the known browser-teardown hang)landing/scripts/check-consistency.mjsmain)landing/scripts/check-docs-privacy.mjsscripts/check-version-consistency.shscripts/check-brand-consistency.shscripts/check-vendored-computer-use.shKnown, deliberately not done
## Related documentationbullets, whose exact format is mandated bydocs/contributing/documentation-style.md.