Goals and strategy documents, with the toolchain consolidation as decision 1

[jcschaff]

Two direction documents and a map, none of which existed. Nine analysis and record documents had accumulated; nothing said what we are building, for whom, or in what order. Documentation only; no code changes.

docs/goals.md

Who it is for, eight goals, what done looks like, Year 3 specifically, and non-goals stated outright. Written to be readable by the External Advisory Board and to be the document the Year 3 report is checked against.

Every goal traces to a tracker row. Where a Year 2 forward commitment exists it is quoted verbatim, and all ten quotes were verified as substrings of the RPPR files with whitespace normalised.

Shaped by four answers given in review:

Question	Answer
primary user	a collaborating project installing the toolkit; the CLI is the product, the API its backend
production quality of what	all four, sequenced: reliability, then installability, then reproducibility, then breadth
trust scope this year	registered simulators only, stated as an access-control boundary rather than an isolation one
the two hosted backends	they should converge, and the strategy says how to begin

docs/strategy.md

The four-layer model, four decisions, sequencing and risks.

Decision 1 consolidates the toolchain. The evidence, all measured: the service uses 17% of pbest (188 of 1,096 lines, five symbols, closed set), and the other 83% is the local-or-remote CLI that is the product. The service executes composites on process-bigraph 1.0.5 while the ecosystem runs 1.8.4, thirty-seven releases and 251 days behind, because the exact pin on pbest transitively freezes the engine. The workbench ecosystem depends on the foundation directly and on pbest not at all. bsander and bsew were the previous generation of the same pipeline, superseded in February 2026.

The lineage is stated plainly and the contributions acknowledged. Attribution is a section rather than a sentence: merge with git subtree so blame keeps naming authors, note that CITATION.cff already credits both, archive rather than delete, add a lineage document, and archive pbest last, only after a release ships from its new home.

The phases include one that did not exist before the 17% measurement: put the local execution path under test before upgrading the engine, because the upgrade lands almost entirely in code the service never runs and pbest's own suite barely covers.

Decision 2 makes identity a digest and sequences it before breadth. Decision 3 records the trusted-tier scope with its trigger for change. Decision 4 names convergence with viva-api as a goal and gives read-only first steps. That repository is in vivarium-collective and was not touched.

docs/README.md, and keeping all of this off the public site

The document map lives in docs/README.md, which GitHub renders when browsing the folder. index.md, the public landing page, is restored to what it was.

These documents are internal and are not published. mkdocs builds every file under docs/ unless told otherwise, and the release workflow runs gh-deploy, so without a change the next release would have published the goals, the strategy, both plans, the ecosystem survey, the CIP review and the grant tracker. exclude_docs in mkdocs.yml now lists them. Verified by building the site and listing its pages: only index.html and modules/index.html remain.

What the reports say

Checked against Year 1, Year 2 and the advisory board report. The three libraries are named in neither report, nor to the board. The reported product is the Compose API and the engine, so consolidating retracts nothing anyone was told. Year 2 claimed the Compose-API kernel marks the standard's transition "from design to operational use", which the engine lag undercuts, making the upgrade a reporting obligation. The board's praise for a sibling tool's low maintenance burden is the argument for this work, quoted in their words.

One trap recorded for the Year 3 report: both prior reports count repositories as output, and this work archives three.

Verification

• mkdocs build -s clean; both documents linked from the index.
• make check clean.
• Ten report quotes verified verbatim.

🤖 Generated with Claude Code

https://claude.ai/code/session_018TgVbCXXWAWhNjtKTzrxvN