The old ADR documented the specific panel choice (GDEY0579T93 + DESPI-c579)
as if it were a freshly weighed option, but the hardware was already on
hand — the real architectural decision was choosing the medium (e-ink over
FSTN graphical / Sharp Memory LCD / OLED-TFT). Rewrite the ADR around the
medium with the panel as instantiation, note the Freewrite Alpha (2023)
data point as honest expectation-setting, and propagate the anchor /
narrative changes through qfd.md, v0.1-mvp-product.md, and README.md.
Move light/dark theme from v1.x stretch into v1.0 Polish as a
runtime-switchable, persisted setting, and extend font selection to
cover adjustable font size with the same persistence. Drop spell-check
from the stretch list — no longer in scope.
Convert every `ADR-NNN` mention in qfd.md to a `[ADR-NNN]` shortcut
reference and add the link definitions at the bottom of the file, so
each ADR mention navigates to the matching adr.md section.
- Re-anchor W1..W4 source links to the renumbered v0.1 user stories
(story 1 "First run" was deleted in the v0.1 refresh).
- W2 now points at ADR-010 and CONTEXT.md as well as the product spec.
- W4 reframed from "first-run setup" to "one-shot provisioning, never
repeated mid-session" so it covers both the v0.1 build-time path and
the v0.9 on-device path.
- ADR-005 tradeoff row rewritten: "captive-portal form" was wrong after
the v0.1 refresh; replaced with the binary-as-secret-store framing.
- New ADR-010 row in the tradeoffs table.
- Read-across notes flag that C12 owns ADR-010's implementation but not
its UX contract, and that C11 LittleFS is unused in v0.1.
- Section 8 picks up three new cross-doc inconsistencies that were
spotted and fixed during the refresh (commit-message format mismatch,
captive-portal vs. solo target user, vocabulary leak resolved by
CONTEXT.md).
Two coupled changes that emerged from one /deep-design session, both touching
the same v0.1 paragraphs:
(1) Align Ctrl-G with the user's existing gct shell alias: git add . ->
short-circuit if nothing staged -> commit with an ISO-8601 timestamp (no
wip prefix) -> push -> on push failure, git pull --no-edit then retry.
Atomic from the user's view. Recorded as ADR-010. The previously-planned
v0.7 commit-message-prompt item is removed; it contradicts the
gct/timestamp model.
(2) Replace the v0.1 captive-portal first-run with build-time env-var
config: build.rs reads TW_* env vars and embeds them as constants. No
NVS read, no LittleFS mount, no AP mode, no HTTP server. The v0.1
target user is the dev themselves; the first release usable by non-dev
users is v0.9, and the v0.9 settings entry is reframed accordingly.
ADR-005 updated to describe the build-time path and the v0.9 migration.
The two changes share files because the v0.1 spec is one interlocked
document; splitting further would require line-level surgery without
improving auditability.
CONTEXT.md fixes the project's user-facing vocabulary (Tracked, Local,
Save, Publish) and the principles that fall out of those definitions
(the device is a writing tool, not a sync engine; it does no git work
the user did not explicitly request). README's file-scopes section and
repo-layout listing point at the new glossary so a first-time reader
lands on canonical definitions, and the ADR log carries an inbound link
so future ADRs can rely on the same terms.
The original row collapsed C and C++ together, but they trade differently
on the ESP-IDF target (RAII, generics, binary size, exception story). Split
them so the language-and-runtime decision actually reflects what was
considered.
The customer-requirements (WHATs) Source column was plain text ("product
§UX", "README v0.8"). Replace with anchored Markdown links into the
product spec, README, and roadmap so each requirement's provenance is
one click away.
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."
Adds a "Companion docs" header (README, technical, ADR, QFD, roadmap)
and inline pointers from the auth section to ADR-005, the screen
layout to ADR-003, and the acceptance criteria block to qfd §6 — so
each "what must this do" claim has a one-click jump to its rationale
or target.
Adds inline pointers from ADR-007 (storage) to the v0.1 technical
persistence + file-layout sections, from ADR-008 (power) to the v0.1
out-of-scope and roadmap v0.8, and from ADR-009 (keyboard) to spike 4
in the v0.1 technical bring-up order.
Adds a "Related docs" header at the top of adr.md and inline "See also"
pointers from ADR-001 (binary/build tradeoffs → qfd §7) and ADR-002
(render module → v0.1 technical, top H1/H2 functions → qfd §3). Makes
the design-doc set walkable instead of a flat list.
Macro-plan dates start 2026-06-01 with `after` dependencies between
versions. Per-version checklists move to docs/roadmap.md so the README
stays synthetic.
Translates user-facing requirements (the WHATs) into engineering
functions (the HOWs) and components, with a House-of-Quality matrix,
roof tradeoffs, function→component mapping (anchored to ADRs), and a
critical performance budget keyed to upcoming spikes. Cross-references
adr.md throughout.
Prior text said "~40 KB of stack space"; the v0.1 technical design's
task table sums to 76 KB (usb 8 + wifi 8 + ui 16 + render 12 + git 32).
Also widens the std::thread stack-cost note from a flat 8 KB to 8–32 KB
to match the per-task budget. No design change — 76 KB still fits
comfortably in the ESP32-S3's 512 KB internal SRAM.
Pins Node 24 via .node-version, declares pnpm 10.32.1 as packageManager
in package.json, and adds oxfmt as a dev dependency with .oxfmtrc.json
(single quotes, no semi, 80 cols). Ignores node_modules.
Strip-aspect 5.79" panel (792×272) replaces the page-shaped 7.5" choice.
Reflows the v0.1 screen layout, framebuffer memory budget, and spike 2
acceptance to validate the SSD1683-class controller path or fall back to
a ~300 LoC custom embedded-hal driver.
Sets language (Rust on esp-idf-rs), rejects Ratatui and Gleam+Shore with
reasons, locks the MVP scope to "write, save, push one file" and defines
nine downstream releases so each ships a usable artifact.
