some more fixes

simplify/migration.md

@@ -0,0 +1,189 @@
+# Migration
+
+The order the work happens in, and what proves each step. Every phase leaves all four apps building
+and shippable; nothing here is a long-lived branch.
+
+## Preconditions
+
+None of this starts until these are true. They are not precautions, they are the things that make
+repo surgery safe.
+
+**Commit and push the two dirty trees.** Margin Docs has 123 uncommitted files. Margin Mail has 123
+uncommitted files on top of a single scaffold commit. Moving files between repos and rewriting
+manifests across that is how work gets lost.
+
+**Give Margin Mail a git remote.** It has none. That blocks the `uses:` reference for a reusable
+workflow, blocks the sibling checkout other apps need, and blocks the shared repo's CI from building
+it. Everything in [release.md](release.md) waits on this one command.
+
+**Get Margin Docs' CI green.** Six of its last seven runs failed in `pnpm install --frozen-lockfile`
+with `ENOENT: no such file or directory, scandir '/Users/runner/work/python/margin/shared'`, because
+its workflow does a single checkout and its manifest points at a sibling repository. Margin Mail
+already solved this with a second checkout and it was never carried back. Do that, as a stopgap, so
+main is green before anything moves. Phase 1 deletes the stopgap.
+
+## Fix before, or fix along the way
+
+The audits turned up 30 defects. Most ride along with the extraction that touches them, but some have
+to be settled first, because extracting a module means choosing which version wins and a bug you have
+not decided about gets chosen by accident.
+
+Fix first, because they block a phase or because they are shipping wrong today:
+
+| Defect | Where | Why first |
+|---|---|---|
+| Margin Mail cannot compile for mobile | `lib.rs:203` has `mobile_entry_point` on `attach_account` rather than `run()` at `:250`; the three helpers called at `:307`, `:310`, `:314` are defined nowhere | The Rust extraction touches `lib.rs` in all four apps. Fixing it afterwards means fixing it twice. All three helpers exist in Margin Calendar and were meant to be ported |
+| Margin's Google refresh token is in plaintext | `gdrive.rs:71`, `:153-157`, in `backup.json` | Same OAuth client and same grant as the two apps that seal theirs, so it sets the suite's real security level. `margin-secrets` should land on a repo that has already stopped doing this |
+| Margin's PDF exports every heading at weight 400 | `pdf.rs:9-20`, `:57-62` load variable fonts, which Typst lays out at the default instance | The extraction has to take Margin Docs' static cuts. Decide that before the crate exists, not during |
+| Margin's Typst escaper is `JSON.stringify` | `src/export/typst.ts:36-38` | Typst copies an unrecognised escape to the page verbatim, so `\b`, `\f` and braceless `\uXXXX` reach the PDF as visible backslashes. The busiest call site is every inline code span |
+| Two apps ship placeholder updater pubkeys | Margin Docs and Margin Mail | Neither can ship a verifiable direct-download update. The shared release pipeline should not be built around a config that has never worked |
+| No workflow sets `max-parallel: 1` | `margin:91`, `margin-caledar:85`, `margin-mail:85` set only `fail-fast: false` | tauri-action merges `latest.json` read-modify-write across platforms. The constraint was written down once and lost, which is the failure this whole exercise is about |
+| Margin Calendar has no rate limit handling | A 429 becomes `ApiError::Other` at `google/api.rs:191-197`; the outbox counts it as a real attempt and five retire the write permanently at `push.rs:29`, `:375-381` | A user's write is silently dropped. `margin-http` fixes it, but the data loss is live now |
+
+Everything else rides along and is listed in the document that owns it: the missing transactions and
+the settings struct with 25 fields and one `serde(default)` in [rust-crates.md](rust-crates.md); the
+theme key declared twice, the updater with no package-manager guard, and the keyboard normalisation
+that makes `cmd+F` and `cmd+f` collide in [hooks.md](hooks.md); the unclamped row menu and the menu
+with no escape layer in [ui-kit.md](ui-kit.md); the two justfile bugs and the unchecked TypeScript
+projects in [toolchain.md](toolchain.md).
+
+One of them is a fix rather than a saving and should be called out: three apps ship modals with
+`role="dialog"` and `aria-modal="true"` and no focus trap behind them. Only Margin has
+`useFocusTrap`. That arrives with `Sheet`.
+
+## Phase 1: the shared repo exists and the build is not broken
+
+Create `margin-shared` as its own repository, MIT licensed. Move `margin/shared` into it intact:
+tokens, fonts, icons, the font binaries and `sync-fonts`. Tag `v0.1.0`. Repoint Margin, Margin Docs
+and Margin Mail off the relative path, and add the dependency to Margin Calendar, which has never had
+it.
+
+Nothing else changes in this phase. No new tokens, no new components, no reconciliation. The point is
+to move the existing thing to a place where a fresh clone works, and to prove the consumption
+mechanism before anything depends on it.
+
+**Proves it worked:** clone each of the four repos into an empty directory, `pnpm install`, `pnpm
+build`. All four succeed. Today two of them cannot. Then Margin Docs' CI goes green with the stopgap
+second checkout removed.
+
+This phase also forces the licence decision. Margin is FSL-1.1-MIT, Margin Mail will be, Margin
+Calendar and Margin Docs are MIT. The shared repo is MIT so all four can consume it. Make that
+deliberately rather than discovering it mid-extraction.
+
+## Phase 2: the design system
+
+`@margin/tokens` and `@margin/fonts`, per [design-system.md](design-system.md).
+
+Margin Calendar is 49 of 52 token values identical to the shared set already, so joining costs two
+imports and a script pair. Promote the corrections two apps found independently, starting with
+`--ink-faint`, which Calendar and Mail both moved to `#6e675b` light and `#8e8677` dark for the same
+contrast reason while Margin and Docs kept the failing `#9b9484`. Promote the 19 tokens that exist in
+two or three apps and not in shared. Collapse the base layer, which is already one file in four
+byte-identical copies.
+
+**Proves it worked:** a screenshot of the same screen in each app before and after, and a lint over
+each app's CSS for colour literals outside the token layer. Margin has 15 hex and 17 `rgba()`
+literals today; Calendar has one; Docs and Mail have none. The lint is what stops the drift
+resuming, so it lands in this phase rather than later.
+
+## Phase 3: the toolchain
+
+`@margin/config`, per [toolchain.md](toolchain.md). The base tsconfig three apps already share byte
+for byte, the Vite factory the four configs differ from only by port, the shared justfile recipes, and
+the prose checker that currently exists in one repo.
+
+Two things gate later phases and belong here. `@margin/ui` cannot ship source-only TSX unless each
+app's tsconfig and Vite config compile TSX out of `node_modules`, and none does today. And the
+checking gate has two holes: nothing type checks the Playwright specs, and nothing builds
+`tsconfig.node.json`, so `vite.config.ts` is unchecked in all four and fails in two.
+
+**Proves it worked:** one recipe name in every app runs the whole gate, and it is red in the places
+the audits say it should be red today.
+
+## Phase 4: the UI kit
+
+`@margin/ui`, in the ranked order in [ui-kit.md](ui-kit.md): sheets and confirmation first, then list
+navigation, the export preview, the primitives, and so on down.
+
+The standing note in `shared/src/icons.ts:11-13` that says the `Icon` component is deliberately not
+shared has to be reopened in the file, with the new reasoning, rather than quietly contradicted.
+
+Do not do this before Phase 2. A component kit on four different token sets is a component kit that
+looks different in four apps.
+
+**Proves it worked:** Margin Mail's `Kit.tsx` renders every primitive in every state in both palettes,
+and it keeps working after each promotion. That page is the regression test and it already exists.
+
+## Phase 5: hooks and IPC
+
+`@margin/hooks` and `@margin/ipc`, per [hooks.md](hooks.md). Start with the six things that are byte
+identical today and verified by hash, because they drop in with no behaviour change. Order by
+confidence, not by line count.
+
+The winners are not all in one app, so no single repo is the source: Docs wins the theme and the
+updater, Mail wins the keyboard registry and the toast and the `call` wrapper, Margin wins the focus
+trap and relative time, Calendar wins clamp and contributes the packaged-by guard.
+
+## Phase 6: the test harness
+
+`@margin/test`, per [testing.md](testing.md). The three Playwright configs are one file with the port
+swapped. The invoke stub is the thing worth sharing and three apps solved events three different ways,
+with the correct one currently living in `tests/` where it cannot be reused.
+
+This is the highest-value item in the whole consolidation for day-to-day work, because it is what
+lets a change be verified without touching the running dev server, which
+[guidelines/working-together.md](guidelines/working-together.md) forbids.
+
+Margin comes last here and is new work rather than migration: it has no tests of any kind and no
+`src/ipc.ts` seam to plug a fixture into.
+
+## Phase 7: the Rust crates
+
+Per [rust-crates.md](rust-crates.md), then [accounts.md](accounts.md), then
+[typesetting.md](typesetting.md). Consumed as cargo git dependencies pinned to a tag, because a path
+dependency across checkouts fails on a fresh clone in exactly the way the npm one already does.
+
+Order within the phase: `margin-log` first and alone, because it is about 100 lines, it is the only
+logging in the suite, and every later phase debugs better with it. Then the Tauri shell, where 73
+distinct lines of `lib.rs` are verbatim identical in all four files. Then SQLite, done for the two
+defects it fixes rather than the volume. Then secrets, Google and HTTP together, since 1,552 of
+Margin Calendar's 1,675 non-test OAuth lines exist verbatim in Margin Mail. Then typesetting,
+grammar and the macOS integrations.
+
+Close the version drift in the same pass: rusqlite 0.37 against 0.40, reqwest 0.12 against 0.13,
+chacha20poly1305 0.10 against 0.11, fontdb 0.23 against 0.24.
+
+Note what is deliberately not built: no shared settings crate, no shared error crate, no shared
+filesystem crate, no shared async crate, and no shared sync engine. Each refusal has evidence behind
+it in its own document, and the sync engine refusal is the most important one in the plan.
+
+## Phase 8: release
+
+Per [release.md](release.md). The `prepare` job is 81 lines in two apps and differs by one line. No
+repo has the good version of the pipeline: every good idea lives in exactly one repo and one app has
+no CI workflow at all.
+
+This is late deliberately. A reusable workflow is only worth building once the four repos agree about
+what a build is, which is what phases 1 through 7 settle.
+
+**Proves it worked:** each app's own workflow file is under 20 lines, and a release of each app
+produces a signed, notarised, verifiable artifact.
+
+## Phase 9: names
+
+Per [naming.md](naming.md). Last, because a rename during extraction is a rename of a moving target,
+and because two of the renames are free only once nothing points at the old paths.
+
+The bundle identifiers stay frozen. Changing one orphans the app data directory, the sealed-secret
+service name, the OAuth redirect scheme registered with Google, the macOS notification settings deep
+link, the App Store record and the Homebrew cask, and breaks the update path for every existing
+install.
+
+## What "done" looks like
+
+A fresh clone of any of the five repos installs and builds with no sibling checkout. The same button
+exists once. A token changed in one place changes in four apps. An icon is aligned by two CSS rules
+rather than by a nudge at each call site. A failure is written to a log file in every app rather than
+one. A change can be verified in a browser against fixtures without touching the running dev server.
+And the rules the four apps are built by are in `guidelines/` in a repository, rather than in memory
+files on one machine.