Decisions

Decisions

Every choice that was hard enough to argue about is written down as an ADR in docs/decisions/. This page is the index; those files are authoritative.

Fourteen of the sixteen are accepted. The two still Proposed wait on the same missing evidence — nobody has yet exercised a real GitHub wiki — though on different halves of it. ADR-0001 wants the rendering spike: does the native GitHub wiki reader present pages the way the flat ---separated filename scheme assumes? ADR-0002 wants a credentialled clone and push against a disposable wiki.

They are provisional rather than unimplemented. The code already follows both: page filenames use the -- scheme with the id chain as the hierarchy of record, and the GitHub adapter takes its token from BERRYWIKI_GITHUB_TOKEN rather than from a clone URL that could be logged. If the evidence contradicts either, the code changes with the ADR.

ADR	Decision	Status
0001	Page filename strategy	Proposed, provisional until the live compatibility spike.
0002	Authentication strategy	Proposed, blocked on live verification. Defers GitHub App auth to ADR-0016.
0003	Implementation language	Accepted. Rust; no TypeScript and no hand-written JavaScript.
0004	Page metadata format	Accepted for Phase 0 — the hidden block. A central manifest stays deferred.
0005	UI technology for the MVP	Accepted (2026-07-11). Server-rendered, zero-<script>.
0006	Draft model	Accepted (2026-07-11). Explicit Save and Save-draft, never silent autosave.
0007	Generated client-script doctrine	Accepted (2026-09-03). Generated-only, under provenance constraints.
0008	Safe mutation, crash recovery, app state	Accepted (2026-07-11). Atomic writes, out-of-clone state, the writer lock.
0009	The git sync engine	Accepted (2026-07-11). A deliberately closed set of git operations.
0010	The store-to-git sync layer	Accepted (2026-07-11). One store mutation becomes one commit.
0011	Attachments	Accepted (2026-09-03).
0012	Accessibility	Accepted (2026-09-03).
0013	Backup and restore	Accepted (2026-09-03).
0014	CherryTree import	Accepted (2026-09-03).
0015	Import formats and the dependency doctrine	Accepted (2026-09-03). Supersedes ADR-0014's deferred D-11 row.
0016	Deployment model and commit identity	Accepted (2026-09-03).

Three that explain the shape of the code

ADR-0003 and ADR-0007 together are why there is no JavaScript. ADR-0003 bans TypeScript and hand-written JavaScript outright. ADR-0007 then answers the question ADR-0003 left open — whether generated client script may ever ship — and rules that it may, but only with a checked-in manifest recording, per artefact, its source files, the pinned toolchain that emitted it, the hash of the emitted bytes as CI reproduces them, and the routes allowed to reference it.

Nothing shipped changed when that was ruled. The no-<script> test stays in place byte-for-byte until a first generated artefact actually lands, and the manifest gate has to exist before it may be relaxed. The ADR is blunt about why: a weak version of that gate would be a fake gate.

ADR-0008 is why a crash cannot cost you a page. Writes are atomic, the state BerryWiki keeps for itself lives outside the clone, and one wiki has at most one writer at a time.

ADR-0015 is why the dependency list is one crate long. Plain-text formats are hand-rolled rather than pulled in; binaries the user already has, such as pandoc or sqlite3, may be shelled out to behind an explicit flag but are never taken as dependencies, and never invoked silently.

Reading further

Package-by-package state is in docs/execution/work-packages.adoc, and known debt — including the absence of the proofs the project intends to have — is in docs/execution/debt-register.adoc.