From 90e98d23752edb4685be25ab46b5cc4fc4c877d8 Mon Sep 17 00:00:00 2001
From: Julien Calixte <julien.calixte@theodo.com>
Date: Thu, 14 May 2026 12:50:12 +0200
Subject: [PATCH] docs(v0.1): cross-link technical doc to ADRs and qfd
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a companion-docs header and inline ADR jumps on every load-bearing
choice (ADR-001 runtime, ADR-002 UI, ADR-004 git kill-switch, ADR-006
concurrency, ADR-007 storage, ADR-009 USB-host gate). Render module
also points at qfd §3 to anchor "why these functions rank top."
---
 docs/v0.1-mvp-technical.md | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/docs/v0.1-mvp-technical.md b/docs/v0.1-mvp-technical.md
index 316f878..5d4a6c8 100644
--- a/docs/v0.1-mvp-technical.md
+++ b/docs/v0.1-mvp-technical.md
@@ -2,12 +2,20 @@
 
 > Scope: ships the product surface in [`v0.1-mvp-product.md`](v0.1-mvp-product.md).
 > No more, no less.
+>
+> Decisions referenced inline point at [`adr.md`](adr.md). Tradeoff weights
+> and the critical-performance budget live in [`qfd.md`](qfd.md). Project
+> overview: [`../README.md`](../README.md). Release sequence:
+> [`roadmap.md`](roadmap.md).
 
 ## Architecture
 
-Single Rust binary on `esp-idf-rs` (std). Two cores, several threads, one
-shared editor state behind a mutex. Wi-Fi and git work happens off the input
-thread so the typing path is never blocked by I/O.
+Single Rust binary on `esp-idf-rs` (std) —
+[ADR-001](adr.md#adr-001-language-and-runtime--rust-on-esp-idf-rs-std).
+Two cores, several threads, one shared editor state behind a mutex
+([ADR-006](adr.md#adr-006-concurrency--stdthread--channels-no-async-runtime)).
+Wi-Fi and git work happens off the input thread so the typing path is never
+blocked by I/O.
 
 ```
                 ┌──────────────────────────────────────────┐
@@ -71,6 +79,10 @@ Target boot time: ≤ 5 s to cursor (v0.1). The 3 s target is v1.0.
 
 We do **not** try to build the whole stack and turn it on. Each spike below
 is a small program that proves one risk before we commit to the next layer.
+Spike 7 is the kill-switch for
+[ADR-004 (gitoxide)](adr.md#adr-004-git-implementation--gitoxide-gix);
+spike 4 is the gate for
+[ADR-009 (USB host)](adr.md#adr-009-keyboard-transport--usb-host-tinyusb).
 
 1. **Spike 1 — Blink.** Confirm toolchain, flash, and basic GPIO.
 2. **Spike 2 — EPD.** Drive the GDEY0579T93 (via DESPI-c579 breakout) over
@@ -119,6 +131,11 @@ Anything else is ignored in v0.1.
 
 ### `render` — dirty-rect to EPD
 
+Custom widget layer on `embedded-graphics` —
+[ADR-002](adr.md#adr-002-ui-strategy--custom-widgets-on-embedded-graphics-not-ratatui).
+Owns the top-ranked engineering functions (latency, refresh-region area)
+in [qfd.md §3](qfd.md#3-house-of-quality--whats--hows).
+
 - A render request is a `RenderOp { Lines(range) | Status(text) | FullRefresh }`.
 - The render thread maintains a shadow of the current screen contents per
   region (header / edit area lines / status).
@@ -131,6 +148,9 @@ Anything else is ignored in v0.1.
 
 ### `persistence` — SD I/O
 
+Storage split rationale:
+[ADR-007](adr.md#adr-007-storage-split--fat-on-sd-for-working-copy-littlefs-on-flash-for-config).
+
 - Atomic save: write to `notes.md.tmp`, fsync, rename. We accept FAT's
   weakness here; on power loss between rename and dir flush, the user gets
   the previous version, which is the documented behavior.
@@ -149,6 +169,12 @@ Anything else is ignored in v0.1.
 
 ### `git` — commit + push
 
+`gitoxide` choice and kill-switch:
+[ADR-004](adr.md#adr-004-git-implementation--gitoxide-gix).
+Auth model: [ADR-005](adr.md#adr-005-auth--https--github-personal-access-token).
+PSRAM heap during push is a top-3 watched metric — see
+[qfd.md §6](qfd.md#6-critical-performance-budget).
+
 - `gix` with the smart-HTTP transport backed by `esp-idf` mbedtls (via a
   custom transport impl, or `gix-transport` with `reqwest`+`rustls-mbedtls`
   if that path is cleaner — decided in spike 7).
@@ -187,6 +213,9 @@ for SPI buffers).
 
 ## Concurrency model
 
+Rationale and rejected alternatives:
+[ADR-006](adr.md#adr-006-concurrency--stdthread--channels-no-async-runtime).
+
 - Editor state behind a single `Mutex`. Holders: `ui_task` (writer),
   `render_task` (reader, snapshot then unlock), `git_task` (reader for save).
 - No `await` / no async runtime — std threads only. Simpler debugging on