Field notes · 35 chapters
Notes from building
The Margin.
The In practice chapters follow one real job through the app as it is today, with the made-up household from our demo workspace. The rest tell how we built it: what broke, how we fixed it and what each fix cost, including the mistakes.
Follow by RSSIn practice
One real job, start to finish, in the app as it is today.
- 28A family Sunday reset: the week's dinners, the shopping list and the choresOne Sunday afternoon at the Riveras' table: five dinners planned, a shopping list nobody typed, a store run with no signal, and chores that pay only when a grown-up has seen the job done.4 min read#meals#shopping#chores
- 29Co-parenting across two households: sharing a child's chores, pocket money and calendarWhen Maya and Leo split the week between two homes, each parent keeps their own household in The Margin, and three switches decide what crosses between them.4 min read#family#permissions#privacy
- 30Tracking income, spending and personal debts so the month adds upLate in September, with the salary not due until the 28th, Alex's budgets look either fine or impossible depending on what you measure them against. Here is how The Margin measures, and how two debts with two friends get settled.3 min read#debts#money
- 31Planning a product launch with an AI agent in an Agent PactAn outside AI agent and one person plan a small shop's launch on a shared page, and the one question that matters waits for the person to answer it.4 min read#pacts#agents#mcp
- 32Scanning a school permission slip and finding it weeks later by one wordA two-page field trip letter goes into The Margin as a scan named "Scan, Sep 9", and a month later a search for one word inside it finds it.3 min read#notes#search#ai
- 33Running a four-person team's week on boards, rules and the Team hubMonday to Friday with a small team in The Margin: one saved view each, cards that wait on other cards, a rule that hands work over, and an agent that writes the Monday digest.3 min read#team#boards#agents
- 34What The Margin's Vault does and does not protectAlex hides a surprise-party plan in the Vault of a shared family workspace. What that keeps off screens and away from AI, what is encrypted, and when to use a personal workspace instead.4 min read#the-vault#privacy#security
Origin
Why this exists at all.
Decisions
The choices we faced, and what we picked.
- 01The case for an all-in-one productivity appEvery good productivity app picks one job. We built tasks, notes, budgets, meal plans and family chores into one workspace, and here is what that costs.4 min read#origins#architecture
- 04MCP tools in practice: our assistant calls the same toolsInstead of a chat panel with a private back door, every capability in The Margin is an MCP tool, and Margin Intelligence, outside agents and tests all call the same ones.4 min read#ai#mcp#architecture
- 05Permissions first in a shared family workspaceHow we designed sharing for a household app: board membership as the unit, per-item shares, workspace-scoped queries, and a Vault the assistant cannot read.4 min read#permissions#privacy#architecture
- 06Why our AI agent runs outside the Next.js appAn agent turn takes fifteen seconds to two minutes; a page render takes milliseconds. Why we split the assistant into its own Python service, and what that boundary has cost us.3 min read#ai#architecture#python
- 07AI assistant memory you can read, edit and deleteAn assistant that remembers everything is surveillance, and one that remembers nothing is a stranger every morning. How we decide what an AI keeps about you, and why you get to see the list.3 min read#ai#memory#privacy
- 08Google OAuth verification rejected: why narrower scopes were rightGoogle rejected our OAuth verification for asking for full Calendar and Sheets access. They were right. How calendar.events, drive.file and the file picker made the integration smaller and easier to trust.3 min read#integrations#oauth#privacy
- 18Four scratch pads: how one page of game prototypes became four real gamesFour playable games on one 111 KB HTML page, rough enough to call scratch pads, and the 60,000 lines it took to make them real.4 min read#games
- 23A game mind that doesn't burn tokens: two tiers of character AIThe break room's characters play and talk with a local mind that runs every frame for free, and ask Margin Intelligence for help only outside play, through a shared cache, under hard caps.5 min read#games#ai
- 24Calm or competitive: 48 ways to play seven games, on one rulebook eachThe break room began with a law against lives, clocks and streaks. Then the founder asked for both moods. Every game now has calm modes and competitive ones, as rule switches on one engine, with streaks that never nag.3 min read#games
Mechanism
How the parts work.
- 02How to make a web app work offline: SQLite in the browserWe put a real SQLite database in the browser in week four. Then we learned that DevTools offline mode does not cover service worker fetches, and our PWA was dead in airplane mode.4 min read#offline-first#architecture
- 03Two planes: what syncs offline and what the server must decideIn a local-first app, your notes can live on the device but your billing tier and role cannot. How we split sync from server authority, and why it costs seven files per table.4 min read#architecture#sync
- 09Embeddings for semantic search kept matching near-duplicatesNear-duplicate cards sit closest in embedding space, so our AI connection engine kept discovering a weekly meal plan. How distill-then-embed, hybrid search and a recurrence filter cut the review queue from ten suggestions to three.4 min read#the-mind#ai
- 11Building a personal knowledge graph that links peopleOur first relationship-graph run drew zero edges. How co-mentions became person-to-person links, how we merge duplicate names with a human in the loop, and how a plain-text guidance box lets you correct the AI.4 min read#the-mind#ai
- 13Why LLM summaries of long notes missed 98% of the textA 238,000-character note had been summarized from its first 4,000 characters. How a gut feeling led us to silent truncation in our distill-then-embed pipeline, and the stride sampling that fixed it.3 min read#the-mind#ai
- 16Why our AI agent got stuck in a loop, and the context fixAsked to move a workout plan by a week, our assistant said 'let me do it now' hundreds of times and never did it. The model was fine. The chat engine kept feeding it its own dithering.4 min read#ai#the-mind#autopsy
- 19One scene, two canvases: the same game code on Canvas 2D and SkiaEvery break room game is written once and drawn by two different renderers. A pixel conformance suite keeps them honest, and a contrast test keeps every theme playable, including themes that do not exist yet.5 min read#games#design
- 20Sound you can license: every recording CC0, measured and ledgeredThe prototypes beeped. The games needed recorded sound: every file public domain, hashed, measured for loudness and pitch, looped without a click, and heard by a person before it shipped. Where no recording fit, a generated take now plays beside it, labeled as one.6 min read#games#sound
- 21Puzzles proven solvable: pairing every level generator with a solverEvery level in the break room is generated from a seed, so nobody hand-checks them. Each generator ships with a solver or a bot that proves thousands of its levels can be finished, on every test run.5 min read#games
- 25Seasons and surroundings: game scenery that follows the real calendarEach break room game has its own places to be played in, dressed for the actual season where you are, drawn from the current theme, and forbidden from ever making the board harder to read.4 min read#games#design
- 26A camera made of paper: cinematic transitions for five-minute gamesPage turns, sketch-ins, match cuts from the shelf, focus pulls and a rewind scribble: how the break room borrows a game camera's craft, speaks in The Margin's own materials, and lets you skip every second of it.3 min read#games#design
Trust
What broke, and what it cost.
- 10An AI privacy bug: sealing a board did not seal its cardsWe built a Vault our own AI cannot read. Then we found 110 sealed cards indexed openly by the background indexer, because sealing a board never reached the cards on it. How we fixed containment.3 min read#security#the-vault
- 12Silent failures: the AI memory feature that never saved a rowOur assistant's remember feature failed on every call from the day it shipped. Fail-soft error handling, a busy table and mocked database tests hid it. How we found it and what changed.2 min read#reliability#ai
- 14Nothing deferred: a day of fixing an AI memory engine end to endA noisy review queue, pronouns mistaken for people, and a self-audit that found real holes. One long day where every finding was fixed and shipped instead of filed.3 min read#culture#the-mind
- 15A brain that knows what changed: keeping notes currentNotes freeze in the tense they were written in. How the Mind retires old facts, re-tells stale summaries, and notices what you stopped mentioning.3 min read#vision#the-mind#ai
- 17The face in the margin: a character instead of a spinnerMargin Intelligence needed a way to show it was thinking without a loading spinner. On drawing a character in a few ink strokes and letting its expression be the status.3 min read#design#craft#the-mind
- 22Fair by proof: rebuilding Volley so no character always winsVolley had a court with no rules, opponents whose results never changed, and a ball that scored for you off the far wall. The rebuild starts from simulations and ends at a balance matrix every pairing has to pass.4 min read#games
- 27The back pages: a new break room, and two classics rebuilt by simulationThe break room became the last pages of a planner, with a small live window onto each game in the margin. Stack was too hard and Catch the Tasks ended at the same moment whatever you did; simulations said why, and the rebuilds were tuned until the numbers changed.4 min read#games#design