margin/simplify/.research/docs-conventions.md

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.