WilliamKarolDiCioccio · Oct 9, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -151,7 +151,11 @@ gitignored. See `docs/developer-setup.md` for full setup.
 
 ## Key Documentation
 
+- `docs/adr/` -- Architecture Decision Records; start at `docs/adr/README.md`
 - `docs/developer-setup.md` -- Platform-specific build instructions
+- `docs/authoring-a-flavor.md` -- Building a whitelabel flavor
+- `docs/diagnostics-known-risks.md` -- Known risks of the diagnostics screen
+- `docs/refreshing-backend-schema-snapshots.md` -- Refreshing the haiku.rag schema snapshots
 - `docs/send-cancel-lifecycle.md` -- Message send/cancel state machine
-- `docs/plans/0001-app-shell/proposal.md` -- Shell architecture design
+- `docs/plans/0001-app-shell/proposal.md` -- Original shell plan (historical; partly superseded)
 - `docs/plans/citations-ui/` -- Citations feature design and data flow
diff --git a/docs/adr/ADR-003-flavor-object.md b/docs/adr/ADR-003-flavor-object.md
@@ -1,12 +1,13 @@
 # ADR-003: Reify the Flavor — a Declaration Object Between Composition and Boot
 
-- **Status:** Proposed
+- **Status:** Accepted (implemented in #428 and #430)
 - **Date:** 2026-07-16
 - **Authors:** William Karol Di Cioccio
 - **Supersedes:** —
 - **Amends:** ADR-002 §2 (barrel-boundary change shipped in #426) and §3.9/§5.2
   (link contrast policy)
 - **Superseded by:** —
+- **Amended by:** #536 (`runSoliplexShell` takes a builder; §2, §4)
 
 ---
 
@@ -156,9 +157,9 @@ final flavor = await standardFlavor(
 runSoliplexShell(flavor.build());
 ```
 
-> Since superseded: `runSoliplexShell` takes the builder — `await
-> runSoliplexShell(flavor.build)` — so a configuration failure reaches the
-> screen rather than stalling the launch. The rest of this record stands.
+> **Amended by #536 (2026-09-02):** `runSoliplexShell` takes the builder —
+> `await runSoliplexShell(flavor.build)` — so a configuration failure reaches
+> the screen rather than stalling the launch. The rest of this record stands.
 
 ---
 
@@ -225,7 +226,8 @@ construction, failing even earlier with the same message. Deferred until the
   sits on top of it, not instead of it. (This change renames #426's
   `StandardModules` / `buildStandardModules` to `StandardKit` /
   `buildStandardKit` and relocates it beside `standard.dart`; §6.)
-- `runSoliplexShell(ShellConfig)` and the shell widget tree.
+- The shell widget tree. (`runSoliplexShell` itself changed later: it takes
+  a `ShellConfig` builder since #536; see §2.)
 - The shipped Soliplex app's behavior, byte for byte.
 
 ---

diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -0,0 +1,91 @@
+# Architecture Decision Records
+
+An ADR records one decision that is costly to reverse: the context, what
+was decided, what was rejected and why, and what it costs. Write one when a
+change does any of the following:
+
+- binds people outside this repo: forks consuming the library, the backend
+  team, deployers or IdP operators;
+- sets a rule every contributor must follow, such as a layering rule, a
+  logging rule or a state-management idiom;
+- has security impact;
+- settles something that has been rewritten or argued about more than once.
+
+A rule in `CLAUDE.md` says *what* to do. The ADR behind it says *why*, so
+that the rule can be changed deliberately rather than eroded.
+
+## Index
+
+| ADR | Title | Status | Date |
+| --- | ----- | ------ | ---- |
+| [ADR-001](ADR-001-reactive-state-management-scoped-statebus.md) | Reactive state management via scoped `StateBus` and ownership-based discovery | Accepted | 2026-04-28 |
+| [ADR-002](ADR-002-customizable-brand-theme.md) | Customizable `BrandTheme` via a façade and a lowering buffer | Accepted, amended by ADR-003 §1.3 | 2026-06-24 |
+| [ADR-003](ADR-003-flavor-object.md) | Reify the `Flavor`: a declaration object between composition and boot | Accepted, amended by #536 | 2026-07-16 |
+
+The repo-wide rule "Riverpod is DI only; signals carry state" is argued in
+ADR-001 §5.3, among the rejected alternatives.
+
+## Conventions
+
+- **File name.** `ADR-NNN-kebab-case-title.md`, three-digit and sequential.
+  Numbers are never reused.
+- **Status.**
+  - `Proposed`: under discussion, not yet in code.
+  - `Accepted`: decided, and the code follows it.
+  - `Superseded`: replaced by a later ADR, linked in `Superseded by`.
+  - `Deprecated`: no longer applies and not replaced.
+
+  Move an ADR to `Accepted` in the PR that implements it.
+- **Changing an accepted ADR.**
+  - Do not rewrite the decision. For a narrower change, add a dated
+    `> **Amended by <ADR or PR> (YYYY-MM-DD):** ...` note at the affected
+    section, and list it in the header's `Amended by`.
+  - When the change reverses the decision, write a new ADR and mark the old
+    one `Superseded`.
+- **Scope.** One decision per ADR. A record that settles several independent
+  axes should list them in a "Decisions by axis" section, or be split.
+- **Update this index** in the same PR that adds or changes an ADR's status.
+
+## Template
+
+```markdown
+# ADR-NNN: <Decision, stated as an outcome>
+
+- **Status:** Proposed
+- **Date:** YYYY-MM-DD
+- **Authors:** <names>
+- **Supersedes:** —
+- **Superseded by:** —
+- **Amends:** — <optional: ADR-NNN §x>
+
+---
+
+## 1. Context and Problem Statement
+
+What forces the decision. Cite code paths, issues and PRs.
+
+## 2. Decision
+
+The decision in a few sentences, plus a sketch or code shape if it helps.
+
+## 3. The Decisions, by Axis
+
+Optional. One subsection per independent sub-decision, each with its reason.
+
+## 4. Consequences
+
+What gets easier, what gets harder, and who is bound (forks, backend,
+deployers, contributors). Name how the decision is enforced: a test, a lint,
+a CI check, or review only.
+
+## 5. Known Limitations and Open Questions
+
+## 6. Migration
+
+Omit for a retroactive record of a decision already in code.
+
+## 7. Alternatives Considered
+
+| Alternative | Why rejected |
+| ----------- | ------------ |
+```
diff --git a/docs/developer-setup.md b/docs/developer-setup.md
@@ -36,23 +36,13 @@ Using VS Code, and the analyzer disagrees with the pin? See **Troubleshooting**.
 ## Quick Start
 
 ```bash
-# The ag_ui dependency is fetched from a Git LFS-enabled repo whose
-# binary assets we don't use, and one of its LFS objects is missing
-# upstream — which aborts the clone during pub get. We need only its
-# pure Dart sources (not LFS-tracked), so skip the LFS smudge filter:
-export GIT_LFS_SKIP_SMUDGE=1
-
 # Install dependencies
 flutter pub get
 
 # Run the app
 flutter run -d macos   # or: -d ios, -d chrome, -d android
 ```
 
-Add `export GIT_LFS_SKIP_SMUDGE=1` to your shell profile (`~/.zshrc`,
-`~/.bashrc`) so it persists. CI sets this automatically for its
-`pub get` step.
-
 ## Platform Setup
 
 ### macOS

diff --git a/docs/plans/0001-app-shell/proposal.md b/docs/plans/0001-app-shell/proposal.md
@@ -4,6 +4,15 @@
 **Date:** 2026-03-11
 **Branch:** `feat/shell-core`
 
+> **Partly superseded.** This is a historical plan, not the current design.
+> `ModuleContribution` and "no base class, no registry" (decision 2) were
+> replaced by the `AppModule` lifecycle in #172. Flavor functions were
+> replaced by the `Flavor` declaration object
+> ([ADR-003](../../adr/ADR-003-flavor-object.md)). Riverpod-as-DI and
+> signals (decisions 3 and 4) stand, and are the subject of
+> [ADR-001](../../adr/ADR-001-reactive-state-management-scoped-statebus.md).
+> For the current architecture see `CLAUDE.md` and `docs/adr/`.
+
 ## Context
 
 The old `soliplex_frontend` is a white-label Flutter app configured via