# πŸ€– The Oficina home The suite's glue: identity, directory, provisioning, person preferences. Consumed by `oficina/sheets` and `oficina/docs`. **It is not an application and holds no documents.** This file is binding. Where it disagrees with a general skill, this file wins. Where it disagrees with the design spec, the spec wins and this file is wrong β€” fix it in the same commit. **The design:** `docs/superpowers/specs/2026-08-30-home-design.md`. Β§1 is the settled-decisions table: dated, attributed, with the rejected alternative beside each. --- ## The one rule > **The home is glue: thin, blind, replaceable. It knows that you exist and > where your teams are. It never stores a readable address, and it never > retains what is in anything.** **"Retains", amended from "learns" on 2026-09-05** β€” spec ruling 18 and `design-activity-pull`, approved that day. The falsifiable form is unchanged **by that amendment** β€” ruling 23 later changed it, and the form above is the current one. **It means holds without a bound**: the home does see titles and does keep them in RAM across requests, bounded by a TTL and a hard maximum; at rest is the unbounded case, and that is what it never does. "Blind" above is Factor XI's category label, not a claim it never sees one. Spec Β§0 carries the full gloss. The falsifiable form: **publish this database in full and the worst anyone learns is how many people exist, what their teams are called, which person refs belong to which team, and which of them own it.** No document. No cell. No readable address. **"And which of them own it" arrived with ruling 23** and is the whole cost of the membership roster: an owner row names a person ref from one team plus a fact that is usually public, where the old wording needed several teams and an outside fact. Spec Β§0 and Β§3.3 carry the full reasoning. *Two absolutes were argued and lost, and stay lost:* **"never stores your address"** β€” a magic link's address is at rest between send and click, sealed (Β§3.2), not absent β€” and **"some unidentified person"**: a team-set fingerprint plus one outside fact names the row (Β§3.3). Three gates enforce it (Β§12; Β§13 step 1 lists all three): a **plaintext grep** over the raw SQLite file and WAL **plus this app's store objects**, against a seeded corpus of known addresses; a **no-address-at-rest** test asserting the schema has no address column and that a full sign-in plus directory upsert **plus rekey plus the roster seed verb** leaves no readable address anywhere, **WAL included**; and **no-content-in-logs** (gate 9). **Gate 9 needs no database** β€” it scans strings, and `cmd/home/main.go` emits log lines β€” **so it was never sequenced behind one**, and it landed beside the skeleton. Gates 1 and 2 do need one, and it now exists: gate 1 scans the raw file, WAL and SHM for canaries, and gate 2 runs in two halves, a static read of every migration and a full sign-in asserted to leave no readable address anywhere. Gate 2's expensive half must be **extended, not replaced**, when the directory upsert, the rekey and the roster seed verb land β€” it asserts the sign-in third of its sentence today. A guard written after the code it guards is a guard written to pass. (Stated as the rule rather than as a status: which gates exist today is a question for `git log`, and a status line in a binding file is a sentence that goes stale without anyone noticing.) --- ## The four things this service never does Each of these is something somebody will propose, in good faith, as an improvement. 1. **Never *store* content from an instance.** No previews at rest, no sheet thumbnails, no cell values, no titles in a database, a log, an error string, a metric label or an on-disk cache. It **may render**, transiently and per request, **and only to that person**, what an instance hands it for the person it hands it for β€” and nothing wider: no search over pulled content, no cross-person aggregation, no analytics, no operator view, and no retry queue holding a response body. **"Per request" does not forbid the cache the spec approves.** `design-activity-pull`'s Β§7 keeps pulled titles in RAM across requests, bounded by a refresh TTL and a hard maximum. Read alone, "transiently and per request" would rule that out, so read it with spec Β§0's gloss: **retains means holds without a bound**, at rest is the unbounded case, and the RAM hold is permitted because it is bounded and tested. **Amended 2026-09-05** from *never render*, on spec ruling 18. "Renders" was doing custody's work: the clause exists to stop the home becoming a place documents live, and storage is what makes it that. It also gained a test β€” spec Β§12's gates 1 and 9 grew a corpus of known titles, URLs and actor strings that day, so *never stores* has a grep behind it where *never renders* had none. 2. **Never hold a per-item grant.** Which sheets you may edit, which document a guest may comment on: all instance-side, decided there on every request. **The home does hold the membership roster** β€” `(team, person_ref, role)`, ruling 23 β€” so it knows who is on a team and who owns it. It never knows what they may do with any particular thing. This replaced *"never hold an authorization model"* on 2026-09-05; the line moved from *facts versus may-this-person* to **resources the home owns versus an instance's items**, because the roster is a person-level entitlement the home now holds on purpose. 3. **Never cross a team.** Data does not cross a team label; a team's instances across apps are one trust domain (spec ruling 23, suite ruling 1). This replaced *"never federate β€” data does not cross an instance boundary"* on 2026-09-05: the boundary was drawn in the wrong place, since `acme.docs` and `acme.sheets` are the same team and always were. **Sharing across teams** is a guest grant on the instance, never a copy. **Team standing is the roster**, not a grant and not a directory row (spec Β§5.5, Β§6: a directory row never grants team standing whatever its `kind` says). Β§6 keeps the two apart deliberately: "a row implying an org membership someone does not have is a lie the directory tells on the org's behalf". 4. **Never become a support console.** Reading someone's data to help them is precisely what **rule 1 above** forbids β€” "only to that person", "no operator view". It used to be the one rule; since the 2026-09-05 amendment "never retains" no longer reaches a console that displays without keeping, so the anchor moved and a reference left pointing at the one rule would rest on nothing. **And it stays small.** Every proposed feature is weighed against "does this belong in an instance instead?" The answer is usually yes. This service has a suite-wide blast radius, and a home that grows features grows that radius. --- ## Review β€” RULED 2026-08-30 by Paul **Every spec and every branch is reviewed by the highest-capability model available before it is approved or merged.** Cheaper models draft; the most capable available reviews. A review by a weaker model than the author is not a review. **Record which model reviewed** β€” in the spec's status line, and in the branch discussion for a branch. A review nobody can attribute is a review nobody can check. The model is **discovered, not hardcoded**; a session that cannot reach one at least as capable as the author's says so and waits. --- ## Shipping cadence β€” RULED 2026-08-30 by Paul Everything on a worktree, on a branch. Never directly on `main`. 1. Branch per piece of work, cut from `main`. 2. Commit regularly and push to the branch. 3. **Squash-merge to `main` only when** the work is done, it is approved (including the review pass above), and **CI is actually green** β€” checked, not assumed. Any one of the three missing means it does not merge. Review on a deployed canary, never localhost. **Every branch gets a discussion, and that discussion is the review record** β€” it survives a squash where a PR body does not. Tasks are a checklist, not a log. **A refusal gets surfaced in the discussion, never routed around** (amadan's own house rule, and the one most likely to be quietly ignored). --- ## Mechanical rules **Identity** - The **credential origin** serves sign-in, WebAuthn, recovery and assertion minting, and **never renders an account-authored string**. It is the relying party. This is a permanent constraint with its own test, not a naming choice. - **The RP ID is the full host β€” `id.oficina.works` β€” asserted by a test.** Never widen it to a registrable suffix. WebAuthn *permits* an RP ID that is a suffix of the origin's hostname, so `oficina.works` would be accepted; it is also valid at every host in the zone, the directory and every team instance included, which collapses the very split the two origins exist to make (Β§4, rulings 2 and 13; the host itself is ruling 16). Note where the first door actually is: `passkey.Config` has no RP ID field β€” the RP ID is always `Origin`'s hostname β€” so the way to widen it is to widen `Origin`, or to bypass `passkey` and build a `webauthn.Config` directly. The second door is `passkey.Config.LegacyRPID`, passed straight through as an RP ID accepted **for assertions only** (registration never takes it), so it must stay empty unless a rename drill (Β§5.7) is actually running, and then hold a full host. The test asserts both: `Origin`'s hostname is exactly `id.oficina.works`, and `LegacyRPID` is empty or a full host. Both are accepted silently, which is why neither can rest on care. - Assertions carry **identity and display preferences, never authorization**. The boundary test (Β§5.4) is **two-sided**: a claim may ride the assertion only if **(a)** the instance makes no trust decision based on it, validating against a **closed enumerated set** and treating a failed match as *absent* rather than as the raw value; **and (b)** the home already holds it for its own purposes, so carrying it adds nothing to what the home knows. Theme passes both. A role fails (a). **"Which documents you can see" passes (a) and fails (b)** β€” it hands the home a document-level graph it has no business holding. - **Do not restore "the instance would behave identically given a hostile value."** Β§5.4 retracts it: a hostile theme gives an ugly page, which *is* different behaviour, so the test's own example fails it β€” and without (a)'s closed set, a free-string theme in CSS is an injection, not an ugly page. - Assertion expiry is **120 seconds, not "seconds"** β€” sized to worst-case cold wake plus clock skew, because the exchange request *is* what wakes a hibernating instance and a tighter window makes the first sign-in to any cold instance fail and loop. Widening it costs nothing **against the threat model**, because **single-use `jti` is what stops replay**, not brevity. The long-lived thing is the session the instance mints. - Every assertion names the **app and instance host** it is for. Without audience binding, team A's assertion replays against team B, and a deployment has thousands of siblings to replay against. - **Signed identity claims are trusted for identity; every other claim must be cosmetically failable.** The subject flagrantly fails (a) β€” a hostile subject is account takeover β€” so the test must exempt identity by construction or it proves too much and gets argued around. **One narrow exception, added 2026-09-05 with ruling 23: `roster_epoch`.** It is not a closed enumerated set and does not fail cosmetically, so it would fail test (a) as written. What admits it is that **the instance decides nothing from it** β€” an unparseable value is ignored, a differing value buys exactly one call-8 refetch, and call 8's answer is what is enforced. A builder following the test without this exception rejects a claim Β§5.3 now puts on every assertion. Spec Β§5.4 carries the reasoning. - **Any "prune when all consumers have caught up" is unbounded in a hibernating fleet.** A dormant instance runs no timers to advance its cursor. Retention is a fixed horizon or a per-consumer TTL, never a slowest-consumer rule. This shipped twice in one spec before it was caught. **Data** - **No address column exists**, so there is none to accidentally populate. Addresses are learned transiently and hashed β€” and where one must survive a restart (a magic link between send and click), it is **sealed before it is written**, never cleaned up afterwards. Deleting a row does not erase bytes: SQLite leaves deleted pages and Litestream ships WAL frames continuously, so a transiently readable write reaches the bucket before any delete. `PRAGMA secure_delete` is on. - **The session Subject is an opaque person ref, never an address.** `rastrillo/auth` as shipped sets `Subject: id.Address` and stores readable addresses in `auth_links.address` and, via `Subject: id.Address`, in `sessions.subject` β€” `auth_sessions` is no longer written at v0.22.0, its rows having been migrated into the shared `sessions` table, so the leak moved rather than closed. Verified at source, filed upstream as `rastrillo/rastrillo` #2. We hand-roll session minting until that lands, and take classification and the Keymail upgrade from **`keymaildev/signin` directly, not from `auth`** β€” corrected 2026-09-05: `auth`'s classification is reachable only through `auth.Begin`, which hardwires `Links: &linkStore{db: cfg.DB}` and writes `auth_links.address`, so "use `auth` only for the parts that hold nothing" was never a thing that could be done. `signin.Flow` takes a `LinkStore` the app supplies, so the app seals what it stores. - **The home hashes; instances never hold the pepper.** A pepper on every instance makes one compromise an offline dictionary attack against the whole suite directory. - Migrations are additive-only. - **No address, team name, queue payload, or pulled content β€” a title, a URL, an actor (added 2026-09-05 with Β§2.2's amendment) β€” in any log line, error string, job status message or metric label.** Platform-held logs are storage we cannot grep. **Frontend** - **Write the attribute spelling: `rst-btn`, not `class="rst-btn"`** β€” spec ruling 20, 2026-09-05. Β§11 ruled the class vocabulary on 2026-08-30 and every reason it gave has since died, so it went back to Paul rather than being propped up with a third. rastrillo's design system rules "One spelling, not two. No permanent class fallback" and drops the class selectors before 1.0; this app has no `rst-` markup yet, so it starts on the spelling that survives β€” free today, a sweep after the first template. **The seven utilities are the exception, and they are not a loophole.** `rst-sr-only`, `rst-mono`, `rst-m-hide`, `rst-grow`, `rst-nm`, `rst-danger` and `rst-cell-mut` keep `class=`, because at v0.22.0 they have **no attribute twin at all** β€” five `.rst-sr-only` selectors, zero `[rst-sr-only]`. tokens.css's header says why ("Utilities keep the class spelling and are not paired… they stay class after the move") and Β§6-v3 agrees ("`class` is for utilities and the app's own CSS"). Write `` and nothing matches, so screen-reader-only text renders **visible**. Kinds, variants and parts are attributes; these seven are classes. This is also what the 6 surviving `class=` occurrences in v0.22.0's partials are β€” utilities, not residue awaiting a flip. Record the graveyard, so neither dead reason is revived: - *"The attribute grammar is ruled but not released."* Dead since **v0.21.0**, this repo's *first* pin. tokens.css there pairs every *component* rule with an attribute twin and says so in its own header: "TWO SPELLINGS, ON PURPOSE, FOR ONE RELEASE." The original claim β€” zero bare `rst-*` selectors against ~528 class occurrences β€” was verified on 2026-08-30 against v0.20.x, was true then, and was already false by the time the skeleton existed. No later bump falsified it. - *"The partials we render alongside write classes."* Dead at **v0.22.0**, the current pin, where the shipped partials flipped to the attribute spelling β€” rastrillo's design-system Β§6-v3 stage 2. Counted in `ui/partials/` with template comments stripped, the class spelling falls from **124 occurrences at v0.21.0 to 6 at v0.22.0**, replaced by the attribute spelling. (Count the class spelling, not the attribute one: `class="rst-…"` is unambiguous, while attribute-spelling totals move with how you treat valued attributes like `rst-tone="…"`, and two careful counts of it disagreed.) `callout.html` at the pin is `
`. tokens.css's header still claims "the class spelling is what every app and every shipped partial writes today" β€” **that sentence is stale upstream**, and this file quoted it as evidence until it was checked. **Re-check on every pin move, name the version you checked, and count both `ui/tokens.css` and `ui/partials/`** β€” checking one and not the other is how the second reason survived a pass that was looking for exactly this. - **rastrillo is `amadan.net/rastrillo/rastrillo`** (moved 2026-10-01, pinned at 29e4491, v0.26.0+8 β€” the version `connect`, `handoff` and `roster` already required). The old path, `github.com/carlosframework/rastrillo`, stops at v0.23.0: code importing it gets no fix, and its own checks cannot tell β€” Home's sign-in field zoomed iOS on every tap for a month that way (`TestNoZoomOnTap`, `make test-browser`). `internal/guardstest`'s `TestNoPreMoveRastrillo` forbids it in every module here; it stays in go.mod only as estilo's indirect requirement. Re-checked at this pin: `ui/partials/` still has the same 6 utility `class=` occurrences, and nothing in the class-versus-attribute reasoning above moved. The CLI is a go.mod `tool`: run it as `go tool rastrillo …`, never a `rastrillo` from PATH. `make release` stamps `amadan.net/rastrillo/rastrillo.BuildVersion`; the old symbol would leave `/api/version` answering "dev". - **`rastrillo doctor`.** `internal/home/static/tokens.css` is vendored, and `TestVendoredAssetsMatchTheLibrary` (noscript_test.go) is the standing gate: run `go tool rastrillo doctor --fix` on every rastrillo upgrade rather than re-copying by hand. **Then delete the scripts it adds** (`static/rastrillo.js`, `select.js`, `datetime.js`, `calendar.js`). Home serves none of them, and the shim doctor adds at this pin still carries rastrillo's old busy rule, which fights estilo's `busy.js` over every submit. `TestNoRastrilloShimBesideBusy` fails if one is left on disk or served. - **No script by default; script only to enhance, and always prefer none** (Paul, 2026-09-29, replacing rulings 21/24's closed list of screens). Every screen works with scripts off β€” magic-link sign-in, recovery codes, the springboard, sign-out β€” and a script may be added to a page only to enhance it or to provide interaction HTML and CSS cannot: the passkey ceremonies (`webauthn.JS()` plus a little glue), the assertion handoff's auto-submit (its Continue button stays for script-off), and estilo's busy rule on every submit button (the spinner, the double-submit guard). Reach for HTML and CSS first; a script is the exception that has to earn its place, not a tool. Scripts are **static same-origin files, never inline `