Skip to content

docs+fix: audit the documentation against the code, and make attribution correct - #348

Merged
Broccolito merged 2 commits into
mainfrom
docs/audit-and-attribution
Sep 20, 2026
Merged

Broccolito merged 2 commits into
mainfrom
docs/audit-and-attribution

Conversation

@Broccolito

Copy link
Copy Markdown
Collaborator

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:

  • 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. A reader who checked it would have discarded the whole warning.
  • 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 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. The Windows release archive carries no LICENSE while 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.
  • 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 §4 permits adding ours alongside; removing theirs would violate it. Goose ships no NOTICE, so §4(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 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'. 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'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.

Verification

Gate Result
cargo test --workspace --lib --bins 15 suites, 7746 passed, 0 failed
vitest run (excl. the known browser-teardown hang) 535 files, 6179 passed, 0 failed
landing/scripts/check-consistency.mjs pass (34 failures on main)
landing/scripts/check-docs-privacy.mjs pass
scripts/check-version-consistency.sh pass, all on 1.91.0
scripts/check-brand-consistency.sh pass
scripts/check-vendored-computer-use.sh pass, 396 files

Known, deliberately not done

  • The browser tests that exercise the real rewriter under the real CSP skip rather than fail when Playwright's Chromium is absent, so that verification never runs in CI. Wiring it up needs a browser install in the frontend workflow.
  • 28 added lines still carry em dashes. They are in ## Related documentation bullets, whose exact format is mandated by docs/contributing/documentation-style.md.

…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.
@Broccolito
Broccolito merged commit 670263e into main Sep 20, 2026
17 checks passed
@Broccolito
Broccolito deleted the docs/audit-and-attribution branch September 20, 2026 10:50
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