From 721bce1019b8db72ea9902641ca682393f747027 Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Sun, 23 Aug 2026 17:45:57 -0400
Subject: [PATCH 1/6] =?UTF-8?q?docs(design):=20the=20web=20UI=20rewrite=20?=
 =?UTF-8?q?=E2=80=94=20zero-dependency,=20view-source,=20on-device?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Records the design for replacing render.py's server-side HTML with a JSON API
plus plain ES modules, following youperiod.app's technical philosophy.

The three findings that shaped it:

- Installing the app FROM keeltrading.com cannot work. keel's data is a local
  SQLite file; an HTTPS page cannot reach 127.0.0.1 reliably, and the exits are
  a tunnel or a hosted service — both excluded. The PWA is therefore served by
  keel itself, where localhost is already a secure context.

- keel's docs/ is the SOURCE, not a duplicate: keeltrading.com fetches it at
  build time and fails loudly if a pinned document vanishes. What ships is the
  app code dropping doc prose and deep-linking instead — which also fixes an
  already-shipping bug, since the wheel carries no docs/ and /glossary renders
  an empty state in every installed deployment.

- --good and --bad have the same relative luminance in light mode (1.01:1), so
  profit and loss are separated by hue alone. Fails WCAG 1.4.1 in a trading app.
  Contrast becomes a CI assertion, not a design review.

Zero third-party JS is achievable because crypto lives in Python and money
crosses the wire as pre-formatted strings, so the client never computes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyeggYtojNXCTHeD3JHxb6
---
 .../specs/2026-08-23-web-ui-rewrite-design.md | 287 ++++++++++++++++++
 1 file changed, 287 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md

diff --git a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
new file mode 100644
index 0000000..4ee3a66
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
@@ -0,0 +1,287 @@
+# Design — The web UI rewrite: a zero-dependency, view-source console
+
+**Status:** proposal · **Date:** 2026-08-23 · **Supersedes:** the HTML-rendering half of D2 (#435)
+
+## The ask
+
+> "Rewrite Keel's UI to be used on mobile, desktop, laptop, or tablet. Easy to navigate for simple
+> and newbie users. Strip out all documents from Keel and point the new UI to keeltrading.com
+> documents. Technically I propose PWA to avoid stores' fees and the app will be installed from
+> keeltrading.com."
+
+Refined across the design conversation to: **keel stays entirely on the user's device, open source
+and free, no server reach.** A paid analysis service is explicitly a *different app and repository*
+and is out of scope here. The technical philosophy to follow is
+[youperiod.app's](https://github.com/getify/youperiod.app/discussions/36).
+
+## The answer in one paragraph
+
+Most of this already shipped. `keel serve` (#435) binds `127.0.0.1:8765`, mints a session token and
+renders eight routes; D1, D3, D5 and D6 are closed and only D4 (#437, the first-run wizard) is open.
+What is left is one layer: **`keel/web/render.py`'s 872 lines of server-side HTML generation get
+deleted, and the local process serves JSON plus static files instead.** The client becomes plain ES
+modules — no framework, no bundler, no transpile, no minification, no source maps, and *zero*
+third-party JavaScript. Two things make that last claim achievable rather than aspirational: keel's
+cryptography lives in Python and the OS keychain, never in the browser (so youperiod's three
+dependencies have no analogue here), and **money crosses the wire as pre-formatted strings**, so the
+client never performs arithmetic and never needs a decimal library. The one part of the original ask
+that cannot be built is installing the app *from* keeltrading.com — that is an origin problem, not a
+preference, and §3 records why.
+
+---
+
+## 1. What exists today
+
+| component | lines | state |
+|---|---|---|
+| `keel/commands/serve.py` | 89 | binds loopback, mints a one-time token, opens the browser |
+| `keel/web/server.py` | 639 | 8 GET routes + a POST write surface at `/setup/` (#469) |
+| `keel/web/render.py` | 872 | server-side HTML, inline stylesheet, no JavaScript |
+| `keel/web/security.py` | 164 | session token |
+| `keel/commands/tui.py` | 5,063 | curses TUI (+ 4,369 lines of tests) |
+
+Routes: `/`, `/setup`, `/activity`, `/insights`, `/rules`, `/venues`, `/gates`, `/glossary`.
+
+D-series status: **D1 #434 · D2 #435 · D3 #436 · D5 #438 · D6 #439 all closed. D4 #437 open.**
+
+`render.py`'s own docstring states the invariant this design must preserve:
+
+> "This module is a THIRD renderer over the same reports, never a second place that computes them."
+
+`tests/commands/test_console_thinness.py` pins that property today. It must pin the API layer after.
+
+## 2. The reference, and what actually transfers
+
+youperiod.app is 137 KB total. Its `server.js` is 4,865 bytes and performs **no rendering** — its
+entire job is serving static files with correct security headers. The client is ~35 KB of
+hand-written ES modules across eight files, one 3.9 KB stylesheet, no build step.
+
+**Transfers directly:** the no-framework rule; the "third-party code needs strong justification, not
+preference" bar; no transpiling, bundling, minifying, or source maps; security headers as the
+server's main job; offline, performant and accessible by default.
+
+**Does not transfer:** youperiod is client-only because it has *no engine*. Its data is what the user
+typed; the browser is the app; IndexedDB is the database. keel is the inverse — a Python process
+wakes on a schedule, talks to the venue, enforces the rails and writes SQLite **with no browser
+open.** IndexedDB therefore cannot be keel's store of record.
+
+The *guarantee*, however, does transfer intact. youperiod's "no stateful server" means your data
+never leaves your device. keel's equivalent is **the server is on your device.**
+
+**Explicitly rejected:** youperiod encrypts everything at rest behind a 12-character passphrase.
+keel cannot. The agent runs unattended via launchd; a passphrase-locked database is one nobody can
+open at 03:00. Passphrase-at-rest and unattended autonomy are mutually exclusive, and autonomy is the
+deliberate choice. The correct analogue is D4's plan: **OS keychain for credentials**, filesystem
+permissions for the database, FileVault/BitLocker for at-rest.
+
+## 3. Why the app cannot be installed from keeltrading.com
+
+keel's data is a SQLite file on the operator's machine, written by a local process holding venue
+credentials. A page served from `https://keeltrading.com` is a **different origin** and cannot read
+it. It could only fetch it from the local server, and an HTTPS page fetching `http://127.0.0.1:8765`
+is precisely the path browsers are tightening — Private Network Access preflights in Chrome, blocked
+outright in Safari. It is inconsistent today and narrowing.
+
+The only two exits are giving the local server a real TLS certificate (requires a tunnel — excluded
+by "no server reach"), or moving the data to a hosted service (a different product, explicitly out of
+scope).
+
+**Therefore: the PWA is served by the origin that serves the data, which is keel itself.**
+`http://127.0.0.1` **is** a secure context by specification, so a service worker, a web app manifest
+and browser install all work there with no networking decision at all. keeltrading.com hosts the
+install instructions and the documentation — which is what it already does.
+
+**Consequence, recorded plainly: iPhone and Android are out of scope.** Not deferred by choice —
+excluded by the constraint. There is no keel on iOS, and "no server reach" removes the tunnel that
+was the only way a phone could have reached the desktop process. The UI is still built responsive,
+because desktop windows get dragged narrow, touch devices running a full OS are in scope, and it
+costs almost nothing while the CSS is being written anyway.
+
+## 4. Architecture
+
+### 4.1 Process model
+
+```
+launchd ──► keel agent (daily)  ──►  SQLite  ◄──  keel serve  ──►  127.0.0.1:8765
+                                                                     │
+                                              ┌──────────────────────┴───────────┐
+                                              │  GET  /            static assets │
+                                              │  GET  /api/*       JSON          │
+                                              │  POST /api/*       gated actions │
+                                              └──────────────────────────────────┘
+```
+
+Static assets and the API share **one origin**, so there is no CORS story at all. Do not split them.
+
+### 4.2 The API contract
+
+The API is a *fourth* consumer of the same frozen report dataclasses the console and the TUI already
+consume. It never computes; it serialises what `gather_status`, `build_insights_report` and their
+siblings already return.
+
+**Money crosses the wire as strings, never as JSON numbers.** `JSON.parse` yields IEEE-754 doubles,
+and keel is `Decimal`-only for exactly the reason that matters here. A serialisation test fails the
+build if any monetary field emits a JSON number.
+
+**The API emits presentation-ready values.** Not `{"qty": "0.01", "price": "50000"}` for the client
+to multiply — `{"notional": "500.00", "notional_display": "$500.00"}`. Every figure a user sees was
+computed by the Python that holds the rails. This is what lets `test_console_thinness.py` extend to
+the API layer, and it is what makes §4.3's zero-dependency claim possible.
+
+### 4.3 The client
+
+Plain ES modules, served as authored. **No framework, no bundler, no transpile, no minification, no
+source maps** — per §4 of the reference philosophy, the code running must be byte-identical to the
+code the user reads in devtools. gzip is fine.
+
+**Zero third-party JavaScript.** Applying the reference's own bar — a dependency must be justified
+because getting it wrong ourselves would undermine the project's principles — nothing clears it:
+
+| need | answer |
+|---|---|
+| charts | SVG polyline, hand-rolled (~150 lines) |
+| live updates | `EventSource` (SSE) |
+| dates | `Intl.DateTimeFormat` |
+| routing | History API over one shell |
+| decimal arithmetic | **none required** — §4.2 |
+| cryptography | Python + OS keychain, never the browser |
+
+**Type checking without a build step:** `// @ts-check` with JSDoc annotations and `tsc --noEmit` in
+CI. Types are checked; nothing is transpiled and nothing shipped is altered.
+
+### 4.4 Security headers
+
+The server's principal job, as in the reference.
+
+- `default-src 'self'` — no CDN, no web fonts, no analytics, no third-party anything.
+- **`connect-src 'self'`** — the UI is *provably incapable* of sending positions, equity or trade
+  history to any origin but the local process. Browser-enforced, one header, verifiable in seconds.
+  This is a stronger claim than keel can make today and should be documented as a feature.
+- `X-Content-Type-Options: nosniff`; Subresource Integrity on any inline `<script>`.
+- Loopback bind and the session token are retained unchanged.
+
+### 4.5 The capability asymmetry
+
+**The client hiding a button is not a gate.** Capability-increasing actions are refused by the API,
+keyed to the session token, with D3's human gate (#436) in front. The client may be fully read and
+modified by its user and still cannot arm a rule, attest an asset, or enable autonomy.
+
+## 5. Documentation
+
+`keel/commands/help_console.py:138-146` records a bug that is already shipping:
+
+> "an installed deployment has no docs/ checkout, and the help screen renders that notice as its
+> empty state"
+
+`pyproject.toml` confirms it — `artifacts = ["keel/templates/*.yaml"]`. The wheel ships `.py` files
+and one YAML template. **No `docs/`.** So `/glossary` renders an empty state in every installed
+deployment, including the signed bundle D5 produces.
+
+**The pipeline runs the opposite way from the original ask.** keeltrading.com's
+`engine-docs.manifest.json` pins `CodeGateSoftware/keel@main`, and `scripts/fetch-engine-docs.mjs`
+declares itself *"the only writer of `src/content/engine-docs/`"* and exits non-zero if a pinned
+document disappears. **keel's `docs/` is the source; the website is the mirror.** Deleting `docs/`
+from keel would fail the website build, loudly, by design.
+
+What ships instead: the **application code** stops carrying documentation prose. Glossary and help
+deep-link to `https://keeltrading.com/{lang}/docs/{slug}`, which yields en/fr/ar for free — the
+manifest already carries all three, and keel's in-app copy is English-only. A one-line definition
+stays inline (the manifest provides one per document, in three languages) so losing the network
+degrades to terse rather than blank. Outbound links are navigation and are unaffected by
+`connect-src`.
+
+## 6. Accessibility, as an acceptance criterion
+
+Measured against the current palette (`render.py:41-49`). **Text contrast is already good** — every
+foreground passes AA on both surfaces in both themes, most pass AAA (`fg` on `bg` 16.50:1 light,
+15.06:1 dark; `muted` 5.32:1 / 6.19:1). Two failures, one specific to this being a trading app:
+
+**6.1 — `--good` and `--bad` are the same brightness.** In light mode `#1f5f4f` has relative
+luminance 0.0904 and `#96322a` has 0.0893 — a delta of 0.0011, a ratio of **1.01:1**. Profit and loss
+are separated by hue alone. `render.py:82` confirms it: `.good { color: var(--good); }` and
+`.bad { color: var(--bad); }` are pure colour classes. This fails WCAG 1.4.1 *Use of Color*, and the
+practical consequences are that roughly one in twelve men cannot reliably distinguish gains from
+losses, and that greyscale, e-ink and direct sunlight collapse the distinction entirely.
+
+*Fix:* never encode P&L in colour alone — `▲ +2.4%` / `▼ −2.4%`, where glyph and sign carry the
+meaning and colour reinforces it. Separate the two luminances as well. Split `--accent` from
+`--good`, which are byte-identical in both themes today, so a link and a gain no longer render alike.
+
+**6.2 — form inputs have no visible boundary.** `render.py:96-97` gives `.field input` the page
+background with a `--line` border at **1.27:1**. The border is the only thing marking the control,
+which fails WCAG 1.4.11 *Non-text Contrast* (3:1 for UI component boundaries). Decorative dividers at
+1.27:1 are exempt and stay; form controls are not, and this lands squarely on D4's wizard, which is
+almost entirely forms.
+
+**6.3 — checked in CI, not by eye.** The WCAG contrast formula is about twenty lines of Python with
+no dependencies. Every foreground/background pair asserts its minimum ratio and `good`/`bad` assert a
+minimum luminance separation, so a palette regression fails the build. This is §2 of the reference
+philosophy applied to design: no tooling, no dependency, just the arithmetic in a readable test.
+
+**6.4 — baseline:** semantic HTML, native form elements, `aria-live`/`aria-atomic` on status regions
+that change underneath the reader, full keyboard paths, visible focus.
+
+## 7. Newbie usability is mostly not a front-end problem
+
+Recorded so effort lands where it pays. Today's navigation is eight peers — an operator's mental
+model. The levers, in order of impact: **D4's wizard (#437)**, which replaces roughly ten CLI
+invocations and hand-edited YAML; **progressive disclosure**, one "everything is fine / here is the
+one thing to do" surface with the eight operator views behind a second tier; and **plain language
+with working documentation links** (§5). None of the three is improved by the choice of front-end
+technology.
+
+## 8. Decisions recorded
+
+1. **The TUI is kept.** It is the only surface that works over SSH on a headless host, and deletion
+   is a one-way door. The cost is two front-ends. *This decision is cheap to reverse later and
+   expensive to reverse early; #525's concern about `keel/commands/` being larger than the engine is
+   better addressed on its own terms.*
+2. **Zero third-party JavaScript**, per §4.3. Any future exception requires the reference's bar:
+   justified because getting it wrong ourselves would undermine keel's principles.
+3. **No build step**, per §4.3 — including no source maps.
+4. **Money as strings**, per §4.2.
+5. **Mobile phones are out of scope**, per §3.
+6. **`docs/` stays in keel**, per §5.
+
+## 9. Non-goals
+
+- Any hosted service, account system, telemetry, or analytics.
+- The paid analysis tier — a different app and repository.
+- Encrypting the database at rest behind a passphrase (§2).
+- Replacing SQLite as the store of record.
+- Widening what the browser may *do*; §4.5's asymmetry is preserved exactly.
+
+## 10. Phases
+
+| # | phase | content |
+|---|---|---|
+| W1 | JSON API | Serialise the existing reports; money-as-strings rule and its test; extend `test_console_thinness.py` to the API layer |
+| W2 | Static serving + headers | §4.4 in full, SRI, asset packaging into the wheel and the bundle |
+| W3 | Client shell | Nav, status view, responsive CSS, palette fixes and the contrast test (§6) |
+| W4 | Remaining views | The other seven routes, SVG charts, SSE live updates |
+| W5 | PWA | Manifest, icons, service worker — **shell only, never data** (§11) |
+| W6 | Documentation | Glossary and help to keeltrading.com; inline one-liners |
+| W7 | Removal | Delete `render.py`'s HTML generation and retire the HTML routes |
+
+## 11. Risks
+
+- **A service worker caching data would be actively dangerous** — opening the app to last week's
+  equity styled as current is worse than an error. Cache the shell only; when the engine is not
+  running, render *"keel isn't running"*, never a stale figure.
+- **Deleting `render.py` breaks the existing thinness pins.** W1 must land the API pins before W7
+  removes the HTML ones.
+- **The signed bundle must include the static assets**; `pyproject.toml`'s `artifacts` list currently
+  covers only the YAML template.
+- **A no-build client has no compile-time safety net** by default; mitigated by `tsc --noEmit` (§4.3).
+- **Distribution tension.** §4 of the reference philosophy prizes view-source auditability, but D5
+  ships a PyInstaller bundle containing `.pyc`, not readable `.py`. Under this philosophy the
+  `curl | bash` wheel installer (#479) is the *more* aligned channel. Worth deciding consciously
+  rather than by default; the web UI is fully auditable in-browser under either.
+- **Version skew:** the website pins `main` while an operator runs a tagged release.
+
+## 12. Open questions
+
+1. Do the manifest, icons and service worker ship in the wheel, or only in the desktop bundle?
+2. Should the installer bundle a rendered documentation snapshot for offline use, at the cost of a
+   build-time dependency on the website's output — or link out only?
+3. §11's distribution tension: is the signed bundle still the primary channel?

From 9f2a5aca5340f4309dbb15f199e57830d0c99f31 Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Sun, 23 Aug 2026 18:08:48 -0400
Subject: [PATCH 2/6] docs(design): documentation is linked, never embedded
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Resolves §12's second open question. The app fetches, bundles and caches
nothing: it opens keeltrading.com/en/docs/{slug}/#{anchor} in a new tab.

Verified this needs no new infrastructure. docs/glossary.md already states its
own rule -- "Each entry is a `## term` heading" -- and the built site carries
the IDs: dist/en/docs/glossary/index.html has id="rail", id="attestation",
id="kill-switch", id="qabd". So the anchor contract is just kebab-casing the
heading, covered by a test that every anchor the app emits exists upstream.

Consequences: /glossary, render_glossary() and the web layer's glossary reader
are deleted rather than ported -- a link needs no renderer. No offline fallback,
deliberately; an operator running a trading engine has network by definition,
and the least technology that does the job is the correct amount.

Version skew is now the main residual risk and is recorded as such: the site
pins main while an operator runs a tagged release.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyeggYtojNXCTHeD3JHxb6
---
 .../specs/2026-08-23-web-ui-rewrite-design.md | 55 +++++++++++++++----
 1 file changed, 43 insertions(+), 12 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
index 4ee3a66..150e8c6 100644
--- a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
+++ b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
@@ -183,12 +183,35 @@ declares itself *"the only writer of `src/content/engine-docs/`"* and exits non-
 document disappears. **keel's `docs/` is the source; the website is the mirror.** Deleting `docs/`
 from keel would fail the website build, loudly, by design.
 
-What ships instead: the **application code** stops carrying documentation prose. Glossary and help
-deep-link to `https://keeltrading.com/{lang}/docs/{slug}`, which yields en/fr/ar for free — the
-manifest already carries all three, and keel's in-app copy is English-only. A one-line definition
-stays inline (the manifest provides one per document, in three languages) so losing the network
-degrades to terse rather than blank. Outbound links are navigation and are unaffected by
-`connect-src`.
+What ships instead: **nothing is fetched, embedded, bundled or cached. The app links out.** A
+documentation reference opens `https://keeltrading.com/en/docs/{slug}/#{anchor}` in a new tab
+(`target="_blank" rel="noopener"`), landing directly on the term.
+
+**This works today with no new infrastructure**, verified against the built site:
+
+- `docs/glossary.md` writes each term as a `## term` heading — an explicit rule stated in the file
+  itself: *"Each entry is a `## term` heading, a definition, and a `Source:` line."*
+- Astro already emits the IDs. `dist/en/docs/glossary/index.html` contains `id="rail"`,
+  `id="attestation"`, `id="instrument-attestation"`, `id="kill-switch"`, `id="qabd"`, `id="riba"`.
+- `src/pages/en/docs/[slug].astro` renders every pinned document at a stable path.
+
+So the anchor contract is: **kebab-case the `## term` heading.** The only maintenance burden is that
+renaming a heading upstream breaks a deep link — acceptable, and cheaply covered by a test asserting
+that every anchor the app emits exists in the corresponding source document.
+
+Outbound links are navigation, not fetches, and are therefore unaffected by `connect-src 'self'`.
+
+**Consequences.** The `/glossary` route, `render_glossary()`, and the web layer's use of
+`load_glossary()`/`parse_glossary()` are all deleted rather than ported — a link needs no renderer.
+`help_console.py`'s glossary reader stays for the TUI, which cannot open an anchor and instead prints
+the URL; the shipped-wheel empty state is the same bug there and gets the same fix.
+
+**Offline is not hedged.** No inline fallback definitions, no cached snapshot. An operator running a
+trading engine has network by definition, and per §2 of the reference philosophy the least technology
+that does the job is the correct amount.
+
+Links default to `/en/`. The site also builds `fr` and `ar`; switching the prefix is a one-line
+change if the interface is ever localised, and is not worth anticipating now.
 
 ## 6. Accessibility, as an acceptance criterion
 
@@ -241,7 +264,9 @@ technology.
 3. **No build step**, per §4.3 — including no source maps.
 4. **Money as strings**, per §4.2.
 5. **Mobile phones are out of scope**, per §3.
-6. **`docs/` stays in keel**, per §5.
+6. **`docs/` stays in keel**, per §5 — it is the source the website mirrors.
+7. **Documentation is linked, never embedded.** Nothing fetched, bundled or cached; the app opens
+   `keeltrading.com/en/docs/{slug}/#{anchor}` in a new tab. No offline fallback (§5).
 
 ## 9. Non-goals
 
@@ -260,7 +285,7 @@ technology.
 | W3 | Client shell | Nav, status view, responsive CSS, palette fixes and the contrast test (§6) |
 | W4 | Remaining views | The other seven routes, SVG charts, SSE live updates |
 | W5 | PWA | Manifest, icons, service worker — **shell only, never data** (§11) |
-| W6 | Documentation | Glossary and help to keeltrading.com; inline one-liners |
+| W6 | Documentation | Deep links to keeltrading.com; delete `/glossary` and `render_glossary()`; anchor-existence test |
 | W7 | Removal | Delete `render.py`'s HTML generation and retire the HTML routes |
 
 ## 11. Risks
@@ -277,11 +302,17 @@ technology.
   ships a PyInstaller bundle containing `.pyc`, not readable `.py`. Under this philosophy the
   `curl | bash` wheel installer (#479) is the *more* aligned channel. Worth deciding consciously
   rather than by default; the web UI is fully auditable in-browser under either.
-- **Version skew:** the website pins `main` while an operator runs a tagged release.
+- **Version skew, and it is now the main residual risk of linking out.** The website pins `main`
+  while an operator runs a tagged release, so a deep link can land on documentation describing
+  behaviour their build does not have. Cheapest mitigation is for the docs pages to state which ref
+  they were built from; pinning the site to the latest tag instead of `main` is the fuller fix and
+  is a website decision, not this one.
+- **A renamed heading breaks a deep link silently.** Covered by the anchor-existence test in §5.
 
 ## 12. Open questions
 
 1. Do the manifest, icons and service worker ship in the wheel, or only in the desktop bundle?
-2. Should the installer bundle a rendered documentation snapshot for offline use, at the cost of a
-   build-time dependency on the website's output — or link out only?
-3. §11's distribution tension: is the signed bundle still the primary channel?
+2. §11's distribution tension: is the signed bundle still the primary channel?
+
+*Resolved during design:* whether to bundle a rendered documentation snapshot for offline use —
+**no.** Link out only (§5, decision 7).

From c3281f0968c2dd6a268836938cd9c7bd85a98e70 Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Sun, 23 Aug 2026 18:40:08 -0400
Subject: [PATCH 3/6] =?UTF-8?q?docs(design):=20fold=20in=20six=20review=20?=
 =?UTF-8?q?points=20=E2=80=94=20TUI=20deletion,=20sort,=20headers,=20SW,?=
 =?UTF-8?q?=20=3Fv=3D,=20bundle?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adopted, with two mechanisms corrected:

- TUI deleted, but in W7 not W0. tui.py imports from commands/{activity,
  admission,status} -- it is a front-end over the shared report builders, not
  their owner -- so deletion never touches what the web UI reads. But D2
  requires read-surface parity first, and the 4,369 test lines ARE the
  specification of what is being ported. A second gate: W7 must confirm the
  browser (with D3's gate) covers what the TUI covered, or the non-technical
  user is stranded at a step needing a terminal.

- Sorting is server-side, not scaled integers. Precision is per-product
  (base_increment), which is exactly what #514/#517 were; a fixed 100x scale
  truncates below a cent and 1e8 caps a USD notional near MAX_SAFE_INTEGER.
  If client-side is ever wanted the field is named `sort`, is ordering-only,
  and is never displayed or summed.

- Versioned doc paths would 404 today: the site builds dist/en/docs/glossary/
  and the manifest pins ref "main". Replaced with ?v= plus a banner, which
  makes skew visible for one small website change and no new routes.

Adopted as proposed: X-Keel-Client custom header forcing a CORS preflight (a
third CSRF layer -- security.py already has Host validation, SameSite=Strict
HttpOnly cookies and an HMAC CSRF token), Sec-Fetch-Site, explicit CacheFirst/
NetworkOnly service-worker routing with the cache keyed to the build version,
and static assets as a W2 acceptance criterion with the bundle as primary.

Also added Referrer-Policy: no-referrer, since the app now links out while the
session token rides in the URL before the cookie exchange. Rejected an embedded
native window: it costs a dependency, three platform backends, and the devtools
that make the view-source claim checkable.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyeggYtojNXCTHeD3JHxb6
---
 .../specs/2026-08-23-web-ui-rewrite-design.md | 137 ++++++++++++++----
 1 file changed, 107 insertions(+), 30 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
index 150e8c6..160de54 100644
--- a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
+++ b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
@@ -24,9 +24,11 @@ modules — no framework, no bundler, no transpile, no minification, no source m
 third-party JavaScript. Two things make that last claim achievable rather than aspirational: keel's
 cryptography lives in Python and the OS keychain, never in the browser (so youperiod's three
 dependencies have no analogue here), and **money crosses the wire as pre-formatted strings**, so the
-client never performs arithmetic and never needs a decimal library. The one part of the original ask
-that cannot be built is installing the app *from* keeltrading.com — that is an origin problem, not a
-preference, and §3 records why.
+client never performs arithmetic and never needs a decimal library. The curses TUI is deleted at the
+end of the sequence — another ~9,400 lines, answering #525 — but only once the browser reaches
+parity, because its tests are the specification of what is being ported. The one part of the original
+ask that cannot be built is installing the app *from* keeltrading.com — that is an origin problem,
+not a preference, and §3 records why.
 
 ---
 
@@ -128,6 +130,17 @@ to multiply — `{"notional": "500.00", "notional_display": "$500.00"}`. Every f
 computed by the Python that holds the rails. This is what lets `test_console_thinness.py` extend to
 the API layer, and it is what makes §4.3's zero-dependency claim possible.
 
+**Sorting is server-side.** Tables sort by query parameter; Python orders with `Decimal`. On loopback
+the round trip is sub-millisecond, so there is nothing to optimise and no client arithmetic to audit.
+
+*Rejected: an integer companion field scaled to cents.* Precision here is **per-product** —
+`base_increment` varies by instrument, which is precisely what #514 and #517 were about — so a fixed
+100× scale silently truncates anything finer than a cent, and a 1e8 scale caps a USD notional near
+$90M against `Number.MAX_SAFE_INTEGER`. If instant client-side re-sort is ever wanted, the field is
+named `sort`, is a plain JSON number, and is documented as **ordering only — never displayed, never
+summed**: float imprecision is harmless for comparison and fatal for display, and the name must not
+let anyone confuse the two.
+
 ### 4.3 The client
 
 Plain ES modules, served as authored. **No framework, no bundler, no transpile, no minification, no
@@ -158,7 +171,21 @@ The server's principal job, as in the reference.
   history to any origin but the local process. Browser-enforced, one header, verifiable in seconds.
   This is a stronger claim than keel can make today and should be documented as a feature.
 - `X-Content-Type-Options: nosniff`; Subresource Integrity on any inline `<script>`.
-- Loopback bind and the session token are retained unchanged.
+- **`Referrer-Policy: no-referrer`.** New in this design because the app now links out (§5). The
+  session token rides in the URL (`/?token=…`) until the cookie exchange; modern browsers already
+  send origin-only cross-origin, so the exposure is small, but one header closes it outright.
+
+**What already exists, and must not be re-invented.** `keel/web/security.py` documents five layers:
+loopback binding; **`Host` header validation** against DNS rebinding; a session token exchanged for a
+`SameSite=Strict`, `HttpOnly` cookie (`Strict` not `Lax`, deliberately, so a link on a hostile page
+cannot arrive authenticated); a closed action set; and an **HMAC-derived CSRF token** on every write,
+described there as *"the layer that does not depend on the browser being current."* Comparisons use
+`secrets.compare_digest`.
+
+**Added as a third CSRF layer**, since `SameSite` has had parser bypasses: require a custom request
+header (`X-Keel-Client: 1`) on every `POST /api/*`, which forces a CORS preflight a hostile origin
+cannot satisfy — an HTML form POST, which is *not* preflighted, is the attack this closes. Pair it
+with a **`Sec-Fetch-Site: same-origin`** check, which page JavaScript cannot forge.
 
 ### 4.5 The capability asymmetry
 
@@ -166,6 +193,13 @@ The server's principal job, as in the reference.
 keyed to the session token, with D3's human gate (#436) in front. The client may be fully read and
 modified by its user and still cannot arm a rule, attest an asset, or enable autonomy.
 
+This is **already implemented and test-enforced**, and the rewrite must preserve it rather than
+rebuild it: the whole write surface routes through `keel.commands.setup.ACTIONS`, every member
+`MECHANICAL`, idempotent and non-destructive, and a test asserts that set is **disjoint from the
+eleven capability-increasing actions in `keel/capabilities.py`.** As `security.py` puts it, "no POST
+at all" would have been satisfied by a server that could not set anything up; this is satisfied only
+by one that cannot arm, release or spend anything.
+
 ## 5. Documentation
 
 `keel/commands/help_console.py:138-146` records a bug that is already shipping:
@@ -213,6 +247,17 @@ that does the job is the correct amount.
 Links default to `/en/`. The site also builds `fr` and `ar`; switching the prefix is a one-line
 change if the interface is ever localised, and is not worth anticipating now.
 
+**Version skew is made visible, not eliminated.** `GET /api/config` exposes the running version — it
+is needed for §4.4's cache key regardless — and outbound links carry it as `?v=0.11.2`. The docs page
+shows a banner when that does not match the ref it was built from.
+
+*Rejected: per-version documentation paths.* `keeltrading.com/en/docs/v0.11.0/glossary#qabd` **404s
+today.** The site builds `dist/en/docs/glossary/` and the manifest pins `ref: "main"`; there is no
+versioned tree. Creating one is work in the *other* repository plus a retention policy, multiplied
+across three languages and the sitemap. A query parameter and a banner cost one small website change
+and no new routes, and they surface the mismatch rather than hiding it behind a link that silently
+describes different software.
+
 ## 6. Accessibility, as an acceptance criterion
 
 Measured against the current palette (`render.py:41-49`). **Text contrast is already good** — every
@@ -255,10 +300,25 @@ technology.
 
 ## 8. Decisions recorded
 
-1. **The TUI is kept.** It is the only surface that works over SSH on a headless host, and deletion
-   is a one-way door. The cost is two front-ends. *This decision is cheap to reverse later and
-   expensive to reverse early; #525's concern about `keel/commands/` being larger than the engine is
-   better addressed on its own terms.*
+1. **The TUI is deleted — in W7, not W0.** ~9,400 lines (`tui.py` 5,063 + 4,369 of tests) go, which
+   answers #525's "`keel/commands/` is larger than the engine it drives" directly. keel is a
+   local-first, double-clickable application; optimising for headless SSH is a distraction, and
+   `windows-curses` is unmaintained.
+
+   **The ordering is the whole decision.** `tui.py` imports from `keel.commands.activity`,
+   `admission` and `status` — it is a front-end *over* the shared report builders, not their owner —
+   so deletion never touches what the web UI reads. But D2 (#435) requires parity with the TUI's read
+   surface before the write surface widens, and deleting at W0 would leave W1–W4 with no working
+   console at all. The 4,369 test lines are also the **specification of what is being ported**: they
+   record what each screen shows and when. They are retired once the new UI passes equivalents, not
+   before.
+
+   **A second gate on W7:** deleting the TUI makes the browser the only interactive surface, so
+   anything an operator could previously only reach through it must be reachable through the browser
+   *or* deliberately CLI-only first. D3 (#436) exists precisely so capability-increasing actions have
+   a GUI gate rather than a bypass; W7 must confirm coverage rather than assume it, or a
+   non-technical user — the whole point of §8.9's double-click path — ends up stranded at a step that
+   needs a terminal.
 2. **Zero third-party JavaScript**, per §4.3. Any future exception requires the reference's bar:
    justified because getting it wrong ourselves would undermine keel's principles.
 3. **No build step**, per §4.3 — including no source maps.
@@ -267,6 +327,10 @@ technology.
 6. **`docs/` stays in keel**, per §5 — it is the source the website mirrors.
 7. **Documentation is linked, never embedded.** Nothing fetched, bundled or cached; the app opens
    `keeltrading.com/en/docs/{slug}/#{anchor}` in a new tab. No offline fallback (§5).
+8. **Sorting is server-side**, per §4.2. No scaled-integer companion fields.
+9. **The signed desktop bundle is the primary channel**, and the static assets ship in it — a W2
+   acceptance criterion, not a §11 risk. The end state is double-click, no terminal command.
+10. **The browser is the window.** `webbrowser.open` as it works today; no embedded webview.
 
 ## 9. Non-goals
 
@@ -275,44 +339,57 @@ technology.
 - Encrypting the database at rest behind a passphrase (§2).
 - Replacing SQLite as the store of record.
 - Widening what the browser may *do*; §4.5's asymmetry is preserved exactly.
+- **An embedded native window** (pywebview or similar). It buys a title bar and costs a dependency,
+  three platform backends, and the devtools that make §4.3's view-source claim checkable by the
+  user. `serve.py` already opens the default browser with no dependency at all; a double-click still
+  produces a window, it simply happens to be a browser.
 
 ## 10. Phases
 
 | # | phase | content |
 |---|---|---|
-| W1 | JSON API | Serialise the existing reports; money-as-strings rule and its test; extend `test_console_thinness.py` to the API layer |
-| W2 | Static serving + headers | §4.4 in full, SRI, asset packaging into the wheel and the bundle |
+| W1 | JSON API | Serialise the existing reports; money-as-strings rule and its test; **server-side sort**; `GET /api/config` (version); extend `test_console_thinness.py` to the API layer |
+| W2 | Static serving + headers | §4.4 in full — CSP, `Referrer-Policy`, `X-Keel-Client` preflight, `Sec-Fetch-Site`, SRI. **Static assets listed in `pyproject.toml` `artifacts` and in the bundle manifest — an acceptance criterion, and the double-click path works end to end** |
 | W3 | Client shell | Nav, status view, responsive CSS, palette fixes and the contrast test (§6) |
 | W4 | Remaining views | The other seven routes, SVG charts, SSE live updates |
-| W5 | PWA | Manifest, icons, service worker — **shell only, never data** (§11) |
-| W6 | Documentation | Deep links to keeltrading.com; delete `/glossary` and `render_glossary()`; anchor-existence test |
-| W7 | Removal | Delete `render.py`'s HTML generation and retire the HTML routes |
+| W5 | PWA | Manifest, icons, service worker. **Routing is explicit: `CacheFirst` for the static shell (`index.html`, `.js`, `.css`), `NetworkOnly` for `/api/*`, no exceptions. The cache name is keyed to the build version**, so an upgraded engine cannot be met by a stale shell |
+| W6 | Documentation | Deep links to keeltrading.com carrying `?v=`; delete `/glossary` and `render_glossary()`; anchor-existence test |
+| W7 | Removal | Delete `render.py`'s HTML generation, retire the HTML routes, **and delete `tui.py` with its tests** (§8.1) — after parity, never before |
 
 ## 11. Risks
 
 - **A service worker caching data would be actively dangerous** — opening the app to last week's
-  equity styled as current is worse than an error. Cache the shell only; when the engine is not
-  running, render *"keel isn't running"*, never a stale figure.
+  equity styled as current is worse than an error. Mitigated by W5's routing rules; when the engine
+  is not running the UI fails visibly with *"keel isn't running"*, never a cached balance.
 - **Deleting `render.py` breaks the existing thinness pins.** W1 must land the API pins before W7
   removes the HTML ones.
-- **The signed bundle must include the static assets**; `pyproject.toml`'s `artifacts` list currently
-  covers only the YAML template.
+- **Deleting the TUI removes the reference implementation.** W7 only, and only once the new UI passes
+  equivalents of what `tests/commands/test_tui.py` asserts (§8.1). Deleting early would discard the
+  specification of the thing being built.
+- **`pyproject.toml`'s `artifacts` currently covers only the YAML template**, so the static assets
+  would be absent from the wheel and the bundle. Promoted to a W2 acceptance criterion.
 - **A no-build client has no compile-time safety net** by default; mitigated by `tsc --noEmit` (§4.3).
-- **Distribution tension.** §4 of the reference philosophy prizes view-source auditability, but D5
-  ships a PyInstaller bundle containing `.pyc`, not readable `.py`. Under this philosophy the
-  `curl | bash` wheel installer (#479) is the *more* aligned channel. Worth deciding consciously
-  rather than by default; the web UI is fully auditable in-browser under either.
-- **Version skew, and it is now the main residual risk of linking out.** The website pins `main`
-  while an operator runs a tagged release, so a deep link can land on documentation describing
-  behaviour their build does not have. Cheapest mitigation is for the docs pages to state which ref
-  they were built from; pinning the site to the latest tag instead of `main` is the fuller fix and
-  is a website decision, not this one.
+- **The auditability claim must stay scoped.** The bundle is the primary channel (§8.9), and
+  PyInstaller ships `.pyc`, not readable `.py` — so the *engine* is not view-source inside it. The
+  honest statement is: the **UI** is fully auditable in the browser on any device; the **engine** is
+  auditable on GitHub and from the wheel, which the `curl | bash` installer (#479) still delivers as
+  readable source. Do not let marketing collapse the two.
+- **Version skew is surfaced, not solved** (§5). A `?v=` parameter and a banner make a mismatch
+  visible; only pinning the website to the latest tag instead of `main` would remove it, and that is
+  a keeltrading.com decision.
 - **A renamed heading breaks a deep link silently.** Covered by the anchor-existence test in §5.
 
 ## 12. Open questions
 
-1. Do the manifest, icons and service worker ship in the wheel, or only in the desktop bundle?
-2. §11's distribution tension: is the signed bundle still the primary channel?
+1. Do the manifest, icons and service worker ship in the wheel as well, or only in the desktop
+   bundle? (The static assets themselves ship in both — §8.9.)
+2. Will keeltrading.com take the `?v=` banner (§5), and does it want to pin to the latest tag rather
+   than `main`?
+
+*Resolved during design:*
 
-*Resolved during design:* whether to bundle a rendered documentation snapshot for offline use —
-**no.** Link out only (§5, decision 7).
+- Bundling a rendered documentation snapshot for offline use — **no.** Link out only (§5, decision 7).
+- Whether the signed bundle is the primary channel — **yes** (§8.9), with §11's scoping caveat.
+- Whether to keep the TUI — **no**, deleted in W7 (§8.1).
+- Client-side sorting via scaled integers — **no**, sorting is server-side (§4.2).
+- An embedded native window — **no** (§9).

From 169a243b200c8981010e9da0a4243e40d9d07f4b Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Sun, 23 Aug 2026 19:47:33 -0400
Subject: [PATCH 4/6] docs(design): the TUI's SSH justification does not
 survive contact with the runbook

I had kept "works over SSH on a headless host" as the TUI's remaining reason to
exist. keel's own documentation refutes it three ways:

- No server deployment profile exists. The four profiles are trading profiles
  (live, paper, paper-hourly, paper-equities), not topologies.
- A headless live cycle already fails closed -- confirm mode "waits for a typed
  `y` at a terminal" (operator-runbook.md:365).
- "Notify-only, by design. There is no remote control surface -- no command,
  query or capability arrives through notifications, ever."
  (operator-runbook.md:864)

And granting a headless host anyway, `ssh -L 8765:127.0.0.1:8765 host` forwards
the WEB UI to a local browser: full interface, encrypted by SSH, still a secure
context because it is localhost at the reading end, no curses. Better than the
TUI on every axis.

The W7-not-W0 ordering is unaffected -- it rests on D2's parity requirement and
on test_tui.py being the specification of what is being ported, neither of which
involved SSH.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyeggYtojNXCTHeD3JHxb6
---
 .../specs/2026-08-23-web-ui-rewrite-design.md    | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
index 160de54..eebeeb7 100644
--- a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
+++ b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
@@ -302,8 +302,20 @@ technology.
 
 1. **The TUI is deleted — in W7, not W0.** ~9,400 lines (`tui.py` 5,063 + 4,369 of tests) go, which
    answers #525's "`keel/commands/` is larger than the engine it drives" directly. keel is a
-   local-first, double-clickable application; optimising for headless SSH is a distraction, and
-   `windows-curses` is unmaintained.
+   local-first, double-clickable application, and `windows-curses` is unmaintained.
+
+   **"But SSH" is not a reason, and keel's own documentation says so three ways.** There is no
+   server deployment profile — the four profiles are *trading* profiles (live, paper, paper-hourly,
+   paper-equities), not topologies. A headless live cycle already **fails closed**, because confirm
+   mode "waits for a typed `y` at a terminal" (`docs/operator-runbook.md:365`). And the project is
+   explicit that no remote surface exists at all: *"Notify-only, by design. There is no remote
+   control surface — no command, query or capability arrives through notifications, ever"*
+   (`docs/operator-runbook.md:864`).
+
+   Even granting a headless host, `ssh -L 8765:127.0.0.1:8765 host` forwards the **web** UI to a
+   local browser — full interface, encrypted by SSH, still a secure context because it is localhost
+   at the reading end, and no curses anywhere. That is better than the TUI on every axis, and
+   `keel status` covers the rest from a plain shell.
 
    **The ordering is the whole decision.** `tui.py` imports from `keel.commands.activity`,
    `admission` and `status` — it is a front-end *over* the shared report builders, not their owner —

From d99381fd344abc62d7868356b37c99a563dc511f Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Sun, 23 Aug 2026 19:54:02 -0400
Subject: [PATCH 5/6] docs(spec): reshape as technical documentation, not a PRD

youperiod's SPECS.md is technical documentation -- Server, Security Headers,
Client, file structure, present tense, concrete ports and filenames -- and Kyle
keeps the rationale somewhere else entirely (discussion #36). This document was
PRD-shaped: phases, risk tables, decision logs, competitive archaeology.

Reshaped to match. Philosophy first as numbered decision rules mirroring #36,
then Server (headers as a table of what each one prevents, plus the five layers
security.py already has and this must not rebuild), then Client (first run, the
data contract with a worked JSON payload, a bullet per JS file), then
Documentation, deletions, build order, distribution.

The rationale is kept but subordinated -- folded into the section it governs,
the way SPECS.md explains why each security header exists, rather than sitting
in separate PRD sections. Nothing verified was dropped: the origin argument, the
contrast measurements, the docs pipeline direction, the SSH refutation and the
per-product precision argument against scaled integers all survive where they
belong.

Two additions the new shape forced out:

- A worked JSON payload. Writing it made the `state` field necessary, so the
  client never infers an outcome from a sign, and it carries the glyph that
  makes gain-vs-loss survive without colour.
- "In js/external there is nothing" -- keel's inversion of the reference's
  three dependencies, and structural rather than lucky: crypto lives in Python
  and the keychain, and the client does no arithmetic.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyeggYtojNXCTHeD3JHxb6
---
 .../specs/2026-08-23-web-ui-rewrite-design.md | 684 +++++++++---------
 1 file changed, 349 insertions(+), 335 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
index eebeeb7..741867b 100644
--- a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
+++ b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
@@ -1,107 +1,71 @@
-# Design — The web UI rewrite: a zero-dependency, view-source console
-
-**Status:** proposal · **Date:** 2026-08-23 · **Supersedes:** the HTML-rendering half of D2 (#435)
-
-## The ask
-
-> "Rewrite Keel's UI to be used on mobile, desktop, laptop, or tablet. Easy to navigate for simple
-> and newbie users. Strip out all documents from Keel and point the new UI to keeltrading.com
-> documents. Technically I propose PWA to avoid stores' fees and the app will be installed from
-> keeltrading.com."
-
-Refined across the design conversation to: **keel stays entirely on the user's device, open source
-and free, no server reach.** A paid analysis service is explicitly a *different app and repository*
-and is out of scope here. The technical philosophy to follow is
-[youperiod.app's](https://github.com/getify/youperiod.app/discussions/36).
-
-## The answer in one paragraph
-
-Most of this already shipped. `keel serve` (#435) binds `127.0.0.1:8765`, mints a session token and
-renders eight routes; D1, D3, D5 and D6 are closed and only D4 (#437, the first-run wizard) is open.
-What is left is one layer: **`keel/web/render.py`'s 872 lines of server-side HTML generation get
-deleted, and the local process serves JSON plus static files instead.** The client becomes plain ES
-modules — no framework, no bundler, no transpile, no minification, no source maps, and *zero*
-third-party JavaScript. Two things make that last claim achievable rather than aspirational: keel's
-cryptography lives in Python and the OS keychain, never in the browser (so youperiod's three
-dependencies have no analogue here), and **money crosses the wire as pre-formatted strings**, so the
-client never performs arithmetic and never needs a decimal library. The curses TUI is deleted at the
-end of the sequence — another ~9,400 lines, answering #525 — but only once the browser reaches
-parity, because its tests are the specification of what is being ported. The one part of the original
-ask that cannot be built is installing the app *from* keeltrading.com — that is an origin problem,
-not a preference, and §3 records why.
+# Technical Specification: keel's web UI
 
----
-
-## 1. What exists today
-
-| component | lines | state |
-|---|---|---|
-| `keel/commands/serve.py` | 89 | binds loopback, mints a one-time token, opens the browser |
-| `keel/web/server.py` | 639 | 8 GET routes + a POST write surface at `/setup/` (#469) |
-| `keel/web/render.py` | 872 | server-side HTML, inline stylesheet, no JavaScript |
-| `keel/web/security.py` | 164 | session token |
-| `keel/commands/tui.py` | 5,063 | curses TUI (+ 4,369 lines of tests) |
+**Date:** 2026-08-23 · **Status:** specification for the target state
 
-Routes: `/`, `/setup`, `/activity`, `/insights`, `/rules`, `/venues`, `/gates`, `/glossary`.
+This document describes the browser interface keel serves from the operator's own machine: what the
+server does, what the client does, and why each decision was made the way it was. It follows the
+shape of [youperiod.app's SPECS.md](https://github.com/getify/youperiod.app/blob/main/SPECS.md) and
+the decision rules of
+[its technical philosophy](https://github.com/getify/youperiod.app/discussions/36).
 
-D-series status: **D1 #434 · D2 #435 · D3 #436 · D5 #438 · D6 #439 all closed. D4 #437 open.**
+**It describes a target, not the present.** Today `keel serve` renders HTML in Python
+(`keel/web/render.py`, 872 lines) and ships no JavaScript. What follows replaces that layer. Where a
+thing already exists it is marked as such, because the existing security model in particular must be
+preserved rather than rebuilt.
 
-`render.py`'s own docstring states the invariant this design must preserve:
+---
 
-> "This module is a THIRD renderer over the same reports, never a second place that computes them."
+## Philosophy
 
-`tests/commands/test_console_thinness.py` pins that property today. It must pin the API layer after.
+The rules used to decide everything below. They mirror the reference philosophy, adapted where keel
+differs from an app with no engine.
 
-## 2. The reference, and what actually transfers
+1. **Privacy, security and safety are the most important feature.** keel holds venue credentials and
+   places real orders. Every trade-off resolves in favour of a smaller, more auditable surface, even
+   at a cost in convenience or development speed.
 
-youperiod.app is 137 KB total. Its `server.js` is 4,865 bytes and performs **no rendering** — its
-entire job is serving static files with correct security headers. The client is ~35 KB of
-hand-written ES modules across eight files, one 3.9 KB stylesheet, no build step.
+2. **Complexity is fought at the individual decision level.** A tool or dependency is admitted only
+   when omitting it would undermine the principles above — never because it is convenient or
+   familiar. §"Dependencies" records the outcome: there are none on the client.
 
-**Transfers directly:** the no-framework rule; the "third-party code needs strong justification, not
-preference" bar; no transpiling, bundling, minifying, or source maps; security headers as the
-server's main job; offline, performant and accessible by default.
+3. **The app runs entirely on the user's device.** No hosted service, no account, no telemetry, no
+   analytics. youperiod says "no stateful server"; keel's equivalent is **the server is on your
+   device.** Nothing crosses the network but the venue calls the engine already makes.
 
-**Does not transfer:** youperiod is client-only because it has *no engine*. Its data is what the user
-typed; the browser is the app; IndexedDB is the database. keel is the inverse — a Python process
-wakes on a schedule, talks to the venue, enforces the rails and writes SQLite **with no browser
-open.** IndexedDB therefore cannot be keel's store of record.
+   Unlike youperiod, keel cannot be client-only: a Python process wakes on a schedule, enforces the
+   rails and writes SQLite **with no browser open.** The browser is a window onto that, never the app
+   itself, so IndexedDB is not and cannot be the store of record.
 
-The *guarantee*, however, does transfer intact. youperiod's "no stateful server" means your data
-never leaves your device. keel's equivalent is **the server is on your device.**
+4. **Nothing is transpiled, bundled, minified, or obfuscated** — and no source maps, for the reason
+   the reference gives: the code running must be byte-identical to the code the user reads in
+   devtools. gzip only. The value of view-source is worth more than the value of tooling.
 
-**Explicitly rejected:** youperiod encrypts everything at rest behind a 12-character passphrase.
-keel cannot. The agent runs unattended via launchd; a passphrase-locked database is one nobody can
-open at 03:00. Passphrase-at-rest and unattended autonomy are mutually exclusive, and autonomy is the
-deliberate choice. The correct analogue is D4's plan: **OS keychain for credentials**, filesystem
-permissions for the database, FileVault/BitLocker for at-rest.
+   keel's own auditability claim must stay scoped honestly: the **UI** is fully readable in any
+   browser on any device; the **engine** is readable on GitHub and in the wheel. A PyInstaller
+   bundle ships `.pyc`, so it does not make the Python readable, and no wording should imply it does.
 
-## 3. Why the app cannot be installed from keeltrading.com
+5. **Offline-capable, performant, and accessible by default.** Semantic HTML, native form elements,
+   `aria-live` on regions that change underneath a reader, keyboard paths, and colour contrast that
+   is asserted in CI rather than judged by eye. For financial data, "offline" means *the shell loads
+   and says the engine is not running* — never a cached balance (§"Service worker").
 
-keel's data is a SQLite file on the operator's machine, written by a local process holding venue
-credentials. A page served from `https://keeltrading.com` is a **different origin** and cannot read
-it. It could only fetch it from the local server, and an HTTPS page fetching `http://127.0.0.1:8765`
-is precisely the path browsers are tightening — Private Network Access preflights in Chrome, blocked
-outright in Safari. It is inconsistent today and narrowing.
+---
 
-The only two exits are giving the local server a real TLS certificate (requires a tunnel — excluded
-by "no server reach"), or moving the data to a hosted service (a different product, explicitly out of
-scope).
+## Server
 
-**Therefore: the PWA is served by the origin that serves the data, which is keel itself.**
-`http://127.0.0.1` **is** a secure context by specification, so a service worker, a web app manifest
-and browser install all work there with no networking decision at all. keeltrading.com hosts the
-install instructions and the documentation — which is what it already does.
+`keel serve` runs a local HTTP server, defaulting to `127.0.0.1` on port **8765**, and opens the URL
+in the user's default browser.
 
-**Consequence, recorded plainly: iPhone and Android are out of scope.** Not deferred by choice —
-excluded by the constraint. There is no keel on iOS, and "no server reach" removes the tunnel that
-was the only way a phone could have reached the desktop process. The UI is still built responsive,
-because desktop windows get dragged narrow, touch devices running a full OS are in scope, and it
-costs almost nothing while the CSS is being written anyway.
+```cmd
+keel serve
+```
 
-## 4. Architecture
+Port 8765 is deliberate: Freqtrade's FreqUI and Jesse's dashboard both sit on 8080, and an operator
+running one of them alongside keel should not discover the clash through a bind error. `--host` and
+`--port` override; `--no-open` suppresses the browser launch.
 
-### 4.1 Process model
+The server does **no rendering**. As in the reference, its job is to serve static files with correct
+security headers, plus a JSON API over the database the engine writes.
 
 ```
 launchd ──► keel agent (daily)  ──►  SQLite  ◄──  keel serve  ──►  127.0.0.1:8765
@@ -113,295 +77,345 @@ launchd ──► keel agent (daily)  ──►  SQLite  ◄──  keel serve
                                               └──────────────────────────────────┘
 ```
 
-Static assets and the API share **one origin**, so there is no CORS story at all. Do not split them.
+Static assets and the API share **one origin**. There is consequently no CORS configuration at all,
+and they must not be split.
 
-### 4.2 The API contract
+### The app cannot be served from keeltrading.com
 
-The API is a *fourth* consumer of the same frozen report dataclasses the console and the TUI already
-consume. It never computes; it serialises what `gather_status`, `build_insights_report` and their
-siblings already return.
+Recorded because it is the first thing anyone proposes. keel's data is a SQLite file on the
+operator's machine. A page served from `https://keeltrading.com` is a **different origin** and cannot
+read it; it could only fetch from the local server, and an HTTPS page fetching `http://127.0.0.1:8765`
+is exactly the path browsers are closing — Private Network Access preflights in Chrome, blocked in
+Safari. The only exits are a TLS certificate for the local server (needs a tunnel) or moving the data
+to a hosted service (a different product).
 
-**Money crosses the wire as strings, never as JSON numbers.** `JSON.parse` yields IEEE-754 doubles,
-and keel is `Decimal`-only for exactly the reason that matters here. A serialisation test fails the
-build if any monetary field emits a JSON number.
+`http://127.0.0.1` **is** a secure context by specification, so the service worker, the web app
+manifest and browser install all work from the local server with no networking decision required.
+keeltrading.com hosts the install instructions and the documentation.
+
+**Consequence: iPhone and Android are out of scope.** Excluded by the architecture, not deferred by
+preference — there is no keel on iOS, and no tunnel is in scope. The interface is still built
+responsive, because desktop windows get dragged narrow and touch devices running a full OS exist.
+
+### Security headers
+
+The server's principal job, as in the reference.
+
+| header | what it prevents |
+|---|---|
+| `Content-Security-Policy: default-src 'self'` | Any third-party resource. No CDN, no web fonts, no analytics — none are used, and the header makes that checkable rather than promised. |
+| `connect-src 'self'` | **The interface is provably incapable of sending positions, equity or trade history anywhere but the local process.** Browser-enforced, one header, verifiable in seconds. Outbound documentation links are navigation, not connections, and are unaffected. |
+| `Referrer-Policy: no-referrer` | Leaking the URL to keeltrading.com when a documentation link is followed. The session token rides in the URL until the cookie exchange; modern browsers already send origin-only cross-origin, so exposure is small, but one header closes it. |
+| `X-Content-Type-Options: nosniff` | Content-type sniffing vulnerabilities. |
+| `Strict-Transport-Security` | Not sent. The origin is loopback HTTP by design; HSTS would be meaningless here and is included in the reference only because that app is served over the public internet. |
+
+Subresource Integrity authorises any inline `<script>` or `<style>` block, as in the reference.
+
+### Existing security layers — preserve, do not rebuild
 
-**The API emits presentation-ready values.** Not `{"qty": "0.01", "price": "50000"}` for the client
-to multiply — `{"notional": "500.00", "notional_display": "$500.00"}`. Every figure a user sees was
-computed by the Python that holds the rails. This is what lets `test_console_thinness.py` extend to
-the API layer, and it is what makes §4.3's zero-dependency claim possible.
+`keel/web/security.py` already documents five layers. The rewrite inherits all of them.
 
-**Sorting is server-side.** Tables sort by query parameter; Python orders with `Decimal`. On loopback
-the round trip is sub-millisecond, so there is nothing to optimise and no client arithmetic to audit.
+1. **Loopback binding.** `--host` accepts anything and says loudly what that means: on a non-loopback
+   address the page is readable by anyone who can reach the port.
+2. **`Host` header validation**, against DNS rebinding — the attack loopback binding invites and that
+   people forget, because the packet really does arrive on loopback and the bind check really does
+   pass. Described in-source as "the cheapest layer and the one that matters most."
+3. **A session token**, minted per run, never written to disk, exchanged on first load for a
+   `SameSite=Strict`, `HttpOnly` cookie. `Strict` rather than `Lax` is deliberate: `Lax` attaches the
+   cookie to top-level navigations, so a link on a hostile page would arrive authenticated.
+4. **A closed action set.** The entire write surface routes through `keel.commands.setup.ACTIONS`,
+   every member declared `MECHANICAL`, idempotent and non-destructive, and **a test asserts that set
+   is disjoint from the eleven capability-increasing actions in `keel/capabilities.py`.**
+5. **A CSRF token on every write**, derived from the session token by HMAC rather than stored — "the
+   layer that does not depend on the browser being current." Comparisons use
+   `secrets.compare_digest`, because `==` on a secret leaks its prefix through timing, and loopback
+   traffic makes that measurement *easier*, not harder.
 
-*Rejected: an integer companion field scaled to cents.* Precision here is **per-product** —
-`base_increment` varies by instrument, which is precisely what #514 and #517 were about — so a fixed
-100× scale silently truncates anything finer than a cent, and a 1e8 scale caps a USD notional near
-$90M against `Number.MAX_SAFE_INTEGER`. If instant client-side re-sort is ever wanted, the field is
-named `sort`, is a plain JSON number, and is documented as **ordering only — never displayed, never
-summed**: float imprecision is harmless for comparison and fatal for display, and the name must not
-let anyone confuse the two.
+**Added by this specification, as a third CSRF layer** (`SameSite` has had parser bypasses): every
+`POST /api/*` requires a custom request header, `X-Keel-Client: 1`. A custom header forces a CORS
+preflight that a hostile origin cannot satisfy — the attack this closes is the HTML form POST, which
+is *not* preflighted. Paired with a `Sec-Fetch-Site: same-origin` check, which page JavaScript
+cannot forge.
 
-### 4.3 The client
+### The capability asymmetry
 
-Plain ES modules, served as authored. **No framework, no bundler, no transpile, no minification, no
-source maps** — per §4 of the reference philosophy, the code running must be byte-identical to the
-code the user reads in devtools. gzip is fine.
+**A client that hides a button is not a gate.** Capability-increasing actions are refused by the
+server, keyed to the session token, with the GUI human gate (#436) in front. The client may be fully
+read and modified by its user and still cannot arm a rule, attest an asset, or enable autonomy.
 
-**Zero third-party JavaScript.** Applying the reference's own bar — a dependency must be justified
-because getting it wrong ourselves would undermine the project's principles — nothing clears it:
+As `security.py` puts it: "no POST at all" would have been satisfied by a server that could not set
+anything up; this is satisfied only by one that cannot arm, release or spend anything.
+
+### Dependencies
+
+The reference admits three client libraries — argon2, base64↔ArrayBuffer, IndexedDB normalisation —
+each because implementing it incorrectly would undermine the app's own principles.
+
+Applying the same bar to keel, **the client has none**, and the two reasons are structural rather
+than fortunate:
+
+- **keel's cryptography is not in the browser.** It lives in Python and the OS keychain. All three of
+  the reference's dependencies are browser-crypto concerns keel does not have.
+- **The client performs no arithmetic**, so no decimal library is required (§"The data contract").
 
 | need | answer |
 |---|---|
-| charts | SVG polyline, hand-rolled (~150 lines) |
-| live updates | `EventSource` (SSE) |
+| charts | SVG path generation, hand-written |
+| live updates | `EventSource` |
 | dates | `Intl.DateTimeFormat` |
-| routing | History API over one shell |
-| decimal arithmetic | **none required** — §4.2 |
-| cryptography | Python + OS keychain, never the browser |
+| routing | History API |
+| decimal arithmetic | not required |
+| cryptography | Python and the OS keychain |
 
-**Type checking without a build step:** `// @ts-check` with JSDoc annotations and `tsc --noEmit` in
+Any future exception must clear the reference's bar: justified because getting it wrong ourselves
+would undermine keel's principles. Convenience does not qualify.
+
+Type checking runs without a build step: `// @ts-check` with JSDoc annotations and `tsc --noEmit` in
 CI. Types are checked; nothing is transpiled and nothing shipped is altered.
 
-### 4.4 Security headers
+---
+
+## Client
 
-The server's principal job, as in the reference.
+Plain ES modules, served exactly as authored.
 
-- `default-src 'self'` — no CDN, no web fonts, no analytics, no third-party anything.
-- **`connect-src 'self'`** — the UI is *provably incapable* of sending positions, equity or trade
-  history to any origin but the local process. Browser-enforced, one header, verifiable in seconds.
-  This is a stronger claim than keel can make today and should be documented as a feature.
-- `X-Content-Type-Options: nosniff`; Subresource Integrity on any inline `<script>`.
-- **`Referrer-Policy: no-referrer`.** New in this design because the app now links out (§5). The
-  session token rides in the URL (`/?token=…`) until the cookie exchange; modern browsers already
-  send origin-only cross-origin, so the exposure is small, but one header closes it outright.
+### First run
 
-**What already exists, and must not be re-invented.** `keel/web/security.py` documents five layers:
-loopback binding; **`Host` header validation** against DNS rebinding; a session token exchanged for a
-`SameSite=Strict`, `HttpOnly` cookie (`Strict` not `Lax`, deliberately, so a link on a hostile page
-cannot arrive authenticated); a closed action set; and an **HMAC-derived CSRF token** on every write,
-described there as *"the layer that does not depend on the browser being current."* Comparisons use
-`secrets.compare_digest`.
+A user with no prior state reaches the first-run wizard (#437), which presents the ceremony rather
+than skipping it: configuration and database creation, credentials captured **via the OS keychain**
+rather than a plaintext `.env`, and each attestation as an explicit step with its reasoning shown.
 
-**Added as a third CSRF layer**, since `SameSite` has had parser bypasses: require a custom request
-header (`X-Keel-Client: 1`) on every `POST /api/*`, which forces a CORS preflight a hostile origin
-cannot satisfy — an HTML form POST, which is *not* preflighted, is the attack this closes. Pair it
-with a **`Sec-Fetch-Site: same-origin`** check, which page JavaScript cannot forge.
+Attestations are **collected, never defaulted** — a Shariah classification is a human-supplied fact
+with a required source, and an unsourced attestation is refused exactly like a missing one. Some
+obligations cannot be automated at all: disabling venue-side interest accrual happens in the venue's
+own dashboard, because that interest is *riba* and no rail can observe it. The wizard shows a
+checklist and requires acknowledgement; it cannot verify.
 
-### 4.5 The capability asymmetry
+**Paper mode is the default.** It needs no venue credentials, which makes it the only thing a new
+user *can* do first, and it is the right default for a tool whose measured result is that no rule
+family is net-positive.
 
-**The client hiding a button is not a gate.** Capability-increasing actions are refused by the API,
-keyed to the session token, with D3's human gate (#436) in front. The client may be fully read and
-modified by its user and still cannot arm a rule, attest an asset, or enable autonomy.
+### The data contract
 
-This is **already implemented and test-enforced**, and the rewrite must preserve it rather than
-rebuild it: the whole write surface routes through `keel.commands.setup.ACTIONS`, every member
-`MECHANICAL`, idempotent and non-destructive, and a test asserts that set is **disjoint from the
-eleven capability-increasing actions in `keel/capabilities.py`.** As `security.py` puts it, "no POST
-at all" would have been satisfied by a server that could not set anything up; this is satisfied only
-by one that cannot arm, release or spend anything.
+The API is a further consumer of the same frozen report dataclasses the console already builds. It
+**never computes**; it serialises what `gather_status`, `build_insights_report` and their siblings
+already return. `tests/commands/test_console_thinness.py`, which pins that property for the console
+and the current web layer, extends to cover it.
 
-## 5. Documentation
+Two rules govern the payload.
 
-`keel/commands/help_console.py:138-146` records a bug that is already shipping:
+**Money crosses the wire as strings, never as JSON numbers.** `JSON.parse` yields IEEE-754 doubles,
+and keel is `Decimal`-only for precisely this reason. A serialisation test fails the build if any
+monetary field emits a JSON number.
+
+**Values arrive presentation-ready.** The client places them; it never derives them. Every figure a
+user sees was computed by the Python that holds the rails — which is what makes the invariant
+*checkable* rather than merely likely.
+
+```json
+{
+  "as_of": "2026-08-23T14:32:07Z",
+  "engine": "running",
+  "equity": { "value": "12345.67", "display": "$12,345.67" },
+  "positions": [
+    {
+      "product_id": "BTC-USD",
+      "qty":      { "value": "0.01000000", "display": "0.01 BTC" },
+      "notional": { "value": "500.00",     "display": "$500.00" },
+      "pnl":      { "value": "-12.34",     "display": "▼ −$12.34", "state": "bad" }
+    }
+  ]
+}
+```
 
-> "an installed deployment has no docs/ checkout, and the help screen renders that notice as its
-> empty state"
+`state` carries the semantic outcome so the client never infers one from a sign, and the `display`
+glyph means the distinction survives without colour (§"Accessibility").
 
-`pyproject.toml` confirms it — `artifacts = ["keel/templates/*.yaml"]`. The wheel ships `.py` files
-and one YAML template. **No `docs/`.** So `/glossary` renders an empty state in every installed
-deployment, including the signed bundle D5 produces.
+**Sorting is server-side.** Tables sort by query parameter and Python orders with `Decimal`. On
+loopback the round trip is sub-millisecond, so there is nothing to optimise and no client arithmetic
+to audit.
 
-**The pipeline runs the opposite way from the original ask.** keeltrading.com's
-`engine-docs.manifest.json` pins `CodeGateSoftware/keel@main`, and `scripts/fetch-engine-docs.mjs`
-declares itself *"the only writer of `src/content/engine-docs/`"* and exits non-zero if a pinned
-document disappears. **keel's `docs/` is the source; the website is the mirror.** Deleting `docs/`
-from keel would fail the website build, loudly, by design.
+*An integer companion field scaled to cents was considered and rejected.* Precision here is
+**per-product** — `base_increment` varies by instrument, which is exactly what #514 and #517 were
+about — so a fixed 100× scale silently truncates anything finer than a cent, and a 1e8 scale caps a
+USD notional near `Number.MAX_SAFE_INTEGER`. Should instant client-side re-sorting ever be wanted,
+the field is named `sort`, is a plain JSON number, and is documented as **ordering only — never
+displayed, never summed.**
+
+`GET /api/config` exposes the running version. It is consumed by the service worker's cache key and
+by outbound documentation links.
+
+### JS file structure
+
+- **main** — the entry point. Attaches event listeners, owns the History API router, and mounts
+  views.
+- **api** — the single `fetch` wrapper. Adds `X-Keel-Client`, and turns a failed request into the
+  explicit *"keel isn't running"* state rather than an empty view.
+- **render** — builds DOM from API payloads. Places `display` strings; contains no arithmetic and no
+  money formatting, deliberately, so that a reviewer can confirm the absence by reading one file.
+- **chart** — SVG path generation for the equity curve.
+- **live** — the `EventSource` subscription and its reconnect behaviour.
+- **format** — `Intl.DateTimeFormat` wrappers. Dates only; money is formatted server-side.
+- **docs** — constructs outbound keeltrading.com links, with the anchor and the `?v=` version.
+- **sw** — the service worker.
+
+In **js/external** there is nothing, and that is the intended end state rather than a stage.
+
+### Service worker
 
-What ships instead: **nothing is fetched, embedded, bundled or cached. The app links out.** A
-documentation reference opens `https://keeltrading.com/en/docs/{slug}/#{anchor}` in a new tab
-(`target="_blank" rel="noopener"`), landing directly on the term.
+Routing is explicit, and the rules exist because a PWA caching financial data is actively dangerous:
+opening the app to last week's equity styled as current is worse than an error.
 
-**This works today with no new infrastructure**, verified against the built site:
+| route | strategy |
+|---|---|
+| `index.html`, `.js`, `.css`, icons | `CacheFirst` |
+| `/api/*` | **`NetworkOnly`, no exceptions** |
+
+If the engine is not running, the shell loads instantly and reports it. It never shows a cached
+account balance.
+
+The cache name is keyed to the build version from `/api/config`, so an upgraded engine can never be
+met by a stale shell holding an older contract.
+
+### Accessibility
+
+Semantic HTML, native form elements, `aria-live` and `aria-atomic` on status regions that change
+underneath a reader, full keyboard paths, and visible focus.
+
+Contrast is **asserted in CI**, not judged by eye. The WCAG formula is about twenty lines of Python
+with no dependencies; every foreground/background pair asserts its minimum ratio, so a palette
+regression fails the build. This is §2 of the philosophy applied to design: no tooling, no
+dependency, just the arithmetic in a readable test.
+
+Measured against the palette in use today (`render.py:41-49`), text contrast is already good — every
+foreground passes AA on both surfaces in both themes, and most pass AAA (`fg` on `bg` is 16.50:1
+light, 15.06:1 dark). Two failures must be fixed in the rewrite:
+
+**`--good` and `--bad` are the same brightness.** In light mode `#1f5f4f` has relative luminance
+0.0904 and `#96322a` has 0.0893 — a delta of 0.0011, a ratio of **1.01:1**. Profit and loss are
+separated by hue alone, and `render.py:82` confirms it: `.good` and `.bad` are pure colour classes.
+This fails WCAG 1.4.1 *Use of Color*, in an application whose central signal is gain versus loss.
+Roughly one in twelve men cannot reliably distinguish them, and greyscale, e-ink and direct sunlight
+collapse the distinction entirely.
+
+The fix is the `state` and `display` fields in the data contract: `▲ +2.4%` / `▼ −2.4%`, where glyph
+and sign carry the meaning and colour reinforces it. The two luminances are separated as well, and
+`--accent` is split from `--good` — they are byte-identical in both themes today, so a link and a
+gain currently render alike.
+
+**Form inputs have no visible boundary.** `render.py:96-97` gives `.field input` the page background
+with a `--line` border at **1.27:1**, so the border is the only thing marking the control. This fails
+WCAG 1.4.11 *Non-text Contrast* (3:1 for component boundaries). Decorative dividers at 1.27:1 are
+exempt and stay; form controls are not, and this lands squarely on the first-run wizard, which is
+almost entirely forms.
+
+---
+
+## Documentation
+
+**Nothing is fetched, embedded, bundled or cached.** A documentation reference opens
+`https://keeltrading.com/en/docs/{slug}/#{anchor}` in a new tab with `rel="noopener"`, landing
+directly on the term.
+
+This works with no new infrastructure, verified against the built site:
 
-- `docs/glossary.md` writes each term as a `## term` heading — an explicit rule stated in the file
-  itself: *"Each entry is a `## term` heading, a definition, and a `Source:` line."*
-- Astro already emits the IDs. `dist/en/docs/glossary/index.html` contains `id="rail"`,
-  `id="attestation"`, `id="instrument-attestation"`, `id="kill-switch"`, `id="qabd"`, `id="riba"`.
+- `docs/glossary.md` states its own rule — "Each entry is a `## term` heading, a definition, and a
+  `Source:` line."
+- Astro emits the IDs. `dist/en/docs/glossary/index.html` contains `id="rail"`, `id="attestation"`,
+  `id="instrument-attestation"`, `id="kill-switch"`, `id="qabd"`, `id="riba"`.
 - `src/pages/en/docs/[slug].astro` renders every pinned document at a stable path.
 
-So the anchor contract is: **kebab-case the `## term` heading.** The only maintenance burden is that
-renaming a heading upstream breaks a deep link — acceptable, and cheaply covered by a test asserting
-that every anchor the app emits exists in the corresponding source document.
+The anchor contract is therefore **kebab-case the `## term` heading**, covered by a test asserting
+that every anchor the app emits exists in the corresponding source document — a renamed heading
+upstream would otherwise break a deep link silently.
 
-Outbound links are navigation, not fetches, and are therefore unaffected by `connect-src 'self'`.
+**`docs/` stays in keel, because keel is the source and the website is the mirror.**
+`engine-docs.manifest.json` pins `CodeGateSoftware/keel@main`, and `scripts/fetch-engine-docs.mjs`
+declares itself "the only writer of `src/content/engine-docs/`", exiting non-zero if a pinned
+document disappears. Deleting `docs/` from keel would fail the website build, loudly, by design.
 
-**Consequences.** The `/glossary` route, `render_glossary()`, and the web layer's use of
-`load_glossary()`/`parse_glossary()` are all deleted rather than ported — a link needs no renderer.
-`help_console.py`'s glossary reader stays for the TUI, which cannot open an anchor and instead prints
-the URL; the shipped-wheel empty state is the same bug there and gets the same fix.
+What changes is that the **application code** stops carrying documentation prose — which also fixes a
+bug already in every release. `pyproject.toml` ships `artifacts = ["keel/templates/*.yaml"]` and no
+`docs/`, so as `keel/commands/help_console.py:138-146` notes in its own docstring, "an installed
+deployment has no docs/ checkout, and the help screen renders that notice as its empty state."
 
 **Offline is not hedged.** No inline fallback definitions, no cached snapshot. An operator running a
-trading engine has network by definition, and per §2 of the reference philosophy the least technology
-that does the job is the correct amount.
-
-Links default to `/en/`. The site also builds `fr` and `ar`; switching the prefix is a one-line
-change if the interface is ever localised, and is not worth anticipating now.
-
-**Version skew is made visible, not eliminated.** `GET /api/config` exposes the running version — it
-is needed for §4.4's cache key regardless — and outbound links carry it as `?v=0.11.2`. The docs page
-shows a banner when that does not match the ref it was built from.
-
-*Rejected: per-version documentation paths.* `keeltrading.com/en/docs/v0.11.0/glossary#qabd` **404s
-today.** The site builds `dist/en/docs/glossary/` and the manifest pins `ref: "main"`; there is no
-versioned tree. Creating one is work in the *other* repository plus a retention policy, multiplied
-across three languages and the sitemap. A query parameter and a banner cost one small website change
-and no new routes, and they surface the mismatch rather than hiding it behind a link that silently
-describes different software.
-
-## 6. Accessibility, as an acceptance criterion
-
-Measured against the current palette (`render.py:41-49`). **Text contrast is already good** — every
-foreground passes AA on both surfaces in both themes, most pass AAA (`fg` on `bg` 16.50:1 light,
-15.06:1 dark; `muted` 5.32:1 / 6.19:1). Two failures, one specific to this being a trading app:
-
-**6.1 — `--good` and `--bad` are the same brightness.** In light mode `#1f5f4f` has relative
-luminance 0.0904 and `#96322a` has 0.0893 — a delta of 0.0011, a ratio of **1.01:1**. Profit and loss
-are separated by hue alone. `render.py:82` confirms it: `.good { color: var(--good); }` and
-`.bad { color: var(--bad); }` are pure colour classes. This fails WCAG 1.4.1 *Use of Color*, and the
-practical consequences are that roughly one in twelve men cannot reliably distinguish gains from
-losses, and that greyscale, e-ink and direct sunlight collapse the distinction entirely.
-
-*Fix:* never encode P&L in colour alone — `▲ +2.4%` / `▼ −2.4%`, where glyph and sign carry the
-meaning and colour reinforces it. Separate the two luminances as well. Split `--accent` from
-`--good`, which are byte-identical in both themes today, so a link and a gain no longer render alike.
-
-**6.2 — form inputs have no visible boundary.** `render.py:96-97` gives `.field input` the page
-background with a `--line` border at **1.27:1**. The border is the only thing marking the control,
-which fails WCAG 1.4.11 *Non-text Contrast* (3:1 for UI component boundaries). Decorative dividers at
-1.27:1 are exempt and stay; form controls are not, and this lands squarely on D4's wizard, which is
-almost entirely forms.
+trading engine has network by definition, and the least technology that does the job is the correct
+amount.
+
+Links default to `/en/`; the site also builds `fr` and `ar`, and changing the prefix is a one-line
+change if the interface is ever localised.
+
+**Version skew is made visible, not eliminated.** Outbound links carry `?v=` from `/api/config`, and
+the documentation page shows a banner when that does not match the ref it was built from. Per-version
+documentation paths were rejected: `keeltrading.com/en/docs/v0.11.0/glossary#qabd` **404s today**,
+since the site builds `dist/en/docs/glossary/` and the manifest pins `main`. Building versioned trees
+is work in the other repository plus a retention policy, multiplied across three languages and the
+sitemap; a query parameter and a banner cost one small change and no new routes.
 
-**6.3 — checked in CI, not by eye.** The WCAG contrast formula is about twenty lines of Python with
-no dependencies. Every foreground/background pair asserts its minimum ratio and `good`/`bad` assert a
-minimum luminance separation, so a palette regression fails the build. This is §2 of the reference
-philosophy applied to design: no tooling, no dependency, just the arithmetic in a readable test.
-
-**6.4 — baseline:** semantic HTML, native form elements, `aria-live`/`aria-atomic` on status regions
-that change underneath the reader, full keyboard paths, visible focus.
-
-## 7. Newbie usability is mostly not a front-end problem
-
-Recorded so effort lands where it pays. Today's navigation is eight peers — an operator's mental
-model. The levers, in order of impact: **D4's wizard (#437)**, which replaces roughly ten CLI
-invocations and hand-edited YAML; **progressive disclosure**, one "everything is fine / here is the
-one thing to do" surface with the eight operator views behind a second tier; and **plain language
-with working documentation links** (§5). None of the three is improved by the choice of front-end
-technology.
-
-## 8. Decisions recorded
-
-1. **The TUI is deleted — in W7, not W0.** ~9,400 lines (`tui.py` 5,063 + 4,369 of tests) go, which
-   answers #525's "`keel/commands/` is larger than the engine it drives" directly. keel is a
-   local-first, double-clickable application, and `windows-curses` is unmaintained.
-
-   **"But SSH" is not a reason, and keel's own documentation says so three ways.** There is no
-   server deployment profile — the four profiles are *trading* profiles (live, paper, paper-hourly,
-   paper-equities), not topologies. A headless live cycle already **fails closed**, because confirm
-   mode "waits for a typed `y` at a terminal" (`docs/operator-runbook.md:365`). And the project is
-   explicit that no remote surface exists at all: *"Notify-only, by design. There is no remote
-   control surface — no command, query or capability arrives through notifications, ever"*
-   (`docs/operator-runbook.md:864`).
-
-   Even granting a headless host, `ssh -L 8765:127.0.0.1:8765 host` forwards the **web** UI to a
-   local browser — full interface, encrypted by SSH, still a secure context because it is localhost
-   at the reading end, and no curses anywhere. That is better than the TUI on every axis, and
-   `keel status` covers the rest from a plain shell.
-
-   **The ordering is the whole decision.** `tui.py` imports from `keel.commands.activity`,
-   `admission` and `status` — it is a front-end *over* the shared report builders, not their owner —
-   so deletion never touches what the web UI reads. But D2 (#435) requires parity with the TUI's read
-   surface before the write surface widens, and deleting at W0 would leave W1–W4 with no working
-   console at all. The 4,369 test lines are also the **specification of what is being ported**: they
-   record what each screen shows and when. They are retired once the new UI passes equivalents, not
-   before.
-
-   **A second gate on W7:** deleting the TUI makes the browser the only interactive surface, so
-   anything an operator could previously only reach through it must be reachable through the browser
-   *or* deliberately CLI-only first. D3 (#436) exists precisely so capability-increasing actions have
-   a GUI gate rather than a bypass; W7 must confirm coverage rather than assume it, or a
-   non-technical user — the whole point of §8.9's double-click path — ends up stranded at a step that
-   needs a terminal.
-2. **Zero third-party JavaScript**, per §4.3. Any future exception requires the reference's bar:
-   justified because getting it wrong ourselves would undermine keel's principles.
-3. **No build step**, per §4.3 — including no source maps.
-4. **Money as strings**, per §4.2.
-5. **Mobile phones are out of scope**, per §3.
-6. **`docs/` stays in keel**, per §5 — it is the source the website mirrors.
-7. **Documentation is linked, never embedded.** Nothing fetched, bundled or cached; the app opens
-   `keeltrading.com/en/docs/{slug}/#{anchor}` in a new tab. No offline fallback (§5).
-8. **Sorting is server-side**, per §4.2. No scaled-integer companion fields.
-9. **The signed desktop bundle is the primary channel**, and the static assets ship in it — a W2
-   acceptance criterion, not a §11 risk. The end state is double-click, no terminal command.
-10. **The browser is the window.** `webbrowser.open` as it works today; no embedded webview.
-
-## 9. Non-goals
-
-- Any hosted service, account system, telemetry, or analytics.
-- The paid analysis tier — a different app and repository.
-- Encrypting the database at rest behind a passphrase (§2).
-- Replacing SQLite as the store of record.
-- Widening what the browser may *do*; §4.5's asymmetry is preserved exactly.
-- **An embedded native window** (pywebview or similar). It buys a title bar and costs a dependency,
-  three platform backends, and the devtools that make §4.3's view-source claim checkable by the
-  user. `serve.py` already opens the default browser with no dependency at all; a double-click still
-  produces a window, it simply happens to be a browser.
-
-## 10. Phases
-
-| # | phase | content |
+---
+
+## What this deletes
+
+| deleted | lines | why |
 |---|---|---|
-| W1 | JSON API | Serialise the existing reports; money-as-strings rule and its test; **server-side sort**; `GET /api/config` (version); extend `test_console_thinness.py` to the API layer |
-| W2 | Static serving + headers | §4.4 in full — CSP, `Referrer-Policy`, `X-Keel-Client` preflight, `Sec-Fetch-Site`, SRI. **Static assets listed in `pyproject.toml` `artifacts` and in the bundle manifest — an acceptance criterion, and the double-click path works end to end** |
-| W3 | Client shell | Nav, status view, responsive CSS, palette fixes and the contrast test (§6) |
-| W4 | Remaining views | The other seven routes, SVG charts, SSE live updates |
-| W5 | PWA | Manifest, icons, service worker. **Routing is explicit: `CacheFirst` for the static shell (`index.html`, `.js`, `.css`), `NetworkOnly` for `/api/*`, no exceptions. The cache name is keyed to the build version**, so an upgraded engine cannot be met by a stale shell |
-| W6 | Documentation | Deep links to keeltrading.com carrying `?v=`; delete `/glossary` and `render_glossary()`; anchor-existence test |
-| W7 | Removal | Delete `render.py`'s HTML generation, retire the HTML routes, **and delete `tui.py` with its tests** (§8.1) — after parity, never before |
-
-## 11. Risks
-
-- **A service worker caching data would be actively dangerous** — opening the app to last week's
-  equity styled as current is worse than an error. Mitigated by W5's routing rules; when the engine
-  is not running the UI fails visibly with *"keel isn't running"*, never a cached balance.
-- **Deleting `render.py` breaks the existing thinness pins.** W1 must land the API pins before W7
-  removes the HTML ones.
-- **Deleting the TUI removes the reference implementation.** W7 only, and only once the new UI passes
-  equivalents of what `tests/commands/test_tui.py` asserts (§8.1). Deleting early would discard the
-  specification of the thing being built.
-- **`pyproject.toml`'s `artifacts` currently covers only the YAML template**, so the static assets
-  would be absent from the wheel and the bundle. Promoted to a W2 acceptance criterion.
-- **A no-build client has no compile-time safety net** by default; mitigated by `tsc --noEmit` (§4.3).
-- **The auditability claim must stay scoped.** The bundle is the primary channel (§8.9), and
-  PyInstaller ships `.pyc`, not readable `.py` — so the *engine* is not view-source inside it. The
-  honest statement is: the **UI** is fully auditable in the browser on any device; the **engine** is
-  auditable on GitHub and from the wheel, which the `curl | bash` installer (#479) still delivers as
-  readable source. Do not let marketing collapse the two.
-- **Version skew is surfaced, not solved** (§5). A `?v=` parameter and a banner make a mismatch
-  visible; only pinning the website to the latest tag instead of `main` would remove it, and that is
-  a keeltrading.com decision.
-- **A renamed heading breaks a deep link silently.** Covered by the anchor-existence test in §5.
-
-## 12. Open questions
+| `render.py`'s HTML generation | 872 | The server no longer renders. |
+| `/glossary`, `render_glossary()` | — | A link needs no renderer. |
+| `keel/commands/tui.py` + its tests | ~9,432 | Below. |
+
+**The TUI goes, and "but SSH" is not a reason.** keel's own documentation refutes it three ways:
+there is no server deployment profile (the four profiles are *trading* profiles — live, paper,
+paper-hourly, paper-equities — not topologies); a headless live cycle already **fails closed**,
+because confirm mode "waits for a typed `y` at a terminal"
+(`docs/operator-runbook.md:365`); and the project is explicit that no remote surface exists at all —
+"Notify-only, by design. There is no remote control surface — no command, query or capability
+arrives through notifications, ever" (`docs/operator-runbook.md:864`).
+
+Granting a headless host anyway, `ssh -L 8765:127.0.0.1:8765 host` forwards the **web** interface to
+a local browser: full interface, encrypted by SSH, still a secure context because it is localhost at
+the reading end, and no curses anywhere. `windows-curses` is unmaintained besides. Deleting ~9,400
+lines also answers #525 directly — `keel/commands/` is larger than the engine it drives.
+
+**Two conditions on the deletion, and they are the reason it happens last rather than first.**
+`tui.py` imports from `keel.commands.{activity,admission,status}` — it is a front-end *over* the
+shared report builders, not their owner — so removing it never touches what the web UI reads. But
+D2 (#435) requires parity with the TUI's read surface before the write surface widens, and
+`tests/commands/test_tui.py` **is the specification of what is being ported**: it records what each
+screen shows and when. Second, once the TUI is gone the browser is the only interactive surface, so
+anything previously reachable only through it must be reachable through the browser or deliberately
+CLI-only — otherwise a non-technical user is stranded at a step that needs a terminal, which would
+undo the point of the exercise.
 
-1. Do the manifest, icons and service worker ship in the wheel as well, or only in the desktop
-   bundle? (The static assets themselves ship in both — §8.9.)
-2. Will keeltrading.com take the `?v=` banner (§5), and does it want to pin to the latest tag rather
-   than `main`?
+---
+
+## Build order
+
+The sequence matters in two places only: the API's test pins must exist before the HTML ones are
+removed, and parity must be reached before the TUI is deleted.
+
+1. **JSON API** — serialise the existing reports; the money-as-strings rule and its test;
+   server-side sort; `GET /api/config`; extend `test_console_thinness.py` to the API layer.
+2. **Static serving and headers** — the full header set, SRI, and the static assets listed in
+   `pyproject.toml`'s `artifacts` and the bundle manifest, so the double-click path works end to end.
+3. **Client shell** — router, status view, responsive CSS, the palette fixes and the contrast test.
+4. **Remaining views** — the other seven routes, SVG charts, `EventSource` updates.
+5. **PWA** — manifest, icons, service worker with the routing above.
+6. **Documentation** — deep links carrying `?v=`; the anchor-existence test.
+7. **Removal** — `render.py`'s HTML, the HTML routes, and `tui.py` with its tests.
 
-*Resolved during design:*
+## Distribution
 
-- Bundling a rendered documentation snapshot for offline use — **no.** Link out only (§5, decision 7).
-- Whether the signed bundle is the primary channel — **yes** (§8.9), with §11's scoping caveat.
-- Whether to keep the TUI — **no**, deleted in W7 (§8.1).
-- Client-side sorting via scaled integers — **no**, sorting is server-side (§4.2).
-- An embedded native window — **no** (§9).
+The signed desktop bundle is the primary channel: the end state is a double-click that opens a window
+with no terminal command. The window is the user's own browser, via `webbrowser.open` as `serve.py`
+already does.
+
+*An embedded native window (pywebview or similar) was rejected.* It buys a title bar and costs a
+dependency, three platform backends, and the devtools that make §4 of the philosophy checkable by the
+user.
+
+## Open questions
+
+1. Do the manifest, icons and service worker ship in the wheel as well, or only in the desktop
+   bundle? The static assets themselves ship in both.
+2. Will keeltrading.com take the `?v=` banner, and does it want to pin to the latest tag rather than
+   `main`?

From ad2fb7631c224ee4ec254ae318104b6872ad37a7 Mon Sep 17 00:00:00 2001
From: Elmehdi Aitbrahim <eaitbrahim@gmail.com>
Date: Sun, 23 Aug 2026 21:17:31 -0400
Subject: [PATCH 6/6] docs(spec): the artifacts key is inert, and the empty
 glossary is structural

The spec claimed the wheel omits docs/ because `artifacts` lists only the YAML
template. Wrong reason, right conclusion, and the real reason is stronger.

Measured: building with `artifacts = ["keel/templates/*.yaml"]` and with
`artifacts = []` produces wheels with IDENTICAL contents -- 140 entries each,
both carrying the two YAML templates. The key is inert on the pinned backend
(uv_build >=0.10.4,<0.13.0), which ships the whole module root regardless.

So docs/ is absent because it sits at the REPOSITORY root, outside `keel/`,
which is what uv_build packages. No glob can reach it.

That makes #539's case stronger rather than weaker: the empty glossary is not a
packaging oversight someone could fix by adding a pattern, it is structural, and
linking out is the only fix that reaches an installed deployment.

The adjacent source comment in pyproject.toml -- "the wheel otherwise contains
only .py files" -- is also wrong by the same measurement.

Found by the agent implementing #535, which I had briefed with my own incorrect
version; it tested the claim instead of inheriting it. Build-order guidance
updated to assert against a built wheel rather than a glob.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NyeggYtojNXCTHeD3JHxb6
---
 .../specs/2026-08-23-web-ui-rewrite-design.md | 24 +++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
index 741867b..eb16f66 100644
--- a/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
+++ b/docs/superpowers/specs/2026-08-23-web-ui-rewrite-design.md
@@ -335,9 +335,23 @@ declares itself "the only writer of `src/content/engine-docs/`", exiting non-zer
 document disappears. Deleting `docs/` from keel would fail the website build, loudly, by design.
 
 What changes is that the **application code** stops carrying documentation prose — which also fixes a
-bug already in every release. `pyproject.toml` ships `artifacts = ["keel/templates/*.yaml"]` and no
-`docs/`, so as `keel/commands/help_console.py:138-146` notes in its own docstring, "an installed
-deployment has no docs/ checkout, and the help screen renders that notice as its empty state."
+bug already in every release. As `keel/commands/help_console.py:138-146` notes in its own docstring,
+"an installed deployment has no docs/ checkout, and the help screen renders that notice as its empty
+state."
+
+**The reason is structural, and stronger than a packaging oversight.** `uv_build` packages the module
+root — `keel/` — and everything under it: 140 entries, the `.py` files plus
+`keel/templates/*.yaml`. `docs/` lives at the *repository* root, outside that tree, so no wheel can
+carry it.
+
+`pyproject.toml`'s `artifacts = ["keel/templates/*.yaml"]` is **inert on the pinned backend**
+(`uv_build>=0.10.4,<0.13.0`), which was measured rather than assumed: building with that list and
+building with `artifacts = []` produce wheels whose contents are identical, both including the two
+YAML templates. The adjacent source comment — "the wheel otherwise contains only .py files" — is
+therefore wrong, and so was an earlier draft of this section that repeated it.
+
+The consequence is that the empty glossary cannot be fixed by adding a glob. Linking out is not the
+cheaper option here; it is the only one that reaches an installed deployment.
 
 **Offline is not hedged.** No inline fallback definitions, no cached snapshot. An operator running a
 trading engine has network by definition, and the least technology that does the job is the correct
@@ -396,7 +410,9 @@ removed, and parity must be reached before the TUI is deleted.
 1. **JSON API** — serialise the existing reports; the money-as-strings rule and its test;
    server-side sort; `GET /api/config`; extend `test_console_thinness.py` to the API layer.
 2. **Static serving and headers** — the full header set, SRI, and the static assets listed in
-   `pyproject.toml`'s `artifacts` and the bundle manifest, so the double-click path works end to end.
+   the bundle manifest, so the double-click path works end to end. Assert this against a **built
+   wheel**, not against files on disk: `pyproject.toml`'s `artifacts` key is inert on the pinned
+   `uv_build` (measured — see § Documentation), so a glob there proves nothing either way.
 3. **Client shell** — router, status view, responsive CSS, the palette fixes and the contrast test.
 4. **Remaining views** — the other seven routes, SVG charts, `EventSource` updates.
 5. **PWA** — manifest, icons, service worker with the routing above.