[M0-R][DOCS] Establish the canonical source-of-truth documentation baseline

[andreazedda]

Scope

Addresses #14 by establishing the first canonical documentation/source-of-truth baseline against:

base master = bf097810b337dc6b766cda04497005670cd96513
current branch head = 3bc54788f8a17143a0cd6fe21fdf66d35f6e81d2
intended use = E1_research_prototype

What this PR changes

Canonical product and governance baseline

• mission and north star: virtual patients, current/experimental therapies, falsification, reproducible protocols and Knowledge Commons;
• current verified state;
• capabilities and limitations;
• roadmap and current critical path;
• source-of-truth hierarchy and conflict protocol;
• documentation policy and machine-readable inventory.

Current versus target architecture

• adds a verified current-system architecture;
• adds a separately labelled target virtual-laboratory architecture;
• converts the former architecture guide into a compatibility pointer;
• prevents target models from being presented as current capabilities.

Mathematical/model documentation

• maps every current twin_engine/model_registry.json model to its version, entry point and maturity status;
• documents current ODE/PK/PD, observation, exposure, toxicity-signal and counterfactual utility formulas;
• defines variables, units/evidence status, worked examples, limitations and falsification criteria;
• marks the therapy-design model as a hypothetical toy model.

Research and operations contracts

• documents Twin/computational-input lineage;
• documents comparability and append-only invalidation;
• documents the target M1 Research Loop and allowed failure states;
• documents current authentication/access gaps and the smoke-user boundary;
• documents current tests, numerical baseline, synthetic-data and CI limitations;
• records the current dependency-security blocker, immediate remediation [M0-R][DEPENDENCIES] Triage newly disclosed Django and sqlparse advisories blocking the canonical baseline #69 and durable Django 5.2 LTS migration [M0-R][FRAMEWORK] Migrate the unsupported Django 4.2 baseline to Django 5.2 LTS #70.

Public documentation repair

• rewrites README and docs landing page around current state and target mission;
• rebuilds MkDocs navigation around Product, Architecture, Models, Research Contracts, Operations, Governance, Reference, Learning and Archive;
• updates the changelog through the current M0-R foundations;
• replaces obsolete security/version/authentication claims in SECURITY.md;
• removes root RELEASE_PREPARATION.md and adds a historical archive record that explicitly invalidates its old release/coverage claims;
• makes strict MkDocs build run on documentation pull requests without deploying PR content.

Source-of-truth boundary

code/schemas/registries/machine-readable governance
> current GitHub docs at verified SHA
> GitHub issues/PR/evidence
> Notion dashboard and decisions
> architecture DOCX proposals
> historical archives

The architecture DOCX remains a target proposal and is not modified in this PR.

Change classification

runtime code: no
scientific equations/runtime outputs: no
DB schema/migrations: no
private data: no
documentation/governance: yes
security wording: yes
navigation: yes
historical archive: yes
CI docs-trigger behavior: yes

Privacy and intended-use impact

• no private clinical payload was accessed or added;
• no intended-use expansion;
• current status remains E1 research prototype;
• no clinical recommendation, validated patient prediction or causal-effect claim is introduced.

Validation evidence — head 3bc54788...

Docs strict MkDocs build: PASS — run 32671631453
Secret Scan: PASS — run 32671631459
uv lock --check: PASS
frozen chemistry sync: PASS
Ruff check: PASS
Ruff format check: PASS
mypy: PASS
repository hygiene: PASS
numerical baseline: PASS / unchanged
Python 3.11 core check/tests: PASS
Python 3.12 core check/tests: PASS
Docker locked build: PASS
dependency audit: FAIL — exact current advisory blocker

The dependency workflow is red because current advisory data identifies vulnerabilities in the unchanged canonical lock:

django 4.2.30  PYSEC-2026-3717
sqlparse 0.5.4 PYSEC-2026-3696, 3697, 3698, 3699

This PR did not change pyproject.toml or uv.lock. The immediate supply-chain work is tracked in #69; durable migration from unsupported Django 4.2 to Django 5.2 LTS is tracked in #70. The findings will not be bypassed or hidden inside this documentation change.

Current blocker

BLOCKED_BY_ISSUE_69_DEPENDENCY_REMEDIATION
BLOCKED_BY_ISSUE_70_DJANGO_5_2_MIGRATION

A green documentation build does not make the canonical M0-R dependency baseline green.

Non-goals

• no [M0-R][CI] Consolidate existing workflows into mandatory scientific quality gates and protected PR governance #13 CI consolidation beyond adding PR-time docs validation;
• no [M0-R][QA] Enforce the minimum scientific invariants and define the extended test architecture #23 QA expansion;
• no dependency/framework upgrade in this PR;
• no product-auth/RBAC implementation;
• no production runtime change;
• no new Patient Twin calibration, patient-specific what-if or biological model.

Rollback

Revert the documentation commits on this branch. No database or numerical migration is required.

Next dependency

1. remediate the immediate lock/advisory findings through [M0-R][DEPENDENCIES] Triage newly disclosed Django and sqlparse advisories blocking the canonical baseline #69;
2. migrate the framework baseline through [M0-R][FRAMEWORK] Migrate the unsupported Django 4.2 baseline to Django 5.2 LTS #70;
3. re-run PR [M0-R][DOCS] Establish the canonical source-of-truth documentation baseline #68 and mark it ready only when its required baseline is governed;
4. merge and complete [M0-R][DOCUMENTATION] Establish the versioned documentation source of truth #14 evidence;
5. unblock [M0-R][CI] Consolidate existing workflows into mandatory scientific quality gates and protected PR governance #13; [M0-R][QA] Enforce the minimum scientific invariants and define the extended test architecture #23 Phase A remains blocked until the stable aggregate CI gate exists.

[andreazedda]

Supersession notice — 2026-08-24

This draft was created before dependency PR #71 and Django 5.2 LTS PR #72 became canonical. The branch has since been synchronized with protected master and the documentation content has been reconciled to master=a33418fb....

To obtain a fresh pull-request event and complete current-head validation against the supported dependency baseline, this PR is being superseded by a replacement PR from the same synchronized documentation branch.

No documentation work is discarded. Issue #14 remains open until the replacement PR passes and merges.