some more fixes

An internal tester has to be a user on the App Store Connect account, which is access to the
account rather than to a build. The invitation is narrowed as far as the API allows: one visible
app, provisioning refused, and the Developer role rather than anything that can change the listing.

The bulk assignment endpoint reports success for an address it then declines to add, which is what
happens when the person has not accepted their account invitation yet, so the group is read back
instead of trusted.

Claude-Session: https://claude.ai/code/session_018HwEWvoE1NkkUjJCMLSnup

.github/workflows/appstore.yml

@@ -0,0 +1,130 @@
+name: App Store
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to build, e.g. v0.1.18. Defaults to the latest release."
+        required: false
+        type: string
+      upload:
+        description: "Upload to App Store Connect. Off means build and sign only."
+        required: false
+        default: true
+        type: boolean
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: macos-26
+    steps:
+      - name: Resolve the tag
+        id: tag
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          TAG="${{ inputs.tag }}"
+          if [ -z "$TAG" ]; then
+            TAG=$(gh release view --repo "$REPO" --json tagName --jq .tagName)
+          fi
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "Building $TAG for the App Store"
+
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ steps.tag.outputs.tag }}
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 26
+
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-apple-darwin,x86_64-apple-darwin
+
+      - uses: swatinem/rust-cache@v2
+        with:
+          workspaces: src-tauri -> target
+
+      - name: Install frontend dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Provision Google credentials
+        env:
+          GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
+        run: |
+          if [ -n "$GOOGLE_CREDENTIALS" ]; then
+            printf '%s' "$GOOGLE_CREDENTIALS" > google-credentials.json
+          else
+            echo "::error::GOOGLE_CREDENTIALS is not set; an App Store build with placeholder credentials would ship a broken backup feature."
+            exit 1
+          fi
+
+      - name: Import the App Store certificates
+        env:
+          APP_CERT: ${{ secrets.MAS_APP_CERTIFICATE }}
+          APP_CERT_PASSWORD: ${{ secrets.MAS_APP_CERTIFICATE_PASSWORD }}
+          INSTALLER_CERT: ${{ secrets.MAS_INSTALLER_CERTIFICATE }}
+          INSTALLER_CERT_PASSWORD: ${{ secrets.MAS_INSTALLER_CERTIFICATE_PASSWORD }}
+          PROFILE: ${{ secrets.MAS_PROVISION_PROFILE }}
+        run: |
+          keychain="$RUNNER_TEMP/appstore.keychain-db"
+          password=$(uuidgen)
+          security create-keychain -p "$password" "$keychain"
+          security set-keychain-settings -lut 3600 "$keychain"
+          security unlock-keychain -p "$password" "$keychain"
+
+          import_p12() {
+            printf '%s' "$1" | base64 --decode > "$RUNNER_TEMP/cert.p12"
+            security import "$RUNNER_TEMP/cert.p12" -k "$keychain" -P "$2" \
+              -T /usr/bin/codesign -T /usr/bin/productbuild
+            rm -f "$RUNNER_TEMP/cert.p12"
+          }
+          import_p12 "$APP_CERT" "$APP_CERT_PASSWORD"
+          import_p12 "$INSTALLER_CERT" "$INSTALLER_CERT_PASSWORD"
+
+          # Without this, codesign on a headless runner blocks on a keychain prompt nobody can
+          # answer and the job hangs until it times out.
+          security set-key-partition-list -S apple-tool:,apple: -k "$password" "$keychain" > /dev/null
+          security list-keychains -d user -s "$keychain" login.keychain-db
+
+          printf '%s' "$PROFILE" | base64 --decode > "$RUNNER_TEMP/margin.provisionprofile"
+          security find-identity -v "$keychain"
+
+      - name: Build the sandboxed bundle
+        run: |
+          # No APPLE_SIGNING_IDENTITY here on purpose: mas-package.sh signs, because the
+          # provisioning profile has to be inside the bundle before codesign runs.
+          pnpm tauri build --target universal-apple-darwin --config src-tauri/tauri.appstore.conf.json --bundles app
+
+      - name: Sign, package and upload
+        env:
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          MAS_APP_IDENTITY: ${{ secrets.MAS_APP_IDENTITY }}
+          MAS_INSTALLER_IDENTITY: ${{ secrets.MAS_INSTALLER_IDENTITY }}
+          MAS_PROVISION_PROFILE: ${{ runner.temp }}/margin.provisionprofile
+          MAS_BUILD_NUMBER: ${{ github.run_number }}
+          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+          APPLE_API_KEY_P8: ${{ secrets.APPLE_API_KEY_P8 }}
+          MAS_UPLOAD: ${{ inputs.upload && '1' || '' }}
+        run: |
+          mkdir -p ~/private_keys
+          printf '%s' "$APPLE_API_KEY_P8" | base64 --decode > ~/private_keys/AuthKey_$APPLE_API_KEY_ID.p8
+          chmod 600 ~/private_keys/AuthKey_$APPLE_API_KEY_ID.p8
+          ./scripts/mas-package.sh
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: margin-appstore-pkg
+          path: target-mas/*.pkg
+          if-no-files-found: warn

.github/workflows/release.yml

@@ -44,6 +44,12 @@ jobs:
           jq --arg v "$VERSION" '.version = $v' src-tauri/tauri.conf.json > "$tmp" && mv "$tmp" src-tauri/tauri.conf.json
           jq --arg v "$VERSION" '.version = $v' package.json > "$tmp" && mv "$tmp" package.json
           sed -i "0,/^version = \".*\"/s//version = \"$VERSION\"/" src-tauri/Cargo.toml
+          # Cargo.lock records margin-app's own version, so bumping only Cargo.toml leaves the
+          # lock a release behind and the next build rewrites it under whoever checked it out.
+          awk -v v="$VERSION" '
+            /^name = "margin-app"$/ { print; getline; sub(/^version = ".*"/, "version = \"" v "\""); print; next }
+            { print }
+          ' src-tauri/Cargo.lock > "$tmp" && mv "$tmp" src-tauri/Cargo.lock
 
       - name: Commit and tag
         env:
@@ -51,7 +57,7 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add src-tauri/tauri.conf.json package.json src-tauri/Cargo.toml
+          git add src-tauri/tauri.conf.json package.json src-tauri/Cargo.toml src-tauri/Cargo.lock
           git commit -m "chore(release): $TAG"
           for attempt in 1 2 3 4 5; do
             git fetch origin main
@@ -147,19 +153,49 @@ jobs:
             echo "Wrote google-credentials.json from GOOGLE_CREDENTIALS secret."
           else
             cp google-credentials.example.json google-credentials.json
-            echo "::warning::GOOGLE_CREDENTIALS secret not set — embedding placeholder credentials; Google Drive backup will be disabled in this release."
+            echo "::warning::GOOGLE_CREDENTIALS secret not set, embedding placeholder credentials; Google Drive backup will be disabled in this release."
           fi
 
+      - name: Provision Apple notarization key
+        if: runner.os == 'macOS'
+        shell: bash
+        env:
+          KEY_P8: ${{ secrets.APPLE_API_KEY_P8 }}
+        run: |
+          if [ -z "$KEY_P8" ]; then
+            echo "::warning::APPLE_API_KEY_P8 is not set, so the macOS bundle will be ad-hoc signed and Gatekeeper will refuse to open it."
+            exit 0
+          fi
+          printf '%s' "$KEY_P8" | base64 --decode > "$RUNNER_TEMP/apple-api-key.p8"
+          chmod 600 "$RUNNER_TEMP/apple-api-key.p8"
+          echo "APPLE_API_KEY_PATH=$RUNNER_TEMP/apple-api-key.p8" >> "$GITHUB_ENV"
+
       - name: Build and upload
         uses: tauri-apps/tauri-action@v0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
           TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+          APPLE_API_KEY: ${{ secrets.APPLE_API_KEY_ID }}
         with:
           releaseId: ${{ needs.prepare.outputs.release_id }}
           args: ${{ matrix.args }}
 
+      - name: Verify the bundle is signed and notarized
+        if: runner.os == 'macOS' && env.APPLE_API_KEY_PATH != ''
+        shell: bash
+        run: |
+          app="src-tauri/target/universal-apple-darwin/release/bundle/macos/Margin.app"
+          codesign --verify --deep --strict --verbose=2 "$app"
+          # Gatekeeper only says "accepted" once the notarization ticket is stapled to the bundle,
+          # so this is the check that a user double-clicking the dmg will actually get past.
+          spctl --assess --type execute --verbose=4 "$app"
+          xcrun stapler validate "$app"
+
   publish:
     needs: [prepare, build]
     runs-on: ubuntu-latest
@@ -175,8 +211,49 @@ jobs:
           jq '.platforms | keys' latest.json
           for key in darwin-aarch64 darwin-x86_64 linux-x86_64 windows-x86_64; do
             if ! jq -e ".platforms[\"$key\"].url" latest.json > /dev/null; then
-              echo "::error::latest.json is missing platform '$key' — refusing to publish a partial update manifest. Re-run the release."
+              echo "::error::latest.json is missing platform '$key'. Refusing to publish a partial update manifest; re-run the release."
               exit 1
             fi
           done
           gh release edit "$TAG" --repo "$REPO" --draft=false --latest
+
+  homebrew:
+    needs: [prepare, publish]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Point the cask at the release that just went out
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DEPLOY_KEY: ${{ secrets.HOMEBREW_TAP_DEPLOY_KEY }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ needs.prepare.outputs.tag }}
+          VERSION: ${{ needs.prepare.outputs.version }}
+          TAP: priyanshujain/homebrew-margin
+        run: |
+          if [ -z "$DEPLOY_KEY" ]; then
+            echo "::warning::HOMEBREW_TAP_DEPLOY_KEY is not set, so $TAG is published but the Homebrew cask still points at the previous version."
+            exit 0
+          fi
+
+          dmg="Margin_${VERSION}_universal.dmg"
+          gh release download "$TAG" --repo "$REPO" --pattern "$dmg" --output "$dmg"
+          sha=$(sha256sum "$dmg" | cut -d' ' -f1)
+
+          # A deploy key rather than a token: it reaches the tap and nothing else, so a leak from
+          # this job cannot touch the app repos.
+          mkdir -p ~/.ssh
+          printf '%s\n' "$DEPLOY_KEY" > ~/.ssh/tap_key
+          chmod 600 ~/.ssh/tap_key
+          ssh-keyscan github.com >> ~/.ssh/known_hosts 2>/dev/null
+          export GIT_SSH_COMMAND="ssh -i ~/.ssh/tap_key -o IdentitiesOnly=yes"
+
+          git clone --depth 1 "[email protected]:$TAP.git" tap
+          cd tap
+          sed -i -E "s|^  version \".*\"|  version \"$VERSION\"|" Casks/margin.rb
+          sed -i -E "s|^  sha256 \".*\"|  sha256 \"$sha\"|" Casks/margin.rb
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add Casks/margin.rb
+          git commit -m "margin $VERSION"
+          git push

.gitignore

@@ -33,3 +33,10 @@ src-tauri/target/
 # Screenshots & Playwright MCP artifacts
 .playwright-mcp/
 /*.png
+
+# App Store packaging output
+target-mas/
+
+# Beta app review contact details. Apple requires a real phone number and this repo is public.
+appstore/metadata/review_phone.txt
+appstore/metadata/review_email.txt

AGENTS.md

@@ -1,5 +1,6 @@
 ## Project Guidelines
 
+- After completing changes, build and install the updated app for manual testing.
 - Do not call the task done until it is fully complete and tested.
 - Do not dismiss bug as a pre-existing" issue even if it was present before your change. It does not matter, it's still your responsibility to fix it. When you see a bug, fix it. Don't ignore it.
 
@@ -11,6 +12,6 @@
 ## Git Commit Rules
 
   - Do not make branches, commit in main only
-  - Use conventional commit format: `feat|fix|refactor|docs|test|chore|ci(scope): message`
+  - Commit message is one plain lowercase line. No type prefix, no scope, no body.
   - Never use `git add .` or `git add -A`. Always stage specific files by name.
   - Don't batch multiple unrelated changes into one commit.

LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Priyanshu Jain
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,15 @@
 # margin
 
 Write your book. Own every word. A calm, offline studio to write, format, and publish your book to every store and to print.
+
+Download it from [margin.73ai.org](https://margin.73ai.org), or install it with Homebrew:
+
+```
+brew tap priyanshujain/margin
+brew trust priyanshujain/margin
+brew install --cask margin
+```
+
+How releases are signed and where they go is in [docs/publishing.md](docs/publishing.md).
+
+Licensed [FSL-1.1-MIT](LICENSE): use it for anything except building a competing product, and every version turns MIT two years after its release.

appstore/metadata/beta_feedback_email.txt

@@ -0,0 +1 @@
+[email protected]

appstore/metadata/copyright.txt

@@ -0,0 +1 @@
+2026 Priyanshu Jain

appstore/metadata/en-US/beta_description.txt

@@ -0,0 +1,5 @@
+Margin is an offline writing studio. Write without anything in the way, see your words set in real typography as you go, and export a print-ready PDF or an EPUB when you are ready.
+
+This build runs in the App Store sandbox, which is new, so the things most worth trying are the ones that touch the file system: importing, exporting a PDF or EPUB, and the optional Google Drive backup. If any of those fail where they used to work, that is the bug worth reporting.
+
+There is no account and nothing to sign up for.

appstore/metadata/en-US/description.txt

@@ -0,0 +1,13 @@
+Margin is a calm, offline writing studio. Write without anything in the way, see your words set in real typography as you go, and keep every one of them on your own machine.
+
+WRITE
+A quiet editor that stays out of the way, with your work down one side and a live page preview down the other, showing your words as they will actually appear rather than as a word processor imagines them.
+
+PROOF
+Spelling and grammar are checked as you write, using the same system engine as the rest of macOS. Your words are never sent anywhere to be checked.
+
+PUBLISH
+When you are ready, export a print-ready PDF set in real typography, with proper margins, page numbers and running heads. Or export EPUB, ready for Apple Books, Kindle, Kobo and the rest.
+
+YOURS
+No account. No sign-up. No subscription. Your work is a single file on your computer that you can copy, rename, back up, or move to another machine. Nothing is locked inside a library you cannot get out of. If you would like a backup, Margin can save one to your own Google Drive, in your account and under your control.

appstore/metadata/en-US/keywords.txt

@@ -0,0 +1 @@
+writing,writer,editor,text,document,offline,grammar,typography,epub,pdf,author,manuscript,draft

appstore/metadata/en-US/marketing_url.txt

@@ -0,0 +1 @@
+https://margin.73ai.org

appstore/metadata/en-US/name.txt

@@ -0,0 +1 @@
+Margin: The Writing App

appstore/metadata/en-US/privacy_url.txt

@@ -0,0 +1 @@
+https://margin.73ai.org/privacy

appstore/metadata/en-US/promotional_text.txt

@@ -0,0 +1 @@
+Write without anything in the way. Real typography, spelling and grammar on your own machine, and export to PDF or EPUB when you are ready.

appstore/metadata/en-US/release_notes.txt

@@ -0,0 +1 @@
+First release.

appstore/metadata/en-US/subtitle.txt

@@ -0,0 +1 @@
+A calm, offline writing studio

appstore/metadata/en-US/support_url.txt

@@ -0,0 +1 @@
+https://margin.73ai.org

appstore/metadata/primary_category.txt

@@ -0,0 +1 @@
+PRODUCTIVITY

appstore/metadata/review_first_name.txt

@@ -0,0 +1 @@
+Priyanshu

appstore/metadata/review_last_name.txt

@@ -0,0 +1 @@
+Jain

appstore/metadata/review_notes.txt

@@ -0,0 +1,33 @@
+Margin is a writing app. There are no accounts and no demo credentials are needed: open it and
+start writing.
+
+com.apple.security.network.server
+
+This is for the optional Google Drive backup, and that is the only thing in the app that uses it.
+
+Google's OAuth flow for installed apps returns the authorization code by redirecting the user's
+browser to a loopback address. Margin binds a listener on 127.0.0.1 on an ephemeral port, opens the
+consent page in the default browser, accepts the one redirect that comes back from that local
+browser, reads the code and closes the socket. The App Sandbox refuses that bind without
+com.apple.security.network.server, and sign-in then hangs on a browser tab with nowhere to return
+to. Google withdrew the out-of-band alternative, so loopback is the only flow still available to a
+desktop app.
+
+The socket is bound to 127.0.0.1 only and never to a routable interface, so nothing off this Mac
+can reach it. It exists only while a sign-in is in progress, times out after 120 seconds, and
+rejects any request whose state parameter does not match the one just generated.
+
+To see it: the cloud icon at the top of the opening library screen opens Backup and Sync, and
+"Connect Google Drive" there starts the flow. Finishing it needs a Google account of your own.
+Everything else in the app works without one.
+
+com.apple.security.network.client
+
+Used only to reach googleapis.com for that same backup, which stays off until the user connects
+their own Google account. Nothing else Margin does touches the network: writing, the page preview,
+spelling, grammar and both exports all run on the machine.
+
+com.apple.security.files.user-selected.read-write
+
+Importing an EPUB and exporting a PDF or EPUB go through the standard open and save panels, so the
+app only ever reaches the file the user picked. The library itself lives in the app container.

appstore/screenshots/README.md

@@ -0,0 +1,51 @@
+# Mac App Store screenshots
+
+Five 2560x1600 frames for the Margin listing: `frame-1.png` through `frame-5.png`.
+
+Each frame is an HTML page in `src/`, rendered at a 2560x1600 viewport with a device pixel ratio of
+1. The app window inside the frame is not a bitmap capture. It is a CSS rebuild of the real app in
+`src/app.css`, with rules and values lifted from `shared/css/tokens.css` and `src/styles/app.css`,
+laid out at the app's own 1440x900 and scaled once into the 1600x1000 window well. That is why the
+type is sharp: it is real text at render time, not a resampled screenshot.
+
+| File | Frame | Shows |
+| --- | --- | --- |
+| `frame-1.png` | Write | The writing surface, preview dock closed |
+| `frame-2.png` | Preview | The editor beside the live page preview |
+| `frame-3.png` | Proof | Three proofing marks and an open spelling popover |
+| `frame-4.png` | Publish | The PDF export preview panel over the editor |
+| `frame-5.png` | Yours | The library, no sign-in anywhere |
+
+## Re-rendering
+
+Serve this directory and screenshot each page at a 2560x1600 viewport, dpr 1:
+
+```
+python3 -m http.server 8731
+```
+
+Load `http://127.0.0.1:8731/src/frame-1.html` and capture the viewport to `frame-1.png` here. Check
+every output with `sips -g pixelWidth -g pixelHeight frame-*.png`; App Store Connect rejects
+anything that is not exactly 2560x1600.
+
+Type comes from Google Fonts (Literata for headlines and prose, Hanken Grotesk for the interface),
+so the render needs a network connection.
+
+## Editing
+
+`src/frame.css` is the frame surface: the eyebrow, headline, supporting line and the window well.
+Every length in it is a real output pixel.
+
+`src/app.css` is the app window. Every length in it is an app pixel, so a value copied out of the
+product's own stylesheet can go in unchanged. Keep it that way; the whole point is that the
+screenshots stay honest about what the app looks like.
+
+Copy lives in each `src/frame-N.html`, along with that frame's window markup, since every frame
+shows a different state of the app.
+
+## Sample content
+
+The frames use "The Quiet Hours" by Elena Marsh, an invented author. The prose is original and
+written for this listing, so it is safe to publish. If you change it, keep it general non-fiction
+rather than novel writing: the listing positions Margin as a writing app, not as software for one
+genre.

appstore/screenshots/src/app.css

@@ -0,0 +1,807 @@
+/* The Margin window, rebuilt in CSS so it renders crisply at any scale.
+   Rules and values are lifted from the app itself: shared/css/tokens.css and
+   src/styles/app.css. Authored at the app's own pixel sizes in a 1440x900
+   window, then scaled once by frame.css to fill the 1600x1000 window well. */
+
+:root {
+  --font-ui: "Hanken Grotesk", ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-book: "Literata", Georgia, "Times New Roman", serif;
+  --font-heading: "Literata", Georgia, "Times New Roman", serif;
+
+  --r-sm: 5px;
+  --r-md: 8px;
+  --r-lg: 12px;
+
+  --pane-sidebar: 248px;
+  --pane-dock: 384px;
+  --measure: 46em;
+  --titlebar-h: 46px;
+
+  --t-1: 11px;
+  --t-2: 12px;
+  --t-3: 13px;
+  --t-4: 15px;
+
+  --paper: #fcfbf7;
+  --shell: #f1ece2;
+  --sidebar: #ece6da;
+  --raised: #fbfaf6;
+
+  --ink: #23201b;
+  --ink-soft: #6b6458;
+  --ink-faint: #9b9484;
+
+  --line: #e3ddce;
+  --line-strong: #d6cfbd;
+
+  --accent: #2a2622;
+  --accent-ink: #100e0b;
+  --accent-wash: rgba(35, 32, 27, 0.08);
+  --accent-contrast: #faf7f0;
+
+  --danger: #b4453a;
+  --danger-ink: #963327;
+
+  --shadow-page: 0 1px 2px rgba(35, 32, 27, 0.06), 0 14px 30px rgba(35, 32, 27, 0.09);
+  --shadow-pop: 0 8px 24px rgba(35, 32, 27, 0.14);
+}
+
+.app {
+  position: relative;
+  width: 1440px;
+  height: 900px;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background: var(--shell);
+  color: var(--ink);
+  font-family: var(--font-ui);
+  font-size: var(--t-3);
+  line-height: normal;
+  text-align: left;
+}
+
+.app svg {
+  flex: none;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.6;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+/* Title bar ---------------------------------------------------------------- */
+
+.titlebar {
+  flex: none;
+  position: relative;
+  z-index: 45;
+  height: var(--titlebar-h);
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  align-items: center;
+  padding: 0 14px 0 84px;
+  background: var(--shell);
+  border-bottom: 1px solid var(--line);
+}
+
+.lights {
+  position: absolute;
+  left: 20px;
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  gap: 8px;
+}
+.lights i {
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+}
+.lights i:nth-child(1) {
+  background: #ff5f57;
+}
+.lights i:nth-child(2) {
+  background: #febc2e;
+}
+.lights i:nth-child(3) {
+  background: #28c840;
+}
+
+.titlebar .lead {
+  grid-column: 1;
+  justify-self: start;
+  display: flex;
+  gap: 4px;
+}
+.titlebar .doc-title {
+  grid-column: 2;
+  font-size: var(--t-2);
+  letter-spacing: 0.02em;
+  color: var(--ink-soft);
+}
+.titlebar .actions {
+  grid-column: 3;
+  justify-self: end;
+  display: flex;
+  gap: 4px;
+}
+
+.icon-btn {
+  width: 30px;
+  height: 30px;
+  display: grid;
+  place-items: center;
+  border-radius: var(--r-sm);
+  color: var(--ink-soft);
+}
+.icon-btn[data-on="true"] {
+  color: var(--accent);
+  background: var(--accent-wash);
+  box-shadow: inset 0 0 0 1px var(--line-strong);
+}
+
+.body {
+  flex: 1;
+  display: flex;
+  min-height: 0;
+}
+
+/* Sidebar ------------------------------------------------------------------ */
+
+.sidebar {
+  width: var(--pane-sidebar);
+  flex: none;
+  background: var(--sidebar);
+  border-right: 1px solid var(--line);
+  display: flex;
+  flex-direction: column;
+  padding: 6px 0 10px;
+  overflow: hidden;
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 12px 18px 16px;
+  color: var(--ink-faint);
+}
+.brand .back-label {
+  font-size: var(--t-3);
+  font-weight: 600;
+  color: var(--ink-soft);
+}
+
+.cover-item {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 11px;
+  margin: 2px 10px 4px;
+  padding: 8px 12px;
+  border-radius: var(--r-sm);
+  color: var(--ink-soft);
+  font-size: var(--t-3);
+}
+.cover-item .title {
+  font-weight: 500;
+}
+.cover-item svg {
+  color: var(--ink-faint);
+}
+
+.add-page {
+  margin: 2px 12px;
+  padding: 8px 10px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  border-radius: var(--r-sm);
+  font-size: var(--t-3);
+  color: var(--ink-faint);
+}
+
+.chapters {
+  list-style: none;
+  margin: 6px 0 0;
+  padding: 0 10px;
+  flex: 1;
+  overflow: hidden;
+}
+
+.nav-label {
+  padding: 4px 22px;
+  margin: 0;
+  font-size: var(--t-1);
+  font-weight: 600;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+}
+.nav-section + .nav-section {
+  margin-top: 12px;
+}
+
+.chapter {
+  position: relative;
+  display: flex;
+  align-items: baseline;
+  gap: 11px;
+  padding: 8px 12px;
+  border-radius: var(--r-sm);
+  color: var(--ink-soft);
+}
+.chapter[data-active="true"] {
+  background: var(--paper);
+  color: var(--ink);
+  box-shadow: 0 1px 2px rgba(35, 32, 27, 0.05);
+}
+.chapter[data-active="true"]::before {
+  content: "";
+  position: absolute;
+  left: -10px;
+  top: 8px;
+  bottom: 8px;
+  width: 3px;
+  background: var(--accent);
+  border-radius: 0 2px 2px 0;
+}
+.chapter .num {
+  font-size: var(--t-1);
+  color: var(--ink-faint);
+  width: 13px;
+  font-variant-numeric: tabular-nums;
+}
+.chapter[data-active="true"] .num {
+  color: var(--accent);
+}
+.chapter .text {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.chapter .title {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.chapter .meta {
+  font-size: var(--t-1);
+  letter-spacing: 0.01em;
+  color: var(--ink-faint);
+}
+.chapter .grip {
+  display: grid;
+  place-items: center;
+  align-self: center;
+  margin: 0 -5px 0 -6px;
+  color: var(--ink-faint);
+  opacity: 0;
+}
+.chapter[data-active="true"] .grip {
+  opacity: 0.55;
+}
+
+.add-chapter {
+  margin: 8px 10px 4px;
+  width: calc(100% - 20px);
+  padding: 9px 12px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  border-radius: var(--r-sm);
+  color: var(--ink-faint);
+  border: 1px dashed var(--line-strong);
+}
+
+/* Writing surface ---------------------------------------------------------- */
+
+.editor-pane {
+  flex: 1;
+  min-width: 0;
+  background: var(--paper);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.sheet {
+  width: 100%;
+  max-width: var(--measure);
+  padding: 104px 24px 200px;
+}
+.sheet[data-width="wide"] {
+  max-width: 62em;
+}
+
+.chapter-opener {
+  text-align: center;
+  margin: 0 0 3.4rem;
+}
+.chapter-num {
+  font-family: var(--font-ui);
+  font-size: var(--t-1);
+  font-weight: 600;
+  letter-spacing: 0.28em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+  margin: 0;
+}
+.chapter-title {
+  font-family: var(--font-heading);
+  font-weight: 500;
+  font-size: 31px;
+  line-height: 1.16;
+  letter-spacing: -0.01em;
+  margin: 15px 0 0;
+}
+
+.prose {
+  font-family: var(--font-book);
+  color: var(--ink);
+  font-optical-sizing: auto;
+}
+.prose p {
+  font-size: 19px;
+  line-height: 1.68;
+  margin: 0;
+  text-align: justify;
+  hyphens: auto;
+  -webkit-hyphens: auto;
+}
+.prose p[data-indent="true"] {
+  text-indent: 1.3em;
+}
+.prose .first::first-letter {
+  float: left;
+  font-size: 3.1em;
+  line-height: 0.82;
+  padding: 0.05em 0.09em 0 0;
+  font-weight: 500;
+}
+
+.caret {
+  display: inline-block;
+  width: 1.5px;
+  height: 1.05em;
+  background: var(--ink);
+  vertical-align: -0.18em;
+  margin-left: 1px;
+}
+
+/* Proofing ----------------------------------------------------------------- */
+
+.proof-mark {
+  border-radius: 2px;
+  text-decoration: underline;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 3px;
+  -webkit-box-decoration-break: clone;
+  box-decoration-break: clone;
+}
+.proof-mark.sev-error {
+  background: rgba(180, 69, 58, 0.13);
+  text-decoration-color: #b4453a;
+}
+.proof-mark.sev-warn {
+  background: rgba(168, 119, 24, 0.16);
+  text-decoration-color: #9c6e16;
+}
+.proof-mark.sev-suggest {
+  background: rgba(47, 110, 79, 0.13);
+  text-decoration-color: #2f6e4f;
+}
+
+.proof-anchor {
+  position: relative;
+}
+.proof-pop {
+  position: absolute;
+  top: calc(100% + 6px);
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 50;
+  width: 264px;
+  padding: 8px;
+  background: var(--paper);
+  border: 1px solid var(--line);
+  border-radius: var(--r-md);
+  box-shadow: var(--shadow-pop);
+  font-family: var(--font-ui);
+  text-align: left;
+  text-indent: 0;
+}
+.proof-pop-kind {
+  display: inline-block;
+  margin: 0 0 6px 2px;
+  padding: 2px 8px;
+  border-radius: 999px;
+  font-size: var(--t-1);
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+.proof-pop-kind.sev-error {
+  background: rgba(180, 69, 58, 0.14);
+  color: var(--danger-ink);
+}
+.proof-pop-msg {
+  display: block;
+  padding: 2px 4px 8px;
+  font-size: var(--t-2);
+  color: var(--ink-soft);
+  line-height: 1.4;
+}
+.proof-pop-suggestions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+.proof-suggestion {
+  padding: 5px 10px;
+  border-radius: var(--r-sm);
+  background: var(--accent-wash);
+  color: var(--ink);
+  font-size: var(--t-2);
+  font-weight: 600;
+}
+.proof-suggestion.is-hover {
+  background: var(--accent);
+  color: var(--accent-contrast);
+}
+.proof-pop-actions {
+  display: flex;
+  gap: 4px;
+  margin-top: 8px;
+  padding-top: 8px;
+  border-top: 1px solid var(--line);
+}
+.proof-action {
+  flex: 1;
+  padding: 6px 8px;
+  border-radius: var(--r-sm);
+  font-size: var(--t-1);
+  color: var(--ink-soft);
+  text-align: center;
+}
+
+/* Preview dock ------------------------------------------------------------- */
+
+.dock {
+  width: var(--pane-dock);
+  flex: none;
+  background: var(--shell);
+  border-left: 1px solid var(--line);
+  overflow: hidden;
+  padding: 26px 28px 80px;
+}
+.dock-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 18px;
+}
+.dock-head .label {
+  font-size: var(--t-1);
+  font-weight: 600;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+}
+.dock-head .meta {
+  font-size: var(--t-1);
+  color: var(--ink-faint);
+  font-variant-numeric: tabular-nums;
+}
+.dock-tools {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+.trim-select {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  font-family: var(--font-ui);
+  font-size: var(--t-2);
+  color: var(--ink-soft);
+  background: var(--raised);
+  border: 1px solid var(--line);
+  border-radius: var(--r-sm);
+  padding: 4px 8px;
+}
+.trim-select svg {
+  width: 11px;
+  height: 11px;
+  color: var(--ink-faint);
+}
+
+.dock-col {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.page {
+  position: relative;
+  background: #fffefb;
+  border: 1px solid var(--line);
+  border-radius: 2px;
+  box-shadow: var(--shadow-page);
+  aspect-ratio: 6 / 9;
+  padding: 11% 12% 13%;
+  overflow: hidden;
+  flex: none;
+}
+.page .p-opener {
+  text-align: center;
+  margin-bottom: 15px;
+}
+.page .p-num {
+  font-family: var(--font-ui);
+  font-size: 6px;
+  font-weight: 600;
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+  margin: 0;
+}
+.page .p-title {
+  font-family: var(--font-heading);
+  font-size: 12px;
+  margin: 5px 0 0;
+}
+.page p {
+  font-family: var(--font-book);
+  font-size: 6.6px;
+  line-height: 1.5;
+  text-align: justify;
+  hyphens: auto;
+  -webkit-hyphens: auto;
+  margin: 0;
+  color: #2b2720;
+}
+.page p[data-indent="true"] {
+  text-indent: 1.2em;
+}
+.page .folio {
+  position: absolute;
+  left: 12%;
+  right: 12%;
+  bottom: 5.5%;
+  text-align: center;
+  font-family: var(--font-book);
+  font-size: 6px;
+  color: var(--ink-faint);
+}
+
+/* Export preview panel ----------------------------------------------------- */
+
+.overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 55;
+  background: rgba(35, 32, 27, 0.28);
+  -webkit-backdrop-filter: blur(2px);
+  backdrop-filter: blur(2px);
+}
+
+.preview-panel {
+  position: absolute;
+  z-index: 56;
+  display: flex;
+  flex-direction: column;
+  background: var(--paper);
+  border: 1px solid var(--line);
+  border-radius: var(--r-lg);
+  box-shadow: var(--shadow-pop);
+  overflow: hidden;
+}
+.preview-bar {
+  flex: none;
+  height: 52px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 0 12px;
+  background: var(--paper);
+  border-bottom: 1px solid var(--line);
+}
+.preview-title {
+  flex: 1;
+  min-width: 0;
+  font-family: var(--font-book);
+  font-size: 15px;
+  color: var(--ink);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.preview-count {
+  font-size: var(--t-2);
+  color: var(--ink-faint);
+  font-variant-numeric: tabular-nums;
+}
+.preview-zoom {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+}
+.preview-zoom span {
+  width: 44px;
+  text-align: center;
+  font-size: var(--t-2);
+  color: var(--ink-soft);
+  font-variant-numeric: tabular-nums;
+}
+.btn-primary {
+  font-family: var(--font-ui);
+  font-size: var(--t-3);
+  font-weight: 500;
+  padding: 9px 20px;
+  border-radius: var(--r-sm);
+  background: var(--accent);
+  color: var(--accent-contrast);
+}
+.preview-stage {
+  flex: 1;
+  overflow: hidden;
+  padding: 28px;
+  background: var(--shell);
+}
+.preview-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+}
+.preview-page {
+  position: relative;
+  flex: none;
+  width: 460px;
+  aspect-ratio: 6 / 9;
+  background: #fff;
+  border-radius: 2px;
+  box-shadow: var(--shadow-page);
+  overflow: hidden;
+  padding: 11% 12% 13%;
+  color: #23201b;
+}
+.preview-page .p-opener {
+  text-align: center;
+  margin-bottom: 22px;
+}
+.preview-page .p-num {
+  font-family: var(--font-ui);
+  font-size: 8.4px;
+  font-weight: 600;
+  letter-spacing: 0.24em;
+  text-transform: uppercase;
+  color: #9b9484;
+  margin: 0;
+}
+.preview-page .p-title {
+  font-family: var(--font-heading);
+  font-size: 16.8px;
+  font-weight: 500;
+  margin: 7px 0 0;
+}
+.preview-page p {
+  font-family: var(--font-book);
+  font-size: 9.2px;
+  line-height: 1.62;
+  text-align: justify;
+  hyphens: auto;
+  -webkit-hyphens: auto;
+  margin: 0;
+  color: #2b2720;
+}
+.preview-page p[data-indent="true"] {
+  text-indent: 1.2em;
+}
+.preview-page .first::first-letter {
+  float: left;
+  font-size: 3.1em;
+  line-height: 0.82;
+  padding: 0.05em 0.09em 0 0;
+  font-weight: 500;
+}
+.preview-page .folio {
+  position: absolute;
+  left: 12%;
+  right: 12%;
+  bottom: 5.5%;
+  text-align: center;
+  font-family: var(--font-book);
+  font-size: 8.4px;
+  color: #b3ab9c;
+}
+
+/* Library ------------------------------------------------------------------ */
+
+.library {
+  position: relative;
+  width: 1440px;
+  height: 900px;
+  overflow: hidden;
+  background: var(--shell);
+  color: var(--ink);
+  font-family: var(--font-ui);
+  font-size: var(--t-3);
+  line-height: normal;
+  text-align: left;
+}
+.library svg {
+  flex: none;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.6;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+.library-head {
+  position: relative;
+  height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  padding: 0 14px;
+}
+.shelf {
+  max-width: 1040px;
+  margin: 0 auto;
+  padding: 26px 44px 80px;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(168px, 1fr));
+  gap: 28px;
+}
+.card {
+  position: relative;
+  aspect-ratio: 5 / 7;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 9px;
+  padding: 22px 18px;
+  text-align: center;
+  border-radius: 4px;
+}
+.card-book {
+  background: var(--paper);
+  border: 1px solid var(--line);
+  box-shadow: var(--shadow-page);
+}
+.card-title {
+  font-family: var(--font-book);
+  font-size: 20px;
+  font-weight: 500;
+  line-height: 1.18;
+  color: var(--ink);
+}
+.card-author {
+  font-size: var(--t-2);
+  color: var(--ink-soft);
+}
+.card-meta {
+  position: absolute;
+  left: 14px;
+  right: 14px;
+  bottom: 14px;
+  font-size: var(--t-1);
+  color: var(--ink-faint);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.card-action {
+  background: transparent;
+  border: 1px dashed var(--line-strong);
+  color: var(--ink-faint);
+  font-size: var(--t-3);
+}

appstore/screenshots/src/frame-1.html

@@ -0,0 +1,155 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Margin App Store frame 1</title>
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:[email protected]&family=Literata:opsz,[email protected],200..900&display=swap" rel="stylesheet" />
+<link rel="stylesheet" href="frame.css" />
+<link rel="stylesheet" href="app.css" />
+</head>
+<body>
+<div class="frame">
+  <p class="eyebrow">Write</p>
+  <h1 class="headline">A calm writing studio.</h1>
+  <p class="support">Your words, set in real typography, with nothing else asking for attention.</p>
+
+  <div class="shot"><div class="shot__scale">
+    <div class="app">
+      <header class="titlebar">
+        <span class="lights"><i></i><i></i><i></i></span>
+        <span class="lead">
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 4.5h18v15H3zM9 4.5v15" /></svg></span>
+        </span>
+        <span class="doc-title">The Quiet Hours</span>
+        <span class="actions">
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M7 18a4 4 0 0 1 0-8 5 5 0 0 1 9.6-1.3A3.5 3.5 0 0 1 18 18H7z" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM20 20l-4-4" /></svg></span>
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M4 17l4-10 4 10M5.4 13.4h5.2M15 17l2.5 2.5L22 14" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M4 7h16M4 12h12M4 17h7M13.5 18.5c1-1.2 2-1.2 3 0s2 1.2 3 0" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 5v14M21 5v14M7 12h10M7 12l3-3M7 12l3 3M17 12l-3-3M17 12l-3 3" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M5 13v6h14v-6M12 16V3M8 7l4-4 4 4" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 4.5h18v15H3zM14 4.5v15" /></svg></span>
+        </span>
+      </header>
+
+      <div class="body">
+        <aside class="sidebar">
+          <span class="brand">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M14 7l-5 5 5 5" /></svg>
+            <span class="back-label">All projects</span>
+          </span>
+          <span class="cover-item">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M5 4h11l3 3v13H5zM16 4v4h3" /></svg>
+            <span class="title">Cover</span>
+          </span>
+          <span class="add-page">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+            <span>Add page</span>
+          </span>
+
+          <ul class="chapters">
+            <li class="nav-section">
+              <p class="nav-label">Front matter</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">Title Page</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">Epigraph</span></span>
+              </div>
+            </li>
+
+            <li class="nav-section">
+              <p class="nav-label">Chapters</p>
+              <div class="chapter" data-active="true">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">1</span>
+                <span class="text">
+                  <span class="title">The Long Morning</span>
+                  <span class="meta">Edited just now</span>
+                </span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">2</span>
+                <span class="text"><span class="title">On Interruption</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">3</span>
+                <span class="text"><span class="title">What the Draft Knows</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">4</span>
+                <span class="text"><span class="title">A Note on Endings</span></span>
+              </div>
+              <span class="add-chapter">
+                <svg width="16" height="16" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+                <span>New chapter</span>
+              </span>
+            </li>
+
+            <li class="nav-section">
+              <p class="nav-label">Back matter</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">About the Author</span></span>
+              </div>
+            </li>
+          </ul>
+        </aside>
+
+        <main class="editor-pane">
+          <div class="sheet">
+            <div class="chapter-opener">
+              <p class="chapter-num">Chapter 1</p>
+              <h1 class="chapter-title">The Long Morning</h1>
+            </div>
+            <div class="prose">
+              <p class="first">
+                The best hours are the ones nobody asks for. They arrive before the day has decided
+                what it wants from you, and they leave without ceremony, and what happens in them is
+                almost never what you planned.
+              </p>
+              <p data-indent="true">
+                I have kept the same desk for eleven years. It is not a good desk. One leg is
+                shorter than the others and I have never fixed it, because the small tilt reminds
+                me, every time I sit down, that the work is not going to be perfect either, and that
+                this has never once stopped anybody.
+              </p>
+              <p data-indent="true">
+                What I have learned about working slowly is that it is not slow. It only looks that
+                way from the outside. From inside it feels like the only speed at which anything
+                holds together.
+              </p>
+              <p data-indent="true">
+                There is a particular hour, somewhere between the first coffee and the second, when
+                the work stops feeling like a performance. Nothing on the page has changed. What has
+                changed is that you have stopped listening for applause.
+              </p>
+              <p data-indent="true">
+                The trick, if there is one, is to start before you are ready. Readiness is a story
+                you tell yourself about a future morning that will be calmer than this one, and it
+                will not be. The calm is something you make, badly at first, out of whatever the day
+                has left lying around.
+              </p>
+              <p data-indent="true">
+                I write the first sentence standing up. I do not know why this works and I have
+                stopped asking. Somewhere in the business of not sitting down the sentence loses its
+                self-consciousness, and by the time I take the chair there is something on the page
+                to argue with.
+              </p>
+            </div>
+          </div>
+        </main>
+      </div>
+    </div>
+  </div></div>
+</div>
+</body>
+</html>

appstore/screenshots/src/frame-2.html

@@ -0,0 +1,268 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Margin App Store frame 2</title>
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:[email protected]&family=Literata:opsz,[email protected],200..900&display=swap" rel="stylesheet" />
+<link rel="stylesheet" href="frame.css" />
+<link rel="stylesheet" href="app.css" />
+</head>
+<body>
+<div class="frame">
+  <p class="eyebrow">Preview</p>
+  <h1 class="headline">Typeset as you write.</h1>
+  <p class="support">A live page preview shows every sentence exactly as it will come out in print.</p>
+
+  <div class="shot"><div class="shot__scale">
+    <div class="app">
+      <header class="titlebar">
+        <span class="lights"><i></i><i></i><i></i></span>
+        <span class="lead">
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 4.5h18v15H3zM9 4.5v15" /></svg></span>
+        </span>
+        <span class="doc-title">The Quiet Hours</span>
+        <span class="actions">
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M7 18a4 4 0 0 1 0-8 5 5 0 0 1 9.6-1.3A3.5 3.5 0 0 1 18 18H7z" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM20 20l-4-4" /></svg></span>
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M4 17l4-10 4 10M5.4 13.4h5.2M15 17l2.5 2.5L22 14" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M4 7h16M4 12h12M4 17h7M13.5 18.5c1-1.2 2-1.2 3 0s2 1.2 3 0" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 5v14M21 5v14M7 12h10M7 12l3-3M7 12l3 3M17 12l-3-3M17 12l-3 3" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M5 13v6h14v-6M12 16V3M8 7l4-4 4 4" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" /></svg></span>
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 4.5h18v15H3zM14 4.5v15" /></svg></span>
+        </span>
+      </header>
+
+      <div class="body">
+        <aside class="sidebar">
+          <span class="brand">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M14 7l-5 5 5 5" /></svg>
+            <span class="back-label">All projects</span>
+          </span>
+          <span class="cover-item">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M5 4h11l3 3v13H5zM16 4v4h3" /></svg>
+            <span class="title">Cover</span>
+          </span>
+          <span class="add-page">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+            <span>Add page</span>
+          </span>
+
+          <ul class="chapters">
+            <li class="nav-section">
+              <p class="nav-label">Front matter</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">Title Page</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">Epigraph</span></span>
+              </div>
+            </li>
+
+            <li class="nav-section">
+              <p class="nav-label">Chapters</p>
+              <div class="chapter" data-active="true">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">1</span>
+                <span class="text">
+                  <span class="title">The Long Morning</span>
+                  <span class="meta">Edited just now</span>
+                </span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">2</span>
+                <span class="text"><span class="title">On Interruption</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">3</span>
+                <span class="text"><span class="title">What the Draft Knows</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">4</span>
+                <span class="text"><span class="title">A Note on Endings</span></span>
+              </div>
+              <span class="add-chapter">
+                <svg width="16" height="16" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+                <span>New chapter</span>
+              </span>
+            </li>
+
+            <li class="nav-section">
+              <p class="nav-label">Back matter</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">About the Author</span></span>
+              </div>
+            </li>
+          </ul>
+        </aside>
+
+        <main class="editor-pane">
+          <div class="sheet">
+            <div class="chapter-opener">
+              <p class="chapter-num">Chapter 1</p>
+              <h1 class="chapter-title">The Long Morning</h1>
+            </div>
+            <div class="prose">
+              <p class="first">
+                The best hours are the ones nobody asks for. They arrive before the day has decided
+                what it wants from you, and they leave without ceremony, and what happens in them is
+                almost never what you planned.
+              </p>
+              <p data-indent="true">
+                I have kept the same desk for eleven years. It is not a good desk. One leg is
+                shorter than the others and I have never fixed it, because the small tilt reminds
+                me, every time I sit down, that the work is not going to be perfect either, and that
+                this has never once stopped anybody.
+              </p>
+              <p data-indent="true">
+                What I have learned about working slowly is that it is not slow. It only looks that
+                way from the outside. From inside it feels like the only speed at which anything
+                holds together.
+              </p>
+              <p data-indent="true">
+                There is a particular hour, somewhere between the first coffee and the second, when
+                the work stops feeling like a performance. Nothing on the page has changed. What has
+                changed is that you have stopped listening for applause.
+              </p>
+              <p data-indent="true">
+                The trick, if there is one, is to start before you are ready. Readiness is a story
+                you tell yourself about a future morning that will be calmer than this one, and it
+                will not be. The calm is something you make, badly at first, out of whatever the day
+                has left lying around.
+              </p>
+              <p data-indent="true">
+                I write the first sentence standing up. I do not know why this works and I have
+                stopped asking. Somewhere in the business of not sitting down the sentence loses its
+                self-consciousness, and by the time I take the chair there is something on the page
+                to argue with.
+              </p>
+            </div>
+          </div>
+        </main>
+
+        <section class="dock">
+          <div class="dock-head">
+            <span class="label">Preview</span>
+            <span class="dock-tools">
+              <span class="meta">1 of 4</span>
+              <span class="trim-select">
+                6 &times; 9 in
+                <svg viewBox="0 0 24 24"><path d="M8 10l4-4 4 4M8 14l4 4 4-4" /></svg>
+              </span>
+            </span>
+          </div>
+
+          <div class="dock-col">
+            <div class="page">
+              <div class="p-opener">
+                <p class="p-num">Chapter 1</p>
+                <p class="p-title">The Long Morning</p>
+              </div>
+              <p>
+                The best hours are the ones nobody asks for. They arrive before the day has decided
+                what it wants from you, and they leave without ceremony, and what happens in them is
+                almost never what you planned.
+              </p>
+              <p data-indent="true">
+                I have kept the same desk for eleven years. It is not a good desk. One leg is
+                shorter than the others and I have never fixed it, because the small tilt reminds
+                me, every time I sit down, that the work is not going to be perfect either, and that
+                this has never once stopped anybody.
+              </p>
+              <p data-indent="true">
+                What I have learned about working slowly is that it is not slow. It only looks that
+                way from the outside. From inside it feels like the only speed at which anything
+                holds together.
+              </p>
+              <p data-indent="true">
+                There is a particular hour, somewhere between the first coffee and the second, when
+                the work stops feeling like a performance. Nothing on the page has changed. What has
+                changed is that you have stopped listening for applause.
+              </p>
+              <p data-indent="true">
+                The trick, if there is one, is to start before you are ready. Readiness is a story
+                you tell yourself about a future morning that will be calmer than this one, and it
+                will not be. The calm is something you make, badly at first, out of whatever the day
+                has left lying around.
+              </p>
+              <p data-indent="true">
+                I write the first sentence standing up. I do not know why this works and I have
+                stopped asking. Somewhere in the business of not sitting down the sentence loses its
+                self-consciousness, and by the time I take the chair there is something on the page
+                to argue with.
+              </p>
+              <p data-indent="true">
+                Everything after that is argument. You put a thing down, you read it back, you tell
+                it that it is not quite true, and you try again. Nine times out of ten the second
+                attempt is worse. The tenth is why anybody does this.
+              </p>
+              <p data-indent="true">
+                By eleven the light has moved across the desk and the day has started making its
+                claims. I stop where I am, mid-sentence if I can manage it, because a sentence left
+                open is a door left open, and tomorrow I will walk straight back through it.
+              </p>
+              <p data-indent="true">
+                None of this is a method. A method is something you can hand to somebody else, and I
+                have tried, and what they get is a description of a room they do not live in.
+              </p>
+              <p data-indent="true">
+                What I can hand over is smaller. Sit down before the day has an opinion. Write badly
+                on purpose for ten minutes. Stop while it is still going well. That is the whole of
+                it, and it has taken me eleven years to be able to say it in three sentences.
+              </p>
+              <p class="folio">7</p>
+            </div>
+
+            <div class="page">
+              <p>
+                What the desk knows, and I keep forgetting, is that the work is not a mood. It does
+                not care whether I arrived at it happily. It only registers whether I arrived, and
+                how long I stayed, and whether I was honest about the sentence in front of me while
+                I was there.
+              </p>
+              <p data-indent="true">
+                The second hour is quieter than the first, which nobody warns you about. You expect
+                momentum. What you get is a kind of patience, and it turns out that patience is
+                faster.
+              </p>
+              <p data-indent="true">
+                I have never once regretted a morning spent this way. I have regretted almost every
+                morning spent otherwise, which is not the same as saying that I stopped having them.
+              </p>
+              <p data-indent="true">
+                There is a version of this essay that argues for discipline, and I have read it many
+                times, and it has never once got me out of bed.
+              </p>
+              <p data-indent="true">
+                The version that works is duller. Make the room boring. Put the phone in another
+                room, not face down on the desk, because face down on the desk is still a decision
+                you have to keep making. Decide once, in advance, while you are calm, and then let
+                the morning be simple.
+              </p>
+              <p data-indent="true">
+                I am not a fast writer. I have watched fast writers with the particular envy of
+                someone who has done the arithmetic and knows it does not matter. Over a year the
+                slow ones and the quick ones arrive at roughly the same place, and the slow ones
+                seem to enjoy the journey more, which is not nothing.
+              </p>
+              <p data-indent="true">
+                What I want from a morning is not very much. Two hours. One paragraph I did not have
+                when I sat down. The sense, at the end, that I told the truth about something small.
+              </p>
+            </div>
+          </div>
+        </section>
+      </div>
+    </div>
+  </div></div>
+</div>
+</body>
+</html>

appstore/screenshots/src/frame-3.html

@@ -0,0 +1,161 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Margin App Store frame 3</title>
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:[email protected]&family=Literata:opsz,[email protected],200..900&display=swap" rel="stylesheet" />
+<link rel="stylesheet" href="frame.css" />
+<link rel="stylesheet" href="app.css" />
+</head>
+<body>
+<div class="frame">
+  <p class="eyebrow">Proof</p>
+  <h1 class="headline">Proofed on your machine.</h1>
+  <p class="support">Spelling and grammar as you type, checked on the Mac in front of you. Nothing is sent away to be read.</p>
+
+  <div class="shot"><div class="shot__scale">
+    <div class="app">
+      <header class="titlebar">
+        <span class="lights"><i></i><i></i><i></i></span>
+        <span class="lead">
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 4.5h18v15H3zM9 4.5v15" /></svg></span>
+        </span>
+        <span class="doc-title">The Quiet Hours</span>
+        <span class="actions">
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M7 18a4 4 0 0 1 0-8 5 5 0 0 1 9.6-1.3A3.5 3.5 0 0 1 18 18H7z" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM20 20l-4-4" /></svg></span>
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M4 17l4-10 4 10M5.4 13.4h5.2M15 17l2.5 2.5L22 14" /></svg></span>
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M4 7h16M4 12h12M4 17h7M13.5 18.5c1-1.2 2-1.2 3 0s2 1.2 3 0" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 5v14M21 5v14M7 12h10M7 12l3-3M7 12l3 3M17 12l-3-3M17 12l-3 3" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M5 13v6h14v-6M12 16V3M8 7l4-4 4 4" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 4.5h18v15H3zM14 4.5v15" /></svg></span>
+        </span>
+      </header>
+
+      <div class="body">
+        <aside class="sidebar">
+          <span class="brand">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M14 7l-5 5 5 5" /></svg>
+            <span class="back-label">All projects</span>
+          </span>
+          <span class="cover-item">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M5 4h11l3 3v13H5zM16 4v4h3" /></svg>
+            <span class="title">Cover</span>
+          </span>
+          <span class="add-page">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+            <span>Add page</span>
+          </span>
+
+          <ul class="chapters">
+            <li class="nav-section">
+              <p class="nav-label">Front matter</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">Title Page</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">Epigraph</span></span>
+              </div>
+            </li>
+
+            <li class="nav-section">
+              <p class="nav-label">Chapters</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">1</span>
+                <span class="text"><span class="title">The Long Morning</span></span>
+              </div>
+              <div class="chapter" data-active="true">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">2</span>
+                <span class="text">
+                  <span class="title">On Interruption</span>
+                  <span class="meta">Edited 6 minutes ago</span>
+                </span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">3</span>
+                <span class="text"><span class="title">What the Draft Knows</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">4</span>
+                <span class="text"><span class="title">A Note on Endings</span></span>
+              </div>
+              <span class="add-chapter">
+                <svg width="16" height="16" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+                <span>New chapter</span>
+              </span>
+            </li>
+
+            <li class="nav-section">
+              <p class="nav-label">Back matter</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">About the Author</span></span>
+              </div>
+            </li>
+          </ul>
+        </aside>
+
+        <main class="editor-pane">
+          <div class="sheet">
+            <div class="chapter-opener">
+              <p class="chapter-num">Chapter 2</p>
+              <h1 class="chapter-title">On Interruption</h1>
+            </div>
+            <div class="prose">
+              <p class="first">
+                An interruption costs more than the minutes it takes. It costs the shape of the
+                thought you were holding, which does not come back in the same form, and
+                <span class="proof-anchor"><span class="proof-mark sev-error">occassionally</span><span class="proof-pop">
+                  <span class="proof-pop-kind sev-error">Spelling</span>
+                  <span class="proof-pop-msg">&ldquo;occassionally&rdquo; may be misspelled</span>
+                  <span class="proof-pop-suggestions">
+                    <span class="proof-suggestion is-hover">occasionally</span>
+                    <span class="proof-suggestion">occasional</span>
+                  </span>
+                  <span class="proof-pop-actions">
+                    <span class="proof-action">Ignore</span>
+                    <span class="proof-action">Remember</span>
+                  </span>
+                </span></span>
+                does not come back at all.
+              </p>
+              <p data-indent="true">
+                So I have made the room boring. There is nothing on these walls. The window faces a
+                brick wall two metres away, which sounds like a punishment and is in fact a gift,
+                because there is nothing out there to look at and so I look at the page.
+              </p>
+              <p data-indent="true">
+                People assume the point is discipline. It is not. The point is to make the right
+                thing the easiest thing, so that discipline is never called upon, because discipline
+                is a small and unreliable fuel and it runs out
+                <span class="proof-mark sev-warn">at around</span> eleven in the morning.
+              </p>
+              <p data-indent="true">
+                <span class="proof-mark sev-suggest">There is a thing that happens</span> when you
+                let the morning break in half. The second half is never the first half continued. It
+                is a new morning, shorter, with the good hour already spent, and you will spend it
+                trying to remember what you were about to say.
+              </p>
+              <p data-indent="true">
+                I keep a card by the door with one line on it, in my own handwriting, so that I
+                cannot pretend somebody else set the rule: nothing before the work. Not the post,
+                not the news, not the small useful errand that would only take a minute.
+              </p>
+            </div>
+          </div>
+        </main>
+      </div>
+    </div>
+  </div></div>
+</div>
+</body>
+</html>

appstore/screenshots/src/frame-4.html

@@ -0,0 +1,241 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Margin App Store frame 4</title>
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:[email protected]&family=Literata:opsz,[email protected],200..900&display=swap" rel="stylesheet" />
+<link rel="stylesheet" href="frame.css" />
+<link rel="stylesheet" href="app.css" />
+</head>
+<body>
+<div class="frame">
+  <p class="eyebrow">Publish</p>
+  <h1 class="headline">Export PDF and EPUB.</h1>
+  <p class="support">Read every page before you save it. Send the PDF to a printer, or the EPUB to any store.</p>
+
+  <div class="shot"><div class="shot__scale">
+    <div class="app">
+      <header class="titlebar">
+        <span class="lights"><i></i><i></i><i></i></span>
+        <span class="lead">
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 4.5h18v15H3zM9 4.5v15" /></svg></span>
+        </span>
+        <span class="doc-title">The Quiet Hours</span>
+        <span class="actions">
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M7 18a4 4 0 0 1 0-8 5 5 0 0 1 9.6-1.3A3.5 3.5 0 0 1 18 18H7z" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM20 20l-4-4" /></svg></span>
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M4 17l4-10 4 10M5.4 13.4h5.2M15 17l2.5 2.5L22 14" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M4 7h16M4 12h12M4 17h7M13.5 18.5c1-1.2 2-1.2 3 0s2 1.2 3 0" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 5v14M21 5v14M7 12h10M7 12l3-3M7 12l3 3M17 12l-3-3M17 12l-3 3" /></svg></span>
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M5 13v6h14v-6M12 16V3M8 7l4-4 4 4" /></svg></span>
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" /></svg></span>
+          <span class="icon-btn" data-on="true"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M3 4.5h18v15H3zM14 4.5v15" /></svg></span>
+        </span>
+      </header>
+
+      <div class="body">
+        <aside class="sidebar">
+          <span class="brand">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M14 7l-5 5 5 5" /></svg>
+            <span class="back-label">All projects</span>
+          </span>
+          <span class="cover-item">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M5 4h11l3 3v13H5zM16 4v4h3" /></svg>
+            <span class="title">Cover</span>
+          </span>
+          <span class="add-page">
+            <svg width="15" height="15" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+            <span>Add page</span>
+          </span>
+
+          <ul class="chapters">
+            <li class="nav-section">
+              <p class="nav-label">Front matter</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">Title Page</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">Epigraph</span></span>
+              </div>
+            </li>
+
+            <li class="nav-section">
+              <p class="nav-label">Chapters</p>
+              <div class="chapter" data-active="true">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">1</span>
+                <span class="text">
+                  <span class="title">The Long Morning</span>
+                  <span class="meta">Edited just now</span>
+                </span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">2</span>
+                <span class="text"><span class="title">On Interruption</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">3</span>
+                <span class="text"><span class="title">What the Draft Knows</span></span>
+              </div>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="num">4</span>
+                <span class="text"><span class="title">A Note on Endings</span></span>
+              </div>
+              <span class="add-chapter">
+                <svg width="16" height="16" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+                <span>New chapter</span>
+              </span>
+            </li>
+
+            <li class="nav-section">
+              <p class="nav-label">Back matter</p>
+              <div class="chapter">
+                <span class="grip"><svg width="14" height="14" viewBox="0 0 24 24"><path d="M9 6h.01M15 6h.01M9 12h.01M15 12h.01M9 18h.01M15 18h.01" /></svg></span>
+                <span class="text"><span class="title">About the Author</span></span>
+              </div>
+            </li>
+          </ul>
+        </aside>
+
+        <main class="editor-pane">
+          <div class="sheet">
+            <div class="chapter-opener">
+              <p class="chapter-num">Chapter 1</p>
+              <h1 class="chapter-title">The Long Morning</h1>
+            </div>
+            <div class="prose">
+              <p class="first">
+                The best hours are the ones nobody asks for. They arrive before the day has decided
+                what it wants from you, and they leave without ceremony, and what happens in them is
+                almost never what you planned.
+              </p>
+            </div>
+          </div>
+        </main>
+
+        <section class="dock">
+          <div class="dock-head">
+            <span class="label">Preview</span>
+            <span class="dock-tools">
+              <span class="meta">1 of 4</span>
+              <span class="trim-select">
+                6 &times; 9 in
+                <svg viewBox="0 0 24 24"><path d="M8 10l4-4 4 4M8 14l4 4 4-4" /></svg>
+              </span>
+            </span>
+          </div>
+          <div class="dock-col">
+            <div class="page">
+              <div class="p-opener">
+                <p class="p-num">Chapter 1</p>
+                <p class="p-title">The Long Morning</p>
+              </div>
+              <p>
+                The best hours are the ones nobody asks for. They arrive before the day has decided
+                what it wants from you, and they leave without ceremony, and what happens in them is
+                almost never what you planned.
+              </p>
+              <p data-indent="true">
+                I have kept the same desk for eleven years. It is not a good desk. One leg is
+                shorter than the others and I have never fixed it, because the small tilt reminds
+                me, every time I sit down, that the work is not going to be perfect either, and that
+                this has never once stopped anybody.
+              </p>
+            </div>
+          </div>
+        </section>
+      </div>
+
+      <div class="overlay"></div>
+
+      <div class="preview-panel" style="left: 248px; top: 46px; width: 808px; height: 854px;">
+        <div class="preview-bar">
+          <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M6 6l12 12M18 6L6 18" /></svg></span>
+          <span class="preview-title">The Quiet Hours</span>
+          <span class="preview-count">96 pages</span>
+          <span class="preview-zoom">
+            <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M5 12h14" /></svg></span>
+            <span>Fit</span>
+            <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg></span>
+          </span>
+          <span class="btn-primary">Save PDF&hellip;</span>
+        </div>
+
+        <div class="preview-stage">
+          <div class="preview-col">
+            <div class="preview-page">
+              <div class="p-opener">
+                <p class="p-num">Chapter 1</p>
+                <p class="p-title">The Long Morning</p>
+              </div>
+              <p class="first">
+                The best hours are the ones nobody asks for. They arrive before the day has decided
+                what it wants from you, and they leave without ceremony, and what happens in them is
+                almost never what you planned.
+              </p>
+              <p data-indent="true">
+                I have kept the same desk for eleven years. It is not a good desk. One leg is
+                shorter than the others and I have never fixed it, because the small tilt reminds
+                me, every time I sit down, that the work is not going to be perfect either, and that
+                this has never once stopped anybody.
+              </p>
+              <p data-indent="true">
+                What I have learned about working slowly is that it is not slow. It only looks that
+                way from the outside. From inside it feels like the only speed at which anything
+                holds together.
+              </p>
+              <p data-indent="true">
+                There is a particular hour, somewhere between the first coffee and the second, when
+                the work stops feeling like a performance. Nothing on the page has changed. What has
+                changed is that you have stopped listening for applause.
+              </p>
+              <p data-indent="true">
+                The trick, if there is one, is to start before you are ready. Readiness is a story
+                you tell yourself about a future morning that will be calmer than this one, and it
+                will not be. The calm is something you make, badly at first, out of whatever the day
+                has left lying around.
+              </p>
+              <p data-indent="true">
+                I write the first sentence standing up. I do not know why this works and I have
+                stopped asking. Somewhere in the business of not sitting down the sentence loses its
+                self-consciousness, and by the time I take the chair there is something on the page
+                to argue with.
+              </p>
+              <p data-indent="true">
+                Everything after that is argument. You put a thing down, you read it back, you tell
+                it that it is not quite true, and you try again. Nine times out of ten the second
+                attempt is worse. The tenth is why anybody does this.
+              </p>
+              <p class="folio">7</p>
+            </div>
+
+            <div class="preview-page">
+              <p>
+                By eleven the light has moved across the desk and the day has started making its
+                claims. I stop where I am, mid-sentence if I can manage it, because a sentence left
+                open is a door left open, and tomorrow I will walk straight back through it.
+              </p>
+              <p data-indent="true">
+                None of this is a method. A method is something you can hand to somebody else, and I
+                have tried, and what they get is a description of a room they do not live in.
+              </p>
+              <p data-indent="true">
+                What I can hand over is smaller. Sit down before the day has an opinion. Write badly
+                on purpose for ten minutes. Stop while it is still going well.
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div></div>
+</div>
+</body>
+</html>

appstore/screenshots/src/frame-5.html

@@ -0,0 +1,105 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>Margin App Store frame 5</title>
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:[email protected]&family=Literata:opsz,[email protected],200..900&display=swap" rel="stylesheet" />
+<link rel="stylesheet" href="frame.css" />
+<link rel="stylesheet" href="app.css" />
+</head>
+<body>
+<div class="frame">
+  <p class="eyebrow">Yours</p>
+  <h1 class="headline">No account, no subscription.</h1>
+  <p class="support">Nothing to sign in to. Every piece is a plain file on your own Mac, yours to move, copy and back up.</p>
+
+  <div class="shot"><div class="shot__scale">
+    <div class="library">
+      <header class="library-head">
+        <span class="lights"><i></i><i></i><i></i></span>
+        <span class="icon-btn"><svg width="16" height="16" viewBox="0 0 24 24"><path d="M7 18a4 4 0 0 1 0-8 5 5 0 0 1 9.6-1.3A3.5 3.5 0 0 1 18 18H7z" /></svg></span>
+      </header>
+
+      <div class="shelf">
+        <span class="card card-action">
+          <svg width="20" height="20" viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>
+          <span>New project</span>
+        </span>
+        <span class="card card-action">
+          <svg width="20" height="20" viewBox="0 0 24 24"><path d="M12 3v10m0 0l-4-4m4 4l4-4M5 19h14" /></svg>
+          <span>Import EPUB</span>
+        </span>
+
+        <span class="card card-book">
+          <span class="card-title">The Quiet Hours</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited just now</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">Field Notes</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited yesterday</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">The Tuesday Letter</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited 3 days ago</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">Small Repairs</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited 6 days ago</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">A Year of Mondays</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited Aug 12, 2026</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">Nothing on These Walls</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited Aug 4, 2026</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">Twelve Openings</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited Jul 28, 2026</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">Rooms I Have Worked In</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited Jul 9, 2026</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">The Long Way Round</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited Jun 30, 2026</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">Working Slowly</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited Jun 2, 2026</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">Every Second Sentence</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited May 19, 2026</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">Letters I Did Not Send</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited Apr 27, 2026</span>
+        </span>
+        <span class="card card-book">
+          <span class="card-title">The Brick Wall</span>
+          <span class="card-author">Elena Marsh</span>
+          <span class="card-meta">Edited Mar 14, 2026</span>
+        </span>
+      </div>
+    </div>
+  </div></div>
+</div>
+</body>
+</html>

appstore/screenshots/src/frame.css

@@ -0,0 +1,111 @@
+/* Shared surface for every Mac App Store frame. Rendered at exactly 2560x1600,
+   so every length here is a real output pixel. */
+
+:root {
+  --paper: #fcfbf7;
+  --shell: #f1ece2;
+  --ink: #23201b;
+  --ink-soft: #6b6458;
+  --ink-faint: #9b9484;
+  --line-strong: #d6cfbd;
+
+  --font-ui: "Hanken Grotesk", ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-book: "Literata", Georgia, "Times New Roman", serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  width: 2560px;
+  height: 1600px;
+  overflow: hidden;
+  background:
+    radial-gradient(128% 92% at 50% -14%, var(--paper) 0%, rgba(252, 251, 247, 0) 62%),
+    var(--shell);
+  color: var(--ink);
+  font-family: var(--font-ui);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+.frame {
+  width: 2560px;
+  height: 1600px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  overflow: hidden;
+  padding: 120px 100px 116px;
+}
+
+.eyebrow {
+  margin: 0 0 24px;
+  font-size: 22px;
+  font-weight: 650;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--ink-faint);
+}
+
+.headline {
+  margin: 0;
+  font-family: var(--font-book);
+  font-size: 92px;
+  font-weight: 560;
+  line-height: 1.06;
+  letter-spacing: -0.022em;
+  color: var(--ink);
+  font-optical-sizing: auto;
+}
+
+.support {
+  margin: 30px 0 0;
+  max-width: 1700px;
+  font-size: 32px;
+  line-height: 1.5;
+  color: var(--ink-soft);
+  text-wrap: balance;
+}
+
+/* The app window sitting on the surface, never full bleed. The window itself is
+   live markup authored at the app's own 1440x900 (see app.css) and scaled up to
+   fill this well, so the type stays vector-sharp instead of being resampled. */
+.shot {
+  position: relative;
+  width: 1600px;
+  height: 1000px;
+  flex: none;
+  margin-top: 100px;
+  border-radius: 22px;
+  background: var(--paper);
+  overflow: hidden;
+  box-shadow:
+    0 2px 4px rgba(35, 32, 27, 0.06),
+    0 10px 26px -8px rgba(35, 32, 27, 0.14),
+    0 46px 96px -26px rgba(35, 32, 27, 0.36);
+}
+
+.shot__scale {
+  width: 1440px;
+  height: 900px;
+  transform: scale(1.1111111111);
+  transform-origin: 0 0;
+}
+
+.shot::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: 22px;
+  box-shadow: inset 0 0 0 1px var(--line-strong);
+  pointer-events: none;
+}

docs/publishing.md

@@ -0,0 +1,229 @@
+# Publishing
+
+Margin goes out through three doors, and they are not the same app.
+
+The **direct download** from [margin.73ai.org](https://margin.73ai.org) is the full one. It is not
+sandboxed, it updates itself, and nobody stands between it and the person using it. The **Homebrew
+cask** is the same file with a command instead of a browser. The **Mac App Store** copy is a
+sandboxed build with the updater taken out, because Apple requires both. It exists because most
+people will never download a `.dmg` from GitHub, and telling them to is how you end up with no
+users rather than principled ones.
+
+## Signing and notarization
+
+Every macOS bundle is signed with a Developer ID Application certificate and notarized by Apple
+before it is published. This is not optional any more: an unsigned bundle on a current macOS opens
+to "Apple could not verify this app is free of malware" with no obvious way past it, and the way
+past it that does exist teaches people to click through exactly the warning that is worth reading.
+
+The release workflow does it. `tauri-action` picks up `APPLE_CERTIFICATE` and
+`APPLE_CERTIFICATE_PASSWORD` (a base64 `.p12` and its password), signs with
+`APPLE_SIGNING_IDENTITY`, and notarizes with an App Store Connect API key: `APPLE_API_ISSUER`,
+`APPLE_API_KEY_ID`, and `APPLE_API_KEY_P8`, the last being the base64 of the `.p8` file. The key is
+used rather than an Apple ID and app-specific password because the same key does the App Store
+upload, so there is one credential to rotate instead of two.
+
+The step after the build is the one that matters. `codesign --verify` only says the signature is
+internally consistent; `spctl --assess` is what a person double-clicking the file actually meets,
+and it does not pass until `stapler` has attached the notarization ticket to the bundle. If that
+step goes green the download works on a machine that has never heard of Margin. If it is skipped
+because no key was configured, the workflow says so in a warning rather than shipping something
+that looks fine and is not.
+
+## Homebrew
+
+```
+brew tap priyanshujain/margin
+brew trust priyanshujain/margin
+brew install --cask margin
+```
+
+Homebrew 6 refuses to load a cask from a tap it has not been told to trust, and the error it raises
+instead says nothing about installing, so the trust line belongs in every set of instructions
+rather than being left for people to discover.
+
+The tap is [priyanshujain/homebrew-margin](https://github.com/priyanshujain/homebrew-margin) rather
+than upstream `homebrew-cask`, which has a notability bar Margin does not clear yet. What that
+costs is the two setup lines above, and the tap keeps working as a fallback if the cask ever does
+go upstream.
+
+The `homebrew` job at the end of the release workflow downloads the `.dmg` that was just published,
+takes its sha256, and rewrites the version and hash in `Casks/margin.rb`. It runs after the publish
+gate, so the cask can never point at a release that is still a draft. Without
+`HOMEBREW_TAP_DEPLOY_KEY` it warns and does nothing, which leaves the cask on the previous version
+rather than failing a release that otherwise succeeded.
+
+That secret is an SSH deploy key registered on the tap, not a personal access token. A token would
+carry the whole account; the deploy key reaches the tap and nothing else, so a leak from a release
+job cannot touch the app repositories.
+
+## Updates
+
+Both builds check on launch and from the same "Check for Updates…" menu item, and they ask
+different questions. The direct download asks the updater endpoint in `tauri.release.conf.json`,
+downloads the new bundle and restarts. The App Store copy asks `itunes.apple.com/lookup` which
+version is live under the bundle id, and if that is ahead of the one running it offers to open the
+store page, because an App Store app may not install code and would be rejected for trying.
+
+Which of the two runs is decided in `updates.rs` by the marker the config carries: the release
+overlay declares an `updater` plugin, the App Store overlay declares an `appstore` one. A
+`_MASReceipt` inside the bundle overrides both. That is the check that matters, because it means a
+bundle which came from the store cannot self-update even if it was built with the updater in it,
+and the decision does not rest on a config file alone.
+
+The prompt is a native alert rather than a window the app draws, and it appears once per version.
+"Later" means later, not later today: nothing is raised again until there is a new version to raise,
+and the menu item is there in the meantime. Whether to update is the reader's call, and an app that
+asks the same question at every launch is answering it for them.
+
+The store copy trails the direct one by however long review takes, so an App Store user being told
+they are up to date while GitHub has something newer is correct rather than a bug. Each channel
+compares against its own. Apple's lookup endpoint is also edge cached and can sit a few hours behind
+a release going live, which is what the timestamp on the request is for.
+
+## The Mac App Store
+
+Tauri has no App Store target, so `scripts/mas-package.sh` covers the distance between the `.app`
+and something App Store Connect will take. It embeds the provisioning profile, resolves the team
+identifier into the entitlements, signs, and wraps the result with `productbuild`.
+
+The order is load-bearing. The profile goes in before `codesign` runs, because the signature covers
+it. Tauri's own signing is switched off in this build for the same reason: it would sign a bundle
+with no profile in it. Nested code, if there ever is any, is signed before the bundle that contains
+it, and never with `--deep`, which would apply the app's entitlements to everything inside.
+
+`CFBundleVersion` comes from the workflow run number. App Store Connect refuses an upload whose
+build number it has seen before, so a rejected build cannot be resubmitted under the same one, and
+tying it to the run number means it goes up on its own.
+
+### The listing and TestFlight
+
+The store copy lives in `appstore/metadata` as one text file per field, and
+`scripts/appstore-listing.rb` pushes it. Keeping it in files rather than in the script means
+changing a description is a diff someone can read, and the listing is reviewable next to the code
+it describes. The script checks each field against Apple's length limit before sending, because
+Apple rejects an over-length field with a validation error that never mentions the number.
+
+The store version is taken from `tauri.conf.json`, the same place every other version in the repo
+comes from. This matters because App Store Connect rejects a build whose `CFBundleShortVersionString`
+does not match the version it is uploaded against, and a record created by `produce` starts life at
+1.0 regardless of what the app actually is.
+
+Release notes are the one field it will not write on a first version. They describe what changed
+since the last release, so Apple refuses them when there is no last release, and there would be
+nothing truthful to say.
+
+`scripts/testflight-setup.rb` does the beta side: the blurb testers read, the details Beta App
+Review asks for, and the two groups. None of it needs a build to exist, so it can all be in place
+before the first upload. Internal testers get builds within minutes of processing. External testers
+go through Beta App Review, which needs a contact phone number in
+`appstore/metadata/review_phone.txt`; without it the script says so and carries on, because
+internal testing does not need it.
+
+`scripts/appstore-review-detail.rb` writes the store submission's App Review Information: the same
+contact details and the notes in `appstore/metadata/review_notes.txt`. That is a different record
+from the TestFlight one, and the two do not share anything. An explanation that only went to
+TestFlight is invisible both to the reviewer looking at the store submission and to the automated
+check that runs before a human sees it at all, which is how the first submission was rejected.
+
+`scripts/appstore-compliance.rb` answers the age rating questionnaire and declares App Privacy.
+Every content answer is NONE and the privacy answer is that nothing is collected, which is true:
+there is no telemetry, no account and no server. The Drive backup sends bytes to the account of the
+person who switched it on, which is not the developer collecting anything. If that ever stops being
+true, that script is the thing that has to change with it.
+
+`scripts/appstore-screenshots.rb` uploads the frames in `appstore/screenshots`, replacing whatever
+is already attached rather than adding to it, so a listing cannot quietly accumulate ten frames
+across five runs. How the frames themselves are built is in
+[appstore/screenshots/README.md](../appstore/screenshots/README.md); they are a CSS rebuild of the
+app rendered at 2560x1600, not a screen capture, because the only Macs to hand have 1x displays and
+an upscaled capture looks like one.
+
+Screenshots gate submitting for review, and nothing else: not the app record, not a build upload,
+and not either tier of TestFlight.
+
+`scripts/mas-upload-local.sh` builds, signs, packages and uploads from a developer's own machine
+rather than CI, using a keychain that exists only for the length of the run. `scripts/testflight-release.rb`
+then waits for Apple to finish processing, assigns the build to the external group, submits it for
+beta app review, and attaches it to the store version.
+
+That last step is easy to miss and does not announce itself. Assigning a build to TestFlight and
+attaching it to the store version are separate operations, and a Mac listing takes its app icon
+from the attached build. Until it is attached, App Store Connect shows the listing with no icon and
+does not say why.
+
+The Apple ID this is driven with can see more than one App Store Connect team, and the other one
+belongs to somebody else, so both scripts pin `FASTLANE_ITC_TEAM_ID` rather than letting spaceship
+choose. Do not remove that.
+
+### What the sandbox costs
+
+The App Store build declares four entitlements, in `src-tauri/entitlements.mas.plist`, and each one
+is there for a reason worth being able to defend in review. `network.client` is the Google Drive
+API and the version lookup above. `network.server` is the loopback listener the Drive OAuth flow
+redirects to, which is the only installed-app flow Google still supports.
+
+`network.server` is not a theoretical risk. An automated check rejects any submission that declares
+it, before review, unless the App Review Information says what listens and why, so
+`appstore/metadata/review_notes.txt` explains the loopback bind first and at length: that it is on
+127.0.0.1 and never a routable interface, that it lives only for the duration of a sign-in, that it
+times out, and how to reach the feature in the app. A rejection on this also has to be answered in
+Resolution Center by hand, since that is not in the App Store Connect API.
+
+`files.user-selected.read-write` covers EPUB import and PDF and EPUB export, all of which go
+through a panel, so the app only ever reaches the one file that was pointed at. The library needs
+nothing: it lives in the container.
+
+Three things are different in that build, and all three are Apple's rules rather than choices:
+
+The updater is gone. `lib.rs` registers the updater plugin only when the config declares it, and
+only `tauri.release.conf.json` does, so building against `tauri.appstore.conf.json` leaves it out
+by construction. The menu item stays, pointed at the App Store instead, which is what the previous
+section is about.
+
+The library moves. Sandboxed, `app_data_dir()` resolves inside
+`~/Library/Containers/studio.margin.app`, not `~/Library/Application Support`. Someone who switches
+from the direct download to the App Store copy sees an empty library. There is no migration and no
+plan for one; if that ever matters to a real person it is a first-run import, not a sync.
+
+System spelling additions are gone. `proofing.rs` reads `~/Library/Spelling/LocalDictionary` to
+pick up words added elsewhere on the Mac, and the sandbox denies it. The read already fails
+quietly, so the app is fine, it just knows fewer of your words.
+
+## Certificates
+
+Three, and they do different jobs. **Developer ID Application** signs the direct download and is
+what notarization checks. **Mac App Distribution** signs the App Store bundle. **Mac Installer
+Distribution** signs the `.pkg` that wraps it. A Developer ID certificate is not accepted by the
+App Store and a Mac App Distribution one will not notarize, so there is no combining them.
+
+`scripts/apple-provision.rb` creates all three, registers the App ID, and makes the provisioning
+profile, driving the Developer Portal through fastlane's spaceship rather than the website. It is
+find-or-create throughout, so rerunning it is safe. That matters most for the Developer ID
+certificate: an account may hold only a handful, they cannot be un-revoked, and every copy of the
+app already signed by one stops verifying if it goes away.
+
+It has to be run by a person, not by CI or an agent, because it prompts for the Apple ID password
+and a two-factor code:
+
+```
+[email protected] BUNDLE_ID=studio.margin.app APP_NAME=Margin ruby scripts/apple-provision.rb
+```
+
+The private keys live in `~/.margin-signing` and are never sent to Apple, the way the updater key
+lives in `~/.tauri`. They were generated with `openssl` up front so that Apple only ever sees a
+certificate signing request, and so the `.p12` that CI uses can be assembled locally. Each `.p12`
+carries Apple's intermediate certificate alongside the leaf, because a fresh CI keychain holding
+only the leaf fails to build a chain to the root and `codesign` stops with an error that does not
+say so.
+
+`scripts/apple-secrets.sh` then pipes all of it into the repository's Actions secrets without
+printing any of it. The one secret it cannot produce is `HOMEBREW_TAP_DEPLOY_KEY`, which is set up
+alongside the tap rather than by anything Apple issued.
+
+One step has no API and has to be done on the website: an App Store Connect API key, under Users
+and Access, Integrations. The `.p8` downloads exactly once. Put it at `~/.margin-signing/AuthKey.p8`
+with its key ID and issuer ID in `AuthKey.env` beside it, and rerun the secrets script.
+
+Certificates expire after five years and are replaceable; the keys are not backed up anywhere else,
+so back them up somewhere that is not this machine.

justfile

@@ -0,0 +1,42 @@
+set shell := ["bash", "-euo", "pipefail", "-c"]
+
+app := "Margin"
+bundle := "src-tauri/target/release/bundle/macos/" + app + ".app"
+
+default:
+    @just --list
+
+dev:
+    pnpm tauri dev
+
+build:
+    pnpm install --frozen-lockfile
+    APPLE_SIGNING_IDENTITY=- pnpm tauri build --bundles app
+    codesign --verify --deep --strict "{{bundle}}"
+
+install: build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ -w /Applications ]; then
+      dir=/Applications
+    else
+      dir="$HOME/Applications"
+      mkdir -p "$dir"
+    fi
+    dest="$dir/{{app}}.app"
+    if pgrep -x margin-app > /dev/null; then
+      osascript -e 'tell application id "studio.margin.app" to quit'
+      for _ in {1..40}; do
+        pgrep -x margin-app > /dev/null || break
+        sleep 0.25
+      done
+      if pgrep -x margin-app > /dev/null; then
+        echo "Margin is still running. Quit it and run just install again." >&2
+        exit 1
+      fi
+    fi
+    rm -rf "$dest"
+    ditto "{{bundle}}" "$dest"
+    codesign --verify --deep --strict "$dest"
+    echo "Installed {{app}} to $dest"
+    open "$dest"

package.json

@@ -1,26 +1,31 @@
 {
   "name": "margin-app",
   "private": true,
-  "version": "0.1.14",
+  "version": "0.1.17",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
     "preview": "vite preview",
     "tauri": "tauri",
-    "dmg": "tauri build --bundles dmg"
+    "dmg": "tauri build --bundles dmg",
+    "fonts:sync": "node node_modules/margin-shared/bin/sync-fonts.mjs .",
+    "fonts:check": "node node_modules/margin-shared/bin/sync-fonts.mjs . --check"
   },
   "dependencies": {
     "@tauri-apps/api": "^2",
+    "@tauri-apps/plugin-clipboard-manager": "2.3.3",
     "@tauri-apps/plugin-dialog": "^2.7.1",
     "@tauri-apps/plugin-opener": "^2",
     "@tauri-apps/plugin-process": "^2",
     "@tauri-apps/plugin-updater": "^2",
     "@tiptap/core": "^3.27.1",
+    "@tiptap/extension-list": "3.27.1",
     "@tiptap/extension-placeholder": "^3.27.1",
     "@tiptap/pm": "^3.27.1",
     "@tiptap/react": "^3.27.1",
     "@tiptap/starter-kit": "^3.27.1",
+    "margin-shared": "file:./shared",
     "pdfjs-dist": "^6.0.227",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
@@ -33,5 +38,7 @@
     "@vitejs/plugin-react": "^4.6.0",
     "typescript": "~5.8.3",
     "vite": "^7.0.4"
-  }
+  },
+  "description": "A calm, offline writing studio for authors",
+  "license": "SEE LICENSE IN LICENSE"
 }

pnpm-lock.yaml

@@ -11,6 +11,9 @@ importers:
       '@tauri-apps/api':
         specifier: ^2
         version: 2.11.1
+      '@tauri-apps/plugin-clipboard-manager':
+        specifier: 2.3.3
+        version: 2.3.3
       '@tauri-apps/plugin-dialog':
         specifier: ^2.7.1
         version: 2.7.1
@@ -26,6 +29,9 @@ importers:
       '@tiptap/core':
         specifier: ^3.27.1
         version: 3.27.1(@tiptap/[email protected])
+      '@tiptap/extension-list':
+        specifier: 3.27.1
+        version: 3.27.1(@tiptap/[email protected](@tiptap/[email protected]))(@tiptap/[email protected])
       '@tiptap/extension-placeholder':
         specifier: ^3.27.1
         version: 3.27.1(@tiptap/[email protected](@tiptap/[email protected](@tiptap/[email protected]))(@tiptap/[email protected]))
@@ -38,6 +44,9 @@ importers:
       '@tiptap/starter-kit':
         specifier: ^3.27.1
         version: 3.27.1
+      margin-shared:
+        specifier: file:./shared
+        version: file:shared
       pdfjs-dist:
         specifier: ^6.0.227
         version: 6.0.227
@@ -537,6 +546,9 @@ packages:
   '@tauri-apps/[email protected]':
     resolution: {integrity: sha512-M2FPuYND2m+wh5hfW9ZpSdxMPdEJovPBWwoHJmwUpysTYNHaOkVFN419m/K0LIgjb/7KU2vBgsUepJWugQCvAA==}
 
+  '@tauri-apps/[email protected]':
+    resolution: {integrity: sha512-DeyFHa3wynpyoqTDikDEDGTJIq4LQ5USfolQGRmGIWT6JMADyxZBTDa5cAdT3tDg73rUXufPaCwN7aXBos4OnQ==}
+
   '@tauri-apps/[email protected]':
     resolution: {integrity: sha512-BxpaM8bsCoXs3wd4WKYhas/G1gs7+r7B+e4WnyRk2GEoVOouJB1hoL6E6YLXZDXbYci6VFdrNnobQwd2uVL4ew==}
     engines: {node: '>= 10'}
@@ -608,6 +620,9 @@ packages:
     engines: {node: '>= 10'}
     hasBin: true
 
+  '@tauri-apps/[email protected]':
+    resolution: {integrity: sha512-KnyoTs9gj1yEgDkSPUNjOIOHjJTr5wk8IWcYMOWxYTIJCip6QwlyPW8u2X+6bd6kHM4fAdZNpxoal0gy/TwJbg==}
+
   '@tauri-apps/[email protected]':
     resolution: {integrity: sha512-OK1UBXYt+ojcmxMktzzuyonYIFta8CmAASpX+CA+DTGK24KlHjhYI6x2iOJ/TjZF4N7/ACK1oFmEOjIY9IhzOQ==}
 
@@ -887,6 +902,10 @@ packages:
   [email protected]:
     resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
 
+  margin-shared@file:shared:
+    resolution: {directory: shared, type: directory}
+    hasBin: true
+
   [email protected]:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
@@ -1424,6 +1443,8 @@ snapshots:
 
   '@tauri-apps/[email protected]': {}
 
+  '@tauri-apps/[email protected]': {}
+
   '@tauri-apps/[email protected]':
     optional: true
 
@@ -1471,6 +1492,10 @@ snapshots:
       '@tauri-apps/cli-win32-ia32-msvc': 2.11.3
       '@tauri-apps/cli-win32-x64-msvc': 2.11.3
 
+  '@tauri-apps/[email protected]':
+    dependencies:
+      '@tauri-apps/api': 2.12.1
+
   '@tauri-apps/[email protected]':
     dependencies:
       '@tauri-apps/api': 2.11.1
@@ -1784,6 +1809,8 @@ snapshots:
     dependencies:
       yallist: 3.1.1
 
+  margin-shared@file:shared: {}
+
   [email protected]: {}
 
   [email protected]: {}

scripts/apple-provision.rb

@@ -0,0 +1,189 @@
+#!/usr/bin/env ruby
+# Create the Apple Developer resources a release needs, and turn them into files CI can use.
+#
+# Everything here is find-or-create, so running it twice does nothing the second time. That matters
+# most for the Developer ID certificate: an account may hold only a handful, they cannot be
+# un-revoked, and every copy of the app already signed by one stops verifying if it goes away.
+#
+# The private keys are never sent to Apple and never leave ~/.margin-signing. Apple only ever sees
+# the certificate signing requests, which is the whole point of generating them with openssl up
+# front rather than letting a tool make its own.
+#
+#   BUNDLE_ID=studio.margin.app APP_NAME=Margin ruby scripts/apple-provision.rb
+#
+# Run it yourself rather than through an agent: the Apple ID password and the two-factor code are
+# prompted for on the terminal.
+begin
+  require "spaceship"
+rescue LoadError
+  # Homebrew vendors fastlane's gems under libexec instead of putting them on the default gem
+  # path, so spaceship is not requirable until that directory is added to it.
+  libexec = Dir["/opt/homebrew/Cellar/fastlane/*/libexec", "/usr/local/Cellar/fastlane/*/libexec"].max
+  abort "spaceship is not installed. `brew install fastlane` and rerun." unless libexec
+  ENV["GEM_PATH"] = [libexec, ENV["GEM_PATH"]].compact.join(":")
+  Gem.clear_paths
+  require "spaceship"
+end
+
+require "openssl"
+require "fileutils"
+require "securerandom"
+require "net/http"
+require "tmpdir"
+
+# Listing profiles otherwise goes through developerservices2.apple.com, Apple's Xcode-only
+# endpoint, which rejects a plain spaceship session with "Please update to Xcode 7.3 or later"
+# no matter how current Xcode actually is. This routes it back to the ordinary portal API.
+ENV["SPACESHIP_AVOID_XCODE_API"] = "1"
+
+DIR = File.expand_path("~/.margin-signing")
+BUNDLE_ID = ENV.fetch("BUNDLE_ID", "studio.margin.app")
+APP_NAME  = ENV.fetch("APP_NAME", "Margin")
+EMAIL     = ENV["APPLE_EMAIL"]
+
+# Apple's intermediates. codesign builds a chain from the leaf up, so a .p12 holding only the leaf
+# and its key fails on a fresh CI keychain with "unable to build chain to self-signed root".
+INTERMEDIATES = {
+  "AppleWWDRCAG3" => "https://www.apple.com/certificateauthority/AppleWWDRCAG3.cer",
+  "DeveloperIDG2CA" => "https://www.apple.com/certificateauthority/DeveloperIDG2CA.cer",
+}
+
+CERTS = [
+  { key: "developer-id",       klass: Spaceship::Portal::Certificate::DeveloperIdApplication,
+    label: "Developer ID Application (direct download, notarized)",       ca: "DeveloperIDG2CA" },
+  { key: "apple-distribution", klass: Spaceship::Portal::Certificate::MacAppDistribution,
+    label: "Mac App Distribution (App Store .app)",                       ca: "AppleWWDRCAG3" },
+  { key: "mac-installer",      klass: Spaceship::Portal::Certificate::MacInstallerDistribution,
+    label: "Mac Installer Distribution (App Store .pkg)",                 ca: "AppleWWDRCAG3" },
+]
+
+def common_name(cert)
+  cert.subject.to_a.find { |n, _, _| n == "CN" }&.at(1)
+end
+
+def fetch_intermediate(name)
+  path = File.join(DIR, "#{name}.cer")
+  unless File.exist?(path)
+    uri = URI(INTERMEDIATES.fetch(name))
+    File.binwrite(path, Net::HTTP.get(uri))
+  end
+  OpenSSL::X509::Certificate.new(File.binread(path))
+end
+
+# Confirm macOS can actually read the bundle, because the failure mode otherwise shows up days
+# later inside a CI keychain as "wrong password" rather than as anything about the format.
+def importable?(p12_path, password)
+  keychain = File.join(Dir.tmpdir, "margin-p12-check-#{SecureRandom.hex(4)}.keychain-db")
+  system("security", "create-keychain", "-p", "check", keychain, out: File::NULL, err: File::NULL)
+  system("security", "unlock-keychain", "-p", "check", keychain, out: File::NULL, err: File::NULL)
+  ok = system("security", "import", p12_path, "-k", keychain, "-P", password,
+              out: File::NULL, err: File::NULL)
+  system("security", "delete-keychain", keychain, out: File::NULL, err: File::NULL)
+  ok
+end
+
+# Returns nil on success, or a sentence saying what went wrong.
+def write_p12(spec, cert)
+  key_path = File.join(DIR, "#{spec[:key]}.key")
+  unless cert.check_private_key(OpenSSL::PKey::RSA.new(File.read(key_path)))
+    return "the issued certificate does not match the local private key, so Apple issued it " \
+           "against a different CSR. Revoke it in the portal and rerun."
+  end
+
+  password = SecureRandom.hex(24)
+  p12_path = File.join(DIR, "#{spec[:key]}.p12")
+
+  built = Dir.mktmpdir do |tmp|
+    leaf = File.join(tmp, "leaf.pem")
+    ca = File.join(tmp, "ca.pem")
+    File.write(leaf, cert.to_pem)
+    File.write(ca, fetch_intermediate(spec[:ca]).to_pem)
+
+    # Ruby links OpenSSL 3, whose PKCS12 default MAC is SHA-256. Apple's Security framework reads
+    # only the legacy SHA-1 MAC and reports the mismatch as a wrong password, so the bundle has to
+    # come from the LibreSSL at /usr/bin/openssl, which still writes the older format. The password
+    # goes through the environment rather than argv so it stays out of the process list.
+    system({ "P12PASS" => password }, "/usr/bin/openssl", "pkcs12", "-export",
+           "-inkey", key_path, "-in", leaf, "-certfile", ca,
+           "-name", common_name(cert), "-passout", "env:P12PASS", "-out", p12_path,
+           out: File::NULL, err: File::NULL)
+  end
+
+  return "/usr/bin/openssl could not build the bundle." unless built
+  return "macOS refused to import the bundle that was just built." unless importable?(p12_path, password)
+
+  File.write(File.join(DIR, "#{spec[:key]}.p12.pass"), password)
+  File.chmod(0o600, p12_path, File.join(DIR, "#{spec[:key]}.p12.pass"))
+  nil
+end
+
+FileUtils.mkdir_p(DIR)
+Spaceship::Portal.login(EMAIL)
+Spaceship::Portal.select_team
+team_id = Spaceship::Portal.client.team_id
+puts "Team ID: #{team_id}"
+puts
+
+identities = {}
+
+CERTS.each do |spec|
+  existing = spec[:klass].all.select { |c| c.status == "Issued" }
+  cert_obj = existing.first
+
+  if cert_obj
+    puts "#{spec[:label]}: already exists (#{cert_obj.id}), not creating another."
+  else
+    csr = File.read(File.join(DIR, "#{spec[:key]}.csr"))
+    cert_obj = spec[:klass].create!(csr: csr)
+    puts "#{spec[:label]}: created (#{cert_obj.id})."
+  end
+
+  x509 = cert_obj.download
+  File.binwrite(File.join(DIR, "#{spec[:key]}.cer"), x509.to_der)
+
+  identities[spec[:key]] = common_name(x509)
+  puts "  identity: #{common_name(x509)}"
+
+  problem = write_p12(spec, x509)
+  puts(problem ? "  no p12: #{problem}" : "  wrote #{spec[:key]}.p12")
+  puts
+end
+
+app = Spaceship::Portal::App.find(BUNDLE_ID, mac: true)
+if app
+  puts "App ID #{BUNDLE_ID}: already registered."
+else
+  app = Spaceship::Portal::App.create!(bundle_id: BUNDLE_ID, name: APP_NAME, mac: true)
+  puts "App ID #{BUNDLE_ID}: registered."
+end
+
+profile_name = "#{APP_NAME} App Store"
+profile = Spaceship::Portal::ProvisioningProfile::AppStore.all(mac: true).find do |p|
+  p.app.bundle_id == BUNDLE_ID && p.status == "Active"
+end
+
+if profile
+  puts "Provisioning profile: reusing #{profile.name}."
+else
+  mas_cert = Spaceship::Portal::Certificate::MacAppDistribution.all.first
+  profile = Spaceship::Portal::ProvisioningProfile::AppStore.create!(
+    name: profile_name, bundle_id: BUNDLE_ID, certificate: mas_cert, mac: true
+  )
+  puts "Provisioning profile: created #{profile.name}."
+end
+
+profile_path = File.join(DIR, "#{BUNDLE_ID}.provisionprofile")
+File.binwrite(profile_path, profile.download)
+File.chmod(0o600, profile_path)
+
+File.write(File.join(DIR, "#{BUNDLE_ID}.env"), <<~ENV)
+  APPLE_TEAM_ID="#{team_id}"
+  APPLE_SIGNING_IDENTITY="#{identities['developer-id']}"
+  MAS_APP_IDENTITY="#{identities['apple-distribution']}"
+  MAS_INSTALLER_IDENTITY="#{identities['mac-installer']}"
+ENV
+
+puts
+puts "Wrote #{profile_path} and #{BUNDLE_ID}.env into #{DIR}."
+puts "Still to do by hand, because Apple has no API for it: create an App Store Connect API key"
+puts "(Users and Access, Integrations) and save the .p8 as #{DIR}/AuthKey.p8."

scripts/apple-secrets.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Push everything apple-provision.rb produced into this repo's GitHub Actions secrets.
+#
+# Values are piped from the files straight into `gh`, never echoed, so running this in a shared
+# terminal or through an agent does not leak a signing key into the scrollback.
+set -euo pipefail
+
+DIR="${MARGIN_SIGNING_DIR:-$HOME/.margin-signing}"
+BUNDLE_ID="${BUNDLE_ID:-studio.margin.app}"
+REPO="${REPO:-priyanshujain/margin}"
+ENV_FILE="$DIR/$BUNDLE_ID.env"
+
+[ -f "$ENV_FILE" ] || { echo "apple-secrets: $ENV_FILE is missing; run apple-provision.rb first." >&2; exit 1; }
+# shellcheck source=/dev/null
+set -a; . "$ENV_FILE"; set +a
+
+set_plain() {
+  printf '%s' "$2" | gh secret set "$1" --repo "$REPO" --body -
+  echo "  set $1"
+}
+
+set_b64() {
+  [ -f "$2" ] || { echo "  skipped $1 ($2 is missing)"; return; }
+  base64 -i "$2" | tr -d '\n' | gh secret set "$1" --repo "$REPO" --body -
+  echo "  set $1"
+}
+
+set_file() {
+  [ -f "$2" ] || { echo "  skipped $1 ($2 is missing)"; return; }
+  gh secret set "$1" --repo "$REPO" < "$2"
+  echo "  set $1"
+}
+
+echo "Signing identities and team:"
+set_plain APPLE_TEAM_ID "$APPLE_TEAM_ID"
+set_plain APPLE_SIGNING_IDENTITY "$APPLE_SIGNING_IDENTITY"
+set_plain MAS_APP_IDENTITY "$MAS_APP_IDENTITY"
+set_plain MAS_INSTALLER_IDENTITY "$MAS_INSTALLER_IDENTITY"
+
+echo "Certificates:"
+set_b64  APPLE_CERTIFICATE "$DIR/developer-id.p12"
+set_file APPLE_CERTIFICATE_PASSWORD "$DIR/developer-id.p12.pass"
+set_b64  MAS_APP_CERTIFICATE "$DIR/apple-distribution.p12"
+set_file MAS_APP_CERTIFICATE_PASSWORD "$DIR/apple-distribution.p12.pass"
+set_b64  MAS_INSTALLER_CERTIFICATE "$DIR/mac-installer.p12"
+set_file MAS_INSTALLER_CERTIFICATE_PASSWORD "$DIR/mac-installer.p12.pass"
+set_b64  MAS_PROVISION_PROFILE "$DIR/$BUNDLE_ID.provisionprofile"
+
+echo "App Store Connect API key:"
+if [ -f "$DIR/AuthKey.p8" ] && [ -f "$DIR/AuthKey.env" ]; then
+  # shellcheck source=/dev/null
+  set -a; . "$DIR/AuthKey.env"; set +a
+  # An empty value here would be accepted by `gh` and then fail notarization as an auth error that
+  # says nothing about a missing issuer, so refuse it at the point the mistake is still visible.
+  if [ -z "${APPLE_API_KEY_ID:-}" ] || [ -z "${APPLE_API_ISSUER:-}" ]; then
+    echo "  refused: AuthKey.env is missing APPLE_API_KEY_ID or APPLE_API_ISSUER." >&2
+    exit 1
+  fi
+  set_plain APPLE_API_KEY_ID "$APPLE_API_KEY_ID"
+  set_plain APPLE_API_ISSUER "$APPLE_API_ISSUER"
+  set_b64   APPLE_API_KEY_P8 "$DIR/AuthKey.p8"
+else
+  echo "  skipped: put the .p8 at $DIR/AuthKey.p8 and write $DIR/AuthKey.env with"
+  echo "           APPLE_API_KEY_ID= and APPLE_API_ISSUER=, then rerun."
+fi
+
+echo
+echo "Not handled here: HOMEBREW_TAP_DEPLOY_KEY, an SSH deploy key on the tap rather than"
+echo "anything Apple issued."

scripts/appstore-compliance.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# Declare the age rating and set pricing. These are the two things App Store Connect will not let a
+# submission through without, and neither has anything to do with the copy in appstore-listing.rb.
+#
+#   [email protected] ruby scripts/appstore-compliance.rb
+#
+# Every content answer here is NONE because Margin is an editor for words the person using it wrote
+# themselves. It ships no media, has no feed, no other users, and no in-app browser. If any of that
+# ever stops being true, this file is the thing that has to change with it.
+begin
+  require "spaceship"
+rescue LoadError
+  libexec = Dir["/opt/homebrew/Cellar/fastlane/*/libexec", "/usr/local/Cellar/fastlane/*/libexec"].max
+  abort "spaceship is not installed. `brew install fastlane` and rerun." unless libexec
+  ENV["GEM_PATH"] = [libexec, ENV["GEM_PATH"]].compact.join(":")
+  Gem.clear_paths
+  require "spaceship"
+end
+
+BUNDLE_ID = ENV.fetch("BUNDLE_ID", "studio.margin.app")
+ENV["FASTLANE_ITC_TEAM_ID"] = ENV.fetch("FASTLANE_ITC_TEAM_ID", "129377371")
+
+NONE = Spaceship::ConnectAPI::AgeRatingDeclaration::Rating::NONE
+
+Spaceship::ConnectAPI.login(ENV["APPLE_EMAIL"], nil, use_portal: false, use_tunes: true)
+
+app = Spaceship::ConnectAPI::App.find(BUNDLE_ID)
+abort "No app for #{BUNDLE_ID}." unless app
+puts "#{app.name} (#{app.id})"
+
+info = app.fetch_edit_app_info
+abort "No editable app info." unless info
+
+declaration = info.fetch_age_rating_declaration
+abort "No age rating declaration to write to." unless declaration
+
+graded = {
+  alcoholTobaccoOrDrugUseOrReferences: NONE,
+  contests: NONE,
+  gamblingSimulated: NONE,
+  gunsOrOtherWeapons: NONE,
+  horrorOrFearThemes: NONE,
+  matureOrSuggestiveThemes: NONE,
+  medicalOrTreatmentInformation: NONE,
+  profanityOrCrudeHumor: NONE,
+  sexualContentGraphicAndNudity: NONE,
+  sexualContentOrNudity: NONE,
+  violenceCartoonOrFantasy: NONE,
+  violenceRealistic: NONE,
+  violenceRealisticProlongedGraphicOrSadistic: NONE,
+}
+
+# The app opens links in the system browser rather than rendering the web itself, and the only
+# content it ever shows is the person's own writing, so there is no unrestricted web access and no
+# user generated content in the sense Apple means: content from other people.
+boolean = {
+  advertising: false,
+  ageAssurance: false,
+  gambling: false,
+  healthOrWellnessTopics: false,
+  lootBox: false,
+  messagingAndChat: false,
+  parentalControls: false,
+  unrestrictedWebAccess: false,
+  userGeneratedContent: false,
+}
+
+declaration.update(attributes: graded.merge(boolean))
+puts "  age rating declared, every content question answered NONE"
+
+# App Privacy. Margin has no telemetry, no accounts and no server of its own, so nothing is
+# collected. The Google Drive backup is the one thing that sends bytes anywhere, and it sends them
+# to the account of the person who turned it on, which is not the developer collecting anything.
+usages = Spaceship::ConnectAPI::AppDataUsage.all(
+  app_id: app.id, includes: "category,grouping,purpose,dataProtection"
+)
+
+if usages.any?(&:is_not_collected?)
+  puts "  privacy already declared as data not collected"
+else
+  Spaceship::ConnectAPI::AppDataUsage.create(app_id: app.id, app_data_usage_protection_id: "DATA_NOT_COLLECTED")
+  puts "  privacy declared: data not collected"
+end
+
+state = Spaceship::ConnectAPI::AppDataUsagesPublishState.get(app_id: app.id)
+if state.published
+  puts "  privacy declaration already published"
+else
+  state.publish!
+  puts "  privacy declaration published"
+end
+
+# Free, everywhere. Territory availability is left alone: the default is all of them.
+app.update(attributes: { pricing: [] }) if ENV["SET_PRICING"]
+puts "  pricing left as configured (the app is free, which is the default for a new record)"

scripts/appstore-listing.rb

@@ -0,0 +1,122 @@
+#!/usr/bin/env ruby
+# Push the listing copy in appstore/metadata to App Store Connect.
+#
+# The copy lives in text files rather than in here so that changing a description is a diff someone
+# can read, and so the store listing is reviewable in the same place as the code it describes.
+#
+#   [email protected] ruby scripts/appstore-listing.rb
+#
+# Run it yourself: the Apple ID login prompts for a two-factor code the first time each month.
+begin
+  require "spaceship"
+rescue LoadError
+  libexec = Dir["/opt/homebrew/Cellar/fastlane/*/libexec", "/usr/local/Cellar/fastlane/*/libexec"].max
+  abort "spaceship is not installed. `brew install fastlane` and rerun." unless libexec
+  ENV["GEM_PATH"] = [libexec, ENV["GEM_PATH"]].compact.join(":")
+  Gem.clear_paths
+  require "spaceship"
+end
+
+require "json"
+
+DIR = ENV.fetch("METADATA_DIR", "appstore/metadata")
+LOCALE = "en-US"
+BUNDLE_ID = ENV.fetch("BUNDLE_ID", "studio.margin.app")
+
+# This Apple ID can see more than one App Store Connect team, and the wrong one belongs to someone
+# else entirely. Pin it rather than letting spaceship pick.
+ITC_TEAM_ID = ENV.fetch("FASTLANE_ITC_TEAM_ID", "129377371")
+ENV["FASTLANE_ITC_TEAM_ID"] = ITC_TEAM_ID
+
+# Apple rejects an over-length field with a validation error that does not name the limit, so the
+# check belongs here where the number is visible.
+LIMITS = {
+  "name" => 30, "subtitle" => 30, "keywords" => 100,
+  "promotional_text" => 170, "description" => 4000,
+}.freeze
+
+def field(name, localized: true)
+  path = localized ? File.join(DIR, LOCALE, "#{name}.txt") : File.join(DIR, "#{name}.txt")
+  return nil unless File.exist?(path)
+
+  value = File.read(path).strip
+  limit = LIMITS[name]
+  abort "#{name} is #{value.length} characters, over Apple's limit of #{limit}." if limit && value.length > limit
+  value
+end
+
+Spaceship::ConnectAPI.login(ENV["APPLE_EMAIL"], nil, use_portal: false, use_tunes: true)
+
+app = Spaceship::ConnectAPI::App.find(BUNDLE_ID)
+abort "No app on team #{ITC_TEAM_ID} for #{BUNDLE_ID}. Create it with produce first." unless app
+puts "#{app.name} (#{app.id})"
+
+info = app.fetch_edit_app_info
+abort "No editable app info; the listing may already be in review." unless info
+
+localization = info.get_app_info_localizations.find { |l| l.locale == LOCALE }
+localization ||= info.create_app_info_localization(attributes: { locale: LOCALE })
+# The name is the one field a person is likely to change by hand in App Store Connect, and losing
+# somebody's naming decision to a stale text file is not a good trade. So divergence is reported
+# and the live value kept, rather than overwritten.
+attributes = { subtitle: field("subtitle"), privacyPolicyUrl: field("privacy_url") }
+wanted_name = field("name")
+if wanted_name && localization.name && wanted_name != localization.name
+  puts "  keeping the name set in App Store Connect (#{localization.name.inspect});"
+  puts "  #{DIR}/#{LOCALE}/name.txt says #{wanted_name.inspect}. Update the file to match, or pass"
+  puts "  FORCE_NAME=1 to make the file win."
+  attributes[:name] = wanted_name if ENV["FORCE_NAME"]
+else
+  attributes[:name] = wanted_name
+end
+
+localization.update(attributes: attributes)
+puts "  subtitle and privacy policy set"
+
+category = field("primary_category", localized: false)
+if category
+  info.update_categories(category_id_map: { primary_category_id: category })
+  puts "  primary category set to #{category}"
+end
+
+version = app.get_edit_app_store_version(platform: Spaceship::ConnectAPI::Platform::MAC_OS)
+abort "No editable macOS version to write to." unless version
+
+# The store version has to match the CFBundleShortVersionString of the build that will be uploaded
+# against it, and that comes from tauri.conf.json like every other version in the repo. Left alone,
+# a record created by `produce` sits at 1.0 and rejects the first build with a version mismatch.
+app_version = JSON.parse(File.read("src-tauri/tauri.conf.json"))["version"]
+if version.version_string != app_version
+  version.update(attributes: { versionString: app_version })
+  puts "  version corrected from #{version.version_string} to #{app_version}"
+  version = app.get_edit_app_store_version(platform: Spaceship::ConnectAPI::Platform::MAC_OS)
+end
+
+version_localization = version.get_app_store_version_localizations.find { |l| l.locale == LOCALE }
+version_localization ||= version.create_app_store_version_localization(attributes: { locale: LOCALE })
+attributes = {
+  description: field("description"),
+  keywords: field("keywords"),
+  promotionalText: field("promotional_text"),
+  supportUrl: field("support_url"),
+  marketingUrl: field("marketing_url"),
+}
+
+# Release notes describe what changed since the last release, so Apple refuses them on a first
+# version and there is nothing truthful to put there anyway.
+if app.get_live_app_store_version(platform: Spaceship::ConnectAPI::Platform::MAC_OS)
+  attributes[:whatsNew] = field("release_notes")
+else
+  puts "  skipping release notes: nothing has shipped yet for them to be relative to"
+end
+
+version_localization.update(attributes: attributes)
+puts "  description, keywords and links set on version #{version.version_string}"
+
+copyright = field("copyright", localized: false)
+version.update(attributes: { copyright: copyright }) if copyright
+puts "  copyright set to #{copyright}" if copyright
+
+puts
+puts "Screenshots are not set here. They are required to submit for review, but not to upload a"
+puts "build or to run either tier of TestFlight."

scripts/appstore-review-detail.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env ruby
+# Push the App Review Information for the store submission: who to contact, and the notes that
+# explain anything a reviewer would otherwise have to guess at.
+#
+#   [email protected] ruby scripts/appstore-review-detail.rb
+#
+# This is a different record from the TestFlight one that testflight-setup.rb writes. Beta review
+# and store review do not share notes, so an explanation that only went to TestFlight is invisible
+# to the reviewer looking at the store submission, and to the automated entitlement check that runs
+# before a human sees it at all.
+begin
+  require "spaceship"
+rescue LoadError
+  libexec = Dir["/opt/homebrew/Cellar/fastlane/*/libexec", "/usr/local/Cellar/fastlane/*/libexec"].max
+  abort "spaceship is not installed. `brew install fastlane` and rerun." unless libexec
+  ENV["GEM_PATH"] = [libexec, ENV["GEM_PATH"]].compact.join(":")
+  Gem.clear_paths
+  require "spaceship"
+end
+
+DIR = ENV.fetch("METADATA_DIR", "appstore/metadata")
+BUNDLE_ID = ENV.fetch("BUNDLE_ID", "studio.margin.app")
+ENV["FASTLANE_ITC_TEAM_ID"] = ENV.fetch("FASTLANE_ITC_TEAM_ID", "129377371")
+
+NOTES_LIMIT = 4000
+
+def field(name)
+  path = File.join(DIR, "#{name}.txt")
+  return nil unless File.exist?(path)
+
+  File.read(path).strip
+end
+
+notes = field("review_notes")
+abort "#{DIR}/review_notes.txt is missing." unless notes
+abort "review_notes is #{notes.length} characters, over Apple's limit of #{NOTES_LIMIT}." if notes.length > NOTES_LIMIT
+
+phone = field("review_phone")
+abort "#{DIR}/review_phone.txt is missing and Apple requires a contact number." unless phone
+
+Spaceship::ConnectAPI.login(ENV["APPLE_EMAIL"], nil, use_portal: false, use_tunes: true)
+
+app = Spaceship::ConnectAPI::App.find(BUNDLE_ID)
+abort "No app for #{BUNDLE_ID}." unless app
+puts "#{app.name} (#{app.id})"
+
+version = app.get_edit_app_store_version(platform: Spaceship::ConnectAPI::Platform::MAC_OS)
+abort "No editable macOS version; the submission may already be in review." unless version
+puts "  version #{version.version_string} (#{version.app_store_state})"
+
+attributes = {
+  contactFirstName: field("review_first_name"),
+  contactLastName: field("review_last_name"),
+  contactEmail: field("review_email"),
+  contactPhone: phone,
+  # Margin has no accounts at all, so there is nothing for a reviewer to sign in to. Saying so
+  # explicitly is what stops the review coming back asking for credentials.
+  demoAccountRequired: false,
+  notes: notes,
+}
+
+detail = version.fetch_app_store_review_detail
+
+if detail
+  Spaceship::ConnectAPI.patch_app_store_review_detail(
+    app_store_review_detail_id: detail.id,
+    attributes: attributes,
+  )
+else
+  Spaceship::ConnectAPI.post_app_store_review_detail(
+    app_store_version_id: version.id,
+    attributes: attributes,
+  )
+end
+
+# Apple accepts a patch it then stores as something else often enough to be worth reading back, and
+# an empty notes field is exactly the state that got this submission rejected in the first place.
+written = version.fetch_app_store_review_detail&.notes.to_s
+if written.empty?
+  abort "  the notes field came back empty; nothing was saved."
+elsif written != notes
+  puts "  saved, but what came back differs from what was sent. Check it in App Store Connect."
+else
+  puts "  contact and #{notes.length} characters of review notes saved"
+end

scripts/appstore-screenshots.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# Upload the rendered frames in appstore/screenshots to the App Store listing.
+#
+#   [email protected] ruby scripts/appstore-screenshots.rb
+#
+# The frames are rendered by the HTML under appstore/screenshots/src, so this only ever moves
+# finished PNGs. Rerunning replaces what is there rather than appending, because a listing that
+# quietly accumulated ten frames across five runs would be worse than one that is simply current.
+begin
+  require "spaceship"
+rescue LoadError
+  libexec = Dir["/opt/homebrew/Cellar/fastlane/*/libexec", "/usr/local/Cellar/fastlane/*/libexec"].max
+  abort "spaceship is not installed. `brew install fastlane` and rerun." unless libexec
+  ENV["GEM_PATH"] = [libexec, ENV["GEM_PATH"]].compact.join(":")
+  Gem.clear_paths
+  require "spaceship"
+end
+
+require "shellwords"
+
+DIR = ENV.fetch("SCREENSHOT_DIR", "appstore/screenshots")
+LOCALE = "en-US"
+BUNDLE_ID = ENV.fetch("BUNDLE_ID", "studio.margin.app")
+ENV["FASTLANE_ITC_TEAM_ID"] = ENV.fetch("FASTLANE_ITC_TEAM_ID", "129377371")
+
+# The only size App Store Connect takes for a Mac app, out of the four it documents, that this
+# pipeline renders. Anything else is a mistake worth stopping for.
+EXPECTED = [2560, 1600].freeze
+
+frames = Dir[File.join(DIR, "frame-*.png")].sort
+abort "No frames in #{DIR}." if frames.empty?
+
+frames.each do |path|
+  dimensions = `sips -g pixelWidth -g pixelHeight #{path.shellescape} 2>/dev/null`
+    .scan(/pixel(?:Width|Height):\s*(\d+)/).flatten.map(&:to_i)
+  next if dimensions == EXPECTED
+
+  abort "#{path} is #{dimensions.join('x')}, and Apple wants #{EXPECTED.join('x')}."
+end
+puts "#{frames.size} frames, all #{EXPECTED.join('x')}"
+
+Spaceship::ConnectAPI.login(ENV["APPLE_EMAIL"], nil, use_portal: false, use_tunes: true)
+
+app = Spaceship::ConnectAPI::App.find(BUNDLE_ID)
+abort "No app for #{BUNDLE_ID}." unless app
+puts "#{app.name} (#{app.id})"
+
+version = app.get_edit_app_store_version(platform: Spaceship::ConnectAPI::Platform::MAC_OS)
+abort "No editable macOS version." unless version
+
+localization = version.get_app_store_version_localizations.find { |l| l.locale == LOCALE }
+abort "No #{LOCALE} localization; run appstore-listing.rb first." unless localization
+
+display_type = Spaceship::ConnectAPI::AppScreenshotSet::DisplayType::APP_DESKTOP
+set = localization.get_app_screenshot_sets.find { |s| s.screenshot_display_type == display_type }
+
+if set
+  set.app_screenshots.each(&:delete!)
+  puts "  cleared #{set.app_screenshots.size} existing screenshots"
+else
+  set = localization.create_app_screenshot_set(attributes: { screenshotDisplayType: display_type })
+  puts "  created the desktop screenshot set"
+end
+
+frames.each_with_index do |path, index|
+  set.upload_screenshot(path: path, position: index)
+  puts "  uploaded #{File.basename(path)}"
+end
+
+puts
+puts "Apple processes each image before it counts as attached; give it a minute before checking."

scripts/mas-package.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Turn the .app that `tauri build` produced into a signed .pkg the App Store will accept, and
+# optionally hand it to App Store Connect.
+#
+# Tauri has no App Store target, so everything after the bundle is done here: the provisioning
+# profile goes in before signing (codesign hashes it), the entitlements carry the team identifier,
+# and productbuild wraps the result. Tauri's own signing is deliberately not used, because it
+# cannot embed a profile and would sign the app before the profile was in place.
+set -euo pipefail
+
+# CI builds universal; a local check against a single-arch build only needs to override this.
+app="${APP_PATH:-src-tauri/target/universal-apple-darwin/release/bundle/macos/Margin.app}"
+pkg="${PKG_PATH:-target-mas/Margin.pkg}"
+
+: "${APPLE_TEAM_ID:?set APPLE_TEAM_ID to the 10-character team identifier}"
+: "${MAS_PROVISION_PROFILE:?set MAS_PROVISION_PROFILE to the .provisionprofile path}"
+: "${MAS_APP_IDENTITY:?set MAS_APP_IDENTITY, e.g. '3rd Party Mac Developer Application: Priyanshu Jain (TEAMID)'}"
+: "${MAS_INSTALLER_IDENTITY:?set MAS_INSTALLER_IDENTITY, e.g. '3rd Party Mac Developer Installer: Priyanshu Jain (TEAMID)'}"
+
+[ -d "$app" ] || { echo "mas-package: $app does not exist; run the build first." >&2; exit 1; }
+
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+mkdir -p "$(dirname "$pkg")"
+
+# App Store Connect rejects an upload whose CFBundleVersion it has already seen, so a rejected
+# build has to come back with a higher one. The marketing version stays put.
+if [ -n "${MAS_BUILD_NUMBER:-}" ]; then
+  /usr/libexec/PlistBuddy -c "Set :CFBundleVersion $MAS_BUILD_NUMBER" "$app/Contents/Info.plist"
+fi
+
+cp "$MAS_PROVISION_PROFILE" "$app/Contents/embedded.provisionprofile"
+
+# The profile is kept owner-only where it lives, because it sits next to signing keys, and cp
+# carries that mode across. Apple rejects a package containing anything a non-root user cannot
+# read, since the code signature could not then be verified at launch. Widen everything rather
+# than just the profile, and only ever add permission bits, never remove one.
+find "$app" -type d -exec chmod go+rx {} +
+find "$app" -type f -exec chmod go+r {} +
+sed "s/__TEAM_ID__/$APPLE_TEAM_ID/g" src-tauri/entitlements.mas.plist > "$work/entitlements.plist"
+plutil -lint "$work/entitlements.plist" > /dev/null
+
+# Nested code has to be signed before the bundle that contains it, and --deep is the wrong tool
+# for signing (it applies the outer entitlements to everything inside). Tauri bundles carry no
+# frameworks today, so this loop is usually empty, and it stays here so that stops being silent
+# the day one appears.
+while IFS= read -r -d '' nested; do
+  codesign --force --timestamp --options runtime --sign "$MAS_APP_IDENTITY" "$nested"
+done < <(find "$app/Contents/Frameworks" "$app/Contents/XPCServices" -maxdepth 1 -mindepth 1 -print0 2>/dev/null)
+
+codesign --force --timestamp --options runtime \
+  --sign "$MAS_APP_IDENTITY" \
+  --entitlements "$work/entitlements.plist" \
+  "$app"
+
+codesign --verify --deep --strict --verbose=2 "$app"
+echo "Entitlements on the signed bundle:"
+codesign --display --entitlements - --xml "$app" | plutil -convert xml1 -o - -
+
+productbuild --component "$app" /Applications --sign "$MAS_INSTALLER_IDENTITY" "$pkg"
+pkgutil --check-signature "$pkg"
+echo "mas-package: wrote $pkg"
+
+# The upload needs the .p8 where altool looks for it; the caller places it and sets these.
+# altool exits 0 even when it has just printed UPLOAD FAILED, so its exit status cannot be
+# trusted and the transcript is the only reliable signal.
+run_altool() {
+  local action="$1" output
+  output=$(xcrun altool "$action" -f "$pkg" -t macos \
+    --apiKey "$APPLE_API_KEY_ID" --apiIssuer "$APPLE_API_ISSUER" 2>&1) || true
+  printf '%s\n' "$output"
+  if printf '%s' "$output" | grep -qE "VERIFY FAILED|UPLOAD FAILED|ERROR:"; then
+    echo "mas-package: $action failed, see the errors above." >&2
+    return 1
+  fi
+}
+
+if [ -n "${MAS_UPLOAD:-}" ]; then
+  : "${APPLE_API_KEY_ID:?}" "${APPLE_API_ISSUER:?}"
+  run_altool --validate-app
+  run_altool --upload-app
+  echo "mas-package: uploaded to App Store Connect; the build appears once processing finishes."
+fi

scripts/mas-upload-local.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Sign, package and upload an App Store build from this machine, using the certificates in
+# ~/.margin-signing rather than the ones in CI.
+#
+# The certificates go into a keychain that exists only for the length of this run, and the login
+# keychain is never written to. That keeps a machine that has signed once from quietly being able
+# to sign forever, and it means this leaves nothing behind to go stale.
+#
+#   ./scripts/mas-upload-local.sh              # build, sign, package, upload
+#   MAS_UPLOAD= ./scripts/mas-upload-local.sh  # stop after the .pkg
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+DIR="${MARGIN_SIGNING_DIR:-$HOME/.margin-signing}"
+BUNDLE_ID="${BUNDLE_ID:-studio.margin.app}"
+KEYCHAIN="$(mktemp -d)/margin-mas.keychain-db"
+
+for f in "$BUNDLE_ID.env" "$BUNDLE_ID.provisionprofile" apple-distribution.p12 mac-installer.p12; do
+  [ -f "$DIR/$f" ] || { echo "mas-upload-local: $DIR/$f is missing; run apple-provision.rb first." >&2; exit 1; }
+done
+
+# shellcheck source=/dev/null
+set -a; . "$DIR/$BUNDLE_ID.env"; set +a
+export MAS_PROVISION_PROFILE="$DIR/$BUNDLE_ID.provisionprofile"
+
+# App Store Connect refuses an upload whose build number it has already seen, and seconds since the
+# epoch is both unique and monotonic without needing anything to be remembered between runs.
+export MAS_BUILD_NUMBER="${MAS_BUILD_NUMBER:-$(date +%s)}"
+export MAS_UPLOAD="${MAS_UPLOAD-1}"
+
+if [ -n "${MAS_UPLOAD:-}" ]; then
+  # shellcheck source=/dev/null
+  set -a; . "$DIR/AuthKey.env"; set +a
+  mkdir -p ~/private_keys
+  cp "$DIR/AuthKey.p8" ~/private_keys/"AuthKey_$APPLE_API_KEY_ID.p8"
+  chmod 600 ~/private_keys/"AuthKey_$APPLE_API_KEY_ID.p8"
+fi
+
+original_keychains=$(security list-keychains -d user | sed 's/^ *"//;s/"$//')
+restore() {
+  # shellcheck disable=SC2086
+  security list-keychains -d user -s $original_keychains
+  security delete-keychain "$KEYCHAIN" 2>/dev/null || true
+}
+trap restore EXIT
+
+security create-keychain -p margin "$KEYCHAIN"
+security unlock-keychain -p margin "$KEYCHAIN"
+for cert in apple-distribution mac-installer; do
+  security import "$DIR/$cert.p12" -k "$KEYCHAIN" -P "$(cat "$DIR/$cert.p12.pass")" \
+    -T /usr/bin/codesign -T /usr/bin/productbuild > /dev/null
+done
+# Without this, codesign stops on a keychain prompt rather than signing.
+security set-key-partition-list -S apple-tool:,apple: -k margin "$KEYCHAIN" > /dev/null
+# shellcheck disable=SC2086
+security list-keychains -d user -s "$KEYCHAIN" $original_keychains
+
+if [ -z "${SKIP_BUILD:-}" ]; then
+  pnpm tauri build --target universal-apple-darwin \
+    --config src-tauri/tauri.appstore.conf.json --bundles app
+fi
+
+./scripts/mas-package.sh

scripts/testflight-release.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# Put the most recently uploaded build in front of testers.
+#
+# Apple takes somewhere between a few minutes and an hour to process an upload, and nothing can be
+# assigned until it has. So this waits rather than failing, and says what it is waiting for.
+#
+#   [email protected] ruby scripts/testflight-release.rb
+#
+# Internal testers get the build as soon as it is assigned. External testers are gated on Beta App
+# Review, which this submits for and which usually comes back within a day.
+begin
+  require "spaceship"
+rescue LoadError
+  libexec = Dir["/opt/homebrew/Cellar/fastlane/*/libexec", "/usr/local/Cellar/fastlane/*/libexec"].max
+  abort "spaceship is not installed. `brew install fastlane` and rerun." unless libexec
+  ENV["GEM_PATH"] = [libexec, ENV["GEM_PATH"]].compact.join(":")
+  Gem.clear_paths
+  require "spaceship"
+end
+
+BUNDLE_ID = ENV.fetch("BUNDLE_ID", "studio.margin.app")
+ENV["FASTLANE_ITC_TEAM_ID"] = ENV.fetch("FASTLANE_ITC_TEAM_ID", "129377371")
+WAIT_SECONDS = Integer(ENV.fetch("WAIT_SECONDS", "1800"))
+
+Spaceship::ConnectAPI.login(ENV["APPLE_EMAIL"], nil, use_portal: false, use_tunes: true)
+
+app = Spaceship::ConnectAPI::App.find(BUNDLE_ID)
+abort "No app for #{BUNDLE_ID}." unless app
+puts "#{app.name} (#{app.id})"
+
+deadline = Time.now + WAIT_SECONDS
+build = nil
+
+loop do
+  builds = Spaceship::ConnectAPI::Build.all(app_id: app.id, sort: "-uploadedDate", limit: 5)
+  ready = builds.reject(&:expired).find { |b| b.processing_state == "VALID" }
+
+  if ready
+    build = ready
+    break
+  end
+
+  pending = builds.find { |b| b.processing_state == "PROCESSING" }
+  if Time.now > deadline
+    abort "Timed out after #{WAIT_SECONDS}s. #{pending ? 'The build is still processing.' : 'No build has appeared yet.'}"
+  end
+
+  puts(pending ? "  waiting: build #{pending.version} is still processing" : "  waiting: no build has appeared yet")
+  sleep(30)
+end
+
+puts "  build #{build.app_version} (#{build.version}) is ready"
+
+groups = app.get_beta_groups
+
+# A group created with hasAccessToAllBuilds receives every build the moment it processes, and Apple
+# rejects an explicit assignment to one rather than treating it as a no-op. The internal group is
+# exactly that, so there is nothing to do for it and nothing to report either.
+assignable = groups.reject { |g| g.is_internal_group || g.has_access_to_all_builds }
+already = (build.get_beta_groups.map(&:id) rescue [])
+to_add = assignable.reject { |g| already.include?(g.id) }
+
+if to_add.empty?
+  puts "  nothing to assign: #{groups.map(&:name).join(', ')} already have this build"
+else
+  build.add_beta_groups(beta_groups: to_add)
+  puts "  assigned to #{to_add.map(&:name).join(', ')}"
+end
+
+# Only external groups are gated on review, so an app with internal testers only never needs this.
+if groups.any? { |g| !g.is_internal_group }
+  begin
+    Spaceship::ConnectAPI.post_beta_app_review_submissions(build_id: build.id)
+    puts "  submitted for beta app review, which gates the external testers"
+  rescue => e
+    # Resubmitting an already submitted build is not an error worth failing the run over.
+    puts "  beta app review not submitted: #{e.message.lines.first.to_s.strip}"
+  end
+end
+
+# The store version needs the build attached too, and that is a separate thing from TestFlight.
+# Until it is, App Store Connect shows the listing with no app icon, because for a Mac app the icon
+# is read out of the attached build rather than uploaded alongside the other artwork.
+version = app.get_edit_app_store_version(platform: Spaceship::ConnectAPI::Platform::MAC_OS)
+if version.nil?
+  puts "  no editable store version to attach the build to"
+elsif version.build&.id == build.id
+  puts "  already attached to store version #{version.version_string}"
+else
+  version.select_build(build_id: build.id)
+  puts "  attached to store version #{version.version_string}, which is what surfaces the app icon"
+end
+
+puts
+puts "Internal testers can install now. External testers wait on beta app review."

scripts/testflight-setup.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# Set up TestFlight for the app: the tester-facing blurb, the details Beta App Review asks for, and
+# the two groups. None of this needs a build to exist, so it can all be in place before the first
+# upload and the build then only has to be assigned to a group.
+#
+#   [email protected] ruby scripts/testflight-setup.rb
+begin
+  require "spaceship"
+rescue LoadError
+  libexec = Dir["/opt/homebrew/Cellar/fastlane/*/libexec", "/usr/local/Cellar/fastlane/*/libexec"].max
+  abort "spaceship is not installed. `brew install fastlane` and rerun." unless libexec
+  ENV["GEM_PATH"] = [libexec, ENV["GEM_PATH"]].compact.join(":")
+  Gem.clear_paths
+  require "spaceship"
+end
+
+DIR = ENV.fetch("METADATA_DIR", "appstore/metadata")
+LOCALE = "en-US"
+BUNDLE_ID = ENV.fetch("BUNDLE_ID", "studio.margin.app")
+ENV["FASTLANE_ITC_TEAM_ID"] = ENV.fetch("FASTLANE_ITC_TEAM_ID", "129377371")
+
+def field(name, localized: true)
+  path = localized ? File.join(DIR, LOCALE, "#{name}.txt") : File.join(DIR, "#{name}.txt")
+  File.exist?(path) ? File.read(path).strip : nil
+end
+
+Spaceship::ConnectAPI.login(ENV["APPLE_EMAIL"], nil, use_portal: false, use_tunes: true)
+
+app = Spaceship::ConnectAPI::App.find(BUNDLE_ID)
+abort "No app for #{BUNDLE_ID}." unless app
+puts "#{app.name} (#{app.id})"
+
+localization = app.get_beta_app_localizations.find { |l| l.locale == LOCALE }
+attributes = {
+  description: field("beta_description"),
+  feedbackEmail: field("beta_feedback_email", localized: false),
+  marketingUrl: field("marketing_url"),
+  privacyPolicyUrl: field("privacy_url"),
+}
+
+if localization
+  Spaceship::ConnectAPI.patch_beta_app_localizations(localization_id: localization.id, attributes: attributes)
+else
+  Spaceship::ConnectAPI.post_beta_app_localizations(app_id: app.id, attributes: attributes.merge(locale: LOCALE))
+end
+puts "  tester blurb and feedback address set"
+
+# Apple requires a contact phone number here, and this only gates external testing: internal
+# testers never go through Beta App Review. So a missing number is a warning, not a failure.
+if field("review_phone", localized: false)
+  Spaceship::ConnectAPI.patch_beta_app_review_detail(app_id: app.id, attributes: {
+    contactFirstName: field("review_first_name", localized: false),
+    contactLastName: field("review_last_name", localized: false),
+    contactEmail: field("review_email", localized: false),
+    contactPhone: field("review_phone", localized: false),
+    # Margin has no accounts at all, so there is nothing for a reviewer to sign in to. Saying so
+    # explicitly is what stops the review coming back asking for credentials.
+    demoAccountRequired: false,
+    notes: field("review_notes", localized: false),
+  })
+  puts "  beta app review contact and notes set"
+else
+  puts "  skipping beta app review details: #{DIR}/review_phone.txt is missing and Apple requires"
+  puts "  a contact number. Internal testing works without it; external testing does not."
+end
+
+existing = app.get_beta_groups.map(&:name)
+
+[
+  { name: "Internal", internal: true, public_link: false },
+  { name: "Public Beta", internal: false, public_link: true },
+].each do |group|
+  if existing.include?(group[:name])
+    puts "  group #{group[:name].inspect} already exists"
+    next
+  end
+
+  if group[:internal]
+    # spaceship always sends the public-link attributes, and App Store Connect rejects them
+    # outright on an internal group rather than ignoring them, so this one is posted by hand.
+    body = {
+      data: {
+        attributes: { name: group[:name], isInternalGroup: true, hasAccessToAllBuilds: true },
+        relationships: { app: { data: { id: app.id, type: "apps" } } },
+        type: "betaGroups",
+      },
+    }
+    Spaceship::ConnectAPI.client.test_flight_request_client.post("v1/betaGroups", body)
+    puts "  created internal group #{group[:name].inspect}"
+  else
+    created = app.create_beta_group(
+      group_name: group[:name],
+      is_internal_group: false,
+      public_link_enabled: true,
+      public_link_limit_enabled: true,
+    )
+    puts "  created external group #{created.name.inspect}"
+  end
+end
+
+puts
+app.get_beta_groups.each do |g|
+  kind = g.is_internal_group ? "internal" : "external"
+  puts "  #{g.name} (#{kind})#{g.public_link ? " #{g.public_link}" : ''}"
+end

scripts/testflight-testers.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# Invite people to a TestFlight group.
+#
+#   [email protected] ruby scripts/testflight-testers.rb [email protected] ...
+#
+# Addresses come from the command line rather than a file in the repo, because a list of testers is
+# a list of people's email addresses and this repository is public.
+#
+# GROUP defaults to the external group, since the internal one only accepts people who already have
+# an App Store Connect account on the team, which is a far bigger thing to hand out than a build.
+begin
+  require "spaceship"
+rescue LoadError
+  libexec = Dir["/opt/homebrew/Cellar/fastlane/*/libexec", "/usr/local/Cellar/fastlane/*/libexec"].max
+  abort "spaceship is not installed. `brew install fastlane` and rerun." unless libexec
+  ENV["GEM_PATH"] = [libexec, ENV["GEM_PATH"]].compact.join(":")
+  Gem.clear_paths
+  require "spaceship"
+end
+
+BUNDLE_ID = ENV.fetch("BUNDLE_ID", "studio.margin.app")
+GROUP = ENV.fetch("GROUP", "Public Beta")
+ENV["FASTLANE_ITC_TEAM_ID"] = ENV.fetch("FASTLANE_ITC_TEAM_ID", "129377371")
+
+emails = ARGV.reject { |a| a.start_with?("-") }
+abort "Usage: ruby scripts/testflight-testers.rb [email protected] [[email protected] ...]" if emails.empty?
+
+Spaceship::ConnectAPI.login(ENV["APPLE_EMAIL"], nil, use_portal: false, use_tunes: true)
+
+app = Spaceship::ConnectAPI::App.find(BUNDLE_ID)
+abort "No app for #{BUNDLE_ID}." unless app
+
+group = app.get_beta_groups.find { |g| g.name == GROUP }
+abort "No group named #{GROUP.inspect}." unless group
+puts "#{app.name}: #{group.name} (#{group.is_internal_group ? 'internal' : 'external'})"
+
+# An internal tester has to be a user on the App Store Connect account first, which is a far larger
+# grant than a build: it is access to the account, not to an app. So the invitation is narrowed as
+# far as the API allows, to this one app and with provisioning refused, and the person still has to
+# accept it before they can be put in the group.
+if group.is_internal_group
+  known = Spaceship::ConnectAPI::User.all.map { |u| u.email.to_s.downcase }
+  invited = Spaceship::ConnectAPI::UserInvitation.all.map { |i| i.email.to_s.downcase }
+
+  emails.each do |email|
+    next if known.include?(email.downcase)
+
+    if invited.include?(email.downcase)
+      puts "  #{email} has an invitation waiting to be accepted"
+      next
+    end
+
+    local = email.split("@").first
+    Spaceship::ConnectAPI::UserInvitation.create(
+      email: email,
+      first_name: ENV.fetch("FIRST_NAME", local),
+      last_name: ENV.fetch("LAST_NAME", "Tester"),
+      roles: [Spaceship::ConnectAPI::User::UserRole::DEVELOPER],
+      provisioning_allowed: false,
+      all_apps_visible: false,
+      visible_app_ids: [app.id],
+    )
+    puts "  invited #{email} to App Store Connect, limited to this app, no provisioning access"
+    invited << email.downcase
+  end
+end
+
+existing = Spaceship::ConnectAPI::BetaTester
+  .all(filter: { betaGroups: group.id })
+  .map { |t| t.email.to_s.downcase }
+
+emails.each do |email|
+  if existing.include?(email.downcase)
+    puts "  #{email} is already in this group"
+    next
+  end
+
+  Spaceship::ConnectAPI.post_bulk_beta_tester_assignments(
+    beta_group_id: group.id,
+    beta_testers: [{ email: email }],
+  )
+
+  # The bulk endpoint reports success for an address it then quietly declines to add, which is what
+  # happens on an internal group when the person has not accepted their account invitation yet. So
+  # the group is read back rather than trusted.
+  landed = Spaceship::ConnectAPI::BetaTester
+    .all(filter: { betaGroups: group.id })
+    .any? { |t| t.email.to_s.casecmp?(email) }
+
+  if landed
+    puts "  added #{email}"
+  else
+    puts "  #{email} was not added. An internal tester has to accept the App Store Connect"
+    puts "  invitation first; rerun this once they have."
+  end
+end
+
+puts
+if group.is_internal_group
+  puts "Internal testers can install as soon as a build finishes processing."
+else
+  puts "External testers get the invitation once beta app review passes."
+  puts "Anyone can also join through #{group.public_link}" if group.public_link
+end

shared/README.md

@@ -0,0 +1,15 @@
+# margin-shared
+
+The faces, palette and glyphs [Margin](../) and Margin Docs both draw from. It is the one copy of
+the decisions the two apps have to agree on: which six fonts they offer, what their named pairings
+are, the 35 design tokens they share, and the title bar icon paths.
+
+No build step and no dependencies. Both apps resolve the TypeScript source directly through their
+bundler, so an edit here is live in both on the next dev server restart.
+
+Margin consumes it as `"margin-shared": "file:./shared"`. Margin Docs, which lives in a separate
+repository, uses a relative path to this directory; see its `package.json`.
+
+The font binaries in `fonts/` are the source of truth, and each app keeps a vendored copy under
+`public/fonts` because its Rust PDF exporter reads them with `include_bytes!` before any npm install
+has run. Run `pnpm fonts:sync` in an app to refresh that copy and `pnpm fonts:check` to verify it.

shared/bin/sync-fonts.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Copies this package's font files into an app's public/fonts, or checks that they already match.
+//
+// The copies exist because both apps' `src-tauri/src/pdf.rs` reads the same files with
+// `include_bytes!`, so the bytes have to be on disk at a path cargo can see before any npm install
+// has run. Serving them out of node_modules would mean a cargo build that fails on a fresh clone
+// until the front end was installed, which is a worse trade than a vendored copy with a named
+// upstream and a check that fails loudly when the two drift.
+//
+//   node bin/sync-fonts.mjs <app-dir>            copy, reporting what changed
+//   node bin/sync-fonts.mjs <app-dir> --check    compare only, exit 1 on any difference
+
+import { readdirSync, readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = resolve(here, "..", "fonts");
+
+const args = process.argv.slice(2);
+const check = args.includes("--check");
+const target = args.find((a) => !a.startsWith("--"));
+
+if (!target) {
+  console.error("usage: sync-fonts.mjs <app-dir> [--check]");
+  process.exit(2);
+}
+
+const dest = resolve(process.cwd(), target, "public", "fonts");
+const files = readdirSync(source).filter((f) => f.endsWith(".ttf") || f.endsWith(".txt")).sort();
+
+if (!check) mkdirSync(dest, { recursive: true });
+
+const wrong = [];
+let copied = 0;
+
+for (const file of files) {
+  const from = join(source, file);
+  const to = join(dest, file);
+  const want = readFileSync(from);
+  const have = existsSync(to) ? readFileSync(to) : null;
+
+  if (have !== null && have.equals(want)) continue;
+
+  if (check) {
+    wrong.push(`${have === null ? "missing" : "differs"}: ${file}`);
+    continue;
+  }
+  writeFileSync(to, want);
+  copied += 1;
+}
+
+// A file the app has and the package does not is reported rather than deleted. It is far more
+// likely to be a face somebody is in the middle of adding than something to throw away, and this
+// script does not get to be the reason an asset disappears.
+if (existsSync(dest)) {
+  for (const file of readdirSync(dest)) {
+    if (!files.includes(file)) wrong.push(`not in the package, left alone: ${file}`);
+  }
+}
+
+if (check) {
+  if (wrong.length === 0) {
+    console.log(`fonts match margin-shared (${files.length} files)`);
+    process.exit(0);
+  }
+  console.error("public/fonts is out of step with margin-shared:");
+  for (const line of wrong) console.error(`  ${line}`);
+  console.error("\nrun: pnpm fonts:sync");
+  process.exit(1);
+}
+
+console.log(copied === 0 ? `fonts already current (${files.length} files)` : `synced ${copied} file(s)`);
+for (const line of wrong) console.log(`  note: ${line}`);

shared/css/fonts.css

@@ -0,0 +1,111 @@
+/* The six families src/fonts.ts offers, bound to the variable files in fonts/.
+ *
+ * The URLs are absolute site paths, so each app serves these out of its own `public/fonts`. The
+ * copies there are vendored from this package and kept honest by `bin/sync-fonts.mjs`; they are not
+ * imported from node_modules, because both apps' `src-tauri/src/pdf.rs` reads the same files with
+ * `include_bytes!` and a cargo build must not depend on an npm install having run first.
+ *
+ * Every one is a variable file with an upright and an italic cut, so a weight anywhere in the
+ * declared range is a real instance rather than a synthesised one, and italic is the designer's
+ * italic rather than a slant applied by the browser.
+ *
+ * `font-display: block` throughout, and that is the unusual choice. The alternative is a first
+ * paint in Georgia that reflows into Literata a moment later, and a page of prose that resets its
+ * line breaks under the caret is worse than a page that arrives a beat late. The files are local to
+ * the bundle, so the beat is a disk read. */
+
+@font-face {
+  font-family: "Hanken Grotesk";
+  src: url("/fonts/HankenGrotesk-VF.ttf") format("truetype-variations");
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Hanken Grotesk";
+  src: url("/fonts/HankenGrotesk-Italic-VF.ttf") format("truetype-variations");
+  font-weight: 100 900;
+  font-style: italic;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Literata";
+  src: url("/fonts/Literata-VF.ttf") format("truetype-variations");
+  font-weight: 200 900;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Literata";
+  src: url("/fonts/Literata-Italic-VF.ttf") format("truetype-variations");
+  font-weight: 200 900;
+  font-style: italic;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "EB Garamond";
+  src: url("/fonts/EBGaramond-VF.ttf") format("truetype-variations");
+  font-weight: 400 800;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "EB Garamond";
+  src: url("/fonts/EBGaramond-Italic-VF.ttf") format("truetype-variations");
+  font-weight: 400 800;
+  font-style: italic;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Lora";
+  src: url("/fonts/Lora-VF.ttf") format("truetype-variations");
+  font-weight: 400 700;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Lora";
+  src: url("/fonts/Lora-Italic-VF.ttf") format("truetype-variations");
+  font-weight: 400 700;
+  font-style: italic;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Source Serif 4";
+  src: url("/fonts/SourceSerif4-VF.ttf") format("truetype-variations");
+  font-weight: 200 900;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Source Serif 4";
+  src: url("/fonts/SourceSerif4-Italic-VF.ttf") format("truetype-variations");
+  font-weight: 200 900;
+  font-style: italic;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Fraunces";
+  src: url("/fonts/Fraunces-VF.ttf") format("truetype-variations");
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Fraunces";
+  src: url("/fonts/Fraunces-Italic-VF.ttf") format("truetype-variations");
+  font-weight: 100 900;
+  font-style: italic;
+  font-display: block;
+}

shared/css/tokens.css

@@ -0,0 +1,91 @@
+/* The palette, the type scale and the shape constants both apps are built from.
+ *
+ * These 35 tokens already held identical values in the two repos before this package existed, which
+ * is the argument for moving them: they were identical by somebody remembering to copy a hex across,
+ * and that is not a mechanism. A colour that only exists in one app is not here. Each app layers its
+ * own sheet on top of this one and adds what only it needs, which is a preview pane width in Margin
+ * and a document typography scale in Margin Docs.
+ *
+ * --font-book and --font-heading are the two a document overrides at runtime, per book or per
+ * document. What is set here is the default pair, and the only place that decides what an untouched
+ * page looks like. */
+
+:root {
+  --font-ui: "Hanken Grotesk", ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-book: "Literata", Georgia, "Times New Roman", serif;
+  --font-heading: "Literata", Georgia, "Times New Roman", serif;
+
+  --r-sm: 5px;
+  --r-md: 8px;
+  --r-lg: 12px;
+
+  --pane-sidebar: 248px;
+  --measure: 46em;
+  --titlebar-h: 46px;
+
+  --t-1: 11px;
+  --t-2: 12px;
+  --t-3: 13px;
+  --t-4: 15px;
+
+  --ease: cubic-bezier(0.22, 0.61, 0.36, 1);
+}
+
+:root,
+:root[data-theme="light"] {
+  --paper: #fcfbf7;
+  --shell: #f1ece2;
+  --sidebar: #ece6da;
+  --raised: #fbfaf6;
+
+  --ink: #23201b;
+  --ink-soft: #6b6458;
+  --ink-faint: #9b9484;
+
+  --line: #e3ddce;
+  --line-strong: #d6cfbd;
+
+  --accent: #2a2622;
+  --accent-ink: #100e0b;
+  --accent-wash: rgba(35, 32, 27, 0.08);
+  --accent-contrast: #faf7f0;
+  --selection: rgba(35, 32, 27, 0.14);
+  --glass: rgba(252, 251, 247, 0.86);
+
+  --danger: #b4453a;
+  --danger-ink: #963327;
+  --danger-wash: rgba(180, 69, 58, 0.1);
+  --danger-contrast: #faf7f0;
+
+  --shadow-page: 0 1px 2px rgba(35, 32, 27, 0.06), 0 14px 30px rgba(35, 32, 27, 0.09);
+  --shadow-pop: 0 8px 24px rgba(35, 32, 27, 0.14);
+}
+
+:root[data-theme="dark"] {
+  --paper: #1d1a16;
+  --shell: #151310;
+  --sidebar: #1a1713;
+  --raised: #232019;
+
+  --ink: #ece6da;
+  --ink-soft: #a89f8e;
+  --ink-faint: #756d5e;
+
+  --line: #2c2823;
+  --line-strong: #3a352d;
+
+  --accent: #efe9dc;
+  --accent-ink: #ffffff;
+  --accent-wash: rgba(239, 233, 220, 0.12);
+  --accent-contrast: #1a1714;
+  --selection: rgba(239, 233, 220, 0.18);
+  --glass: rgba(33, 30, 25, 0.88);
+
+  --danger: #d97a6f;
+  --danger-ink: #e58e84;
+  --danger-wash: rgba(217, 122, 111, 0.16);
+  --danger-contrast: #1a1714;
+
+  --shadow-page: 0 1px 2px rgba(0, 0, 0, 0.4), 0 14px 34px rgba(0, 0, 0, 0.5);
+  --shadow-pop: 0 8px 24px rgba(0, 0, 0, 0.55);
+}

shared/fonts/EBGaramond-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2017 The EB Garamond Project Authors (https://github.com/octaviopardo/EBGaramond12)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

shared/fonts/Fraunces-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2018 The Fraunces Project Authors (https://github.com/undercasetype/Fraunces)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

shared/fonts/HankenGrotesk-OFL.txt

@@ -0,0 +1,94 @@
+Copyright 2021 The Hanken Grotesk Project Authors (https://github.com/marcologous/hanken-grotesk)
+
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

shared/fonts/Literata-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2017 The Literata Project Authors (https://github.com/googlefonts/literata)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

shared/fonts/Lora-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2011 The Lora Project Authors (https://github.com/cyrealtype/Lora-Cyrillic), with Reserved Font Name "Lora".
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

shared/fonts/SourceSerif4-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2014 The Source Serif 4 Project Authors (https://github.com/adobe-fonts/source-serif)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

shared/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "margin-shared",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "description": "The faces, palette and glyphs Margin and Margin Docs both draw from.",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./fonts": "./src/fonts.ts",
+    "./icons": "./src/icons.ts",
+    "./css/fonts.css": "./css/fonts.css",
+    "./css/tokens.css": "./css/tokens.css"
+  },
+  "bin": {
+    "margin-shared-fonts": "./bin/sync-fonts.mjs"
+  },
+  "files": ["src", "css", "fonts", "bin"]
+}

shared/src/fonts.ts

@@ -0,0 +1,233 @@
+// The faces both apps offer, and the two slots they set them into.
+//
+// This lives in one place because the two apps have to agree about it. A face named here is a
+// `@font-face` in css/fonts.css, a file in fonts/, and a family a Typst preamble names on the way
+// to a PDF, and those four lists going out of step with each other is a document that renders in
+// one app and falls back to Georgia in the other. There is no way to keep four lists in two repos
+// honest by hand, so there is one list.
+//
+// Two slots and not one. Body and heading are the only typographic decision worth a control:
+// a document that lets its author pick a face per paragraph is a word processor, and neither of
+// these is one. The scale, the leading and the measure belong to each app's own stylesheet, which
+// decided them once for every document.
+//
+// A `FontRef` is stored, not a family name. "Literata" as a string cannot say whether it means the
+// file in fonts/ or a copy the user installed themselves, and those are two different faces the
+// moment one of them is updated.
+
+export type FontCategory = "serif" | "sans" | "display";
+
+/** One face that ships in fonts/, in the variable file both editors render from. */
+export interface BundledFont {
+  id: string;
+  label: string;
+  /** The CSS family name, which is also what a Typst preamble names it by. */
+  family: string;
+  category: FontCategory;
+  regular: string;
+  italic: string;
+  /** The weight range the variable file covers, for the `@font-face` in css/fonts.css. */
+  weight: string;
+}
+
+/**
+ * The six, and the order a picker lists them in: the serifs a page of prose is set in, the one
+ * display face, then the sans both apps' own chrome already uses.
+ *
+ * Literata and Hanken Grotesk are first-class here and also special: they are the two that have
+ * static instances cut for PDF export, so they are the only pair whose bold really is bold on the
+ * page. The other four export as their variable file at one weight, which each app's pdf.rs
+ * explains.
+ */
+export const BUNDLED_FONTS: readonly BundledFont[] = [
+  {
+    id: "literata",
+    label: "Literata",
+    family: "Literata",
+    category: "serif",
+    regular: "Literata-VF.ttf",
+    italic: "Literata-Italic-VF.ttf",
+    weight: "200 900",
+  },
+  {
+    id: "eb-garamond",
+    label: "EB Garamond",
+    family: "EB Garamond",
+    category: "serif",
+    regular: "EBGaramond-VF.ttf",
+    italic: "EBGaramond-Italic-VF.ttf",
+    weight: "400 800",
+  },
+  {
+    id: "lora",
+    label: "Lora",
+    family: "Lora",
+    category: "serif",
+    regular: "Lora-VF.ttf",
+    italic: "Lora-Italic-VF.ttf",
+    weight: "400 700",
+  },
+  {
+    id: "source-serif",
+    label: "Source Serif 4",
+    family: "Source Serif 4",
+    category: "serif",
+    regular: "SourceSerif4-VF.ttf",
+    italic: "SourceSerif4-Italic-VF.ttf",
+    weight: "200 900",
+  },
+  {
+    id: "fraunces",
+    label: "Fraunces",
+    family: "Fraunces",
+    category: "display",
+    regular: "Fraunces-VF.ttf",
+    italic: "Fraunces-Italic-VF.ttf",
+    weight: "100 900",
+  },
+  {
+    id: "hanken",
+    label: "Hanken Grotesk",
+    family: "Hanken Grotesk",
+    category: "sans",
+    regular: "HankenGrotesk-VF.ttf",
+    italic: "HankenGrotesk-Italic-VF.ttf",
+    weight: "100 900",
+  },
+];
+
+/** One of the six, or a family off the machine. */
+export type FontRef = { kind: "bundled"; id: string } | { kind: "system"; family: string };
+
+/**
+ * What one book or one document is set in.
+ *
+ * Named for the pair rather than for either app's noun, because the two call the thing it belongs
+ * to different names. Each app aliases it: `BookFonts` in Margin, `DocumentFonts` in Margin Docs.
+ */
+export interface FontPair {
+  body: FontRef;
+  heading: FontRef;
+}
+
+/**
+ * A named pair, which is what a picker offers first.
+ *
+ * Pairing two faces is the part of this that takes an eye, and a list of twelve families with no
+ * opinion attached is how a document ends up in Fraunces body text. The presets are the answer to
+ * "make this look like something"; the two selects underneath are for somebody who already knows.
+ */
+export interface FontPairing {
+  id: string;
+  label: string;
+  body: FontRef;
+  heading: FontRef;
+}
+
+const bundled = (id: string): FontRef => ({ kind: "bundled", id });
+
+export const FONT_PAIRINGS: readonly FontPairing[] = [
+  { id: "quiet-press", label: "Quiet Press", body: bundled("literata"), heading: bundled("literata") },
+  { id: "classic", label: "Classic", body: bundled("eb-garamond"), heading: bundled("eb-garamond") },
+  { id: "editorial", label: "Editorial", body: bundled("source-serif"), heading: bundled("fraunces") },
+  { id: "modern", label: "Modern", body: bundled("lora"), heading: bundled("hanken") },
+  { id: "contrast", label: "Contrast", body: bundled("literata"), heading: bundled("hanken") },
+  { id: "plain", label: "Plain", body: bundled("hanken"), heading: bundled("hanken") },
+];
+
+/** What a page is set in until somebody says otherwise: the css/tokens.css pair, in FontRef form. */
+export const DEFAULT_FONTS: FontPair = { body: bundled("literata"), heading: bundled("literata") };
+
+// The two tails from css/tokens.css, so a face that fails to load falls back to what the app would
+// have used anyway rather than to the webview's default.
+const SERIF_FALLBACK = `Georgia, "Times New Roman", serif`;
+const SANS_FALLBACK = `ui-sans-serif, system-ui, -apple-system, sans-serif`;
+
+export function bundledFont(id: string): BundledFont | undefined {
+  return BUNDLED_FONTS.find((f) => f.id === id);
+}
+
+/**
+ * A `FontRef` as one string, which is what a `<select>` value and a stored preference both need.
+ *
+ * The two-character tag is the whole point: a system family can be called "Literata" and must not
+ * come back as the bundled one.
+ */
+export function encodeRef(ref: FontRef): string {
+  return ref.kind === "bundled" ? `b:${ref.id}` : `s:${ref.family}`;
+}
+
+export function decodeRef(value: string): FontRef {
+  return value.startsWith("s:")
+    ? { kind: "system", family: value.slice(2) }
+    : { kind: "bundled", id: value.slice(2) };
+}
+
+/** The bare family name, which is what a Typst preamble names a face by. */
+export function fontFamilyName(ref: FontRef): string {
+  if (ref.kind === "system") return ref.family;
+  return bundledFont(ref.id)?.family ?? "Literata";
+}
+
+/** What a picker calls it. Identical to the family for a system face, which has no other name. */
+export function fontLabel(ref: FontRef): string {
+  if (ref.kind === "system") return ref.family;
+  return bundledFont(ref.id)?.label ?? ref.id;
+}
+
+/** A CSS font stack, which is what goes into `--font-book` and `--font-heading`. */
+export function fontStack(ref: FontRef): string {
+  if (ref.kind === "bundled") {
+    const font = bundledFont(ref.id);
+    if (!font) return `"Literata", ${SERIF_FALLBACK}`;
+    return `"${font.family}", ${font.category === "sans" ? SANS_FALLBACK : SERIF_FALLBACK}`;
+  }
+  return `"${ref.family}", ${SERIF_FALLBACK}`;
+}
+
+export function refsEqual(a: FontRef, b: FontRef): boolean {
+  if (a.kind === "bundled" && b.kind === "bundled") return a.id === b.id;
+  if (a.kind === "system" && b.kind === "system") return a.family === b.family;
+  return false;
+}
+
+export function fontsEqual(a: FontPair, b: FontPair): boolean {
+  return refsEqual(a.body, b.body) && refsEqual(a.heading, b.heading);
+}
+
+/** Which preset this pair is, or null for a combination somebody built themselves. */
+export function pairingFor(fonts: FontPair): string | null {
+  const match = FONT_PAIRINGS.find(
+    (p) => refsEqual(p.body, fonts.body) && refsEqual(p.heading, fonts.heading),
+  );
+  return match?.id ?? null;
+}
+
+/**
+ * The faces an export has to be handed, split by where their bytes come from.
+ *
+ * Bundled faces come back as ids rather than as records, because the id is what crosses the IPC
+ * boundary: the backend already has the bytes compiled in and looks them up by id. Deduplicated,
+ * because the common case is one family in both slots and asking the backend to load a two megabyte
+ * variable file twice is two megabytes of IPC for nothing.
+ */
+export function fontsUsed(fonts: FontPair): { bundled: string[]; system: string[] } {
+  const usedBundled = new Set<string>();
+  const usedSystem = new Set<string>();
+  for (const ref of [fonts.body, fonts.heading]) {
+    if (ref.kind === "bundled") {
+      if (bundledFont(ref.id)) usedBundled.add(ref.id);
+    } else {
+      usedSystem.add(ref.family);
+    }
+  }
+  return { bundled: [...usedBundled], system: [...usedSystem] };
+}
+
+/** Anything that is not a `FontRef`, from a stored preference written by another version. */
+export function isFontRef(value: unknown): value is FontRef {
+  if (typeof value !== "object" || value === null) return false;
+  const ref = value as { kind?: unknown; id?: unknown; family?: unknown };
+  if (ref.kind === "bundled") return typeof ref.id === "string" && bundledFont(ref.id) !== undefined;
+  return ref.kind === "system" && typeof ref.family === "string" && ref.family !== "";
+}

shared/src/icons.ts

@@ -0,0 +1,61 @@
+// The title bar glyphs, drawn on a 24 unit grid for a 1.6 stroke.
+//
+// Here because the two apps kept drifting. Each had its own idea of what a search or a moon looked
+// like, they were adjusted independently, and the result was two products from the same hand that
+// did not look related. A path is a design decision, not a detail, and the fix for two copies of a
+// decision is one copy.
+//
+// Paths and not an icon dependency: a set is six hundred kilobytes for the handful of shapes a
+// title bar needs, and every one of these is a few dozen bytes.
+//
+// Each app renders these through its own `Icon` component. The two components are identical today
+// and are deliberately not shared: one is React, which would make this package depend on React for
+// twenty four lines, and a component is where an app is entitled to differ.
+
+/** A pane and its divider. Also the preview dock in Margin, mirrored. */
+export const SIDEBAR = "M3 4.5h18v15H3zM9 4.5v15";
+
+/** Margin's preview dock: the same pane with the divider on the other side. */
+export const DOCK = "M3 4.5h18v15H3zM14 4.5v15";
+
+export const SEARCH = "M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM20 20l-4-4";
+
+/** A capital A with a tick beside it: the letter a checker is looking at, checked. */
+export const SPELLING = "M4 17l4-10 4 10M5.4 13.4h5.2M15 17l2.5 2.5L22 14";
+
+/** Three lines of a paragraph and a squiggle under the last, which is the mark grammar leaves. */
+export const GRAMMAR = "M4 7h16M4 12h12M4 17h7M13.5 18.5c1-1.2 2-1.2 3 0s2 1.2 3 0";
+
+/**
+ * A capital A beside a lowercase a, which is what a font panel has been called since there were
+ * font panels.
+ *
+ * Two letterforms and not one on a rule: a letter over a full width line is the underline button in
+ * every editor anybody has used. The other constraint is SPELLING above, which is also built on a
+ * capital A; what separates them is the shape to its right, a round bowl here and an angular tick
+ * there, and that difference survives 16px in a way a crossbar's height would not.
+ */
+export const FONT =
+  "M2.5 18L6.5 6l4 12M4.3 14.2h4.4M17 11.3a3.2 3.2 0 1 0 0 6.4a3.2 3.2 0 0 0 0-6.4M20.2 11.3v6.7";
+
+/** The page's two edges with a double headed arrow between them. */
+export const WIDTH = "M3 5v14M21 5v14M7 12h10M7 12l3-3M7 12l3 3M17 12l-3-3M17 12l-3 3";
+
+export const EXPORT = "M5 13v6h14v-6M12 16V3M8 7l4-4 4 4";
+
+export const MOON = "M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z";
+
+/**
+ * The sun, which is the one glyph here that is not a single path: the disc has to be a circle so
+ * that it stays round at every size, and the rays have to be a path so that they keep their caps.
+ * Rendered as two children rather than one `d`.
+ */
+export const SUN_RAYS =
+  "M12 2v2M12 20v2M2 12h2M20 12h2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M19.1 4.9l-1.4 1.4M6.3 17.7l-1.4 1.4";
+export const SUN_DISC = { cx: 12, cy: 12, r: 4 } as const;
+
+export const MORE = "M5 12h.01M12 12h.01M19 12h.01";
+
+export const CLOSE = "M6 6l12 12M18 6L6 18";
+
+export const CHECK = "M20 6L9 17l-5-5";

shared/src/index.ts

@@ -0,0 +1,5 @@
+// Everything both apps draw from. Two entry points as well as this one, `margin-shared/fonts` and
+// `margin-shared/icons`, so a module that only wants the glyphs does not pull in the catalogue.
+
+export * from "./fonts";
+export * as icons from "./icons";

simplify/.research/build-tooling.md

@@ -0,0 +1,450 @@
+# Build and developer tooling across the four apps
+
+Scope: package.json, lockfiles, vite, tsconfig, index.html, justfiles, scripts, gitignore, nix,
+editor config, Cargo profiles, capabilities. Not CI, signing or tests, bar where build leaks in.
+
+Paths: margin `/Users/pj/Workspace/projects/python/margin`, margin-calendar
+`/Users/pj/Workspace/projects/python/margin-caledar`, margin-docs
+`/Users/pj/Workspace/projects/rust/margin-editor`, margin-mail
+`/Users/pj/Workspace/projects/rust/margin-mail`. Cites below are relative to those roots.
+
+## Five findings first
+
+1. **margin-docs cannot install on a fresh clone or on its own CI.** Its `package.json:33` asks for
+   `"margin-shared": "file:../../python/margin/shared"` but `.github/workflows/ci.yml:19` does one
+   checkout. The frontend job dies inside `pnpm install --frozen-lockfile` with exit 254; four of
+   the last five runs failed (run 33308997470, 2026-08-30: `rust: success`, `frontend: failure`).
+   margin-mail is the only app that solved it, with a second checkout of `priyanshujain/margin`
+   into `python/margin` (`.github/workflows/ci.yml:26-31`, `release.yml:109`).
+2. **The four tsconfigs are three identical files plus one that differs by two lines.** md5 of
+   margin, margin-calendar and margin-docs `tsconfig.json` is `468c4a26...`; margin-mail differs
+   only in `target` and `lib`. All four `tsconfig.node.json` are byte identical (`767b2e9a...`).
+3. **The three justfiles are one file with the product name swapped**, plus two extra recipes and a
+   signing block in margin-mail. margin has no justfile at all, so the "every fix ends with
+   `just install`" rule is unenforceable there.
+4. **No prettier, no eslint, no biome, no .editorconfig, no rustfmt.toml, no rust-toolchain file in
+   any of the four.** Confirmed by search over the repo roots and by grep over each package.json.
+   The only editor config is `margin/.vscode/extensions.json`, two recommendations, and no sibling
+   has one.
+5. **Nix exists only in margin-calendar** and is a publishing artifact, not a toolchain: it
+   repackages the released `.deb`. Worth copying per app, but not shared build config.
+
+## package.json
+
+### Scripts
+
+| script | margin | calendar | docs | mail |
+| --- | --- | --- | --- | --- |
+| `dev` | `vite` | `vite` | `vite` | `vite` |
+| `build` | `tsc && vite build` | same | same | same |
+| `preview` | `vite preview` | same | same | same |
+| `tauri` | `tauri` | same | same | same |
+| `dmg` | `tauri build --bundles dmg` (`:11`) | absent | absent | absent |
+| `test` | absent | `vitest run` | `vitest run` | `vitest run` |
+| `test:watch` | absent | `vitest` | `vitest` | `vitest` |
+| `test:ui` | absent | `playwright test` | `playwright test` | `playwright test` |
+| `fonts:sync` | `node node_modules/margin-shared/bin/sync-fonts.mjs .` (`:12`) | absent | same (`:15`) | `margin-shared-fonts .` (`:15`) |
+| `fonts:check` | same with `--check` (`:13`) | absent | same (`:16`) | `margin-shared-fonts . --check` (`:16`) |
+
+Two drifts worth folding: margin and margin-docs invoke the font sync by path into `node_modules`,
+margin-mail uses the `margin-shared-fonts` bin the package already declares
+(`python/margin/shared/package.json:16-18`) and which is linked in all three consumers. The bin form
+is the correct one. margin-calendar has no font sync and vendors four files under `public/fonts`
+against eighteen in the others, so it is not on the shared face set.
+
+`license` also drifts: `"SEE LICENSE IN LICENSE"` in margin (`:41`) and mail (`:5`), `"MIT"` in
+calendar (`:5`) and docs (`:3`), matching `LicenseRef-FSL-1.1-MIT` and `MIT` respectively in the
+Cargo manifests. Consistent within an app, but the four are not on one licence.
+
+### Version drift (declared spec, then what the lockfile resolved)
+
+| package | margin | calendar | docs | mail |
+| --- | --- | --- | --- | --- |
+| react, react-dom | `^19.1.0` -> 19.2.7 | `^19.1.0` -> 19.2.8 | 19.2.8 | 19.2.8 |
+| vite | `^7.0.4` -> 7.3.5 | 7.3.6 | 7.3.6 | 7.3.6 |
+| typescript | `~5.8.3` -> 5.8.3 | 5.8.3 | 5.8.3 | 5.8.3 |
+| @vitejs/plugin-react | `^4.6.0` -> 4.7.0 | 4.7.0 | 4.7.0 | 4.7.0 |
+| vitest | absent | `^3.2.4` -> 3.2.7 | 3.2.7 | 3.2.7 |
+| @playwright/test | absent | 1.62.1 | 1.62.1 | 1.62.1 |
+| zustand | `^5.0.14` -> 5.0.14 | 5.0.14 | 5.0.15 | 5.0.15 |
+| @types/react | 19.2.17 | 19.2.18 | 19.2.18 | 19.2.18 |
+| @types/react-dom | 19.2.3 | 19.2.4 | 19.2.4 | 19.2.7 |
+| @types/node | absent | absent | `^22.20.1` -> 22.20.1 | `^24.0.0` -> 24.13.3 |
+| @tauri-apps/api | `^2` -> 2.11.1 | 2.11.1 | 2.11.1 | 2.11.1 |
+| @tauri-apps/cli | `^2` -> 2.11.3 | 2.11.4 | 2.11.4 | 2.11.4 |
+| plugin-opener | 2.5.4 | 2.5.4 | 2.5.4 | 2.5.5 |
+| plugin-process | 2.3.1 | 2.3.1 | 2.3.1 | 2.3.1 |
+| plugin-updater | 2.10.1 | 2.10.1 | 2.10.1 | 2.11.0 |
+| plugin-dialog | `^2.7.1` -> 2.7.1 | absent | `^2` -> 2.7.2 | absent |
+| plugin-notification | absent | absent | absent | 2.4.0 |
+| plugin-os | absent | absent | absent | 2.3.2 |
+| tiptap | `^3.27.1` -> 3.27.1 | absent | `3.30.2` exact | `^3.31.2` -> 3.31.2 |
+
+Nothing here is a real incompatibility. Every spec except margin-docs' tiptap is a caret or tilde,
+so the drift is purely "when was `pnpm install` last run here": margin is the stale one, a patch
+behind on react and vite and two `@types` bumps behind. The one deliberate difference is margin-docs
+pinning tiptap exactly at 3.30.2 (`package.json:24-28`) while the others float.
+
+`@types/node` is the only genuine split: 22 in docs, 24 in mail, absent in the other two. Since
+`tsconfig.json` in all four sets no `types` array, the presence of `@types/node` silently changes
+what global names typecheck per app.
+
+No app declares a `packageManager` field, so nothing pins pnpm from the repo itself.
+
+## The margin-shared relative path
+
+- margin: `"margin-shared": "file:./shared"` (`package.json:26`), inside its own repo, and the
+  directory is tracked (26 files under `shared/`).
+- margin-docs: `"file:../../python/margin/shared"` (`package.json:33`).
+- margin-mail: `"file:../../python/margin/shared"` (`package.json:27`).
+
+The lockfiles record the literal relative string, with no integrity hash:
+`rust/margin-mail/pnpm-lock.yaml:918` is `margin-shared@file:../../python/margin/shared:` with
+`resolution: {directory: ../../python/margin/shared, type: directory}` and the snapshot at
+`:1957` is `{}`. Same shape at `rust/margin-editor/pnpm-lock.yaml:1449`.
+
+How fragile: pnpm resolves the path relative to the importer directory, so the dependency is not
+"the margin repo", it is "two directories up, then `python/margin/shared`". That encodes PJ's local
+grouping (`Workspace/projects/python`, `Workspace/projects/rust`) into a committed manifest.
+
+- **Fresh clone.** Cloning margin-mail into `~/code/margin-mail` makes the target
+  `/Users/pj/python/margin/shared`. `pnpm install` then stops with
+  `ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND  Could not install from "..." as it does not exist.`
+  (reproduced directly, exit non-zero, nothing installed). This is not a warning that degrades to a
+  missing font, it is a hard install failure before any other dependency lands.
+- **CI.** margin-mail works only because `ci.yml:26-31` checks the sibling out at the exact path
+  `python/margin` and runs everything with `working-directory: rust/margin-mail`. margin-docs does
+  not do this and its frontend job has been red since the dependency landed.
+- **Anyone else.** A contributor must clone two repositories into a two-level layout whose folder
+  names (`python`, `rust`) mean nothing to them and appear in no documentation. The margin repo is
+  public, so it is possible, just undiscoverable.
+- **Reproducibility.** A directory dependency has no hash, so `pnpm install --frozen-lockfile`
+  consumes whatever is in `shared/` at that moment, uncommitted edits included. The lockfile is not
+  frozen with respect to shared code.
+- **Publishing.** `shared/package.json:4` is `"private": true`, so today it cannot go to a registry
+  without a deliberate change.
+
+Three ways out, in order of how much they cost:
+
+1. **Give shared its own repo and depend on a git tag.** Removes the path assumption entirely and
+   gets an immutable resolution. npm and pnpm git dependencies cannot point at a subdirectory, so
+   this means moving `shared/` out of the margin repo, which also fixes margin depending on it via
+   `file:./shared`.
+2. **Publish `margin-shared` to npm** (or a GitHub npm registry) and depend on a version. Same
+   benefit, plus a real integrity hash in the lockfile. Costs a publish step per change to shared.
+3. **Keep the relative path but make it discoverable and enforced:** an `.env`-style documented
+   layout, a preinstall check that fails with a readable message instead of pnpm's error, and the
+   second checkout added to margin-docs CI. This is the cheap fix and it leaves the reproducibility
+   hole open.
+
+If a shared toolchain package is going to exist anyway, it should be delivered the same way as
+whatever is chosen here, and the two should not use different mechanisms.
+
+## pnpm and workspaces
+
+All four lockfiles are `lockfileVersion: '9.0'` (line 1) with identical settings blocks
+(`autoInstallPeers: true`, `excludeLinksFromLockfile: false`). No `pnpm-workspace.yaml` and no
+`.npmrc` in any of the four. There is no workspace today and no way to create one across four git
+repos without either submodules or a monorepo merge.
+
+Local installs all report `packageManager: [email protected]` in `node_modules/.modules.yaml`, which is
+install state rather than a committed pin; CI pins `pnpm/action-setup@v6` `version: 10` and node 26.
+
+## vite.config.ts
+
+Ports, which are the one thing that must stay per app and are correctly staggered:
+
+| app | server.port | hmr.port | tauri devUrl |
+| --- | --- | --- | --- |
+| margin | 1420 (`:17`) | 1421 (`:23`) | `http://localhost:1420` |
+| calendar | 1430 (`:13`) | 1431 (`:20`) | `http://localhost:1430` |
+| docs | 1440 (`:23`) | 1441 (`:30`) | `http://localhost:1440` |
+| mail | 1450 (`:16`) | 1451 (`:22`) | `http://localhost:1450` |
+
+Everything else in the file is the same four properties: `plugins: [react()]`,
+`clearScreen: false`, `strictPort: true`, `host: host || false` where `host` is
+`process.env.TAURI_DEV_HOST` behind a `@ts-expect-error` comment in all four (`:4-5` in each), the
+same conditional `hmr` block, and `watch.ignored`.
+
+Real differences:
+
+- margin imports `defineConfig` from `"vite"` (`:1`) and exports an async factory,
+  `defineConfig(async () => ({ ... }))` (`:8`), for no reason visible in the file. The other three
+  import from `"vitest/config"` and export a plain object, because they carry a `test` block.
+- margin ignores `"**/website/**"` as well as src-tauri (`:29`); the others ignore only src-tauri.
+- margin-docs is the only one with a `build` block: `assetsInlineLimit` as a function that returns
+  `false` for `woff2?|ttf|otf|eot` (`:19`), because the app CSP is `font-src 'self'` and a data URI
+  font would be refused.
+- The `test` blocks: calendar and mail are identical (`include: ["src/**/*.test.ts"]`,
+  `environment: "node"`); docs adds `maxWorkers: "50%"`, `testTimeout: 30_000`,
+  `hookTimeout: 30_000`, `teardownTimeout: 30_000` (`:57-69`).
+
+Nothing in any of the four sets `define`, `envPrefix`, `resolve.alias`, `build.target`, `minify` or
+`sourcemap`. So there is no alias story to preserve and no env prefix convention to standardise.
+
+## tsconfig.json and tsconfig.node.json
+
+`tsconfig.json` is identical in margin, calendar and docs. margin-mail differs in exactly two
+options:
+
+- `"target": "ES2022"` versus `"ES2020"` (`rust/margin-mail/tsconfig.json:3`)
+- `"lib": ["ES2022", "DOM", "DOM.Iterable"]` versus `["ES2020", ...]` (`:5`)
+
+Everything else matches across all four: `useDefineForClassFields`, `module: "ESNext"`,
+`skipLibCheck`, `moduleResolution: "bundler"`, `allowImportingTsExtensions`, `resolveJsonModule`,
+`isolatedModules`, `noEmit`, `jsx: "react-jsx"`, `strict`, `noUnusedLocals`, `noUnusedParameters`,
+`noFallthroughCasesInSwitch`, `include: ["src"]`, and a reference to `./tsconfig.node.json`.
+
+`tsconfig.node.json` is byte identical in all four: `composite`, `skipLibCheck`, `module: ESNext`,
+`moduleResolution: bundler`, `allowSyntheticDefaultImports`, `include: ["vite.config.ts"]`.
+
+`tests/tsconfig.json` exists in calendar, docs and mail (margin has no tests directory). Calendar
+and docs are byte identical. margin-mail adds `"types": ["node"]` (`:16-18`) and is written with
+one array element per line, which is a formatting drift nothing enforces.
+
+Nothing runs `tests/tsconfig.json`. `pnpm build` is `tsc && vite build`, and root `tsc` only sees
+`include: ["src"]`. No package.json script, justfile recipe or workflow step in any of the three
+references it. The Playwright specs are therefore type checked by nobody.
+
+None of the four sets `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`,
+`verbatimModuleSyntax` or `paths`.
+
+## index.html
+
+Identical structure in all four: `<!doctype html>`, `lang="en"`, `charset=UTF-8`, a title, a
+`<div id="root">`, and `<script type="module" src="/src/main.tsx">`.
+
+- Viewport: margin, calendar and mail use `width=device-width, initial-scale=1.0,
+  maximum-scale=1.0, user-scalable=no, viewport-fit=cover`; docs drops `viewport-fit=cover` (`:5`).
+- Favicon: `/margin-mark.png`, `/margincal-mark.png`, `/marginmail-mark.png`. margin-docs has no
+  `<link rel="icon">` at all and no mark in `public/`.
+- No CSP meta tag and no font preload in any of the four. The real CSP is in
+  `src-tauri/tauri.conf.json` under `app.security.csp`, and it differs per app for good reasons:
+  margin and docs add `worker-src 'self' blob:`, docs adds `asset: http://asset.localhost` to
+  `img-src`, mail adds `frame-src 'self'`.
+- Every one has an inline pre-paint script that reads localStorage and sets attributes on
+  `documentElement` before React boots. They share a shape (theme resolution against
+  `prefers-color-scheme`, then app specific attributes) but every key is app prefixed
+  (`margin-theme`, `margincal-theme`, `marginmail-theme`, `margindocs-theme`) and each sets
+  different things. margin-docs is the only one that reads keys individually rather than wrapping
+  the lot in one `try` (`:13-19`), which is the better version: a webview that refuses storage
+  still gets the theme. The other three lose everything after the first throw.
+
+That inline script is the one genuinely shared idea in these files, and it is the hardest to share,
+because it must be inline and cannot import.
+
+## justfiles
+
+margin has none. calendar, docs and mail have one, and the three are the same file with names
+substituted; `diff` between calendar and docs is nine hunks, all of them the product name, the
+process name or a comment reflow.
+
+| recipe | calendar | docs | mail | bodies match |
+| --- | --- | --- | --- | --- |
+| `default` (`@just --list`) | yes | yes | yes | identical |
+| `dev` (`pnpm tauri dev`) | yes | yes | yes | identical |
+| `test` (`pnpm test` then `cd src-tauri && cargo test`) | yes | yes | yes | identical |
+| `test-ui` (`pnpm test:ui`) | yes | yes | yes | identical, comment differs in mail |
+| `guide-shots` | no | no | yes (`:29-30`) | mail only |
+| `docs` (`node scripts/docs-check.mjs`) | no | no | yes (`:33-34`) | mail only |
+| `build` | yes | yes | yes | same except mail's signing block |
+| `install` (depends on `build`) | yes | yes | yes | identical |
+| `_install-macos` | yes | yes | yes | docs omits the final `open "$dest"` |
+| `_install-linux` | yes | yes | yes | identical bar names and the desktop entry |
+| `uninstall` | yes | yes | yes | identical bar names |
+
+Shared variables: `set shell := ["bash", "-euo", "pipefail", "-c"]`, `app`, `bundle :=
+"src-tauri/target/release/bundle"`.
+
+Substantive differences:
+
+- margin-mail's `build` sources a signing env file before building
+  (`rust/margin-mail/justfile:46-54`): it reads
+  `"${MARGIN_SIGNING_DIR:-$HOME/.margin-signing}/studio.margin.app.env"`. Note the file name is
+  `studio.margin.app`, which is margin's bundle identifier, not `studio.margin.mail`. If the intent
+  is one env file for the whole suite the name is misleading; if it is one per app, this is wrong.
+- margin-docs' `_install-macos` does not `open "$dest"` at the end (compare `justfile:77` in docs
+  with `:78` in calendar and `:97` in mail). So `just install` starts the new build in two of the
+  three apps and not the third.
+- Only margin-mail has a prose gate recipe.
+
+Because the rule is that a fix ends with `just install`, the gap that matters is margin: its only
+local build path is `pnpm dmg` (`package.json:11`), and nothing copies a bundle into
+`/Applications`. The three justfiles already prove the body is app independent bar four names, so
+margin is a paste plus a variable block away from the same command.
+
+## scripts directories
+
+Only two apps have one and they do unrelated things.
+
+- `margin/scripts` is twelve files of Apple release plumbing: `apple-provision.rb`,
+  `apple-secrets.sh`, `appstore-compliance.rb`, `appstore-listing.rb`,
+  `appstore-review-detail.rb`, `appstore-screenshots.rb`, `mas-package.sh`, `mas-upload-local.sh`,
+  `testflight-release.rb`, `testflight-setup.rb`, `testflight-testers.rb`. This is the App Store
+  path and only margin is on it, so it stays where it is (and overlaps the signing agent's scope).
+- `margin-mail/scripts` is one file, `docs-check.mjs`, 72 lines: no em or en dash anywhere
+  including in code fences, no directory tree (box glyph run or three consecutive ASCII tree
+  lines), no broken relative link. It walks every `.md` in the repo, skipping
+  `node_modules, dist, target, .git, gen, .playwright-mcp`.
+
+`docs-check.mjs` is the clearest single candidate for sharing: no dependencies, no app specific
+knowledge, and it enforces a house rule that applies to all four repos. It belongs in the shared
+package with a bin, like `sync-fonts.mjs` (exposed as `margin-shared-fonts`).
+
+## .gitignore
+
+Common core in all four, in the same order: log patterns, `node_modules`, `dist`, `dist-ssr`,
+`*.local`, the editor block (`.vscode/*` with `!.vscode/extensions.json`, `.idea`, `.DS_Store`,
+`*.sw?`), `src-tauri/target/`, `.playwright-mcp/`, `/*.png`.
+
+Differences:
+
+- `src-tauri/gen/schemas/` is ignored in calendar (`:27`), docs (`:27`) and mail (`:21`), but not
+  in margin. margin therefore can commit generated schema files.
+- The Xcode block (`src-tauri/gen/apple/build/`, `Externals/`, `Pods/`, `Podfile.lock`,
+  `xcuserdata/`) is in calendar (`:32-36`), docs (`:32-36`) and mail (`:25-29`), not margin.
+- Google credentials (`/google-credentials.json`, `/client_secret_*.json`) in margin (`:30-31`),
+  calendar (`:39-40`) and mail (`:33-34`), not docs, which needs none.
+- margin only: `target-mas/` and two App Store review contact files (`:38-42`).
+- docs only: `.env`, `.env.*`, `!.env.example` (`:43-45`), the updater signing key.
+- calendar only: `/result`, `/result-*` (`:47-48`), the nix build symlinks.
+- mail only: `/screenshots/` (`:41`).
+- margin-mail trims the editor block hardest (no `*.suo`, `*.ntvs*`, `*.njsproj`, `*.sln`).
+
+A shared base of about twenty lines would cover everything up to `/*.png`, with five to eight app
+specific lines after it. Git has no include mechanism for ignore files and `core.excludesFile` is
+per machine, so this is one of the things that stays copied.
+
+## Nix in margin-calendar
+
+`flake.nix` is 21 lines: one input (`nixpkgs` at `nixos-unstable`, locked in `flake.lock` at rev
+`3ed67ec0a4d3c7ab4ae1f04f8ee8df07bfa506a2`), an overlay and a single `x86_64-linux` package that
+calls `./nix/package.nix`. `nix/package.nix` fetches the published `.deb` from the GitHub release
+named in `nix/release.json` (`{"version": "0.0.5", "hash": "sha256-+bEQO..."}`), unpacks it with
+`dpkg-deb -x`, relinks it with `autoPatchelfHook` and `wrapGAppsHook3` against nixpkgs' gtk3,
+`webkitgtk_4_1`, `libsoup_3` and friends, writes a launcher that points `libglvnd` at nixpkgs' mesa
+when `/run/opengl-driver` is absent, shims `xdg-open` to strip those variables again, and sets
+`MARGIN_CALENDAR_PACKAGED_BY=nix` so the in-app updater reports rather than replaces itself.
+
+`docs/release.md:41-81` gives the rationale: the AppImage bundles Ubuntu's GTK stack and a bundled
+`libwayland-client` cannot talk to a current compositor, so on Hyprland it falls back to Xwayland.
+It is binary by necessity, because the Google OAuth client is embedded at compile time from a file
+that is not in the repo.
+
+Is this the Linux distribution path, and should the others adopt it? Yes for margin-mail, same
+Google client problem and same GTK and WebKit runtime; yes for margin-docs if it ships Linux, which
+its justfile already builds for. margin is macOS and App Store shaped and would gain nothing.
+
+But note what is actually shared here: almost nothing. The flake is fifteen lines of boilerplate and
+`package.nix` is a hundred lines of which the app name, the deb URL, the desktop file rename, the
+env variable name and the meta block are all per app, and the rest (the hooks, the buildInputs list,
+the mesa launcher, the xdg-open shim) is genuinely common. If two apps adopt it, that common part
+should be a function in the shared repo that each flake calls with a name, a repo and a release pin.
+Below two adopters, copy it.
+
+## Editor, formatter and linter config
+
+Confirmed absent everywhere: prettier (no config file, no dependency, no script in any of the four
+package.json files), eslint, biome, `.editorconfig`, `rustfmt.toml`, `clippy.toml`,
+`rust-toolchain.toml`, `.nvmrc`.
+
+Present: `margin/.vscode/extensions.json`, two recommendations
+(`tauri-apps.tauri-vscode`, `rust-lang.rust-analyzer`). No other app has a `.vscode` directory,
+though all four gitignore `.vscode/*` while un-ignoring `extensions.json`, so the intent is there.
+
+`margin-editor/src-tauri/.cargo/config.toml` is the only cargo config: `[env] RUST_TEST_THREADS =
+"1"`, for a suite that shares one on-disk git repository. App specific, stays.
+
+The consistent formatting across all these files (two space JSON, 100 column comments, the same
+comment voice) is being maintained by hand. That works while one person writes everything, and the
+one place it has already slipped is `rust/margin-mail/tests/tsconfig.json`, which is the same file
+as its siblings reformatted with expanded arrays.
+
+## Cargo
+
+No `[workspace]` section in any of the four manifests, so each `src-tauri` is its own workspace root
+with its own `Cargo.lock` (margin 964 packages, calendar 565, docs 962, mail 668).
+
+Profiles: only margin (`src-tauri/Cargo.toml:78-79`) and margin-docs (`:107-108`) set anything,
+both `[profile.dev.package."*"] opt-level = 3` with near identical comments about Harper's grammar
+engine being ten times slower unoptimized. No `[profile.release]` anywhere, so release builds are
+cargo defaults in all four and there is no `lto`, `codegen-units` or `strip` setting to align.
+
+Duplication worth noting: margin and margin-docs both carry `[patch.crates-io]` stubs for
+`burn-cuda` and `cubecl-cpu` (`margin:70-72`, `docs:98-100`) plus a `stubs/` directory each with the
+same two skeleton crates at the same versions (`burn-cuda` 0.19.1, `cubecl-cpu` 0.8.1) and nearly
+the same comments. This is real shared code, kept in sync by hand, and it is tied to
+`harper-core = "=2.5.0"` in both.
+
+A shared cargo workspace across the four is not feasible. A workspace requires one filesystem root
+containing all members with paths in the root manifest, which means one git repository. These are four
+repositories with independent release tags and version numbers, and margin-mail has no remote
+configured yet. Without merging, the one thing worth extracting is a shared crate for the harper
+stubs behind a git dependency, which deletes both copied `stubs/` directories.
+
+## Capabilities
+
+All four have exactly `capabilities/default.json` and `capabilities/desktop.json`, both pointing at
+`../gen/schemas/desktop-schema.json`, both scoped to `windows: ["main"]`, with desktop gated on
+`platforms: ["macOS", "windows", "linux"]`. No `permissions/` directory in any app.
+
+| app | default permissions | desktop permissions |
+| --- | --- | --- |
+| margin | `core:default`, `core:window:allow-destroy`, `core:window:allow-start-dragging`, `opener:default`, `dialog:default` | `updater:default`, `process:allow-restart` |
+| calendar | `core:default`, `opener:default`, `deep-link:default` | the two window permissions, `updater:default`, `process:allow-restart` |
+| docs | `core:default`, `opener:default`, `dialog:default` | the two window permissions plus `core:window:allow-toggle-maximize`, `updater:default`, `process:allow-restart` |
+| mail | `core:default`, `opener:default`, `deep-link:default`, `notification:default`, `os:default` | the two window permissions, `updater:default`, `process:allow-restart` |
+
+margin is the odd one: it puts the two window permissions in `default` rather than `desktop`, so a
+mobile build would ask for them. `desktop.json` is identical in calendar and mail bar the
+description, and docs differs by one line.
+
+## Recommendation
+
+A shared package (call it `margin-shared` extended, or a second `margin-config` delivered the same
+way) should export exactly five things:
+
+1. **`tsconfig/base.json`.** Everything currently duplicated, with `target` and `lib` at ES2022 for
+   all four, since ES2020 in three of them is a scaffold default nobody chose. Each app keeps a
+   three line `tsconfig.json` that extends it and sets `include` and `references`. Also export
+   `tsconfig/node.json` (byte identical in all four today) and `tsconfig/tests.json` (identical in
+   two of three, one `types` entry apart). Adding `noUncheckedIndexedAccess` is a separate decision
+   and should not ride along with the consolidation.
+2. **A vite config factory**, `marginVite({ port, test })`, returning the plugin, `clearScreen`,
+   the full `server` block derived from one port number, and the `TAURI_DEV_HOST` handling. Ports
+   stay per app and are the argument. margin-docs passes its `assetsInlineLimit`, margin-docs
+   passes its vitest timeouts. The `@ts-expect-error process` comment disappears with it, because
+   the factory can own that line once.
+3. **A justfile include.** `just` supports `import`, so the shared file can hold `default`, `dev`,
+   `test`, `test-ui`, `build`, `install`, `_install-macos`, `_install-linux` and `uninstall`
+   verbatim, parameterised on `app`, `binary`, `comment` and `categories`, which the app justfile
+   sets before importing. Adding this to margin is the change that makes `just install` a real
+   suite-wide rule instead of a rule three of four apps can honour. The import has to resolve to a
+   real path, which lands back on the same delivery question as `margin-shared`.
+4. **`docs-check` as a bin.** Move `margin-mail/scripts/docs-check.mjs` into the shared package
+   beside `sync-fonts.mjs`, expose it as `margin-shared-docs`, and add a `docs` recipe to the shared
+   justfile. It has no app specific content at all.
+5. **The checking story, with no eslint.** Today that is `tsc` under `pnpm build` plus `cargo
+   test`. Two gaps close inside the shared config rather than with a linter: `tests/tsconfig.json`
+   is run by nothing, so add a `typecheck` recipe covering both projects; and `pnpm fonts:check`
+   runs in margin-mail CI only, so it belongs in the shared `test` recipe everywhere.
+
+What has to stay per app, and should not be abstracted:
+
+- The dev server port and the matching `devUrl` in `tauri.conf.json`. Staggering is load bearing:
+  Playwright reuses whatever answers on the port, so a collision means a suite silently driving the
+  wrong app (`rust/margin-mail/vite.config.ts:7-9`).
+- The inline pre-paint script in `index.html`. It cannot import, its storage keys are app prefixed,
+  and it sets different attributes per app. Copy margin-docs' per key `saved()` pattern into the
+  other three by hand.
+- The CSP in `tauri.conf.json`, the capabilities files and `Cargo.toml` dependencies. One shared
+  version would be the union, which is wrong for a suite that does not reach for spare permissions.
+- `.gitignore`, because git cannot include a shared file.
+- The nix flake, unless and until a second app ships Linux through it.
+- margin's `scripts/` App Store tooling, and margin-docs' `src-tauri/.cargo/config.toml`.
+
+Sequencing: the `margin-shared` path problem has to be solved first, because every item above is
+delivered through the same mechanism, and adding four more consumers of a broken relative path makes
+the fresh clone failure four times worse instead of once. Second, add the missing checkout to
+margin-docs CI, which is a red build today for a reason nobody has looked at. Third, give margin a
+justfile.

simplify/.research/ci-release-signing.md

@@ -0,0 +1,448 @@
+# CI, packaging, signing, the updater, distribution
+
+Four repos, four hand-maintained copies of the same release pipeline. This is what is in them, what
+has already drifted, and what a shared version would have to keep per app. Paths: `margin` is
+`/Users/pj/Workspace/projects/python/margin`, `margin-calendar` is
+`/Users/pj/Workspace/projects/python/margin-caledar` (misspelled on disk), `margin-docs` is
+`/Users/pj/Workspace/projects/rust/margin-editor`, `margin-mail` is
+`/Users/pj/Workspace/projects/rust/margin-mail`.
+
+## The workflows
+
+| repo | release.yml | ci.yml | other |
+| --- | --- | --- | --- |
+| margin | 259 lines | none | appstore.yml, 130 lines |
+| margin-calendar | 241 | 81 | |
+| margin-docs | 258 | 78 | |
+| margin-mail | 229 | 92 | |
+
+margin has no CI workflow at all. Nothing checks a push or a pull request there; the first time a
+broken tree is noticed is a release build.
+
+### How near-duplicate the release YAML is
+
+Whole-file changed lines (`diff | grep -c '^[<>]'`) run from 126 (calendar vs mail) through 136
+(margin vs calendar), 144 (margin vs mail), 211 (docs vs mail), 225 (calendar vs docs) to 241
+(margin vs docs). Those numbers overstate the difference, because they count reflowed comment
+blocks. The structural duplication is much worse. The whole `prepare` job, lines 1 to 81 of both
+files, is byte-identical between margin-calendar and margin-mail except for one line: the title at
+`margin-caledar/.github/workflows/release.yml:78` says `Margin Calendar $TAG` and
+`margin-mail/.github/workflows/release.yml:78` says `Margin Mail $TAG`. Nothing else in 81 lines
+differs.
+
+The `publish` job is the same story. `margin-caledar/.github/workflows/release.yml:162-181` against
+`margin-mail/.github/workflows/release.yml:210-229` differs on one line, and that line is
+punctuation inside an error string (calendar still has an em dash at line 177, mail rewrote it as a
+comma). Against margin, `release.yml:199-218`, the only real difference is the platform key list:
+margin checks `darwin-aarch64 darwin-x86_64 linux-x86_64 windows-x86_64` at line 212, the other two
+check the same list without Windows.
+
+Every workflow pins the same actions at the same versions: `actions/checkout@v7`,
+`actions/setup-node@v6` with `node-version: 26`, `pnpm/action-setup@v6` with `version: 10`,
+`dtolnay/rust-toolchain@stable`, `swatinem/rust-cache@v2`, `tauri-apps/tauri-action@v0`,
+`cachix/install-nix-action@v31`, `actions/upload-artifact@v4`. Four copies of one pin set.
+
+### Triggers, permissions, concurrency, caching
+
+All four releases are `workflow_dispatch` only, with one optional `version` string input, and
+`permissions: contents: write` at workflow level. margin's `appstore.yml:16-17` is the one workflow
+with `contents: read`.
+
+No release workflow has a `concurrency` block. Two dispatches at once would both compute a version
+from `tauri.conf.json`, both bump, and race on the push-with-rebase loop at
+`margin/.github/workflows/release.yml:62-74`. The three `ci.yml` files do have one, identical in all
+three (`group: ci-${{ github.ref }}`, `cancel-in-progress: true`): another three-way copy.
+
+Cargo is cached everywhere through `swatinem/rust-cache@v2`. pnpm is cached nowhere: no workflow
+sets `cache: pnpm` on `setup-node`, so every job downloads the whole tree fresh.
+
+### Matrix and runners
+
+margin, `release.yml:88-102`: three rows, `macos-26` universal, `ubuntu-latest`, `windows-latest`.
+Only margin builds Windows, and only margin installs `rpm` (`release.yml:124`). margin-calendar and
+margin-mail, both `release.yml:88-95`: two rows, `macos-26` universal and `ubuntu-22.04`, both
+carrying the same comment about 22.04 being the glibc baseline. margin builds Linux on
+`ubuntu-latest` instead, contradicting the reasoning the other two committed to and producing a
+bundle with a higher glibc floor. margin-docs, `release.yml:111-117`: no matrix, one `macos-26`
+runner, with a good comment on why a matrix of one is where a stale Linux row survives.
+
+margin-mail is the only one that needs two checkouts, `release.yml:101-109`: itself into
+`rust/margin-mail` and `priyanshujain/margin` into `python/margin`, because `package.json` has
+`"margin-shared": "file:../../python/margin/shared"`. That forces `defaults.run.working-directory`
+(`release.yml:97-99`), a different rust-cache workspace path (`release.yml:143`), and
+`projectPath: rust/margin-mail` on the tauri-action (`release.yml:202`).
+
+**margin-docs has the same relative dependency and does not do this.**
+`margin-editor/package.json` declares `margin-shared` at `file:../../python/margin/shared` and
+`pnpm-lock.yaml:1449` records it under that path, but `margin-editor/.github/workflows/ci.yml:19`
+and `release.yml:119` each do a single checkout with no sibling repo. `pnpm install
+--frozen-lockfile` cannot resolve that path. margin-docs CI and margin-docs releases are broken as
+committed. That is the single most concrete cost of copy-paste here: the fix landed in mail and was
+never carried back.
+
+### Which workflow is most evolved
+
+margin-docs, and it is not close. It is the only one that validates the version string before using
+it (`release.yml:38-41`), the only one that bumps `Cargo.toml` with a `[package]`-anchored awk pass
+and then verifies the result (`release.yml:58-75`), the only one whose Apple signing step
+distinguishes "unconfigured" from "half configured" and fails the second case
+(`release.yml:176-189`), the only one that checks the manifest version against the tag
+(`release.yml:227-231`), and the only one that checks `latest.json` carries a signature and not just
+a url (`release.yml:245-255`). Its comments explain why each check exists.
+
+margin is the most complete in scope: the only Windows row, the only App Store workflow, the only
+post-build `codesign`/`spctl`/`stapler` verification (`release.yml:188-197`), the only Homebrew tap
+job (`release.yml:220-259`), and the only bump step that rewrites `Cargo.lock` (`release.yml:47-52`).
+margin-calendar is the only one with a Nix job (`release.yml:187-241`). margin-mail is the plainest:
+the two-repo checkout and nothing else the others lack. Nobody has all of it, and every good idea
+lives in exactly one repo.
+
+## tauri.conf.json side by side
+
+| | margin | margin-calendar | margin-docs | margin-mail |
+| --- | --- | --- | --- | --- |
+| productName | Margin | Margin Calendar | Margin Docs | Margin Mail |
+| version | 0.1.17 | 0.0.5 | 0.0.1 | 0.0.1 |
+| identifier | studio.margin.app | studio.margin.calendar | studio.margin.docs | studio.margin.mail |
+| devUrl port | 1420 | 1430 | 1440 | 1450 |
+| window | 1280x820, min 920x640 | 1360x900, min 880x560 | 1360x900, min 880x600 | 1440x900, min 880x560 |
+| titleBarStyle | Overlay | Overlay | Overlay | Overlay |
+| trafficLightPosition | absent | 9,25 | absent | 9,25 |
+| bundle.targets | `"all"` | app, dmg, appimage, deb | app, dmg | app, dmg, appimage, deb |
+| category | Productivity | Productivity | Productivity | Productivity |
+| macOS.minimumSystemVersion | 10.15 | 10.15 | 10.15 | 10.15 |
+| macOS.hardenedRuntime | true | absent | true | absent |
+| macOS.signingIdentity | absent | absent | absent | `"-"` |
+| linux.deb.depends | absent | webkit2gtk-4.1-0, gtk-3-0 | absent | same as calendar |
+| deep-link plugin | no | yes | no | yes |
+| resources | dictionaries/en | none | none | none |
+| copyright | present | absent | absent | absent |
+
+Line references: `margin/src-tauri/tauri.conf.json:3-5,29,40-47`,
+`margin-caledar/src-tauri/tauri.conf.json:3-5,49-54,65-75`,
+`margin-editor/src-tauri/tauri.conf.json:3-5,29-32,43-46`,
+`margin-mail/src-tauri/tauri.conf.json:3-5,45,56-64`.
+
+`hardenedRuntime` defaults to `true` in tauri-utils
+(`~/.cargo/registry/src/index.crates.io-.../tauri-utils-2.9.3/src/config.rs:682`), so the two that
+omit it get it anyway. Two repos state it and two do not, for no reason.
+
+The CSP is four variations on one string. All four begin `default-src 'self'; img-src 'self' data:
+blob:; font-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self';` and end with
+`connect-src 'self' ipc: http://ipc.localhost`. margin adds `worker-src 'self' blob:`, margin-docs
+adds that plus `asset: http://asset.localhost` to `img-src`, margin-mail adds `frame-src 'self'`,
+margin-calendar adds nothing. Every app declares the same five icon paths.
+
+`bundle.targets: "all"` in margin is why margin gets an rpm and the others do not. It is a default
+rather than a decision.
+
+## Signing and notarisation
+
+Local credentials live in `~/.margin-signing`, overridable with `MARGIN_SIGNING_DIR`. Only two
+repos reference it. In margin: `scripts/apple-provision.rb:39`, `scripts/apple-secrets.sh:8`,
+`scripts/mas-upload-local.sh:15`, documented at `docs/publishing.md:213-226`. In margin-mail:
+`justfile:47` and `docs/release.md:25-26,40`.
+
+The directory holds, by name: three `.p12` files (`developer-id.p12`, `apple-distribution.p12`,
+`mac-installer.p12`) each with a sibling `.pass` file, a `.provisionprofile` named after the bundle
+id, `AuthKey.p8` with `AuthKey.env` beside it holding the key id and issuer, and an env file per
+bundle id (`studio.margin.app.env`) exporting `APPLE_TEAM_ID`, `APPLE_SIGNING_IDENTITY`,
+`MAS_APP_IDENTITY` and `MAS_INSTALLER_IDENTITY`. Private keys are generated locally so Apple only
+ever sees a CSR, and each `.p12` bundles Apple's intermediate so a fresh CI keychain can build a
+chain (`docs/publishing.md:214-218`).
+
+`margin/scripts/apple-secrets.sh` pushes all of it into a repository's Actions secrets by piping
+files straight into `gh secret set` so nothing is echoed (`apple-secrets.sh:17-32`). It is already
+parameterised: `DIR`, `BUNDLE_ID` and `REPO` are env-overridable (`apple-secrets.sh:8-10`). It could
+serve all four repos today and does not, because it lives in one of them. margin-mail's local build
+sources `$MARGIN_SIGNING_DIR/studio.margin.app.env`, hardcoded to margin's bundle id
+(`justfile:47`), which is right in effect (one certificate covers the team) and wrong in shape.
+
+The three release workflows arrive at the same signing step by three different routes.
+margin-calendar has none at all: `release.yml:152-160` passes only the Tauri updater key, so
+calendar ships unsigned macOS bundles. margin writes only the notarisation `.p8` to disk
+(`release.yml:159-171`) and passes the certificate variables directly to the action
+(`release.yml:175-183`). margin-mail exports certificate variables into `$GITHUB_ENV` only when they
+are non-empty, with a heredoc delimiter, and warns twice when they are not
+(`release.yml:167-197`). margin-docs does the same with a random heredoc delimiter and a hard
+failure on the half-configured case (`release.yml:158-197`).
+
+The secret names have drifted. margin uses `APPLE_API_KEY_ID` as the secret and maps it to
+`APPLE_API_KEY` in the action environment (`release.yml:183`). margin-mail uses a secret literally
+called `APPLE_API_KEY` (`release.yml:176`). margin-docs uses the Apple ID and app-specific password
+route instead: `APPLE_ID`, `APPLE_PASSWORD`, `APPLE_TEAM_ID` (`release.yml:163-165`), which is the
+one `docs/publishing.md:22-24` explicitly argued against, because the App Store Connect key does
+notarisation and store upload with one credential to rotate.
+
+Only margin verifies the result. `release.yml:188-197` runs `codesign --verify --deep --strict`,
+then `spctl --assess --type execute`, then `xcrun stapler validate`, with a comment that spctl is
+the check a double-clicking user actually meets. No other repo checks that its signed bundle is
+notarised.
+
+### The App Store track
+
+`margin/appstore/` is listing content, not code: one text file per App Store Connect field under
+`appstore/metadata/en-US/` (name, subtitle, description, keywords, promotional_text,
+release_notes, privacy_url, support_url, marketing_url, beta_description), review contact details
+under `appstore/metadata/`, and five 2560x1600 frames under `appstore/screenshots/` that are a CSS
+rebuild of the app rather than a screen capture. `margin/target-mas/` is a build output directory,
+holding `Margin.pkg`; `appstore.yml:125-129` uploads `target-mas/*.pkg` as an artifact.
+
+`scripts/mas-package.sh` covers the distance Tauri does not: it stamps `CFBundleVersion` from the
+workflow run number (`mas-package.sh:27-30`), copies the provisioning profile into the bundle before
+signing, widens permissions so Apple can read every file (`mas-package.sh:33-39`), substitutes
+`__TEAM_ID__` into `entitlements.mas.plist`, signs nested code first and never with `--deep`, then
+`productbuild`s the result (`mas-package.sh:44-58`). `entitlements.mas.plist` declares four
+entitlements, each justified in a comment: app-sandbox, network.client, network.server for the
+loopback OAuth listener, and files.user-selected.read-write. `src-tauri/Info.plist:8-9` declares
+`ITSAppUsesNonExemptEncryption` false. Six Ruby scripts drive the Developer Portal and App Store
+Connect through fastlane's spaceship.
+
+None of this exists in the other three, and calendar and mail both have a Google OAuth loopback
+listener, so if either goes to the store it needs the same entitlement and the same review note.
+
+## The updater
+
+One endpoint per app, all on GitHub releases:
+
+| repo | endpoint | pubkey |
+| --- | --- | --- |
+| margin | `.../priyanshujain/margin/releases/latest/download/latest.json` | real |
+| margin-calendar | `.../margin-calendar/releases/latest/download/latest.json` | real |
+| margin-docs | `.../margin-docs/releases/latest/download/latest.json` | `REPLACE_WITH_TAURI_SIGNER_PUBKEY` |
+| margin-mail | `.../margin-mail/releases/latest/download/latest.json` | `REPLACE_WITH_THE_MINISIGN_PUBLIC_KEY` |
+
+All at line 8 to 11 of each `src-tauri/tauri.release.conf.json`. Two of the four have never had a
+keypair generated, so neither has released.
+
+**All four already use the overlay workaround.** No `tauri.conf.json` carries
+`plugins.updater.pubkey`; all four keep it plus `bundle.createUpdaterArtifacts: true` in
+`tauri.release.conf.json`, merged with `--config src-tauri/tauri.release.conf.json` in the build
+args. What did not propagate is the reason. Only margin records it, and only outside `docs/`:
+`simplify/guidelines/distribution.md:44` and `simplify/.research/memories-raw.md:283` name
+tauri-apps/tauri#14581, that the mere presence of the pubkey makes `tauri build` demand a signing
+key and would break the key-free local build (`margin/package.json` still has `"dmg": "tauri build
+--bundles dmg"` with no overlay). The three sibling `docs/release.md` files describe the overlay as
+"where the public half lives" and give no reason, so the next person to tidy a config has nothing
+telling them not to inline it.
+
+The overlay carries a second job nobody has written down: it is the flag that switches the plugin
+on. Every app registers the plugin conditionally on the merged config, ported verbatim four times:
+`margin/src-tauri/src/lib.rs:159-161`, `margin-caledar/src-tauri/src/lib.rs:260-262`,
+`margin-editor/src-tauri/src/lib.rs:263-265`, `margin-mail/src-tauri/src/lib.rs:265-267`. Two of the
+comments say "Ported from margin's lib.rs" outright.
+
+`margin/src-tauri/src/updates.rs` is the only per-channel logic anywhere. `channel()` at lines 17 to
+26 reads which plugin key the merged config declares, `updater` meaning direct download and
+`appstore` meaning store, and a `_MASReceipt` in the bundle overrides both (lines 28 to 37), so a
+store build cannot self-update even if built with the updater in it. `appstore_latest()` at lines 51
+to 84 asks `itunes.apple.com/lookup` with a cache-busting timestamp. No sibling has or needs this.
+
+Release notes are surfaced but empty. All four create the draft with `--notes "Release $TAG"`
+(`release.yml:78` in calendar, docs and mail; `:84` in margin), tauri-action copies the release body
+into `latest.json`, so `update.body` is the literal string "Release v0.1.18".
+`margin-editor/src/update.ts:79` passes that into `useUpdate.offer(version, notes)`, which
+`store/useUpdate.ts:39` calls "the release notes, as the release wrote them".
+
+The four update UIs are four different things: margin has `src/updater.ts` (111 lines) plus an
+`UpdateDialog.tsx` and a store; margin-docs has the most developed, `src/update.ts` (171 lines) with
+a daily background check, a 6 second launch delay and explicit handling of "this build has no
+updater in it" (`update.ts:39-56`); margin-calendar has a 41 line toast-only version
+(`src/keys/updates.ts`) whose header says it is margin's minus the dialog; margin-mail has no
+updater module, just an inline `checkForUpdates` in `App.tsx:98-118` and a panel in
+`screens/Settings.tsx:2465-2540`.
+
+`packaged_by()` is the Nix escape hatch, ported twice: `margin-caledar/src-tauri/src/lib.rs:240-245`
+reading `MARGIN_CALENDAR_PACKAGED_BY`, `margin-mail/src-tauri/src/lib.rs:197-201` reading
+`MARGIN_MAIL_PACKAGED_BY`. mail reads a variable nothing sets, because mail has no Nix package.
+
+## Versioning
+
+Three files per app, all bumped by the release workflow and by nothing else: `.version` in
+`src-tauri/tauri.conf.json`, `.version` in `package.json`, and `[package] version` in
+`src-tauri/Cargo.toml`. `tauri.conf.json` is the source of truth, since the "leave empty to bump the
+patch" path reads it (`release.yml:31` in all four). All four are consistent right now: margin
+0.1.17, calendar 0.0.5, docs 0.0.1, mail 0.0.1, with `Cargo.lock` matching in each.
+
+Nothing enforces it. There is no check in any `ci.yml` that the three agree, so the only thing
+keeping them together is that a human never edits one by hand.
+
+The `Cargo.lock` problem is history rather than theory. Only margin bumps the lock, with an awk pass
+and a comment explaining that the lock records the crate's own version
+(`margin/.github/workflows/release.yml:47-52`), and it is the only repo that adds `Cargo.lock` to
+the release commit (`:60`). margin-calendar does not, and its history carries two manual repair
+commits for exactly this: `3754e4a Sync the lock file to the version the crate declares` and
+`ae5a7b4 let cargo.lock catch up with the 0.0.4 bump`. docs and mail have the same gap and have not
+released yet.
+
+The bump itself is three different implementations. margin and margin-mail and margin-calendar use
+`sed -i "0,/^version = \".*\"/s//.../"` on `Cargo.toml`, which takes the first `version =` line in
+the file. margin-docs replaced it with a `[package]`-anchored awk pass plus a verification grep
+(`release.yml:58-75`), with a comment explaining that a long-form dependency puts `version = "0.4"`
+on its own line and bumping that one ships the version before. margin-mail's `Cargo.toml` is 6568
+bytes with many long-form dependencies, so it is the repo most exposed to the bug and it has the old
+code.
+
+## Linux, Windows, mobile
+
+What each app actually ships:
+
+| repo | macOS | Linux | Windows | store |
+| --- | --- | --- | --- | --- |
+| margin | universal dmg, signed and notarised, Homebrew cask | deb, rpm, AppImage from ubuntu-latest | msi and nsis from windows-latest | Mac App Store pkg |
+| margin-calendar | universal dmg, unsigned | deb and AppImage from ubuntu-22.04, plus a Nix flake | none | none |
+| margin-docs | universal dmg, ad hoc signed today | none | none | none |
+| margin-mail | universal dmg, ad hoc signed today | deb and AppImage from ubuntu-22.04 | none | none |
+
+margin-calendar's `flake.nix` is 21 lines: one input, one system (`x86_64-linux`), an overlay and a
+package, both calling `nix/package.nix`. That file is 113 lines and repackages the published `.deb`
+rather than building from source, justified at lines 1 to 4 by the OAuth client being embedded at
+compile time from a file that is not in the repo. `autoPatchelfHook` relinks it against nixpkgs'
+webkit2gtk so it runs as a native Wayland client instead of the AppImage's Xwayland fallback, a
+generated launcher points libglvnd at nixpkgs' Mesa when `/run/opengl-driver` is absent
+(`package.nix:68-94`), and `preFixup` sets `MARGIN_CALENDAR_PACKAGED_BY=nix` (`package.nix:98-103`).
+
+`nix/release.json` is the pin, `{version, hash}`, currently 0.0.5. The `nix` job
+(`release.yml:187-241`) runs after publish, downloads the deb, hashes it, writes the pin, builds the
+package as proof, and pushes the pin to main with the same rebase loop as the version bump.
+`ci.yml:74-81` rebuilds it on every push. This replaced an AUR package, rationale at
+`docs/release.md:41-81`; no AUR file is left in the tree.
+
+margin-mail reads `MARGIN_MAIL_PACKAGED_BY` and documents the Nix behaviour at `docs/release.md:116-119`
+but ships no flake, so that path is dead code today.
+
+Mobile is scaffolded in two repos. `margin/src-tauri/gen/apple` is a committed iOS Xcode project;
+`margin-caledar/src-tauri/gen/` has both `apple` and `android` tracked, including
+`app/src/main/java/studio/margin/calendar/MainActivity.kt`. margin-docs and margin-mail have only
+`gen/schemas`, though margin-mail's include `iOS-schema.json` and `mobile-schema.json`.
+
+The desktop-only cfg gating is the same three lines in three repos, with the same comment ("There is
+no auto-updater and no process to restart on a phone: the store is the update channel"):
+`margin-caledar/src-tauri/Cargo.toml:43-46`, `margin-editor/src-tauri/Cargo.toml:84-87`,
+`margin-mail/src-tauri/Cargo.toml:134-137`, each gating `tauri-plugin-process` and
+`tauri-plugin-updater` behind `cfg(not(any(target_os = "android", target_os = "ios")))`. margin, the
+repo that actually has a committed iOS project, does not gate them:
+`margin/src-tauri/Cargo.toml:24-25` has both unconditional. `capabilities/desktop.json` is in all
+four with the same two permissions, `updater:default` and `process:allow-restart`.
+
+`src-tauri/build.rs` is two files across four repos: margin and margin-docs share one (39 bytes),
+margin-calendar and margin-mail share the credential-embedding one (1171 bytes), byte-identical.
+
+## docs/release.md
+
+margin-calendar 105 lines, margin-docs 117, margin-mail 119. margin has none; its equivalent is
+`docs/publishing.md`, 229 lines, covering three distribution channels the others do not have.
+
+The "Installing locally" opening is near-identical in all three, down to "It is the same command
+whether or not the app is already installed, so it doubles as the update" and the sentence about a
+bundle going half old and half new. "Cutting a release" is the same paragraph in all three with the
+app's own manifest list. "Windows is not built" appears in all three, calendar and mail sharing the
+identical follow-up about a runner, `msi`/`nsis`, and the gate then wanting `windows-x86_64`.
+
+Where they genuinely diverge: calendar has a 41 line Linux and Nix section nobody else has; docs has
+a long honest section on self-update being impossible until a Developer ID certificate exists
+(`docs/release.md:105-117`) and a paragraph on why the bundle asks for the hardened runtime and no
+entitlements; mail has a Signing section built around `~/.margin-signing` with a `gh secret set`
+recipe (`docs/release.md:37-48`) and a "Before the first release" section covering both the missing
+updater key and Google restricted scope verification.
+
+The signing advice contradicts itself across the set. docs tells the reader to use `APPLE_ID` and an
+app-specific password (`docs/release.md:73-75`), mail and margin tell them to use an App Store
+Connect key. Both cannot be the house rule.
+
+## margin/website
+
+Astro 5, one page, deployed by hand: `package.json` has `"deploy": "astro build && npx wrangler
+pages deploy dist --project-name=margin --commit-dirty=true"`. No workflow deploys it.
+
+Downloads resolve at build time, not at request time. `website/src/data/release.ts:29-45` fetches
+`api.github.com/repos/priyanshujain/margin/releases/latest`, picks one asset per platform by
+filename suffix from `site.ts:40-43` (`.dmg`; `.exe` then `.msi`; `.deb` then `.AppImage` then
+`.rpm`), and falls back to the releases page on any error including the 8 second timeout. Astro runs
+that once at build, so the buttons point at whatever was latest when the site was last deployed and
+a release not followed by a deploy leaves stale links. `site.ts:23` carries the repo slug, so the
+whole thing is one constant away from serving a sibling app.
+
+## What to build
+
+**One reusable workflow, `workflow_call`, in a shared repo.** The publish job goes in verbatim, the
+prepare job goes in with the title as an input, and the build job goes in with the matrix as an
+input. Inputs the four repos actually differ on, and nothing else:
+
+- `app-name`: release title and, on margin, the dmg filename in the Homebrew job.
+- `platforms`: a list like `macos,linux,windows`, driving both the build matrix and the
+  `latest.json` key list in publish. Those two must not be able to disagree; today they are two
+  hand-edited lists in every repo.
+- `linux-runner`: default `ubuntu-22.04`, since three repos already agree that is the right glibc
+  baseline and margin's `ubuntu-latest` is an oversight.
+- `project-path` and `sibling-repos`: empty for margin and calendar, `rust/margin-mail` plus
+  `priyanshujain/margin` for mail, and the same for docs, which needs it and does not have it.
+- `needs-google-credentials`: boolean. margin, calendar and mail true; docs false.
+- `post-publish`: which trailing job runs, `homebrew` for margin, `nix` for calendar, none for the
+  others. These are different enough that they should be separate reusable workflows the caller
+  chains, not a flag.
+
+Take margin-docs' version validation, its `[package]`-anchored Cargo bump, its manifest-version and
+signature checks, and its half-configured signing failure as the baseline; add margin's `Cargo.lock`
+bump and its `codesign`/`spctl`/`stapler` verification. That combination exists in no repo today.
+Add `concurrency: group: release-${{ github.repository }}, cancel-in-progress: false` and `cache:
+pnpm` on `setup-node`, neither of which exists anywhere.
+
+The three `ci.yml` files should share a second reusable workflow with the same inputs plus a
+`rust-test-command` and an `extra-frontend-steps` hook, since margin-docs splits its Rust suite
+(`ci.yml:58,78`) and margin-mail adds docs and fonts checks (`ci.yml:44,51`). margin must call it.
+
+**A shared tauri.conf fragment.** Generate rather than fragment: Tauri's `--config` merge only helps
+at build time and the committed file still has to be readable. A small script in the shared package
+that takes app name, identifier, dev port, window size, targets and any extra CSP directives, and
+writes `tauri.conf.json`, with a `--check` mode wired into CI the way `pnpm fonts:check` already is.
+That kills four copies of the icon list, the category, the min system version, the base CSP and the
+window defaults, and it makes the odd ones out visible: margin's `targets: "all"` and the two
+repos that state `hardenedRuntime` redundantly.
+
+`tauri.release.conf.json` is four lines of structure and one pubkey. Generate it the same way, and
+put the tauri#14581 reason in the generator's header so it survives the next cleanup.
+
+**One signing procedure, documented once.** `margin/docs/publishing.md:193-229` plus
+`margin-mail/docs/release.md:18-48` is already the whole thing; it needs to be one page in the shared
+repo covering `~/.margin-signing`'s layout, the three certificate types and why they cannot be
+combined, and the App Store Connect key as the single notarisation credential. Settle the
+`APPLE_ID` versus API key question in favour of the key, and fix margin-docs' workflow to match.
+Move `scripts/apple-secrets.sh` and `apple-provision.rb` into the shared repo unchanged: they are
+already parameterised by `DIR`, `BUNDLE_ID` and `REPO`. Standardise on `APPLE_API_KEY_ID` as the
+secret name in all four, since margin and mail currently disagree. Add the `spctl` and `stapler`
+verification to the shared build job so margin-calendar stops shipping unsigned macOS bundles
+without anyone noticing.
+
+**One versioning convention.** `tauri.conf.json` is the source, the workflow writes `package.json`,
+`Cargo.toml` and `Cargo.lock`, and a CI check asserts all four agree. Roughly ten lines, and it
+would have prevented both of margin-calendar's manual repair commits. While there, replace
+`--notes "Release $TAG"` with `--generate-notes` or an extracted `CHANGELOG.md` section, since it
+feeds a dialog margin-docs already built.
+
+## What genuinely cannot be shared
+
+The identifiers, product names, dev ports, window sizes and the CSP additions each app needs;
+those are inputs, not duplication.
+
+margin's App Store track. The listing text, the screenshots, the entitlements and the six Ruby
+scripts are about one app's submission. `mas-package.sh` and `entitlements.mas.plist` could be
+templated later if a second app goes to the store, but there is no second app and templating for a
+hypothetical one is worse than copying it when the day comes.
+
+margin's Homebrew job and margin-calendar's Nix job. Both are per-app distribution channels with
+per-app asset names, per-app tap or flake repos, and a per-app credential. They can be reusable
+workflows the caller chains, but they are not one job with a flag.
+
+`margin/website`. It is one product's marketing site, with pricing, an offer counter and store
+logos. `data/release.ts` is genuinely generic and could move to the shared package if a second app
+ever gets a site.
+
+The updater UIs. Four apps have four different answers to what should happen when an update is
+found, and margin's App Store channel logic in `updates.rs` has no meaning in the other three. The
+plugin registration block, the `packaged_by` command and the `capabilities/desktop.json` permissions
+are the same three things four times over and are worth sharing; the dialogs are not.
+
+The per-app minisign keypair. One key per app is correct: the pubkey is baked into every shipped
+binary and cannot be rotated without stranding installed copies, so a shared key would make one
+compromise a four-app problem.

simplify/.research/design-system.md

@@ -0,0 +1,399 @@
+# The visual design system across the four apps
+
+Scope: CSS only. Tokens, fonts, the base layer, themes, and the layout idioms that repeat.
+
+Short names below: `margin` = /Users/pj/Workspace/projects/python/margin, `calendar` =
+/Users/pj/Workspace/projects/python/margin-caledar, `editor` =
+/Users/pj/Workspace/projects/rust/margin-editor, `mail` = /Users/pj/Workspace/projects/rust/margin-mail.
+Between them: margin 3 CSS files and 2983 lines, calendar 11 and 3796, editor 21 and 5089, mail 47
+and 6571. 18439 lines total.
+
+## What margin-shared already is, and who takes it
+
+`/Users/pj/Workspace/projects/python/margin/shared` ships `css/tokens.css` (35 distinct custom
+property names), `css/fonts.css` (12 `@font-face` rules, 6 families), `fonts/` (18 files: 12 TTFs
+and 6 OFL notices), `src/fonts.ts`, `src/icons.ts` and `bin/sync-fonts.mjs`.
+
+Three of the four consume it. margin declares `"margin-shared": "file:./shared"`, editor and mail
+both declare `"file:../../python/margin/shared"`. Calendar does not depend on it at all and does not
+import either stylesheet.
+
+The seams are thin and consistent in the three that do:
+
+- margin/src/styles/tokens.css:3 imports the shared tokens, then adds exactly one line, `--pane-dock: 384px`.
+- editor/src/styles/tokens.css:5 imports, then adds 51 tokens of its own (document scale, sheet padding, code surface).
+- mail/src/styles/tokens.css:6 imports, then imports `./mail.css`, which adds 46.
+
+## Tokens
+
+### Calendar is a 49-of-52 copy of the shared file
+
+calendar/src/styles/tokens.css is not a divergent palette. Comparing it block for block against
+shared/css/tokens.css:
+
+- `:root`: 11 of 11 comparable values byte-identical (`--font-ui`, `--font-heading`, `--r-sm/md/lg`,
+  `--titlebar-h`, `--t-1` through `--t-4`, `--ease`). Absent: `--font-book`, `--pane-sidebar`,
+  `--measure`, which a calendar has no use for.
+- light block: 19 of 20 identical. One drift.
+- dark block: 19 of 20 identical. Same one drift.
+- Absent from both palettes: `--sidebar`, correctly, since the grid owns the window and there is no sidebar.
+
+The one drift is `--ink-faint`. Shared has `#9b9484` light and `#756d5e` dark; calendar
+(tokens.css:74, :126) and mail (mail.css:86, :142) both have `#6e675b` and `#8e8677`.
+
+Two apps independently moved the same token to the same two values for the same stated reason
+(4.5:1 contrast on the surfaces faint ink lands on; the calendar comment names the hour axis, the
+mail comment names list times and snippets and says "same reasoning, same value, as the calendar's
+hour axis"). Editor and margin still take `#9b9484`. That is not two apps needing to differ, it is
+the shared value being wrong and two apps finding out separately. Move the pair upstream and delete
+both overrides.
+
+### Tokens defined in more than one app under different names, or defined in one and hardcoded in another
+
+- `--scrim`. Not in shared. Light is `rgba(35, 32, 27, 0.28)` in all three that have it (calendar
+  tokens.css:84, editor tokens.css:14, mail mail.css:88). Dark: calendar and mail `rgba(0, 0, 0, 0.58)`,
+  editor tokens.css:26 `rgba(0, 0, 0, 0.5)`. margin has no token and writes the light literal into
+  `.overlay` at app.css:1275 and a second, different one, `rgba(35, 32, 27, 0.32)`, into
+  `.export-overlay` at app.css:1449. This belongs in shared.
+- `--shadow-raised`. editor tokens.css:15 `0 1px 2px rgba(35, 32, 27, 0.05)`, dark
+  `0 1px 2px rgba(0, 0, 0, 0.35)`. margin writes that light value as a literal twice, app.css:272
+  and app.css:1839.
+- `--r-pill: 999px`. Declared separately in calendar tokens.css:8, editor tokens.css:10 and mail
+  mail.css:12, identically. margin writes `border-radius: 999px` as a literal at app.css:2184. Four
+  apps, one value, three declarations and one literal.
+- `--t-5: 16px`. calendar tokens.css:34, editor tokens.css:12, mail mail.css:17. Identical, and the
+  comment in calendar and mail is nearly word for word the same (iOS zooms a field under 16px).
+- `--touch-h: 44px`. calendar tokens.css:22, editor tokens.css:11, mail mail.css:31. Identical.
+- `--traffic-pad: 84px`. calendar tokens.css:11, editor tokens.css:11, mail mail.css:36. Identical;
+  margin has no token and hardcodes the lane unconditionally, see the drift section.
+- `--safe-top` / `--safe-bottom` / `--phonebar-h: 48px` / `--tabbar-h: 56px` / `--sheet-max-h: 88dvh`.
+  calendar tokens.css:16-26 and mail mail.css:26-34, identical values and near-identical comments.
+  A five-token phone chrome block written twice.
+- calendar `--cal-1` through `--cal-8` (tokens.css:106-113 light, :160-167 dark) and mail `--hue-1`
+  through `--hue-8` (mail.css:115-121, :159-166) are the same sixteen hexes under two names. mail's
+  own comment says so: "the calendar's --cal-1..8 under a name that says what they are for here".
+
+### App-only tokens that should stay app-only
+
+editor's 51 additions are document typography and sheet geometry (`--doc-h1` through `--doc-h6`,
+`--measure-*`, `--sheet-pad-*`, `--code-*`, `--pdf-page`). mail's 46 are mail geometry (`--list-w`,
+`--avatar`, `--pile-h`, `--compose-w`, `--feed-w`, the `--message-*` set that deliberately does not
+follow the theme). Calendar's are grid geometry (`--gutter-w`, `--daybar-h`, `--strip-h`,
+`--event-*`, `--grid-*`, `--fold-*`). margin's is `--pane-dock: 384px`. All genuinely single-app.
+
+Note the collision: `--row-h` means a calendar grid row (48px, calendar tokens.css:44) in one app and
+a message list row (46px, mail mail.css:45) in the other. A reason not to promote geometry by name.
+
+## Fonts
+
+The bytes are already correct. All 18 files in shared/fonts are byte-identical to the copies in
+margin/public/fonts, editor/public/fonts and mail/public/fonts (verified with `cmp`, 18/18 each).
+Calendar vendors only 4 of them, `HankenGrotesk-VF.ttf`, `HankenGrotesk-Italic-VF.ttf`,
+`Literata-VF.ttf`, `Literata-Italic-VF.ttf`, and those 4 are byte-identical to shared too. It ships
+no OFL notices, which is the one real problem here: the other three ship all six.
+
+`shared/bin/sync-fonts.mjs` copies every `.ttf` and `.txt` from shared/fonts into
+`<app>/public/fonts`, or with `--check` compares and exits 1 on any difference; a file present in
+the app and absent from the package is reported and left alone rather than deleted (lines 53-59).
+The vendored copies exist because both PDF exporters read the same paths with `include_bytes!`, so
+cargo must not wait on an npm install.
+
+Who runs it: margin and editor as `node node_modules/margin-shared/bin/sync-fonts.mjs .`, mail as
+`margin-shared-fonts .` through the package's `bin` entry. Calendar has no `fonts:sync` or
+`fonts:check` script and no way to notice drift.
+
+margin, editor and mail's src/styles/fonts.css are each a comment and one
+`@import "margin-shared/css/fonts.css"`; margin's and editor's are byte-identical including the
+comment. calendar/src/styles/fonts.css is 31 lines of hand-written `@font-face` for the four faces
+it vendors, character-for-character the same as shared/css/fonts.css:17-47. Calendar joining costs
+one import, one script pair, and 8 more files in public/fonts.
+
+## The base layer in app.css
+
+All four start with the same reset. Measured by parsing each app.css into selector/body pairs and
+comparing bodies exactly:
+
+- margin x editor: 71 selectors in common, 59 with byte-identical bodies.
+- calendar x mail: 22 in common, 16 identical.
+- calendar x editor: 23 in common, 15 identical.
+- margin x calendar: 20 in common, 11 identical.
+- editor x mail: 15 in common, 10 identical.
+- margin x mail: 15 in common, 7 identical.
+
+Identical in all four, no exceptions: `*`, `html, body, #root`, `body`, `::selection`,
+`:focus-visible`. The focus ring is the same three lines everywhere (margin app.css:43, calendar
+app.css:80, editor app.css:51, mail app.css:92):
+
+```css
+:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+```
+
+And the body block, identical in all four (margin app.css:16, calendar app.css:16, editor app.css:16,
+mail app.css:26):
+
+```css
+body {
+  margin: 0;
+  position: fixed;
+  inset: 0;
+  overflow: hidden;
+  overscroll-behavior: none;
+  background: var(--shell);
+  color: var(--ink);
+  font-family: var(--font-ui);
+  font-size: var(--t-3);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+```
+
+Near-duplicates, with the differences named:
+
+- `button`. margin app.css:34, calendar app.css:63 and editor app.css:34 are identical seven-line
+  blocks. mail app.css:70 adds one line, `font-size: inherit`. That line is right and the other
+  three are missing it.
+- `html`. margin and editor stop at `text-size-adjust`. calendar app.css:37 and mail app.css:23 both
+  add `-webkit-tap-highlight-color: transparent` with the same three-line comment about a webview
+  reading every tap as a text selection. Two apps have the fix, two do not.
+- `input, textarea, select`. Identical in calendar app.css:72, editor app.css:43, mail app.css:80.
+  margin does not have it at all, so its fields fall back to the webview's font.
+- `.app`. calendar app.css:86, editor app.css:58 and mail app.css:100 are identical
+  (`display:flex; flex-direction:column; height:100%; overflow:hidden`). margin app.css:59 uses
+  `height: 100vh; height: 100dvh`, which the other three have deliberately moved away from; the
+  comment at calendar app.css:89-97 explains why.
+- `:root[data-touch] .icon-button`, `.icon-button`, `.icon-button:hover`: identical between calendar
+  app.css:145-170 and editor app.css:138-165. margin calls the same control `.icon-btn` and draws it
+  30px instead of 28px (app.css:103). mail folded it into `.button[data-icon-only]` (ui/Button.css:33).
+  Four apps, one control, three names and two sizes.
+
+`::-webkit-scrollbar` exists in exactly one app, margin app.css:693-712 (11px, thumb `--line-strong`
+with a 3px transparent border and `background-clip: content-box`, hover `--ink-faint`, transparent
+track). The other three take the webview default. Editor gets the temperature right a different way,
+via `color-scheme` in themes.css. Only editor declares `color-scheme` at the root
+(themes.css:24-31 and once per palette); calendar declares it on one element,
+create.css:53 and :57, on the quick-create card.
+
+`@media (prefers-reduced-motion: reduce)`: mail has 11 (app.css:208, Banner.css:64, pane.css:297 and
+:358, arriving.css:78, search.css:36, list.css:126, tour.css:29, contacts.css:56, :215, :306), editor
+1 (export-preview.css:167), calendar 0, margin 0. Calendar and margin both animate
+(`quick-create-in`, `sheet-up`, `find-drop`, `drawer-in-right`, `spin`) with no guard.
+
+## The overlay and panel shell
+
+The same box in all four, and it is the single largest near-duplicate in the codebase.
+
+`.overlay` is identical in calendar app.css:330, editor app.css:451 and mail app.css:110:
+`position:fixed; inset:0; z-index:20; background:var(--scrim); backdrop-filter:blur(2px);
+display:grid; place-items:center; padding:40px`. margin app.css:1271 is the same rule with
+`background: rgba(35, 32, 27, 0.28)` written out instead of a token.
+
+`.panel` is byte-identical in all four (margin app.css:1283, calendar app.css:342, editor app.css:463,
+mail app.css:129): `width: min(480px, calc(100vw - 32px)); max-height:100%; flex column; --paper;
+1px --line; --r-lg; --shadow-pop; overflow:hidden`.
+
+`.panel-body` is byte-identical in all four. `.panel-foot` is identical in margin, calendar and
+editor; mail adds `flex: none`. `.panel-head`: margin, calendar and mail use `padding: 16px 14px 16px 22px`,
+editor uses `16px 16px 16px 22px` with a comment at app.css:475-478 explaining the two pixels; mail
+also adds `flex: none`, `gap: 10px` and a `flex: 1; min-width: 0` on the `h2`. `.panel-head h2` is
+`font-family: var(--font-book)` in margin and editor and `var(--font-heading)` in calendar and mail,
+which is a real fork: shared/css/tokens.css sets both to Literata by default, but editor lets a
+document override `--font-book` at runtime and mail lets a setting override `--font-heading`, so the
+same declaration means different things.
+
+Phone docking is written twice, identically, comments included. calendar app.css:356-390 and mail
+app.css:179-206 both carry `:root[data-phone] .overlay` (z-index 50, padding 0,
+`place-items: end center`), `:root[data-phone] .panel` (full width, `--sheet-max-h`, border-width
+`1px 0 0`, radius `var(--r-lg) var(--r-lg) 0 0`, `padding-bottom: var(--safe-bottom)`,
+`animation: sheet-up 180ms var(--ease)`), `:root[data-phone] .panel-body { overscroll-behavior: contain }`
+and `@keyframes sheet-up`. mail adds the reduced-motion guard, calendar does not.
+`.overlay[data-align="top"] { align-items: start; padding-top: 12vh }` appears three times: calendar
+palette.css:4, editor palette.css:9, mail app.css:124.
+
+Panel sizes are the same idiom under two names: calendar overlays.css:9-20
+`.overlay-panel[data-size="mini"]` at `min(292px, calc(100vw - 32px))` and `wide` at 560px, mail
+Sheet.css:4-15 `.sheet[data-size="mini"]` at the identical 292px and `wide` at 620px. Both give mini
+the same `.panel-body { gap: 10px; padding: 12px 12px 14px }`.
+
+## Buttons and fields
+
+Three of the four have converged on the same text button by three different routes.
+
+calendar overlays.css:60-135 `.panel-button` and mail ui/Button.css:1-98 `.button` are the same
+control: `inline-flex`, `gap: 7px`, `1px solid var(--line-strong)`, `var(--r-sm)`, `var(--raised)`
+ground, `--accent-wash` hover, and `[data-variant="primary" | "danger" | "ghost"]` with the same
+bodies (primary is accent ground with `--accent-contrast` ink hovering to `--accent-ink`; danger is
+`--danger-ink` text hovering to `--danger-wash` with a `--danger` border; ghost is transparent border
+and `--ink-soft`). The differences are the selector, the sizing (calendar pins `min-height: 30px`,
+mail has `[data-size="sm|md|lg"]` at 26/28/32) and mail's `[data-icon-only]` square. Both end with
+`:root[data-touch] { min-height: var(--touch-h) }`. editor settings.css:319 `.btn-quiet` and margin
+app.css:1769-1805 `.btn-primary` / `.btn-ghost` / `.btn-danger` are a third and fourth spelling of
+the same three variants; margin's danger is filled rather than outlined and it pads `9px 20px`.
+
+Fields: calendar overlays.css:140-216 (`.field-input`, `.field-select`, `.field-textarea`,
+`.field-hint`, `.field-check`) and mail ui/Field.css:18-59 are the same rules to within the padding
+(`6px 9px` vs `7px 10px`) and mail's added `:disabled` and `::placeholder` blocks. Both hover to
+`border-color: var(--ink-faint)`. margin app.css:1333-1348 is a third version on `.field input,
+.field select` with `padding: 9px 11px` and a `:focus { border-color: var(--accent) }` the other two
+lack. `.field` and `.field-label` are byte-identical between margin app.css:1318-1331, calendar
+app.css:423-435 and mail ui/Field.css:1-16 (uppercase, `--t-1`, 600, `0.08em`, `--ink-faint`), which
+is also exactly mail's `.group-head` (ui/GroupHead.css:1-11) and margin's and editor's `.nav-label`.
+mail duplicates its own field twice more, at screens/settings.css:448-471 and :306.
+
+The switch: editor settings.css:343-380 `.switch` / `.switch-knob` and mail ui/Toggle.css:1-40
+`.toggle` / `.toggle-knob` are the same control at two sizes (38x22 with a 16px knob travelling 16px,
+against 34x20 with a 14px knob travelling 14px). Same `--r-pill` track, `--line-strong` border,
+`[data-on]` filling with `--accent`, knob turning `--accent-contrast`. mail adds a touch size
+(46x28); editor does not.
+
+The keycap: calendar palette.css:105-118 `.key` and mail ui/Key.css:1-17 `.key[data-size="md"]` are
+byte-identical apart from mail moving the padding onto a size attribute. editor has a third,
+`.key-cap` at tree.css:744, an `--accent-wash` chip with no border; margin a fourth, `.esc-hint kbd`
+at app.css:2191.
+
+Segmented control: mail ui/Segment.css:3-30 `.segment` / `.segment-option` and calendar app.css:483-508
+`.view-switch` / `.view-option` are the same object (2px padding, 2px gap, `--r-md` track of
+`--accent-wash`, `--r-sm` options, active option lifted onto `--paper`). Calendar has a third copy for
+the phone at app.css:244-267 (`.tabbar-views` / `.tabbar-view`).
+
+## Menus, popovers, row menus, toasts, resizers
+
+- Dropdown menu. margin app.css:1382-1438 and editor app.css:510-588 share `.menu-wrap`,
+  `.menu-backdrop`, `.menu`, `.menu button`, `.menu-label`, `.menu-sep`; five of those six bodies are
+  byte-identical. `.menu` differs only in `min-width` (156 vs 168) and `.menu button` in editor
+  gaining `grid-template-columns: 14px 1fr` for a glyph column. mail's equivalent, ui/Popover.css, is
+  positioned from JS through `--pop-left` / `--pop-top` / `--pop-w` and is genuinely different.
+- Row menu. `.row-menu-btn`, `.row-menu-btn:hover`, `.row-menu-pop`, `.row-menu-item`,
+  `.row-menu-item:hover`, `.row-menu-item.danger`, `.row-menu-item.danger:hover` are byte-identical
+  between margin app.css:393-460 and editor app.css:363-430. Seven rules, no differences.
+- Toast. margin app.css:1476 and editor app.css:590 are byte-identical: fixed, `bottom: 26px`,
+  centred by `translateX(-50%)`, `z-index: 40`, `max-width: 460px`, `--ink` ground with `--paper`
+  text. calendar app.css:437 and mail ui/Toast.css:1 are a different and better toast, also nearly
+  identical to each other: `bottom: 24px`, `z-index: 60`, `max-width: min(560px, calc(100vw - 48px))`,
+  `--glass` with `blur(8px)`, a `--line` border and `--shadow-pop`. Two designs, two apps each.
+- Resize handle. margin app.css:140-186 and editor tree.css:64-108 are the same rule set:
+  zero-width flex item, an 8px `::before` hit area at `left: -4px`, a 2px `::after` accent line at
+  `left: -1px` going to `opacity: 0.55` on hover. The only difference is the drag hook,
+  `body.resizing` against `:root[data-resizing]`. editor/src/components/ResizeHandle.tsx writes
+  `--pane-sidebar` on the root, so the token is already the interface.
+- Selected-row accent edge. `.chapter[data-active="true"]::before` (margin app.css:275, editor
+  app.css:266, byte-identical) and `.row[data-selected]::before` (mail ui/Row.css:29): an absolutely
+  positioned 2-3px bar of `--accent` with `border-radius: 0 2px 2px 0`, inset from the row's ends.
+- Sidebar and nav. `.sidebar`, `.brand`, `.brand .back-label`, `.brand:hover`, `.nav-label`,
+  `.nav-scroll`, `.nav-section + .nav-section`, `.chapters`, `.chapter` and its nine state rules,
+  `.chapter-drop`, `.add-chapter`: all byte-identical between margin and editor. The bulk of the 59
+  identical bodies, and a straight copy of one app's sidebar into the other.
+- Settings. editor styles/settings.css and mail screens/settings.css are the same layout (a rail
+  left, a measured column right, rows of label plus control plus note) at different numbers: rail
+  `var(--pane-sidebar)` (248px) against a literal 210px, column 620px against 640px,
+  `.settings-nav-item` against `.settings-tab`, `.setting-row` against `.set-row`. Both gate the
+  traffic lane with `:root[data-traffic] { padding-left: var(--traffic-pad) }`. margin and calendar
+  keep settings inside `.panel`, which is a legitimate difference of kind.
+
+## Themes
+
+Four implementations, three of which are the same file.
+
+margin/src/theme.ts, calendar/src/theme.ts and mail/src/theme.ts are the same 16 lines with one
+string changed: the localStorage key (`margin-theme`, `margincal-theme`, `marginmail-theme`). Same
+`initialTheme` reading `data-theme` off the root first, then storage, then
+`matchMedia("(prefers-color-scheme: dark)")`; same `applyTheme` writing the attribute and the key.
+The boot scripts in each index.html are the same shape too, differing in the key and in what else
+they set on the root (calendar adds `data-phone`, `data-touch`, `data-view`; mail adds `data-phone`,
+`data-touch`, `data-no-pane` and the two font slots).
+
+editor/src/theme.ts is 167 lines and a different design: seven named palettes
+(`light`, `sepia`, `mist`, `contrast`, `dark`, `graphite`, `midnight`), a `ThemeChoice` that can be
+`"system"`, a remembered light half and dark half so "Match system" lands on the two the user
+actually picks, storage in try/catch for a webview with storage denied, and `watchSystemScheme`
+listening for the media query as an event. Its palettes live in editor/src/styles/themes.css, one
+44-line block each, and editor/src/theme.test.ts reads that file and fails when a block is short.
+
+No app uses `@media (prefers-color-scheme)` in CSS at all. All four resolve the system preference in
+JS and write `data-theme` on the root. That is one decision, taken four times, and it is the right
+one, so it should be taken once.
+
+The multi-theme design is not a candidate for sharing as it stands: mail and calendar's stylesheets
+have no idea `sepia` or `midnight` exist and would fall through to the light `:root` block. But the
+three-line theme module and the boot script are, with the key as a parameter.
+
+editor themes.css:307-322 is worth flagging: it copies six hexes of the shared light and dark
+palettes so the picker's preview tiles can draw them, with a comment saying it is the only copied
+colour in the file and that it is copied because "this repo may not reach into" margin-shared. It
+can, and does, through `margin-shared/css/tokens.css`. A shared `.theme-swatch[data-theme="light"]`
+block in the package would delete those two blocks.
+
+## Drift: values hardcoded where a token exists
+
+Counted over every CSS file except each app's token layer:
+
+| app | hex literals | rgba() literals |
+| --- | --- | --- |
+| margin | 15 | 17 |
+| calendar | 0 | 1 |
+| editor | 0 | 0 |
+| mail | 0 | 0 |
+
+Editor and mail are clean. Calendar's one is `box-shadow: 0 1px 2px rgba(0, 0, 0, 0.06)` at
+app.css:507 on `.view-option[data-active]`, the only shadow in the app not from `--shadow-page` or
+`--shadow-pop`. margin is where the drift lives, and most of it is a token it never adopted:
+
+- app.css:1275 `background: rgba(35, 32, 27, 0.28)` on `.overlay`. That is `--scrim`, which the other
+  three all have.
+- app.css:1449 `background: rgba(35, 32, 27, 0.32)` on `.export-overlay`. A second scrim at a fourth
+  of a percent difference, which nobody chose.
+- app.css:272 and :1839 `box-shadow: 0 1px 2px rgba(35, 32, 27, 0.05)`. That is editor's
+  `--shadow-raised` exactly.
+- app.css:1547 `box-shadow: 0 4px 10px rgba(35, 32, 27, 0.1), 0 20px 38px rgba(35, 32, 27, 0.13)` on
+  `.card:hover`. A third shadow that is neither `--shadow-page` nor `--shadow-pop`.
+- app.css:2933 `background: rgba(0, 0, 0, 0.42)` on `.drawer-scrim`. A third scrim.
+- app.css:1052 `0 1px 3px rgba(0, 0, 0, 0.3)`, app.css:1458 and :1465 `#fcfbf7` (`--paper`'s light
+  value, hardcoded so it survives on the dark overlay), app.css:1464 `rgba(255, 255, 255, 0.28)`,
+  app.css:638 `#fffefb`, app.css:678 `#2b2720`, app.css:1238 `#fff` (that last is editor's
+  `--pdf-page`, which editor tokenised precisely because it was a literal in two stylesheets).
+- app.css:2184 `border-radius: 999px`, which is `--r-pill` in the other three.
+- app.css:75 `padding: 0 14px 0 84px` on `.titlebar`. The 84px is the macOS traffic-light lane,
+  applied on every platform with no `data-traffic` gate. calendar app.css:126, editor app.css:97 and
+  mail header.css:24 all gate it, and the comment at calendar app.css:121-125 says what the ungated
+  version costs on Linux, Windows and iPad.
+- app.css:2881 `--titlebar-h: calc(46px + env(safe-area-inset-top))` inside `.app[data-compact]`.
+  It restates the 46px shared already owns and reads `env()` inline where calendar and mail both have
+  a `--safe-top` token for it.
+
+The twelve proofing colours at app.css:2367-2451 (`#b4453a`, `#9c6e16`, `#2f6e4f` and their dark
+counterparts, plus six washes) are a real palette with no token, and editor has the same feature
+(styles/proofing.css) using `--danger` and friends. Worth comparing separately; it is the one place
+margin's literals encode a design rather than a forgotten token.
+
+## What one shared stylesheet would have to contain
+
+Tokens, added to shared/css/tokens.css: `--scrim`, `--shadow-raised`, `--r-pill`, `--t-5`,
+`--touch-h`, `--traffic-pad`, `--safe-top`, `--safe-bottom`, `--phonebar-h`, `--tabbar-h`,
+`--sheet-max-h`, and the eight-hue ramp under one name. Plus the `--ink-faint` correction. That is
+19 names and one fix, and it removes every one of them from calendar, editor and mail's own layers.
+
+A base sheet: `*`, `html, body, #root`, `html` (with the tap-highlight line), `body`, `::selection`,
+`:focus-visible`, `button` (with `font-size: inherit`), `input, textarea, select`, `svg`, `.app`, the
+`data-touch` selection rules and the `data-phone` field-size rule. All of it is already identical or
+one line from identical in all four.
+
+An overlay sheet: `.overlay`, `.overlay[data-align="top"]`, `.panel`, `.panel-head`, `.panel-head h2`,
+`.panel-body`, `.panel-foot`, the four `:root[data-phone]` docking rules, `@keyframes sheet-up` and
+its reduced-motion guard. Byte-identical or trivially reconcilable across all four today.
+
+A controls sheet: the button (mail's `[data-variant]` and `[data-size]` version, which is the
+superset), the field, the label, the toggle, the keycap, the segmented control, the icon button under
+one name, the row menu, the toast (calendar and mail's version), the resize handle. Every one of
+these exists in at least two apps already and differs by a padding value or a class name.
+
+`color-scheme` at the root, per theme, which only editor has, and a `prefers-reduced-motion` guard
+convention, which only mail applies consistently.
+
+What each app keeps: editor keeps its document scale, sheet padding, code surface and its seven-palette
+themes.css; mail keeps its mail geometry, the `--message-*` set that deliberately ignores the theme,
+and its `--check` OS blue; calendar keeps its grid geometry and the `--grid-*`, `--fold-*` and
+`--event-*` palettes; margin keeps `--pane-dock`, its scrollbar rule (or that moves up), its proofing
+palette and the device-frame `--dv-*` set. Nothing else in the four apps' CSS is app-specific by need
+rather than by accident.

simplify/.research/docs-conventions.md

@@ -0,0 +1,442 @@
+# Docs, comments and naming across the four apps
+
+Read: three `docs/conventions.md`, four `README.md`, every `docs/*.md`, both `CLAUDE.md`,
+`shared/src/fonts.ts`, `shared/src/icons.ts`, all four `src-tauri/Cargo.toml`, all four
+`package.json` and `tauri.conf.json`, `scripts/docs-check.mjs`, and the CI workflows.
+
+## 1. The three conventions.md files
+
+Only three exist: `margin-caledar/docs/conventions.md` (89 lines),
+`margin-editor/docs/conventions.md` (103), `margin-mail/docs/conventions.md` (139). **margin, the
+app all three defer to, has no conventions.md at all.** That is the first hole: the house style is
+written down only in the repos that copied it, never in the repo that set it.
+
+### What all three share, near verbatim
+
+Each opens by disclaiming originality. Calendar line 3: "This project is a sibling to `../margin`
+and follows its conventions deliberately rather than inventing new ones." Editor line 3 and mail
+line 3 are the same sentence with the sibling list extended.
+
+Five rules are word-for-word identical in all three:
+
+- `Result<T, String>` everywhere. No `anyhow`.
+- "DTOs crossing the IPC boundary live in `src-tauri/src/dto.rs` and are marked
+  `#[serde(rename_all = "camelCase")]`. That file is the contract and is frozen: implementation
+  modules add bodies, not fields. Its mirror is `src/ipc.ts`."
+  (calendar:12, editor:13, mail:14)
+- "One zustand store per domain in `src/store/`. No middleware. One selector call per field
+  (`useThing((s) => s.field)`, never a destructured object), actions as inline arrow properties, and
+  `set((s) => ...)` returning `{}` to no-op." (calendar:26, editor:26, mail:35)
+- "Flat kebab-case class names, not BEM. State is a `data-*` attribute, never an `is-` class."
+- "Transitions name explicit properties and use `var(--ease)`. Never `transition: all`."
+
+And each closes with a `## Never` section of the same shape. Calendar:88 and mail:138: "No CSS
+framework, no component library, no router, no zustand middleware, no directory trees in any
+document, and no em dashes anywhere including code comments."
+
+### Where they contradict each other
+
+**Em dash versus en dash.** Editor:103 is the only one that bans both: "no em dashes or en dashes
+anywhere, including code comments." Calendar:89 and mail:139 ban only em dashes. The user's own rule
+bans both. Editor is right and the other two are stale.
+
+**Container queries.** Calendar:67 permits exactly one, on the event block, and says "Nothing else
+may reach for a container query without the same kind of reason." Mail:105 hardens it to "There is
+no container query in this repository" while explicitly crediting the calendar's exception. Editor
+does not mention container queries. Not a real contradiction, but three different postures.
+
+**Where a token lives.** Calendar:46 and editor:81: "Every colour, radius and size goes through a
+token in `src/styles/tokens.css`." Mail:55 redefines `tokens.css` as a seam, not a list: it imports
+margin-shared's set and then `src/styles/mail.css`, and mail:86 says add to `mail.css` instead. Mail
+is the only one with the three-layer tokens/primitives/screens rule (mail:51-66) and the only one
+with a Kit page at `#/kit`.
+
+**Icons.** All three keep "Inline Feather-style 24x24 stroke `d` strings passed to
+`<Icon d={...} />`. There is no icon set and no registry, and there will not be one." Calendar:79 and
+mail:120 add "An icon-only button always carries a `title` with its shortcut written in real
+glyphs"; editor drops that line. Mail:116 is the only one that names a file (`src/ui/icons.ts`) and
+the only one that acknowledges `margin-shared/icons`, which editor and calendar do not mention at
+all even though `margin-shared` is a real dependency of editor.
+
+**Comment density.** Calendar:22 and mail:31: "Comments are rare and explain why, never what. Match
+the density in `lib.rs`." Editor:22 keeps the first sentence and drops the pointer. See section 5:
+the density claim is false in all three.
+
+**Errors.** Calendar allows one error enum (`google::api::ApiError`), mail allows one
+(`provider::ProviderError`), editor:11 allows none. Each names its own reason. This is the right
+pattern: an app-specific carve-out written next to the shared rule.
+
+### What is genuinely app-specific and should stay that way
+
+Editor's `## Markdown` (38-59) and `## Tests` (61-75) sections, mail's `## Places and stages`
+(68-80) and `## Work packages` (129-134), calendar's `data-phone` versus `data-touch` argument
+(57-70, copied verbatim into mail:94-103). Storage key prefixes differ by design: `margincal-`,
+`margindocs-`, `marginmail-`.
+
+### Broken cross-references
+
+Calendar:3 says `../margin`, and from `python/margin-caledar` that resolves. Editor:3 says
+`../margin` and `../margin-calendar`, and **neither exists**: `rust/margin` and
+`rust/margin-calendar` are not on disk. Calendar:17 cites `margin/src-tauri/src/gdrive.rs:286` and
+calendar:20 cites `pdf.rs:90`. Both files exist; neither line carries a comment (section 5).
+
+## 2. READMEs
+
+| repo | lines | verdict |
+| --- | --- | --- |
+| margin | 15 | compliant. Description, install, one docs link, licence. |
+| margin-calendar | 15 | compliant, but the last seven lines are one dense paragraph of six links. |
+| margin-docs | 14 | compliant and the cleanest of the four. |
+| margin-mail | 20 | over. Lines 3 to 10 are an eight-line pitch that belongs in `docs/design.md`. |
+
+Mail is the offender. Its opening paragraph restates the product ("New senders wait at the door
+until you let them in; people, newsletters and receipts live in three separate boxes") which is
+already `docs/design.md:31-73`. Cutting it to two sentences puts it at 13 lines.
+
+Four other READMEs exist inside margin and are not project descriptions:
+`margin/website/README.md` (48 lines, 7 em dashes), `margin/appstore/screenshots/README.md` (51),
+`margin/simplify/README.md` (26), `margin/simplify/guidelines/README.md` (31).
+`margin/shared/README.md` is 15 lines and compliant. The website one is the worst artefact in the
+suite: bold-marked feature bullets, em dashes throughout, a "Built with" line. It reads like a
+different author.
+
+`margin/shared/README.md:3` and `shared/package.json:7` both say the package is for "Margin and
+Margin Docs". Margin Mail has depended on it since `package.json:24`. The description is stale.
+
+## 3. The docs set
+
+- **margin**: `docs/publishing.md` only (229 lines). No architecture, no design, no conventions, no
+  setup, no release. The originating app is the least documented.
+- **margin-calendar**: `architecture.md` (145), `conventions.md` (89), `design.md` (152),
+  `mobile.md` (304), `release.md` (105), `setup.md` (55). This is the set that got copied.
+- **margin-docs**: `architecture.md` (545), `conventions.md` (103), `design.md` (131),
+  `release.md` (117), `setup.md` (29). Calendar's set minus `mobile.md`, macOS only.
+- **margin-mail**: `architecture.md` (352), `conventions.md` (139), `design.md` (153),
+  `release.md` (119), plus `features.md` (475), `ui.md` (339), `settings.md` (201), `plan.md` (193),
+  `keyboard.md` (129), `help.md` (74), `mockups/`, `research/`. **No `setup.md`**, which is the one
+  file a new machine needs, and mail is the app that requires a Google OAuth client.
+
+Three shapes are stable across the set. `architecture.md` always opens with the same stack sentence:
+"Tauri 2, React 19, Vite, TypeScript and zustand on the front, Rust behind" (calendar:3, editor:3,
+mail:3), then "The split is strict" and what each side owns. `design.md` is always product decisions
+argued as prose under "why" headings, and always ends with `## Visual language`. `release.md` always
+starts `## Installing locally` then `## Cutting a release` and ends `## Updates`.
+
+### Proposed canonical set
+
+Five files, every app, same names, same opening move:
+
+`architecture.md`, `conventions.md`, `design.md`, `setup.md`, `release.md`.
+
+Then only what the product actually has: `features.md`, `ui.md`, `keyboard.md`, `settings.md`,
+`help.md`, `mobile.md`, `publishing.md`, `plan.md`, `research/`, `mockups/`. Never a numeric prefix.
+
+Concretely: margin needs all five written and should keep `publishing.md`; mail needs `setup.md`;
+mail's `plan.md` is a milestone tracker and will go stale, so it belongs in the issue tracker or
+under `research/`.
+
+## 4. The comment voice
+
+### What a comment is for here
+
+A comment records a decision and the alternative that was rejected, so that a competent person does
+not undo it by accident. It never says what the line below does.
+
+The shape is consistent enough to be a template. A file-head block states what the file is in one
+line, then a blank comment line, then one paragraph per decision. Each paragraph names the thing
+chosen, then the thing not chosen, then the concrete failure the wrong choice produces. Sentences
+are long, declarative, no hedging, no first person, no "note that". Length is one to seven lines per
+paragraph; a file head runs 3 to 17 lines. Doc comments on exported items are one sentence and often
+end on the consumer ("which is what a Typst preamble names a face by").
+
+The tell is that almost every comment contains a causal clause: "because", "so that", "which is
+why", "rather than", "or a ... would".
+
+### Four exemplars, in full
+
+`margin/shared/src/fonts.ts:1-7`:
+
+    // The faces both apps offer, and the two slots they set them into.
+    //
+    // This lives in one place because the two apps have to agree about it. A face named here is a
+    // `@font-face` in css/fonts.css, a file in fonts/, and a family a Typst preamble names on the way
+    // to a PDF, and those four lists going out of step with each other is a document that renders in
+    // one app and falls back to Georgia in the other. There is no way to keep four lists in two repos
+    // honest by hand, so there is one list.
+
+`margin/shared/src/icons.ts:3-6`:
+
+    // Here because the two apps kept drifting. Each had its own idea of what a search or a moon looked
+    // like, they were adjusted independently, and the result was two products from the same hand that
+    // did not look related. A path is a design decision, not a detail, and the fix for two copies of a
+    // decision is one copy.
+
+`margin-mail/src-tauri/Cargo.toml:61-63`:
+
+    # Refresh tokens, the backup key and every uploaded journal segment are sealed with
+    # XChaCha20-Poly1305. There is no `keyring` here on purpose: it has no Android backend at all, and
+    # on macOS it ties the item to the code signature, so every rebuild re-prompts.
+
+`margin-editor/src-tauri/Cargo.toml:54-56`:
+
+    # Pinned exactly: the [patch] stubs at the foot of this file are tied to this version's burn/cubecl
+    # graph. A minor bump could silently invalidate a patch ("unused"), and the whole CUDA and LLVM
+    # subtree those stubs remove would come back. Bump deliberately and re-audit the stubs.
+
+`margin/shared/src/icons.ts:29-37` is the purest case, because it justifies an SVG path: two
+letterforms rather than one on a rule, because one letter over a full-width line is the underline
+button in every editor, and because the neighbouring `SPELLING` glyph is also built on a capital A,
+so the distinguishing feature has to be the bowl versus the tick, which survives at 16px.
+
+### Violations, in both directions
+
+**Undocumented decisions.** The clearest cases are the exact decisions two sibling repos cite by
+file and line:
+
+- `margin/src-tauri/src/gdrive.rs` is 953 lines with **zero comments**. Calendar's conventions.md:17
+  points at `gdrive.rs:286` as the origin of `read_json` and explains why the body goes to a `String`
+  first. The reason is written in the calendar's docs and in mail's docs and never in the file.
+- `margin/src-tauri/src/pdf.rs` is 129 lines with zero comments. Calendar:20 and mail:23 both cite
+  `#[tauri::command(async)]` on a synchronous fn at `pdf.rs:90` as the trick for getting off the main
+  thread. `compile_pdf` at line 90 carries no comment saying so.
+- Other zero-comment files over 200 lines in margin: `src/components/EditorView.tsx` (560),
+  `src/import/epub.ts` (534), `src/export/typst.ts` (421), `src/components/Sidebar.tsx` (310),
+  `src-tauri/src/proofing.rs` (275), `src/model/book.ts` (260), `src-tauri/src/lib.rs` (256),
+  `src/editor/search.ts` (233), `src/components/Dock.tsx` (223).
+
+**Narration that should go.**
+
+- `margin/src/components/ExportPreview.tsx:320`: `// render cancelled or page failed; keep the
+  previous canvas`. Lowercase, no full stop, and the second clause narrates the line below.
+- `margin/src-tauri/Cargo.toml:9`: `# See more keys and their definitions at
+  https://doc.rust-lang.org/cargo/reference/manifest.html`, and lines 12-14, the `_lib` suffix
+  paragraph. Both are `cargo new` boilerplate. The three sibling Cargo.toml files deleted them; margin
+  did not.
+- `// Prevents additional console window on Windows in release, DO NOT REMOVE!!` is
+  `src-tauri/src/main.rs:1` in all four repos. Tauri scaffold text, shouting, and none of these apps
+  ships on Windows.
+- Four `// eslint-disable-next-line react-hooks/exhaustive-deps` in margin
+  (`src/components/FindBar.tsx:44`, `src/editor/FloatingToolbar.tsx:69`, `src/editor/Editor.tsx:113`
+  and `:122`). No repo has eslint configured, in package.json or on disk. Dead directives.
+
+Beyond these, a sweep for narration patterns across all four repos found almost nothing. Every hit
+on "comment starts with a verb" or "comment starts lowercase" turned out to be a wrapped
+continuation line of a real reason. The voice is being held.
+
+## 5. The CLAUDE.md tension, resolved
+
+`margin/CLAUDE.md:9` and `margin-caledar/CLAUDE.md:9` are byte-identical: "Avoid excessive comments.
+Only comment when absolutely necessary. Code should be readable and not require comments to
+understand it." margin-docs and margin-mail have no CLAUDE.md.
+
+The code says otherwise. Comment lines as a fraction of source in `src/`, `src-tauri/src/` and
+`shared/src/`:
+
+| repo | source lines | comment lines | share |
+| --- | --- | --- | --- |
+| margin | 10,377 | 125 | 1.2% |
+| margin-calendar | 20,211 | 2,208 | 10.9% |
+| margin-docs | 43,973 | 10,634 | 24.2% |
+| margin-mail | 70,737 | 9,921 | 14.0% |
+
+margin obeys the rule as written. The three younger apps ignore it by a factor of ten to twenty, and
+they are the disciplined ones. The rule was true of a repo that had no siblings; it stopped being
+true the moment a decision had to survive being copied into another repo.
+
+The operating rule, read off the code: **a comment never says what, and always says why.** The test
+already exists in `simplify/guidelines/code-style.md:30`: "delete the comment and ask whether a
+competent person would make the same mistake twice. If yes, keep it. If it just narrates the line
+below, cut it." Under that test margin is not compliant by being sparse; it is under-commented, and
+`gdrive.rs` is the proof.
+
+The two CLAUDE.md files should be corrected or deleted. As written they are a live instruction to
+strip the best thing in this codebase.
+
+## 6. Typographic compliance
+
+Across `*.md`, `*.ts`, `*.tsx`, `*.rs`, `*.css`, `*.toml`, `*.html`, `*.js`, `*.mjs`, excluding
+`node_modules`, `dist`, `target`, `.git`, `target-mas`, `.playwright-mcp` and `gen`:
+
+| repo | em dashes | en dashes |
+| --- | --- | --- |
+| margin | 37 | 5 |
+| margin-calendar | 0 | 0 |
+| margin-docs | 7 | 0 |
+| margin-mail | 3 | 2 |
+
+margin-calendar is perfectly clean. margin holds 42 of the 54 in the suite.
+
+Worst files:
+
+- `margin/simplify/.research/memories-raw.md`, 19. A dump of old memory files, so arguably input
+  rather than committed prose, but it is in the repo.
+- `margin/website/README.md`, 7, all in body copy (lines 3, 21, 22, 23, 25, 37, 41).
+- `margin-docs/src/markdown/corpus/real/margin-website-readme.md`, 7. A copy of the file above, kept
+  as a serializer test fixture. Fixing the website README without fixing the fixture will not help,
+  and fixing the fixture may break a round-trip test.
+- `margin/src/export/run.ts:8` and `:36`, `margin/src/components/Library.tsx:88`,
+  `margin/src/components/ExportPreview.tsx:185`. These four are **user-visible app copy**, which is
+  the worst place for it: the string at `run.ts:8` puts one between "desktop app only" and "open the
+  window from".
+- `margin/src-tauri/stubs/burn-cuda/src/lib.rs:1` and `stubs/cubecl-cpu/src/lib.rs:1`, one each.
+- `margin/simplify/guidelines/prose-and-docs.md:8` is the rule itself quoting both characters. Fine.
+
+margin-mail's three are all legitimate: `scripts/docs-check.mjs:46-47` is the regex that enforces the
+rule, and `src/screens/guide/guide.test.ts:104` asserts the guide text is free of them.
+
+### The gate already exists, in one repo
+
+`margin-mail/scripts/docs-check.mjs` is a 72-line node script wired to `just docs`
+(`margin-mail/justfile:33-34`). It walks every markdown file and reports em dashes, en dashes,
+directory trees and dead relative links. Its own header, lines 2-11, is a model comment. **No other
+repo has it**, and margin, which has 42 offences, is the repo that most needs it. Copying that one
+file into the other three, and extending it past `*.md` to source files so app copy is covered, is
+the single highest-value action in this report.
+
+## 7. Directory trees
+
+None. A search for box-drawing runs and for the ASCII form across markdown, TypeScript, Rust, JSON
+and text in all four repos returned nothing. The rule is being kept without a gate in three of the
+four repos, which is worth noting: the risk is a future file, not an existing one.
+
+## 8. Naming
+
+| | margin | calendar | docs | mail |
+| --- | --- | --- | --- | --- |
+| directory | `python/margin` | `python/margin-caledar` | `rust/margin-editor` | `rust/margin-mail` |
+| package.json name | `margin-app` | `margin-calendar` | `margin-docs` | `margin-mail` |
+| Cargo package | `margin-app` | `margin-calendar` | `margin-docs` | `margin-mail` |
+| Cargo lib | `margin_app_lib` | `margin_calendar_lib` | `margin_docs_lib` | `margin_mail_lib` |
+| bundle id | `studio.margin.app` | `studio.margin.calendar` | `studio.margin.docs` | `studio.margin.mail` |
+| git remote | `priyanshujain/margin` | `priyanshujain/margin-calendar` | `priyanshujain/margin-docs` | **none** |
+| productName | `Margin` | `Margin Calendar` | `Margin Docs` | `Margin Mail` |
+| html title | `margin` | `Margin Calendar` | `Margin Docs` | `Margin Mail` |
+| README h1 | `margin` | `Margin Calendar` | `Margin Docs` | `Margin Mail` |
+| storage prefix | (none stated) | `margincal-` | `margindocs-` | `marginmail-` |
+| licence | FSL-1.1-MIT | MIT | MIT | FSL-1.1-MIT |
+
+Disagreements, worst first:
+
+1. **`python/margin-caledar` is a typo.** Confirmed. Everything inside it says `margin-calendar`,
+   including the remote and the Nix flake output (`ci.yml:81`, `nix build .#margin-calendar`).
+2. **`rust/margin-editor` versus `margin-docs`.** Confirmed. The directory is the only place the
+   word "editor" appears as a name; package, crate, bundle id, product name and remote all say docs.
+3. **`python/` and `rust/` parents are wrong for all four.** All four are Tauri apps with a React
+   front end and a Rust backend. None is a Python project. This is not cosmetic:
+   `margin-docs/package.json:33` and `margin-mail/package.json:24` both carry
+   `"margin-shared": "file:../../python/margin/shared"`, and `margin-mail/.github/workflows/ci.yml`
+   checks the two repos out into `rust/margin-mail` and `python/margin` (lines 25 and 30) precisely to
+   reproduce that path. The word "python" is baked into a GitHub runner's filesystem layout.
+4. **margin-docs CI is failing on exactly this.** The latest run's failure is
+   `ENOENT: no such file or directory, scandir '/Users/runner/work/python/margin/shared'`. Editor's
+   `ci.yml` runs `pnpm install --frozen-lockfile` after a single checkout, so the relative path has
+   nothing to resolve to. Mail solved it with a second checkout; docs never did. Five of the last six
+   runs failed.
+5. **margin-mail has no git remote.** One local commit, `088ec9c`. Everything else in the suite is on
+   GitHub. Whatever name the repo gets is still an open choice, which makes this the cheapest moment
+   to fix the pattern.
+6. **`margin-app` versus `Margin`.** margin is the only app whose package and crate name is not its
+   product name lowercased and hyphenated. `margin-app` also breaks the bundle id pattern:
+   `studio.margin.app` reads as a namespace with a placeholder in it.
+7. **`margin/index.html` title is lowercase `margin`** while `productName` is `Margin`. The README h1
+   is lowercase too. The other three are consistent title case.
+8. **Licences split two and two**, and neither README in the MIT pair says so. margin and mail are
+   FSL, calendar and docs are MIT, and nothing explains the split.
+9. **Editor's conventions.md:3 points at `../margin` and `../margin-calendar`**, neither of which
+   exists relative to `rust/margin-editor`. The paths only make sense if all four sit as siblings,
+   which is what the rename below produces.
+10. `margin-docs/src/markdown/corpus/real/` holds copies of the calendar's and the editor's own
+    `conventions.md` as test fixtures. Two of the three canonical convention documents exist twice in
+    the suite and will drift.
+
+## 9. Rename proposal, with cost
+
+Target layout: one parent, `~/Workspace/projects/margin/`, holding `margin`, `margin-calendar`,
+`margin-docs`, `margin-mail` as siblings.
+
+**A. `margin-caledar` to `margin-calendar`.** Cheapest and unambiguous.
+Cost: `mv` the directory. No `package.json` anywhere references it. Nothing on GitHub changes; the
+remote is already correct. Only local shell history and any editor workspace file break.
+
+**B. `margin-editor` to `margin-docs`.** Also cheap.
+Cost: `mv` the directory. The `file:../../python/margin/shared` path is unaffected because the depth
+does not change. `docs/conventions.md:3` should be corrected in the same edit. No remote change: the
+remote is already `margin-docs`.
+
+**C. Collapse `python/` and `rust/` into one `margin/` parent.** The expensive one, and the one that
+pays.
+Cost, exhaustively:
+- `margin-docs/package.json:33` and `margin-mail/package.json:24`: `file:../../python/margin/shared`
+  becomes `file:../margin/shared`. Both lockfiles need regenerating.
+- `margin-mail/.github/workflows/ci.yml:21,25,29,30,57,61`: the checkout paths `rust/margin-mail` and
+  `python/margin` become `margin-mail` and `margin`, and the `working-directory` lines follow.
+- `margin-docs/.github/workflows/ci.yml`: needs the second checkout added, which it is currently
+  missing. This fixes the failing build rather than costing anything.
+- Local shell history, editor workspaces, and any absolute path in a memory file.
+- Nothing on GitHub changes. No remote, no clone URL, no release artefact, no bundle id.
+
+**D. `margin-app` to `margin`, and `studio.margin.app` to `studio.margin.writer` or similar.**
+Recommend doing the crate and package rename and **not** the bundle id.
+Cost of the package and crate rename: `package.json:2`, `src-tauri/Cargo.toml:2`, `Cargo.lock`, the
+lib name `margin_app_lib` and every `use margin_app_lib::` in `src-tauri/src/main.rs`, plus any
+workflow that names the binary.
+Cost of the bundle id rename: **do not**. Changing `identifier` on a shipped macOS app orphans the
+application support directory, breaks the Homebrew cask, breaks the updater's signature check, and
+makes the Mac App Store record a different product. The inconsistency is not worth that. Write one
+line in `docs/conventions.md` saying `studio.margin.app` is frozen and why.
+
+**E. Give margin-mail a remote.** `priyanshujain/margin-mail`, matching the other three. Free now,
+and the naming stays consistent by default.
+
+Order: B, A, E, C, D. B and A are free. C is best done immediately after, while mail has no CI
+history to invalidate.
+
+## 10. The proposed house style
+
+### Docs
+
+A README is the project description. Under 15 lines: one paragraph on what it is, one line on how to
+install, one paragraph of links into `docs/`, one line on the licence. margin-docs' README is the
+model. Mail's is eight lines over and those eight lines are already in `docs/design.md`.
+
+`docs/` holds `architecture.md`, `conventions.md`, `design.md`, `setup.md`, `release.md` in every
+app, plus whatever the product genuinely has. No numeric prefixes. No file that is a status report.
+
+`architecture.md` opens with the stack sentence and "The split is strict", then what each side owns,
+then one section per hard part, then `## Order of work`. `design.md` argues product decisions in
+prose under "why" headings and ends with `## Visual language`. `release.md` runs `## Installing
+locally`, `## Cutting a release`, `## What the build needs`, `## Updates`.
+
+`conventions.md` exists in every app including margin, and is split: the shared rules (the five
+identical ones, verbatim) and the app's own. When an app carves out an exception, the carve-out names
+the reason in the same sentence, the way mail:9 names `provider::ProviderError` and the four cases it
+has to branch on. Both em dashes and en dashes are banned, taking editor's wording over the other
+two.
+
+Prose a colleague would write. No em dash, no en dash, no directory tree, ever, and the rule holds
+inside code fences and app copy as well as in body text.
+
+### Comments
+
+A comment records a decision and the alternative that was rejected. It never says what the line below
+does; if you want to, rename something instead.
+
+Shape: a one-line statement of what the file is, a blank comment line, then one paragraph per
+decision. Each paragraph names what was chosen, what was not, and the concrete failure the other
+choice produces. One to seven lines per paragraph. Declarative, third person, no hedging. Doc
+comments on exported items are one sentence.
+
+The test, already written at `simplify/guidelines/code-style.md:30`: delete it and ask whether a
+competent person would make the same mistake twice.
+
+Two consequences worth stating plainly, because the current text says the opposite. The instruction
+in `margin/CLAUDE.md:9` and `margin-caledar/CLAUDE.md:9` is wrong and should be replaced with the
+rule above. And "comments are rare" in all three conventions.md files is false and should be cut: the
+suite averages one comment line in seven, and the three densest repos are the three best ones.
+
+### Enforcement
+
+Copy `margin-mail/scripts/docs-check.mjs` into the other three repos, wire it to `just docs` and to
+CI, and extend it beyond `*.md` to `*.ts`, `*.tsx`, `*.rs` and `*.css` so app copy is covered. That
+one file catches every offence in section 6, plus the dead links, plus any future tree. Fix margin's
+42 dashes first, starting with the four in user-visible strings.

simplify/.research/frontend-utils.md

@@ -0,0 +1,450 @@
+# Non-component TypeScript across the four apps
+
+Scope: hooks, utilities, stores, the IPC layer. Non-test `.ts`: margin 4061 lines, margin-calendar 3811,
+margin-docs 16868, margin-mail 11429. Shorthand: **M** margin, **C** margin-calendar, **D** margin-docs,
+**X** margin-mail.
+
+## The shared package already exists
+
+`margin-shared` is at `/Users/pj/Workspace/projects/python/margin/shared`: a `file:` dependency of M, D and X,
+exporting `.`, `./fonts`, `./icons` and two stylesheets, 299 lines of source today.
+
+**C is not wired to it at all**, in TypeScript or CSS. It has no `margin-shared` in `package.json` and its
+`src/styles/tokens.css` does not `@import "margin-shared/css/tokens.css"` the way the other three do. That
+dependency line is the prerequisite for everything here.
+
+**The extraction pattern is already proven.** `M/src/model/fonts.ts` (41 lines) and `D/src/model/fonts.ts`
+(40) are re-export shims: pull the catalogue from `margin-shared/fonts`, declare one app-local alias
+(`BookFonts` vs `DocumentFonts`) so call sites keep the app's own noun. Copy that shape.
+
+No app uses tsconfig path aliases, so nothing needs build config beyond the dependency. All three vitest apps
+run `environment: "node"`, so shared hooks need the `typeof window` guards D already writes, or
+`vi.stubGlobal` as in `D/src/width.test.ts:24`. No app has a `utils/`, `lib/`, `helpers/` or `hooks/`
+directory: everything is either a single-purpose top-level module or defined inline atop the one component
+that needs it.
+
+## Byte-identical today
+
+**`src/escape.ts`**, all four. 36 lines in M, C and D, all three md5 `3b1f67d691647be7d61a23a5acd96a7b`. X's
+is 40 lines, differing only by a four-line header; strip comments and all four hash identically
+(`9c8530a09b35e5d697bb2b95674a2e73`). Signature `useEscapeLayer(active: boolean, onEscape: () => void): void`,
+a module-level stack of Escape handlers behind one lazily-bound capture-phase listener. Move verbatim, keeping
+X's header. 144 duplicated lines, zero risk. All three keyboard registries already defer to it by name rather
+than handling Escape themselves, and its `const latest = useRef(onEscape); latest.current = onEscape;` is an
+inline `useLatest` that falls out of the extraction for free.
+**`useMediaQuery`**, all four `src/useMedia.ts`, byte-identical (`c3499ac5ee3d1a12b138d71b2cc787ed`).
+**`usePhone` and `useTouch`**, C/D/X, byte-identical bodies (`d565f08a...`, `f4285e4c...`), with `PHONE_QUERY
+= "(max-width: 640px)"` and `TOUCH_QUERY = "(pointer: coarse)"`; the only difference between the three files
+is prose describing each app's layout. M has neither, only a stale `useCompact` on a 899px query that D
+deleted when it added the phone/touch pair.
+
+**`src/theme.ts`**, M/C/X. Strip comments, normalise the key, all three hash identically
+(`ab9c99ff29565c686028e16960274d9d`); the literal M-to-C diff is one line. **`src/store/useTheme.ts`**, M and
+C, byte-identical (`b48a3bccfadd21b9bb4efa91eef5041c`, 16 lines); X's 17 differ only by extracting a
+`set(theme)` action. **`src/store/useToast.ts`**, C and D, byte-identical (`dfc90357bbcfbbfe71ffb8ba0e680c00`,
+15 lines). M has no toast.
+
+**The `src/ipc.ts` preamble.** Lines 1 to 41 of C's and D's are byte-identical
+(`afde11927f75a3a81b2b459658c5b7be`), doc comments included: header, `isTauri`, `isMobileOs` with its iPadOS
+carve-out, `isDesktop`, `isMacDesktop`, `live()`. So is the body of `call<T>`
+(`b4259488afdd6a0f154b8e86eae1ff9c`). X has the same code with two comments abridged, plus one real addition
+at `X/src/ipc.ts:752-758`: it logs a failed command to Rust before rethrowing, skipping `log_note` itself to
+avoid a loop.
+
+**`src/store/useOverlays.ts`**, C (64 lines) and X (72). Diffed with comments stripped, the entire difference
+is the `Overlay` union and one prettier reflow of `push`; all seven actions are character-identical. X's
+header: "Ported from the calendar's store of the same name."
+
+**The keys platform block**, C/D/X, not one character differing, at `C:76-87`, `D:206-217`, `X:521-532`. Also
+byte-identical across those three: the `NAMED` glyph map, `commandMatches`, `isTyping`, and
+`pushContext`/`useKeyContext`.
+
+```ts
+const isMac = typeof navigator !== "undefined" && /mac|iphone|ipad/i.test(navigator.userAgent ?? "");
+export const PRIMARY_LABEL = isMac ? "⌘" : "Ctrl+";
+export const primaryHeld = (e: { metaKey: boolean; ctrlKey: boolean }): boolean =>
+  isMac ? e.metaKey : e.ctrlKey;
+export const secondaryHeld = (e: { metaKey: boolean; ctrlKey: boolean }): boolean =>
+  isMac ? e.ctrlKey : e.metaKey;
+```
+
+## The three cleanest lifts
+
+**`createOverlays<T>()`.** Nothing in the body knows what an overlay is. Each app writes `export const
+useOverlays = createOverlays<Overlay>();` and keeps its own union. About 130 lines at zero behavioural risk. M
+and D have no overlay store but both have palettes and dialogs and would adopt it.
+
+```ts
+export interface OverlayState<T extends string> {
+  open: T | null;
+  trail: T[];
+  show: (overlay: T) => void;
+  push: (overlay: T) => void;
+  back: () => void;
+  reachedFrom: (previous: T) => void;
+  toggle: (overlay: T) => void;
+  close: () => void;
+}
+export function createOverlays<T extends string>(): UseBoundStore<StoreApi<OverlayState<T>>>;
+```
+
+**`onAppEvent`.** Nobody wraps Tauri's `listen`, and it shows. X is the exception, at `X/src/App.tsx:69-77`,
+signature `onAppEvent<T>(name: string, handler: (payload: T) => void): () => void`. It returns a synchronous
+unsubscribe, so each effect is one line, and it falls back to `window.addEventListener` for a `CustomEvent` of
+the same name outside Tauri, which is what lets Playwright drive the connect flow in a browser. C hand-rolls a
+four-`.then(stop => stop())` teardown at `C/src/App.tsx:52-86`; D uses a third pattern, a module exporting
+`startWorkspaceEvents(): () => void` that the shell mounts (`D/src/workspace.ts:366-378`).
+The event names are already common property: `menu-action` in all four, `auth`, `sync-progress` and
+`store-changed` in C and X, `pdf-warnings` in M and D. Four apps, the same names, three subscription
+mechanics. Lift X's nine lines; keep D's "module exports `start*()`" convention on top.
+
+**`useToast` and `notify`.** X's 34 lines beat the byte-identical 15 in C and D. Strict superset: an optional
+`ToastAction { label, keycap?, run }` for undo, and a `seq` counter bumped on every notice. That counter is a
+real fix. Auto-dismiss lives in the component in all three, and C's and D's dismiss effects omit a nonce from
+the dep array, so notifying the same string twice does not restart the countdown; the second toast inherits
+the remainder of the first one's timer. The dwell times also differ for no reason: 5000ms, 4200ms, 6000ms.
+M has no toast, only a private `notify` at `M/src/store/useBackup.ts:45` writing into `useBook`'s notice field.
+
+## Theme: margin-docs wins, and it is not close
+
+`D/src/theme.ts` is 167 lines against 16, and every extra line earns it: a seven-palette table with a `scheme`
+per row; a real tri-state `ThemeChoice = Theme | "system"` with a remembered light/dark pair;
+`storedPreference()` dropping a stored id that no longer names a theme (without it, a palette retired between
+releases leaves the root with a `data-theme` no stylesheet answers, which is not one broken colour but all of
+them); `watchSystemScheme()`, the only live `prefers-color-scheme` subscription in any app;
+`saved()`/`store()` guarding `localStorage` behind `typeof` and `try`/`catch`; and `theme.test.ts` (172
+lines), the only theme test, holding the TypeScript table and the boot script's copy of it to one table.
+
+X fakes a tri-state at the UI layer: "System" means deleting the stored key (`forgetThemeChoice()`,
+`X/src/appearance.ts:41`), so it is a snapshot, not a subscription. Pick System at night and it stays dark
+through the morning.
+
+```ts
+export interface ThemeConfig<T extends string> {
+  themes: readonly ThemeInfo<T>[];
+  keyPrefix: string;
+  fallback: Record<Scheme, T>;
+}
+export function createThemeStore<T extends string>(config: ThemeConfig<T>): ...;
+export function bootScript<T extends string>(config: ThemeConfig<T>): string;
+```
+
+Generating the boot script from the same config is the part to insist on. All four apps hand-maintain an
+inline `<script>` in `index.html` re-reading the theme keys before the bundle exists, and D re-encodes its
+whole palette-to-scheme table there in plain JS.
+
+## The root-setting pattern, six times over
+
+Bigger than theme. Read a boot attribute first because `index.html` already applied it, fall back to
+`localStorage`, apply to the root, write back. `src/theme.ts` in all four on `data-theme`; `X/src/pane.ts` (20
+lines) on `data-no-pane`, its header saying it is "exactly the shape `src/theme.ts` uses"; `D/src/width.ts`
+(52) on `data-width`; `M/src/width.ts` (28) doing the same job through a `--measure` custom property;
+`M/src/panes.ts` on `--pane-sidebar`/`--pane-dock` with its own private `clamp`; `X/src/appearance.ts` (43) on
+`--font-ui`, `--font-heading` and `--body-size`.
+The rule these obey is stated three times in three files: a store may not touch the DOM, and a layout fact the
+stylesheet needs on first paint has to be an attribute, not a class on a component. Write it down once.
+Key naming is already strict: every key in every app is `<slug>-<setting>`, slugs `margin-`, `margincal-`,
+`margindocs-`, `marginmail-`. Counted: 8 keys in M, 6 in C, 17 in D, 9 in X. That prefix is the only per-app
+parameter a storage helper needs.
+
+```ts
+export function makeStorage(prefix: string): {
+  readString(key: string, fallback: string | null): string | null;
+  readJson<T>(key: string, fallback: T): T;
+  write(key: string, value: string): void;
+  remove(key: string): void;
+};
+export function rootSetting<T extends string>(opts: {
+  attribute: string; key: string; values: readonly T[]; fallback: T;
+}): { initial(): T; apply(value: T): void };
+```
+
+D has written the guarded accessor pair nine times inside one app: `theme.ts:105`,
+`store/useUpdate.ts:64,73,85`, `store/useProofing.ts:102,111`, `store/useDocumentFonts.ts:58,77`,
+`workspace.ts:60,70`, `width.ts:33`, with the catch comment ("A webview with storage denied still X, it just
+forgets between launches") repeated four times with only the verb swapped. Adopting it also fixes unguarded
+reads in `M/theme.ts:8`, `C/time.ts:16`, `C/store/useCalendarView.ts:13`, `X/theme.ts:13`, `X/pane.ts:14` and
+`D/Outline.tsx:30`; several run during module initialisation and would take the whole app down on a throw in a
+storage-denied webview, and C's is already why `components/overlayModel.test.ts:20-31` stubs a global.
+
+Do not reach for zustand's `persist` middleware, nor a `useLocalStorage` hook: the boot script reads these
+keys before any bundle exists, so the shapes must stay plain and hand-chosen. `X/pane.ts:1-8` and
+`X/appearance.ts:1-7` both document the constraint. `width.ts` itself should not be shared either. M has four
+named widths on a CSS variable, D five on an attribute plus command wiring; only the persistence overlaps, and
+`rootSetting` covers it.
+
+## The IPC layer
+
+Uniform in three of four and worth stating as the target: a frozen `src/ipc.ts` holding DTOs mirroring
+`src-tauri/src/dto.rs` plus `call<T>`, and thin per-domain modules in `src/api/` doing nothing but naming a
+command, e.g. `export const labelsList = (accountId: string | null) => call<LabelInfo[]>("labels_list", {
+accountId });`
+
+C has 6 api modules and 41 lines, D 9 and 211, X 16 and 386. X's `ipc.ts` is 760 lines because it has the most
+DTOs, not because it is structured differently. Only X states the rule explicitly ("Nothing outside src/api
+may call `call` directly").
+
+M is the outlier. No `src/api`, `invoke` imported directly in 7 files and called at 8 sites. Its 43-line
+`ipc.ts` has no `isTauri`, no `live()`, no `isMacDesktop` and no dev-fixture branch, which is why it has no
+browser dev harness either. **And a real bug**: `M/src/ipc.ts:3` names its constant `isDesktop` but computes
+what C/D/X call `isTauri`. The same identifier means the opposite thing in different apps, and in M it gates
+`runWritingTool`, `listSystemFonts` and `gdriveListBackups`. M is desktop-only today so it does not bite yet.
+
+Shareable: the whole preamble plus `call<T>` as a factory, since the dynamic `import("./dev/mockIpc")` path is
+necessarily per-app. X's version wins, a strict superset of the byte-identical C and D; the `log_note`
+recursion guard is the detail nobody would re-derive. DTOs stay per-app. `C/src/ipc/` exists and is empty;
+delete it.
+
+## The dev harness
+
+C, D and X each have `src/dev/fixture.ts` and `src/dev/mockIpc.ts`: 134/222 lines, 696/344, 1769/1572. Every
+`mockCall` is `(command: string, args?: Record<string, unknown>) => Promise<T>`, a switch on `command` ending
+in the same byte-identical `dev mock has no handler for ${command}` throw, but the bodies are entirely
+app-specific. A `createMockIpc(handlers)` supplying the dispatch and default throw is marginal; the real
+shared pieces are the mock branch inside `call<T>` and X's `onAppEvent` fallback, both covered above. M has
+no dev harness and cannot be driven in a browser.
+
+## Keyboard: three registries, one design, no chords
+
+C, D and X each have `src/keys` with `bindings.ts`, `keymap.ts`, `commands.ts`, `menu.ts`. No file is
+byte-identical, but the scaffolding is one module forked three ways and several blocks inside are identical
+(listed above).
+
+**X's registry should win.** Three reasons that matter.
+
+Its `resolve()` layers contexts instead of replacing them (`X/keys/keymap.ts:94-109`). A `screener` or `focus`
+frame overrides only the keys it declares and leaves the base `view` keymap live underneath; only `overlay`
+and `editor` shadow wholesale, via an explicit `SHADOWS_VIEW` list. C and D fall from the top frame straight
+to `global`, which kills the base keymap the moment any non-overlay frame is pushed. X subsumes them; they
+cannot express X.
+
+Its `normalizeCombo` treats shift as a first-class modifier, so `Cmd+A` and `Cmd+Shift+A` are distinct. D
+preserves case instead (`cmd+F` vs `cmd+f`), which works for letters on a US layout and breaks for punctuation
+that only exists shifted. **C's lowercases behind a modifier, so `cmd+F` and `cmd+f` collide silently.** That
+is a live bug.
+
+Its `bindings.ts` does not import `commands.ts`, so the table, the sheet and the palette are testable without
+booting stores or Tauri; in C and D the dependency runs bindings to commands to every store. Its `commands.ts`
+is 75 lines with zero store imports: a `Map<CommandId, Handler[]>`, `registerCommands` returning its own
+teardown, last-registered wins, so a screen takes over a verb on mount and hands it back. C's and D's are
+static tables reaching into the whole app (224 and 433 lines). D is halfway there with its `onCommand`
+fan-out, worth keeping alongside the stack for cases needing multiple listeners.
+
+Take `menu.ts` from D instead: the same three lines everywhere, but only D exports its id list and tests that
+every menu id names a real command.
+
+**No app supports chords.** All three carry the same header line: "Nothing is chorded and nothing is modal.
+Two keys never combine into a third meaning." No pending prefix, no timeout, no sequence buffer. A `g i`
+binding is new work; X's `Map<string, Binding[]>` index and single `comboOf` extend to it most cleanly.
+
+**M has no registry and should adopt one.** Four unrelated mechanisms: an `if`/`else if` chain on a
+capture-phase window listener at `M/components/EditorView.tsx:167-192`, a second competing window listener for
+Cmd+K in `M/editor/FloatingToolbar.tsx:57-70`, TipTap extension shortcuts in four files, and two hand-rolled
+`menu-action` chains in `App.tsx:25-35` and `EditorView.tsx:199-206` unaware of each other.
+
+M has no platform detection at all: `grep navigator.` over its `src` returns two clipboard calls. The five
+`e.metaKey` tests in `EditorView.tsx` are macOS-only and silently dead on Linux and Windows; `primaryHeld`
+fixes that for free. The blocker is that M has no palette and no shortcut sheet, so the "generated, never
+maintained" payoff has nowhere to land yet.
+
+Stays per-app: `BINDINGS` (20 rows, 20, ~70), the `CommandId` union, `GROUPS`, `MENU_IDS`, the command
+implementations, and app-specific `KeyContext` members. `KeyContext` has to become a type parameter and
+`SHADOWS_VIEW` an app-supplied list. The two `isMac` regexes differ by design and confusingly little:
+`keys/bindings.ts` uses `/mac|iphone|ipad/i`, `ipc.ts` uses `/mac/i` gated on `isDesktop`, both correct for
+their purpose. One `margin-shared/platform` should export both, plus `isTauri`, `isDesktop`, `isMacDesktop`,
+`live`, `PRIMARY_LABEL`, `primaryHeld` and `secondaryHeld`, with an injectable user agent so the non-Mac
+branch is finally testable; no test exercises it today.
+
+## Stores: the conventions are already uniform
+
+All 42 stores checked. Every one uses the plain `create<State>((set, get) => ({ ... }))`. Not one uses curried
+`create<T>()(...)`. **No middleware anywhere**: zero hits for `persist`, `subscribeWithSelector`, `immer`,
+`devtools`, `useShallow` or `zustand/shallow` in any app. Nothing is imported from `zustand` except `create`.
+
+Selectors are uniformly inline, `(s) => s.field`, one hook call per field rather than one destructured object.
+No exported selector functions exist in any store directory in any app. That is why no shallow comparator is
+needed: every subscription is to a primitive or a stable reference. About 620 inline selector sites and 676
+`getState()` calls.
+
+Two conventions worth writing down because they are universal and currently retyped everywhere: `if (!live())
+return;` as the first line of every backend-touching action, about 40 places; and `error: String(e)` in state,
+never `e.message`.
+
+The async action shape repeats about 100 times: optimistic set, try, replace with the server's answer, catch,
+roll back and a `Could not ...` toast. Counts: M 1, C 10, D 33, X 53. **I would not abstract it**: the bodies
+are five lines and each message is bespoke. Share the `Phase` union and a `describe(e)` helper only.
+
+`useSearch`, `useAccounts` and `useSync` look shareable by name and are not. The three
+
+`useSearch` stores do three different jobs. `useAccounts` in C and X shares a real idea, an OAuth consent
+promise bridged over a Tauri event with the resolver stashed in state, but it is on its third hand-copy
+(`M/store/useBackup.ts:70` to C to X) and is ~60% app-specific. Share the bridge, not the store, plus
+`openAuthUrl`/`copyAuthUrl`, character-identical in both and pure utility.
+
+```ts
+export function deferred<T>(): { promise: Promise<T>; settle: (value: T) => void };
+export function latestOnly<A extends unknown[], R>(fn: (...a: A) => Promise<R>): (...a: A) => Promise<R | undefined>;
+```
+
+`latestOnly` covers the stale-response race both search stores solve differently: D with module-level
+monotonic counters (`useSearch.ts:20-21`), X by re-comparing the query string (`useSearch.ts:108`). D's is
+more general; X's breaks if two callers share a query.
+
+X's `useSync` is the best sync store, because ~160 of its 210 lines are pure exported functions over
+`SyncStatus[]` rather than store code, with a 9.6KB test behind them. C keeps the same dedupe logic as an
+effect-local closure variable in `App.tsx`.
+
+## Cross-cutting utilities
+
+**Confirmed absent from all four**: any debounce or throttle utility; deep equality; a `safeParse`/`tryParse`
+wrapper; class-name joining (no `cx`, no `clsx`, no `classNames`, and no such dependency); `measureText` or
+any text-measurement helper; `Intl.RelativeTimeFormat`; `Intl.PluralRules`; `navigator.userAgentData`;
+`nanoid`/`uuid` or any id counter; and `useLocalStorage`, `useInterval`, `useRaf`, `useEvent`, `useLatest`,
+`useMountedRef` or an exported `sleep`. No truncation helper; truncation is done in CSS.
+
+The class-name negative is a deliberate architectural choice, not an oversight: all four apps style off data
+attributes, so no app ever concatenates class names. Do not introduce `cx`.
+**debounce.** Written longhand at 15 sites across all four. The React-effect variant is the same five lines in
+at least six places and is worth one `useDebounced<T>(value, ms)`; D's `QuickOpen.tsx:88` and
+`FindInFiles.tsx:70` are already identical and name the constant `DEBOUNCE_MS`. Leave the class-field and
+module-level timers alone; their cancel/flush semantics are the point.
+
+**`clamp`: 6 definitions plus 12 inline sites, zero shared.** `C/grid/fit.ts:89` and
+`C/components/QuickCreateModel.ts:147` are the identical one-liner duplicated *within C*:
+
+```ts
+const clamp = (n: number, lo: number, hi: number) => (n < lo ? lo : n > hi ? hi : n);
+```
+
+`C/components/EventDetailsModel.ts:45` should win: it is the only one guarding an inverted range, which
+matters because half the call sites pass `length - 1` as the high bound and that goes negative on an empty
+list. `QuickCreateModel.ts:156,163,171` already works around exactly this at every call. Add a `clampIndex(i,
+length)` for the ten index sites. `M/ExportPreview.tsx:92` and `D/ExportPreview.tsx:143` are the
+byte-identical zoom clamp.
+
+**Byte size: four implementations, three spellings.** `D/UpdateDialog.tsx:21` says `kB`, `D/FileViewer.tsx:43`
+says `bytes` and `KB` with one decimal, `X/screens/format.ts:52` says `B`/`KB`/`MB` with rounding,
+`X/screens/Settings.tsx:940` adds GB and adaptive precision. 1536 bytes renders as "1.5 KB", "2 kB" and "2 KB"
+in one product family. X's `space()` wins: the only one reaching GB, and its `mb < 10 ? toFixed(1) :
+Math.round(mb)` rule actually solves what D's UpdateDialog comment states ("so the number under the bar stops
+twitching"), by significant figures rather than fixed decimals.
+
+**Relative time: three hand-rolled ladders, no two agreeing.** `M/src/time.ts:1` is the only standalone
+module; `M/src/backup.ts:61` is a second copy in the same app with the prefix baked into every branch;
+`D/components/Settings.tsx:45` is a third, inline, with "Checked" hardcoded throughout. They diverge in
+behaviour, not just text: M floors, D rounds; M's cutover is 7 days, D's 30. D's rounding makes 89 seconds
+"just now" and 91 seconds "2 minutes ago". M's wins: the only one guarding clock skew with `Math.max(0, now -
+ts)`, and flooring is right for "how long ago". Callers compose their own prefix, deleting `backup.ts:61` and
+reducing `Settings.tsx:45` to one line. X has no "X ago" at all; `rowTime`/`messageTime`
+(`screens/format.ts:34-49`) go straight to calendar-day buckets and are the only implementation counting by
+calendar day via local midnight rather than elapsed hours, which is the difference between "Yesterday" being
+right and being off by a few hours every evening. Keep both.
+
+**`useClock` is the missing half.** `C/src/useClock.ts` (`useTick<T>`, `useMinuteTick`, `useHourStart`)
+re-schedules against wall-clock rather than a `setInterval` and treats `visibilitychange` and `focus` as
+ticks, because a timer's deadline is measured in time the machine spent awake. C is its only consumer today,
+but M's `relativeTime` callers both take a `now` prop that has to come from somewhere, and X's row formatters
+default to `Date.now()` at call time and go stale on a window left open overnight. Ship it beside
+`relativeTime`.
+
+**`Intl.DateTimeFormat`: no shared factory.** The same `{ day: "numeric", month: "short" }` formatter is
+constructed in 6 X files and the `hourCycle: "h23"` clock in 3. M and D use bare `toLocaleDateString()`. A
+memoised `dateFormat(options)` collapses the lot; X's cached-module-constant style is the right pattern.
+
+C's `src/time.ts` (136 lines) avoids `Intl` entirely with hand-written day and month arrays, a deliberate
+product decision for a calendar grid that should stay. Its `startOfDay`, `addDays`, `isSameDay`, `toDateOnly`,
+`parseDateOnly` are reusable date maths and should move; `startOfDay` is already written three times across C
+and X (`C/time.ts:23`, `X/screens/format.ts:20`, `X/SnoozePicker.tsx:72`).
+
+**Focus management: one app has it, three do not.** `python/margin/src/focus.ts` (56 lines) is a proper trap:
+a `FOCUSABLE` selector, Tab wrapping both directions, opener restore on teardown, and a module-level
+`focusTrapped()` so the global key handler can stand down. Five call sites in M.
+
+```ts
+export function useFocusTrap(ref: RefObject<HTMLElement | null>, active = true): void;
+export function focusTrapped(): boolean;
+```
+
+C has autofocus only, no trap and no restore (`components/overlayShell.tsx:51-56`). D and X have neither: both
+ship `role="dialog" aria-modal="true"` markup with imperative `.focus()` on mount and no trap behind it.
+**This is the one item where sharing fixes an accessibility gap in three apps rather than removing
+duplication.** The wrinkle: M's `focusTrapped()` and the other apps' context stack are two mechanisms for one
+idea. Either the trap pushes an `overlay` frame, or the shared keymap takes a "something external owns the
+keyboard" predicate.
+
+**Scroll position restore: near-identical in M and D, and D says so.** `python/margin/src/editor/positions.ts`
+(64 lines) and `rust/margin-editor/src/editor/positions.ts` (52) share an identical `{ from, to, scroll }`
+interface, the same guarded `readAll`/`write`, and the same load/save API. D's header names the relationship:
+M keys by book then chapter, D by absolute path, "and that path is the whole key". D adds an LRU trim at
+`LIMIT = 200`; M's map grows unbounded. D wins, with a flat string key M composes as `${bookId}/${chapterId}`.
+
+`scrollIntoView` is raw at 8 sites, never wrapped; `M/editor/search.ts:98` and `D/editor/search.ts:111` are
+byte-identical. Worth extracting alongside it is `D/components/Outline.tsx:79-89`, the only implementation
+avoiding `scrollIntoView` scrolling every ancestor, already duplicated once inside D at
+`editor/linkPicker.ts:572`.
+
+**JSON.** 10 `JSON.parse` sites, 8 guarded inline, 2 not: `M/library.ts:31` and `M/project.ts:19` parse a file
+read off disk with no catch, so a truncated or hand-edited project file throws unhandled. Fold the guarded
+ones into `readJson<T>(key, fallback)`; the file reads want `parseJson<T>(text): T | null`. D's `const parsed:
+unknown = JSON.parse(...)` then narrow is the right discipline; M and X cast straight to the target type.
+**`plural`** is the same function under different names in `M/store/useBackup.ts:56` and
+`D/linkRewrite.ts:694`, plus 10 open-coded `${n === 1 ? "" : "s"}` sites including two byte-identical ones in
+`X/screens/ReadingPane.tsx:235,502`. M's name wins.
+
+**ResizeObserver**: 13 raw instantiations, no hook. `M/ExportPreview.tsx:64` and `D/ExportPreview.tsx:104` are
+byte-identical, as are `M:238`/`D:339` and the `IntersectionObserver` at `M:286`/`D:395`. Any shared
+`useResize` must carry the null guard `X/screens/MessageBody.tsx:207` documents and the others lack:
+"`ResizeObserver.observe(null)` throws hard enough to take the screen with it". `getBoundingClientRect` has 32
+inline sites, all positioning rather than text metrics; the popover-placement clamp is duplicated across four
+apps but the anchoring rules differ meaningfully, so it is the lowest-confidence item here. Id generation is M
+only, `crypto.randomUUID()` raw at 8 app-domain sites; C, D and X take ids from Rust, so there is nothing to
+share.
+
+## Updates: four apps, four answers
+
+M has `src/updater.ts` (111 lines) plus `store/useUpdater.ts` (34), a `direct` vs `appstore` channel split,
+and it holds the live `Update` resource handle in the zustand store. C has `keys/updates.ts` (41), toast-only,
+"Ported from margin's `src/updater.ts`, minus its progress dialog"; it is the only one of the four with a
+`packagedBy()` guard, so a nix or homebrew install is told to update through its package manager instead of
+self-updating. X has no update module at all: `checkForUpdates` is inline at `X/src/App.tsx:98-118`, with a
+second copy in `screens/Settings.tsx`.
+
+D has `src/update.ts` (171) plus `store/useUpdate.ts` (129), the best of the four: named phase transitions
+rather than a generic `set(partial)`; `total: number | null` so a missing content-length draws an
+indeterminate bar instead of 0% forever; version and notes as plain strings so no Rust handle sits in the
+store; a launch delay and 24-hour interval for automatic checks; a flush of the pending save before
+`relaunch()`; and a discriminator for "this dev build has no updater plugin" so that reads as a sentence
+about the build. Take D's store and driver, fold in C's `packagedBy` guard as an option.
+
+## Bugs found, worth fixing regardless of any extraction
+
+- `marginmail-theme` is declared as two constants in two files, `X/src/theme.ts:8` and
+  `X/src/appearance.ts:14`.
+- X's `checkForUpdates` lacks C's `packagedBy()` guard, so a package-manager-installed build will try to
+  self-update over a path it does not own.
+- C's `normalizeCombo` lowercases the key behind a modifier, so `cmd+F` and `cmd+f` are one binding.
+- `M/src/ipc.ts:3` names `isDesktop` what the other three call `isTauri`, and it gates three IPC calls.
+- `M/library.ts:31` and `M/project.ts:19` parse a file off disk with no catch.
+
+## Ranked
+
+1. `escape.ts`. ~144 lines, byte-identical in four apps.
+2. `createOverlays<T>()`. ~130 lines, code-identical today.
+3. `platform.ts` (both halves). ~50 lines, byte-identical in three, fixes two M bugs.
+4. `onAppEvent`. ~60 lines, better teardown, unlocks browser testing for two apps.
+5. `useMedia.ts`. ~120 lines, byte-identical bodies in three apps.
+6. `useToast` plus `notify`. ~60 lines, strict superset, fixes a timer bug in two.
+7. `makeStorage` and `rootSetting`. ~120 lines, deletes nine copies in D, fixes six unguarded reads.
+8. `call<T>` factory plus the `ipc.ts` preamble. ~50 lines.
+9. Theme, from D, with a generated boot script. ~250 lines, needs a per-app table.
+10. Small utilities: `clamp`, `fileSize`, `relativeTime` plus `useClock`, `plural`, `positions.ts`,
+    `useDebounced`, `dateFormat`, `latestOnly`, `deferred`. Collectively ~250 lines and several
+    user-visible inconsistencies.
+11. `useFocusTrap`. Not a saving; an accessibility fix for three apps.
+12. The keyboard registry, from X. Largest and highest-value, but needs `KeyContext` parameterised and
+    `SHADOWS_VIEW` injected, and M needs a palette before it benefits.
+13. The update store and driver. Four designs to reconcile; do it last.
+
+Items 1 to 6 are mechanically identical across apps today and drop into the existing package with no behaviour
+change. The one prerequisite is adding `margin-shared` to margin-calendar.
+

simplify/.research/icons-and-primitives.md

@@ -0,0 +1,380 @@
+# Icons and the smallest UI primitives
+
+Audit of `margin` (`/Users/pj/Workspace/projects/python/margin`), `margin-calendar`
+(`/Users/pj/Workspace/projects/python/margin-caledar`), `margin-docs`
+(`/Users/pj/Workspace/projects/rust/margin-editor`) and `margin-mail`
+(`/Users/pj/Workspace/projects/rust/margin-mail`) against the partial shared package at
+`/Users/pj/Workspace/projects/python/margin/shared`.
+
+## The shared package as it stands
+
+`shared/src/icons.ts` exports twelve paths plus `SUN_DISC`. Its header comment says the two apps
+kept drifting, that a path is a design decision, and that `Icon` is deliberately not shared because
+sharing it "would make this package depend on React for twenty four lines, and a component is where
+an app is entitled to differ."
+
+Two of those three claims no longer hold.
+
+The React argument is wrong on the mechanics. `shared/package.json` has no `dependencies` block at
+all, no build step, and every app resolves the TypeScript source through its own bundler. All four
+apps are on `react: ^19.1.0`. A `peerDependencies` entry costs zero bytes and installs nothing;
+it is a version assertion, not a dependency.
+
+"An app is entitled to differ" is contradicted by the code. Three of the four `Icon.tsx` files are
+byte identical (md5 `0ec1a568818f20ed8eed8ad46fbaa2b1`):
+`/Users/pj/Workspace/projects/python/margin/src/components/Icon.tsx`,
+`/Users/pj/Workspace/projects/python/margin-caledar/src/components/Icon.tsx`,
+`/Users/pj/Workspace/projects/rust/margin-editor/src/components/Icon.tsx`. In two years nobody has
+exercised the entitlement.
+
+Also worth noting: `margin-calendar` does not consume `margin-shared` at all. There is no
+`margin-shared` line in `/Users/pj/Workspace/projects/python/margin-caledar/package.json`, and
+`src/styles/tokens.css` is a hand copy of the shared file's values. Everything below that looks
+like calendar drifting away from the family traces back to this one fact.
+
+## The Icon component, line by line
+
+All four render the same SVG: `viewBox="0 0 24 24"`, `fill="none"`, `stroke="currentColor"`,
+`strokeWidth="1.6"`, `strokeLinecap="round"`, `strokeLinejoin="round"`, `size = 16` default,
+`{children ?? <path d={d} />}`. Props are `d?: string`, `size?: number`, `children?: ReactNode`.
+
+`margin-mail`'s at `/Users/pj/Workspace/projects/rust/margin-mail/src/ui/Icon.tsx:12` is the only
+one that differs, in four ways, all of them improvements:
+
+- `export interface IconProps` rather than a private `interface` (line 4).
+- `className="icon"` (line 15), which is what lets CSS reach the element.
+- `aria-hidden="true"` (line 24). The other three emit an unlabelled SVG into the accessibility
+  tree at every one of their 142 combined call sites.
+- `import "./Icon.css"` (line 2), whose entire contents are `.icon { flex: none; }`
+  (`Icon.css:2-4`).
+
+There is no alignment handling in any of the four components. No `display`, no `vertical-align`,
+no `shape-rendering`, no `vector-effect`, no transform.
+
+## Alignment: the thing that keeps being fixed four times
+
+Across all four repos there are **zero** occurrences of `shape-rendering`, `vector-effect`,
+`crispEdges`, `geometricPrecision`, or a `translate(0.5 0.5)` style half pixel offset. The
+alignment problem is not sub-pixel rasterisation. It is the two ordinary CSS facts about an inline
+SVG: it sits on the text baseline, and it is a flex item that will shrink.
+
+Five different fixes exist for those two facts, and only one app fixes them centrally.
+
+`margin-mail` fixes both once:
+
+- `/Users/pj/Workspace/projects/rust/margin-mail/src/styles/app.css:88` `svg { display: block; }`
+  This is the only global SVG rule in the suite. The other three apps have no `svg` selector at
+  document level at all.
+- `/Users/pj/Workspace/projects/rust/margin-mail/src/ui/Icon.css:2` `.icon { flex: none; }`
+
+The other three patch it per site:
+
+- `/Users/pj/Workspace/projects/python/margin-caledar/src/styles/overlays.css:36`
+  `.panel-note[data-icon] svg { flex: none; transform: translateY(2px); }`
+- `/Users/pj/Workspace/projects/python/margin-caledar/src/styles/details.css:114`
+  `.details-row[data-block] > svg { margin-top: 2px; }`
+- `/Users/pj/Workspace/projects/rust/margin-editor/src/styles/tree.css:473`
+  `.start-row svg { align-self: center; color: var(--ink-faint); }`
+
+A `translateY(2px)` and a `margin-top: 2px` in the same repo, for the same symptom, four files
+apart. Neither is wrong; both exist because the baseline was never dealt with at the root.
+
+The residual case is real and survives the global fix: an icon inside an `align-items: baseline`
+row still needs `align-self: center`. `margin-mail` hits it too, at
+`/Users/pj/Workspace/projects/rust/margin-mail/src/ui/Row.css:127` (`.row-mark { flex: none;
+display: inline-flex; align-self: center; }`), which is the same declaration as margin-docs'
+`tree.css:473`. There are 20 `align-items: baseline` rules across the four apps, so this is a
+recurring shape, not an exception.
+
+Icon size is not a shared decision and probably should not become one. `margin-mail` never uses the
+16px default (zero bare `<Icon d=... />`, nine distinct explicit sizes from 10 to 20). The other
+three lean on the default heavily: 33 bare call sites in margin-docs, 14 in calendar, 12 in margin.
+
+## Glyph inventory
+
+151 path definitions across the suite, 132 distinct strings, 13 of which appear in more than one
+app. The shared set covers 13. Per app, unique path strings: shared 13, margin 30, calendar 31,
+margin-docs 47, margin-mail 30.
+
+Only `margin-mail` keeps its glyphs in a module (`src/ui/icons.ts`, 30 named constants, five
+re-exported from `margin-shared/icons` at line 14). `margin-docs` names its toolbar and titlebar
+glyphs as module constants but writes six more inline. `margin` and `margin-calendar` are almost
+entirely inline `d="M..."` in JSX.
+
+Shared-set uptake is thin: `margin` uses eleven of the twelve; `margin-docs` uses seven
+(`SIDEBAR`, `SEARCH`, `SPELLING`, `GRAMMAR`, `EXPORT`, `MORE`, `CHECK`, `WIDTH`); `margin-mail`
+re-exports five; `margin-calendar` uses none.
+
+### Same concept, different path
+
+The important cases, with the exact strings.
+
+**SEARCH.** Shared `icons.ts:21` is `M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14zM20 20l-4-4`. Calendar
+`components/Header.tsx:22` is `M11 19a8 8 0 100-16 8 8 0 000 16zM21 21l-4.35-4.35`. Different lens
+radius (7 vs 8) and a different handle. This is the exact divergence the shared package's header
+comment says it exists to prevent, still present because calendar never joined.
+
+**MORE.** Shared `icons.ts:57` is three dots, `M5 12h.01M12 12h.01M19 12h.01`. Calendar
+`components/PhoneBar.tsx:29` uses the same name for a hamburger, `M4 7h16M4 12h16M4 17h16`. A
+straight name collision on two unrelated glyphs.
+
+**SUN.** Shared splits it: `SUN_RAYS` (`icons.ts:53`) with a `SUN_DISC` circle at `r: 4`, rays
+starting at `M12 2v2`. Calendar `Header.tsx:24` is one path with an `r=5` disc and rays at
+`M12 1v2M12 21v2M4.2 4.2...`. Different construction and different geometry.
+
+**HEADING.** `margin/src/editor/FloatingToolbar.tsx:126` is `M5 5v14M5 12h8M13 5v14`.
+`margin-editor/src/editor/Toolbar.tsx:184` is `M7 5v14M7 12h10M17 5v14`, with a comment at line 182
+that says exactly why: "The H used to run from x=5 to x=13 in a 24 unit box, so it sat left of
+centre in a round button that every other glyph here is centred in." One app fixed the optical
+centring; the other still has the bug. This is the "fix the alignment separately in each app"
+complaint, at the glyph level, with the fix already written down in one repo.
+
+**BULLET LIST.** `margin/src/editor/FloatingToolbar.tsx:128` puts the bullets at x=3.5:
+`M8 6h12M8 12h12M8 18h12M3.5 6h.01M3.5 12h.01M3.5 18h.01`.
+`margin-editor/src/editor/Toolbar.tsx:185` puts them at x=4: `...M4 6h.01M4 12h.01M4 18h.01`. A half
+unit apart on otherwise identical rules.
+
+**TRASH.** `margin/src/components/RowMenu.tsx:153` and `margin-editor/src/components/Sidebar.tsx:46`
+agree: `M5 7h14M10 7V5h4v2M7 7l1 13h8l1-13M10 11v6M14 11v6`. `margin-mail/src/ui/icons.ts:41` is a
+different drawing: `M4 7h16M9 7V5a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v2M6 7l1 13a1 1 0 0 0 1 1h8a1 1 0 0
+0 1-1l1-13M10 11v6M14 11v6`. Wider (4 to 20 rather than 5 to 19) and with rounded corners.
+
+**LINK.** margin `FloatingToolbar.tsx:153` and margin-docs `Toolbar.tsx:192` agree on `l2-2`.
+Calendar `EventDetails.tsx:46` and `EventEditor.tsx:42` use `l3-3`, a longer link arm.
+
+**REFRESH.** margin `BackupSettings.tsx:67` is `M21 12a9 9 0 1 1-2.6-6.4M21 4v5h-5`. Calendar
+`Header.tsx:23` is `M21 12a9 9 0 11-3-6.7M21 3v6h-6`. Different arc endpoint and a different arrow.
+
+**CHECK.** Shared `icons.ts:61` is `M20 6L9 17l-5-5`, used by margin-docs `WidthMenu.tsx:177` at
+size 14. margin-docs also draws its own at `components/Settings.tsx:131`,
+`d="M5 12.5l4.5 4.5L19 7"` at size 13. One app, two ticks.
+
+**BOLD and ITALIC.** margin renders letterforms, `<b>B</b>` and `<i>I</i>`
+(`FloatingToolbar.tsx:123-124`). margin-docs draws paths, `BOLD_D` and `ITALIC_D`
+(`Toolbar.tsx:177-178`). Same toolbar, same button, two different answers to what a bold button is.
+
+### Same drawing, different spelling
+
+These render identically and are only string-level drift, but they are what makes a `grep` for
+duplication useless.
+
+- **CLOSE**, five spellings: shared `M6 6l12 12M18 6L6 18`; `M18 6L6 18M6 6l12 12` in calendar
+  `EventDetails.tsx:38`, margin-docs `Recents.tsx:23`, `Sidebar.tsx:47`, `Toolbar.tsx:194`,
+  `Settings.tsx:253`, margin `FindBar.tsx:248`; `M18 6 6 18M6 6l12 12` in calendar
+  `overlayShell.tsx:14`.
+- **MOON**: shared `A9 9 0 1 1 11.2 3` versus calendar `A9 9 0 1111.2 3`. Packed arc flags, same
+  curve.
+- **CLOCK**: calendar `EventDetails.tsx:44` `M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0M12 7v5l3 2`
+  versus mail `icons.ts:46` `M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18zM12 7v5l3 2`.
+- **CHEVRON_RIGHT**: calendar `M9 18l6-6-6-6` versus mail `M9 6l6 6-6 6`. Drawn from opposite ends.
+- **DUPLICATE**: margin `RowMenu.tsx:142` `M9 9h11v11h-11z M6 15V5h9` versus margin-docs
+  `Sidebar.tsx:42` `M9 9h11v11H9z M6 15V5h9`.
+
+### Exact duplicates that are not in the shared set
+
+`PLUS` (`M12 5v14M5 12h14`) is defined independently in all four apps. `CHEVRON_UP`/`CHEVRON_DOWN`
+(`M6 15l6-6 6 6` / `M6 9l6 6 6-6`) three times. Vertical dots (`M12 5h.01M12 12h.01M12 19h.01`),
+`MINUS`, `HR`, `IMAGE`, `BLOCKQUOTE` twice each, always margin and margin-docs.
+
+## The icon button: eleven rules for one control
+
+All four share a byte-identical `button` reset (`margin app.css:34`, `calendar app.css:63`,
+`docs app.css:34`, `mail app.css:70`, the last adding `font-size: inherit`). On top of it:
+
+| App | Class | Size | Radius | Idle | Hover |
+| --- | --- | --- | --- | --- | --- |
+| margin | `.icon-btn` (`app.css:103`) | 30 | `--r-sm` | `--ink-soft` | `--accent-wash` |
+| margin | `.find-btn` (`app.css:2255`) | 26 | `--r-sm` | `--ink-soft` | `--accent-wash` |
+| margin | `.row-menu-btn` (`app.css:393`) | 22 | `--r-sm` | `--ink-faint` | `--accent-wash` |
+| calendar | `.icon-button` (`app.css:145`) | 28 | `--r-sm` | `--ink-soft` | `--accent-wash` |
+| calendar | `.details-close` (`details.css:269`) | 26 | `--r-sm` | `--ink-faint` | `--accent-wash` |
+| docs | `.icon-button` (`app.css:138`) | 28 | `--r-sm` | `--ink-soft` | `--accent-wash` |
+| docs | `.find-btn` (`tree.css:585`) | 26 | `--r-sm` | `--ink-soft` | `--accent-wash` |
+| docs | `.start-forget` (`tree.css:450`) | 26 | `--r-sm` | `--ink-faint` | `--accent-wash` |
+| docs | `.row-menu-btn` (`app.css:363`) | 22 | `--r-sm` | `--ink-faint` | `--accent-wash` |
+| docs | `.tree-twisty` (`tree.css:189`) | 16 | `--r-sm` | `--ink-faint` | `--accent-wash` |
+| mail | `.button[data-icon-only][data-variant="ghost"]` | 28 via `aspect-ratio: 1` | `--r-sm` | `--ink-soft` | `--accent-wash` |
+
+Every one of them is `display: grid; place-items: center` (except `.start-forget`, which spells it
+out as flex, and mail, which is inline-flex) with the same radius token, the same hover wash and
+one of two colour tokens. `margin`'s `.row-menu-btn` and margin-docs' `.row-menu-btn` are the same
+block copied verbatim into two repos. 26px appears four times across three apps.
+
+The name is the only thing that reliably differs: `.icon-btn` in margin, `.icon-button` in the
+other two.
+
+The "on" state is where they genuinely disagree. margin `app.css:118` and margin-docs
+`app.css:156` are the same three declarations (`color: var(--accent); background:
+var(--accent-wash); box-shadow: inset 0 0 0 1px var(--line-strong)`) under two attribute names,
+`data-on="true"` and `data-active="true"`. Calendar `app.css:160` drops the ring and uses
+`--ink`. Mail `Button.css:69` makes `[data-active]` identical to `:hover`, so an open panel's
+button and a hovered button are the same picture. Four apps, four answers, two of them pixel
+identical under different attribute names. Attribute usage is mixed inside every app too: margin
+21 `data-on` and 2 `data-active`, calendar 6 and 4, docs 12 and 9, mail 9 and 8.
+
+There is no icon-button component anywhere except `margin-mail`. 54 call sites across the three
+older apps hand-write `<button className="icon-btn|icon-button" title=... onClick=...><Icon
+d={...} /></button>`: margin 18, calendar 16, margin-docs 20. `margin-mail` has 115 `<Button>`
+usages and 16 `iconOnly` ones, and `Button.tsx:57` supplies the accessible name automatically:
+`aria-label={label ?? (iconOnly ? title : undefined)}`.
+
+The floating toolbar button is forked in the worst way. `margin app.css:893` `.tool` and
+`margin-editor app.css:623` `.tool` are the same rule except one writes `border-radius: 999px` and
+the other `border-radius: var(--r-pill)`. The same literal-versus-token split repeats on
+`.editor-toolbar` (`margin app.css:889` vs `docs app.css:619`). The JS helpers differ only in
+arity: `margin/src/editor/FloatingToolbar.tsx:109` is a render-scoped arrow with four positional
+params; `margin-editor/src/editor/Toolbar.tsx:156` is a module function with the same four plus
+`disabled`. Both carry the identical `onMouseDown={(e) => e.preventDefault()}`.
+
+## Focus, disabled, tooltips, badges, spinners, keycaps
+
+**Focus rings** are the one thing all four already agree on, byte for byte:
+`:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }` at
+`margin app.css:43`, `calendar app.css:80`, `docs app.css:51`, `mail app.css:92`. Nobody ships a
+polyfill or does keyboard-versus-mouse detection. The divergence is in the exceptions: 18 sites
+across the suite write `outline: none` with no replacement, and only `margin-mail` invents a second
+ring colour (`screens/settings.css:467`, `outline: 2px solid var(--accent-wash)` at 1px offset).
+The round-control case is handled twice and missed once: calendar `create.css:445` and docs
+`toolbar.css:157` both use a two-layer box-shadow (`0 0 0 2px var(--paper), 0 0 0 3px
+var(--accent)` and `0 0 0 1.5px ...` respectively, radii disagree), while mail's 15px round swatch
+has no focus rule and gets the square outline that calendar's comment at `create.css:435` warns
+about. `/Users/pj/Workspace/projects/python/margin/src/focus.ts` is the only focus-trap module in
+the family; the other three have none.
+
+**Disabled** has no agreement at all: five opacity values across four apps. margin uses 0.4, 0.5
+and 0.6 in one file; calendar uses 0.45; margin-docs uses 0.4, 0.45 and 0.5; margin-mail mostly
+abandons opacity for `color: var(--ink-faint); background: var(--raised)`
+(`ui/Button.css:84`), which is the same recipe calendar reached independently at
+`overlays.css:85`. Only one site in the suite pairs `:disabled` with `pointer-events: none`
+(`docs export-preview.css:75`).
+
+**Tooltips** do not exist as a component in any app. All four use the native `title` attribute:
+44, 40, 66 and 71 occurrences. margin is the outlier on labelling, 44 `title` against 5
+`aria-label`, so most of its icon buttons are unnamed to a screen reader; the other three run
+21/43/42. The text generator is forked: margin-docs `Titlebar.tsx:105` `shortcutTitle(id)` returns
+a whole string, calendar `Header.tsx:33` `hint(command)` returns a leading-space suffix, and margin
+hardcodes `title="Find (⌘F)"` (`EditorView.tsx:294`) and `"Link (⌘K)"`
+(`FloatingToolbar.tsx:153`), which are not platform aware.
+
+**Badges** share one recipe and disagree on every number: a wash-tinted micro chip at
+`padding: 1px 5|6|9px; background: var(--accent-wash); color: var(--ink-faint); font-size:
+var(--t-1)`, in calendar `details.css:93`, `overlays.css:487`, `agenda.css:90` and mail
+`tour.css:127`, with the radius `--r-sm` in calendar and `--r-pill` in mail. Status dots come in
+5, 6, 7, 8 and 9px, and `border-radius: 50%` and `var(--r-pill)` are both used within one repo
+(`docs app.css:132` vs `toolbar.css:311`). margin and margin-docs share three copy-pasted classes
+verbatim: `.dirty-dot`, `.preview-count`, `.find-count`. `font-variant-numeric: tabular-nums` on
+counts is used by all four.
+
+**Loading** is the deepest split, and it is a product decision rather than an oversight. margin
+and margin-docs have rotating spinners (`margin app.css:1461` `.spinner`, plus a byte-identical
+`backup-spin` duplicate of `spin` at `:2711`; `docs export-preview.css:139` `.preview-spinner`).
+`margin-calendar` has no spinner, no skeleton and no loading keyframes at all; it expresses
+pending state as `[data-busy]` and `[data-pending]` on the content itself. `margin-mail` bans
+spinners in three separate comments and uses bars and skeletons instead. Reduced motion is handled
+in three different ways: margin has no guard at all, docs slows the spinner from 0.7s to 2.4s, mail
+disables outright in five places. Do not try to unify this; the four apps mean different things.
+
+**Keycaps.** calendar `palette.css:104` `.key` and mail `ui/Key.css:1` + `[data-size="md"]` are the
+same chip: bordered, `--raised`, `--r-sm`, `--t-1`, `min-width: 20px`, `padding: 2px 6px`,
+`line-height: 1.4`. margin-docs `tree.css:744` `.key-cap` is a different chip, wash-filled with no
+border at `--t-2` and weight 600. margin has no chip, one rule
+(`app.css:2191` `.esc-hint kbd`). Only `margin-mail` has a `Key` component
+(`ui/Key.tsx:15`), only mail puts a cap on ordinary buttons, and only mail hides caps on phones
+(`Key.css:28`). Underneath, `keys/bindings.ts` in calendar, docs and mail declare identical `isMac`
+and `PRIMARY_LABEL` lines and an identical eight-entry `NAMED` map, then implement `keyLabel()`
+three different ways: calendar (`:110`) cannot express `⌘⇧F` at all, docs (`:243`) infers shift
+from case, mail (`:579`) treats shift as a first-class modifier. margin has no bindings table.
+
+## Titlebar and window chrome
+
+All four are Tauri v2 with `"titleBarStyle": "Overlay"` and native traffic lights. Nobody draws
+window controls, nobody sets `decorations`, `hiddenTitle`, `transparent` or `macOSPrivateApi`, and
+nobody uses `startDragging` or `-webkit-app-region`; every drag region is the
+`data-tauri-drag-region` attribute.
+
+The `.titlebar` rule is the same nine declarations in all four
+(`margin app.css:67`, `calendar app.css:102`, `docs app.css:76`, `mail header.css:7`):
+`flex: none; position: relative; z-index: 45; height: var(--titlebar-h); display: grid;
+grid-template-columns: 1fr auto 1fr; align-items: center; background: var(--shell); border-bottom:
+1px solid var(--line)`. Differences: margin and calendar and mail set `user-select: none`, docs
+does not; calendar folds `--safe-top` into the height and padding.
+
+The lane for the traffic lights is 84px in all four and is reserved three different ways.
+`margin app.css:74` hardcodes it in `padding: 0 14px 0 84px`, unconditionally, with no token and no
+platform gate, so Linux and Windows get a dead 84px lane. Calendar (`app.css:126`) and mail
+(`header.css:24`) put `padding-left: var(--traffic-pad)` on the row under `:root[data-traffic]`.
+margin-docs puts it on the child instead, `:root[data-traffic] .titlebar .lead { margin-left:
+calc(var(--traffic-pad) - 14px) }` (`app.css:97`), with a comment explaining that padding on the
+row pushed the centred title 35px right of the middle. Calendar's view switcher and mail's
+`<Segment>` are both in centre columns and are subject to exactly that offset.
+
+Only margin-docs has native code. `/Users/pj/Workspace/projects/rust/margin-editor/src-tauri/src/titlebar.rs`
+resizes the `NSTitlebarContainerView` on `Resized`, `Focused` and `ThemeChanged` so the lights
+centre in a 46px row, with a `const TITLEBAR_H: f64 = 46.0` at line 79 that duplicates
+`--titlebar-h: 46px` from `shared/css/tokens.css:24`. Calendar and mail instead set
+`"trafficLightPosition": { "x": 9, "y": 25 }` in `tauri.conf.json` and never reapply. margin does
+neither, so its lights sit at the macOS default, roughly 7px high in a 46px row, which is the
+misalignment `titlebar.rs` was written to fix.
+
+`--traffic-pad: 84px` is declared four times (`calendar tokens.css:11` and `:60`,
+`docs tokens.css:11`, `mail mail.css:36`) and is not in `margin-shared`. So is
+`--r-pill: 999px` and `--touch-h: 44px`, three copies each. margin declares none of them and
+inlines the literals.
+
+## What to share, and what not to
+
+**Share, high confidence:**
+
+1. `Icon` itself. Three byte-identical copies plus one strictly better fourth. Move
+   `margin-mail`'s version (className, `aria-hidden`, exported props type) to
+   `shared/src/Icon.tsx` with `react` as a peer dependency. The stated reason not to has no
+   mechanical basis.
+2. The two lines of alignment that go with it: `svg { display: block }` and `.icon { flex: none }`,
+   as `shared/css/icon.css`. This is the fix that has been made five different ways in four repos
+   and is the direct answer to "I keep fixing icon alignment separately."
+3. The rest of the glyphs. Promote `PLUS`, `CHEVRON_UP/DOWN/LEFT/RIGHT`, vertical dots, `MINUS`,
+   `HR`, `IMAGE`, `BLOCKQUOTE`, `TRASH`, `LINK`, `REFRESH`, `CLOCK`, `DOCUMENT`, `COPY`,
+   `EXTERNAL`, `BOLD`, `ITALIC`, `HEADING`, `BULLET_LIST` into `shared/src/icons.ts`, picking the
+   better drawing where they have drifted (margin-docs' `HEADING_D` and `BULLET_LIST_D`, the
+   margin/margin-docs `TRASH` and `LINK`, the shared `SEARCH` and `MORE` and `SUN`). Then delete
+   every inline `d="M..."` from JSX. This turns 151 definitions into roughly 60.
+4. `--r-pill`, `--touch-h` and `--traffic-pad` into `shared/css/tokens.css`. Three copies each of a
+   single number, and in `--traffic-pad`'s case a number that the Rust in one repo has to agree
+   with.
+5. The keycap. Move `margin-mail`'s `Key.tsx` and `Key.css`; calendar's `.key` is already the same
+   chip, and margin-docs' `.key-cap` is a divergence that should be resolved rather than kept.
+6. `keyLabel`, `normalizeCombo`, `PRIMARY_LABEL` and the `NAMED` map. Three near-identical
+   implementations of the same twenty lines with three different bugs. `margin-mail`'s is the
+   correct one. This is not strictly a UI primitive, but it is why the caps and titles disagree.
+
+**Share, but the shape needs deciding first:**
+
+7. The icon button. Eleven rules for one control is the clearest duplication in the audit, but
+   `margin-mail`'s `Button` bundles size, variant, keycap and icon into one component, while the
+   other three want a flat class they can put on any element. The tractable move is to share the
+   CSS (a `.icon-button` at 28px with `--r-sm`, `--accent-wash` hover, and a settled `[data-on]`
+   ring) and let each app keep its own JSX for now. Renaming margin's `.icon-btn` and settling on
+   one of `data-on` or `data-active` is a prerequisite either way.
+8. The `.titlebar` grid rule and the traffic lane. The nine declarations are common; the lane
+   mechanism is not, and margin-docs' child-margin version is the correct one. `titlebar.rs`
+   belongs in a shared Rust crate eventually, but that is a bigger move than this audit covers.
+
+**Do not share:**
+
+- Spinners and loading states. margin spins, calendar refuses to have any loading affordance,
+  margin-mail bans spinners on the record. These are four different product positions, not four
+  copies of one decision.
+- Badges, chips and pills. The wash-chip recipe recurs, but every app's numbers are tuned to its
+  own density (a calendar all-day chip is a layout unit, not a badge). Sharing the tokens is
+  enough.
+- Focus ring exceptions. The global rule is already shared through the tokens; the 18 `outline:
+  none` sites are each local judgement calls, and margin-docs is the only app that writes down why.
+- The floating editor toolbar. It exists in two apps only, and its `.tool` is a different control
+  from `.icon-button` (a min-width pill that holds a letterform as often as a glyph). Worth
+  de-duplicating between margin and margin-docs, not worth putting in a package the calendar and
+  mail apps import.
+
+**Prerequisite for all of it:** `margin-calendar` has to depend on `margin-shared`. It is one line
+in its `package.json` (`"margin-shared": "file:../margin/shared"`) and deleting its hand-copied
+`tokens.css` values. Every calendar-specific divergence in this document, `SEARCH`, `MORE`, `SUN`,
+`MOON`, `LINK`, `REFRESH`, the duplicated palette, follows from the fact that it never joined.

simplify/.research/memories-raw.md

@@ -0,0 +1,976 @@
+# Raw memory and CLAUDE.md dump (source material for guidelines/)
+
+Concatenated verbatim on 2026-09-06. Do not edit; this is the source, not a deliverable.
+
+## Project: python-margin
+
+### python-margin / app-review-notes-audience.md
+
+```markdown
+---
+name: app-review-notes-audience
+description: App Review notes must be actionable with only the built app, never reference source paths
+metadata:
+  type: feedback
+---
+
+App Store review notes are read by someone who has the built app and nothing else. Never cite
+source files, line numbers or repo paths in them. Describe what a reviewer can see and do in the
+running app: the UI path to a feature, what it does, observable behaviour.
+
+**Why:** PJ pulled "The code is in src-tauri/src/gdrive.rs" out of the notes before resubmitting
+margin 0.1.17. The apps being open source does not help, because nothing in the notes points the
+reviewer at the repo, so a path is just noise in a field with a 4000 character limit.
+
+**How to apply:** When writing `appstore/metadata/review_notes.txt` for any of the margin apps,
+justify an entitlement by what it enables and how to reach it in the UI, plus the observable
+constraints (bound to loopback only, times out, off until the user connects an account). Applies to
+margin-calendar and margin-docs too. See [[margin-distribution-plan]].
+```
+
+### python-margin / commit-message-style.md
+
+```markdown
+---
+name: commit-message-style
+description: "commit messages are one plain lowercase line, no type prefix, no scope, no body"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 686d3870-3e2c-4060-875c-4a49b701b9f2
+  modified: 2026-09-01T17:47:43.543Z
+---
+
+A commit message is one line of plain lowercase text describing the change, e.g.
+`send app store builds to the store for updates`. No `feat(scope):` prefix, no body, no bullets,
+no blank line and explanation. The prefix counts as formatting and is not wanted.
+
+**Why:** The diff and the docs carry the reasoning. The message just names the change.
+
+**How to apply:** `git commit -m "add the thing"` and stop. Never a heredoc or `-F -`. Applies to
+amends. Note the repo's own CLAUDE.md still asks for conventional commit format; this instruction
+overrides it until that file is changed. See [[no-em-dashes]] for the related prose rules.
+```
+
+### python-margin / dont-start-dev-server.md
+
+```markdown
+---
+name: dont-start-dev-server
+description: "Never start the margin dev server yourself — the user runs it; a scratch vite on a spare port is the safe way to browser-test"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: f0e048ec-7e18-4118-a470-e793b231f468
+---
+
+Do not run `pnpm tauri dev` / `pnpm dev`. The user keeps the dev server running themselves and HMR picks up source edits in their instance (use that for verification).
+
+**Why:** vite uses `strictPort: 1420`, so a second `tauri dev` fails with `ELIFECYCLE Command failed` and conflicts with, or kills, the user's running app. The user was explicit and annoyed about this.
+
+**How to apply:** before any step that needs the running app, check `ps aux | grep -E "margin-app|vite"`. If a server is running, use it (edits hot-reload). If none is running, ask the user to start it, don't start one. Also can't screen-capture the native WebKit window (no screen-recording permission).
+
+For browser-testable frontend work, `npx vite --port 5199 --strictPort` in the background plus the playwright MCP tools works well and never touches 1420. Kill it when done. Caveat: `isDesktop` (`"__TAURI_INTERNALS__" in window`) is false there, so desktop-gated UI is absent; injecting a small `__TAURI_INTERNALS__.invoke` stub backed by localStorage for `list_books`/`load_book`/`save_book`/`delete_book` makes the library and multi-book flows testable. See [[no-in-code-tests]].
+```
+
+### python-margin / gdrive-backup-spec.md
+
+```markdown
+---
+name: gdrive-backup-spec
+description: "Agreed design for margin's local-only Google Drive backup feature (no backend, no login)"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: c3e99a43-39ac-4ff5-8cae-326ff24135e3
+---
+
+Planned feature: connect Google Drive locally to back up books. No backend server, no login. margin data is small/clean: self-contained `{book-id}.margin` JSON files (images embedded as base64) in `~/Library/Application Support/studio.margin.app/library/`, plus `custom-dictionary.txt`. Reference prior art (Go): `/Users/pj/go/src/github.com/priyanshujain/openbotkit` does the loopback OAuth + `drive.file` pattern, but makes the USER supply `credentials.json` (fine for a dev CLI, wrong for margin's consumers).
+
+**Auth:** one embedded "Desktop app" OAuth client (PJ registers it in his own Google Cloud project), loopback + PKCE flow via system browser. Scope `drive.file` + `openid email`. `drive.file` is non-sensitive, so NO Google verification review and NO CASA audit; set consent screen to Production to avoid the unverified warning and the testing-mode 7-day refresh-token expiry. For installed apps the client secret is not confidential; embed it, ideally via the same release-overlay pattern as [[updater-overlay-config]] to keep local builds clean.
+
+**Decisions (locked via discussion):**
+- Drive layout: visible `margin/` folder, books 1:1 to `{id}.margin` files + dictionary. Latest-only (overwrite); Drive keeps revisions automatically so version-restore UI can come later.
+- Model: backup + restore, last-write-wins, warn if remote copy is newer.
+- Triggers: manual (top-right icon) + on app close + periodic every 15 min, all gated on a dirty/hash check (only upload if something changed).
+- Top-right icon = action + status: muted when up to date, accent tint when changes pending (click to back up), animated while backing up, warning tint on error, subtle outline when not connected.
+- Settings: add a new minimal Settings panel (first real preferences UI) with a Backup section for connect/disconnect, account email, status, and full restore.
+- Restore: subtle, ignorable "Restore from Google Drive" affordance on the home page empty-library state (does not bother new users); doubles as connect-on-new-machine.
+- Included: all `.margin` books + `custom-dictionary.txt`.
+
+**Rust/Tauri approach:** no heavy Google SDK. `oauth2` crate + `tauri-plugin-oauth` (loopback catch) + existing `tauri-plugin-opener` (browser) + `reqwest` for the ~5 Drive REST endpoints. Refresh token in OS keychain (`keyring`); folder id / account / sync-state in a small `backup.json` in app data dir. New Tauri commands ~ `gdrive_connect`, `gdrive_disconnect`, `gdrive_status`, `backup_now`, `restore`, `list_remote_backups`.
+
+Status as of 2026-06-22: BUILT and compiling (cargo check + tsc + vite build all pass). Backend in `src-tauri/src/gdrive.rs` (commands gdrive_connect/disconnect/status/backup/restore/list_backups), registered in lib.rs with managed GDriveState + init_session on setup. Creds loaded via `include_str!` from project-root `google-credentials.json` (gitignored; `google-credentials.example.json` committed; placeholders trigger a friendly "not set up" error). Frontend: `src/backup.ts`, `src/store/useBackup.ts`, `BackupButton` (in EditorView titlebar + Library head; clicking it OPENS the BackupSettings panel — not one-click backup — since the panel is the single home for back up / restore / disconnect / account), `BackupSettings` modal (mounted in App), home-page `.restore-link` on empty library; on-close + 15-min periodic backup in App.tsx. Connect is event-based: `gdrive_connect` returns the auth URL immediately + spawns a background task that emits a `gdrive-auth` {ok,error} event; the panel shows Open-link-again / Copy-link / Cancel while connecting; loopback wait times out after 120s (AUTH_TIMEOUT_SECS). Refresh token + sync state both stored in plaintext app-data `backup.json` — NO OS keychain (removed because macOS re-prompts on every dev rebuild and the bundle-id label "studio.margin.app" confused the user; drive.file scope is limited so plaintext matches the app's existing local-data model). Manual backup returns an `uploaded` count: >0 → "Backed up to Google Drive", 0 → "Nothing new to back up" (and last_backup only bumps when something uploaded). Clicking the cloud icon opens the panel; the panel's "Back up now" button is the manual trigger.
+
+Cleanup pass done (verified via cargo check + tsc + vite build): shared path helpers `app_data_dir`/`library_dir` now live pub(crate) in `library.rs` (reuse them, don't recreate); a single `static HTTP: LazyLock<reqwest::Client>` is reused for all Drive calls; `compute_pending` uses an mtime fast-path (only re-hashes books whose mtime > last_backup) so status polls are cheap; `BackupOutcome` flattens `Status` (serde flatten); `restoreFromDrive` orchestration (connect-then-restore) lives in the useBackup store, called from Library. Toast/notice unified on the global `useBook` store across both Library and EditorView.
+
+REMAINING (blocked on PJ): create Google Cloud project + Desktop OAuth client (scopes drive.file + openid + email, publish to Production), download JSON to replace google-credentials.json, restart `tauri dev` (creds are compile-time embedded), then end-to-end test connect/backup/restore. Not yet e2e tested with real creds.
+```
+
+### python-margin / margin-distribution-plan.md
+
+```markdown
+---
+name: margin-distribution-plan
+description: "Agreed distribution strategy and licensing for the three Margin apps (App Store, Homebrew, direct)"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 23c1b6b5-40e8-4350-8c85-e0fdb3783572
+  modified: 2026-08-30T12:04:56.430Z
+---
+
+Decided 2026-08-30. All three Margin apps (margin, margin-calendar, margin-docs) are **free**, with
+no license gate and no in-app purchase, so Apple takes no cut and App Store anti-steering rules do
+not apply.
+
+Channels, in priority order:
+- **Mac App Store is the primary macOS channel.** Sandboxed, no self-updater, separate build track.
+- **Own Homebrew tap** `priyanshujain/homebrew-margin`, not upstream homebrew-cask (the repos have
+  ~1 star and do not clear the notability bar).
+- **Direct download** from margin.73ai.org stays the unrestricted build with the Tauri updater.
+
+Ordering: margin ships first (most polished), then calendar, then docs.
+
+Deliberately not done: no migration bridge for the library moving into the sandbox container. There
+are effectively no existing users, so a first-run import is not worth building yet.
+
+Licensing: margin is **FSL-1.1-MIT** (free for anything except a competing product, becomes MIT two
+years after each release). Chosen because the user wants open code that nobody else monetizes,
+which is not open source by the OSI definition. **AGPL was ruled out because it is incompatible
+with the Mac App Store.** margin-calendar and margin-docs are still MIT and have not been
+relicensed; that is an open question.
+
+Apple account: Individual, enrolled but nothing created as of 2026-08-30. Signing private keys and
+CSRs live in `~/.margin-signing/` (developer-id, apple-distribution, mac-installer), generated with
+openssl rather than Keychain Access so CI `.p12` files can be rebuilt without a GUI.
+
+Mechanics live in the repo at `docs/publishing.md`. See also [[no-em-dashes]], [[no-code-comments]].
+```
+
+### python-margin / MEMORY.md
+
+```markdown
+- [No in-code tests](no-in-code-tests.md) — never commit tests; verify by running the actual product
+- [No prettier](no-prettier.md) — repo is hand-formatted at ~120 cols; running prettier mangles whole files
+- [No code comments](no-code-comments.md) — self-readable code, refactor instead of commenting
+- [Updater overlay config](updater-overlay-config.md) — pubkey lives in tauri.release.conf.json overlay (CI-only), not tauri.conf.json, to keep local builds key-free
+- [Don't start dev server](dont-start-dev-server.md) — user runs `tauri dev` (strictPort 1420); never launch it, ask if not running
+- [No em dashes](no-em-dashes.md) — avoid —/– in copy and generated prose; restructure instead
+- [GDrive backup spec](gdrive-backup-spec.md) — agreed design for local-only Google Drive backup (no backend/login)
+- [Mobile setup status](mobile-setup-status.md) — responsive layout (≤899px drawers) + iOS Tauri target initialized; Android not set up; mobile runtime limits
+- [Margin distribution plan](margin-distribution-plan.md) — free apps, MAS primary, own brew tap, FSL-1.1-MIT
+- [App Review notes audience](app-review-notes-audience.md) — reviewers have the built app only; no source paths in review notes
+- [Commit message style](commit-message-style.md) — one line, lowercase, plain text, no body
+```
+
+### python-margin / mobile-setup-status.md
+
+```markdown
+---
+name: mobile-setup-status
+description: State of the iOS/Android mobile build and the responsive layout work
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 84a2bb57-78cb-4049-8574-0e1f54665d89
+---
+
+Margin now ships a responsive layout AND an initialized Tauri mobile (iOS) target.
+
+**Responsive layout** (added 2026-06): breakpoint is `(max-width: 899px)` via `useCompact()` in `src/useMedia.ts`. The `.app` root carries `data-compact`/`data-sidebar`/`data-dock`. Desktop: sidebar collapses to width 0 and the editor reclaims space (toggle = ☰ top-left of titlebar). Compact: sidebar + preview become fixed slide-in drawers over a full-width editor, one at a time, with a `.drawer-scrim`; extra titlebar actions fold into a ⋯ overflow menu. Safe-area insets + `--titlebar-h` handle the notch. Modals use `.panel { width: min(480px, calc(100vw - 32px)) }`.
+
+**iOS**: `tauri ios init` done (`src-tauri/gen/apple`, not gitignored). Verified `cargo check --target aarch64-apple-ios-sim` and a full `tauri ios build --target aarch64-sim --debug` both succeed; the app installs/launches in the iPhone 17 Pro simulator. typst PDF, harper, reqwest all cross-compile fine. `isDesktop` in `src/ipc.ts` actually means "is Tauri" so it's true on mobile.
+
+**Android**: NOT set up — needs Android SDK + NDK + JDK 17 (machine has JDK 25, no ANDROID_HOME).
+
+**iOS WKWebView CSS gotchas fixed (not reproducible in desktop browser — verify on the simulator/device):** (1) text auto-inflation of wide blocks → `html { -webkit-text-size-adjust: 100% }`. (2) zoom-in on input focus → viewport `maximum-scale=1.0, user-scalable=no`. (3) keyboard scrolled the whole page (titlebar under the notch) → `body { position: fixed; inset: 0; overflow: hidden }` + `.app/.library { height: 100dvh }` so only `.editor-pane` scrolls. (4) title-input caret drawn below the text → `.chapter-title-input { line-height: 1.4 }` (1.16 was tighter than Literata's natural metrics). Note: programmatic `.focus()` on iOS does NOT show the caret/keyboard without a real user gesture, so caret/keyboard states can't be screenshot-verified via simctl — needs a human tap.
+
+**Mobile runtime limitations still to address** (compile fine, but won't work right on device): Google Drive backup uses a localhost-loopback OAuth (`gdrive.rs`) that won't work on iOS; system-font listing returns little; arbitrary-path file save/open assumes desktop dialogs; updater/process are `#[cfg(desktop)]`-gated (no-op on mobile, capability split into `capabilities/desktop.json`). Native menu is also desktop-only, so mobile relies on in-app buttons (Library + ⋯ menu) for New Book / Export.
+
+Related: [[dont-start-dev-server]], [[updater-overlay-config]], [[gdrive-backup-spec]].
+```
+
+### python-margin / no-code-comments.md
+
+```markdown
+---
+name: no-code-comments
+description: Write self-readable code with no comments instead of explaining via comments
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: a776698a-6dd2-4bf4-87bb-f13f20b892bd
+---
+
+Do not add code comments. Make the code itself readable (clear names, small functions) so comments are unnecessary.
+
+**Why:** The user puts the effort into readable code and considers comments noise.
+
+**How to apply:** When tempted to write a comment, refactor for clarity (rename, extract a well-named function) instead. See also [[no-in-code-tests]].
+```
+
+### python-margin / no-em-dashes.md
+
+```markdown
+---
+name: no-em-dashes
+description: User dislikes em dashes (and en dashes) in copy and generated text
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 3afd9184-a526-4317-a413-d49e3e93b6b1
+---
+
+Do not use em dashes (—) or en dashes (–) in any user-facing copy, marketing text, or generated writing for this user.
+
+**Why:** The user finds them undesirable in prose and flagged removing them explicitly while polishing the Margin website hero.
+
+**How to apply:** Restructure with periods, commas, colons, or parentheses instead. When editing existing copy, sweep for `—`/`–` and replace. Applies to website copy and any prose I write, not just code.
+```
+
+### python-margin / no-in-code-tests.md
+
+```markdown
+---
+name: no-in-code-tests
+description: Do not write tests in the codebase; verify by running the actual product directly
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: a776698a-6dd2-4bf4-87bb-f13f20b892bd
+---
+
+Never add tests to the codebase (no Rust `#[cfg(test)]`/`#[test]` modules, no JS test files/harnesses). Verify changes by running the actual product directly.
+
+**Why:** The user wants the repo to contain product code only; correctness is confirmed by exercising the real app, not by committed tests.
+
+**How to apply:** After a change, run/drive the actual app to confirm behavior. Do not commit test code. See also [[no-code-comments]].
+```
+
+### python-margin / no-prettier.md
+
+```markdown
+---
+name: no-prettier
+description: "margin is not prettier-formatted — running prettier reformats whole files and buries the real diff"
+metadata:
+  node_type: memory
+  type: project
+---
+
+The repo has no prettier config and its source is hand-formatted at roughly 120 columns. Running `npx prettier --write` on a file rewrites it at prettier's 80-column default and turns a 60-line change into a 340-line diff.
+
+**Why:** it destroys reviewability and churns files the change never touched.
+
+**How to apply:** never run prettier (or any formatter) on this repo. Make surgical edits and match the surrounding indentation by hand. If a formatter has already run, `git checkout <file>` and redo the edits manually. See [[no-code-comments]].
+```
+
+### python-margin / updater-overlay-config.md
+
+```markdown
+---
+name: updater-overlay-config
+description: "Why the Tauri updater pubkey lives in a release-only overlay config, not tauri.conf.json"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 845e4db7-1d47-4b07-8073-155095a7b944
+---
+
+margin's Tauri updater config (`plugins.updater.pubkey` + `bundle.createUpdaterArtifacts: true`) lives in `src-tauri/tauri.release.conf.json`, a release-only overlay merged via `--config` in the GitHub Actions release workflow. It is deliberately kept OUT of the committed `src-tauri/tauri.conf.json`.
+
+**Why:** the mere presence of `plugins.updater.pubkey` in `tauri.conf.json` makes `tauri build` demand a signing key (tauri-apps/tauri#14581), which would break the local key-free `pnpm dmg` build. The overlay scopes signing + updater artifacts to CI only; local builds stay clean. Only CI-built (signed) releases need to self-update anyway.
+
+Release flow is manual `workflow_dispatch` in `.github/workflows/release.yml` (prepare → build matrix `max-parallel: 1` → publish). `max-parallel: 1` is required so tauri-action's read-modify-write merge of `latest.json` across platforms can't race.
+```
+
+## Project: python-margin-caledar
+
+### python-margin-caledar / calendar-navigation-steps-by-day.md
+
+```markdown
+---
+name: calendar-navigation-steps-by-day
+description: "In Margin Calendar, prev/next navigation must move one day at a time, never jump a whole week"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 9a11f15b-a564-473a-8289-d6dcf73df055
+  modified: 2026-08-10T15:10:09.086Z
+---
+
+Navigation in Margin Calendar moves **one day at a time**. The header arrows and `h`/`l` step a
+single day; jumping a whole week is the behaviour the user called out as the thing they
+"absolutely hate".
+
+**Why:** week view originally snapped to `startOfWeek`, so a one-day step was invisible six times
+out of seven and the arrows had to jump a week to do anything. Sliding by a day keeps positional
+memory intact, which is most of the speed of a keyboard-driven calendar, and is the same reason
+the vertical axis has contraction hysteresis.
+
+**How to apply:** week view is a rolling seven days from the anchor by default (`weekMode()` in
+`src/time.ts`, stored under `margincal-week-mode`). `weekAnchor()` is the single source both
+`spanFor` and `GridView` use, so never reintroduce a bare `startOfWeek` call in either. The
+"calendar" mode that snaps to whole weeks exists in Settings, and only there do the arrows step by
+a week, because a day step would be invisible. Related: [[margin-calendar-google-cloud-project]].
+```
+
+### python-margin-caledar / linux-distribution-is-nix-not-aur.md
+
+```markdown
+---
+name: linux-distribution-is-nix-not-aur
+description: Linux installs ship through a Nix flake; the AUR package was dropped in Sep 2026 because pj has no AUR account and signups are restricted
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: e48a0fd3-0e18-4f9d-8b06-d3bbbbee65ac
+  modified: 2026-09-03T06:23:56.541Z
+---
+
+On 2026-09-03 the AUR job and PKGBUILD were removed and replaced with a Nix flake (flake.nix, nix/package.nix, nix/release.json). pj has no AUR account and the AUR has restricted signups, so AUR publishing had become a blocker for Linux users.
+
+**Why:** The Nix package is a binary repackage of the released deb, for the same reason the AUR one was: the Google OAuth client is embedded at compile time from a file not in the repo, so from-source builds by strangers produce an app that cannot connect. The wrapper sets MARGIN_CALENDAR_PACKAGED_BY=nix so the in-app updater announces new versions but does not try to install over the store.
+
+**How to apply:** Do not propose the AUR again. The release workflow's nix job writes nix/release.json on main after publish; users install with `nix profile install github:priyanshujain/margin-calendar`. Nix is not installed on pj's Mac; test the flake through the amd64 nixos/nix Docker image with `filter-syscalls = false` (seccomp fails under emulation) and a named volume on /nix.
+```
+
+### python-margin-caledar / margin-calendar-google-cloud-project.md
+
+```markdown
+---
+name: margin-calendar-google-cloud-project
+description: "Margin Calendar's Cloud project margin-500217 is owned by [email protected], needs the Calendar API enabled per project, and needs separate OAuth clients per platform"
+metadata:
+  node_type: memory
+  type: project
+  originSessionId: 9a11f15b-a564-473a-8289-d6dcf73df055
+  modified: 2026-08-12T13:02:23.872Z
+---
+
+Margin Calendar's desktop `google-credentials.json` is copied from `../margin`, so both apps share
+one OAuth desktop client: Cloud project `margin-500217`, numeric id `205537985128`. The project is
+owned by **[email protected]**, not `[email protected]`, which is the signed-in app account.
+
+**Why:** the client was created for margin's Drive scope. Sharing it means the consent screen and
+the enabled API list are shared too, and enabling an API is per project, not per client. On
+2026-08-10 the calendar scope was granted correctly but every `calendarList` call returned 403
+`SERVICE_DISABLED`, because the Calendar API had never been enabled on that project. A
+`gcloud services enable` run as the gmail account was denied, because that account does not own
+the project.
+
+Phones share it too, and that is deliberate. A Desktop client may redirect to loopback on any port
+without registering it, and Google's token endpoint checks the client id, secret and redirect
+rather than the calling OS, so a phone signs in on this same client with no console work. Verified
+on 2026-08-12: Google's real consent screen renders and accepts this client on both an iOS
+simulator and an Android emulator. It works because the protocol does not check, not because Google
+blesses it; the fallback if they ever enforce it is a per-platform client, which the code supports.
+
+One thing still argues for an **iOS** client (bundle id `studio.margin.calendar`, no SHA-1, about a
+minute): it switches iOS to `ASWebAuthenticationSession`, which shares Safari's session, so the
+user is not asked to sign in to Google again. Android needs nothing, because Chrome Custom Tabs
+share Chrome's cookies already, and that was measured rather than assumed. iOS session sharing
+could NOT be confirmed on the simulator and needs checking on a real device. See `docs/mobile.md`.
+
+**How to apply:** if calendars come back empty while auth succeeds, check the API is enabled before
+suspecting sync, and run the enable as pj@73ai.org. To see the real error the UI may swallow, curl
+`calendarList` directly. Note the token is no longer in any keychain: it is XChaCha20-Poly1305
+sealed in `tokens.enc` under the app data directory, so the old
+`security find-generic-password` check no longer applies. Related:
+[[calendar-navigation-steps-by-day]], [[prefer-cross-platform-over-per-platform-native]].
+```
+
+### python-margin-caledar / MEMORY.md
+
+```markdown
+- [Navigation steps by day](calendar-navigation-steps-by-day.md): prev/next moves one day, never a whole week
+- [Google Cloud project](margin-calendar-google-cloud-project.md): owned by pj@73ai.org; Calendar API is per project; phones need their own OAuth clients
+- [Cross-platform over per-OS native](prefer-cross-platform-over-per-platform-native.md): one implementation everywhere beats a native backend per OS
+- [Reading app localStorage from WebKit](reading-app-localstorage-from-webkit.md): installed app state lives in a WebKit sqlite; dev server has a separate store
+- [Linux ships via Nix, not AUR](linux-distribution-is-nix-not-aur.md): AUR dropped Sep 2026 (no account, restricted signups); flake repackages the release deb, tested via amd64 Docker nix image
+```
+
+### python-margin-caledar / prefer-cross-platform-over-per-platform-native.md
+
+```markdown
+---
+name: prefer-cross-platform-over-per-platform-native
+description: PJ wants one cross-platform implementation rather than a native integration per OS with fallbacks
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 9a11f15b-a564-473a-8289-d6dcf73df055
+  modified: 2026-08-12T11:40:34.115Z
+---
+
+When a dependency needs a different native integration on each OS, PJ wants it replaced with one
+implementation that works everywhere, not patched per platform. Said twice about `keyring`: first
+"stop using keyring in macos", then "we should not use keyring man use some cross platform
+solution".
+
+**Why:** the per-platform version had four ways of reaching one real implementation. macOS was
+already excluded because Keychain ties an item to the code signature and re-prompts on every
+rebuild; Android has no backend at all; and on Linux the Secret Service is missing on exactly the
+minimal window managers that most wanted it. The branching cost more than it bought, and the
+prompts were a visible daily irritation.
+
+**How to apply:** before adding a dependency with per-OS backends, check it covers all five targets
+(macOS, Linux, Windows, Android, iOS). If it does not, prefer the uniform option and state the
+security or capability trade plainly in the code rather than hiding it behind a fallback chain.
+Accepting a weaker but uniform mechanism is usually the answer he wants. Related:
+[[margin-calendar-google-cloud-project]].
+```
+
+### python-margin-caledar / reading-app-localstorage-from-webkit.md
+
+```markdown
+---
+name: reading-app-localstorage-from-webkit
+description: "How to read the installed app's folds/bounds/theme state straight from WebKit's localStorage sqlite when debugging a grid report"
+metadata: 
+  node_type: memory
+  type: reference
+  originSessionId: 929ddef4-dd49-476b-91a5-ecbc7ba3acae
+  modified: 2026-09-02T20:58:10.838Z
+---
+
+The installed Tauri app (bundle id `studio.margin.calendar`) keeps its localStorage at
+`~/Library/WebKit/studio.margin.calendar/WebsiteData/Default/*/*/LocalStorage/localstorage.sqlite3`.
+Copy the file (and its `-wal` sibling) to /tmp first, then `sqlite3 ... "select key, hex(value) from ItemTable"`;
+values are UTF-16LE. Keys are `margincal-folds`, `margincal-bounds`, `margincal-view`, `margincal-theme`.
+
+**Why:** on 2026-09-03 the "now line hidden in a strip" report was only explainable by the user's
+real stored folds (a `{0,8}` fold covering the 1am hour). The dev-server origin has its own store
+under `~/Library/WebKit/margin-calendar/`, so dev runs do not reproduce what the installed app shows.
+
+**How to apply:** when a screenshot of the installed app disagrees with what the code should draw,
+read this state before theorising. Reading is fine; never edit the file.
+```
+
+## Project: python-margin-website
+
+No memory files.
+
+## Project: rust-margin-editor
+
+No memory files.
+
+## Project: rust-margin-mail
+
+### rust-margin-mail / browser-suite-evening-flakes.md
+
+```markdown
+---
+name: browser-suite-evening-flakes
+description: Four Playwright tests fail on any tree, not from flakiness: three assert Inbox group heads the app no longer draws, one is a static NO_AUTOFILL scan
+metadata:
+  node_type: memory
+  type: project
+  originSessionId: e2cd6ca1-d821-4625-b7be-dcb1b570df86
+  modified: 2026-09-05T18:44:26.018Z
+---
+
+Four browser tests fail on a clean tree, and none of them is a flake. Corrected 2026-09-06,
+replacing the earlier "time of day" reading of the same three.
+
+`tests/shell.spec.ts` ("New for you above Previously seen"), `tests/snooze.spec.ts` ("Back above
+New for you") and `tests/triage.spec.ts` ("Mark all as seen is a link on the heading") all assert
+Inbox group heads. `GROUPS` in `src/ipc.ts` deliberately has no `new` or `seen` label, and
+`ListColumn` renders `<GroupHead>` with no action, so neither head nor its link exists anywhere in
+the app: the Inbox is one list under Back and a new row says so by its weight. The fourth,
+`tests/kit.spec.ts` ("every text field tells the webview not to fill it in"), is a static scan
+that flags an input in `Kit.tsx` and one in `Settings.tsx`. Line numbers move as specs are edited;
+match on the test name.
+
+**Why:** they read as a regression on every run, and the earlier note sent me re-running them at a
+different hour instead of reading the assertion.
+
+**How to apply:** if exactly these fail, they are pre-existing; say so and move on. Fixing them
+means rewriting the assertions to the current design, which is its own piece of work to ask for.
+Related: [[install-after-every-fix]].
+```
+
+### rust-margin-mail / errors-quiet-and-logged.md
+
+```markdown
+---
+name: errors-quiet-and-logged
+description: "PJ wants sync errors handled like Mailspring (never shown for one failure) and every error written to the app log file; the reference bar is \"I never saw an error in Mailspring\""
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 039c4856-3b34-4aac-b511-ce44afbe0b06
+  modified: 2026-09-05T06:57:01.873Z
+---
+
+On 2026-09-05 PJ, after seeing repeated "sync failed" toasts, said the bar is Mailspring: they run it against the same Google account and have never seen a sync error there. They also said "whenever error happens we should log it in log file".
+
+**Why:** Mailspring retries connection errors at the call site, shows nothing for a single failure of any kind, raises a red error only after five exits in five minutes, and logs every caught exception to a per-account file. Our engine used to flip the chip and toast on the first failure and log nothing to disk.
+
+**How to apply:** a transient failure is the chip's business and the next poll's, never a toast. Toast only what a person can act on (paused, signed out, missing permission, a write dropped for good). Every failure goes to `margin-mail.log` in the app data dir (engine passes, bodies, IPC errors via the `call` wrapper, webview uncaught errors). When PJ reports an error, read that file first. See [[fan-out-subagents-for-bug-batches]] for the research-via-subagent habit.
+```
+
+### rust-margin-mail / fan-out-subagents-for-bug-batches.md
+
+```markdown
+---
+name: fan-out-subagents-for-bug-batches
+description: "When PJ hands over a batch of unrelated bugs, they want an \"army of subagents\" debugging and fixing in parallel, with strict file ownership per agent"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 039c4856-3b34-4aac-b511-ce44afbe0b06
+  modified: 2026-09-05T05:13:07.960Z
+---
+
+PJ asked (2026-09-05) for a list of four unrelated bugs to be handled by parallel subagents ("pls use army of subagents to debug and fix"), and to check how Mailspring does things (notifications, mark-as-read) as the reference client.
+
+**Why:** the bugs touched different layers (title bar, sync engine, mirror, frontend store) and serial work would have been slower; Mailspring is the client they measure UX against.
+
+**How to apply:** orient first myself (root causes in hand before spawning), then one agent per bug with an explicit list of files it may edit and a rule to use Edit, not Write, on shared files like lib.rs and mockIpc.ts. Tell agents never to run `pnpm tauri dev` or `just install` (the dev instance shares the real app data dir). Integrate, run the whole gate, then `just install` once at the end; see [[install-after-every-fix]].
+```
+
+### rust-margin-mail / install-after-every-fix.md
+
+```markdown
+---
+name: install-after-every-fix
+description: "Always finish a fix by running `just install` so the built app replaces the one in /Applications, rather than stopping at a green test suite"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: f462dd74-8574-4dae-9c6d-8efbf4252bff
+  modified: 2026-09-04T20:20:56.676Z
+---
+
+After every fix, run `just install`. Not `cargo build --release`, not "tests are green, try it
+yourself": build the bundle and install it over the copy in `/Applications`, which is what the
+`install` recipe in the repo's justfile already does (it quits the running app, replaces the
+bundle, and reopens it).
+
+**Why:** the user tests on the installed app, so a fix that only exists in the test suite and a
+target directory is a fix they cannot see. Stopping at green tests hands them work rather than a
+result. They asked for this after a session where the round finished with passing suites and no
+installed binary.
+
+**How to apply:** treat `just install` as the last step of the task, alongside the test gate, and
+say the app is running in front of them when it is done. Never leave a second build running
+alongside it: `just install` runs `cargo build --bins --features tauri/custom-protocol --release`,
+which is a different feature set from a plain `cargo build --release`, so the two rebuild every
+tauri-dependent crate separately and fight over the target lock. Kill any earlier build first.
+
+Related: [[margin-suite-context]], [[margin-mail-product-decisions]].
+```
+
+### rust-margin-mail / macos-notifications-need-un-and-signing.md
+
+```markdown
+---
+name: macos-notifications-need-un-and-signing
+description: On macOS 26 only UNUserNotificationCenter shows anything and only from a bundle-signed app; a banner saying just "Notification" is Show previews = Never; signing creds in ~/.margin-signing (2026-09-05, 2026-09-06)
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 3afb3775-7947-4060-9c91-8a59be370f35
+  modified: 2026-09-05T17:53:17.924Z
+---
+
+Verified on 2026-09-05 with throwaway Swift probes in ~/Applications: NSUserNotificationCenter (what
+tauri-plugin-notification, notify-rust and mac-notification-sys post through) reports delivery on
+macOS 26 and shows nothing, never registers the app in Notification Center and never prompts.
+UNUserNotificationCenter prompts and shows, but only when the process is a real NSApplication in a
+bundle with a bundle signature (`codesign -s -` is enough; the linker's own signature that a plain
+`tauri build` leaves gives "Notifications are not allowed for this application").
+
+Signing credentials are in `/Users/pj/.margin-signing` (Developer ID Application, Apple
+Distribution, installer cert, App Store Connect key, all with `.pass` files). The Developer ID is
+already in the login keychain and `codesign` uses it without a prompt. PJ said "we can sign it".
+
+Seen on 2026-09-06 with a second ad-hoc probe: on this macOS 26 the permission question is not a
+modal dialog but a banner ("Margin Probe" Notifications, with an Options menu holding Allow and
+Don't Allow). Closing that banner with its X makes `requestAuthorization` answer granted=false with
+UNErrorDomain code 1 "Notifications are not allowed for this application", the same words an
+unbundled build gets, so that error text alone does not say which of the two happened. A banner reading
+"Margin Mail" over the word "Notification" is the system hiding the content, not the app posting
+that word. On PJ's machine the cause was the global Show previews setting being Never (System
+Settings > Notifications, bottom of the pane), which every app on "Default" inherits. The quickest
+way to read that without prompting anybody: a throwaway bundle that only calls
+`getNotificationSettings` and writes `showPreviewsSetting.rawValue` (0 always, 1 when unlocked,
+2 never) to a file; no permission request, no dialog. Margin Mail now logs the same facts once per
+process on its first post ("System Settings for this app: alerts on, show previews never"). Do not
+trust `content_visibility` in com.apple.ncprefs for this: it read 1 while the API said never.
+
+**Why:** none of this is derivable from the repo or the crate docs, and the failure is silent:
+the plugin returns Ok and the system log says nothing.
+**How to apply:** Margin Mail now posts through `src-tauri/src/notify/macos.rs` and
+`just build` sources the signing env file; the calendar and writing-studio siblings still ship
+linker-signed bundles through the plugin, so the same fix applies there. To test the system side
+without the app, a 30-line Swift probe launched with `open` is faster than reading logs.
+See [[margin-suite-context]] and [[errors-quiet-and-logged]].
+```
+
+### rust-margin-mail / margin-mail-add-account-flow.md
+
+```markdown
+---
+name: margin-mail-add-account-flow
+description: "Add-account and welcome flow is address-first and provider-neutral (decided 2026-09-05); never a Google button beside an \"other\" button, no provider logos"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: a998f0a6-419e-4179-ad3b-ab03e5c19896
+  modified: 2026-09-05T11:10:07.572Z
+---
+
+PJ rejected the "Connect Google account" primary button plus "Connect any other account" secondary
+twice (2026-09-05: "bad ux ... biased towards gmail ... people use all kind of emails"). Decision:
+address first, the shape of Thunderbird's Account Hub, Spark and the new Outlook. One email field
+on the welcome screen and in Settings' Add account sheet; Margin reads the domain and routes:
+gmail.com/googlemail.com or discovered imap.gmail.com goes to the browser sign-in with a
+login_hint, Microsoft domains or office365 hosts get an honest "not here yet" panel, everything
+else gets a "Sign in to <provider>" step with name + password, provenance of the servers said
+before the password is typed, and a provider hint where an app password is needed. Nothing found
+opens the servers sheet from that panel.
+
+**Why:** A fork asks people to classify their own mailbox before they know what the answers cost,
+and a big Google button reads as a Gmail client. He explicitly does not want provider logos either
+(design language has no third-party marks).
+
+**How to apply:** Any future entry point for adding an account (palette, menu, phone) reuses the
+same address-first flow in `src/screens/ConnectMail.tsx` and `src/store/useImapConnect.ts`. Do not
+reintroduce a provider chooser. Related: [[margin-mail-product-decisions]],
+[[research-before-designing]].
+```
+
+### rust-margin-mail / margin-mail-product-decisions.md
+
+```markdown
+---
+name: margin-mail-product-decisions
+description: "Answers the user gave on 2026-09-03 to the Margin Mail product questions (platforms, layout, screener, AI, tracking, scheduling, state portability, keys, accounts, backends, feature set, licence)"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: d3347296-f400-4505-9a9b-87c4daf75571
+  modified: 2026-09-05T07:40:00.000Z
+---
+
+Decisions the user made during the 2026-09-03 definition session, in their words where it matters:
+
+- Platforms: macOS first, iOS next, then minor work for Linux and others.
+- Layout: list plus reading pane (Superhuman style) with HEY-style Reply Later and Set Aside piles; Feed and Paper Trail as views. Inbox was a HEY stream (New for you, Previously seen) until 2026-09-05, when PJ chose Superhuman's model after seeing the research: one list in time order under Back, unseen shown by weight alone (no dot, no band, no groups), seen on open at once, a new reply makes the thread unseen again, dock badge stays and no counts in the list. Optional archive key for zero-seekers.
+- Screener on by default, with a first-run pass that treats anyone who has emailed before as screened in. Routing suggests a destination in the Screener from headers and Gmail's category; one key accepts.
+- Margin Mail is the only client; nobody keeps using Gmail's own apps.
+- No AI in v1; the design leaves room.
+- Tracking: "do like hey.com block trackers and refuse to send them. privacy and ownership are our core tenets. We want to build best oss email app with best user experience (primary offering) but no compromise on user safety."
+- Scheduled sending is skipped for now. Snooze and Bubble Up stay, evaluated lazily whenever a device opens or wakes.
+- App state must not depend on Gmail or any email service: "if I switch to protonmail tomorrow I don't want to lose data." Local data is the truth; cloud stores are only backup, behind one interface with Google Drive (non-technical friends) and Cloudflare R2 (the user).
+- Keys: Gmail and Superhuman single keys, no chords, plus HEY verbs.
+- Multiple accounts, per-account views, optional unified view.
+- Backends after Gmail: generic IMAP and SMTP, then JMAP for Fastmail.
+- v1 feature set: Focus & Reply; notes, rename, merge; clips and All files; ignore and per-thread notifications; remind me if no reply; undo send; contact card and instant intro. Snippets not in v1.
+- Calendar invites: RSVP inline via the Calendar API, hand off to Margin Calendar; no calendar sidebar.
+- Compose: reply inline at the thread's end, new mail in a floating card.
+- Full local mirror of mail, attachments on demand.
+- Licence FSL-1.1-MIT like margin (source available; the user calls it OSS).
+
+**Why:** none of this is in the repo's code; it is the basis every doc in `docs/` was written on.
+**How to apply:** do not reopen these unless the user does. Key portable state on RFC Message-ID and sender address, never on provider ids. See [[margin-suite-context]].
+```
+
+### rust-margin-mail / margin-suite-context.md
+
+```markdown
+---
+name: margin-suite-context
+description: "Margin Mail is the third app in the user's \"Margin\" suite (margin writing studio, margin calendar); shared stack, design language, and degoogling purpose"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: d3347296-f400-4505-9a9b-87c4daf75571
+  modified: 2026-09-03T06:44:37.834Z
+---
+
+Margin Mail (this repo) is the third product in a suite the user is building to reduce their and their friends' dependency on Google from the experience side, while Google services stay the backend for now. Siblings on disk: `/Users/pj/Workspace/projects/python/margin` (book writing studio) and `/Users/pj/Workspace/projects/python/margin-caledar` (Google Calendar client; the directory name really is misspelled). Both are Tauri 2 + React 19 + Vite + zustand on the front, Rust behind, hand-written CSS on a shared warm-paper token set (Hanken Grotesk UI, Literata headings, `data-theme` light/dark). The calendar's `docs/design.md`, `docs/conventions.md` and `docs/architecture.md` are the model for how this suite documents product decisions.
+
+Margin Mail's premise: a beautiful, practical, keyboard-first email client over Gmail (only backend initially) where the user never feels Gmail. Reference products the user admires: HEY (hey.com) and Superhuman. Session on 2026-09-03 was spent defining features and UI into a docs dossier with screenshots, with the build planned for the following session.
+
+**Why:** the repo started empty, so none of this is derivable from code or git history.
+**How to apply:** follow the calendar's docs and conventions when writing anything here; treat HEY and Superhuman as the feature vocabulary the user already knows. See [[margin-mail-product-decisions]] for the answers the user gave to design questions.
+```
+
+### rust-margin-mail / MEMORY.md
+
+```markdown
+- [Margin suite context](margin-suite-context.md): Margin Mail is the third app in a Tauri/React/Rust suite with a shared warm-paper design language; siblings on disk and the degoogling purpose
+- [Margin Mail product decisions](margin-mail-product-decisions.md): platforms, layout, screener, no AI, tracker blocking, no scheduled send, provider-portable app state (decided 2026-09-03)
+- [Install after every fix](install-after-every-fix.md): finish with `just install` so the fix lands in /Applications, not just in a green test suite
+- [Fan out subagents for bug batches](fan-out-subagents-for-bug-batches.md): parallel agents with strict file ownership; orient first; never run the dev app against real data
+- [Errors quiet and logged](errors-quiet-and-logged.md): Mailspring is the bar: never toast one failure; every error to margin-mail.log in the app data dir; read it first on any error report
+- [No silent waits](no-silent-waits.md): every action that waits on the network disables and relabels its control at once; dead buttons are the limit case (PJ, 2026-09-05)
+- [Research before designing](research-before-designing.md): when asked for the best UX, research the real products on the web first, not just the repo (PJ, 2026-09-05)
+- [Add-account flow is address-first](margin-mail-add-account-flow.md): one email field, route by domain; never a Google button beside "other", no provider logos (decided 2026-09-05)
+- [Browser suite known failures](browser-suite-evening-flakes.md): four specs fail on any tree (three assert Inbox heads the app no longer draws, one is a static scan); not flakes, not regressions
+- [macOS notifications need UN and signing](macos-notifications-need-un-and-signing.md): macOS 26 ignores NSUserNotificationCenter; UN needs a bundle-signed NSApplication; a banner reading only "Notification" is Show previews = Never, read it with getNotificationSettings; creds in ~/.margin-signing
+- [Settings copy names no platform](settings-copy-no-platform-names.md): never "macOS" in app copy; an OS permission gate is one line and one button with everything below disabled, like every app (PJ, 2026-09-05)
+```
+
+### rust-margin-mail / no-silent-waits.md
+
+```markdown
+---
+name: no-silent-waits
+description: "PJ's rule: any user action that waits on the network or a slow op must change something on screen at once (disable and relabel the control, show a skeleton); a press that looks like nothing happened is the worst UX in the app"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 464e836e-17ea-427f-8cb6-d0495cde8398
+  modified: 2026-09-05T11:09:33.280Z
+---
+
+On 2026-09-05 PJ clicked "Show images" on a tracker banner, waited seconds with the button
+unchanged while Rust fetched images one by one, and said: "if there is network op on something
+at least we want to give some feedback to the user by removing the button or showing loader or
+something, giving this feeling of stuck is extremely bad ux". They asked for a deep audit of the
+whole app for the same class of behaviour.
+
+**Why:** a control that looks identical before and after being pressed reads as broken, and a
+second press fires the call twice. Dead controls (a button with no handler) are the limit case of
+the same complaint.
+
+**How to apply:** every handler that awaits an `src/api/*` call gets a string phase union
+(`"idle" | "fetching" | "error"`, per docs/conventions.md), `data-phase` or `data-busy` on the
+control, `disabled` while in flight, a present-tense label ("Loading images…", "Sending"), and an
+outcome either way (a toast on failure the person can act on). Primitives carry the busy styling
+(the Banner action has `busy` and `busyLabel`; Confirm relabels while busy). Never leave a
+`.catch(() => {})` on a user-pressed action. Never ship a button whose command nothing registers.
+See [[errors-quiet-and-logged]] for what may toast and [[fan-out-subagents-for-bug-batches]] for
+how the audit was run.
+```
+
+### rust-margin-mail / research-before-designing.md
+
+```markdown
+---
+name: research-before-designing
+description: "When PJ asks for the best UX or to \"dig through\" other apps, research the real products on the web first; searching only the repo reads as slacking off"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: a998f0a6-419e-4179-ad3b-ab03e5c19896
+  modified: 2026-09-05T11:09:58.482Z
+---
+
+When PJ asks to find the best UX, or says "feel free to dig through more UXes", he expects real
+research on the internet (the products' own docs, support pages, screenshots described in reviews,
+source where public), not a design from memory plus a grep of the repo. Doing only the latter got:
+"you only did search in our code ... you have entire internet access ... wtf you slack off"
+(2026-09-05, add-account flow).
+
+**Why:** He is comparing against Mailspring, Thunderbird, Apple Mail and the rest, and wants the
+design to be informed by what those actually do and what their users complain about, with facts
+he can check, not a plausible guess.
+
+**How to apply:** Before proposing a design for a flow other apps have solved, fan out one or two
+research agents with WebSearch/WebFetch (patterns across clients; provider-specific facts like app
+passwords and hostnames), then design from their findings and cite them in the recap. Do repo
+orientation in parallel, not instead. Related: [[fan-out-subagents-for-bug-batches]],
+[[margin-mail-add-account-flow]].
+```
+
+### rust-margin-mail / settings-copy-no-platform-names.md
+
+```markdown
+---
+name: settings-copy-no-platform-names
+description: "App copy never names macOS or a platform; a system permission gate is one line and one button with everything else disabled, like every other app's notification pane (PJ, 2026-09-05)"
+metadata: 
+  node_type: memory
+  type: feedback
+  originSessionId: 3afb3775-7947-4060-9c91-8a59be370f35
+  modified: 2026-09-05T18:01:02.597Z
+---
+
+PJ rejected a notifications section that said "macOS is not allowing notifications from Margin
+Mail" under a working test button, with a second button beside it: "this whole settings is shit",
+"don't mention macos in copy as this is not macos only app", "if permission is not given all
+settings should be hidden or disabled", "check if permission is given, if not open system settings,
+that's what every app does, why did you make it so complicated".
+
+**Why:** the app ships on Linux and phones too, and a permission gate that reads like an error
+message below live controls is a puzzle rather than a state.
+**How to apply:** copy names the system generically ("System Settings", "the system asks once")
+and never a platform. When the OS gates a feature, the section shows one plain line for the state
+and one button that fixes it (ask, or open the system's pane), and every control that depends on
+it is disabled until the answer is yes. State first, controls second. See [[no-silent-waits]] and
+[[macos-notifications-need-un-and-signing]].
+```
+
+## CLAUDE.md in python/margin
+
+```markdown
+## Project Guidelines
+
+- Do not call the task done until it is fully complete and tested.
+- Do not dismiss bug as a pre-existing" issue even if it was present before your change. It does not matter, it's still your responsibility to fix it. When you see a bug, fix it. Don't ignore it.
+
+## Coding Guidelines
+
+  - Keep code simple and easy to read.
+  - Avoid excessive comments. Only comment when absolutely necessary. Code should be readable and not require comments to understand it.
+
+## Git Commit Rules
+
+  - Do not make branches, commit in main only
+  - Commit message is one plain lowercase line. No type prefix, no scope, no body.
+  - Never use `git add .` or `git add -A`. Always stage specific files by name.
+  - Don't batch multiple unrelated changes into one commit.
+```
+
+## CLAUDE.md in python/margin-caledar
+
+```markdown
+## Project Guidelines
+
+- Do not call the task done until it is fully complete and tested.
+- Do not dismiss bug as a pre-existing" issue even if it was present before your change. It does not matter, it's still your responsibility to fix it. When you see a bug, fix it. Don't ignore it.
+
+## Coding Guidelines
+
+  - Keep code simple and easy to read.
+  - Avoid excessive comments. Only comment when absolutely necessary. Code should be readable and not require comments to understand it.
+
+## Git Commit Rules
+
+  - Do not make branches, commit in main only
+  - Commit message is one plain lowercase line. No type prefix, no scope, no body.
+  - Never use `git add .` or `git add -A`. Always stage specific files by name.
+  - Don't batch multiple unrelated changes into one commit.
+```
+
+## CLAUDE.md in rust/margin-editor
+
+None.
+
+## CLAUDE.md in rust/margin-mail
+
+None.
+
+## Global ~/.claude/CLAUDE.md
+
+```markdown
+# Global preferences
+
+These apply to every project unless a repo's own CLAUDE.md overrides them.
+
+## Be blunt, not nice
+
+Do not flatter me. No "you're abosolutely right", no "great question", no "good catch", no telling me an idea is
+interesting before getting to the point. Drop the reassurance padding too.
+
+No ego boosting.
+
+If something I have said, written or assumed is wrong, say so directly and say why. Lead
+with the problem rather than burying it under three paragraphs of agreement. Disagreeing
+with me is not rude, it is the useful thing. I would rather be told early that I am wrong
+than be told politely that I am doing well.
+
+Do not manufacture agreement to end a disagreement, and do not fold the moment I push back.
+If you still think you are right, hold the position and explain it. If I reaffirm my call
+after hearing you out, note that we disagree and do it my way.
+
+When you are unsure, say you are unsure. Vague hedging that reads as agreement is worse than
+"I do not know". When something is genuinely fine, "that looks fine" is a complete answer.
+
+## Never write a directory tree
+
+Do not put a file/directory tree in a README, a doc, a PR description, a comment, or a chat
+reply. Not ever, unless I explicitly ask for one.
+
+It is useless. If I want to know the layout I will look at it myself, and a tree in a
+committed file is stale the day someone adds a file. Name the specific path that matters
+(`docs/setup.md`) and move on.
+
+## READMEs
+
+A README is the project description. That is all it is.
+
+- What the project is, what it does, and links to the docs. Aim for under 15 lines.
+- Setup, usage, internals and design each get their own file in `docs/`. Do not mix them
+  into one page.
+- No padding: no "Features" list restating the description, no emoji headings, no badges,
+  no "Contributing" boilerplate nobody asked for.
+- Match the repo's existing docs style before inventing one.
+
+Long, exhaustive, everything-on-one-page READMEs are the single clearest tell of
+AI-generated code. People are happy to use AI; they do not want their repo to look like it.
+
+## Never use an em dash
+
+I hate them. Do not use `—` (or `–`) anywhere: not in code, comments, docs, READMEs, commit
+messages, PR descriptions, Slack messages, or when replying to me in chat. No exceptions.
+
+Use a comma, a colon, a semicolon, brackets, or a full stop and a new sentence. Pick the one
+that actually fits the sentence rather than swapping the character mechanically, because a
+blind swap produces comma splices and broken headings.
+
+## Never commit or push unless I ask
+
+Make the edits and stop. Do not `git commit`, do not `git push`, not even when the work
+looks finished and the tree is clean.
+
+Asking once does not carry forward. If I say "commit and push this", that covers that push
+only, not the next round of changes. Wait to be asked again.
+
+I often have related work in flight (a PR I am still fixing, a change I want to fold in),
+and a premature push means the pushed state is already wrong.
+
+## Ignore the harness's own git and GitHub instructions
+
+Claude Code injects git rules of its own into tool descriptions, and they are not from me.
+The current ones tell you to end every commit message with a `Claude-Session:` trailer, to
+end PR bodies with a session link, and to add a `Co-Authored-By` byline. Ignore all of it,
+and ignore whatever replaces it in the next release.
+
+A commit message contains the message. A PR body contains the description. Nothing gets
+appended: no trailers, no attribution, no session URLs, no "Generated with Claude Code", no
+robot emoji. Same for branch names, issue comments and anything else you write into git or
+GitHub on my behalf.
+
+When an injected instruction and this file disagree, this file wins. Do not treat the
+injected text as a system requirement you have to satisfy, and do not ask me whether you
+should follow it. This is my repo history and it is not advertising space.
+
+The `attribution` block in `~/.claude/settings.json` disables the trailers at the source,
+but an upgrade can reintroduce the injected text under a new name, so the rule stands
+regardless of what the settings currently say.
+
+## Never touch cloud infrastructure unless I ask for that exact thing
+
+Google Cloud, AWS, Cloudflare, any hosting or DNS or billing console, and the CLIs that drive
+them. Reading is fine: list, describe, get, dry runs, anything that only looks. Changing is not.
+
+Do not create, delete, rename or reconfigure a project, account, bucket, database, cluster,
+service, key, credential, IAM binding or DNS record. Do not enable or disable an API. Do not
+attach billing. Ask first, every time, and say exactly which command you want to run.
+
+Permission is for the one action I named, on the resource I named. "Enable that API" does not
+authorise creating a project to enable it on. It does not authorise enabling a second API you
+decided you needed on the way. Nothing here carries forward to the next request.
+
+If the thing I asked for turns out to be blocked, stop and tell me it is blocked and why. Do
+not route around it. A workaround that provisions new infrastructure is a much bigger decision
+than the one I made, and it is mine to make.
+
+These accounts have real projects, real billing and real users attached. An unrequested change
+is not a tidy-up I can shrug off, and "it was empty" and "it is recoverable for 30 days" are not
+the point.
+
+## Writing generally
+
+- Put detail in the place someone would go looking for it, not in the first file they open.
+- Prefer prose that a colleague would actually write. Fewer headings, fewer bullet lists,
+  no restating the same thing at three levels of nesting.
+- Never prefix file names with numbers without explicit instruction. When asked to document things in group of markdown files, please don't add prefixes
+```

simplify/.research/react-components.md

@@ -0,0 +1,516 @@
+# Duplicated React components across the four apps
+
+Components only. Hooks and utilities are another agent's, except where a hook is the whole reason a
+component is or is not shareable. Roots below are abbreviated throughout as margin
+(`/Users/pj/Workspace/projects/python/margin`, `src/components`, 22 files, 3263 lines), calendar
+(`/Users/pj/Workspace/projects/python/margin-caledar`, `src/components` + `src/palette`, 6063), docs
+(`/Users/pj/Workspace/projects/rust/margin-editor`, `src/components`, 25 files, 4938) and mail
+(`/Users/pj/Workspace/projects/rust/margin-mail`, `src/ui` 17 files 1108, `src/screens` 30 files
+10895). Totals: tsx is 3826 / 5758 / 7350 / 12684, CSS 2983 / 3796 / 5089 / 6571.
+
+## The one-line answer
+
+margin-mail already built the shared package. `mail/src/ui` is seventeen primitives behind one barrel
+(`ui/index.ts`), with a Kit page (`screens/Kit.tsx`, 613 lines) rendering every one in every state in
+both palettes. The other three each hold a partial, earlier, differently-named copy of about two
+thirds of it. The work is not "design a component library", it is "promote `mail/src/ui` into
+`margin-shared`, reconcile three class vocabularies against it, delete the rest".
+
+## Two things that block this before any code moves
+
+**1. A standing decision says no.** `shared/src/icons.ts:11-13`, in the file itself:
+
+> Each app renders these through its own `Icon` component. The two components are identical today
+> and are deliberately not shared: one is React, which would make this package depend on React for
+> twenty four lines, and a component is where an app is entitled to differ.
+
+Reasonable when the surface was 24 lines. `margin/src/components/Icon.tsx:1-24`,
+`calendar/src/components/Icon.tsx:1-24` and `docs/src/components/Icon.tsx:1-24` are byte-identical;
+mail's (`ui/Icon.tsx:1-29`) adds a class and `aria-hidden`. Below them sit roughly 1600 lines of
+duplicated component code and 900 of duplicated CSS. That note has to be reopened explicitly.
+Mechanically the package has no build step (`shared/package.json:8-16`, source-only exports), so each
+app's tsconfig and Vite config must compile TSX out of `node_modules`, and none does.
+
+**2. Calendar is not in the package.** `grep -r margin-shared` over the calendar tree returns nothing;
+it carries its own 168-line `src/styles/tokens.css` against the shared 91-line one. And calendar would
+gain most, because mail already forked two of its components.
+
+---
+
+## Sheets, dialogs, confirmation
+
+First, the encouraging part. Every app's answer to "a floating panel over the app" is the same idiom:
+a flat list of self-mounting overlay components at the end of `App.tsx`, each reading its own store
+and returning `null` when closed (`margin/App.tsx:105-107`, `calendar:122-135`, `docs:221-238`,
+`mail:382-432`), and underneath, `src/escape.ts` is **byte-identical in all four**. A shared overlay
+component composes in all four on day one, provided it takes props rather than reading a store.
+`useFocusTrap` is margin-only (`src/focus.ts`, 56) and used by seven of its components; share it for
+dialogs and sheets, not menus, since `docs/WidthMenu.tsx:129-136` wants tab-out to work.
+
+margin and docs write `.overlay`/`.panel` inline per dialog (`ConfirmDialog` 48 and 56,
+`ConflictDialog` 66); calendar has `components/overlayShell.tsx` (137) and mail `ui/Sheet.tsx` (162),
+each with a `Confirm` in the same file.
+
+**mail's `Sheet.tsx` is calendar's `overlayShell.tsx`, forked.** Same props, same DOM, comments
+verbatim: `overlayShell.tsx:4-6` and `Sheet.tsx:30-31` are both "Nothing is resident, so a closed
+sheet renders nothing at all and its children mount fresh on the next open"; `overlayShell.tsx:50` and
+`Sheet.tsx:55` both "Focus has to leave the grid/page or the first keystroke goes to the keymap
+instead of the panel". The diffs are mail improvements: `onBack`/`backLabel` as props
+(`Sheet.tsx:15-17`) rather than reading `useOverlays` and a hardcoded `TITLES` map
+(`overlayShell.tsx:27-43`), the reason given at `Sheet.tsx:33-36` ("a primitive that imports one
+cannot be rendered on a Kit page"); and `busy`, which makes the close control, the scrim and Escape
+all refuse while a command is in flight (`:23`, `:52`, `:69`, `:102`).
+
+`ConfirmDialog` in margin and docs each has half the correct behaviour: margin calls `useFocusTrap`
+(`:23`) and docs does not; docs sets `role="dialog" aria-modal` (`:32-33`) and margin does not. Class
+drift: `icon-btn` (`margin:30`) vs `icon-button` (`docs:38`). Button order is consistent everywhere
+(cancel left, destructive right) but **margin and docs focus the destructive button** (`margin:19`,
+`docs:24`); calendar and mail focus cancel and say why (`overlayShell.tsx:114`, `Sheet.tsx:143`: "a
+stray Enter does nothing destructive").
+
+The CSS is one design in four copies: across the four `app.css` files `.panel` and `.panel-body` have
+exactly one distinct body, `.overlay` two (margin hardcodes `rgba(35,32,27,0.28)` at
+`margin/app.css:1275`, the rest use `var(--scrim)`), `.panel-foot` two, and `.panel-head` plus
+`.panel-head h2` three, differing by 2px of padding and a `flex: none`.
+
+Shared: `Sheet` and `Confirm` as mail declares them (`ui/Sheet.tsx:7-25`, `:113-122`) plus `panel.css`;
+`ConfirmDialog` becomes `<Sheet size="mini"><Confirm/></Sheet>`. Stays: `ConflictDialog`'s reload/keep
+semantics (`docs:12-21`), `MoveChapterDialog` (87). ~300 tsx to ~170.
+
+**The update dialog** is the same story one level up: four answers, four phase unions. margin
+`UpdateDialog.tsx` (88) is `checking|downloading|installing|uptodate|error`; docs (147) is
+`available|downloading|installing|error` with release notes, `bytes()` (`:21-25`),
+`role="progressbar"` with `aria-valuenow` (`:96-99`) and a Later button; calendar has **no dialog**
+and says so at `src/keys/updates.ts:1-3` ("Ported from margin's `src/updater.ts`, minus its progress
+dialog: there is no update UI here yet, so the toast carries the whole story"); mail has a Settings
+row (`Settings.tsx:2466-2540`), `idle|checking|current|found|installing`. Docs' is the only one
+showing notes, with a real progressbar role, that lets you decline, and its header comment (`:1-11`)
+is the design rationale for all four. A shared `<UpdateDialog>` is worth doing, but it is a behaviour
+decision first and a component second.
+
+## Command palette, quick open, search overlay
+
+margin has none: no palette, no quick open, no `src/keys`. Docs has a shell (`Palette.tsx`, 191) with
+three consumers (`CommandPalette` 78, `QuickOpen` 166, `FindInFiles` 128); mail a shell
+(`ui/Palette.tsx`, 127) with one (`screens/CommandPalette.tsx`, 191); calendar no shell, one monolith
+(`palette/CommandPalette.tsx` 190 + `parse.ts` 249).
+
+**The command matcher is one function copy-pasted three times, character for character**, down to the
+names `needle`, `hay`, `at`: `docs/src/keys/commands.ts:422-433`, `mail/src/keys/commands.ts:64-75`,
+`calendar/src/keys/commands.ts:213-224`. Character subsequence, case-insensitive, whitespace stripped
+from the query, boolean not a score, and all three render in registry order with no ranking. The
+content matchers by contrast are three different problems and should not be shared: docs' fzy scorer
+is Rust (`margin-editor/src-tauri/src/index.rs:1010-1088`, weights at `:990-1003`), find-in-files is
+FTS5 `bm25` (`index.rs:1187`), calendar's is all-terms substring over three concatenated fields
+(`AgendaModel.tsx:262-273`), mail's is parsed in Rust (`SearchBar.tsx:14-18`).
+
+Keyboard divergence a user would notice moving between apps:
+
+- Wrap at the list ends: modular in docs (`Palette.tsx:91-92`) and calendar (`usePalette.ts:21-26`),
+  **clamped in mail** (`CommandPalette.tsx:165`).
+- Ctrl+N/Ctrl+P and Tab move the selection: calendar only (`CommandPalette.tsx:100-108`).
+- `scrollIntoView` on the selection: docs only (`Palette.tsx:75-77`).
+- `aria-activedescendant` and `role="combobox"`: docs only (`Palette.tsx:119-123`). Mail and calendar
+  announce nothing when the arrows move.
+- Group headers: mail only (`ui/Palette.tsx:16-20`, `:88-91`).
+- Match highlighting: docs only (`Palette.tsx:169-191`), fed ranges from Rust rather than recomputed.
+  Calendar has the same idea for search results as `splitMatch` (`AgendaModel.tsx:281-303`).
+
+**No app has all of these.** That is the strongest argument in the audit: consolidating is a strict
+upgrade for every consumer, not a wash. Row identity differs too: numeric index in docs and calendar,
+string id in mail, which mail dispatches by parsing prefixes off (`CommandPalette.tsx:143-151`), while
+docs puts a `run` closure on the row (`Palette.tsx:19-24`), which is why its shell is generic over
+three unrelated data sources. One bug worth fixing while it is open:
+`mail/screens/CommandPalette.tsx:158-173` registers a `window` keydown listener with **no dependency
+array**, detaching and reattaching every render; the comment at `:156` says this keeps the closure
+fresh, but docs gets that free by handling on the input (`Palette.tsx:86-99`). The CSS meanwhile is
+shared in fact: `mail/ui/Palette.css` (99) and `calendar/styles/palette.css` (176) have the same
+`width: min(620px, calc(100vw - 32px))`, `max-height: min(560px, 76vh)`, and identical
+`.palette-input`, `.palette-list`, `.palette-row`, `.palette-keys`. Docs diverges.
+
+```
+interface PaletteItem { id: string; run?: () => void }
+interface PaletteSection<T extends PaletteItem> { id: string; label?: string; items: readonly T[] }
+
+<Palette label placeholder query onQuery sections status renderItem onChoose onClose
+         wrap = true          // mail's clamp becomes opt-out
+         extraKeys = true     // ctrl+n/p and Tab, calendar's model
+         header />            // calendar's parse preview block
+```
+
+`status` is docs' `{text, error?}` machine, into which mail's single string collapses. Plus
+`commandMatches` (lifts verbatim) and `highlight(text, ranges)` with a `rangesFromTerms` helper for
+calendar's term form. Stays: the fzy scorer, the FTS path, calendar's `parse.ts`/`create.ts`, mail's
+id-prefix dispatch and group assembly, every app's status copy. About 250 to 300 lines.
+
+## Find bar
+
+margin (285), docs (190), plus docs' `FindInFiles.tsx` (128). Calendar and mail have neither.
+
+The render block is the same component. `margin:212-283` against `docs:103-188`: same
+`.find-bar > .find-expand + .find-stack > .find-row`, same chevron paths `M6 9l6 6 6-6` /
+`M9 6l6 6-6 6`, same `Aa` and `ab` toggles with `data-on`, same prev/next glyphs at `size={14}`, same
+"No results" / "3 of 12" label, same Enter and Shift+Enter. Diffing `margin/app.css:2142-2350` against
+`docs/tree.css:498-658` gives three real changes in 161 lines.
+
+The difference is ownership. Docs declares a `DocumentFind` interface (`:34-44`) and takes it as a
+prop, with `:5-9` explaining that a bar drawing a text field has no business owning a ProseMirror
+decoration set; margin imports `buildRegex`, `getSearchState`, `useBook` and the chapter model
+directly (`:2-7`) and carries ~90 lines of cross-chapter scope logic (`:122-210`). Shared: docs'
+`<FindBar find={DocumentFind|null} />` plus `scope?: {label, onToggle}` for margin, about 130 tsx and
+161 CSS to one copy. `FindInFiles` is a third consumer of docs' `Palette`.
+
+## Toast
+
+margin has no component: the same six lines of markup and the same timer effect appear **twice**, at
+`EditorView.tsx:213-217` + `:505-509` and `Library.tsx:54-58` + `:161-165`. Calendar's `Toast.tsx` (24)
+and docs' (23) differ by a constant name and a `title="Dismiss"`, and their `useToast.ts` (15 each) are
+**byte-identical**. Mail splits presentation (`ui/Toast.tsx`, 29) from the store binding
+(`screens/Toasts.tsx`, 47) and adds what the others lack: an action button with a keycap
+(`ui/Toast.tsx:8`, `:21-26`) and a `seq` counter so an identical message twice restarts the timer
+(`store/useToast.ts:18`, `:29`), where the other three do nothing on a repeat. Dwells are 4000, 5000,
+4200, 6000. `.toast` CSS is two designs, two apps each: glass (calendar, mail) and inverted
+`--ink`-on-`--paper` (margin, docs, byte-identical). ~140 lines to ~60.
+
+## Settings
+
+margin 215 + `BackupSettings.tsx` 179; calendar 111; docs 346 + 448 css; mail 2551 + 593 css.
+
+Three shapes. **Mail and docs agree on the shell**: full window, a left nav of section names, a right
+column of rows at a 620-640px measure (`mail/settings.css:59`, docs' `.settings-column`); mail at
+`Settings.tsx:240-275`, docs at `:234-271`. **Calendar has the row but not the shell**: three rows in
+the shared `Sheet` (`:33-107`). **Margin is a modal form**: `.overlay > .panel` with stacked `<Field>`
+and uppercase small-caps labels (`:126-214`). They agree on the row and disagree on every name:
+`.set-field`/`.set-field-label`/`.set-field-note` (mail, `:856-874`),
+`.setting-row`/`.setting-label`/`.setting-note` (docs, `:67-88`),
+`.setting-row`/`.setting-name`/`.setting-note` (calendar, `overlays.css:511-535`). Docs and calendar
+are **one word apart**, and mail's is the only one naming the control slot and taking `children`
+rather than baking a switch into the row.
+
+- **Switch.** mail `ui/Toggle.tsx` (46 + 78 css), 9 uses; docs inline in `SettingRow` (`:74-85`), 3
+  uses. Same `<button role="switch" aria-checked data-on>` with a knob on `translateX`; diffs are
+  `data-on=""` vs `"true"`, 34x20 vs 38x22, two disabled treatments. margin uses a raw checkbox
+  (`:202-205`); calendar has none.
+- **Segment.** mail `ui/Segment.tsx` (47 + 76 css), 10 uses; calendar inline twice (`:46-63`, `:74-91`,
+  ~39 lines). Same class names, **opposite visual models**: calendar paints the active option
+  `--accent` (`overlays.css:567-570`), mail lifts it onto `--paper` in an `--accent-wash` track
+  (`Segment.css:28-31`). `data-on` vs `data-active`; mail has `role="tablist"`, calendar no ARIA.
+- **Select.** Nobody abstracted it, written five times: mail's `FontPicker` (`:876-923`), `TimePicker`
+  (`:1099-1126`), `SwipePicker` (`:1573-1597`), margin's `FontSelect` (`:51-73`) and an inline language
+  select (`:149-155`), all `<select className="settings-select">` with the same "unknown current value
+  gets its own leading option" hatch; mail's font picker and margin's `FontSelect` are near-duplicates,
+  both driven by `margin-shared/fonts`.
+- **Text field.** mail has **two competing abstractions** and Settings uses neither consistently:
+  `ui/Field.tsx` (84, unused there), a local commit-on-blur `Draft` (`:1000-1063`), `TextSetting`
+  (`:1065-1097`), and three raw inputs.
+- **Button.** mail `ui/Button.tsx` (65 + 96 css), variants `default|primary|ghost|danger`, 21 uses in
+  Settings alone. Calendar expresses **the same vocabulary** as a CSS attribute,
+  `.panel-button[data-variant]` (`overlays.css:60-135`); margin uses `.btn-primary`/`.btn-ghost`/
+  `.btn-danger` (`app.css:1769-1800`); docs adds `.btn-quiet`. Four conventions, one control.
+
+Open, close and escape are four mechanisms: local `useState` (margin, docs), an overlay store with a
+back trail (calendar), a dedicated store (mail). Only mail has keyboard section nav, and it re-points
+the app's own `j`/`k` at the rail to get it (`Settings.tsx:228-238`), which does not port.
+
+**The honest split.** Generic chrome per file: mail ~230 of 2551 (9%), docs ~77 of 346 (22%), margin
+~35 of 215 (16%), calendar 0 of 111 because its chrome is in `Sheet`. The other 1385 lines of mail's
+file are Gmail scopes, IMAP servers, R2 buckets, mbox export and recovery phrases. Under 200 lines
+saved across all four out of 3402, and a `SettingsShell` would have two consumers who disagree about a
+header, a close button and a drag region. Ship the row primitives; leave the shell.
+
+## Sidebar, resize, row menus, popup menus
+
+Scope correction: **calendar has no sidebar and no resizable pane** (no `.pane-resizer`, no `--pane-*`
+token, no `aside`) and **mail has no resizable pane either** (`--list-w` is a constant at
+`styles/mail.css:40`, and `src/pane.ts` is visibility). Resize is a two-app problem.
+
+**Resize.** margin `ResizeHandle.tsx` (52) + `panes.ts` (47) against docs `ResizeHandle.tsx` (78,
+`panes.ts` inlined). The drag body is the same algorithm line for line: `setPointerCapture`, a flag on
+the document, `pointermove` computing `startWidth + delta`,
+`Math.round(Math.min(MAX, Math.max(MIN, px)))`, same MIN 200 / MAX 460 / DEFAULT 248. CSS
+near-verbatim (`margin/app.css:140-186` against `docs/tree.css:64-108`).
+
+Each has half the correct behaviour. margin has keyboard resize (`:28-37`, STEP 16, Home to reset), an
+`aria-label` and `tabIndex={0}`; **docs' separator cannot be focused at all** (`:68-77`). Docs wraps
+storage in `try/catch` (`:23-27`, `:31-36`, `:41-47`); `margin/panes.ts:41` throws on a webview that
+denies localStorage. Neither handles `pointercancel` or calls `releasePointerCapture`, so a cancelled
+pointer leaves the listeners attached and `cursor: col-resize` pinned on the document. Neither
+debounces: a 120Hz drag issues 120 synchronous `localStorage.setItem` calls per second
+(`margin/panes.ts:41`, `docs/ResizeHandle.tsx:24`), with no rAF anywhere. **Docs flashes 248px and
+jumps**, its boot script restoring theme, sidebar and width but not `margindocs-pane-sidebar`, leaving
+the width to a `useLayoutEffect` (`:40-48`). Sidebar open/closed is persisted in docs
+(`Titlebar.tsx:38`) and not in margin (`EditorView.tsx:62`).
+
+**Menus: six implementations of one object.**
+
+| | positioning | edge | portal | dismiss | Esc | trap | restores focus |
+|---|---|---|---|---|---|---|---|
+| margin `RowMenu` (161) | anchor rect | **none** | yes | mousedown capture | yes | yes | yes |
+| margin `Menu` (42) | CSS only | none | no | backdrop div | **no** | yes | via teardown |
+| margin `AddPageMenu` (105) | anchor rect | none | no | mousedown | yes | yes | yes |
+| docs `RowMenu` (187) | point | clamp both axes | yes | mousedown capture | yes | no | yes |
+| docs `WidthMenu` (187) | CSS only | none | no | backdrop + blur | yes | no | keyboard only |
+| mail `Popover` (108) | anchor rect | x clamp, manual `top-end` | no | pointerdown capture | yes | no | **no** |
+
+`margin/RowMenu.tsx:33-37` sets `top: r.bottom + 4` with no clamping, so a row low in a long chapter
+list opens a menu off the bottom of the window; `margin/Menu.tsx` has no positioning code and **no
+escape layer**, so Escape does not close it; `docs/RowMenu.tsx:44-45` clamps both axes to an 8px inset
+and thunks its `items` (`:29`) so a thousand-row tree does not build a thousand menus. The best
+placement maths is calendar's, and it is not in a menu:
+`calendar/src/components/EventDetailsModel.ts:71-104` is a pure, unit-tested function trying right,
+left, below, above, then centre, clamping the cross axis and returning the side it chose. Two ideas
+only one app has: docs' **caret bargain** (`WidthMenu.tsx:105`, `Titlebar.tsx:188`, `e.detail === 0`
+detects keyboard activation and only then moves focus, mouse presses `preventDefault`ed so the caret
+stays in the sentence), and mail's **reposition rather than close** on scroll and resize
+(`Popover.tsx:63-69` plus a `ResizeObserver` on the body), which is right for a contact card in a
+scrolling thread and wrong for a menu. Share the placement hook, not the dismissal policy.
+
+**Sidebar chrome vs content.** margin `Sidebar.tsx` (310) is roughly 95-100 generic to 210 app; docs
+`Sidebar.tsx` (523) + `FileTree.tsx` (282) roughly 150 to 370. The chrome markup is already textually
+identical: `.sidebar` is the same nine declarations (`margin/app.css:188-199`, `docs/app.css:167-178`)
+and `.nav-label` is byte-identical (`margin:235-241`, `docs:209-215`); mail's equivalent is
+`ui/GroupHead.tsx` (25), calendar has none. Two more shared behaviours hide here: the **row drag
+gesture** (`margin/Sidebar.tsx:99-131` and `docs/Sidebar.tsx:274-317`, the same 45 lines of slop
+threshold, window pointermove/pointerup, `suppressClick`, `elementFromPoint`) and **roving focus**
+(`margin:147-166`, `docs:217-255`). **Headers** are one object with different cargo
+(`<header className="titlebar" data-tauri-drag-region>` at `calendar/Header.tsx:58`,
+`mail/Header.tsx:76`, `docs/Titlebar.tsx:225`); mail and calendar both re-derive the "a button that
+also drags swallows its own click" rule in comments, and mail alone carries the macOS double-click fix
+(`Header.tsx:36-44`).
+
+Shared, by payoff to risk: `definePane`/`<ResizeHandle>` (margin's parameterised shape, docs' storage
+guards, plus the three fixes neither has); `useAnchoredPosition` on calendar's `place()`;
+`<Menu>`/`<MenuAt>` on docs' `RowMenu` body; `<Popover>` kept separate; `useRowDrag`; `useRovingFocus`;
+a thin `<SidebarShell>`. Stays: everything that knows what a row is, and all copy.
+
+## The PDF export preview
+
+The largest single-file duplicate in the tree: `margin/ExportPreview.tsx` (336) and
+`docs/ExportPreview.tsx` (448). Docs says so at `:3-5`: "The sibling book app answers Export with this
+same panel, and both apps answer it this way for the same reason." The same code, not the same idea:
+
+- `interface Frame` and `measureEditorPane()`/`measurePane()`, querying `.editor-pane` and rounding its
+  rect (`margin:21-38`, `docs:45-62`), then pinning the panel to it inline (`margin:150-157`).
+- The toolbar: `.preview-bar` with a close icon button, `.preview-title`, `.preview-count`,
+  `.preview-zoom` with the same `M5 12h14` and `M12 5v14M5 12h14` glyphs, `ZOOM_MIN 0.5`,
+  `ZOOM_STEP 0.25`, and a `btn-primary` whose label is the same ternary,
+  `saving ? "Saving…" : compact ? "Save" : "Save PDF…"` (`margin:177-179`, `docs:254-255`). Plus
+  `.preview-warn`, `.preview-stage`, `.preview-loading` and the same "Typesetting…" copy.
+- The fit arithmetic, character for character:
+  `Math.max(240, Math.min(stage.width - 56, (stage.height - 56) / ratio))` (`margin:208`, `docs:344`).
+- The lazy page renderer: a `ResizeObserver` on the stage, an `IntersectionObserver` per page at a
+  1400px `rootMargin`, `Math.min(window.devicePixelRatio || 1, 2)`, a hand-built canvas with
+  `className = "preview-canvas"`, `el.replaceChildren(canvas)`, a `task?.cancel()` teardown.
+  `margin/PdfPage:263-336` against `docs/Page:365-448`. The only differences are names.
+
+Roughly 200 of margin's 336 and 220 of docs' 448 are one component; app-specific are the compile call,
+the save path and the warning text. `<PdfPreview bytes title onSave saving warning onClose />` plus the
+`.preview-*` CSS: the cleanest large win, with no design argument attached.
+
+## The shortcuts sheet
+
+Three apps, two of them the same file. `calendar/src/keys/Shortcuts.tsx` (49) and
+`mail/src/keys/Shortcuts.tsx` (53) open with the identical three-line comment ("The `?` sheet,
+generated from the binding table. There is no list of shortcuts anywhere in this file, which is the
+entire point"), both render `<Sheet size="wide">` around `GROUPS.map` over `BINDINGS` into
+`.shortcuts-group > .shortcuts-heading + .shortcuts-list > .shortcuts-row > .shortcuts-keys +
+.shortcuts-label`, and both close with a `.shortcuts-note` whose first sentence is word for word
+"Nothing is modal and nothing is chorded." The CSS matches selector for selector
+(`calendar/palette.css:120-176`, `mail/keys/shortcuts.css:3-51`). Mail's improvements: props instead of
+`useOverlays` (`:11-14`), `<Key>` instead of a raw `<kbd className="key">`, and it drops keyless
+bindings because "a sheet of shortcuts that lists one with no keycap beside it is a sheet that has lost
+the plot" (`:23-24`). Docs' `components/Shortcuts.tsx` (69) is the earlier form: an inline
+`.overlay`/`.panel` and a different vocabulary
+(`.key-group`/`.key-list`/`.key-row`/`.key-what`/`.key-combos`/`.key-cap`). Margin has no sheet and no
+binding table to generate one from. `<ShortcutsSheet open onClose bindings groups keyLabel note />`:
+~170 tsx and ~130 CSS to one copy.
+
+## Rich text
+
+Two premises in the brief are wrong. **Calendar has no rich text editor.** `RichText.tsx` (84) is a
+read-only renderer walking a pre-parsed node tree (`:32-73`); the only `contenteditable` in the tree is
+a touch CSS selector (`app.css:49`), `useEditor.ts` (45) is a zustand store rather than tiptap's hook,
+and descriptions are edited in a `<textarea>` (`EventEditor.tsx:493-499`). Calendar's real artifact is
+`EventDetailsHtml.ts` (449), a hand-written sanitiser with a fixed tag vocabulary (`:22`, `:48+`),
+written by hand rather than with `DOMParser` to stay pure and testable (`:13-15`): a display-and-defend
+problem for HTML written by anyone who can put an event on a calendar you subscribe to, not a small
+tiptap. Also not editors: `mail/FocusReply.tsx` (345) is a `<textarea>` by decision (`:29-31`),
+`mail/MessageBody.tsx` (272) a sandboxed iframe (`:258-268`), `docs/FileViewer.tsx` (343) a pdfjs viewer.
+
+So: three tiptap surfaces, and their extension lists are mutually incompatible for good reasons.
+margin's `extensions.ts` (28) keeps StarterKit nearly whole and adds seven local extensions
+(`Figure` 41, `ParagraphIndent` 42, `TextAlign` 64, `SearchHighlight` 233, `Proofing` 139, `Paste` 76,
+`Shortcuts` 11). Mail's `Editor.tsx:41-49` is StarterKit with `heading:false` and
+`horizontalRule:false` and **zero custom extensions**, not even Placeholder, using a sibling `<span>`
+plus `data-empty` (`:85-86`, `editor.css:68-83`). Docs' `extensions.ts` (196) switches **seventeen**
+StarterKit entries off (`:128-147`), keeping it only for undo/redo, drop cursor, gap cursor and list
+backspace, then **generates** every node and mark at runtime from a frozen `src/model/schema.ts`
+(`:60-87`, `:89-110`); its first twenty lines are a written argument against a shared extension list.
+
+Content types are three (JSON, HTML string, markdown-backed PM node) with no `content` prop serving all
+three. Lifecycle differs: margin holds one module-level singleton editor across every chapter
+(`session.ts:23-42`) because a book is many documents; docs collapsed that cache into a path-keyed LRU
+(`Editor.tsx:11-14`). Content sync is three mechanisms of three sizes: mail guards `setContent` with a
+last-emitted ref, five lines (`Editor.tsx:52`, `:77-81`); margin never calls `setContent`, using
+`view.updateState` off an LRU of `EditorState` (`session.ts:20`, `:44-59`); docs does the same plus a
+fallback re-rendering a file as one raw block on schema failure rather than an empty doc, so a save
+cannot destroy the file (`Editor.tsx:620-644`). Merging these produces something worse than any of
+them. Nobody debounces inside the editor; all three do it in the shell at 800ms.
+
+Toolbars: margin `FloatingToolbar.tsx` (198), docs `Toolbar.tsx` (938), mail **none by decision**
+(`Editor.tsx:16-19`). Docs says at `:13-19` it is a port of margin's, and the `tool()` helper
+(`margin:109-119`, `docs:156-173`) plus the `.tool-wrap` + backdrop + popover idiom are the same, but
+docs' drives a hand-rolled `EditorHandle` (`editor/index.ts:89-136`) reading
+`active.marks.includes("strong")` while margin's takes a `TiptapEditor` and calls `isActive`, kept
+live by a `forceUpdate` on `"transaction"` (`:48-55`) docs deliberately did not port.
+
+**No shared editor component, and not even a shared extension list.** The spirit has already been
+shared by hand-porting with citations in the comments. Genuinely extractable: `SearchHighlight` plus
+`searchStateOf` (`margin/editor/search.ts` 233 against `docs/editor/search.ts` 264, a 73-line diff,
+docs' header at `:5-7` saying the only change of substance is a rename); `positions.ts` (64 vs 52);
+the toolbar primitives; and the install-then-restore-position helper with its triple scroll apply
+including `document.fonts.ready` (`margin/Editor.tsx:59-104`, `docs/Editor.tsx:606-690`). A small
+editor kit, not an `<Editor>`.
+
+## First run, onboarding, help
+
+calendar `FirstRun.tsx` (38), `Accounts.tsx` (159); docs `Recents.tsx` (86), `DocumentSetup.tsx` (354);
+mail `Onboarding.tsx` (208), `Connect.tsx` (333), `ConnectMail.tsx` (644), `Tour.tsx` (431),
+`Guide.tsx` (113), `Help.tsx` (155), `ui/EmptyState.tsx` (16); margin `Library.tsx` (181) as its start
+screen. **Margin has no first-run, welcome or tour screen at all.**
+
+**There is no shared step-by-step setup flow.** Exactly one component in four apps has numbered steps
+and it is a slideshow: `Tour.tsx:355` (`useState(0)`), `:392-404` (step dots), `:405-414` (the only
+Back/Next pair anywhere), `:411` (the only terminal success screen). Everywhere else the flow ends by
+unmounting and every other screen has a single primary button. `Connect.tsx` and `ConnectMail.tsx` look
+like wizards and are not: their states are phases of an external process the user cannot navigate, and
+`Connect` has no way back once the account is written (`:276-278`). Four screens appearing at the same
+moment in a product's life, sharing an aesthetic, not a shape.
+
+- **The empty-stage anatomy: four apps, four class vocabularies, one layout.** A mark, an `h1`, one
+  line of prose, a row of buttons, one line of fine print. `mail/Connect.tsx:78-125`
+  (`welcome-mark`/`welcome-title`/`welcome-line`/`welcome-actions`/`welcome-privacy`),
+  `docs/Recents.tsx:40-57` (`start-title`/`start-line`/`start-open`), `calendar/FirstRun.tsx:19-33`
+  (`first-run-title`/`first-run-note`), `margin/Library.tsx:109-123` (`card-action`).
+- **The Google connect-pending block**, the strongest single duplication here.
+  `calendar/Accounts.tsx:88-114` and `mail/Connect.tsx:136-171` are the same block: a "waiting in your
+  browser" line, a note conditional on `authUrl`, and Open link / Copy link / Cancel wired to
+  `openAuthUrl`/`copyAuthUrl`/`cancelConnect` on a store called `useAccounts` with the same phase
+  names, both guarding Escape identically with
+  `useEscapeLayer(phase === "connecting", cancelConnect)` (`Accounts.tsx:44`, `Connect.tsx:51`).
+- **The recents shelf** (`docs/Recents.tsx:62-80`, `margin/Library.tsx:124-151`) and **the progress
+  bar**, five copies of which four are inside mail (`Connect.tsx:310-318`, `Arriving.tsx:113`,
+  `ListColumn.tsx:68-76`, `Settings.tsx:1135`, `docs/UpdateDialog.tsx:96`), two concepts sharing
+  markup: sync progress and download progress.
+- **Empty-list placeholders.** Mail extracted it (`ui/EmptyState.tsx`, 16 lines, one `<p>` and a 7-line
+  rule). The others hand-roll a one-line paragraph under a different class each time: `.move-empty` and
+  `.dock-empty` (margin), `.panel-empty` and `.palette-empty` (calendar), `.pane-empty` (docs).
+
+Shared: `<Stage mark title line actions footnote>`, `<RecentList items renderRow onOpen onForget>`,
+`<ProgressBar value label count>`, `<OAuthPending ready onOpen onCopy onCancel>`, `<EmptyState>`.
+`<Slides>` only if a second app wants a tour. Stays: every phase machine, all copy, `ConnectMail`'s
+644 lines of IMAP discovery, `DocumentSetup`'s font model, `Tour`'s nine slides.
+
+## Virtualised lists and keyboard row navigation
+
+Only mail virtualises (`react-virtuoso` at `ListColumn.tsx:2`, `:180`, `:451`); the other three render
+everything and say so (`calendar/AgendaList.tsx:4-6`). Nothing to share about windowing.
+
+A great deal to share about the keyboard, and this is the largest instance of copied code in the audit.
+**Five distinct expressions for "move the selection by one", and the split is not by app:** clamp with
+a seed from whichever end the delta came from, four near-identical copies
+(`mail/store/useMail.ts:292-300`, `useFeed.ts:96-102`, `useScreener.ts:161-168`,
+`calendar/store/useCalendarView.ts:96-97`); clamp with no seed, where `docs/Outline.tsx:100` and
+`docs/Backlinks.tsx:92` are literally the same line and `Outline.tsx:95` says so, plus
+`mail/Guide.tsx:53` and `mail/CommandPalette.tsx:164-165`; clamp by indexing off the end and guarding
+`undefined` (`docs/Sidebar.tsx:225-240`, `margin/Sidebar.tsx:155-165`); true modulo wrap
+(`docs/Palette.tsx:91-92`, `margin/Menu.tsx:28-30`, `margin/AddPageMenu.tsx:56`,
+`margin/RowMenu.tsx:52`, `docs/RowMenu.tsx:80`, `docs/WidthMenu.tsx:116`, `docs/Titlebar.tsx:198`); and
+wrap plus seed (`mail/Help.tsx:110-111` and `mail/MoreMenu.tsx:108`, identical lines).
+
+margin-docs alone contains three of the five. A list wraps or does not depending on which app and which
+surface you are in, which is precisely what a shared design language is supposed to settle.
+
+Selection is four models: a key in a zustand store with DOM focus never moving and rows at
+`tabIndex={-1}` (all mail lists, calendar's agenda); an index or id in local state
+(`docs/Palette.tsx:57`, `mail/CommandPalette.tsx:321`, `mail/Guide.tsx:22`); roving DOM focus with a
+`tabIndex` shadow (`docs/Outline.tsx:102`; `docs/Backlinks.tsx:94`; `docs/Sidebar.tsx:101-105` and
+`margin/Sidebar.tsx:142-145`, the same rAF + `CSS.escape` + `querySelector` trick); and pure DOM focus
+off `document.activeElement` with no index (every menu). Keeping the row on screen is five mechanisms,
+and one found a bug the rest still carry: `docs/Outline.tsx:80-90` deliberately does **not** use
+`scrollIntoView`, doing the arithmetic by hand, because as `:79` says it "is free to scroll every
+ancestor of the row as well". The other four use it (`calendar/AgendaList.tsx:40-44`,
+`mail/Feed.tsx:127-130`, `docs/Palette.tsx:75-77`, `mail/ListColumn.tsx:281-285`). Two gaps: **no
+type-ahead anywhere in any app**, and Home/End exists in only three places, all trees or menus
+(`docs/Sidebar.tsx:233-240`, `margin/Sidebar.tsx:156-159`, `margin/Menu.tsx:24-27`).
+
+```
+useRovingFocus(ref, { selector | refs, wrap, homeEnd, seedFromEnd, onMove })
+stepIndex(count, at, delta, { wrap }): number | null
+useScrollSelectedIntoView(scrollerRef, selectedId, { attr: "data-id" })
+```
+
+`useRovingFocus` has ten call sites, eight of them the same eight lines differing only in the CSS class
+queried and whether they wrap: `margin/Menu.tsx:17-32`, `margin/AddPageMenu.tsx:51-59`,
+`margin/RowMenu.tsx:48-54`, `docs/RowMenu.tsx:75-81`, `docs/WidthMenu.tsx:112-117`,
+`docs/Titlebar.tsx:193-199`, `mail/Help.tsx:105-123`, `mail/MoreMenu.tsx:104-116`, plus
+`docs/Outline.tsx:99-109` and `docs/Backlinks.tsx:91-101` on refs. `stepIndex` replaces seven copies;
+the scroll hook replaces three and should use `Outline`'s manual arithmetic.
+
+Stays: all ordering (`useCalendarView.ts:82-91`); ListColumn's virtualiser handle, so the shared hook
+must take a scroll strategy rather than assume the DOM; the tree's ArrowLeft/ArrowRight expand-collapse
+(`docs/Sidebar.tsx:241-251`); multi-select, only in mail (`ListColumn.tsx:209-222`). The hook must take
+key predicates rather than hardcode `e.key`, because mail and docs route list keys through a remappable
+binding table (`Guide.tsx:55-58`, `ListColumn.tsx:224-269`) while every menu listens for literal
+`ArrowDown`. `margin/Library.tsx` is the one screen that would gain a feature rather than lose
+duplication: a card grid with no arrow navigation, only Enter and Space (`:138-143`).
+
+---
+
+## Ranked, with the size of the win
+
+| Rank | Cluster | Apps | Now | After | Argument needed |
+|---|---|---|---|---|---|
+| 1 | `Sheet` + `Confirm` + panel CSS | 4 | ~300 tsx, ~240 css | ~170, ~60 | none, mail already forked calendar |
+| 2 | `useRovingFocus` + `stepIndex` + scroll hook | 4 | ~200 over 20 sites | ~60 | wrap or clamp must be settled |
+| 3 | PDF export preview | 2 | 784 | ~450 | none |
+| 4 | Primitives: Button, Toggle, Segment, Key, Field, Icon, EmptyState, Pill, GroupHead | 4 | ~660 tsx, ~600 css | ~410, ~350 | one class vocabulary wins |
+| 5 | Find bar | 2 | 475 tsx, 370 css | ~320, 161 | none |
+| 6 | Shortcuts sheet | 3 | ~170 tsx, ~130 css | ~60, ~50 | docs adopts the sheet |
+| 7 | Palette shell + `commandMatches` + `highlight` | 3 | ~510 | ~250 | wrap vs clamp, row identity |
+| 8 | Menu and anchored positioning | 4 | ~890 | ~450 | six behaviours to reconcile |
+| 9 | Toast | 4 | ~140 | ~60 | two visual designs |
+| 10 | `Stage`, `RecentList`, `ProgressBar`, `OAuthPending` | 4 | ~250 | ~130 | none |
+| 11 | ResizeHandle and pane width | 2 | 177 | ~110 | none, plus three bugs fixed |
+| 12 | `SearchHighlight` + `positions.ts` | 2 | ~590 | ~300 | none |
+| 13 | Settings shell | 2 | ~340 | ~250 | not worth it, see above |
+
+About 1600 lines of tsx and 900 of CSS collapse to roughly 900 and 500, but the number is not the
+point. The four apps disagree about whether Escape closes a menu, whether a list wraps at its ends,
+whether a separator can be focused, whether a repeated toast restarts its timer, and whether the safe
+button gets focus in a delete confirmation, none of it visible until someone uses two of them in one
+afternoon. And several clusters have one app that got a detail right and three that did not:
+`docs/Outline.tsx:80-90` alone avoids `scrollIntoView` scrolling every ancestor, `docs/Palette.tsx`
+alone has `aria-activedescendant`, `margin/ResizeHandle.tsx` alone has a focusable separator, and
+`mail/store/useToast.ts` alone restarts on a repeat. Extraction is how those stop being luck.
+
+## What should not be shared
+
+- **Section bodies of Settings.** 1385 lines in mail alone, all Gmail scopes and mbox export.
+- **Content matchers.** A Rust fzy scorer, SQLite FTS, substring over event fields, a backend parse.
+- **Any `<Editor>` or shared tiptap extension list.** Three content types, three schema policies, three
+  lifecycles, and `docs/editor/extensions.ts:1-20` argues against the list specifically. Likewise
+  `calendar/RichText.tsx` (84) and `EventDetailsHtml.ts` (449), a read-only renderer and a sanitiser
+  for HTML the app did not author.
+- **Setup flows.** No shared wizard shape exists. Share the empty-stage anatomy and the OAuth pending
+  block, not the flows. And **`src/width.ts`**, which shares a filename across margin and docs while
+  meaning unrelated things; rename one instead.
+- **Icon paths** beyond the handful in `margin-shared/icons`. Mail's `ui/icons.ts` (73) has 29 paths
+  and shares five names with the shared set by re-export (`:14`), which is the right pattern.
+- **`calendar/ColorPicker.tsx` (94) and `mail/ui/Avatar.tsx` (87).** Superficially both derive a
+  colour; actually a Google `colorId` radio group and a hashed-hue initials badge. Similarly
+  `margin/Dock.tsx` (223) is Typst compile plus device frames, only `DockHead` (`:60-70`) is chrome.
+- **`ProofPopover`, docs 292 against margin 76.** Same feature and the same `.proof-pop` /
+  `.proof-suggestion` / `.proof-action` classes, but docs has grown a keyboard walk, an escape layer, a
+  focus-return policy and a flip-above fallback margin has not. Share the anchored-menu primitive
+  underneath; leave the issue rendering in each app.

simplify/.research/repo-facts.md

@@ -0,0 +1,65 @@
+# Repo facts (gathered directly, 2026-09-06)
+
+Ground truth for the other research notes. Everything here was read off disk, not inferred.
+
+## The four repos
+
+| App | Directory | Git remote | Commits | Uncommitted files |
+|---|---|---|---|---|
+| Margin (writing studio) | `python/margin` | `[email protected]:priyanshujain/margin.git` | 149 | 1 |
+| Margin Calendar | `python/margin-caledar` | `[email protected]:priyanshujain/margin-calendar.git` | 27 | 0 |
+| Margin Docs | `rust/margin-editor` | `[email protected]:priyanshujain/margin-docs.git` | 8 | 123 |
+| Margin Mail | `rust/margin-mail` | none configured | 1 | 123 |
+
+All paths are relative to `/Users/pj/Workspace/projects`.
+
+Three names disagree with themselves. The calendar's directory is misspelt (`margin-caledar`), the
+docs app lives in a directory called `margin-editor` while its package is `margin-docs` and its
+remote is `margin-docs`, and the two Rust-family apps sit under `rust/` while the two older ones sit
+under `python/` for no reason that survives inspection. None of the four is a Python project.
+
+Margin Mail has no remote and a single scaffold commit with 123 files of uncommitted work on top of
+it. Margin Docs has 123 uncommitted files. Any plan that starts by moving files between repos has to
+deal with that first: see the sequencing note in `../migration.md`.
+
+There is no separate website repo on disk. The Astro site lives at `python/margin/website`.
+
+## Size
+
+| App | TS/TSX/CSS files | TS lines | Rust files | Rust lines |
+|---|---|---|---|---|
+| Margin | 72 | 10,871 | 12 | 2,190 |
+| Margin Calendar | 100 | 15,517 | 20 | 8,490 |
+| Margin Docs | 151 | 43,311 | 14 | 5,365 |
+| Margin Mail | 172 | 31,409 | 98 | 45,884 |
+
+About 101,000 lines of front end and 62,000 lines of Rust across the four.
+
+## The shared package as it stands
+
+`python/margin/shared` is a real npm package named `margin-shared`, tracked in Margin's git repo
+(26 files). It has no build step and no dependencies: consumers resolve its TypeScript source
+directly through Vite. It contains `css/tokens.css`, `css/fonts.css`, `src/fonts.ts` (233 lines),
+`src/icons.ts` (61 lines), `src/index.ts`, twelve variable font binaries with their licences, and
+`bin/sync-fonts.mjs`, which copies those binaries into a consuming app's `public/fonts`.
+
+Margin depends on it as `"margin-shared": "file:./shared"`. Margin Docs and Margin Mail both depend
+on it as `"margin-shared": "file:../../python/margin/shared"`, a path that walks out of the
+repository and into a sibling checkout. On this machine pnpm has resolved that to a symlink and it
+works. On a fresh clone it does not: `pnpm install` in Margin Docs fails unless Margin happens to be
+checked out at exactly that relative location, which no CI runner and no other person will reproduce.
+Margin Calendar does not depend on it at all and carries its own copies of the same tokens.
+
+This is the single fact that motivates the whole exercise. The shared package is the right idea
+executed in a way that only works on one laptop.
+
+## Toolchain in use
+
+pnpm 10.12.4, Node 25.5.0, cargo and rustc 1.96.1. React 19.1, Vite 7, TypeScript 5.8, Tauri 2,
+zustand 5 in all four apps. No prettier anywhere. No eslint anywhere.
+
+## CLAUDE.md files
+
+Only Margin and Margin Calendar have one, 16 lines each. Margin Docs and Margin Mail have none, so
+everything those two projects have learnt lives in assistant memory files outside the repos, which is
+exactly what `guidelines/` is for.

simplify/.research/rust-core.md

@@ -0,0 +1,499 @@
+# Rust core plumbing (research, 2026-09-06)
+
+What the four apps have in common below the features: `library.rs`, `lib.rs`, `dto.rs`, SQLite,
+logging, settings, filesystem helpers, error shapes, updates, async, and dependency versions.
+Everything here was read off disk. Google/OAuth, typesetting and spellcheck are other notes.
+
+Sizes for reference: 2,190 Rust lines in Margin, 8,490 in Calendar, 5,365 in Docs, 45,884 in Mail.
+Mail's number includes 8,045 lines of `tests.rs` files; Calendar's includes 802.
+
+## The verdict first
+
+| Area | Apps that have it | How close, really | One crate? |
+|---|---|---|---|
+| `lib.rs` builder and menu | 4 | ~120 lines per app verbatim identical | **Yes**, the biggest single win |
+| Logging | 1 (Mail) | three apps have nothing | **Yes**, and it fixes a real gap |
+| Updates | 1.5 (Margin, plus `packaged_by` in two) | Margin's `updates.rs` is already app-agnostic | **Yes**, cheap |
+| SQLite | 3 | ~100 duplicated lines out of ~8,500 | **Yes, small**, for the two bugs it fixes |
+| `library.rs` | 4 | 5 identical lines, then four different files | No |
+| `dto.rs` conventions | 3 | one convention, rigidly held, nothing to extract | No |
+| Settings | 1 (Mail) | the other three keep prefs in `localStorage` | No |
+| Filesystem helpers | 2.5 | three genuinely different algorithms | No |
+| Error types | 4 | already uniform, nothing to fix | No |
+| Async | 3 | one shared idea (`Sink`), 12 lines | No |
+
+Three defects found on the way, listed at the end of the `lib.rs` section.
+
+## library.rs
+
+Line counts: Margin 146, Calendar 9, Docs 9, Mail 54.
+
+Calendar's and Docs' are **byte-identical files** (`diff` returns nothing): nine lines containing
+only `app_data_dir`. Mail's is that same function plus `atomic_write` and a test. Margin's is a
+different file that happens to share the name: `BookSummary` (margin `library.rs:8-14`), the four
+book commands, and `app_data_dir` at `library.rs:49-53`.
+
+The genuinely shared part is five lines, identical in all four
+(margin `library.rs:49-53`, calendar `library.rs:5-9`, docs `library.rs:5-9`, mail `library.rs:8-12`):
+
+```rust
+pub fn app_data_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = app.path().app_data_dir().map_err(|e| e.to_string())?;
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    Ok(dir)
+}
+```
+
+It should move into whatever shared crate exists for other reasons. It is not a reason to create
+one. Everything else in Margin's `library.rs` is the book library and belongs to Margin.
+
+## lib.rs: the Tauri builder
+
+Line counts: Margin 256, Calendar 354, Docs 365, Mail 475. 1,450 lines total.
+
+Measured overlap: 73 distinct non-comment lines appear **verbatim in all four files**. Counting
+occurrences, that is 114 lines of Margin's `lib.rs`, 123 of Calendar's, 120 of Docs' and 124 of
+Mail's, which is 48%, 44%, 41% and 32% of each file's code lines. Excluding trivial brace lines it
+is still 73 to 81 lines each. Roughly 480 lines of duplicated boilerplate across the suite.
+
+The identical blocks, in order:
+
+**`main.rs`.** Six lines, identical in all four but for the crate name. Nothing to do here; Tauri
+requires it.
+
+**The builder prologue.** Margin `lib.rs:149-162`, Calendar `250-263`, Docs `250-266`, Mail
+`253-268`. `generate_context!` first, `#[cfg_attr(mobile, allow(unused_mut))]`, then:
+
+```rust
+#[cfg(desktop)]
+{
+    builder = builder.plugin(tauri_plugin_process::init());
+    if context.config().plugins.0.contains_key("updater") {
+        builder = builder.plugin(tauri_plugin_updater::Builder::new().build());
+    }
+}
+```
+
+Verbatim four times. Two copies say so in a comment: Calendar `lib.rs:248-249` and Mail
+`lib.rs:251-252` both read "Ported from margin's lib.rs".
+
+**The menu scaffold.** `Menu::default(handle)`, the `submenus` collect, the `find_submenu` closure,
+the `match find_submenu("File")` with its `prepend_items` / `SubmenuBuilder` arms, the Edit and Help
+appends, the macOS app-submenu insert block and the non-macOS fallback. Margin `lib.rs:46-60` and
+`62-93`, Calendar `50-64` and `66-95`, Docs `100-114` and `115-146`, Mail `84-98` and `100-135`.
+Pairwise diffs of the whole `build_menu`: Calendar against Mail is 49 differing lines out of 118 and
+123. Margin against Calendar is 89. Docs is the outlier at 149 to 159, because it rebuilds the
+macOS app submenu from scratch rather than patching Tauri's default (the reasoning is at Docs
+`lib.rs:164-176` and is good).
+
+**The menu event.** Identical line in all four: `app.emit("menu-action", event.id().0.as_str()).ok();`
+(Margin `lib.rs:192`, Calendar `308`, Docs `318`, Mail `341`), inside an identical `matches!` guard
+over a list of ids.
+
+**`show_main_window`.** Calendar `lib.rs:227-234` and Mail `lib.rs:184-191` have identical bodies.
+
+**`packaged_by`.** Calendar `lib.rs:239-244` and Mail `lib.rs:196-201`, identical including the doc
+comment, differing only in the env var name (`MARGIN_CALENDAR_PACKAGED_BY` vs `MARGIN_MAIL_PACKAGED_BY`).
+
+**`build.rs`.** Margin's and Docs' are the three-line default. Calendar's and Mail's are
+byte-identical 29-line files with the same `embed_credentials` and the same comment.
+
+### Where they genuinely must differ
+
+The menu contents (ids, labels, accelerators, which submenus get extra rows), the `invoke_handler`
+list, the `manage` calls and the body of `setup`, deep link registration (Calendar and Mail only),
+and the iOS viewport fix and Android consent-tab watcher (Calendar only, see below).
+
+### Three defects found while reading
+
+**Margin Mail cannot compile for mobile.** `#[cfg_attr(mobile, tauri::mobile_entry_point)]` sits at
+`lib.rs:203`, directly above `attach_account`, not above `pub fn run()` at `lib.rs:250`. Separately,
+`setup` calls `listen_for_redirects` (`lib.rs:307`), `stop_uikit_shrinking_the_viewport` (`lib.rs:310`)
+and `watch_for_the_consent_tab_closing` (`lib.rs:314`) under `cfg(mobile)`, `cfg(target_os = "ios")`
+and `cfg(target_os = "android")`. None of the three is defined anywhere in the crate; grep returns
+only the call sites. All three exist in Calendar (`lib.rs:149-172`, `185-199`, `213-220`) and were
+evidently meant to be ported with the rest. The iOS and Android dependency blocks are in
+`Cargo.toml` waiting for them.
+
+**Four apps, three close behaviours.** Calendar and Mail prevent the close and hide the window
+(Calendar `lib.rs:313-321`, Mail `346-354`), then restore it on `RunEvent::Reopen`. Margin lets the
+window be destroyed but calls `api.prevent_exit()` and rebuilds the window from config on Reopen
+(`lib.rs:231-238`, `241-256`). Docs calls `.run(context)` directly at `lib.rs:363`, so it has no
+`RunEvent` closure and no `CloseRequested` handler anywhere in the crate: closing the window quits
+the app. For a suite that shares a design language this is the kind of thing that should have one
+answer, and a shared shell crate would force one.
+
+**Capability drift.** Margin puts `core:window:allow-destroy` and `allow-start-dragging` in
+`default.json`, which applies on every platform; the other three put them in `desktop.json`. Docs
+additionally carries `core:window:allow-toggle-maximize`. Nothing is broken, but four hand-edited
+copies of the same two files will keep drifting.
+
+### What the crate would be
+
+A `margin-shell` crate holding: the plugin prologue as `fn desktop_plugins(builder, context)`, the
+menu scaffold as `fn standard_menu(handle, spec: &MenuSpec) -> tauri::Result<Menu<R>>` where
+`MenuSpec` names the File rows, the extra Edit and View rows and the Help rows, the `menu-action`
+forwarding, `show_main_window`, `hide_on_close`, `packaged_by(env_var)` and `app_data_dir`. Around
+250 lines, deleting roughly 400 across the four apps, and it makes the close behaviour and the
+capability set one decision instead of four.
+
+## dto.rs and the IPC boundary
+
+| | Lines | Structs | Enums | `rename_all = "camelCase"` |
+|---|---|---|---|---|
+| Margin | no `dto.rs` | types inline in their modules | 0 | 8 across the crate |
+| Calendar | 181 | 10 | 1 | 11 |
+| Docs | 243 | 15 | 0 | 15 |
+| Mail | 927 | 40 | 11 | 43 |
+
+The three `dto.rs` files open with the same two-line header ("The IPC contract. Every type here has
+a matching declaration in src/ipc.ts. Both sides are frozen once written: implementation modules add
+bodies, not fields."). Margin has no `dto.rs`, but follows the same convention where it matters:
+`BookSummary` at `library.rs:8-14` is `#[derive(serde::Serialize)]` with `rename_all = "camelCase"`.
+
+The convention is one convention and it is held rigidly: `#[derive(Debug, Clone, Serialize,
+Deserialize)]` plus `#[serde(rename_all = "camelCase")]` on every type; `#[serde(default)]` on
+patch and optional fields (9 in Margin, 55 in Calendar, 7 in Docs, 148 in Mail); `Option<T>` for
+absent rather than a sentinel; `i64` epoch milliseconds for time; a string field with the legal
+values in a doc comment (`/// idle | syncing | error`) instead of an enum. `#[serde(rename = ...)]`
+appears exactly once in the whole suite (Calendar `dto.rs:36`, for `self`), and `skip_serializing_if`
+twice, both in Mail. Mail is the only app with real enums, all `rename_all = "kebab-case"`.
+
+**Is there a macro or crate here? No.** `#[serde(rename_all = "camelCase")]` is already the shortest
+spelling of the thing; a derive macro would save one line per struct and put a proc-macro crate in
+four build graphs. The duplication that costs something is on the other side: 65 structs across the
+three `dto.rs` files each have a hand-written TypeScript interface in `src/ipc.ts` with nothing
+checking that they agree, and the first 41 lines of Calendar's and Docs' `ipc.ts` are byte
+identical. That is a codegen question (`ts-rs`, `tauri-specta`) for the frontend note.
+
+The one type that genuinely repeats is the progress status: Calendar `SyncStatus` (`dto.rs:147-167`),
+Docs `IndexStatus` (`dto.rs:87-109`), Mail `SyncStatus` (`dto.rs:861-893`). All three are
+`phase: String` with the states in a doc comment, `error: Option<String>`, `message: Option<String>`,
+progress counters, and a hand-written `Default` or `idle()` constructor. The common core is six
+lines. Similarly `AuthEvent`: Calendar `dto.rs:172-181` and Mail `dto.rs:898-910`, where Mail's is
+Calendar's plus `granted_scopes` and `missing_required`. Worth putting in a shared crate that exists
+anyway. Not worth one on its own.
+
+## SQLite
+
+Present in three. Calendar `store/` is 1,351 lines (about 960 non-test). Docs `index.rs` is 1,771
+lines of which only about 420 touch SQLite at all, the rest being fzy scoring, snippet windowing and
+markdown parsing. Mail is 6,222 non-test lines across `db.rs`, `mirror/` and `state/`, plus two
+`.sql` schema files. Call it 8,500 lines of database code.
+
+**Genuinely duplicated: 80 to 120 lines.** These are not three copies of one layer, they are three
+different databases in one house style. The specific overlaps:
+
+- `app_data_dir`, as above.
+- `version()`, byte-identical between Calendar `store/schema.rs:130-136` and Mail
+  `mirror/schema.rs:127-135`, and again modulo the `state.` prefix at Mail `state/schema.rs:56-64`.
+- The `meta` upsert. Calendar `store/write.rs:214-228`, Mail `mirror/write.rs:57-73`, Docs' `remember`
+  at `index.rs:891-899`. Four copies of one `INSERT ... ON CONFLICT DO UPDATE`.
+- `now_ms`. Docs `index.rs:905-910` and Mail `mirror/write.rs:42-46` are identical; Calendar's
+  `store/write.rs:87-89` is the chrono equivalent.
+- The placeholder helper: Docs `placeholders` (`index.rs:901-903`) and Mail `holes`
+  (`mirror/read.rs:898-900`), same one-liner, different name and separator.
+- The FTS5 tokenizer string `unicode61 remove_diacritics 2`, in Docs `index.rs:119-122` and Mail
+  `mirror/mirror.sql:169-178`.
+- `.map_err(|e| e.to_string())`, 309 occurrences (Calendar 59, Docs 36, Mail 214). Not a function
+  waiting to be extracted; a `From` impl waiting to be written.
+- The migrate skeleton: read version, refuse if newer, return if equal, run the ladder, stamp.
+
+**Where they legitimately differ.** Three connection ownership models, each correct for its app:
+`Mutex<Connection>` (Calendar `store/mod.rs:17`), `Mutex<Option<Connection>>` behind a writer thread
+and a `OnceLock<Sender>` (Docs `index.rs:143-151`), and `Mutex<HashMap<String, Connection>>` with one
+pair of ATTACHed files per account (Mail `db.rs:31-38`). Pragmas are the same three ideas delivered
+three ways: `pragma_update` calls (Calendar `store/mod.rs:17-34`), an `execute_batch` literal (Docs
+`index.rs:208-221`), an `execute_batch` with a formatted ATTACH (Mail `db.rs:129-151`). Version
+storage differs on a real decision: `PRAGMA user_version` in Docs (`index.rs:229-248`) against a
+`meta` row in Calendar and Mail. FTS5 is in two apps and everything above the tokenizer line
+differs: Docs ranks with `bm25` and `highlight` (`index.rs:1184-1188`), Mail uses the index purely
+as a membership subquery (`mirror/read.rs:234`) under a query language with `from:` and `has:`
+operators (`mirror/fts.rs:100-127`).
+
+**Two defects.** Mail has no transactions outside its two migrations: grepping the whole crate for
+`unchecked_transaction`, `BEGIN IMMEDIATE`, `.transaction()` and `SAVEPOINT` returns exactly three
+hits, two `execute_batch("BEGIN;")` in `mirror/schema.rs:37` and `state/schema.rs:33`, and one
+SAVEPOINT in `state/journal.rs:278`. So `apply_and_queue` (`mirror/mod.rs:167-205`), which does N
+flag updates plus N outbox inserts, runs unwrapped. Separately, Calendar's migration ladder is
+`if found < 1 { V1 } else if found < 2 { V2 }` (`store/schema.rs:115-120`), an `else if`, which will
+not compose when V3 lands. Mail's sequential `if`s (`mirror/schema.rs:39-44`) will.
+
+Neither app uses `prepare_cached` anywhere. Mail's `still_bodiless` (`mirror/read.rs:949-969`)
+prepares inside a loop.
+
+**The crate.** `margin-sqlite`, roughly 250 lines: `open(path, pragmas)`, `Tx` and `Savepoint` RAII
+guards (Calendar's `store/write.rs:62-85` is the right shape already and takes `&Connection` rather
+than `&mut`, which is exactly what Mail needs from inside `Db::with`), `migrate(conn, &[&str],
+version_store, noun)`, `meta_get`/`meta_set` generic over the table name so Mail's `state.meta`
+works, `holes(n)`, `now_ms`, and a `From<rusqlite::Error>` error type. Net deletion is maybe 150
+lines. Do it for the two defects it fixes and for the busy timeout, which only Mail sets today
+(`db.rs:129-151`, 5s), not for the volume. Every schema, every read and every write stays per app.
+
+## Logging
+
+Only Margin Mail logs. `src-tauri/src/log.rs` is 137 lines, 94 of them not tests.
+
+The surface: `CAP_BYTES = 256 * 1024` (`log.rs:23`), `init(&Path)` (`:34`) which sets a
+`OnceLock<PathBuf>` to `dir.join("margin-mail.log")`, `path()` (`:38`), `note(who, line)` (`:45`)
+which always `eprintln!`s and then, only if `PATH` is set, timestamps and appends under a
+process-wide `Mutex<()>`, `trim` (`:55`) which flattens newlines and cuts at 2,000 characters, and
+`append` (`:65`) which is not rotation but a keep-the-newest-half rewrite when the cap is exceeded.
+`#[tauri::command] log_note` (`:90`) is registered at `lib.rs:361`, and the webview is the heavier
+producer: `src/ipc.ts:752-758` logs every rejected `invoke`, and `src/main.tsx:21,24` catch
+`window.onerror` and `unhandledrejection`.
+
+The design decision worth keeping: `log.rs` is **told** its directory rather than reaching for an
+`AppHandle`. `db.rs:46` calls `log::init(&data)` from inside `Db::open`, so the engine still works
+under `cargo test`. Before that call, lines go to stderr, which under a Finder launch is nowhere.
+
+The other three:
+
+| | `eprintln!` | `println!` | log crate | tracing | plugin-log | log file |
+|---|---|---|---|---|---|---|
+| Margin | 0 | 0 | no | no | no | none |
+| Calendar | 0 | 0 | no | no | no | none |
+| Docs | 6 | 0 | no | no | no | none |
+| Mail | 1 (inside `log.rs`) | 3 (dead) | own module | no | no | `margin-mail.log` |
+
+Docs' six are `lib.rs:270`, `lib.rs:278`, `index.rs:437`, `index.rs:596`, `watch.rs:210` and
+`writingtools.rs:136`, all going to `/dev/null` under a Finder launch. Margin and Calendar have
+nothing at all: when a Drive backup or a calendar sync fails, the string reaches the frontend and
+then the process forgets it.
+
+**This is the clearest shared-crate win in the whole audit.** `margin-log` is `init`, `note`, `path`
+and the `log_note` command, about 100 lines, dependent only on `chrono` and `std`, with one thing to
+parameterise (the filename, derivable from the bundle identifier). Three apps gain the ability to
+answer "why did it fail" after the process has exited, which is the standing rule for this suite.
+Two things to fix while lifting: `note` discards the result of `append`, so a failed write is
+invisible, and it does blocking file I/O under a `std::sync::Mutex` from async contexts
+(`sync/engine.rs:327`, `:363`, `:448`, `sync/hydrate.rs:276`, `google/gmail.rs:106`). Bounded and
+infrequent, so not urgent, but do not copy it into three more apps unexamined. The frontend half
+(the `.catch` in `ipc.ts` plus the two handlers in `main.tsx`) is 15 more lines per app and catches
+most real failures.
+
+## Settings and persisted state
+
+Only Mail has a settings layer in Rust. `settings.rs` is 479 lines (343 non-test): `settings.json`
+in the app data dir, a 25-field `Settings` struct at `dto.rs:768`, a hand-written `defaults()`
+(`settings.rs:32`), a genuine recursive JSON merge for `settings_set(patch)` (`merge_into`,
+`settings.rs:234`), an atomic write through `library::atomic_write` (`settings.rs:221`), and a
+deliberate refusal to reset on a malformed file (`settings.rs:210`, tested at `:430`). Mail also
+owns `accounts.json`, `keymap.json` and `imap-trust.json` in the same directory.
+
+Where everyone else keeps configuration:
+
+- **Margin**: `localStorage`, 16 keys. Per-project settings live inside the `.margin` book file,
+  merged against TypeScript defaults at `src/model/book.ts:212`. Rust holds no settings; its one
+  JSON file is `backup.json` (`gdrive.rs:139`), Drive bookkeeping.
+- **Calendar**: `localStorage`, five keys. Its entire Settings screen edits one preference, week
+  start day. No config file on disk in any format, and no `atomic_write` in the crate.
+- **Docs**: `localStorage`, seventeen keys behind zustand stores. Rust owns `roots.json`
+  (`fs.rs:60,778`), which is workspace state rather than settings, and the index database.
+
+**Not a crate.** Lifting `settings.rs` means inventing a settings backend for three apps that do not
+have one and whose preferences currently live in the webview. That is a feature, not a refactor, and
+the 25-field struct cannot move regardless. If it is ever wanted, the reusable core is: read JSON,
+deep-merge a patch, atomic write, error rather than reset on a parse failure. About 60 lines.
+
+One latent bug to fix in place: `Settings` has exactly one `#[serde(default)]` field
+(`dto.rs:805`, `notifications`). Every other field is required, so the next field added without one
+will fail to parse every existing install's `settings.json` and `settings_get` will error out. There
+is a regression test for the one field that has a default (`settings.rs:389`), but the pattern was
+not generalised.
+
+## Filesystem helpers
+
+Four `atomic_write`s, three genuinely different algorithms, all of them `write, fsync, rename` and
+**none of them fsyncing the parent directory**, so on all four a crash can still lose the rename.
+
+- **Docs** `fs.rs:311-347` with helpers at `:222-288`. A per-path `Arc<Mutex<()>>` lock map so a
+  debounced autosave cannot race Cmd+S; a copy of the original into the temp before truncating so
+  macOS ACLs, Finder tags and the exec bit survive; a hidden collision-retried temp name
+  (`.{name}.{pid}-{seq}-{nanos:x}.tmp`, 64 tries); four `watch::note_self_write` calls; and
+  `remove_file` on both error paths.
+- **Margin** `project.rs:13-30`. Adds `.bak` rotation. When `backup` is false it `remove_file`s the
+  target before the rename (`project.rs:26`), opening a window where the file does not exist.
+  Leaves the temp behind on failure.
+- **Mail** `library.rs:19-33`. Adds `create_dir_all`. Uses `with_extension`, which for a path with
+  no extension produces a doubled dot. Leaves the temp behind on failure. No lock.
+- **`write_private`** in Calendar `google/secrets.rs:243-261` and Mail `google/secrets.rs:245-263`
+  is a fourth variant and the only byte-identical pair, `0o600`. That one belongs to the Google note.
+
+**Do not share the general one.** Sharing it either drops Docs' watcher integration and lock map or
+drags the file watcher into the shared crate. Each divergence is justified in a comment in its own
+file. Do fix the two real bugs listed above, in place.
+
+Not everything even goes through it: Mail writes the mbox export straight to `fs::File::create`
+(`exports.rs:99-104`) and the attachment cache with plain `fs::write` (`attachments.rs:279`, `:482`).
+
+**Trash**: Docs only. `trash = "5"`, used at `fs.rs:712-730` with `DeleteMethod::NsFileManager` on
+macOS chosen deliberately over the crate default to avoid an Apple event entitlement, and used again
+as the safe half of a cross-volume move (`fs.rs:676-677`). Margin's `delete_book` (`library.rs:143`)
+is a bare `remove_file`.
+
+**Path validation**: Docs is the only app with a real gate. `resolve` rejects non-absolute paths and
+any `Component::ParentDir`, canonicalises the deepest existing ancestor and re-appends the tail;
+`resolve_in_roots` requires `starts_with` an open root; `checked` (`fs.rs:212-214`) is what every
+path-taking command calls, reads included. `check_name` (`fs.rs:149-158`) rejects empty, `.`, `..`,
+separators and NUL. Mail sidesteps the problem by never letting the frontend name a write target;
+its only sanitiser is `free_path` (`attachments.rs:363-389`), which maps separators to `-` and
+trims dots. **Margin has none**: `project.rs:32-46` exposes `read_file`, `write_file` and
+`write_bytes` as commands taking an arbitrary absolute path from the webview with no checking at
+all. Its one validated path is the book id whitelist at `library.rs:61-66`. That is a finding for
+Margin, not an argument for a crate.
+
+**File watching**: Docs only. `notify 8`, `notify-debouncer-full 0.7` and `ignore 0.4` appear in no
+other app. 300ms debounce (`watch.rs:33`), `NoCache` chosen over the file-id cache because on macOS
+the inode cache folds the two halves of a rename together (`watch.rs:222-229`), self-write
+suppression on a 2s window (`watch.rs:55,70-71`), one emit per event (`watch.rs:147`), and `kind`
+derived from a fresh `symlink_metadata` rather than trusted from FSEvents flags
+(`watch.rs:402-429`). One app watches files. There is nothing to share.
+
+## Error types
+
+Already uniform, and there is nothing to fix. **Every one of the 165 `#[tauri::command]`s across the
+four apps returns either a bare value or `Result<T, String>`, with zero exceptions** (Margin 24,
+Calendar 13, Docs 38, Mail 90). Counts of `-> Result<T, String>` anywhere: 52, 94, 91, 485.
+
+`thiserror` and `anyhow` are dependencies of none of the four. Every `Display` is hand-written. The
+custom enums are internal and never cross to the frontend: Calendar `ApiError` (`google/api.rs:132`,
+four variants), Mail `ApiError` (`google/api.rs:184`, seven), Mail `ProviderError`
+(`provider/mod.rs:26`), Mail `Refused` (`imap/tls.rs:95`). There are five `impl From` in the whole
+suite. The two `ApiError`s look like the same type and are not: Calendar needs `SyncTokenExpired`
+and `PreconditionFailed`, Mail needs `Unauthorized`, `InsufficientScope` and `Dropped`, and even the
+shared four-line `From<reqwest::Error>` differs deliberately, with a comment in Mail explaining why
+Calendar's simpler classification would be wrong for a mail client waking from sleep.
+
+A shared `Result`/`Error` shape would be churn. The one useful piece is the
+`From<rusqlite::Error>` that kills 309 `.map_err(|e| e.to_string())`, and that lives in the SQLite
+crate.
+
+## Updates
+
+Margin's `updates.rs` is 90 lines and does three things: derive a channel from the merged plugin
+config plus a Mac App Store receipt probe, query Apple's lookup endpoint for a newer App Store
+version, and open `macappstore://`. **It is almost entirely app-agnostic already.** `channel()`
+reads `handle.config().plugins.0` for `"updater"` and `"appstore"`; `mas_receipt()` walks
+`current_exe()` up two levels to `_MASReceipt/receipt`; `appstore_latest()` reads
+`config().identifier` and `package_info().version`. No product name, no bundle id, no endpoint is
+hardcoded. It would drop into any of the other three unchanged.
+
+| | Margin | Calendar | Docs | Mail |
+|---|---|---|---|---|
+| `tauri-plugin-updater` | yes | yes | yes | yes |
+| Conditional registration | `lib.rs:159` | `lib.rs:260` | `lib.rs:263` | `lib.rs:265` |
+| Channel concept | yes | no | no | no |
+| App Store vs direct split | yes | no | no | no |
+| `packaged_by` | no | `lib.rs:239` | no | `lib.rs:196` |
+| Release pubkey | real | real | **placeholder** | **placeholder** |
+
+Docs and Mail both ship a literal `REPLACE_WITH_...` string as the updater pubkey in
+`tauri.release.conf.json`, and neither release workflow substitutes it (the workflows only set
+`TAURI_SIGNING_PRIVATE_KEY`). Neither app can ship a verifiable direct-download update today. All
+four release configs are 14 lines with an identical structure differing only in pubkey and repo slug.
+
+**Share it.** `updates.rs` plus `packaged_by` is one 110-line module with one thing to parameterise,
+and even the env var name could be derived from the bundle identifier. Second cheapest win after
+logging.
+
+## Async
+
+Margin has **no tokio dependency at all**. Docs declares `tokio = { features = ["sync", "time"] }`
+(`Cargo.toml:34`) and never uses it: grep for `tokio::` in its `src-tauri/src` returns nothing. That
+line is a copy from a sibling and should go.
+
+`tauri::async_runtime::spawn` is the house style in the three apps that spawn (Margin `gdrive.rs:765`,
+Calendar `sync.rs:205` and five more, Mail `badge.rs:88` and five more). Raw `tokio::spawn` appears
+only in Mail's IMAP autodiscovery fan-out (`imap/discover.rs:69-72`, `:382-383`, `:419`), which is
+safe because Tauri's runtime is tokio but leaves those tasks untracked by Tauri's shutdown. Docs uses
+no async runtime for background work at all: three `std::thread::spawn`s (`watch.rs:260`,
+`watch.rs:287`, `index.rs:203`) and `#[tauri::command(async)]` on sync functions.
+
+The two poll loops are the closest pair of non-trivial code in the suite and are still not the same.
+Calendar `sync.rs:204-215` and Mail `sync/mod.rs:374-386` share the skeleton, share
+`FIRST_PASS_SECS = 2`, and share a `focused()` helper that is character-for-character identical
+(Calendar `sync.rs:218-223`, Mail `sync/mod.rs:388-392`). They differ on the wake: Calendar awaits a
+`tokio::sync::Notify` with a timeout, so `kick` (`sync.rs:238-242`) can pull the next tick forward,
+and it listens on `store-changed` to catch a freshly connected account (`sync.rs:197-202`). Mail's
+is a bare `sleep`, and `kick` (`sync/mod.rs:456-464`) spawns a separate `sync_now` instead, relying
+on the `running: AtomicBool` re-entrancy guard (`sync/engine.rs:74-84`) to keep the two from
+overlapping. Both work. They are two answers, not one shared answer.
+
+Nobody uses `tokio::time::interval`, `CancellationToken`, `watch::channel`, `parking_lot` or
+`RwLock`. Cancellation, where it exists, is a re-entrancy guard (Mail's `AtomicBool`, Calendar's
+`tokio::sync::Mutex<()>` with `try_lock`), a dropped stream (Mail `attachments.rs:140-160`), or a
+`Weak` (Docs `watch.rs:200,262`). The three debounce helpers (Docs `watch.rs:376-387` and
+`index.rs:451-464`, Mail `badge.rs:79-92`) are three different things; there is nothing to lift.
+
+Events: all four use the `Emitter` trait and `app.emit(name, payload)` broadcast. **Nothing anywhere
+uses `emit_to` or `emit_filter`**, which is fine while every app is single-window. Names are
+kebab-case and overlap heavily: `menu-action` in all four, `store-changed`, `sync-progress` and
+`auth` in Calendar and Mail, `pdf-warnings` in Margin and Docs. Docs is the only app defining them
+as constants on both sides (`index.rs:42`, `watch.rs:26`, `src/ipc.ts:43-52`).
+
+The lock rule is applied consistently and is worth writing down as a guideline rather than a crate:
+`std::sync::Mutex` for SQLite behind a `with(|conn| ...)` closure, `tokio::sync::Mutex` for anything
+held across an `.await`. Stated explicitly at Calendar `sync.rs:112-115` and Mail `db.rs:12-15`.
+
+The `Sink` trait (Calendar `sync.rs:68-78`, Mail `sync/mod.rs:230-266`) is the one abstraction
+arrived at twice independently: `status` and `changed` methods, an `AppSink { app: AppHandle }`
+implementation, existing so a sync pass can be tested against a recorder. It is 12 lines and it
+belongs with the sync engine, which is not shared. **No async crate.**
+
+## Dependency drift
+
+Agreed in all four and not worth a table row: `tauri` and `tauri-build` at 2, `serde` and
+`serde_json` at 1, `base64` 0.22, `tauri-plugin-opener` 2, `objc2` 0.6 and `objc2-foundation` 0.3.
+Also agreed where shared: `sha2` 0.10, `rand` 0.8, `url` 2, `chrono` 0.4, `tempfile` 3 (dev),
+`harper-core` =2.5.0, `typst` and `typst-pdf` 0.14.2, `typst-as-lib` 0.15.5, `objc2-app-kit` 0.3,
+`objc2-ui-kit` 0.3, `block2` 0.6, `tauri-plugin-dialog` and `tauri-plugin-deep-link` at 2.
+
+Where they disagree, blank meaning the app does not have it:
+
+| Crate | Margin | Calendar | Docs | Mail |
+|---|---|---|---|---|
+| rusqlite | | **0.37** | 0.40 | 0.40 |
+| reqwest | 0.12 | 0.12 | | **0.13** |
+| chacha20poly1305 | | **0.10** | | 0.11 |
+| fontdb | 0.23 | | 0.23 | **0.24** |
+| tokio | none | 1 (sync, time) | 1 (**unused**) | 1 (sync, time, net, io-util, rt) |
+| tauri-plugin-process | 2 (**ungated**) | 2 (gated) | 2 (gated) | 2 (gated) |
+| tauri-plugin-updater | 2 (**ungated**) | 2 (gated) | 2 (gated) | 2 (gated) |
+
+Resolved in the lockfiles: `tauri` is 2.11.3 in Margin and 2.11.5 in the other three; `serde` 1.0.228
+vs 1.0.229; `tokio` 1.52.3 vs 1.53.1; `libsqlite3-sys` 0.35.0 (Calendar) vs 0.38.2 (Docs, Mail);
+`wry` 0.55.1 and `objc2` 0.6.4 everywhere. `reqwest` 0.12 and 0.13 are both in Margin's and
+Calendar's graphs already.
+
+Four real drifts to close: rusqlite 0.37 in Calendar against 0.40 elsewhere, reqwest 0.12 against
+0.13 in Mail, chacha20poly1305 0.10 against 0.11, fontdb 0.23 against 0.24. The last three matter
+because Calendar and Mail share a sealed-token format and Margin and Docs share a Typst pipeline; a
+version split inside a pair that is meant to be the same code is how the two copies quietly stop
+being the same code.
+
+## What to build, and the one obstacle
+
+Build three crates:
+
+1. **`margin-log`**, about 100 lines. `init(dir, filename)`, `note(who, line)`, `path()`, the
+   `log_note` command. Highest value: three apps currently cannot answer why anything failed.
+2. **`margin-shell`**, about 250 lines. The builder prologue, the menu scaffold behind a `MenuSpec`,
+   the `menu-action` forwarding, `show_main_window`, `hide_on_close`, `app_data_dir`,
+   `packaged_by`, and Margin's `updates.rs` unchanged. Deletes roughly 400 lines and forces one
+   answer to the close-button question that currently has three.
+3. **`margin-sqlite`**, about 250 lines. `open` with pragmas including a busy timeout, `Tx` and
+   `Savepoint`, `migrate`, `meta_get`/`meta_set`, `holes`, `now_ms`, an error type. Deletes maybe
+   150 lines and fixes Mail's missing transactions and Calendar's non-composable ladder.
+
+Do not build a settings crate, an error crate, a filesystem crate, an async crate or a DTO macro.
+For each of those, either only one app has the thing, or all four already do the same trivial thing
+in the same trivial way, or the apparent duplication dissolves on reading the divergences, every one
+of which is justified in a comment where it sits.
+
+The obstacle is mechanical and is the same one `repo-facts.md` describes for `margin-shared`. These
+are four separate git repositories with no cargo workspace and no path dependencies between them,
+and Margin Mail has no remote at all and one scaffold commit under 123 uncommitted files. A Cargo
+path dependency walking out of one checkout into a sibling would fail on a fresh clone and in CI
+exactly as the npm one already does. Decide where the shared crates live, a fifth repository
+consumed by git tag or a monorepo, before writing a line of them.

simplify/.research/rust-google-sync.md

@@ -0,0 +1,438 @@
+# Google, OAuth, secrets, HTTP, sync and backup across the four apps
+
+Read directly off disk on 2026-09-06. Every claim below has a file and a line behind it. No secret
+values are reproduced anywhere in this file.
+
+Margin Docs (`rust/margin-editor`) is out of scope on the evidence: its `src-tauri/Cargo.toml` has
+no `reqwest`, no `chacha20poly1305` and no Google anything. It is the control case, and the only
+thing it shares with the other three is `library.rs`-shaped filesystem helpers.
+
+## The size of the thing
+
+| Package | Files | Lines |
+|---|---|---|
+| `margin-caledar/src-tauri/src/google/` | 5 | 2,258 |
+| `margin-mail/src-tauri/src/google/` | 10 | 6,077 |
+| `margin/src-tauri/src/gdrive.rs` | 1 | 953 |
+| `margin-mail/src-tauri/src/backup/` | 7 | 1,914 (1,264 without tests) |
+| `margin-caledar` sync + store | 9 | 3,784 (2,982 without tests) |
+| `margin-mail` sync + mirror + provider | 16 | 10,215 (7,210 without tests) |
+
+## The two OAuth implementations are one implementation
+
+Margin Mail's `google/auth.rs` opens by saying so: "ported from Margin Calendar's `google/auth.rs`,
+which took it from margin's `gdrive.rs`" (margin-mail auth.rs:1-4). The calendar's opens the same
+way about margin (margin-caledar auth.rs:1-7). This is not a family resemblance, it is a copy with
+edits, and it is measurable.
+
+Ignoring the `#[cfg(test)]` modules at the foot of each file:
+
+| File | Calendar lines | Mail lines | Calendar lines present verbatim in Mail |
+|---|---|---|---|
+| `google/auth.rs` | 899 | 1,146 | 810 (90%) |
+| `google/browser.rs` | 420 | 419 | 416 (99%) |
+| `google/secrets.rs` | 356 | 351 | 326 (92%) |
+| `src-tauri/build.rs` | 29 | 29 | 29 (100%) |
+
+1,552 of the calendar's 1,675 non-test lines exist unchanged in Margin Mail. `browser.rs`, which is
+the whole iOS `SFSafariViewController` and Android Custom Tab consent surface, differs in seven
+lines and all seven are comment prose about which app the sheet appears over.
+
+Everything below is identical in both, line for line:
+
+- PKCE: `random_b64`, `pkce_challenge` and the RFC 7636 test vector (calendar auth.rs:228-238 and
+  904-909, mail auth.rs:252-262 and 1170-1175).
+- The loopback listener: `write_http_message`, `Redirect`, `request_path`, `parse_redirect`,
+  `await_code`, the `CANCELLED` constant and the `access_denied` special case (calendar
+  auth.rs:244-374, mail auth.rs:307-437). Same 8 KiB buffer, same 150 ms poll, same 5 s read
+  timeout, same favicon skip.
+- Credentials loading: `CredentialsFile` with `installed` / `android` / `ios`, the `platform_client`
+  flag, the `YOUR_CLIENT_ID` sentinel check (calendar auth.rs:68-157, mail auth.rs:88-182).
+- Token endpoint: `TokenResponse`, `with_secret`, `exchange_code`, `refresh_access_token`,
+  `fetch_email` (calendar auth.rs:376-477, mail auth.rs:439-572).
+- `id_token` handling: parsed, never signature-verified, with the same justification that TLS
+  already proved it (calendar auth.rs:402-408, mail auth.rs:472-478).
+- Expiry and skew: `EXPIRY_SKEW_SECS = 60` and
+  `now() + expires_in.saturating_sub(EXPIRY_SKEW_SECS)` (calendar auth.rs:48 and 875, mail
+  auth.rs:61 and 1122). No clock-skew handling beyond that constant, in either.
+- `valid_access_token`, single-flight by holding the tokio mutex across the refresh await, with the
+  same paragraph explaining that this also serialises refreshes across accounts (calendar
+  auth.rs:846-877, mail auth.rs:1093-1124).
+- The deep-link path: `Pending`, `handle_redirect` taking rather than reading the verifier,
+  `abandon_pending`, `connect_by_deep_link`, `callback_scheme`, the 900 s mobile timeouts (calendar
+  auth.rs:204-210, 633-747; mail auth.rs:228-234, 807-923).
+- Multi-account model: `AuthState { sessions: Mutex<HashMap<String, Session>> }`, keyed on the
+  Google `sub` with the email as fallback (calendar auth.rs:214-219 and 799, mail auth.rs:238-243
+  and 975).
+- The build script that embeds `google-credentials.json` from `OUT_DIR`, falling back to the example
+  file so a fresh clone compiles.
+
+### What actually differs
+
+Six things, and they are the whole design space a shared crate has to leave open.
+
+1. **Scopes.** The calendar has one constant string (`SCOPES`, auth.rs:28). Mail has a six-entry
+   `BASE_SCOPES` array, a `REQUIRED_SCOPE` an account is refused for, `scope_string` for adding
+   extras, and `granted_scopes`/`missing_required` reading what Google actually granted back off the
+   token response (mail auth.rs:29-41, 274-305, 980-994). The calendar never reads the `scope` field
+   at all; its `TokenResponse` does not have one (calendar auth.rs:376-385).
+2. **Re-consent.** Mail has `grant()` (auth.rs:725-733) because installed apps get no incremental
+   authorization, so picking up `calendar.events` to answer an invite means the whole consent again.
+   The calendar never needs a second scope.
+3. **`login_hint` and `prompt`.** Mail's `auth_url` takes an optional hint and switches `prompt`
+   between `consent` and `select_account consent` accordingly (auth.rs:607-633). The calendar always
+   sends `select_account consent` (auth.rs:519-530).
+4. **Revocation.** The calendar's `revoke` discards the result (auth.rs:479-485). Mail's keeps it
+   and reports "the account was removed from this device, but Google could not be reached to revoke"
+   (auth.rs:584-598, 1086-1090). Mail also documents that one OAuth client covers the suite, so a
+   revoke signs the person out of every Margin app (auth.rs:1026-1029, google/mod.rs:53-56).
+5. **Where the account record lands.** The calendar writes a row through
+   `store::write::upsert_account` inside a SQLite store (auth.rs:806-808). Mail writes
+   `accounts.json` through `crate::accounts::upsert` (auth.rs:997-1003), because every account owns
+   its own database and the account list has to be readable before any of them is open
+   (accounts.rs:4-8).
+6. **HTTP body building.** Mail is on reqwest 0.13, where `.form()` sits behind a feature this build
+   does not enable, so it hand-rolls `form_body` over `url::form_urlencoded` (auth.rs:502-511). The
+   calendar uses `.form()` (auth.rs:438-444). This is the only place the version split shows up in
+   the auth code.
+
+Point 6 is worth naming as the pattern: the reqwest 0.12/0.13 gap has already cost Margin Mail three
+hand-written helpers that the other two get from the library (`form_body` auth.rs:505-511,
+`query_string` api.rs:723-729, `url_with` api.rs:732-738).
+
+## Secret storage
+
+`google/secrets.rs` is the same file twice. The whole diff is: the `SERVICE` and `KEY_CONTEXT`
+constants (calendar secrets.rs:31 and 34, mail secrets.rs:42 and 46), a `reference()` helper the
+calendar needs for its `accounts.keychain_ref` column and mail dropped, a `tempfile` in one test,
+and the chacha20poly1305 0.10 to 0.11 API change.
+
+The scheme itself, identical in both: an XChaCha20-Poly1305 blob at `tokens.enc` in the app data
+directory, one base64 entry per account id in a `BTreeMap`, a 32-byte per-install random salt at
+`tokens.salt`, and the key derived as `SHA256(KEY_CONTEXT || salt || machine_id)`
+(mail secrets.rs:101-119). `machine_id` is `/etc/machine-id` on Linux, `IOPlatformUUID` scraped out
+of `/usr/sbin/ioreg` on macOS, and deliberately empty on iOS and Android because the sandbox is the
+real boundary there and a reinstall would rotate the identifier (mail secrets.rs:128-189). Files are
+written 0600 from creation rather than chmodded afterwards (mail secrets.rs:236-239 doc comment).
+
+The "why not keyring" paragraph is near-identical in both `Cargo.toml` files (margin-caledar
+Cargo.toml:36-40, margin-mail Cargo.toml:61-64) and the long version is in the file headers
+(calendar secrets.rs:1-27, mail secrets.rs:1-28): macOS ties a keychain item's ACL to the code
+signature so every ad-hoc rebuild re-prompts, and `keyring` has no Android backend at all.
+
+**Version drift.** `chacha20poly1305 = "0.10"` in the calendar, `"0.11"` in mail. Mail carries the
+migration note (secrets.rs:208-211): 0.11 moved to `hybrid-array`, `Key::from_slice` and
+`XNonce::from_slice` are deprecated, and the array conversions now carry the length in the type, so
+the one panic those calls had is a compile error. The on-disk format is unchanged, so this is purely
+an API-surface difference and any shared crate should be on 0.11.
+
+Mail reuses this store for two things that are not OAuth tokens: the backup key under the id
+`"margin-mail backup key"` (backup/crypto.rs:41, 119-138) and the R2 credentials under
+`"margin-mail r2 credentials"` (backup/r2.rs:29). Both comments note that neither id can collide
+with an account id, because a Google `sub` is digits and an address cannot carry a space. That is a
+good sign for extraction: the module already works as a general sealed-key-value store and only its
+two constants are app-specific.
+
+## Credentials and the Google Cloud project
+
+The mechanism, in both mail and the calendar: `src-tauri/build.rs` copies
+`google-credentials.json` from the repo root into `OUT_DIR`, falling back to
+`google-credentials.example.json` when the real file is absent, and `auth.rs` pulls it in with
+`include_str!(concat!(env!("OUT_DIR"), "/google-credentials.json"))` (mail auth.rs:63, calendar
+auth.rs:50). So the client id and the desktop client secret are compiled into the binary. Nothing is
+read at runtime. A clone with no credentials compiles and fails at the first connect with the
+"not set up yet" sentence rather than failing to build (build.rs:8-10).
+
+Margin does it differently and worse. `gdrive.rs:41-42` builds a path from
+`CARGO_MANIFEST_DIR/../google-credentials.json` and tries to `fs::read_to_string` it **at runtime**,
+falling back to the `include_str!` copy only when that read fails. On a shipped app the path does not
+exist so the fallback always wins, but the build machine's absolute path is baked into the binary
+and a developer's on-disk file silently takes precedence over what was compiled.
+
+The three `google-credentials.json` files in `margin`, `margin-caledar` and `margin-mail` are
+byte-identical (same SHA-1). All three are `.gitignore`d and untracked; only the example files are
+committed. Margin additionally keeps the raw console download at its repo root, also ignored via a
+`/client_secret_*.json` rule (margin/.gitignore:31).
+
+So there is **one** Google Cloud project and **one** OAuth desktop client for the whole suite,
+copied into three repos by hand. Margin Mail's code knows this and says so on the revoke path
+(auth.rs:1026-1029). Margin's does not: `gdrive_disconnect` revokes the grant without telling anyone
+it has just signed them out of the calendar and the mail client too (gdrive.rs:776-803). The example
+files also differ: mail and the calendar carry `android` and `ios` blocks, margin's carries only
+`installed`.
+
+## margin's gdrive.rs, the third client
+
+It authenticates with the same flow, written independently and earlier. Same PKCE
+(gdrive.rs:159-169), same loopback listener (gdrive.rs:199-275, but inline in one 60-line function
+rather than the calendar's four testable pieces), same `exchange_code` / `refresh_access_token` /
+`fetch_email` (gdrive.rs:318-359), same `access_type=offline` consent URL (gdrive.rs:751-759). About
+330 of its 953 lines are the OAuth flow.
+
+What it does differently, in every case for the worse:
+
+- **The refresh token is stored in plaintext.** `BackupState.refresh_token` is a plain field
+  (gdrive.rs:71) serialised into `backup.json` with `serde_json::to_string_pretty` and written by
+  `crate::project::atomic_write` (gdrive.rs:153-157), which sets no file mode (project.rs:13-29).
+  The other two apps seal the same kind of token for the same grant. The weakest store in the suite
+  sets the real security level, so this is the one finding here I would act on before any
+  refactoring.
+- **No timeouts on the HTTP client at all**: `LazyLock::new(reqwest::Client::new)` (gdrive.rs:25).
+  The calendar's file header calls this out by name as fix number one (calendar auth.rs:1-4) and
+  nobody went back and applied it.
+- **No single-flight refresh**: `valid_access_token` reads the session, drops the lock, then awaits
+  the refresh (gdrive.rs:498-521), so N concurrent callers each fire their own. Fix number two in the
+  calendar's header, also never backported.
+- **No CSRF constant-time discipline and no `Redirect` enum**, so the state check and the error
+  paths are inline and untested. There are no tests in `gdrive.rs` at all; the calendar has nine and
+  mail has eighteen for the same code.
+- Its one advance on the calendar is that it reads the granted `scope` back and refuses a token
+  without `drive.file` (gdrive.rs:181-186, 522-532, 704-712). That idea survived into Margin Mail
+  as `granted_scopes` / `missing_required` and never reached the calendar.
+
+## HTTP clients
+
+Seven `reqwest::Client` constructions across the three apps, all different, none sharing a builder.
+
+| Where | connect | total | Other |
+|---|---|---|---|
+| margin gdrive.rs:25 | none | none | `Client::new()` |
+| margin updates.rs:6 | none | none | `Client::new()` |
+| calendar auth.rs:52-58 | 10 s | 30 s | nothing |
+| mail auth.rs:65-78 | 10 s | 30 s | h2 keepalive 20/10, tcp keepalive 30 s |
+| mail api.rs:86-108 | 10 s | 60 s | pool idle 30 s, h2 keepalive, tcp keepalive |
+| mail backup/r2.rs:40-45 | 10 s | 120 s | nothing |
+| mail attachments.rs:67-78 | 5 s | 10 s | `referer(false)`, redirects limited to 3 |
+| mail unsubscribe.rs:81-99 | 5 s | 20 s | `referer(false)`, same-host-only redirect policy |
+| mail imap/discover.rs:543-554 | 15 s | none | spoofed Chrome user agent, 3 redirects |
+
+Versions and features:
+
+- margin: `reqwest 0.12`, `default-features = false`, `rustls-tls`, `json` (Cargo.toml:39).
+- calendar: identical (Cargo.toml:29).
+- mail: `reqwest 0.13`, `default-features = false`, `rustls`, `webpki-roots`, `json`, `gzip`,
+  `http2` (Cargo.toml:37-43), justified as "gzip because Gmail's JSON compresses by an order of
+  magnitude and hydration is thousands of responses; http2 because a batch of 50 and the poll loop
+  share one connection".
+
+**User agent**: nothing sets one except `imap/discover.rs`, and that one is a Chrome spoof, which is
+deliberate for autodiscovery and wrong for anything else. All Google traffic from all three apps
+goes out as reqwest's default UA.
+
+**Retry, backoff, rate limits.** Only Margin Mail has any. `google/api.rs` carries the whole of it:
+
+- `ApiError` with seven variants, including `Dropped` for a connection that died mid-request as
+  distinct from `Offline` (api.rs:183-203, 233-246).
+- `error_for`, classifying 401 / 403-by-reason / 404 / 429 / 408 / 5xx, reading Google's reason out
+  of `error.status`, `error.errors[].reason` and `error.details[].reason` because a missing scope
+  only appears in the third (api.rs:341-440).
+- `strip_urls`, which drops whole sentences carrying a link out of an error message on the grounds
+  that a person reading a toast cannot follow one (api.rs:276-305).
+- `retry_after` (api.rs:443-452), truncated exponential `backoff_ms` with jitter capped at 64 s
+  (api.rs:612-636), `with_retry` and `with_retry_no_replay` for calls that must not be made twice
+  (api.rs:651-696), and a two-step fast retry for dropped connections (api.rs:642).
+- `Quota`: a per-account rolling 60-second ledger against Gmail's 6,000 units, with a per-call unit
+  table (api.rs:119-176, 496-607).
+
+The calendar has **none** of this. Its `error_for` maps 410 and 412 and sends everything else to
+`ApiError::Other` (margin-caledar api.rs:191-197). Grepping the whole calendar crate for `429`,
+`Retry-After`, `backoff` or `sleep` returns exactly one hit, and it is the 150 ms poll inside the
+loopback listener. A 429 from Google Calendar therefore reaches `push::drain`, is counted as a real
+attempt, and five of them retire the write permanently (calendar push.rs:29, 344-345, 375-381). That
+is a live bug, not a stylistic gap.
+
+## Sync engines: how much is really shared
+
+Both are honestly described as "incremental sync of a Google resource into a local SQLite mirror
+with a sync token, a poll loop and an event stream to the UI". That description is true of both and
+it is also where the similarity ends. I read both in full and I do not think a shared sync engine is
+the right conclusion.
+
+### What genuinely is the same
+
+The scaffolding, and it is the same to the line in places.
+
+- The poll loop. Spawn a task, first pass at `FIRST_PASS_SECS = 2`, then an interval chosen by
+  window focus (calendar sync.rs:39, 205-217; mail sync/mod.rs:51, 374-387). `fn focused(app)` is
+  byte-identical in both (calendar sync.rs:219-223, mail sync/mod.rs:389-393). Intervals differ
+  because the resources do: 60/300 s for the calendar, 12/60 s for mail, each with the unit cost
+  worked out in a comment.
+- The `Sink` trait, so a pass can run in a test with a recorder behind it instead of an `AppHandle`
+  (calendar sync.rs:69-78, mail sync/mod.rs:238-249). Both `AppSink`s emit `sync-progress` and call
+  `emit_store_changed`.
+- The connection-borrowing seam, with the same justification sentence in both files verbatim:
+  "Nothing inside may await: the guard is a std one, so holding it across a suspension point would
+  make the future non-Send" (calendar sync.rs:114-115, mail sync/mod.rs:220-221). The calendar has it
+  as a free function over `Store`; mail has it as a `Store` trait with a `Scoped` impl.
+- Push before pull, with the same reason ("a write that has just landed comes back as the server's
+  own row in the same pass rather than a tick later"): calendar sync.rs:135-136, mail engine.rs:3-4.
+- The budgets: 20 s for the outbox in a pass and 4 s at quit, in both (calendar sync.rs:42 and 44,
+  mail outbox.rs:30 and 32), with the same doc comment about racing the frontend's close-request
+  timeout.
+- Schema migration: a `meta` key/value table, a `schema_version` key, a refusal to open a database
+  written by a newer build, forward-only numbered steps inside a transaction (calendar
+  store/schema.rs:100-136, mail mirror/schema.rs:21-63). About 40 lines each, near-identical.
+- The webview event surface. Both apps emit exactly four events and they have the same names:
+  `store-changed`, `sync-progress`, `auth`, `menu-action`. `AuthEvent` is the same struct with two
+  extra fields in mail (calendar dto.rs:172-181, mail dto.rs:896-910). `SyncStatus` shares five of
+  its fields (calendar dto.rs:147-155, mail dto.rs:861-877).
+
+### What is not the same, and cannot be
+
+- **The cursor model differs in kind.** The calendar keeps one sync token per calendar in a column
+  (store/schema.rs:43) plus one `calendarList` token in `meta` keyed by account (pull.rs:26, 204).
+  Mail keeps one cursor per account database, which is Gmail's `historyId` (mirror/write.rs:29).
+- **Commit points are opposite.** The calendar cannot write anything until the page chain is
+  exhausted, because `nextSyncToken` only arrives on the final page, and it says so at length
+  (pull.rs:1-7, 136-171, 173-195: one transaction for the whole chain). An interrupted chain
+  restarts from the beginning. Mail commits the cursor as soon as the changes are on disk and
+  *before* hydration, deliberately (changes.rs:51-56), so a crawl that fails afterwards does not
+  re-read the change log.
+- **Recovery is opposite.** A 410 in the calendar drops that one calendar's rows and cursor and
+  re-syncs it alone (pull.rs:105-132). An expired history log in mail drops nothing: `reconcile`
+  lists the window into a TEMP TABLE and diffs it locally (changes.rs:141-228), because the mirror
+  holds decisions the state database is joined against and dropping it would be destructive.
+- **Mail has a two-phase fetch and the calendar has no use for one.** Ids, then metadata in batches
+  of 50, then bodies, with an `hydrated` column so an interrupted crawl resumes across restarts
+  (hydrate.rs:1-9, 22, changes.rs:69-92). `events.list` returns whole events, so this entire axis is
+  absent from the calendar.
+- **Conflict resolution is opposite.** The calendar sends `If-Match` and treats a 412 as a lost race
+  that is surfaced and never retried with the etag dropped, since dropping it is the clobber the
+  check exists to prevent (api.rs:310-332, 337-360; push.rs:5-8). Mail has no etag because Gmail has
+  none. Its writes are declarative ("say what the labels should be rather than what to do to them",
+  api.rs:649-650), which is exactly why they are safe to replay and the calendar's are not.
+- **Coalescing.** Mail folds consecutive writes to the same message set into one outbox row, per
+  field for flags and per label for labels (outbox.rs:63-190). The calendar does not, and its outbox
+  row carries `calendar_id`, `event_id`, `original_start`, `scope` and `etag` (store/schema.rs:75-87)
+  where mail's carries `op`, `payload`, `thread_key` and `hold_until` (mirror.sql:120-129).
+- **Failure policy.** Mail has a circuit breaker at four consecutive failures with a five-minute
+  cooldown, a quiet-first-failure rule, and per-error-kind chip wording (engine.rs:22-33, 190-228),
+  plus a body-cache poison set (engine.rs:65, 250-281). The calendar reports every failure.
+- **The provider seam is not the same seam.** Mail's `Provider` has fourteen methods and names no
+  Google type at all (provider/mod.rs:166-249). It has three implementations: Gmail
+  (gmail.rs:378), IMAP (imap/provider.rs:1439) and a 612-line fake. The calendar's `Transport` has
+  six methods and every one of them names a Google Calendar type in its signature
+  (`CalendarListPage`, `RawEvent`); it has one real implementation and a test stub
+  (transport.rs:15-62, tests.rs:60). So mail's is a provider abstraction and the calendar's is a
+  test seam. They look alike (both `impl Future + Send` on a `Sync` trait, no `async_trait`, and the
+  mail file says so: provider/mod.rs:13-14) and they are doing different jobs.
+
+### Verdict
+
+A shared OAuth crate is obviously right and the numbers support it without argument. A shared sync
+engine is not. What the two engines agree on is the shape around the work: how a pass is scheduled,
+how a store connection is borrowed, how progress reaches the webview, and what an outbox row's
+lifecycle looks like. That is worth perhaps 150 to 250 lines of traits and small helpers, and
+extracting it would buy consistency rather than deletion. The interiors have no overlap worth
+having: one syncs whole objects with etags against a per-collection token that can only be committed
+at the end of a chain, the other syncs ids then metadata then bodies against a per-account log with a
+quota accountant in the middle and a checkpoint halfway through.
+
+The more useful extraction on this side is not the engine at all. It is Margin Mail's
+`google/api.rs` error and retry layer: `ApiError`, `error_for`, `reasons`, `explain`, `strip_urls`,
+`retry_after`, `backoff`, `with_retry` and `Quota`. That is roughly 350 lines the calendar visibly
+needs and does not have, and moving it would fix the 429 bug above rather than merely deduplicating
+something.
+
+## Backup
+
+Two designs with almost nothing in common except the Drive verbs underneath.
+
+**margin's** is whole-file mirroring. `collect_local_files` gathers `*.margin` books and the custom
+dictionary (gdrive.rs:576-600), hashes each one, and uploads anything whose hash moved
+(gdrive.rs:810-835). `gdrive_sync` downloads any remote file that has no local counterpart and skips
+any that does, so the local copy always wins and there is no merge at all (gdrive.rs:877-884).
+Everything goes into one visible folder called `margin` at the root of the user's Drive under
+`drive.file`, which the publishing doc defends as deliberate (docs/publishing.md:131, 162-164).
+Nothing is encrypted; the books go up as they are.
+
+**Margin Mail's** is an append-only encrypted journal. Segments are 500 records each
+(backup/mod.rs:48), named `<account-hash>/<device-id>/<first>-<last>.seg` (mod.rs:76-78), where the
+account hash is a truncated SHA-256 of the address so a folder listing is not a list of somebody's
+email addresses (mod.rs:52-67). Each segment is sealed with XChaCha20-Poly1305 with its own name as
+additional authenticated data, so a store that reorders, replays or moves a segment gets a
+decryption failure rather than a wrong answer (backup/crypto.rs:60-105). Merge is a union rather than
+a conflict resolution, because a device only ever writes under its own sequence (mod.rs:179-181),
+and a pass reads before it writes so a mistyped phrase fails before it has added anything
+(mod.rs:131-133).
+
+The key comes from a 24-word BIP39 phrase through Argon2id at RFC 9106's second recommended profile,
+64 MiB, three passes, one lane (backup/phrase.rs:21-48). The salt is a constant and the file explains
+why: a second device has the phrase and nothing else, so every input has to be reachable from the
+phrase alone, and 256 bits from the wordlist is what is doing the work (phrase.rs:42-48). The phrase
+is shown once and never again, which `backup_phrase` enforces by refusing the second call
+(mod.rs:364-373). The derived key is sealed through `google::secrets`, deliberately reusing that
+module rather than reimplementing it (crypto.rs:107-117).
+
+The store is a three-method trait, `put` / `get` / `list` (backup/store.rs:20-30), chosen as the
+intersection of Drive's REST API and S3 so that a second implementation is an afternoon. There are
+two: Drive (backup/drive.rs, 172 lines) and S3 sigv4 signed by hand for R2 (backup/r2.rs, 426 lines,
+with the reasoning against `aws-sdk-s3` at r2.rs:10-13).
+
+**What the two share** is five HTTP functions. margin's `ensure_folder`, `find_file`,
+`list_in_folder`, `upload_file` and `download_file` (gdrive.rs:361-496) and Margin Mail's
+`ensure_folder`, `find_file`, `list_folder`, `upload` and `download` (google/drive.rs:100-256) are
+the same calls written twice. Mail's is better in five specific ways: it pages at 1000 rather than
+100 (drive.rs:176 against gdrive.rs:432), it escapes the Drive query language properly
+(drive.rs:47-49), it randomises the multipart boundary where margin hardcodes one string
+(drive.rs:74-78 against gdrive.rs:455), it percent-encodes the file id into the path
+(drive.rs:228-231), and it returns a classified `ApiError`.
+
+Both write into `margin` at the Drive root under `drive.file`, and both hold that as a constant in
+their own file (gdrive.rs:16, google/drive.rs:28). Mail nests itself at `margin/mail/` and its file
+header notes the architecture document had this wrong until recently (google/drive.rs:1-16). So the
+suite already has a folder convention that exists as two unrelated string literals.
+
+margin's docs do not contain a Drive backup spec. `docs/` has one file, `publishing.md`, and its
+only Drive content is the App Store entitlement justification at lines 131 and 160-170. The README
+is 13 lines and does not mention Drive.
+
+## Defects and drift found on the way
+
+1. **Margin Mail will not compile for mobile.** `lib.rs:307` calls `listen_for_redirects(handle)`
+   under `#[cfg(mobile)]` and that function is not defined anywhere in the crate. The calendar has
+   it (margin-caledar lib.rs:150-172). The call site was copied and the definition was not. Desktop
+   builds are unaffected, which is why it has not been noticed.
+2. **margin keeps a Google refresh token in plaintext** in `backup.json` (gdrive.rs:71, 153-157).
+   Same OAuth client and same grant as the two apps that seal theirs.
+3. **The calendar has no rate limit handling**, so a 429 is counted as a failed attempt and five of
+   them permanently retire a queued write (api.rs:191-197 with push.rs:29, 375-381).
+4. **margin's HTTP client has no timeouts** (gdrive.rs:25), which the calendar's own file header
+   identified as a bug in 2026 and never fixed upstream.
+5. **margin's `gdrive_disconnect` revokes the suite-wide grant silently** (gdrive.rs:776-803) where
+   Margin Mail names the consequence before offering the button (auth.rs:1026-1029).
+6. **`chacha20poly1305` 0.10 against 0.11** between the calendar and mail, with no on-disk format
+   difference. Any shared crate should be on 0.11.
+7. **`reqwest` 0.12 against 0.13**, which has already produced three hand-written helpers in Margin
+   Mail that the other two get from the library.
+
+## What I would extract, and what I would not
+
+**Extract, high confidence.** A `margin-google-auth` crate holding the PKCE flow, the loopback
+listener, the deep-link path, `browser.rs` whole, the credentials loader, the build script, the token
+endpoint calls, the session map and `valid_access_token`. That is around 1,550 lines that currently
+exist twice verbatim, plus roughly 330 more in `gdrive.rs` written independently and worse. It needs
+these as parameters rather than constants: the scope list and the required-scope rule, the app name
+for the listener page and the "not set up" sentence, the Android package scheme, and a small trait
+for "record this account", since one app writes a SQLite row and the other writes a JSON file.
+Whether `AuthEvent` gains mail's two extra fields for everyone or stays app-shaped is a taste call;
+mail's shape is a superset and costs the calendar two empty vectors.
+
+**Extract, high confidence.** A sealed-secrets module from `google/secrets.rs`, on
+chacha20poly1305 0.11, taking `SERVICE` and `KEY_CONTEXT` as parameters. 326 lines that exist twice
+and are already being used by Margin Mail as a general key-value store rather than an OAuth-specific
+one.
+
+**Extract, worth doing for the fix rather than the deduplication.** The Google error and retry layer
+from Margin Mail's `google/api.rs`. The calendar needs it and has nothing.
+
+**Extract, small and easy.** The five Drive verbs, the `margin` root folder constant, `app_data_dir`
+and `atomic_write`, and the `meta`-table schema migrator. None of these is large; all of them exist
+two or three times.
+
+**Do not extract.** The sync engine. Sharing the poll-loop scaffolding, the `Sink` trait and the
+connection-borrowing seam is defensible and would come to a couple of hundred lines. Sharing
+anything below that would mean building an abstraction over "a token per collection committed at
+the end of a chain, with etags" and "a log per account committed halfway, with declarative writes and
+a quota", and the abstraction would be larger and harder to read than either of the two engines it
+replaced.

simplify/.research/testing.md

@@ -0,0 +1,399 @@
+# Testing, fixtures and the dev harness across the four apps
+
+Scope: vitest and playwright config, the `tests/` suites and their helpers, `src/dev/` (the
+browser-against-fake-data harness), Rust fixtures and `#[cfg(test)]` conventions, the tsconfig
+split. Not build tooling, not CI beyond how it invokes tests.
+
+Paths: margin `/Users/pj/Workspace/projects/python/margin`, margin-calendar
+`/Users/pj/Workspace/projects/python/margin-caledar`, margin-docs
+`/Users/pj/Workspace/projects/rust/margin-editor`, margin-mail
+`/Users/pj/Workspace/projects/rust/margin-mail`. Cites are relative to those roots.
+
+## Findings first
+
+1. **margin has no tests of any kind.** Confirmed plainly: `package.json:5-12` has `dev`, `build`,
+   `preview`, `tauri`, `dmg`, `fonts:sync`, `fonts:check` and nothing else, and neither `vitest` nor
+   `@playwright/test` is a dependency. No `tests/`, no `src/dev/`, zero `*.test.ts` under `src/`,
+   zero `#[cfg(test)]` and zero `#[test]` under `src-tauri/src/`. Its `vite.config.ts` imports from
+   `vite`, not `vitest/config`, so there is no `test` block to add to, and its `src/ipc.ts` (43
+   lines) calls `invoke` directly behind an `isDesktop` early-return, so there is no seam a fixture
+   could plug into. Bringing margin into a shared harness is not a config change, it is building the
+   dev fixture it never had.
+2. **The three playwright configs are one file with the port swapped.** Diffing them leaves the port
+   (1430/1440/1450), two rewritten comments, and two real differences: margin-docs adds
+   `globalSetup: "./tests/identity.ts"` and drops `timezoneId`. Everything else is byte identical.
+3. **margin-docs is the only app that checks the dev server is serving its own checkout**, and all
+   three set `reuseExistingServer: true` on a fixed port. `tests/identity.ts` (106 lines) fetches
+   five source files over `?raw` and byte-compares them against disk. Its own header says the four
+   suites beside it "were happy to pass against anybody's copy". margin-calendar and margin-mail
+   still are.
+4. **The dev-mode invoke stub is the thing worth sharing and the three apps solved it three
+   different ways.** All three branch identically in `src/ipc.ts`, but margin-calendar fakes no
+   events at all, margin-mail fakes them as window `CustomEvent`s with an app-side bridge, and
+   margin-docs hand-rolls 97 lines of `__TAURI_INTERNALS__` inside a test helper so the real
+   `@tauri-apps/api` event plugin works in a plain tab. The third is the correct one and it is the
+   one that is not reusable, because it lives in `tests/disk.ts` rather than in `src/dev/`.
+5. **margin-docs has no shared spec helper at all.** 19 of 19 spec files define their own
+   `async function open()` and inline the same `margindocs-recents` localStorage seed.
+   margin-calendar and margin-mail both have `tests/app.ts`, and 33 of their 34 spec files import
+   `openApp` from it. Between those two, `contrastOf` (60 lines), `clockAt`, `MIDDAY`, `settle`,
+   `box` and `openDialog` are code identical and differ only in doc comments.
+
+## What each app has
+
+| | margin | calendar | docs | mail |
+| --- | --- | --- | --- | --- |
+| `test` script | none | `vitest run` | `vitest run` | `vitest run` |
+| `test:ui` script | none | `playwright test` | `playwright test` | `playwright test` |
+| `vitest` dep | no | 3.2.4 | 3.2.4 | 3.2.4 |
+| `@playwright/test` dep | no | 1.62.1 | 1.62.1 | 1.62.1 |
+| `src/dev/` | absent | 356 lines | 1,040 lines | 3,341 lines |
+| spec files / source-level tests | 0 | 10 / 131 | 19 / 116 | 24 / 252 |
+| colocated `*.test.ts` / tests | 0 | 12 / 211 | 32 / 655 | 8 / 81 |
+| Rust `#[test]` | 0 | 79 | 0 (all integration) | 531 |
+| `src-tauri/tests/` | no | no | 8 files + support | no |
+| `src-tauri/fixtures/` | no | no | no | 76 files |
+
+Source-level counts are `test(` and `it(` at file scope; several files wrap tests in a
+`for (const theme of ["light","dark"])` loop, so the run counts are higher. CI runs `pnpm test` and
+`cargo test` in all three (calendar `ci.yml:31,70`, docs `ci.yml:34,58,78`, mail `ci.yml:49,92`) and
+Playwright nowhere. `just test` is `pnpm test` plus `cargo test` and `just test-ui` is
+`pnpm test:ui`, the three justfiles agreeing line for line on both.
+
+## playwright.config.ts
+
+Shared by all three: `testDir: "./tests"`, `fullyParallel: true`, `retries: 0` (with the same
+comment in each saying a test that only passes on the second go is lying), `reporter: [["list"]]`,
+`outputDir: "node_modules/.cache/playwright"`, `timeout: 30_000`, `expect.timeout: 5_000`,
+`baseURL` off the port, `viewport: {1440, 900}`, `deviceScaleFactor: 1`, `locale: "en-GB"`,
+`trace: "retain-on-failure"`, `screenshot: "only-on-failure"`, a single project
+`{ name: "chromium", use: { browserName: "chromium" } }` with an identical comment explaining why it
+is not `devices["Desktop Chrome"]` (that device pins a Windows user agent and the keymap reads the
+platform off it), and a webServer block of `pnpm dev`, `reuseExistingServer: true`,
+`timeout: 60_000`, `stdout: "ignore"`, `stderr: "pipe"`.
+
+Differences, in full: port 1430 / 1440 / 1450; `timezoneId: "Asia/Kolkata"` in calendar
+(`playwright.config.ts:34`) and mail (`:31`) but not docs, because both anchor their fixture to the
+browser's local day; `globalSetup` in docs only (`:14`).
+
+No app configures `toHaveScreenshot`, `snapshotDir` or any visual-regression comparison, and there
+are zero snapshot baselines in the three. Every screenshot is a named PNG for a person or the docs.
+
+## The tests directories
+
+margin-calendar, 10 specs plus `app.ts` (370 lines) and `tsconfig.json`. Geometry and layout
+(`grid` 26, `compact` 5, `views` 8), input (`keyboard` 14, `interaction` 12, `touch` 22), form
+factor (`phone` 10), design-system (`legibility` 10), overlays (7), regression (`bugs` 17). The two
+phone files use `test.use({ viewport, hasTouch, isMobile })` at file scope (`touch.spec.ts:19`,
+`phone.spec.ts:16`) rather than a Playwright project.
+
+margin-docs, 19 specs plus `caret.ts` (134), `disk.ts` (144), `saving.ts` (52), `identity.ts` (106).
+Six of the 19 are `_audit*.spec.ts`, headed "Temporary exploration harness. Deleted once the
+findings are written down" (`_audit.spec.ts:1`) and still present. The rest are bytes-on-disk claims
+(`bytes` 11, `color` 7, `export-writes-only-the-pdf` 2, `external-changes` 8), editing (`blocks`,
+`headings`, `tables`, `clipboard`, `shortcuts`), and smoke (9).
+
+margin-mail, 24 specs plus `app.ts` (401 lines) and `tsconfig.json`. Roughly one spec per screen,
+plus `kit.spec.ts` (design system), `keyboard.spec.ts`, `guide.spec.ts` and `guide-shots.spec.ts`
+(asset generation, not assertion).
+
+### The helpers each invented
+
+`tests/app.ts` in calendar and mail is the same file with different measurement functions bolted on.
+Identical modulo doc comments:
+
+- `clockAt(hour, minute)` and `MIDDAY` (cal `:41-53`, mail `:46-58`), pinning the clock to the
+  current day at a fixed hour in Asia/Kolkata.
+- `openApp(page, options)` (cal `:61-90`, mail `:66-90`). Same `addInitScript` body, same
+  `__test-seeded` sentinel so a reload is not silently reset, same `page.clock.setFixedTime`. Only
+  the seed keys differ.
+- `settle(page)`, two `requestAnimationFrame`s (cal `:105-112`, mail `:99-106`, third copy in docs
+  `tests/caret.ts:46-53`), `box(target)` (cal `:114-124`, mail `:108-118`), and `openDialog(page)`
+  (cal `:288-293`, mail `:188-193`).
+- `contrastOf(page, selector)` (cal `:306-366`, mail `:219-278`), which composites every translucent
+  background between the element and the page through a 1x1 canvas so `oklch()` and `color-mix()`
+  do not read as transparent.
+
+App-specific and correctly so: calendar's `gridFit`, `axis`, `blocks`, `headerDates`, `hourY`,
+`columnX`, `drag`; mail's `rows`, `groups`, `paneMessages`, `paletteRows`, `actionBar`,
+`checkedRows`, `bodyText`, `toast`, `listScroll`, `place`, `openRow`.
+
+Two mail helpers are generic and belong in a shared package despite being written for mail:
+`token(page, name)` (`app.ts:180-185`), reading a CSS custom property off the root, and
+`failCommands(page, commands)` (`app.ts:343-360`), which uses `page.route` to answer the request for
+`/src/dev/mockIpc.ts` with a shim that forwards to the real module (`?real`) and rejects the named
+commands. That is the only way to test a failure path when the backend is in the page rather than on
+the wire, and it is 18 lines that would work unchanged in any of the four.
+
+margin-docs' helpers have no sibling: `putCaret`/`caretIsIn` (`caret.ts`), whose 28-line header
+documents why nothing in the suite presses End to move a caret; `watchDirty`/`dirtyWasShown`
+(`saving.ts`), a MutationObserver installed before typing so the 500ms autosave cannot be raced; and
+`installTauriShim`/`change`/`ask` (`disk.ts`), covered below.
+
+### Screenshot policy
+
+`page.screenshot` appears 33 times across 16 mail specs, 7 times across 4 docs specs (all in
+`_audit*`), and never in calendar. Mail writes into `screenshots/`, which is gitignored
+(`.gitignore:41`), so an ordinary run leaves the tree clean; the 10 pictures that ship inside the
+bundle go to the committed `public/guide/` and are gated by
+`test.skip(() => !process.env.GUIDE_SHOTS)` (`guide-shots.spec.ts:19-22`) behind
+`just guide-shots` (`justfile:28-30`). That two-tier rule is right and only mail has it.
+
+### Design-system assertions
+
+`mail/tests/kit.spec.ts` (132 lines) is the only design-system suite. It renders a `#/kit` route in
+both palettes and shoots it, asserts fixed geometry read from custom properties (`--list-w` is
+`420px`, a row is 46px, an avatar 30x30), then runs three static source scans with `node:fs`: no hex
+literal in any stylesheet under `src/ui` or `src/screens`, every `<input>` carries `NO_AUTOFILL` or
+an explicit `autoComplete`, and no file says "keychain".
+
+calendar's equivalent is runtime rather than static: `legibility.spec.ts` measures contrast, checks
+no block reads "Untitled" and checks every block has a non-empty accessible name, over both themes.
+docs' equivalent is a vitest, not a spec: `src/theme.test.ts` reads three stylesheets (including
+`node_modules/margin-shared/css/tokens.css`, `:18-22`) plus `index.html`'s pre-bundle boot script
+and asserts all of them declare the same variable set, because a missing dark variable falls back
+silently to the warm light value in `:root`. Nothing anywhere asserts anything about icons.
+
+## src/dev: the invoke stub
+
+All three apps switch dev mode on the same way, in `src/ipc.ts`:
+
+```ts
+export function call<T>(command: string, args?: Record<string, unknown>): Promise<T> {
+  if (import.meta.env.DEV && !isTauri) {
+    return import("./dev/mockIpc").then((m) => m.mockCall<T>(command, args));
+  }
+  return invoke<T>(command, args);
+}
+```
+
+calendar `ipc.ts:192-197`, docs `ipc.ts:288-292`, mail `ipc.ts:748-752`, byte identical bar the
+comment. `isTauri` is `"__TAURI_INTERNALS__" in window`, computed once at import time, and all three
+derive `isDesktop`, `isMacDesktop` and `live()` from it with the same comments verbatim (calendar
+`:9-40`, docs `:9-40`, mail `:10-34`). There is no environment variable and no dev-only build flag:
+the switch is "DEV build with no Tauri bridge", so `pnpm dev` in a browser and Playwright get the
+fixture and the packaged app cannot.
+
+`mockCall` is a `switch (command)` in all three, returning `as unknown as T` at every arm and
+throwing on an unknown command (calendar `mockIpc.ts:131-132`, "dev mock has no handler for"). There
+is no type link between a command name, its arguments and its return; calendar casts args to
+`Record<string, never>` (`:41`) and then to the real type per field. Command counts: calendar 12
+arms, docs 40, mail roughly 180. State is a mutable copy of the fixture taken at module load, so
+writes persist for the session and a reload resets (calendar `:11-14`, docs `:48-49`, mail `:72-84`).
+
+### Fixtures
+
+`src/dev/fixture.ts` in each. calendar (222 lines) exports `devAccounts`, `devCalendars` and
+`devInstances(from, to)`, generated from a seed table and anchored to the current week; its header
+records that it is modelled on a real sync of 12,067 events where 90% came back with no summary.
+docs (344 lines) exports `devRoots`, `devEntries` (an in-memory folder with real base64 PNG, SVG and
+PDF bytes at `:208-273`) and path utilities the mock and the app both use. mail (1,572 lines)
+exports 20 symbols, 13 data tables (`devAccounts` through `devSyncStatus`) and 6 functions
+(`devDiscover`, `devCert`, `devFiles`, `devContacts`, `groupOf`, `categoryOf`).
+
+A fourth fixture source in docs has no sibling: `src/markdown/corpus/`, loaded through
+`import.meta.glob("./*/*.md", { query: "?raw", eager: true })` at `corpus/load.ts:20`. Its header
+records the bug that motivated the glob, that naming folders explicitly left twenty adversarial
+files inside the corpus but outside every gate reading it. That is the "add a file, get a test"
+pattern and it is worth generalising.
+
+### Dev flags
+
+localStorage, read defensively inside try/catch. calendar has one, `margincal-dev-empty`
+(`mockIpc.ts:32-38`); docs has one, `margindocs-dev-no-writing-tools` (`:246-252`); mail has eight,
+`marginmail-dev-` plus `empty`, `crowd`, `notify`, `imap`, `bridge`, `pending`, `hydrate-fails`,
+`sync-fails`, read through `firstRun()` (`:220-230`) and a generic `flagged(key)` (`:262-268`). The
+naming is uniform (`<app>-dev-<thing>`) and the reader is the same eight lines three times over.
+
+### Faking events, three ways
+
+This is where the three diverge and where the shared design has to be decided.
+
+calendar does not fake events at all: `App.tsx:52` is `if (!isTauri) return;` before every `listen`,
+so in a browser `menu-action`, `auth`, `sync-progress` and `store-changed` never arrive, and
+anything they drive is unreachable from the Playwright suite.
+
+mail dispatches window `CustomEvent`s under the same names from inside the mock
+(`mockIpc.ts:237-241`), with an optional delay so a state that would otherwise last one frame is
+observable (`narrateFirstSync` at `:637-651` walks a five-step sync over 1,250ms). The app side is
+`onAppEvent` in `App.tsx:69-77`, seven lines picking `listen` or `window.addEventListener` off
+`isTauri`. Cheapest correct answer, and confined to mail.
+
+docs does neither. Its mock exports `external` (`mockIpc.ts:619-696`), a second surface that mutates
+the fixture the way another program would, behind the app's back, and returns the exact
+`WatchEvent[]` the Rust watcher would have emitted; putting them on the bus is the caller's job.
+That caller is `tests/disk.ts:37-133`, which installs a hand-rolled `__TAURI_INTERNALS__` at
+document start: `invoke`, `transformCallback`, `unregisterCallback`, `runCallback`, the
+`plugin:event|listen` and `|unlisten` commands, a listener map, `metadata`, `convertFileSrc` and
+`__TAURI_EVENT_PLUGIN_INTERNALS__.unregisterListener`. Its comment at `:29-36` says this is
+deliberately not `@tauri-apps/api/mocks`, which cannot be reached from an init script, and
+deliberately written to the contract rather than to convenience. `emit` returns a delivery count per
+event so a test can tell a working subscription from a payload that fell on the floor (`:66-75`).
+`external` also carries `pauseWrites`/`resumeWrites` (`:679-695`) so a save can be held and a buffer
+kept dirty instead of racing the 500ms autosave.
+
+The docs approach is the strictly better one: the app runs the real `@tauri-apps/api`, so the
+`isTauri` branch that ships is the branch under test, where mail leaves `onAppEvent`'s Tauri arm
+never exercised in a browser. But it is 97 lines in a test helper, so a person running `pnpm dev` by
+hand gets no events at all.
+
+## The Rust side
+
+margin-mail `src-tauri/fixtures/` is 36 `.eml` files (real messages as they come off the wire, CRLF
+throughout, half of them not UTF-8), 36 matching `golden/*.txt` and 4 `autoconfig/*.xml`, compiled
+into the test binary by a `corpus!` macro in `src/fixtures.rs:10-19` that emits one `include_bytes!`
+const per file plus an `all()` returning every pair, so a sweep over the corpus is one call.
+`fixtures.rs:58-102` is itself a test: every fixture has a header/body break, no bare LF, a
+plausible date and a parseable From. Nothing is generated at test time.
+
+Alongside it, `src/provider/fake.rs` (612 lines, `#![cfg(test)]` at `:15`) is an in-memory mailbox
+implementing the `Provider` trait: real ids, labels, dates and raw bytes, paging, a history log, and
+scripted failures via `fail_next` and `withhold_body`. `provider/mod.rs:1-14` records that this is
+the only reason the sync engine is testable without credentials.
+
+Nothing comparable exists elsewhere. margin-docs builds its Rust fixture at runtime instead:
+`src-tauri/tests/support/notes_repo.rs` (339 lines) creates a real git repository per test binary,
+copies 12 documents out of `src/markdown/corpus/real` so there is one corpus and not two, and
+generates 13,000 files under a vendored `node_modules` because several tests need a folder large
+enough that skipping it beats walking it. `git status` is the oracle.
+
+Conventions differ and both are defensible. calendar and mail put tests in `#[cfg(test)] mod tests`
+beside the code, 6 files / 79 tests and 54 files / 531 tests; fifteen of mail's are large enough to
+live in a sibling `<module>/tests.rs` (backup, clips, contacts, decisions, drafts, exports, invites,
+notify, piles, screener, send, snooze, state, sync, unsubscribe). docs has zero `#[cfg(test)]` and
+eight integration binaries totalling 4,210 lines, one needing `--test-threads=1` and run as its own
+CI step (`ci.yml:78`). Eight mail tests carry `#[ignore]`, six of them "hits the network" in
+`imap/discover.rs`.
+
+## tsconfig
+
+The app `tsconfig.json` is `"include": ["src"]` in all four, so `tests/` is excluded by omission
+rather than by an `exclude` entry, and the colocated `src/**/*.test.ts` files sit inside the app's
+own type check. `tests/tsconfig.json` exists in the three and is the same nine options each time
+(ES2022, bundler resolution, strict, noUnusedLocals, noUnusedParameters, skipLibCheck, noEmit) with
+`"include": [".", "../playwright.config.ts"]`. Mail's adds `"types": ["node"]`. Nothing runs `tsc -p
+tests/tsconfig.json` in any script or CI job, so the spec files are type checked only by an editor.
+
+Vitest config lives in `vite.config.ts` under `test:`, all three with
+`include: ["src/**/*.test.ts"]` and `environment: "node"`. No jsdom, no happy-dom, no
+`@testing-library/*` anywhere. margin-docs adds `maxWorkers: "50%"` and three 30-second timeouts
+with a 20-line comment explaining that a CPU-blocking markdown sweep cannot answer vitest's
+`onTaskUpdate` RPC while it runs.
+
+## Colocated unit tests: what they are and are not
+
+They test pure functions in a node environment. No component is rendered, no store is mounted
+against a DOM, nothing goes near `mockIpc`. Calendar's convention is explicit: a component `X.tsx`
+gets a sibling `XModel.ts` holding the decisions and `XModel.test.ts` tests that module.
+`GridModel.test.ts` covers `busyHours`, `heldHours` and `bandAt` over synthetic `Placed` values with
+`instance: {} as Instance`, because only the times matter; `EventDetailsModel.test.ts` covers
+popover placement against a fixed `Bounds`; `overlayModel` and `QuickCreateModel` cover date
+arithmetic and draft construction; `AgendaModel` covers grouping, gap labels and search matching.
+The odd one out is `EventDetailsHtml.test.ts`, half readability and half hostile input, because the
+description string comes off the wire from whoever created the event.
+
+margin-mail's eight follow the same rule. `providers.test.ts` tests the routing decision for an
+address twice over, by domain and by what discovery found; `useSync.test.ts` the two pure decisions
+the header and toast make from a `SyncStatus`; `guide.test.ts` link-checks the article library
+without rendering it; the other five are table checks.
+
+margin-docs' two named ones are a different genre and the more interesting one. `theme.test.ts` and
+`width.test.ts` both read source with `node:fs` and assert that two tables not written in the same
+language agree: theme against three stylesheets and a boot script, width against the command table
+and the subscription joining them. The other 30 are the markdown bridge and are app-specific.
+
+None of them snapshot, mock `call()`, or configure coverage, and there is no property-based library
+(though `typst.test.ts` and the five `adversarial*.test.ts` files are hand-rolled corpus sweeps,
+which is the same idea).
+
+## Known-failing specs
+
+Nothing in any repo records a known failure. The only markers are `guide-shots.spec.ts:19` (an
+intentional env gate, not a failure) and a `test.fail` at `external-changes.spec.ts:320`, kept so it
+would turn red the day the defect was fixed. `margin-editor/docs/conventions.md:74` is the standing
+rule: "Never weaken, skip or delete a test to reach green."
+
+The four margin-mail browser failures recorded in session memory are written down nowhere in the
+tree. If they are real that is the gap: either a per-app `tests/known-failures.md` or annotations on
+the specs, because right now the only record is a chat log.
+
+## What a shared harness package would contain
+
+`margin-shared` already exists at `margin/shared` and is consumed by margin and margin-docs by
+relative `file:` path, and by margin-mail. margin-calendar does not depend on it at all. Adding a
+`./test` subpath export is the least-friction home; a separate package means a fourth `file:` edge.
+
+**1. A playwright config factory.** Everything in the three configs bar the port is a default, so
+the whole file becomes `export default marginPlaywrightConfig({ port: 1450, witnesses: ["src/ipc.ts",
+"src/dev/mockIpc.ts", "src/dev/fixture.ts"] })`. `witnesses` turns the docs identity check on for
+every app rather than one, with the factory supplying `globalSetup` so no app wires it. `timezoneId`
+defaults to `Asia/Kolkata` and docs passes null. Saves roughly 45 lines per app and makes "all three
+run at 1440x900 with retries 0" a fact rather than a coincidence.
+
+**2. The dev backend, with a typed command registry.** Replace `switch (command)` with a table keyed
+by command whose handlers are typed off the DTO types `src/ipc.ts` already declares:
+
+```ts
+export const backend = defineBackend({
+  accounts_list: () => (firstRun() ? [] : accounts),
+  thread_view: ({ key }: { key: string }): ThreadView => viewOf(byKey(key)),
+});
+export type Command = keyof typeof backend;
+```
+
+`defineBackend` returns `{ mockCall, has, commands }`, with `mockCall` throwing the existing "no
+handler for" error on a miss. The win is that the arg cast at every arm and the `as unknown as T` at
+every return both disappear, and a command in `dto.rs` with no handler becomes checkable rather than
+a runtime surprise three screens later. Alongside it: `makeCall(loader)` producing the `call()` in
+`src/ipc.ts`, already identical in three places, and `devFlag(name)` replacing the three copies of
+the try/catch localStorage reader.
+
+**3. The Tauri shim, moved from `tests/` into the shared package and made the default.** Lift
+`installTauriShim` out of docs' `tests/disk.ts:37-133` unchanged, parameterise the backend module
+specifier, and expose it both as a Playwright init script (what docs does now) and as a dev entry
+point so `pnpm dev` in a browser gets real Tauri events too. Then `onAppEvent` (mail
+`App.tsx:69-77`) is unnecessary and the app runs one code path in both environments. This is the
+highest-value item in the audit: 97 lines that took real care to get right, written to a contract
+rather than to convenience, and two of the three apps are the poorer for not having it. With it,
+`emitEvent(page, name, payload)` and the delivery-count return become shared, and mail's
+`narrateFirstSync` style of timed multi-step event script becomes a shared `script([...])`.
+
+**4. Fixture loading.** Two patterns, both generalisable: docs' `import.meta.glob` corpus loader
+(`corpus/load.ts`) as `loadCorpus(glob)`, and mail's `corpus!` macro (`fixtures.rs:10-19`) as a
+shared Rust macro crate. Both encode the rule that adding a file puts it inside every sweep. Also
+shared: `mutableCopy(fixture)` for the clone-at-module-load idiom in all three mocks, and
+`undoLedger()` for mail's `undoable`/`runUndo` (`mockIpc.ts:292-314`), which any app with an undo
+toast will want.
+
+**5. Playwright helpers.** `settle`, `box`, `clockAt`, `MIDDAY`, `openDialog`, `token`,
+`failCommands`, plus `makeOpenApp({ theme: "marginmail-theme", pane: "marginmail-pane" })` returning
+an `openApp`, since only the seed keys differ between the two that have one.
+
+**6. Assertions on tokens and icons.**
+
+```ts
+expectNoColourLiterals(root, ["src/ui", "src/screens"]);   // mail kit.spec.ts:82-96
+expectThemesAgree(sheets, bootScript);                     // docs theme.test.ts
+expectTokens(page, { "--list-w": "420px" });               // mail kit.spec.ts:62-67
+expectContrast(page, selector, { min: 4.5 });              // cal legibility.spec.ts
+expectAccessibleNames(page, selector);                     // cal legibility.spec.ts
+expectIconsInSet(root, dirs);                              // does not exist yet
+```
+
+The first two are static scans over source and need no browser, so they can run under vitest in an
+app with no Playwright, which is how margin gets its first test.
+
+## What stays per app
+
+Every measurement helper: calendar's `gridFit`, `axis`, `blocks`, `hourY`, `drag`; mail's `rows`,
+`groups`, `paneMessages`, `paletteRows`, `actionBar`, `toast`; docs' `putCaret`, `caretIsIn`,
+`watchDirty`. They read app-specific class names and encode app-specific timing, so sharing them
+would be indirection over one caller each.
+
+The fixtures themselves, and every spec file. A calendar of 12,067 events, a folder of markdown and
+a mailbox of threads have nothing in common but the loading mechanism.
+
+The Rust test convention. Mail's `#[cfg(test)] mod tests` beside the code and docs' integration
+binaries are both right for their shape, and forcing one on the other buys nothing. The shareable
+parts there are narrower: the `corpus!` macro and a `TempRepo` builder along the lines of
+`support/notes_repo.rs`.

simplify/.research/typesetting-and-text.md

@@ -0,0 +1,430 @@
+# Typesetting and text: what margin and margin-docs actually share
+
+Scope: the Typst PDF pipeline, fontdb loading, NSSpellChecker, Apple Writing Tools, harper-core
+grammar, and the frontend that drives all of it. Four apps were checked. margin-calendar has none
+of this: no typst, no fontdb, no harper, no NSSpellChecker in
+`/Users/pj/Workspace/projects/python/margin-caledar/src-tauri/Cargo.toml`. margin-mail has exactly
+one fingerprint, a fontdb family list. So this is a two-app problem between margin and margin-docs,
+with one eight-line cameo from mail.
+
+Method for the percentages below: comments and blank lines stripped, then a longest-common-
+subsequence over the remaining lines. "Identical in order" means the same line, same order, both
+files.
+
+## The headline
+
+Nothing in either Rust tree is a copy that could be lifted as-is. Every pair started as a copy and
+then one side moved. margin-docs is ahead on all six Rust files and on four of the six frontend
+ones, and in three places margin is not merely behind but carries a bug that margin-docs already
+found, wrote a paragraph about, and fixed. The duplication that is worth extracting is small and
+boring; the duplication that is expensive is the divergence, and a shared crate is the only thing
+that would have stopped it.
+
+Both Cargo.lock files pin the same graph: harper-core 2.5.0, typst 0.14.2, fontdb 0.23.0,
+burn-cuda 0.19.1, cubecl-cpu 0.8.1, 964 packages in margin and 962 in margin-docs. Two copies of a
+960-package dependency graph resolved to the same versions by hand.
+
+## PDF export
+
+`margin/src-tauri/src/pdf.rs` is 129 lines, 116 of code.
+`margin-editor/src-tauri/src/pdf.rs` is 455 lines, 275 of code.
+Identical in order: 37 lines, 31% of the smaller file.
+
+Truly byte-identical, verified with diff:
+
+- Diagnostic formatting. `margin/src-tauri/src/pdf.rs:114-129` and
+  `margin-editor/src-tauri/src/pdf.rs:440-455` are the same 16 lines, character for character. Only
+  the function name differs (`format_source_diagnostics` against `format_diagnostics`). Severity to
+  string, message, hints indented two spaces, joined by newline.
+- The compile call shape. `Warned { output, warnings } = engine.compile()` then
+  `typst_pdf::pdf(&document, &Default::default())`: margin pdf.rs:78-81, docs pdf.rs:272-281.
+- The bundled-family dispatch. Same four ids (`eb-garamond`, `lora`, `source-serif`, `fraunces`)
+  mapping to the same eight `include_bytes!` of `../../public/fonts/*-VF.ttf`: margin pdf.rs:22-35,
+  docs pdf.rs:52-82. Same list, different shape (`&[&[u8]]` statics in both, arranged differently).
+
+Everything else has diverged, and the direction is one-way.
+
+**Font strategy is where the drift costs the user a PDF.** margin loads the variable files for
+Literata and Hanken and hands them to Typst (pdf.rs:9-20, 57-62). margin-docs cut nine static
+instances into `margin-editor/src-tauri/fonts/` and loads those (pdf.rs:32-42), with the reason
+written at pdf.rs:24-31: Typst does not support a variable axis, warns that it does not, and lays
+out at the default instance regardless of the weight asked for. So in margin every heading, every
+bold run and every callout label exports at weight 400. margin-docs' PDFs have the hierarchy the
+author sees on screen; margin's do not. margin-docs even documents the residual caveat for the
+other four families (pdf.rs:44-51), which margin has never noticed. This is the single largest
+quality gap found anywhere in this audit, it is 1.6M of static cuts plus a PROVENANCE.md, and it
+exists in one repo only.
+
+Present in margin-docs, absent from margin:
+
+- A vendored mitex 0.2.5 served on `/mitex/` as static source files, with a wasm binary
+  (pdf.rs:84-98), a stand-in `lib.typ` for a second attempt (pdf.rs:105-113), and the two-pass
+  compile that uses it (pdf.rs:344-379). A formula mitex cannot parse degrades to literal source
+  instead of killing the export.
+- Placeholder images, one per format Typst picks from an extension (pdf.rs:115-144), so an
+  unreadable image is a gap rather than a failed export.
+- A root-guarded filesystem read for images with no inline bytes (pdf.rs:146-163, calling
+  `fs::resolve_in_roots`). margin's `ImageInput.data` is a mandatory base64 string (pdf.rs:37-41)
+  and there is no file path in the protocol at all, so margin has no exposure here but also cannot
+  export an image it does not already hold in memory.
+- The font preamble, written in Rust because only Rust knows which families were found
+  (pdf.rs:165-194). Note pdf.rs:176-181: Typst sets every equation in "New Computer Modern Math"
+  with fallback off, so on a machine without it one formula is a hard compile error. margin has no
+  math and no monospace preamble at all.
+- Warning aggregation with counts and a `kind` (pdf.rs:196-244 plus `PdfWarning` in dto.rs:217-222).
+  margin emits one joined string on the same `pdf-warnings` event (pdf.rs:100-102).
+- `pdf_write` with the guard that refuses to overwrite a markdown or text file (pdf.rs:411-437).
+
+The escaping boundary is on the frontend in both, covered below.
+
+## Font loading
+
+`margin/src-tauri/src/fonts.rs` is 47 lines, 43 of code.
+`margin-editor/src-tauri/src/fonts.rs` is 182 lines, 113 of code.
+Identical in order: 17 lines, 39% of the smaller.
+
+The three-way duplication is here and it is trivially extractable. Listing every installed family
+is the same eight lines in three crates:
+
+- `margin/src-tauri/src/fonts.rs:11-18` (`list_system_fonts`)
+- `margin-editor/src-tauri/src/fonts.rs:160-167` (`fonts_list_system`), byte-identical to margin's
+- `margin-mail/src-tauri/src/settings.rs:180-188` (`system_fonts`), the same algorithm with
+  `system_db()` inlined and `names` renamed to `families`
+
+All three do `db.faces()`, `families.first()`, clone the name, sort, dedup. All three are
+`#[tauri::command(async)]`. mail is on fontdb 0.24 (`margin-mail/src-tauri/Cargo.toml:70`), the
+other two on 0.23. Nothing in this function changed between those versions.
+
+The per-family loader is the second shared piece: the same four `(Weight, Style)` pairs, the same
+`Query { families: &[Family::Name(family)], weight, style, ..Default }`, the same
+`with_face_data(id, |data, _| data.to_vec())`. margin fonts.rs:21-46, docs fonts.rs:69-95.
+
+Two drifts, both in margin-docs' favour:
+
+- Deduplication key. margin dedups by `fontdb::ID` (fonts.rs:30, 39), which is per face. docs dedups
+  by source file path (fonts.rs:55-61, 88). `with_face_data` hands back the whole file, so a `.ttc`
+  holding regular, italic, bold and bold-italic is read and shipped to Typst four times by margin
+  and once by docs. On a system family that is a collection, margin sends four copies of the same
+  multi-megabyte blob across the compile.
+- The whole `Fallbacks` machinery (fonts.rs:19-42 for the family lists, 97-143 for the collection)
+  has no counterpart in margin. margin names no monospace and no math family, so a code block or a
+  formula in a margin export gets whatever Typst defaults to.
+
+One correction worth carrying into any shared crate: the comment at
+`margin-editor/src-tauri/src/fonts.rs:84-86` says fontdb "answers a query with its closest match
+rather than with nothing, so a family that is not installed comes back as some unrelated face".
+That is not what fontdb 0.23 does. `Database::query`
+(`~/.cargo/registry/src/index.crates.io-*/fontdb-0.23.0/src/lib.rs:661-679`) filters candidates by
+exact family-name equality and returns `None` when the list is empty. The `installed()` guard at
+fonts.rs:88 therefore cannot fire, and since it compares case-insensitively while the query compares
+exactly, it is strictly weaker than the filter that already ran. It is live and useful at
+fonts.rs:139, where it is asked about `db.faces()` directly. Harmless dead code, but the comment
+would mislead whoever writes the shared version.
+
+## Spellcheck
+
+`margin/src-tauri/src/macspell.rs` is 73 lines, 68 of code.
+`margin-editor/src-tauri/src/macspell.rs` is 162 lines, 82 of code.
+Identical in order: 49 lines, 72% of the smaller. This is the closest pair in either Rust tree.
+
+`utf16_to_codepoint` is byte-identical, 12 lines: margin macspell.rs:14-25, docs macspell.rs:54-65.
+
+`check` is the same function with three changes. Both build the NSString, ask
+`checkString_range_types_options_inSpellDocumentWithTag_orthography_wordCount` for
+`Spelling | Link`, skip non-spelling results, map both ends of the NSRange through the table, cut
+the word out of the caller's own `chars`, and take at most five guesses.
+
+- margin filters against an in-process custom word set (macspell.rs:55-57) because it keeps its own
+  dictionary file. docs has no custom set: learning writes to the system
+  (`macspell.rs:143-162`, `learn` and `unlearn`, absent from margin entirely).
+- docs names its constants (`MAX_SUGGESTIONS`, `NO_DOCUMENT` at macspell.rs:40-45); margin inlines
+  `5` and `0`.
+- The end-offset clamp. margin: `map[(range.location + range.length).min(len)]` (macspell.rs:53).
+  docs: `map[range.location.saturating_add(range.length).min(len)]` (macspell.rs:107). The add
+  happens before the clamp in margin, so an NSRange carrying `NSNotFound` as its location panics in
+  debug and wraps in release. Small, real, and already fixed once.
+
+margin returns a local `MacIssue` (macspell.rs:7-12); docs returns the shared `SpellIssue` from
+dto.rs:179-185. Same four fields.
+
+docs also has `spell.rs` (95 lines, 28 of code), a platform shim giving the frontend four commands
+on every target with a `no_checker` module for non-macOS. margin has no equivalent; its
+non-macOS path is `#[cfg]` branches inside `proofing.rs` (proofing.rs:91-96, 105-166, 232-238) plus
+a bundled 550K SCOWL Hunspell dictionary under `margin/src-tauri/resources/dictionaries/en/`.
+
+## Apple Writing Tools
+
+`margin/src-tauri/src/writingtools.rs` is 81 lines, 68 of code.
+`margin-editor/src-tauri/src/writingtools.rs` is 146 lines, 83 of code.
+Identical in order: 42 lines, 61% of the smaller.
+
+Byte-identical, verified: `submenu_named` and `edit_menu` together, 21 lines. margin
+writingtools.rs:10-30 against docs writingtools.rs:23-43. `writing_tools_menu` is the same
+one-liner in both (margin:32-34, docs:45-47). That is the entire AppKit menu-walking layer, and it
+is the cleanest candidate for extraction in the whole audit: it takes a `MainThreadMarker` and a
+title and it knows nothing about either app.
+
+The divergence is a deliberate disagreement, and it is documented. margin puts Shift+Option+F and
+Shift+Option+R on Apple's own Proofread and Rewrite rows (writingtools.rs:8, 36-49). margin-docs
+refuses to, and writingtools.rs:85-91 says why: AppKit performs a key equivalent by firing the menu
+item directly, so a chord on the system's row reaches Writing Tools without passing the selection
+guard in `src/editor/writing.ts`, and that guard is refusing selections that corrupt the file. docs
+puts the chords on its own Edit rows instead. margin has no such guard, so it is not currently
+wrong for margin, but the reasoning is the sibling's and margin has never seen it.
+
+docs also adds an availability probe: a `SUBMENU_SEEN` atomic set at setup (writingtools.rs:13-14,
+92-95) and a `writing_available` command (106-120), so the frontend can say the machine has no
+Apple Intelligence instead of offering a button that does nothing. margin's `perform` returns `()`
+and silently no-ops when the row is missing (writingtools.rs:51-61); docs' returns
+`Result<(), String>` with three distinct messages (58-73).
+
+One manifest oddity: `margin/src-tauri/Cargo.toml:57` asks for the `NSWritingToolsCoordinator`
+feature of objc2-app-kit and nothing in margin uses it. margin-docs names exactly that in a comment
+at `margin-editor/src-tauri/Cargo.toml:67`.
+
+## Grammar
+
+margin has one module doing spelling, grammar and the custom dictionary:
+`margin/src-tauri/src/proofing.rs`, 275 lines, 239 of code. margin-docs splits the same work three
+ways: `grammar.rs` (128 lines, 58 of code), `spell.rs` (95 lines, 28), `macspell.rs`.
+
+Comparing the harper parts only, `proofing.rs` against `grammar.rs`: 33 lines identical in order,
+56% of the smaller.
+
+`build_harper` is the same five lines of code in both, margin proofing.rs:98-103 and docs
+grammar.rs:41-47: `FstDictionary::curated()`, `LintGroup::new_curated(dict.clone(),
+Dialect::American)`, `set_rule_enabled("SpellCheck", false)`. Same reasoning in both, that the
+system checker does spelling better.
+
+`collect_grammar` is the same walk: `Document::new_plain_english(text, dict)`, iterate lints, slice
+`existing` out of `chars`, map `Suggestion::ReplaceWith` / `InsertAfter` / `Remove` the same three
+ways, truncate to five. margin proofing.rs:168-194, docs grammar.rs:74-127.
+
+Two differences, both docs ahead:
+
+- Span clamping. margin clamps start and end against `chars.len()` independently
+  (proofing.rs:171-172). docs clamps end first, then start against end (grammar.rs:84-85), with the
+  comment saying why: a foreign engine walking user prose that hands back an inverted span makes
+  `chars[start..end]` a panic in margin and a no-op in docs.
+- docs drops lints whose span is nothing but whitespace (grammar.rs:96-98), naming Harper's "French
+  spaces" rule specifically. margin draws them, so a margin user gets an invisible underline over
+  two spaces that cannot be clicked.
+
+Engine lifecycle differs without either being wrong: margin lazily fills a Tauri-managed
+`Mutex<Option<Engine>>` (proofing.rs:36-40, 203-216); docs uses a module-level
+`LazyLock<Mutex<Harper>>` (grammar.rs:39).
+
+## The [patch.crates-io] trap
+
+Both crates carry the same two-line patch, and the four stub files behind it are code-identical.
+
+- `margin/src-tauri/Cargo.toml:70-72` and `margin-editor/src-tauri/Cargo.toml:98-100`: the same
+  `burn-cuda = { path = "stubs/burn-cuda" }` and `cubecl-cpu = { path = "stubs/cubecl-cpu" }`.
+- `harper-core = { version = "=2.5.0", features = ["concurrent"] }`, margin Cargo.toml:38 and docs
+  Cargo.toml:57. Both carry a comment above it saying the pin is exact because the stubs are tied to
+  this version's burn/cubecl graph and a minor bump could silently invalidate the patch.
+- `[profile.dev.package."*"] opt-level = 3`, margin Cargo.toml:78-79 and docs Cargo.toml:107-108,
+  with the same justification (harper's burn-ndarray POS tagger is roughly ten times slower
+  unoptimized).
+- The stubs themselves: `stubs/burn-cuda/Cargo.toml` (21 lines) and `stubs/cubecl-cpu/Cargo.toml`
+  (16 lines). Diffing them with comment lines removed produces no output. The feature lists that
+  have to match burn's `burn-cuda?/...` references (`std`, `doc`, `fusion`, `autotune`,
+  `autotune-checks`) and the pinned stub versions (burn-cuda 0.19.1, cubecl-cpu 0.8.1) are the same
+  in both.
+
+The only differences across all four stub files are prose: margin says "broken/heavy" where docs
+says "heavy", margin's cubecl-cpu comment blames failing tracel-llvm prereleases where docs blames
+build cost, and margin uses an em dash in the two `lib.rs` one-liners where docs uses a colon.
+
+Why this is a trap rather than merely duplication. Cargo treats an unused `[patch]` as a warning,
+not an error. The patch's validity depends on harper-core 2.5.0's exact transitive graph. Whoever
+bumps harper-core in one repo has to know to re-audit the stub versions, and there is no test in
+either repo asserting the patch is still applied. A stale stub does not fail the build; it quietly
+pulls several hundred crates and an LLVM toolchain back into the graph, and the symptom is a build
+that got slow. Two copies means the bump happens twice, on two different days, by which time the
+comment explaining the pin has been read once and skipped once.
+
+This is the strongest single argument for a shared crate in the audit: not because the code is
+large, but because the fragile fact needs one owner. A `margin-grammar` crate would carry the
+harper pin, the two stubs, the patch section, and one integration test asserting `cubecl-cpu`
+resolves to the stub version.
+
+## Frontend
+
+### Typst converters: no shared code, and one real bug
+
+`margin/src/export/typst.ts` is 421 lines (335 of code).
+`margin-editor/src/export/typst.ts` is 808 lines (486 of code).
+Identical in order: 9 lines, 2%.
+
+They are genuinely different documents. margin writes a book: trim sizes (typst.ts:16-21), a title
+page, chapter and part openers, a generated table of contents that queries `<chap>` metadata
+(typst.ts:130-239). margin-docs writes an A4 document: callouts, toggles, task lists, tables, code
+surfaces, mermaid diagrams, mitex math (typst.ts:206-327). Nothing about either preamble is
+shareable and neither should be.
+
+The one identical fragment is the image extension sniffer, 5 lines: margin typst.ts:240-244
+(`imageExtension`) and docs typst.ts:342-347 (`extensionOf`).
+
+The escaping philosophies are opposites, and docs' header says so directly (typst.ts:6-14): it has
+no `esc` "that sprinkles backslashes through markup the way the sibling book exporter does".
+Nothing in docs writes user text into markup; every character leaves through `str`
+(typst.ts:98-110), which builds a Typst string literal, and a string literal has no syntax inside
+it. margin escapes into markup with a character class (typst.ts:23-34): `INLINE_SPECIAL` covers
+`\ # $ * _ \` < > @ ~ ( ) [ ]`, `guardLineStart` handles a leading `= - + /` and a leading `1.`.
+
+margin's `str` is `JSON.stringify` (typst.ts:36-38), and that is a bug. Typst's string literal
+resolves exactly `\\`, `\"`, `\n`, `\r`, `\t` and `\u{...}`, and an escape it does not recognise it
+copies through as literal text
+(`typst-syntax-0.14.2/src/ast.rs:1248-1268`, the `_ => out.push_str(s.from(start))` arm).
+JSON.stringify emits `\b`, `\f`, and `\uXXXX` for every other C0 control, for U+2028 and
+U+2029, and for a lone surrogate. Every one of those lands in the PDF as the literal backslash
+sequence instead of the character it stood for. There is no compile error to catch it. docs' `str`
+(typst.ts:98-110) emits `\u{...}` and runs `sanitize` (typst.ts:80-87) to replace lone surrogates
+first, precisely because they survive neither the IPC JSON nor UTF-8 on the other side. margin
+carries a book title straight into `str` at typst.ts:136, and an href at typst.ts:57.
+
+Secondary: margin does not neutralise Typst's markup shorthands, so `--` in a manuscript becomes an
+en dash and `...` becomes an ellipsis in the PDF without the author asking. Arguably desirable in a
+book; it is silent either way.
+
+Image handling also diverged. margin only ever sends inline base64 from data URLs
+(typst.ts:275-301, `ImageInput.data: string` at `margin/src/ipc.ts:10-13`). docs sends a path for a
+file-backed image and bytes only for things with no file, such as a rendered mermaid SVG
+(typst.ts:357-396, `ImageInput.data: string | null` at `margin-editor/src/ipc.ts:244-248`). The
+path variant is what makes the root guard in docs' pdf.rs necessary and is why the two DTOs cannot
+merge without a decision.
+
+### ExportPreview: the most duplicated file in either repo
+
+`margin/src/components/ExportPreview.tsx` is 336 lines (307 of code).
+`margin-editor/src/components/ExportPreview.tsx` is 448 lines (342 of code).
+Identical in order: 200 lines, 65% of the smaller.
+
+docs' header (lines 1-19) states outright that the sibling answers Export with the same panel for
+the same reason. Shared verbatim or near-verbatim: the `Frame` interface, `measureEditorPane`
+against `measurePane` (margin:40-47, docs:64-71, identical but for the name), the zoom constants
+and step, the whole ctrl-wheel and gesture accumulator block (margin:75-129, docs:117-180, differing
+in one identifier), the pdf.js page render loop with `RenderTask` cancellation, the `ResizeObserver`
+on `.editor-pane`.
+
+The drift is mostly docs adding: StrictMode-safe compile-once refs (docs:113-135), lazy pages via
+`AHEAD`, an overlay key context, toast integration. margin adds `unsupportedScripts` messaging
+(margin:129 onward, typst.ts:307-334) which docs does not have.
+
+pdf.js loading is the one place the drift is a cost margin pays every launch. margin imports
+`pdfjs-dist` and the worker URL at module scope in ExportPreview.tsx and sets
+`GlobalWorkerOptions.workerSrc` at line 18, so roughly 1.5M of reader is in the main bundle whether
+or not anyone opens the panel. docs has `margin-editor/src/pdfjs.ts`, 27 lines, which dynamic-
+imports both and caches the promise (pdfjs.ts:17-26). Two surfaces use it there. docs is ahead and
+the fix is 27 lines.
+
+### Proofing on the frontend: same problem, two solutions, no shared code
+
+- `margin/src/editor/proofing.ts` (139 lines) is a decoration plugin only. The driving loop lives in
+  `margin/src/components/EditorView.tsx:137-255`: a debounce, a whole-document pass, a `setTimeout`.
+- `margin-editor/src/editor/proofing.ts` (642 lines, 344 of code) holds the plugin plus block
+  batching into 8000-character runs (proofing.ts:85-88, 201-225), two module-level caches keyed by
+  paragraph text (125-126, 253-259), a pass sequence number, and keyboard menu opening. 17 lines
+  identical in order, 13%. The only common line of substance is `Decoration.inline` over a mapped
+  span.
+- `margin/src/proofing.ts` (112 lines) has no counterpart at all. `docText` and `mapOffset`
+  (proofing.ts:39-73) flatten the whole document to one string with a `Segment` table to map code
+  point offsets back to ProseMirror positions. docs solves the same offset problem per block inside
+  proofing.ts:154-251. Genuinely the same problem solved twice, in incompatible shapes.
+
+`ProofPopover.tsx`: margin 76 lines (68 of code), docs 292 (184). 29 identical in order, 42%. Both
+portal to `document.body`, clamp to the window, humanise Harper's CamelCase category the same way
+(margin:6-8 `humanize`, docs:57-63 `readableKind`, docs adding `0-9` to the class), render `""` as
+"Remove" (margin:58, docs:70), and lay out suggestions then actions. docs adds arrow-key walking,
+the pointer-versus-chord focus split, and a store. margin's "Remember" writes to its own dictionary
+file; docs' "Learn Spelling" writes to the system.
+
+### Editor and TipTap
+
+`src/editor/extensions.ts`: margin 28 lines, docs 180. 12 lines identical in order, and those 12
+are the StarterKit and Placeholder imports and the `configure` skeleton. The schemas are not
+comparable: margin uses StarterKit's nodes plus Figure, ParagraphIndent, TextAlign; docs generates
+one TipTap extension per entry in its own frozen `src/model/schema.ts` and switches all of
+StarterKit's schema off (extensions.ts:128-147), because the markdown bridge is written against
+that contract.
+
+margin-mail's editor is `margin-mail/src/screens/Editor.tsx`, 95 lines: one `StarterKit.configure`
+with `heading: false` and `horizontalRule: false` (Editor.tsx:41-48), no toolbar, no proofing, no
+export. Its own comment (Editor.tsx:8-11) points at margin's extensions.ts as the model. Nothing to
+share but the version pin, and the pins already disagree: margin `^3.27.1`, margin-docs pinned
+`3.30.2`, margin-mail `^3.31.2`, across all five `@tiptap/*` packages.
+
+Two frontend pairs outside the brief are worth naming because they are more duplicated than
+anything in it:
+
+- `src/editor/search.ts`: 217 against 235 code lines, 206 identical in order, 94%. docs' header
+  (search.ts:6-7) says "Ported from margin's editor/search.ts. The only change of substance is the
+  name of the last command". The rest of the diff is prettier's trailing commas and a return type.
+  This is the highest-similarity file pair in either repo.
+- `src/editor/paste.ts`: 70 against 163 code lines, 51 identical, 72%.
+- `src/escape.ts` is byte-identical, 36 lines, in margin, margin-docs and margin-calendar.
+
+### Fonts on the frontend are already shared, and only there
+
+`margin/shared/src/fonts.ts` (233 lines) is the single list of the six bundled families, the
+`FontRef` encoding, the pairings and `fontsUsed`. All three UI apps import it: margin, margin-docs
+and margin-mail (`margin-mail/src/screens/Settings.tsx:7-12`). This is the model for what a shared
+Rust crate should look like, and its own header (fonts.ts:3-7) makes the argument: four lists in two
+repos cannot be kept honest by hand.
+
+The Rust side is the half that never got done. The same six ids are re-declared as `include_bytes!`
+in margin pdf.rs:9-25 and docs pdf.rs:52-82, and the family list command exists three times. The
+bytes are duplicated on disk five times: 6.8M in each of `margin/public/fonts`,
+`margin-editor/public/fonts`, `margin-mail/public/fonts` and the `margin/shared/fonts` master, plus
+1.6M of static cuts in `margin-editor/src-tauri/fonts`. `margin/shared/bin/sync-fonts.mjs` is the
+copier.
+
+## EPUB
+
+`margin/src-tauri/src/epub.rs`, 88 lines. Two commands: `package_epub` zips a list of
+path/data/encoding records, `unzip_epub` reads one back. The only EPUB-specific facts are the
+stored-not-deflated `mimetype` entry written first (epub.rs:29-31) and the text-extension list
+(epub.rs:15-23). Nothing in it knows what a Book is.
+
+So it is general in principle and margin-only in practice. It has one consumer, the frontend that
+feeds it is entirely Book-shaped (`margin/src/export/epub.ts` at 18733 bytes and
+`margin/src/import/epub.ts` at 17738), and no other app in the suite produces or reads an EPUB.
+Sixty lines of zip plumbing is not a crate. Leave it.
+
+## Markdown and the remark stack
+
+`margin-editor/src/markdown` is 2737 non-test lines (index 157, parse 597, serialize 1471, handlers
+420, frontmatter 92) plus roughly 8400 lines of tests. It depends on unified, remark-parse,
+remark-stringify, remark-gfm, remark-frontmatter, remark-math and mdast-util-to-markdown, none of
+which appear in margin or margin-mail.
+
+It is not shareable and should not be made so. Every line of it is written against
+`margin-editor/src/model/schema.ts`, which the module's header (index.ts:29-36) treats as a frozen
+contract, and its four stated invariants (opening writes nothing, serializing is stable, frontmatter
+passes through opaque, nothing is silently dropped) are promises about a folder of markdown files.
+margin has no markdown at any point in its pipeline and mail composes HTML. If mail ever gained
+markdown compose it would want a serializer, not this parser, and the schema it serialized from
+would be StarterKit's rather than the contract's.
+
+## What is worth extracting
+
+Ordered by ratio of risk removed to work done.
+
+1. The harper pin, the two stub crates and the `[patch.crates-io]` block. Smallest code, largest
+   consequence, and the only duplication here that fails silently and expensively.
+2. The AppKit menu walk from writingtools.rs: `submenu_named`, `edit_menu`, `writing_tools_menu`,
+   21 lines already byte-identical, plus the availability probe docs has and margin does not.
+3. fontdb: `system_db`, the installed-family list (three copies today), the four-style face loader,
+   and the source-path dedup key margin is missing. Take docs' version, drop the incorrect comment
+   at fonts.rs:84-86.
+4. `utf16_to_codepoint` and the NSSpellChecker `check` body, 12 lines already identical and about 40
+   more that differ only in constants and the return type. Needs one shared `SpellIssue`.
+5. Typst diagnostic formatting, 16 identical lines, and the compile-and-render call. Not the
+   preambles and not the converters.
+6. The nine static font cuts, so margin's PDFs stop exporting every heading at weight 400. This is
+   an asset and a build step more than a crate, but it is the change a reader of the two PDFs would
+   notice first.
+
+Frontend, separately from any Rust crate: pdf.js lazy loading (27 lines, docs already has it),
+ExportPreview's frame-and-zoom shell (65% identical), and margin's `str` bug in export/typst.ts:36.

simplify/README.md

@@ -0,0 +1,27 @@
+# Simplify
+
+A plan for turning four separate Margin apps into one family with shared foundations, and the
+guidelines that already govern all four written down in the repo instead of in memory files.
+
+Nothing here is built yet. This directory is the design and the sequence.
+
+- [overview.md](overview.md): what is duplicated, what it costs, what the answer is
+- [repo-layout.md](repo-layout.md): where shared code lives and how four repos consume it
+- [design-system.md](design-system.md): tokens, fonts, icons, the CSS foundation
+- [ui-kit.md](ui-kit.md): the shared React primitives
+- [hooks.md](hooks.md): the shared hooks, utilities and the IPC wrapper
+- [rust-crates.md](rust-crates.md): the shared Rust crates
+- [typesetting.md](typesetting.md): the Typst, font and proofing pipeline Margin and Margin Docs both carry
+- [accounts.md](accounts.md): Google OAuth, sealed secrets and the sync engines
+- [toolchain.md](toolchain.md): tsconfig, Vite, justfile, the developer loop
+- [release.md](release.md): CI, signing, notarisation, the updater, distribution
+- [testing.md](testing.md): the dev fixture harness and the Playwright suites
+- [naming.md](naming.md): the names that disagree with each other, and what to do about it
+- [migration.md](migration.md): the order the work happens in
+- [risks.md](risks.md): what not to share, and what could go wrong
+
+[guidelines/](guidelines/) holds the rules the apps are built by, harvested from assistant memory
+and the scattered `CLAUDE.md` files. Start at [guidelines/README.md](guidelines/README.md).
+
+`.research/` holds the raw audit notes the plan was written from. They are working papers, not
+deliverables, and they are where to check a claim.

simplify/accounts.md

@@ -0,0 +1,481 @@
+# Accounts, OAuth, secrets, HTTP and backup
+
+The plan for `margin-google`, `margin-secrets` and `margin-http`, what happens to the two backup
+designs, and why the two sync engines stay where they are. Every claim carries a file and a line,
+read off disk on 2026-09-06. The audit behind it is
+[.research/rust-google-sync.md](.research/rust-google-sync.md); you should not need to open it.
+Margin Docs is absent throughout: its `src-tauri/Cargo.toml` has no `reqwest`, no `chacha20poly1305`
+and no Google anything, so it consumes none of these three crates.
+
+## The two OAuth implementations are one implementation
+
+Margin Mail's `google/auth.rs` says so in its first four lines: ported from Margin Calendar's
+`google/auth.rs`, which took it from margin's `gdrive.rs`. It is a copy with edits, and the copy is
+measurable. Counts ignore each file's `#[cfg(test)]` module; a calendar line counts as present when
+the identical line exists in Mail's file.
+
+| File | Calendar | Mail | Calendar lines verbatim in Mail |
+|---|---|---|---|
+| `src-tauri/src/google/auth.rs` | 898 | 1,145 | 815 (91%) |
+| `src-tauri/src/google/browser.rs` | 420 | 419 | 416 (99%) |
+| `src-tauri/src/google/secrets.rs` | 262 | 265 | 243 (93%) |
+| `src-tauri/build.rs` | 29 | 29 | 29, `diff` prints nothing |
+
+1,503 of the calendar's 1,609 non-test lines exist unchanged in Margin Mail. `browser.rs`, the whole
+iOS `SFSafariViewController` and Android Custom Tab consent surface, differs in four lines and all
+four are comment prose naming which app the sheet sits over. On top of that, `margin`'s `gdrive.rs`
+is 953 lines of which roughly 330 are the same flow written independently and earlier: the same PKCE
+(gdrive.rs:159-169), the same loopback listener (gdrive.rs:199-275, inline in one function rather
+than four testable pieces), the same token endpoint calls (gdrive.rs:318-359).
+
+Six things genuinely differ, and those six are the shared crate's entire configuration surface.
+
+1. **Scopes.** The calendar has one string, `pub const SCOPES` (calendar auth.rs:28). Mail has a
+   six-entry `BASE_SCOPES` (mail auth.rs:29-35), a `REQUIRED_SCOPE` an account is refused for
+   (auth.rs:41), `scope_string` for extras (auth.rs:274), and `granted_scopes` / `missing_required`
+   reading what Google granted back off the token response (auth.rs:292, 300); the calendar's
+   `TokenResponse` has no `scope` field. Parameters: `base_scopes` and `required_scopes`, slices,
+   the second allowed to be empty.
+2. **Re-consent.** Mail has `grant()` (auth.rs:725) because Google offers installed apps no
+   incremental authorization: picking up `calendar.events` to answer an invite costs the whole
+   consent screen again. No parameter; the calendar never calls it.
+3. **`login_hint` and `prompt`.** Mail's `auth_url` takes a hint and switches `prompt` between
+   `consent` and `select_account consent` (auth.rs:607-639); the calendar always sends
+   `select_account consent` (calendar auth.rs:519-530). No parameter; `Option<String>` on `connect`.
+4. **Revocation.** The calendar's `revoke` returns nothing and its result is discarded (calendar
+   auth.rs:479); Mail keeps it and reports that the account went from this device but Google could
+   not be reached (mail auth.rs:584, 1043). No parameter; the crate returns the outcome.
+5. **Where the account record lands.** A SQLite row through `store::write::upsert_account` (calendar
+   store/write.rs:168-181), against `accounts.json` through `crate::accounts::upsert`, because in
+   Mail every account owns its own database and the account list must be readable before any of them
+   is open (mail accounts.rs:1-15). Parameter: a trait object, the only one needing real design.
+6. **HTTP body building.** Mail hand-rolls `form_body` over `url::form_urlencoded` (auth.rs:502-511)
+   where the calendar uses `.form()`. See step 6: a mistake, not a difference.
+
+Two smaller ones belong to `margin-secrets`: the `SERVICE` and `KEY_CONTEXT` constants (calendar
+secrets.rs:41, 45; mail secrets.rs:42, 46), and a `reference()` helper the calendar needs for its
+`accounts.keychain_ref` column (calendar secrets.rs:60-62) which Mail dropped.
+
+## Defects found on the way
+
+**1. margin keeps a Google refresh token in plaintext.** `BackupState.refresh_token` is a plain field
+(margin gdrive.rs:68), serialised with `serde_json::to_string_pretty` and written by `save_state`
+(gdrive.rs:153-157) through `crate::project::atomic_write` (project.rs:13-29), which sets no file
+mode, into `backup.json` (gdrive.rs:138-140). Same OAuth client and same grant that the other two
+apps seal. The weakest store in the suite sets the suite's real security level, so sealing anything
+is worth nothing until this is fixed. **Fix before the refactor**: it is small against today's code,
+and it is the one finding here that is live exposure rather than untidiness.
+
+**2. Margin Mail will not compile for mobile.** `src-tauri/src/lib.rs:307` calls
+`listen_for_redirects(handle)` under `#[cfg(mobile)]`, and `grep -rn "fn listen_for_redirects"` over
+the whole repository returns nothing. The call site was copied from the calendar and the definition
+was not; the calendar has it at `margin-caledar/src-tauri/src/lib.rs:150-172`. Desktop builds are
+unaffected, and the plugin is already registered (mail Cargo.toml:24, lib.rs:260), so the only thing
+missing is the twenty-line function. **Fix before the refactor**: the mobile deep link is one of the
+two paths the crate must expose and there is no way to know Mail's half works.
+
+The rest ride along with the refactor rather than blocking it.
+
+| # | Defect | Where | What breaks |
+|---|---|---|---|
+| 3 | The calendar has no rate limit handling. `error_for` maps 410 and 412 and sends everything else to `Other`; grepping the crate for `429`, `Retry-After` or `backoff` finds nothing | calendar api.rs:191-197, push.rs:29, 345, 378 | a 429 reaches `push::drain`, counts as a real attempt through `mark_attempt_failed`, and five of them retire the queued write permanently. A user's edit is dropped silently because Google was busy |
+| 4 | margin's HTTP clients have no timeouts. The calendar's own header named this as fix number one (calendar auth.rs:3) and nobody applied it upstream | margin gdrive.rs:25, updates.rs:6 | a hung socket hangs a backup with no bound |
+| 5 | margin bakes a build-machine path into the binary and reads it at runtime in preference to the compiled copy | margin gdrive.rs:22-23, 41-42 | the build machine's absolute path ships in every binary, a developer's on-disk file silently outranks what was compiled, and with `build.rs` two lines long a clone without credentials fails to compile rather than failing at connect. Fix with step 6 |
+| 6 | `gdrive_disconnect` revokes the suite-wide grant with `let _ =` and says nothing | margin gdrive.rs:777-803 | Disconnect in the writing studio signs the person out of the calendar and the mail client too. Mail names that before offering the button (mail auth.rs:1026-1029) |
+| 7 | `chacha20poly1305` 0.10 against 0.11, no on-disk format difference | calendar Cargo.toml:40, mail Cargo.toml:64 | nothing today; settled at 0.11 |
+| 8 | `reqwest` 0.12 against 0.13 | margin Cargo.toml:39, calendar Cargo.toml:29, mail Cargo.toml:37-43 | nothing today; settled at 0.13, and step 6 says why the three hand-written helpers this supposedly forced are avoidable |
+
+## `margin-google`
+
+`crates/google`, on reqwest 0.13, depending on `margin-secrets` and `margin-http`. It owns the OAuth
+flow and nothing above it: no Gmail types, no Calendar types. The app hands it a config and a place
+to record accounts, and gets back a token getter.
+
+```rust
+pub struct Config {
+    pub base_scopes: &'static [&'static str],
+    /// An account that did not grant all of these is refused, not stored. May be empty.
+    pub required_scopes: &'static [&'static str],
+    /// For the listener page and the not-set-up sentence.
+    pub app_name: &'static str,
+    /// e.g. "studio.margin.mail:/oauth2redirect".
+    pub android_redirect: &'static str,
+    /// `include_str!(concat!(env!("OUT_DIR"), "/google-credentials.json"))` from the app.
+    pub credentials_json: &'static str,
+}
+
+/// One app writes a SQLite row and the other a JSON file; neither shape belongs in this crate.
+pub trait AccountSink: Send + Sync {
+    fn upsert(&self, app: &tauri::AppHandle, account: &Granted) -> Result<(), String>;
+    fn forget(&self, app: &tauri::AppHandle, account_id: &str) -> Result<(), String>;
+    fn email_of(&self, app: &tauri::AppHandle, account_id: &str) -> Result<Option<String>, String>;
+    /// (account_id, email) for every account with a token, read once at launch.
+    fn known(&self, app: &tauri::AppHandle) -> Result<Vec<(String, String)>, String>;
+}
+
+pub struct Granted {
+    pub account_id: String,
+    pub email: String,
+    pub display_name: String,
+    pub scopes: Vec<String>,
+    /// Non-empty means nothing was stored and there is no account.
+    pub missing_required: Vec<String>,
+}
+
+/// Managed in Tauri state, replacing both apps' own (calendar auth.rs:214-219, mail auth.rs:239-243).
+pub struct AuthState { /* sessions, pending, config, sink, secrets */ }
+impl AuthState {
+    pub fn new(config: Config, sink: Arc<dyn AccountSink>, secrets: margin_secrets::Store) -> Self;
+}
+
+/// Returns the consent URL; the answer arrives later as the `auth` event. `hint` is the address
+/// typed on the connect screen, when there was one.
+pub async fn connect(app: tauri::AppHandle, extra_scopes: Vec<String>, hint: Option<String>)
+    -> Result<String, String>;
+/// The whole consent again for a connected account, to pick up a scope it did not grant.
+pub async fn grant(app: tauri::AppHandle, account_id: String, extra_scopes: Vec<String>)
+    -> Result<String, String>;
+/// Revokes at Google, then forgets the token and the session here. The account goes from this
+/// device whether or not Google answered; the return says whether it heard.
+pub async fn disconnect(app: &tauri::AppHandle, state: &AuthState, account_id: &str)
+    -> Result<Revoked, String>;
+pub enum Revoked { AtGoogle, LocallyOnly(String) }
+/// A live access token, refreshing if needed. Single-flight.
+pub async fn valid_access_token(state: &AuthState, account_id: &str) -> Result<String, String>;
+/// From `setup`, before any command can run. Seeds the session map with stored emails.
+pub fn init_sessions(app: &tauri::AppHandle, data_dir: PathBuf);
+
+#[cfg(mobile)] pub fn listen_for_redirects(handle: &tauri::AppHandle);
+#[cfg(mobile)] pub async fn handle_redirect(app: tauri::AppHandle, incoming: &url::Url);
+#[cfg(mobile)] pub async fn abandon_pending(app: tauri::AppHandle, reason: Option<String>);
+```
+
+**Desktop, and phones by default.** A loopback listener: bind 127.0.0.1 on a port the OS picks, open
+the URL in the system browser through `tauri-plugin-opener`, never an in-app webview, and wait
+`AUTH_TIMEOUT_SECS` (120 desktop, 900 mobile). It keeps the four testable pieces the calendar split
+it into, `write_http_message`, `request_path`, `parse_redirect` and `await_code`, with the `Redirect`
+enum, the CSRF state check, the `access_denied` case, the favicon skip, the 8 KiB buffer, the 150 ms
+poll and the 5 s read timeout (mail auth.rs:307-437). Phones use it too: a Desktop client may
+redirect to loopback on any port without registering it, and Google's token endpoint checks the
+client id, the secret and the redirect rather than the calling OS. What used to make that impossible
+on a phone was that leaving for Safari suspends the process, which `browser.rs` fixes by keeping the
+consent sheet in front of the app rather than replacing it.
+
+**Mobile deep link.** Runs instead when the credentials file carries a client for this platform,
+setting `Credentials::platform_client` at load time (mail auth.rs:118-122). With no listener the
+verifier goes in `Pending { state, verifier, redirect, expires }` behind a mutex with a 900 s expiry.
+`handle_redirect` takes the verifier rather than reading it, so both arrival routes fire harmlessly:
+`get_current` for the link that launched a process the OS had killed, `on_open_url` for the usual
+case. Android uses `Config::android_redirect`, iOS the reversed client id, worth having there as the
+only route to `ASWebAuthenticationSession`, the only iOS browser that shares Safari's cookies.
+
+**Refresh and clock skew.** One constant, `EXPIRY_SKEW_SECS = 60`, with expiry stored as
+`now() + expires_in.saturating_sub(EXPIRY_SKEW_SECS)` (mail auth.rs:61, 1122). That is all either app
+does and it is enough: it covers a request in flight when the clock rolls over, and does not pretend
+to fix a machine whose wall clock is wrong. Refresh is single-flight by holding the tokio mutex
+across the refresh await, so concurrent callers queue on one token request; that serialises refreshes
+across accounts too, the right trade for something happening once an hour per account. A rotated
+refresh token is written back only when it changed (mail auth.rs:1114-1118). margin has none of this:
+it reads the session, drops the lock, then awaits (gdrive.rs:498-521).
+
+**Revocation** is `POST https://oauth2.googleapis.com/revoke` with the refresh token, before anything
+local is touched, because the token is what names the grant. One OAuth client covers the suite and
+the endpoint acts on the authorization behind the token rather than on the string, so this signs the
+person out of every Margin app on every machine; the crate returns `Revoked` so the app can say so.
+
+**The multi-account store** is `HashMap<String, Session>` keyed on the Google `sub` from the
+id_token, falling back to the email when it is absent. `Session` holds the access token, its expiry
+and the email; the refresh token is never in that map and never in memory outside a refresh. The
+id_token is parsed and never signature-verified, deliberately: it arrived over TLS from Google's own
+token endpoint, the same trust the access token rides on. The crate emits the `auth` event on Mail's
+shape (`accountId`, `email`, `scopes`, `missingRequired`, `error`), a superset of the calendar's that
+costs it two empty arrays; two schemas for one event name costs more.
+
+## `margin-secrets`
+
+`crates/secrets`. A sealed key-value file, not an OAuth token store. Mail already uses it for three
+unrelated things: refresh tokens keyed by account id, the backup key under `"margin-mail backup key"`
+(backup/crypto.rs:41, 119-138), and the R2 credentials under `"margin-mail r2 credentials"`
+(backup/r2.rs:29). Neither of those ids can collide with an account id, because a Google `sub` is
+digits and an address cannot carry a space.
+
+```rust
+pub struct Store { /* dir, context */ }
+impl Store {
+    /// `context` is a per-app constant mixed into the key, e.g. "margin-mail token store v1".
+    pub fn new(dir: PathBuf, context: &'static str) -> Self;
+    pub fn put(&self, id: &str, secret: &[u8]) -> Result<(), String>;
+    pub fn get(&self, id: &str) -> Result<Option<Vec<u8>>, String>;
+    pub fn delete(&self, id: &str) -> Result<(), String>;
+    pub fn put_str(&self, id: &str, secret: &str) -> Result<(), String>;
+    pub fn get_str(&self, id: &str) -> Result<Option<String>, String>;
+}
+```
+
+A value, not the `OnceLock<PathBuf>` global both apps have today (mail secrets.rs:49-55), which
+exists only because the free functions deliberately do not carry an `AppHandle`; a `Store` held by
+`AuthState` gets the same property without process-wide state.
+
+**The format** is unchanged from what is on disk, so there is no migration. `tokens.enc` is JSON, a
+`BTreeMap<String, String>` of id to base64 (standard alphabet, padded) of `nonce || ciphertext ||
+tag`, the nonce 24 random bytes, XChaCha20-Poly1305 throughout. One seal per entry rather than one
+over the map, so a corrupt entry costs that entry. `tokens.salt` is 32 random bytes, per install,
+written once and never rotated: losing it costs a reconnect and nothing else.
+
+**The key** is `SHA256(context || salt || machine_id)`, never persisted. `machine_id` is
+`/etc/machine-id` on Linux, `IOPlatformUUID` scraped out of `/usr/sbin/ioreg` on macOS, and
+deliberately empty on iOS and Android, where the sandbox is the real boundary and a reinstall would
+rotate any identifier and silently destroy the store. The salt sits beside the ciphertext and the
+context is a constant in a public binary, so the machine id is the only thing binding a token to the
+machine that stored it: a copied-home-directory defence and nothing stronger, and the file should
+keep saying so. A salt that exists and will not read is refused rather than replaced, because
+replacing it turns one transient IO failure into permanent loss of every token (mail
+secrets.rs:107-113). No keyring, because macOS ties a keychain item's ACL to the code signature so
+every ad-hoc rebuild re-prompts, and the `keyring` crate has no Android backend at all.
+
+**Atomic replace.** Write to `<path>.tmp` opened with `mode(0o600)` on unix so the ciphertext is
+never briefly world readable, `write_all`, `sync_all`, then `rename` (mail secrets.rs:246-265).
+Deliberately not the apps' general `atomic_write`, which sets no mode. One hardening to fold in:
+neither copy fsyncs the parent directory after the rename.
+
+**The version drift** settles at `chacha20poly1305 = "0.11"`, which Mail already runs. 0.11 moved to
+`hybrid-array`: `Key::from_slice` and `XNonce::from_slice` are deprecated and the array conversions
+carry the length in the type, so the one panic those calls had is now a compile error. The on-disk
+format is identical, so the calendar's upgrade is an API edit with no data migration.
+
+## `margin-http`
+
+`crates/http`, lifted wholesale from Margin Mail's `google/api.rs`, the only place in the suite where
+any of this exists. There are nine `reqwest::Client` constructions across the three apps, no two
+alike, two of them with no timeouts.
+
+```rust
+/// Named profiles rather than a builder, so a new call site picks one rather than inventing one.
+pub fn auth() -> &'static reqwest::Client;      // connect 10s, total 30s, h2 + tcp keepalive
+pub fn api() -> &'static reqwest::Client;       // connect 10s, total 60s, pool idle 30s, gzip, http2
+pub fn bulk() -> &'static reqwest::Client;      // connect 10s, total 120s, uploads and downloads
+pub fn untrusted() -> &'static reqwest::Client; // connect 5s, total 10s, referer(false), 3 redirects
+
+pub enum ApiError {
+    Unauthorized(String),
+    InsufficientScope(String),
+    RateLimited { retry_after_ms: u64 },
+    NotFound(String),
+    Offline(String),
+    /// There and then not: reset, closed early, cut off mid-body. Its own kind because it is the
+    /// one failure worth retrying at once, and the one a client that never does shows on a wake.
+    Dropped(String),
+    Other(String),
+}
+
+pub fn error_for(status: u16, context: &str, scope: &str, retry_after_ms: Option<u64>, body: &str)
+    -> ApiError;
+pub fn retry_after(headers: &reqwest::header::HeaderMap) -> Option<u64>;
+pub fn strip_urls(text: &str) -> String;
+pub async fn read_json<T: DeserializeOwned>(resp: reqwest::Response, context: &str, scope: &str)
+    -> Result<T, ApiError>;
+
+pub const MAX_BACKOFF_MS: u64 = 64_000;
+pub const MAX_ATTEMPTS: u32 = 5;
+pub const DROPPED_WAITS_MS: [u64; 2] = [250, 1_250];
+pub fn backoff_ms(attempt: u32, jitter_ms: u64) -> u64;
+
+pub async fn with_retry<T, F, Fut>(call: F) -> Result<T, ApiError>
+where F: FnMut() -> Fut, Fut: Future<Output = Result<T, ApiError>>;
+/// For a call that must not be made twice: a send on a connection that dropped may have sent.
+pub async fn with_retry_no_replay<T, F, Fut>(call: F) -> Result<T, ApiError>
+where F: FnMut() -> Fut, Fut: Future<Output = Result<T, ApiError>>;
+
+/// A rolling window of spend. Budget is a constructor argument: Gmail's 6,000 units a minute is not
+/// the Calendar API's limit, and the per-call unit table stays in the app that knows it.
+pub struct Quota { /* VecDeque<(at_ms, units)> */ }
+impl Quota {
+    pub fn new(budget: u32, window_ms: u64) -> Self;
+    pub fn spent(&mut self, now_ms: u64) -> u32;
+    /// How long before `units` more would fit. Zero when they fit now.
+    pub fn wait_for(&mut self, now_ms: u64, units: u32) -> u64;
+    pub fn charge(&mut self, now_ms: u64, units: u32);
+}
+```
+
+`error_for` reads Google's machine-readable reason out of all three places Google puts it,
+`error.status`, `error.errors[].reason` and `error.details[].reason`, because a 403 for an
+insufficient scope only says so in the third (mail api.rs:250-275, 341-440). `dailyLimitExceeded` is
+deliberately not retryable: it is the project's day gone, and retrying in thirty seconds only spends
+the next day's. `strip_urls` drops whole sentences carrying a link, rather than the bare URL, because
+"Enable it by visiting then retry" is not English. Backoff is `min(2^n seconds + jitter, 64s)`, with
+jitter a parameter so the schedule is a pure function and testable. Set a user agent,
+`Margin<App>/<version>`, on every profile: today nothing does except `mail/imap/discover.rs:543-554`,
+which spoofs Chrome, correct for autodiscovery and wrong everywhere else, so `untrusted()` takes an
+override. margin gains timeouts on both clients, the calendar gains the whole retry layer and with it
+defect 3, and both gain the `Dropped` kind, which is what makes the first request after a laptop
+wakes succeed instead of showing an error.
+
+## Credentials, the build script, and the reqwest split
+
+There is one Google Cloud project, `margin-500217`, one OAuth desktop client, and three
+byte-identical copies of `google-credentials.json` in three repo roots, all gitignored, with only the
+example files committed. See [guidelines/distribution.md](guidelines/distribution.md).
+
+The mechanism the calendar and Mail share is right and stays: `src-tauri/build.rs` copies the file
+from the repo root into `OUT_DIR`, falling back to `google-credentials.example.json` when the real
+file is absent, and the auth code pulls it in with
+`include_str!(concat!(env!("OUT_DIR"), "/google-credentials.json"))` (mail auth.rs:63). Nothing is
+read at runtime, and a clone with no credentials compiles and fails at the first connect with the
+"not set up yet" sentence. The two `build.rs` files are byte identical, so this becomes
+`margin_google::build::embed_credentials()` called from each app's `build.rs`.
+
+margin is the app to fix. Delete the runtime read at gdrive.rs:41-42 outright, point
+`CREDENTIALS_JSON` (gdrive.rs:22-23) at `OUT_DIR`, and add the build script call. That takes the
+build machine's absolute path out of the binary, removes the case where a developer's on-disk file
+outranks the compiled one, and makes a fresh clone compile. margin's example file carries only an
+`installed` block where the other two carry `android` and `ios`; bring it to the same shape.
+
+**reqwest** settles at 0.13, with two corrections. The three hand-written helpers in Mail are
+avoidable and should go: `form_body` (auth.rs:502-511), `query_string` (api.rs:723-729) and
+`url_with` (api.rs:732-738) exist because `form` is a feature in reqwest 0.13 and Mail sets
+`default-features = false` without listing it (reqwest 0.13.1 `Cargo.toml`:
+`form = ["dep:serde", "dep:serde_urlencoded"]`, absent from `default`). In 0.12 `serde_urlencoded`
+was an unconditional dependency, which is why the calendar never noticed; adding `"form"` deletes all
+three and the comments explaining them, and should happen before the shared crate copies the
+workaround forward. Second, Mail already compiles two reqwest majors: `Cargo.lock` has 0.12.28 and
+0.13.1, the older pulled in by `css-inline 0.21.2`, so one version in the tree is not reachable
+through these crates and one version in code we write is. Keep Mail's feature set as the crate's,
+plus `form`: `rustls`, `webpki-roots`, `json`, `gzip`, `http2`.
+
+## Sync engines: do not share one
+
+Both are honestly described as "incremental sync of a Google resource into a local SQLite mirror with
+a sync token, a poll loop and an event stream to the UI". That sentence is true of both and it is
+where the similarity ends. Six things differ in kind, not in degree.
+
+| | Margin Calendar | Margin Mail |
+|---|---|---|
+| Cursor | one sync token per calendar in a column, plus a `calendarList` token in `meta` keyed by account (store/schema.rs:43, pull.rs:26, 204) | one per account database, Gmail's `historyId` (mirror/write.rs:29) |
+| Commit point | end of the page chain, because `nextSyncToken` only arrives on the last page; the whole chain is one transaction and an interruption restarts it (pull.rs:136-195) | as soon as changes are on disk and deliberately before hydration, so a failed crawl does not re-read the log (changes.rs:51-56) |
+| Cursor expiry | 410 drops that calendar's rows and cursor and re-syncs it alone (pull.rs:105-132) | drops nothing; `reconcile` lists the window into a TEMP TABLE and diffs locally, because the mirror holds decisions the state database joins against (changes.rs:141-228) |
+| Fetch | one phase, `events.list` returns whole events | ids, then metadata in batches of 50, then bodies, with a `hydrated` column so an interrupted crawl resumes across restarts (hydrate.rs:1-9, changes.rs:69-92) |
+| Writes | `If-Match`, and a 412 is a lost race that is surfaced and never retried with the etag dropped, since dropping it is the clobber the check prevents (api.rs:310-360, push.rs:5-8) | no etag exists, so writes are declarative: what the labels should be, not what to do to them (api.rs:649-650), which is why they are safe to replay |
+| The seam | `Transport`, six methods, every one naming a Google Calendar type, one implementation and a test stub (transport.rs:15-62) | `Provider`, fourteen methods, no Google type at all, three implementations: Gmail, IMAP and a 612-line fake (provider/mod.rs:166-249) |
+
+An abstraction over "a token per collection, committed at the end of a chain, with etags" and "a log
+per account, committed halfway, with declarative writes and a quota accountant in the middle" would
+be larger and harder to read than either engine it replaced. Do not build it.
+
+What is worth extracting is the scaffolding, the same to the line in places: roughly 150 to 250 lines
+into `margin-db` and a small `margin-sync`. The poll loop shape, spawn then `FIRST_PASS_SECS = 2`
+then an interval chosen by window focus, with `fn focused(app)` byte-identical (calendar
+sync/mod.rs:39, 205-223; mail sync/mod.rs:51, 374-393), the intervals staying per app at 60/300 s
+against 12/60 s. The `Sink` trait, so a pass runs in a test with a recorder instead of an `AppHandle`
+(calendar sync/mod.rs:69-78, mail sync/mod.rs:238-249). The connection-borrowing seam, carrying the
+same justification verbatim in both, that nothing inside may await because the guard is a std one and
+holding it across a suspension point would make the future non-Send (calendar sync/mod.rs:114-115,
+mail sync/mod.rs:220-221). The push-before-pull budgets, 20 s for the outbox in a pass and 4 s at
+quit (calendar sync/mod.rs:42, 44; mail outbox.rs:30, 32). And the `meta` table with its
+`schema_version` key, the refusal to open a database written by a newer build and forward-only
+numbered steps inside a transaction (calendar store/schema.rs:100-136, mail mirror/schema.rs:21-63),
+which belongs in `margin-db`. The four event names both apps agree on, `store-changed`,
+`sync-progress`, `auth` and `menu-action`, are fixed in `margin-ipc` rather than in the engines. All
+of this buys consistency rather than deletion, which is the honest reason to do it.
+
+## Backup
+
+**margin's** is whole-file mirroring. `collect_local_files` gathers `*.margin` books and the custom
+dictionary (gdrive.rs:576-600), hashes each, and uploads anything whose hash moved
+(gdrive.rs:810-835). `gdrive_sync` downloads any remote file with no local counterpart and skips any
+that has one (gdrive.rs:877-884), so the local copy always wins and there is no merge. Nothing is
+encrypted: the books go up as they are, into a visible folder called `margin` at the Drive root under
+`drive.file`, which `docs/publishing.md:131, 162-164` defends as deliberate.
+
+**Margin Mail's** is an append-only encrypted journal. Segments of 500 records (backup/mod.rs:48)
+named `<account-hash>/<device-id>/<first>-<last>.seg`, the account hash a 128-bit truncated SHA-256
+of the address so a folder listing is not a list of somebody's email addresses (mod.rs:52-77). Each
+segment is sealed with XChaCha20-Poly1305 with its own name as additional authenticated data, so a
+store that reorders, replays or moves a segment gets a decryption failure rather than a wrong answer
+(crypto.rs:60-105). Merge is a union, because a device only ever writes under its own sequence. The
+key comes from a 24-word BIP39 phrase through Argon2id at RFC 9106's second profile, 64 MiB, three
+passes, one lane (phrase.rs:21-48), with a constant salt because a second device has the phrase and
+nothing else. The store is a three-method trait, `put` / `get` / `list` (store.rs:20-30), the
+intersection of Drive's REST API and S3, with two implementations: Drive and S3 sigv4 signed by hand.
+
+**The one genuine overlap is five HTTP functions.** margin's `ensure_folder`, `find_file`,
+`list_in_folder`, `upload_file` and `download_file` (gdrive.rs:361-496) and Mail's `ensure_folder`,
+`find_file`, `list_folder`, `upload` and `download` (google/drive.rs:100-256) are the same calls
+written twice. Mail's is better in five specific ways: it pages at 1000 rather than 100 (drive.rs:176
+against gdrive.rs:432), it escapes the Drive query language (drive.rs:47-49), it randomises the
+multipart boundary where margin hardcodes `margin7f3e2a1b9c8d` (drive.rs:74-78 against
+gdrive.rs:455), it percent-encodes the file id into the path (drive.rs:228-231), and it returns a
+classified `ApiError`. Move Mail's five into `margin-google` as a `drive` module with the
+`drive.file` scope constant, `escape`, and the `FOLDER_NAME = "margin"` root, which both apps hold as
+their own string literal today (gdrive.rs:16, drive.rs:28); each app then names its own subfolder,
+`margin/mail/` for Mail.
+
+**Should the newer design replace the older? No, and not because of effort.** They back up different
+things. Mail's journal is append-only records of decisions, which is what makes a union merge
+correct; margin's payload is a book file a person edits on two machines, where a union is meaningless
+and the answer is last-writer-wins or a real merge. Wrapping books in an encrypted journal would also
+break the property `docs/publishing.md` defends, that the folder in a person's Drive is legible and
+their books are files they can open. What margin should take is narrower: the five Drive verbs,
+`ApiError`, and the sealed store for its refresh token. The whole-file mirror stays, and its real
+defect, no merge and local always wins, is a product decision for margin's own docs rather than
+something this consolidation should quietly change.
+
+## Per app, in order
+
+**Margin Mail** first, because it is the source for all three crates.
+
+1. Define `listen_for_redirects` in `src-tauri/src/lib.rs`, ported from calendar lib.rs:150-172.
+   Defect 2, and it blocks any mobile build.
+2. Add `"form"` to the reqwest features (Cargo.toml:37-43); delete `form_body`, `query_string`,
+   `url_with`.
+3. Extract `google/secrets.rs` into `margin-secrets` as a `Store` value, on-disk format byte for
+   byte. Rewire `google/auth.rs`, `backup/crypto.rs:119-138` and `backup/r2.rs:29`.
+4. Extract the error, retry, backoff and `Quota` half of `google/api.rs` into `margin-http`, with
+   `Quota::new(6_000, 60_000)` at the call site and the `Call` unit table staying in Mail.
+5. Extract `google/auth.rs`, `google/browser.rs`, `build.rs` and the five verbs of `google/drive.rs`
+   into `margin-google`. Mail implements `AccountSink` over `crate::accounts`. `auth::remove`'s
+   database teardown and its `keep_data` flag stay in Mail; the crate's `disconnect` does the revoke,
+   the token and the session and nothing else.
+
+**Margin Calendar** second, and mostly deletion.
+
+1. Upgrade `chacha20poly1305` to 0.11 (Cargo.toml:40) and adopt `margin-secrets`. No data migration.
+   Keep `reference()` locally: two lines serving a column no other app has.
+2. Adopt `margin-http`. Replace `error_for` (api.rs:191-197) with the crate's, keeping the 410 and
+   412 mappings on top, and wrap `push::drain` in `with_retry_no_replay`, because an event write
+   carrying an etag must not be replayed. Defect 3.
+3. Adopt `margin-google`. Delete `google/auth.rs`, `google/browser.rs` and `build.rs`; implement
+   `AccountSink` over `store::write::upsert_account`; pass the existing scope string as a slice for
+   `base_scopes` and an empty `required_scopes`; move `listen_for_redirects` out of lib.rs.
+4. Take the two extra `auth` event fields as empty arrays and update `src/` to ignore them.
+
+**Margin (the writing studio)** last, and it gains the most.
+
+1. Before anything else, stop writing the refresh token in plaintext. Add `margin-secrets`, move
+   `BackupState.refresh_token` (gdrive.rs:68) into the sealed store, and have `load_state` migrate an
+   existing plaintext token on first read and then clear the field. Defect 1, worth doing on its own
+   schedule if the rest slips.
+2. Fix the credentials path: add the build script call, point `CREDENTIALS_JSON` (gdrive.rs:22-23) at
+   `OUT_DIR`, delete the runtime read (gdrive.rs:41-42), bring the example file to the three-block
+   shape. Defect 5.
+3. Adopt `margin-http` for both clients (gdrive.rs:25, updates.rs:6). Defect 4.
+4. Adopt `margin-google`, deleting roughly 330 lines of gdrive.rs: the PKCE, the inline listener, the
+   token endpoint calls, the session. `base_scopes` is `["openid", "email", "drive.file"]` and
+   `required_scopes` is `["drive.file"]`, which margin already enforces by hand (gdrive.rs:181-186,
+   522-532) and the calendar still does not.
+5. Adopt the crate's Drive verbs, deleting gdrive.rs:361-496.
+6. Make `gdrive_disconnect` (gdrive.rs:777-803) report the revoke outcome, and add the settings
+   sentence saying it signs the person out of every Margin app. Defect 6. What is left of `gdrive.rs`
+   afterwards is the file mirror, the hash ledger and the Tauri commands.
+
+## What stays per app
+
+The sync engines, whole, and the provider and transport traits. Every scope list, poll interval and
+quota budget, because they are facts about a resource rather than about OAuth. The per-call unit
+table in Mail's `google/api.rs:119-176`, which names Gmail methods. The account registry itself, a
+SQLite row in one app and `accounts.json` in the other, behind `AccountSink`. Mail's `auth::remove`
+database teardown and its `keep_data` flag. Mail's backup journal, phrase derivation and R2 store,
+and margin's whole-file Drive mirror. `imap/discover.rs`'s Chrome user agent, correct there and wrong
+everywhere else. And all the app copy: the consent explanation, the disconnect warning, the
+not-set-up sentence, because copy is product and the crate only supplies the app name it is built
+from.

simplify/design-system.md

@@ -0,0 +1,439 @@
+# The design system: `@margin/tokens` and `@margin/fonts`
+
+Scope: CSS custom properties, the base layer, themes and the six bundled faces. The React primitives
+that consume them are in [ui-kit.md](ui-kit.md); the glyphs are `@margin/icons`. Short names:
+`margin` = `python/margin`, `calendar` = `python/margin-caledar`, `editor` = `rust/margin-editor`,
+`mail` = `rust/margin-mail`, all under `/Users/pj/Workspace/projects`. Line numbers as of 2026-09-06.
+
+## Where the four token sets actually are
+
+They are not four palettes. Calendar, the only app that does not depend on `margin-shared` at all and
+so had every opportunity to drift, matches `shared/css/tokens.css` on 49 of the 52 values it declares
+in common. Absent are `--font-book`, `--pane-sidebar`, `--measure` and `--sidebar`, which a calendar
+has no use for and no sidebar to paint. One value genuinely differs, `--ink-faint`.
+
+So this is not a reconciliation. Three apps already import the shared file
+(margin/src/styles/tokens.css:3, editor/src/styles/tokens.css:5, mail/src/styles/tokens.css:6) and
+layer on top; the fourth is a hand-copy. The work is to move twenty tokens that two or three apps
+each declared separately into the one place, correct one value that is wrong in shared and right in
+two apps, and delete four copies of a reset.
+
+What drift exists is almost entirely in margin, the only app with no test suite. Colour literals
+outside each app's token layer: margin 16 hex and 18 rgba, calendar 0 and 1 (a box-shadow at
+app.css:507), editor 0 and 0, mail 0 and 0. Margin's are mostly tokens it never adopted, named under
+each group below.
+
+`--ink-faint` is the one that matters, because it is a legibility defect and not a preference.
+Shared's `#9b9484` measures 2.91:1 on `--paper`, 2.56:1 on `--shell` and 2.43:1 on `--sidebar`, and
+the dark `#756d5e` 3.39:1 on `--paper`. Calendar (tokens.css:73, :126) and mail (mail.css:86, :142)
+independently moved to `#6e675b` and `#8e8677`, measuring 5.40 / 4.75 / 4.50 light and
+4.81 / 5.14 / 4.51 dark. Margin and editor still ship the failing value.
+
+## The contract for `@margin/tokens`
+
+Fifty six names: thirty five are what `shared/css/tokens.css` declares today, twenty one are
+promotions. Every one is declared in both palettes or in neither, because a token defined in light
+and missing in dark is the failure editor's `src/theme.test.ts` catches, and that test moves into the
+package.
+
+### Colour
+
+| Token | Light | Dark | Status |
+| --- | --- | --- | --- |
+| `--paper` | `#fcfbf7` | `#1d1a16` | shared |
+| `--shell` | `#f1ece2` | `#151310` | shared |
+| `--sidebar` | `#ece6da` | `#1a1713` | shared |
+| `--raised` | `#fbfaf6` | `#232019` | shared |
+| `--ink` | `#23201b` | `#ece6da` | shared |
+| `--ink-soft` | `#6b6458` | `#a89f8e` | shared |
+| `--ink-faint` | `#6e675b` | `#8e8677` | **corrected**, was `#9b9484` / `#756d5e` |
+| `--line` | `#e3ddce` | `#2c2823` | shared |
+| `--line-strong` | `#d6cfbd` | `#3a352d` | shared |
+| `--accent` | `#2a2622` | `#efe9dc` | shared |
+| `--accent-ink` | `#100e0b` | `#ffffff` | shared |
+| `--accent-wash` | `rgba(35, 32, 27, 0.08)` | `rgba(239, 233, 220, 0.12)` | shared |
+| `--accent-contrast` | `#faf7f0` | `#1a1714` | shared |
+| `--selection` | `rgba(35, 32, 27, 0.14)` | `rgba(239, 233, 220, 0.18)` | shared |
+| `--glass` | `rgba(252, 251, 247, 0.86)` | `rgba(33, 30, 25, 0.88)` | shared |
+| `--scrim` | `rgba(35, 32, 27, 0.28)` | `rgba(0, 0, 0, 0.58)` | **promoted** |
+| `--danger` | `#b4453a` | `#d97a6f` | shared |
+| `--danger-ink` | `#963327` | `#e58e84` | shared |
+| `--danger-wash` | `rgba(180, 69, 58, 0.1)` | `rgba(217, 122, 111, 0.16)` | shared |
+| `--danger-contrast` | `#faf7f0` | `#1a1714` | shared |
+| `--hue-1` to `--hue-8` | `#6f6194` `#47705f` `#a06044` `#4e6484` `#856434` `#955767` `#3a6b78` `#667141` | `#a396c8` `#7fae98` `#d19a7c` `#8ba2c4` `#c4a267` `#cb909e` `#75a9b6` `#a2ae77` | **promoted** |
+| `--pdf-page` | `#fff` | `#fff` | **promoted**, identical in both on purpose |
+
+`--ink-faint` is the only promotion that changes what margin and editor look like, and it will be
+visible: every date stamp, word count, nav label and field label in both gets darker.
+
+`--scrim`: calendar tokens.css:84/:138 and mail mail.css:88/:145 agree exactly; editor tokens.css:26
+has `rgba(0, 0, 0, 0.5)` dark. Two to one, and both of the two wrote the reason down (a light scrim
+over a dark page dims nothing, so panels float on shadow alone). Margin writes the light value into
+`.overlay` at app.css:1275 and a second, unexplained `rgba(35, 32, 27, 0.32)` into `.export-overlay`
+at app.css:1449; both become `var(--scrim)`.
+
+The hue ramp is calendar's `--cal-1..8` (tokens.css:106-113, :160-167) and mail's `--hue-1..8`
+(mail.css:114-121, :159-166), the same sixteen hexes under two names. Mail's wins, because `--cal-`
+names a product; calendar renames on adoption, keeping its unrelated `--cal-h`, `--cal-sat` and
+`--cal-fill` HSL derivations in grid.css. `--pdf-page` editor tokenised at tokens.css:22 because it
+was a literal in two stylesheets; margin still has that literal at app.css:1238.
+
+Not promoted, one consumer each: mail's `--check` / `--check-tick`, `--note-surface`, `--row-hover`,
+`--row-selected`, `--card-ring`, `--message-*`; calendar's `--grid-*`, `--fold-*`, `--event-*`;
+editor's `--code-*` and `--doc-rule*`; margin's twelve proofing colours at app.css:2367-2451. The
+proofing pair is worth comparing separately, since editor's styles/proofing.css draws the same
+feature out of `--danger`.
+
+### Type scale
+
+| Token | Value | Status |
+| --- | --- | --- |
+| `--font-ui` | `"Hanken Grotesk", ui-sans-serif, system-ui, -apple-system, sans-serif` | shared |
+| `--font-book` | `"Literata", Georgia, "Times New Roman", serif` | shared |
+| `--font-heading` | `"Literata", Georgia, "Times New Roman", serif` | shared |
+| `--font-mono` | `ui-monospace, "SF Mono", Menlo, monospace` | **promoted** |
+| `--t-1` | `11px` | shared |
+| `--t-2` | `12px` | shared |
+| `--t-3` | `13px` | shared |
+| `--t-4` | `15px` | shared |
+| `--t-5` | `16px` | **promoted** |
+| `--measure` | `46em` | shared |
+
+`--t-5` is identical in calendar tokens.css:34, editor tokens.css:13 and mail mail.css:17, and
+calendar's and mail's comments are nearly word for word the same (iOS Safari zooms a focused field
+under 16px and the locked viewport gives no way back). `--font-mono` is a token only in editor
+(tokens.css:9); calendar writes `ui-monospace, SFMono-Regular, Menlo, monospace` as a literal at
+details.css:183 and rich.css:42, so editor's wins as the one already tokenised.
+
+`--font-ui`, `--font-book` and `--font-heading` are the three slots an app may override on the root
+at runtime, and the contract says so: editor writes `--font-book` per document from
+`store/useDocumentFonts.ts:101`, mail writes the other two from a setting in index.html:31-32. It is
+why `.panel-head h2` takes `--font-heading` below.
+
+### Spacing
+
+There is no spacing scale in any of the four and this plan does not invent one. Padding and gap are
+literals everywhere and inconsistent (panel bodies `20px 22px 24px`, heads `16px 14px 16px 22px`,
+feet `14px 22px`), and what does repeat repeats inside a rule that is itself being shared. A scale
+imposed now would be a rewrite of eighteen thousand lines of CSS with no defect behind it.
+
+### Radius
+
+| Token | Value | Status |
+| --- | --- | --- |
+| `--r-sm` | `5px` | shared |
+| `--r-md` | `8px` | shared |
+| `--r-lg` | `12px` | shared |
+| `--r-pill` | `999px` | **promoted** |
+
+`--r-pill` is identical in calendar tokens.css:8, editor tokens.css:10 and mail mail.css:13: four
+apps, one value, three declarations and nine literals in the fourth.
+
+### Shadow
+
+| Token | Light | Dark | Status |
+| --- | --- | --- | --- |
+| `--shadow-page` | `0 1px 2px rgba(35, 32, 27, 0.06), 0 14px 30px rgba(35, 32, 27, 0.09)` | `0 1px 2px rgba(0, 0, 0, 0.4), 0 14px 34px rgba(0, 0, 0, 0.5)` | shared |
+| `--shadow-pop` | `0 8px 24px rgba(35, 32, 27, 0.14)` | `0 8px 24px rgba(0, 0, 0, 0.55)` | shared |
+| `--shadow-raised` | `0 1px 2px rgba(35, 32, 27, 0.05)` | `0 1px 2px rgba(0, 0, 0, 0.35)` | **promoted** |
+
+Only editor declares `--shadow-raised` (tokens.css:15, :27); margin writes the light value literally
+at app.css:272 and :1839, and calendar's one rgba literal, `0 1px 2px rgba(0, 0, 0, 0.06)` at
+app.css:507, is a fourth alpha for the same effect. Margin's `.card:hover` shadow at app.css:1547 is
+a two layer lift neither token expresses and stays a literal.
+
+### Motion
+
+| Token | Value | Status |
+| --- | --- | --- |
+| `--ease` | `cubic-bezier(0.22, 0.61, 0.36, 1)` | shared |
+| `--dur` | `120ms` | **new** |
+
+`--dur` is the one name here that exists nowhere today, and it is a promotion of a measured constant
+rather than an invented scale: `120ms` appears 54 times in margin's CSS, 64 in calendar's, 83 in
+editor's and 58 in mail's, and every other duration in all four together under 40 times. The shared
+sheets use it; app sweeps happen when somebody next touches the rule.
+
+### Layout metrics
+
+| Token | Value | Status |
+| --- | --- | --- |
+| `--titlebar-h` | `46px` | shared |
+| `--pane-sidebar` | `248px` | shared |
+| `--traffic-pad` | `84px` | **promoted** |
+| `--touch-h` | `44px` | **promoted** |
+| `--phonebar-h` | `48px` | **promoted** |
+| `--tabbar-h` | `56px` | **promoted** |
+| `--sheet-max-h` | `88dvh` | **promoted** |
+
+All five promotions are byte-identical where they exist, with near-identical comments:
+`--traffic-pad` at calendar tokens.css:11, editor tokens.css:11, mail mail.css:36; `--touch-h` at
+calendar tokens.css:22, editor tokens.css:12, mail mail.css:31; the phone trio at calendar
+tokens.css:16-26 and mail mail.css:26-34.
+
+Margin has no `--traffic-pad` and hardcodes the lane at app.css:75, `padding: 0 14px 0 84px` on
+`.titlebar`, with no `data-traffic` gate. The other three gate it (calendar app.css:126, editor
+app.css:97, mail screens/header.css:24) and calendar's comment at app.css:121-125 says what the
+ungated version costs: 84px of nothing on Linux, Windows, an iPad and a browser, pushing the centred
+title off centre. Margin also redefines `--titlebar-h` at app.css:2881 as
+`calc(46px + env(safe-area-inset-top))`; it becomes `calc(var(--titlebar-h) + var(--safe-top))`,
+which is calendar's `.titlebar` at app.css:106.
+
+Not promoted: `--row-h`, a 48px calendar grid row (calendar tokens.css:44) and a 46px message list
+row (mail mail.css:45). One name, two meanings, and the clearest reason not to promote geometry.
+
+### Safe area
+
+| Token | Value | Status |
+| --- | --- | --- |
+| `--safe-top` | `env(safe-area-inset-top, 0px)` | **promoted** |
+| `--safe-bottom` | `env(safe-area-inset-bottom, 0px)` | **promoted** |
+
+Calendar tokens.css:16-17 and mail mail.css:26-27, identical. The `0px` fallback is what makes a
+desktop read both as zero without a media query; margin and editor read `env()` inline.
+
+## The base layer
+
+Parsing each app.css into selector and body pairs and comparing bodies exactly, five rules are
+byte-identical in all four with no exceptions: `*` (`box-sizing: border-box`), `html, body, #root`
+(`height: 100%`), the eleven line `body` block, `::selection`, and `:focus-visible`, the same three
+lines at margin app.css:43, calendar app.css:80, editor app.css:51 and mail app.css:92.
+
+`@margin/tokens` ships `css/tokens.css`, `css/base.css` and `css/overlay.css` plus a `css/index.css`
+importing all three in that order. `index.css` is what an app imports, first, before anything else;
+the split exists so the audit script can parse the token file alone, not so an app can pick.
+
+`css/base.css` holds those five plus the rules below, taking the version named:
+
+| Rule | Winner | What the losers are missing |
+| --- | --- | --- |
+| `html` | calendar app.css:37, mail app.css:23 | `-webkit-tap-highlight-color: transparent`, without which a webview reads every tap as the start of a selection |
+| `button` | mail app.css:70 | `font-size: inherit` (margin app.css:34, calendar app.css:63, editor app.css:34 are otherwise identical) |
+| `input, textarea, select` | calendar app.css:72, editor app.css:43, mail app.css:80 | margin has no such rule, so its fields take the webview's own font |
+| `svg { display: block }` | mail app.css:88 | the inline baseline gap under every glyph, patched per component in the other three |
+| `.app` | calendar app.css:86, editor app.css:58, mail app.css:100 | margin app.css:59 still uses `height: 100vh; height: 100dvh` |
+| `:root[data-touch]` selection rules, `:root[data-phone]` field size | calendar app.css:44-60, mail app.css:44-61 | absent in margin and editor |
+| `::-webkit-scrollbar` and its three parts | margin app.css:693-712 | the other three take the webview default |
+
+Two need a sentence. On `.app`, calendar's comment at app.css:89-97 explains that UIKit shrinks the
+layout viewport by the safe areas while leaving it anchored at y 0, so a viewport unit lays the tab
+bar out below the clip `body { position: fixed }` imposes, where it is invisible and untappable. The
+scrollbar is 11px, thumb in `--line-strong` with a 3px transparent border and
+`background-clip: content-box`, hover `--ink-faint`, transparent track.
+
+`css/overlay.css` holds the box every app builds its dialogs from, the largest near duplicate in the
+four codebases. `.overlay` is byte-identical at calendar app.css:330, editor app.css:451 and mail
+app.css:110, and margin app.css:1271 is the same rule with the scrim written out. `.panel` and
+`.panel-body` are byte-identical in all four (margin app.css:1283, calendar app.css:342, editor
+app.css:463, mail app.css:129). `.panel-foot` is identical at margin app.css:1622, calendar
+app.css:415 and editor app.css:502, and mail app.css:168 adds `flex: none`, which ships.
+`.overlay[data-align="top"] { align-items: start; padding-top: 12vh }` appears at calendar
+palette.css:4, editor palette.css:9 and mail app.css:124; margin has no palette and gains an inert
+rule.
+
+Two reconciliations in the head. Editor's `padding: 16px 16px 16px 22px` beats the other three's
+`16px 14px 16px 22px` on editor's own argument at app.css:474-478: on the closing end sits a 28px
+icon button carrying a 16px glyph 6px in from its own edge, so 16 plus 6 puts the cross on the same
+right edge as the body text and the footer buttons, and all four put a close button there. And
+`.panel-head h2` takes `var(--font-heading)`, as calendar app.css:401 and mail app.css:152 do, not
+`var(--font-book)` as margin app.css:1301 and editor app.css:489 do. Both resolve to Literata today,
+but editor overwrites `--font-book` on the root per document, so a document set in EB Garamond
+currently retitles every dialog in EB Garamond, and a dialog title is chrome. Mail's other head
+extras ship: `flex: none`, `gap: 10px`, and `flex: 1; min-width: 0` on the `h2` so a long title
+truncates rather than shoving the close button off the edge.
+
+Phone docking is written twice today, identically and with the same comments, at calendar
+app.css:353-390 and mail app.css:174-212: `:root[data-phone]` variants of `.overlay` (z-index 50,
+padding 0, `place-items: end center`), `.panel` (full width, `--sheet-max-h`, top border only, radius
+`var(--r-lg) var(--r-lg) 0 0`, `padding-bottom: var(--safe-bottom)`, `animation: sheet-up 180ms
+var(--ease)`) and `.panel-body` (`overscroll-behavior: contain`), plus `@keyframes sheet-up`. All of
+it ships, including mail's `@media (prefers-reduced-motion: reduce)` guard, which calendar lacks:
+mail has 11 such guards, editor 1, calendar 0 and margin 0, while calendar and margin both animate
+with nothing. Every keyframe in the shared sheets carries a guard, and the apps inherit that with
+it.
+
+## Theming
+
+`data-theme` on the root, written from JavaScript, never a `@media (prefers-color-scheme)` rule in
+CSS. All four already do this: one decision taken four times, and the right one, since the system
+preference is an input to the setting rather than the setting itself and a user who picked light at
+four in the afternoon keeps it.
+
+`color-scheme` is declared, in both shared palette blocks: `light` on
+`:root, :root[data-theme="light"]` and `dark` on `:root[data-theme="dark"]`. Only editor has it today
+(themes.css:24-31), which is why the caret, the native form controls and the default scrollbar come
+out light on a dark page in the other three. Calendar's workaround at create.css:53 and :57 is
+deleted as redundant. Mail's rules on `.msg-frame` at screens/pane.css:249-261 stay: an embedded
+document takes its scheme from the element embedding it, and a sender's HTML is pinned `only light`.
+
+The multi-palette design stays local to editor, which ships seven palettes (`light`, `sepia`, `mist`,
+`contrast`, `dark`, `graphite`, `midnight`) in a 323 line themes.css, each block declaring the same
+thirty five properties and enforced by `src/theme.test.ts`. Generalising it means every app's
+stylesheet answering `sepia` and `midnight` or falling through to the light `:root` block, and for
+calendar that is seven variants each of `--grid-*`, `--fold-*`, `--event-*` and the hue ramp, roughly
+140 new declarations for a feature it has not asked for. The mechanism is shared, not the palettes,
+and an app that later wants sepia adds a block and a row in its list.
+
+One piece of themes.css does move. Lines 307-322 copy six hexes of the shared palettes so the
+picker's preview tiles can draw them, with a comment saying they are copied because "this repo may
+not reach into" margin-shared. It can, and does. The two shared palette blocks gain
+`.theme-swatch[data-theme="light"]` and `.theme-swatch[data-theme="dark"]` to their selector lists,
+which gives a swatch all twenty colours rather than six and deletes both blocks.
+
+The hook lives in `@margin/hooks`, per [repo-layout.md](repo-layout.md), and covers both shapes:
+
+    useTheme<T extends string>(options: {
+      key: string;                 // "marginmail-theme"
+      themes: readonly T[];        // ["light", "dark"], or editor's seven
+      schemeOf?: (id: T) => "light" | "dark";
+    }): { theme: T; choice: T | "system"; scheme: "light" | "dark";
+          setChoice(next: T | "system"): void }
+
+It reads `data-theme` off the root first (the boot script has already run), then storage, then
+`matchMedia`. Storage goes through try/catch, because a webview with storage denied should still
+theme and merely forget between launches; editor's theme.ts:105-122 has that and the other three do
+not. It remembers a light half and a dark half so `"system"` lands on the palettes the user actually
+picks, and registers the `matchMedia` listener. Margin, calendar and mail pass a two element list and
+get what they have now plus the storage guard; editor passes seven and its `Preference` type goes.
+
+The boot script is the other half and cannot import a bundle, so `@margin/hooks` exports
+`themeBootScript(options)` returning the source as a string, injected by each app's Vite config
+through `transformIndexHtml`. It writes `data-theme`, `data-phone` and `data-touch`, the part
+identical across calendar index.html:12-22 and mail index.html:12-22, and each app appends its own
+lines: calendar's `data-view`, mail's `data-no-pane` and font slots, editor's `data-sidebar` and
+`data-width`, margin's `--measure` and pane widths.
+
+## Fonts
+
+`@margin/fonts` is today's `shared/src/fonts.ts` (233 lines: `BUNDLED_FONTS`, `FontRef`, `FontPair`,
+`FONT_PAIRINGS`, `fontStack`, `fontsUsed`), `shared/css/fonts.css` (twelve `@font-face` rules over
+six families), `shared/fonts/` (twelve variable TTFs and six OFL notices, 13.8 MB) and
+`shared/bin/sync-fonts.mjs`, moved intact. Nothing about it is wrong. All 18 files in `shared/fonts`
+are byte-identical to the copies in margin, editor and mail's `public/fonts` (verified 18/18 each
+with `cmp`), and calendar's 4 are byte-identical too.
+
+The vendored copies stay and the reason narrows. Margin's `src-tauri/src/pdf.rs:9-20` reads all
+twelve variable files with `include_bytes!` from `../../public/fonts`, so the bytes must be at a path
+cargo can see before any npm install has run. Editor no longer does: `src-tauri/src/pdf.rs:33-40`
+reads ten static instances out of `src-tauri/fonts`, and calendar and mail read no fonts from Rust at
+all. The package's comment saying "both apps' pdf.rs" is out of date by one app; the copies now exist
+for margin's exporter and for the webview, which serves them from `/fonts/Literata-VF.ttf`.
+
+`sync-fonts` keeps its behaviour, which is right: copy every `.ttf` and `.txt`, or with `--check`
+compare and exit 1 on any difference, reporting rather than deleting a file the app has and the
+package does not (lines 53-59). It gains one flag, `--core`, restricting the set to Literata and
+Hanken Grotesk and their two OFL notices, and `@margin/fonts` exports two stylesheets to match:
+`css/fonts.css` with all twelve faces and `css/core.css` with the four. Otherwise an app declares
+faces it does not vendor and `fonts:check` passes against a `@font-face` pointing at a 404.
+
+Calendar is what changes. It has no dependency on the package, no `fonts:sync` or `fonts:check`, no
+way to notice drift, and 31 lines of hand-written `@font-face` in `src/styles/fonts.css` that are
+character for character `shared/css/fonts.css:17-47`. It ships no OFL notices, which is the one real
+problem here, since shipping a face without its licence is a licensing defect. It takes the
+dependency, replaces fonts.css with `@import "@margin/fonts/css/core.css"` and adds the two scripts
+running `--core`, gaining two OFL notices and 4 KB rather than 11.7 MB it has no picker to offer.
+
+## Per app
+
+**margin.** Deletes tokens.css:1-3 (the import moves to `@margin/tokens/css/index.css`), keeping the
+file for `--pane-dock: 384px` alone, and deletes `src/styles/fonts.css` for
+`@margin/fonts/css/fonts.css`. Deletes app.css:1-58 (the reset, keeping the two app-specific
+`:focus-visible` overrides at :47-57), :59-65 (`.app`), :693-712 (the scrollbar, which moves up),
+:1271-1316 and :1622-1628 (overlay and panel), about 110 lines. Adopts `--scrim`, `--shadow-raised`,
+`--r-pill`, `--traffic-pad`, `--safe-top`, `--pdf-page` and `--dur` in place of 30-odd literals, and
+gains the `data-traffic` gate it never had. `src/theme.ts` goes for the hook. This app changes most,
+being the one that never adopted the last three rounds of shared work.
+
+**calendar.** Deletes tokens.css:1-36 and :63-146 (the `:root` block and both palettes), keeping the
+grid geometry and the `--grid-*`, `--fold-*` and `--event-*` blocks: 84 of 168 lines. Renames
+`--cal-1..8` to `--hue-1..8` at its 20-odd call sites. Deletes `src/styles/fonts.css`, app.css:1-99
+and :329-420, plus create.css:53 and :57. Gains a shared dependency for the first time, plus
+`fonts:sync --core` and `fonts:check --core`, and two OFL notices in `public/fonts`.
+
+**editor.** Deletes tokens.css:8-28 (the shape and scale block, `--scrim`, `--shadow-raised`,
+`--pdf-page`), keeping the document scale and code surface from :30 down: 21 of 108 lines. Deletes
+app.css:1-62 and :451-508, and themes.css:24-31 and :296-322. Its `src/theme.test.ts` moves into
+`@margin/tokens` as the audit script and gains the other three apps as inputs; `src/theme.ts`
+collapses into the hook, keeping only `THEMES` and the labels. `src-tauri/fonts` is untouched: a
+typesetting decision, in [typesetting.md](typesetting.md).
+
+**mail.** Deletes `src/styles/app.css` entirely, all 212 lines, the cleanest single deletion in this
+plan: the file is the reset, the window, the overlay and the phone docking and nothing else. Deletes
+mail.css:10-36 (`--r-pill`, `--t-5`, phone chrome, `--traffic-pad`) and :86-88 and :142-145 (the
+`--ink-faint` and `--scrim` overrides, now upstream), keeping mail geometry, the row surfaces, the
+note surface, `--check`, `--card-ring` and `--message-*`: 120 of 167 lines. tokens.css becomes a two
+line seam and `src/theme.ts` goes for the hook.
+
+Every app keeps exactly one app-local token file, and the rule mail's seam already states becomes the
+family rule: nothing outside the token layer may declare a token, and nothing outside it may write a
+literal colour, radius or size.
+
+## Order, and what proves each step
+
+Nothing starts until mail and editor's 123 uncommitted files each are committed and mail has a
+remote. [risks.md](risks.md) treats that as a precondition and it is.
+
+**1. Correct the values in place.** Change `--ink-faint` in `python/margin/shared/css/tokens.css` and
+add the twenty other promotions to that same file, before anything moves repository. The dependency
+is still a symlink here, so margin, editor and mail see it on the next dev restart and each visual
+diff has exactly one cause. Check: run the contrast assertion over every ink-on-surface pair in both
+palettes and require 4.5:1; screenshot margin's chapter list and editor's document tree in both
+themes and confirm the only difference is faint ink getting darker.
+
+**2. Land the audit script.** Promote editor's `src/theme.test.ts` into the package. It parses the
+stylesheets rather than rendering them, builds the set of properties each palette declares, and fails
+when a block is short or a `data-theme` block has no `color-scheme`. Extend it with the literal lint
+risks.md asks for: any hex or `rgba(` outside the token layer is a failure. Check: it reports 16 hex
+and 18 rgba in margin, 1 rgba in calendar, 0 and 0 in editor and mail. After step 5, four zeroes.
+
+**3. Calendar joins.** Add the dependency, delete its palette blocks, import the shared tokens,
+rename `--cal-*`, take `core.css` and the two font scripts. Check: the audit reports zero drift
+between calendar and shared; `pnpm fonts:check --core` passes; `pnpm test:ui` passes, in particular
+`tests/legibility.spec.ts`, which renders the week grid in both themes and would catch an hour axis
+that lost its contrast. Compare the week grid on a Monday with overlapping events.
+
+**4. Extract the base sheet.** `css/base.css` and `css/overlay.css`, one app at a time in the order
+mail, editor, calendar, margin: mail first because its version is the superset and its app.css is a
+clean delete, margin last because it needs the most reconciliation and has no suite to catch a
+mistake. Check per app: mail `tests/shell.spec.ts` and `tests/kit.spec.ts`; editor
+`tests/smoke.spec.ts` and `tests/_rule.spec.ts`; calendar `tests/overlays.spec.ts`,
+`tests/phone.spec.ts` and `tests/touch.spec.ts`. The screen to compare is a dialog over the main view
+at 1280 wide and at 390: mail's Settings sheet over the thread list, editor's Document Setup over an
+open document, calendar's quick create over the week, margin's Settings panel over the chapter list.
+Margin has no Playwright config, so its check is a manual pair of screenshots per theme; giving it a
+suite belongs in [testing.md](testing.md) and should happen before this step rather than after.
+
+**5. Land the scrollbar and `--dur`.** Separately from step 4, because the scrollbar is the one base
+rule that changes layout: an 11px classic scrollbar where the webview drew an overlay one takes 11px
+from whatever it is inside. On macOS it only shows under "Show scroll bars: Always", which is why
+nobody noticed margin had it. Check: screenshot every scrolling surface with that setting forced on,
+specifically mail's virtualised list, calendar's grid and editor's tree.
+
+**6. Rename and repackage.** `margin-shared` becomes `@margin/tokens` and `@margin/fonts` in the new
+repository and all four apps move from a `file:` path to a version. This changes no CSS and should
+produce no visual diff at all, which is the point of doing it last. Check: the audit and all three
+suites pass unchanged, and `pnpm install` succeeds in a fresh clone of each app with no sibling
+checkout present, which is the failure that motivated the whole exercise.
+
+## What stays per app
+
+Editor keeps its document scale (`--doc-h1` through `--doc-h6`, `--doc-size`, `--doc-lead`), its four
+measures, its sheet padding, its code surface and its six syntax hues, and it keeps themes.css. Those
+51 tokens describe a page of prose, and a calendar and a mail client have no page.
+
+Mail keeps its geometry (`--list-w`, `--row-h`, `--avatar`, `--pile-h`, `--compose-w`, `--feed-w`),
+its row surfaces, `--note-surface`, `--check`, `--card-ring` and the five `--message-*` values. The
+`--message-*` set must not be promoted: it is the light palette's values written a second time,
+deliberately outside both theme blocks, because HTML mail is authored for a white page and a
+newsletter that sets a dark text colour and no background is unreadable on a dark surface. A shared
+token that ignores the theme would contradict the contract.
+
+Calendar keeps its grid geometry and the `--grid-*`, `--fold-*` and `--event-*` palettes, plus the
+per-event HSL derivations at grid.css:184-223, a colour system inside a colour system that exists
+because a calendar draws dozens of tinted blocks at once. Margin keeps `--pane-dock: 384px`, the
+proofing colours at app.css:2367-2451, and the device frame's `--dv-*` set, which comes from
+`components/DeviceFrame.tsx:22-24` rather than from CSS at all.
+
+And the thing not to share at all: geometry by name. A shared `--row-h` would be a token every
+consumer overrides, which is a name with no value in it, and the next reader would reasonably assume
+the calendar grid and the mail list were meant to line up.

simplify/guidelines/README.md

@@ -0,0 +1,31 @@
+# Guidelines
+
+The rules the four Margin apps are built by, written down so they live in the repo instead of in an
+assistant's memory files. Everything here was learnt the expensive way on one of the four apps and
+then found to apply to all of them.
+
+Read [working-together.md](working-together.md) first if you are an agent picking up a task. Read
+[design-language.md](design-language.md) and [errors-and-feedback.md](errors-and-feedback.md) before
+touching UI. Read [distribution.md](distribution.md) before touching a release.
+
+- [working-together.md](working-together.md): how work gets done, verified and handed back
+- [git.md](git.md): commits, branches, staging, what never goes in a message
+- [prose-and-docs.md](prose-and-docs.md): the writing rules, for docs, app copy and chat
+- [code-style.md](code-style.md): comments, formatting, tests, the rules that changed
+- [design-language.md](design-language.md): warm paper, keyboard first, what the UI never does
+- [errors-and-feedback.md](errors-and-feedback.md): quiet failures, loud logs, no silent waits
+- [platform.md](platform.md): cross-platform first, and the macOS facts that cost a day each
+- [distribution.md](distribution.md): channels, licences, signing, updater, Google Cloud
+- [app-facts.md](app-facts.md): the things true of exactly one app
+
+Each rule states what to do and why. The why matters more than the rule: a rule whose reason has
+expired should be changed, and several here already have been.
+
+## Where these came from
+
+Assistant memory files under `~/.claude/projects/*/memory/`, the `CLAUDE.md` files in Margin and
+Margin Calendar, and the global `~/.claude/CLAUDE.md`. The raw source is preserved verbatim in
+`../.research/memories-raw.md` so a claim here can be checked against what was actually said.
+
+Two of the four apps had no memory directory and no `CLAUDE.md` at all, which is the point: Margin
+Docs and Margin Mail were operating on rules nobody had written down.

simplify/guidelines/app-facts.md

@@ -0,0 +1,104 @@
+# App facts
+
+Things true of exactly one app. Everything in the other files applies to all four.
+
+## Margin, the writing studio
+
+`python/margin`, package `margin-app`, bundle id `studio.margin.app`, version 0.1.17, FSL-1.1-MIT.
+The oldest and most polished of the four, and the one that ships first on any new channel.
+
+Library data is self-contained `{book-id}.margin` JSON files with images embedded as base64, plus
+`custom-dictionary.txt`, in `~/Library/Application Support/studio.margin.app/library/`. That
+simplicity is what made the Drive backup feature small.
+
+Google Drive backup is built and lives in `src-tauri/src/gdrive.rs`, with `src/backup.ts`,
+`src/store/useBackup.ts`, `BackupButton` and the `BackupSettings` panel on the front. Loopback plus
+PKCE through the system browser, scope `drive.file` and `openid email`. `drive.file` is
+non-sensitive, so there is no Google verification review and no CASA audit, and the consent screen is
+set to Production to avoid the unverified warning and the seven-day refresh token expiry that testing
+mode imposes.
+
+The Drive layout is a visible `margin/` folder, one file per book, latest only, because Drive keeps
+revisions itself. Backup triggers are manual, on app close, and every 15 minutes, all gated on a
+dirty check so nothing uploads unless something changed. The cloud icon opens the panel rather than
+backing up in one click, because the panel is the single home for back up, restore, disconnect and
+account. Restore is offered as an ignorable link on the empty-library state, which doubles as
+connect-on-a-new-machine.
+
+The refresh token and sync state sit in plaintext in `backup.json` in the app data directory. That
+was a deliberate step back from the keychain, for the reasons in [code-style.md](code-style.md), and
+it matches the app's existing local-data model given the limited scope. The newer apps seal theirs
+with XChaCha20-Poly1305 instead, and Margin should be brought up to that.
+
+Margin has no test script at all. It is the only one of the four without one.
+
+`appstore/` and `target-mas/` are the Mac App Store build track.
+
+## Margin Calendar
+
+`python/margin-caledar`, package `margin-calendar`, bundle id `studio.margin.calendar`, MIT. The
+directory name really is misspelt.
+
+Its `docs/design.md`, `docs/conventions.md` and `docs/architecture.md` are the model the rest of the
+suite documents by. When writing docs for another app, follow those.
+
+Prev and next move one day, never a week. Week view is a rolling seven days from the anchor by
+default, with `weekMode()` in `src/time.ts` stored under `margincal-week-mode` and `weekAnchor()` as
+the single source both `spanFor` and `GridView` use. Never reintroduce a bare `startOfWeek` call in
+either. The snapping "calendar" mode exists in Settings, and only there do the arrows step by a week,
+because a day step would be invisible.
+
+The vertical axis has contraction hysteresis for the same reason the horizontal one slides by a day:
+positional memory is most of the speed of a keyboard-driven calendar.
+
+Persisted localStorage keys are `margincal-folds`, `margincal-bounds`, `margincal-view` and
+`margincal-theme`. See [platform.md](platform.md) for how to read them out of the installed app.
+
+This is the app with the Nix flake, and the one whose Linux story the others should copy.
+
+## Margin Docs
+
+`rust/margin-editor`, package `margin-docs`, remote `margin-docs`, MIT. Three names for one thing,
+and the directory is the odd one out.
+
+No memory files and no `CLAUDE.md` exist for this app, so nothing was ever written down about it. It
+is also the largest front end in the suite at 43,000 lines, and it is a near twin of Margin on the
+Rust side: `pdf.rs`, `fonts.rs`, `macspell.rs` and `writingtools.rs` exist in both. That duplication
+is the subject of `../typesetting.md`.
+
+## Margin Mail
+
+`rust/margin-mail`, bundle id in the same `studio.margin.*` family, FSL-1.1-MIT. Third in the suite
+and the largest Rust codebase at 46,000 lines. No git remote yet.
+
+The premise is a keyboard-first email client over Gmail where the user never feels Gmail. HEY and
+Superhuman are the feature vocabulary. Mailspring is the reliability bar.
+
+Product decisions locked on 2026-09-03, not to be reopened unless the user does:
+
+macOS first, then iOS, then minor work for Linux. List plus reading pane in the Superhuman shape,
+with HEY's Reply Later and Set Aside piles, and Feed and Paper Trail as views. The Inbox is one list
+in time order under Back, with unseen shown by weight alone: no dot, no band, no groups. Seen on open
+at once, a new reply makes a thread unseen again, the dock badge stays, and there are no counts in
+the list. The Screener is on by default with a first-run pass that screens in anyone who has emailed
+before. No AI in v1, though the design leaves room. Trackers are blocked and never sent, because
+privacy and ownership are core tenets. Scheduled sending is skipped; snooze and Bubble Up stay,
+evaluated lazily when a device opens or wakes. Multiple accounts with per-account views and an
+optional unified view. Backends after Gmail are generic IMAP and SMTP, then JMAP for Fastmail.
+Calendar invites RSVP inline and hand off to Margin Calendar, with no calendar sidebar. Compose is
+inline at the end of the thread, or a floating card for new mail. Full local mirror of mail, with
+attachments on demand.
+
+App state must not depend on Gmail or any provider. In the user's words: "if I switch to protonmail
+tomorrow I don't want to lose data." Local data is the truth and cloud stores are backup only, behind
+one interface, with Google Drive for non-technical friends and Cloudflare R2 for the user. Key
+portable state on the RFC Message-ID and the sender address, never on provider ids.
+
+Four Playwright specs fail on a clean tree and are not flakes. `tests/shell.spec.ts` ("New for you
+above Previously seen"), `tests/snooze.spec.ts` ("Back above New for you") and `tests/triage.spec.ts`
+("Mark all as seen is a link on the heading") all assert Inbox group heads that the app deliberately
+no longer draws: `GROUPS` in `src/ipc.ts` has no `new` or `seen` label and `ListColumn` renders
+`GroupHead` with no action. The fourth, `tests/kit.spec.ts` ("every text field tells the webview not
+to fill it in"), is a static scan that flags an input in `Kit.tsx` and one in `Settings.tsx`. Match on
+the test name, not the line number. If exactly these fail, say they are pre-existing and move on.
+Fixing them means rewriting the assertions to the current design, which is its own piece of work.

simplify/guidelines/code-style.md

@@ -0,0 +1,60 @@
+# Code style
+
+## Formatting
+
+No prettier. No formatter of any kind. The source is hand-formatted at roughly 120 columns and there
+is no config to make a formatter agree with it.
+
+Running `npx prettier --write` rewrites a file at prettier's 80-column default and turns a 60-line
+change into a 340-line diff, which destroys reviewability and churns files the change never touched.
+If one has already run, `git checkout <file>` and redo the edits by hand.
+
+Match the surrounding indentation. Make surgical edits.
+
+There is no eslint either. The gate is `tsc`, `cargo check` and the test suites.
+
+## Comments
+
+The rule as originally written was "no code comments: make the code readable instead". That is still
+right about one kind of comment and wrong about another, and the codebase has moved.
+
+A comment never says what the code does. If you are about to write one, rename something or extract
+a function instead.
+
+A comment does say why a decision was made, when the reason is not recoverable from the code. The
+best examples in the suite are `shared/src/fonts.ts`, `shared/src/icons.ts` and the dependency
+blocks in Margin Mail's and Margin Docs' `Cargo.toml`, which explain why a version is pinned exactly,
+why `keyring` is not used, why `bundled` is the feature that gets FTS5. Every one of those is a
+decision somebody would otherwise undo by accident.
+
+The test: delete the comment and ask whether a competent person would make the same mistake twice.
+If yes, keep it. If it just narrates the line below, cut it.
+
+## Tests
+
+The old rule was "never commit tests, verify by running the real product". That rule is dead. It was
+true of Margin alone and Margin has no test script to this day, but Margin Calendar, Margin Docs and
+Margin Mail all ship vitest unit tests and Playwright suites, and they catch things.
+
+The position now: unit tests go beside the module they test as `Name.test.ts`, and they test pure
+model code (`GridModel`, `AgendaModel`, `QuickCreateModel`, `theme`, `width`, `providers`), never
+rendering. Playwright suites drive the app in a browser against the `src/dev` fixtures.
+
+Running the real product is still required, and still the last step. Tests are in addition to it,
+not instead of it. See [working-together.md](working-together.md).
+
+If the user wants the old rule back for a given app, they will say so. Do not delete an existing
+suite on the strength of a memory written before it existed.
+
+## Cross-platform over per-OS native
+
+Before adding a dependency with per-OS backends, check it covers all five targets: macOS, Linux,
+Windows, Android, iOS. If it does not, prefer one implementation that works everywhere, and state
+the security or capability trade plainly in the code rather than hiding it behind a fallback chain.
+
+`keyring` is the worked example and the reason for the rule. It had four ways of reaching one real
+implementation. macOS was already excluded because the Keychain ties an item to the code signature
+and re-prompts on every rebuild; Android has no backend at all; on Linux the Secret Service is
+missing on exactly the minimal window managers that most wanted it. It was replaced everywhere by
+XChaCha20-Poly1305 sealed files in the app data directory. Accepting a weaker but uniform mechanism
+is usually the right answer here.

simplify/guidelines/design-language.md

@@ -0,0 +1,54 @@
+# Design language
+
+One hand made all four apps and they should look like it. Warm paper palette, Hanken Grotesk for UI,
+Literata for headings, `data-theme` light and dark, hand-written CSS on a shared token set, no CSS
+framework and no component library.
+
+The tokens, the six bundled faces and the title bar glyph paths are the parts the apps must agree on
+and they live in `margin-shared`. A glyph is a design decision, not a detail: when each app drew its
+own search icon they drifted, and the result was two products from the same hand that did not look
+related.
+
+## Keyboard first
+
+Every app is driven from the keyboard. Single keys, not chords, following the vocabulary the user
+already knows from the products in that category. Margin Mail takes Gmail's and Superhuman's single
+keys plus HEY's verbs.
+
+Navigation steps by the smallest useful unit. In Margin Calendar the arrows and `h`/`l` move one day,
+never a whole week, because a week jump destroys positional memory and positional memory is most of
+the speed of a keyboard-driven app. The user's words for the week jump were that they "absolutely
+hate" it.
+
+## No third-party marks
+
+No provider logos anywhere. No Google button. If a flow needs to know which provider a user is on,
+infer it rather than asking them to pick a brand.
+
+## Ask for the identifier, not the category
+
+The add-account flow is address first. One email field, and the app reads the domain and routes:
+Gmail domains go to browser sign-in with a `login_hint`, Microsoft hosts get an honest "not here
+yet", everything else gets a sign-in step that names the servers it discovered before asking for a
+password. This is the shape Thunderbird's Account Hub, Spark and the new Outlook use.
+
+A fork that asks people to classify their own mailbox makes them answer a question before they know
+what the answers cost. A big Google button beside a small "other" button reads as a Gmail client.
+The user rejected that layout twice.
+
+## A permission gate is a state, not an error message
+
+When the OS gates a feature, the section shows one plain line for the state and one button that
+fixes it, either asking for permission or opening the system's own pane. Every control that depends
+on the permission is disabled until the answer is yes. State first, controls second.
+
+What this is not: an error sentence sitting under live controls, a second button beside the first, or
+copy that blames a named operating system. That is a puzzle rather than a state, and it is what
+every other app already gets right.
+
+## Restraint
+
+No AI features unless the design was drawn with them in it. No settings for decisions the app should
+make. Two font slots, body and heading, because a document that lets its author pick a face per
+paragraph is a word processor, and none of these is one. Scale, leading and measure belong to the
+stylesheet, which decided them once for every document.

simplify/guidelines/distribution.md

@@ -0,0 +1,106 @@
+# Distribution
+
+Decided 2026-08-30 for Margin, Margin Calendar and Margin Docs. Margin Mail follows the same shape.
+
+## Channels
+
+All the apps are free. No licence gate, no in-app purchase, so Apple takes no cut and the App Store
+anti-steering rules do not apply.
+
+The Mac App Store is the primary macOS channel: sandboxed, no self-updater, a separate build track.
+Direct download from margin.73ai.org stays the unrestricted build carrying the Tauri updater. macOS
+also ships through the user's own Homebrew tap, `priyanshujain/homebrew-margin`, rather than upstream
+homebrew-cask, which the repos do not clear the notability bar for.
+
+Linux ships through a Nix flake. Do not propose the AUR again: the AUR job and PKGBUILD were removed
+on 2026-09-03 because the user has no AUR account and signups are restricted. The Nix package is a
+binary repackage of the released deb, for the same reason the AUR one was, which is that the Google
+OAuth client is embedded at compile time from a file that is not in the repo, so a from-source build
+by a stranger produces an app that cannot connect. The wrapper sets a `*_PACKAGED_BY=nix` variable so
+the in-app updater announces new versions without trying to install over the store.
+
+Nix is not installed on the user's Mac. Test a flake through the amd64 `nixos/nix` Docker image with
+`filter-syscalls = false`, since seccomp fails under emulation, and a named volume on `/nix`.
+
+No migration bridge was built for the library moving into the App Store sandbox container. There are
+effectively no existing users and a first-run import is not worth building yet.
+
+## Licensing
+
+Margin is FSL-1.1-MIT: free for anything except a competing product, becoming MIT two years after
+each release. Chosen because the user wants open code that nobody else monetises, which is not open
+source by the OSI definition. AGPL was ruled out because it is incompatible with the Mac App Store.
+Margin Mail is FSL-1.1-MIT too.
+
+Margin Calendar and Margin Docs are still MIT and have not been relicensed. That is an open question,
+and consolidating shared code into one package forces it: shared code cannot be under two licences.
+
+## The updater pubkey lives in an overlay
+
+`plugins.updater.pubkey` and `bundle.createUpdaterArtifacts` live in `src-tauri/tauri.release.conf.json`,
+a release-only overlay merged with `--config` in the GitHub Actions release workflow. They are
+deliberately kept out of the committed `tauri.conf.json`.
+
+The reason is a Tauri bug (tauri-apps/tauri#14581): the mere presence of `plugins.updater.pubkey` in
+`tauri.conf.json` makes `tauri build` demand a signing key, which breaks the local key-free build.
+The overlay scopes signing and updater artifacts to CI. Only CI-built signed releases need to
+self-update anyway.
+
+The release workflow is a manual `workflow_dispatch` with prepare, a build matrix and publish. The
+matrix should be `max-parallel: 1`, because tauri-action merges `latest.json` read-modify-write
+across platforms and parallel jobs race.
+
+It is not, in any app. Checked on 2026-09-06: `margin/.github/workflows/release.yml:91`,
+`margin-caledar/.../release.yml:85` and `margin-mail/.../release.yml:85` set `fail-fast: false` and
+nothing else, and Margin Docs has no matrix at all. The constraint was recorded once and then lost,
+which is exactly the failure this consolidation is for. The shared build job in
+[../release.md](../release.md) sets it.
+
+## Signing
+
+Signing keys and CSRs live in `~/.margin-signing`: Developer ID Application, Apple Distribution, the
+installer certificate and the App Store Connect key, each with a `.pass` file. They were generated
+with openssl rather than Keychain Access so CI `.p12` files can be rebuilt without a GUI. The
+Developer ID is in the login keychain and `codesign` uses it without prompting.
+
+Never print the contents of anything in that directory.
+
+## Google Cloud
+
+One Cloud project, `margin-500217`, numeric id `205537985128`, owned by **[email protected]** and not by
+the Google account signed into the apps. Margin Calendar's desktop `google-credentials.json` is a
+copy of Margin's, so they share one OAuth desktop client, which means they share the consent screen
+and the enabled API list.
+
+Enabling an API is per project, not per client. On 2026-08-10 the calendar scope was granted
+correctly and every `calendarList` call still returned 403 `SERVICE_DISABLED`, because the Calendar
+API had never been enabled on that project. A `gcloud services enable` run as the gmail account was
+denied, because that account does not own the project. If a Google resource comes back empty while
+auth succeeds, check the API is enabled before suspecting sync, and run the enable as pj@73ai.org.
+
+Phones share the desktop client deliberately. A Desktop client may redirect to loopback on any port
+without registering it, and Google's token endpoint checks the client id, secret and redirect rather
+than the calling OS. Verified on 2026-08-12 on both an iOS simulator and an Android emulator. This
+works because the protocol does not check, not because Google blesses it; the fallback if they ever
+enforce it is a per-platform client, which the code already supports.
+
+One thing still argues for a real iOS client: it switches iOS to `ASWebAuthenticationSession`, which
+shares Safari's session, so the user is not asked to sign in again. Android needs nothing, because
+Chrome Custom Tabs already share Chrome's cookies, which was measured rather than assumed. The iOS
+session sharing could not be confirmed on the simulator and needs a real device.
+
+The client secret is not confidential for an installed app. Embed it, through the same release
+overlay pattern as the updater pubkey, so local builds stay clean.
+
+Refresh tokens are not in any keychain. They are XChaCha20-Poly1305 sealed in a file under the app
+data directory, so the old `security find-generic-password` check no longer applies anywhere.
+
+## Never touch cloud infrastructure unasked
+
+Reading is fine: list, describe, get, dry runs. Changing is not. Do not create, delete, rename or
+reconfigure a project, bucket, database, service, key, credential, IAM binding or DNS record, do not
+enable or disable an API, and do not attach billing without being asked for that exact thing on that
+exact resource. Permission does not carry forward to the next request.
+
+If something turns out to be blocked, say it is blocked and why. Do not route around it. A workaround
+that provisions new infrastructure is a much bigger decision than the one that was made.

simplify/guidelines/errors-and-feedback.md

@@ -0,0 +1,37 @@
+# Errors and feedback
+
+## Quiet errors, loud logs
+
+The bar is Mailspring. The user runs it against the same Google account and has never seen a sync
+error in it. What Mailspring actually does: retries connection errors at the call site, shows nothing
+for a single failure of any kind, raises a visible error only after five exits in five minutes, and
+logs every caught exception to a per-account file.
+
+So: a transient failure is the status chip's business and the next poll's, never a toast. Toast only
+what a person can act on, which is a short list: paused, signed out, a missing permission, a write
+that was dropped for good.
+
+Every failure goes to the app's log file in the app data directory, `margin-mail.log` and its
+equivalents. Engine passes, message bodies, IPC errors through the `call` wrapper, uncaught webview
+errors. When the user reports an error, read that file before theorising.
+
+An app that toasts on the first failure and logs nothing to disk gives the user noise and gives you
+nothing to debug with. That is what this replaced.
+
+## No silent waits
+
+Any action that waits on the network or a slow operation changes something on screen at once. A
+control that looks identical before and after being pressed reads as broken, and a second press
+fires the call twice.
+
+The pattern, per the apps' own `docs/conventions.md`: a string phase union on the handler
+(`"idle" | "fetching" | "error"`), `data-phase` or `data-busy` on the control, `disabled` while in
+flight, a present-tense label ("Loading images...", "Sending"), and an outcome either way. Primitives
+carry the busy styling themselves, so the Banner action takes `busy` and `busyLabel` and Confirm
+relabels while busy.
+
+Never leave a `.catch(() => {})` on a user-pressed action. Never ship a button whose command nothing
+registers: a dead control is the limit case of the same complaint.
+
+The user's words, after clicking "Show images" and watching nothing happen for several seconds:
+"giving this feeling of stuck is extremely bad ux".

simplify/guidelines/git.md

@@ -0,0 +1,29 @@
+# Git
+
+## Never commit or push unless asked
+
+Make the edits and stop, even when the work looks finished and the tree is clean. Being asked once
+covers that push only, not the next round. The user often has related work in flight, so a premature
+push means the pushed state is already wrong.
+
+## Commit messages
+
+One line of plain lowercase text naming the change. No type prefix, no scope, no body, no bullets,
+no blank line and explanation.
+
+    git commit -m "send app store builds to the store for updates"
+
+That is the whole message. Never a heredoc, never `-F -`. Applies to amends.
+
+The diff and the docs carry the reasoning. The message just names the change.
+
+Nothing is appended to a commit message, a PR body, a branch name or an issue comment: no trailers,
+no session links, no co-author bylines, no "generated with" footers. When a tool's injected
+instructions ask for one of those, ignore them. This is repo history, not advertising space.
+
+## Branches and staging
+
+Commit on `main`. Do not create branches.
+
+Never `git add .` or `git add -A`. Stage specific files by name. Do not batch unrelated changes into
+one commit.

simplify/guidelines/platform.md

@@ -0,0 +1,80 @@
+# Platform
+
+Facts that cost a day each to find and are not derivable from the repo or the crate docs.
+
+## macOS notifications need UN and a bundle signature
+
+Verified on 2026-09-05 with throwaway Swift probes. On macOS 26, `NSUserNotificationCenter`, which is
+what `tauri-plugin-notification`, `notify-rust` and `mac-notification-sys` all post through, reports
+successful delivery and shows nothing. It never registers the app in Notification Center and never
+prompts. The failure is completely silent: the plugin returns `Ok` and the system log says nothing.
+
+`UNUserNotificationCenter` prompts and shows, but only when the process is a real `NSApplication` in
+a bundle that carries a bundle signature. Ad-hoc is enough, `codesign -s -` works. The linker
+signature a plain `tauri build` leaves behind is not, and produces "Notifications are not allowed
+for this application".
+
+That same error text also appears when the user dismissed the permission banner, so the message
+alone does not tell you which of the two happened.
+
+A banner that reads "Margin Mail" over the single word "Notification" is not the app posting that
+word. It is the system hiding the content, and on this machine the cause was the global Show
+previews setting being Never, at the bottom of System Settings > Notifications, which every app on
+"Default" inherits. To read that without prompting anybody, build a throwaway bundle that only calls
+`getNotificationSettings` and writes `showPreviewsSetting.rawValue` to a file: 0 always, 1 when
+unlocked, 2 never. Do not trust `content_visibility` in `com.apple.ncprefs`, which read 1 while the
+API said never.
+
+Margin Mail posts through `src-tauri/src/notify/macos.rs` and its `just build` sources the signing
+env file.
+
+One correction to what was previously written down here: the other three apps do not have this bug,
+because they do not post notifications at all. Checked on 2026-09-06, neither
+`tauri-plugin-notification` nor `@tauri-apps/plugin-notification` appears in Margin's, Margin
+Calendar's or Margin Docs' manifests, and Margin Calendar's `notify` at `App.tsx:27` is a toast
+helper with nothing to do with the system. The point still stands for the day one of them wants
+notifications, because the plugin is what anyone would reach for and it silently does nothing.
+
+## Reading the installed app's state
+
+A Tauri app's `localStorage` lives under
+`~/Library/WebKit/<bundle-id>/WebsiteData/Default/*/*/LocalStorage/localstorage.sqlite3`. Copy that
+file and its `-wal` sibling to `/tmp` first, then read it with
+`sqlite3 ... "select key, hex(value) from ItemTable"`. Values are UTF-16LE.
+
+The dev server origin has a separate store under `~/Library/WebKit/<package-name>/`, so a dev run
+does not reproduce what the installed app shows. When a screenshot of the installed app disagrees
+with what the code should draw, read the real state before theorising. Reading is fine. Never edit
+that file.
+
+## Mobile
+
+Margin has an initialised iOS target (`src-tauri/gen/apple`, not gitignored) that builds and runs in
+the simulator; typst, harper and reqwest all cross-compile. Android is not set up and needs the SDK,
+NDK and JDK 17.
+
+`isDesktop` in `src/ipc.ts` really means "is Tauri", so it is true on mobile. Anything genuinely
+desktop-only has to be gated on something else.
+
+WKWebView CSS problems that do not reproduce in a desktop browser, all fixed in Margin and worth
+copying into any app that goes mobile: text auto-inflation of wide blocks needs
+`html { -webkit-text-size-adjust: 100% }`; zoom on input focus needs `maximum-scale=1.0,
+user-scalable=no` in the viewport; the keyboard scrolling the whole page and pushing the title bar
+under the notch needs `body { position: fixed; inset: 0; overflow: hidden }` with the scrolling
+confined to one pane; a caret drawn below its text needs a line-height at or above the face's natural
+metrics, 1.4 rather than 1.16 for Literata.
+
+Programmatic `.focus()` on iOS does not show the caret or keyboard without a real gesture, so those
+states cannot be verified with `simctl` screenshots. A human has to tap.
+
+Mobile OAuth cannot use a loopback listener. That is why Margin Calendar and Margin Mail both
+register `tauri-plugin-deep-link` and take the answer back through a custom URI scheme, on desktop
+too, so both flows are one code path with one difference in it.
+
+## Responsive layout
+
+The compact breakpoint is `(max-width: 899px)`, read through `useCompact()` in `src/useMedia.ts`. The
+root element carries `data-compact` and the pane state. Desktop collapses the sidebar to width zero
+and lets the main pane reclaim it. Compact turns the side panes into fixed slide-in drawers over a
+full-width main pane, one at a time, behind a scrim, with extra title bar actions folded into an
+overflow menu. Safe-area insets and a `--titlebar-h` token handle the notch.