Skip to content

Restructure public documentation for release - #14

Merged
VivienP merged 1 commit into
mainfrom
docs/public-release-readiness
Aug 14, 2026
Merged

Restructure public documentation for release#14
VivienP merged 1 commit into
mainfrom
docs/public-release-readiness

Conversation

@VivienP

@VivienP VivienP commented Aug 14, 2026

Copy link
Copy Markdown
Owner

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.md goes from 2,366 to 1,235 words (excluding code blocks). Detail moves to documents that
own it, and each concern gets exactly one canonical owner.

What changed

New

  • LICENSE — MIT, Copyright (c) 2026 Vivien Perrelle. pyproject.toml and the README already
    declared 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 stated
    against 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 artifact
    behind 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.mddocs/archive/2026-implementation-roadmap.md, under a banner naming what
    supersedes it. Its "publication-ready" thesis line is corrected in the banner rather than edited
    away. docs/ROADMAP.md is now a short statement of open work only — no roadmap was invented.
  • docs/superpowers/specs/2026-08-12-cv-passport-demo-design.mddocs/designs/cv-passport-demo.md.
    The public hierarchy no longer depends on an internal tool name or a date stamp.

Corrected

  • CONTRIBUTING.md documented docker compose up -d. Every service is profile-gated, so
    docker compose config --services returns nothing — that command started no database.
  • experiment assert takes the assertion file as a positional argument, not --file.
  • .claude/tools/gates.py cited roadmap coordinates ("Slice 1/2/3/6", "Gate 0") that did not exist
    even before this change, and displayed the same broken bare docker compose up.

Claims weakened to match evidence — none promoted

  • docs/SPEC.md and docs/DATA_STRATEGY.md were headed planned while much of what they specify is
    demonstrated; both are now labelled as the normative documents they are.
  • docs/SIMULATOR_MODEL.md said planned; the simulator is deferred and has no adapter.
  • AI_CONTRACT.md §2 said LabBridge "is demonstrated through" a biosensor environment that has no
    implementation.
  • Removed "portfolio value" / "portfolio hardening"; dropped the fault-tolerance and
    multi-fidelity package 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 at
    docs/ARCHITECTURE_DECISIONS.md:394, byte-identical on main)
  • sha256sum -c SHA256SUMS.txt — 16/16, regenerated for the moved and new documents
  • python .claude/tools/check_agent_system.py — 0 errors
  • labbridge validate-artifacts — 8/8 bundles verified
  • pytest -q -m "not slow and not data and not integration" — 721 passed
  • ruff format --check, ruff check, mypy --strict, git diff --check — all clean

The documented demo was executed rather than assumed: docker compose --profile demo up -d --build --wait exits 0 and http://localhost:8000/ returns HTTP 200.

Reviewed with the repository reviewer and data-integrity-reviewer lenses; both returned
APPROVE-WITH-WARNINGS and every warning is addressed in this branch.

Limitations and follow-up

  • The LIMITATIONS.md inside the Gamry, electrolysis, and EchemDB artifacts still describes each as
    an "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.
  • Private vulnerability reporting must be enabled once in Settings → Security for the channel
    SECURITY.md describes to exist.
  • No code of conduct and no CITATION.cff. Both need information that should not be invented.
  • No demo screenshot is published. The committed browser artifact exists, but the project's own rule
    ties publication to human acceptance records that do not yet exist.

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.
@VivienP
VivienP merged commit fc53486 into main Aug 14, 2026
3 checks passed
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