Restructure public documentation for release - #14
Merged
Conversation
The README had become a development log: 2,366 words carrying a 30-row capability table, delivery-phase coordinates, and CLI catalogues that an unfamiliar reader had to parse before learning what LabBridge does. It is now 1,235 words and defers detail to the documents that own it. docs/PROJECT_STATUS.md becomes the single owner of capability status, so a status can no longer drift between documents. docs/GETTING_STARTED.md owns the runnable path, docs/README.md indexes by reader intent, and docs/ROADMAP.md states only open work instead of an unapproved plan. The completed delivery plan moves to docs/archive/ under a banner, and the demo design record moves off a tool-specific path into docs/designs/; both are retained for decision traceability. Two documented commands were wrong rather than merely stale: CONTRIBUTING told contributors to run `docker compose up -d`, which starts nothing now that every service is profile-gated, and `experiment assert` takes the assertion file as a positional argument, not --file. LICENSE materialises the MIT grant that pyproject.toml and the README already declared. Stale statuses are corrected downward: SPEC and DATA_STRATEGY no longer say `planned`, SIMULATOR_MODEL says `deferred`, and AI_CONTRACT no longer says LabBridge is demonstrated through an environment that has no adapter. No capability status was promoted.
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.
Summary
Turns the repository documentation into a public entry point an unfamiliar scientist or engineer can
use, and adds the licence file the project declared but never shipped. Documentation and repository
presentation only — no runtime behaviour, no product code, no artifact bytes changed.
README.mdgoes from 2,366 to 1,235 words (excluding code blocks). Detail moves to documents thatown it, and each concern gets exactly one canonical owner.
What changed
New
LICENSE— MIT,Copyright (c) 2026 Vivien Perrelle.pyproject.tomland the README alreadydeclared MIT; no file carried the grant. The built wheel now ships
dist-info/licenses/LICENSE.SECURITY.md— routes reports through GitHub private vulnerability reporting, with scope statedagainst what the project actually is (no auth, no tenancy, no deployment).
docs/PROJECT_STATUS.md— the single owner of capability status, each claim linked to the artifactbehind it and the boundary that artifact does not cross.
docs/GETTING_STARTED.md— install, demo, CLI file-to-Package workflow, artifact verification.docs/README.md— documentation index organised by reader intent.Moved, retained for traceability
docs/ROADMAP.md→docs/archive/2026-implementation-roadmap.md, under a banner naming whatsupersedes it. Its "publication-ready" thesis line is corrected in the banner rather than edited
away.
docs/ROADMAP.mdis now a short statement of open work only — no roadmap was invented.docs/superpowers/specs/2026-08-12-cv-passport-demo-design.md→docs/designs/cv-passport-demo.md.The public hierarchy no longer depends on an internal tool name or a date stamp.
Corrected
CONTRIBUTING.mddocumenteddocker compose up -d. Every service is profile-gated, sodocker compose config --servicesreturns nothing — that command started no database.experiment asserttakes the assertion file as a positional argument, not--file..claude/tools/gates.pycited roadmap coordinates ("Slice 1/2/3/6", "Gate 0") that did not existeven before this change, and displayed the same broken bare
docker compose up.Claims weakened to match evidence — none promoted
docs/SPEC.mdanddocs/DATA_STRATEGY.mdwere headedplannedwhile much of what they specify isdemonstrated; both are now labelled as the normative documents they are.docs/SIMULATOR_MODEL.mdsaidplanned; the simulator isdeferredand has no adapter.AI_CONTRACT.md§2 said LabBridge "is demonstrated through" a biosensor environment that has noimplementation.
fault-toleranceandmulti-fidelitypackage keywords, the latter contradicting the project's own "not two fidelities"rule.
Validation
Run on a clean checkout carrying these changes:
python scripts/check_docs.py --strict— 0 errors, 0 drift (1 pre-existing warning atdocs/ARCHITECTURE_DECISIONS.md:394, byte-identical onmain)sha256sum -c SHA256SUMS.txt— 16/16, regenerated for the moved and new documentspython .claude/tools/check_agent_system.py— 0 errorslabbridge validate-artifacts— 8/8 bundles verifiedpytest -q -m "not slow and not data and not integration"— 721 passedruff format --check,ruff check,mypy --strict,git diff --check— all cleanThe documented demo was executed rather than assumed:
docker compose --profile demo up -d --build --waitexits 0 andhttp://localhost:8000/returns HTTP 200.Reviewed with the repository
revieweranddata-integrity-reviewerlenses; both returnedAPPROVE-WITH-WARNINGS and every warning is addressed in this branch.
Limitations and follow-up
LIMITATIONS.mdinside the Gamry, electrolysis, and EchemDB artifacts still describes each asan "uncommitted candidate". That was true when the bytes were produced and is now stale, but those
files sit inside closed SHA-256 manifests and a released artifact is immutable. Correcting the
wording requires regenerating the artifacts; the discrepancy is recorded in
docs/ROADMAP.md.Settings → Securityfor the channelSECURITY.mddescribes to exist.CITATION.cff. Both need information that should not be invented.ties publication to human acceptance records that do not yet exist.