pj/margin
1
0 Fork 0
mirror of https://github.com/priyanshujain/margin.git synced 2026-10-05 04:27:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

some more fixes

Browse Source
This commit is contained in:
pj committed 2026-10-03 22:48:49 +05:30
1 parent 7a3c04f170
commit 2b86a407ba
63 files changed
+12172 -44
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

simplify/.research/memories-raw.md
+976
View File
@@ -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
```