julien/typewriter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add "Durability before delivery" principle to Publish UX

Browse Source 
The user-meaningful moment of a Publish is when the local commit
lands (~0.2 s), not when the push completes (~5–10 s). New principle
in CONTEXT.md, instantiated in v0.1 product doc with staged status
transitions and a corrected on-demand Wi-Fi status example.
This commit is contained in:
Julien Calixte
2026-05-17 12:54:09 +02:00
parent 011f79f134
commit b7a0aa7c5c
2 changed files with 23 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
CONTEXT.md
View File

@@ -92,6 +92,12 @@ into user-facing language).
detail the device authors itself. Branches are out of scope for the same
reason — the device tracks one linear stream of work on whichever branch
the remote was cloned on, and never switches.
- **Durability before delivery.** A **Publish**'s user-meaningful moment is
when the local commit lands (~0.2 s), not when the push completes
(~5–10 s). The status line surfaces the commit-landed state as soon as
it exists; the remaining push time is the transport of an already-safe
thing. Long-form rationale:
[`docs/notes/ctrl-g-perceived-latency.md`](docs/notes/ctrl-g-perceived-latency.md).
- **No state the user didn't ask for.** No banners about pending work, no
prompts about divergence, no "did you mean to publish" warnings. The status
line reflects the _current_ action's outcome, nothing else.

28
docs/v0.1-mvp-product.md
View File

@@ -72,7 +72,7 @@ Auth model rationale: [ADR-005](adr.md#adr-005-auth--https--github-personal-acce
[POWER ON, config present]
│
▼
Boot (~3 s): Wi-Fi reconnect in background
Boot (~3 s): Wi-Fi stays off (brought up on demand by `Ctrl-G`)
│
▼
Open /sd/local/notes.md, place cursor at end of file
@@ -82,13 +82,14 @@ Auth model rationale: [ADR-005](adr.md#adr-005-auth--https--github-personal-acce
│
├── Ctrl-S → write file, full refresh, status: "saved 14:02"
│
└── Ctrl-G → save if dirty, then:
git add .
└── Ctrl-G → save buffer; in parallel: commit locally + bring Wi-Fi up
(if nothing staged: status "nothing to publish", stop)
git commit -m "<ISO-8601 timestamp>"
git push
└─ on failure: git pull --no-edit, retry push
status: "published abc1234" or "publish failed: <reason>"
git add . && git commit -m "<ISO-8601 timestamp>"
t≈0.2 s, status: "✓ committed abc1234 · pushing…"
once Wi-Fi up: git push
└─ on failure: git pull --no-edit, retry push once
t≈5–10 s, status: "✓ pushed abc1234" or "publish failed: <reason>"
(local commit preserved either way)
```
## Screen layout
@@ -114,14 +115,19 @@ context," not a full page. Hardware rationale: [ADR-003](adr.md#adr-003-display-
│ │
│ │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ INSERT • unsaved • Wi-Fi ✓ │ ← status
│ INSERT • unsaved • Wi-Fi — │ ← status
└─────────────────────────────────────────────────────────────────────────────────────┘
```
- Header: filename, dirty indicator (●/○), wall clock if SNTP has set time.
- Status: mode (always `INSERT` in v0.1), save state, Wi-Fi state. After a
`Ctrl-S` / `Ctrl-G`, status briefly shows the action result (saved at /
pushed `abc1234` / error message) then returns to default.
- Status: mode (always `INSERT` in v0.1), save state, Wi-Fi state
(`—` = off, `✓` = connected, `✗` = failed; default is `—` because the
radio is on-demand). `Ctrl-S` briefly flashes "saved at HH:MM" and
returns. `Ctrl-G` transitions through `✓ committed abc1234 · pushing…`
at ~0.2 s — the commit-landed moment, when the user's work is durable
(see "Durability before delivery" in [`CONTEXT.md`](../CONTEXT.md)) —
and ends at `✓ pushed abc1234` (or `publish failed: <reason>`, with the
local commit preserved either way).
- Cursor: solid block at the insertion point. **No blink.**
Fonts: one mono font, embedded in firmware. Target sizing: a 14 px mono