Decisions

Decision records will live here.

• No Separate Interview Event Log — why the app does not keep a separate interview-event log table. (Amended 2026-07-31 — its audit revisit clause fired.)
• The Turn Audit Log Is a First-Party Table — why the interview audit trail moves off stored tool calls into an append-only interviewTurnEvents table recording the full agenda and the model's raw structured output, and why neither saveMessages: "all" nor inputs-plus-a-hash can carry it.
• Deterministic Write-Safety For Hosted App Flow Conditions — why the hosted app gates writeModule with evaluateFlowCondition while local no-runtime skills remain agent-interpreted.
• References Bind To Stable IDs, Not Handles — why stored references point at a stable identity with the handle as display hint, and why the Obsidian-style wikilink model was abandoned.
• Block Edits Run Inside One Envelope — why the block-editing mutations share one bracketing seam that owns load, guard and stamp, including the historical ordering transition it once enclosed.
• One Block Notification Channel, Two Error Audiences — why a refused block edit crosses the wire as structured ConvexError data rather than a stringified throw, and why the agent's in-band writeModule outcomes are never merged into the same channel.
• The Three Selection Cells Are Not Duplicates — why canvas selection keeps three state cells, and why emitSelection is a resolver over the snapshot rather than a translation layer to be collapsed.
• Component File Partitions Must Preserve Locality — why deep extraction remains the default, when a single-consumer partition is allowed for navigation, and which props-shaped seams are still refused.
• The Folio Tiers Share Parts, Not a Recipe — why there is no shared folio card composer: a shared behaviour is promoted into the Stack molecule as a slot default the tier mounts and wires, never a flag-configured shell. (Amended 2026-09-14: the tiers diverge on purpose only where a reason is recorded at the call site; two identical assemblies are a copy to promote, not a divergence.)
• Container Screens Share One Anatomy — owner rulings 2026-09-14: Workspace and Project are one screen built from neutral compound parts, the parent folio owns the portal holding its children, container screens keep the Goldie sidebar, a child card opens on click while its own controls keep their actions, and manual tag entry is retired.
• Interview Turns Run gpt-5.6-luna at reasoningEffort "none" — why the interview agent moved off gpt-5-nano, why reasoning effort was dropped to "none" rather than tuned, and what the ping-instrumented eval A/B actually showed.
• Interview Writes Stay Object-Encoded — why the array-shaped writes encoding is not adopted despite a real −25% output saving, and why the key-discriminated union that would fix its silent value corruption is strict-legal and is rejected on cost, not impossibility.
• Independent Block Agent Threads — why each working-document block owns a reactive Goldie conversation separate from the document agent thread.
• Interview Names the Pass, Not the Agent — the vocabulary rule for retiring "interview" as the document agent's name, the keep/rename ledger for every name that borrowed the word, and why the schema-touching renames wait for the backend gate.
• Names Are Projections, Not Stored Copies — why a block's or field's displayed name is computed live from label, handle, or content, why the display is the editor, and why the Control Panel label row was removed.
• One Domain Rulebook, Concept-Sliced Convex, Standard FSD — why the codebase uses one runtime-free canonical domain package shared by frontend and Convex, concept-sliced Convex adapters, and standard Feature-Sliced Design, which brand promise each structural rule serves, and what has actually migrated versus what remains target.
• Folio Operations Resolve Once — why Folio action availability resolves once in the domain, then projects to menus, agent instructions, and server enforcement without collapsing distinct invariants into generic CRUD.
• A Selected Document Paints a Black Spine and No Rail — why the outer Folio marks selection with a black spine and the quietest tint in the palette, and why it never paints the containment rail a module does.
• Content Writes Receive One Server-Constructed Authority — why content mutations resolve their current actor and capabilities from a server-held Document session instead of accepting createdBy from the client, and why that seam is not yet authenticated identity.
• Folio About Is Schema-Bound YAML — why every Folio renders locked YAML keys with typed editable values, why Guide is one fact projected onto two faces, and why Document keeps the shared Control Panel shape without mounting a second conversation.
• Tinted Chrome, White Paper — why every folio kind fills the shared Header, why chrome carries a tint while anything that prints sits on white (the tint is the seam), and why Builder capability gates every header and card — a Maker or Reader sees the paper alone.
• The Control Panel Is Drawn With a Neutral Shared Shell — superseded 2026-09-28 (the per-card panel and WorkPanel are retired); why the panel body was promoted into Shared UI, how the three tiers hand it their own words instead of a tier flag, and why the source diff moved with it.
• Two Columns — Glyphs Print, Edges Do Not — owner ruling 2026-09-15: words that print line up letter to letter on the glyph column; screen chrome (cards, buttons, chips, the composer) lines up frame to frame on the same x and gives its own contents a chrome inset. Bounds the 2026-08-09 print ruling to words.
• Buy the Mechanics, Build the Document Semantics — which parts lean on established packages (editor mechanics, validation, function wrappers, ordering keys, diffs), which stay custom because they are the product's own rules, and which frameworks are deliberately not introduced.
• Sealed Versions Are Immutable; Derivation From Them Stays Open — owner ruling 2026-09-04: only the live head is edited in place, a card showing a sealed edition offers no mutating operation, and whether a sealed version may later seed a new editable lineage is deliberately left open with every lineage fact preserved.
• Delete Is a Folio Fact, Not a Placement — owner ruling 2026-09-04: a deleted Folio leaves the live canvas, newly sealed schedules and ordinary search, keeps its live pin for Put back, stays in every older sealed edition, and is never confused with Remove.
• The About Face Writes Identity and Guide — owner ruling 2026-09-06: the typed write a person's guide and name edits reach; a block's material is edited on its own face; Goldie keeps her own door to numbering and conditions. Since 2026-09-10 the face itself is retired (GB-221) and the fold and header carry the write.
• Duplicate Copies the Live Draft, Whole and Fresh — owner ruling 2026-09-06: a copy is recursive, clears collected answers only, takes the next free handle and " (copy)", records its lineage, always copies the working draft, and a whole document duplicates through the creation door.
• Root Documents Are Created Through an Interim Browser Door — owner ruling 2026-09-06: until sign-in exists, New document mints the document, its sealed v1, its live head and a bound session for this browser in one transaction; a stated temporary door that sign-in replaces.
• A Library Is a Shelf, Not a Folio — recorded 2026-09-06 before Stage E: a publication names an exact sealed edition, searching and selecting create nothing, insertion or an accepted proposal materialises an independent derived Folio, and the two open owner questions (Library master vs original; label snapshot) are filed rather than chosen.
• Info Lives on the Card; the Panel's ⓘ Becomes Search — owner ruling 2026-10-09: the panel's About view is retired; a Block or Module's menu gets Info, opening it in place as its Goldie card (clause, guide, title bottom left); the panel header's ⓘ becomes 🔍 Search.
• Add Opens in Goldie's Panel — owner ruling 2026-10-09: Add swaps Goldie's conversation for a search with the All + filter, ticks, Cancel and Add, as ⓘ About swaps it; a ticked document previews on the page as a pending card. Replaces the Add modal.
• A Library Says Where It Is Used — owner rulings 2026-10-09: seats still decide who can see a Library; each Library is used Everywhere or Only in chosen Projects, set from a Join | Use in modal on the Library or from a Project's Libraries menu; the Add modal is one search with the All + filter control. Retires Active Libraries.
• Library Access Is Your Own Seat, Never the Project's — owner ruling 2026-10-04: only your own seat (owned, added, joined, bought) opens a Library; access to a Workspace, Project or Document lends none, Goldie included; a folio's Library list only narrows. Replaces share-dialog-by-page rule 3's shared-Library bullet.
• A Local Test-User Door, Locked Five Ways — owner ruling 2026-10-04 (option A): /dev/sign-in signs an agent or the owner in as user_dev_tester or user_dev_guest without WorkOS; dev build, localhost, one-hour tokens, a deployment holding DEV_LOGIN_JWKS, and user_dev_ subjects only.
• Library Membership Is an Index Card; Access Is Held, Not Copied — owner rulings 2026-09-25: one entry row per Library and Folio is the only membership truth and the export prints the list, saving files a snapshot into a separate Library master, a saved Project carries everything beneath it and any part of it can be inserted alone, and Library rights are held by a firm-ready holder while only people are built.
• The Folio Canvas Shows a Listing — owner rulings 2026-09-07: one canvas screen for every folio kind, a child with a route is a card and one without opens in place, the canvas reads a listing so a Library can use it, Home is the canvas of the session's binding, and a Maker invited to a folio sees only its subtree.
• The Goldie Card — owner rulings 2026-10-03: one flip card for every list (Projects, Documents, Libraries, a Library's Documents); each corner one job; first tap selects, second opens; rename on the card only; Goldie's edits accepted or rejected for the whole card; lists sortable by drag and drop with the order kept per person, new cards on top, a Library's own Documents in the publisher's order; no side-panel About for a listed card.
• One Page Header for Every Page — owner rulings 2026-10-01: one header component on every page; the header speaks of editability, sharing and publishing only; Share at every level, Save to Library on Documents and below; a seat inherits down; the Draft / Published latch and the editability badge are removed.
• Work Bar Shows Where You Stand — owner rulings 2026-09-10: the Work Bar's title slot is one crumb, where you came from (the parent's kind and name as a link one step up), never the item's name, which its own card carries; a container's page is the list of its children; the document's card stands above the paper, not on it; and the level above a Document is the Project, whose page is the project folio with its documents filed beneath it.
• Maker Fills, Builder Builds — owner ruling 2026-09-11: a Maker only fills fields and never edits a block; the per-block lock is removed, not inverted; a Maker sees no control that is not a field; Reader stays on the ladder unbuilt; export is the read-only copy for everyone else; the role names are an open question filed separately.
• Which Libraries to Search Is Chosen on the Search Card — owner rulings 2026-09-28 (GB-245): the search card is the only place to choose; chips filter this search only; "+ More Libraries" opens the Libraries page; once a chip changes, "Keep selection" saves the chips one level up; the menu row and "Inherited from" notes are gone.
• Builder Goldie Lives in the Side Panel — owner ruling 2026-09-28: the Builder talks to Goldie in the Maker's fixed side panel about the selected item; one conversation per document, each turn anchored to the selection at send time; no per-card trigger.
• The Side-Panel Goldie Is Maker Only — superseded 2026-09-28; owner ruling 2026-09-15: the interview lives in the side panel and the side panel is drawn only for a Maker; in Builder mode Goldie is the in-folio agent on the card, proposing edits to that folio and its children and new folios below.
• One Goldie Per Folio, One Agent Definition — owner ruling 2026-09-15: every folio has its own Goldie thread and authority, built as one agent definition with the folio as its scope parameter; she is briefed on the whole document every turn and may read any folio, while what she may propose is enforced at the filing gate.
• Factory Log — the dated rulings, measurements and incidents behind the agent rule sheets (Repository Operations, Planning Workflow), moved out of the rules on 2026-09-12 so agents read current rules only; includes the verification-tier ruling.
• The Folio Carries the Product — owner sittings 2026-08-28: the farm bet is two stakes — the Folio carries all five jobs and the Stack is replaceable furniture; AI parity is the defensible core; a Builder authors a kit, a Maker is interviewed, and the interview is a projection of the same folios the document prints from.
• Frame Rulings, August 2026 — rulings settled in-sitting that must not be re-raised: module is the reuse grain and block the clause; the human rules the glyph menu and Goldie keeps the About ledger; the glyph menu is the registry office; locks inherit top-down, deny structure and prose but never value-filling, are derived not stamped; and the September build-order rulings in one line each.
• Refuted Deepening Candidates — the architecture-deepening ideas checked and ruled out, voided by later work, or superseded by GB-152, recorded 2026-09-12 when the candidates register retired so no survey re-raises them; open candidates are Backlog tasks labelled deepening.
• Library Search Is a Conversation — rescued 2026-09-12 from the retired permissions-and-locking plan (R5): searching the library is asked of Goldie, never a modal; candidates render in place as spine-less sibling blocks (S1–S6); no search backend exists today.
• Unprompted Turns Have a Bound of One — owner ruling 2026-08-10, rescued 2026-09-12 from the retired agent-turn-policy plan: Goldie may volunteer once on Form and then must wait, never on Document or in the block panel; derived from the thread's last message, never stored; why not a counted N; the ghost prompt is policy-generated by construction and whether it ever goes quiet stays open.
• The Folio Schema — the settled Folio storage shape recorded 2026-09-12 when the two Folio plans retired: six recursive tables, the twenty-nine binding constraints with their owner rulings, the printed About card grammar, the six-pillar review lens, and the two remaining stages (proposals and Goldie address Folios; docs made wholly Current) that Backlog tasks own.
• Tiptap for Content Editing — recorded 2026-09-12 from the retired editor plan: a restricted Tiptap editor behind an authored-Markdown boundary, one editor per content block, semantic round-trip, no collaboration, and the harness-then-spike order of work.
• Builder First, Before Sharing — recorded 2026-09-12 from the retired MVP plan: why one Builder making a versioned Document is the first proof, the six sequencing decisions, and what stays outside that proof.
• The Workspace Is Home; the Project Is the Sharing Grain — owner ruling 2026-09-13: one workspace is minted for every person and its canvas is their home screen; the Project is stored beneath it, retires the hard-coded placeholder, and is the tier a person shares; the organisation is the access record and capability rules, never a Folio kind; identity comes first; and no read may infer the current workspace or project from the person.
• Goldie Finds a Clause and Stages It — owner rulings 2026-09-30 (GB-245): Goldie searches the Libraries by index card and never reads or retypes a clause; her one best pick lands through the same staged copy the search card makes; what the conversation staged stays within her reach; search ranks by the selected folio and document but filters by typed text only; supersedes S2 and S3a of Library Search Is a Conversation for Goldie.
• Proposals Wait for an Explicit Accept — owner ruling 2026-10-07: nothing Goldie proposes applies without an explicit accept; a new proposal joins the queue rather than accepting the open one; each step is decided on its own from a resolution bar above her composer, in step with the review gutter; no Accept all on the bar or in the chat's list of changes, and asking about a proposed card accepts nothing (2026-10-08).