HomeZero · North-star design
Three AI agents — an advisor who knows you, a market who knows the place, a home who knows the house — summoned one at a time as your intent deepens. The app is just the surface they play on.
Status
Canonical north-star design. Supersedes the “team birth at one Finish” timing where stated; composes with the locked specs everywhere else.
Scope flag: MVP = rungs 0–3, plus three day-one rung-orthogonal workstreams (the multiplayer board, the assistant reach, the export). This is deliberately not a minimal MVP. Deferred to later sessions = rungs 4–5 (the tour) and estimator math.
Locked specs referenced (the-flow.md, onboarding.md, market-cell.md, advisor-briefing-flow.md, briefing.md) live at the workspace-root specs/ (and specs/agents/), not under homezero/specs/ where this design doc sits. Code refs are paths in homezero/ (convex/…, app/…).
00
The whole thing in one breath
Home Zero is three AI agents — an advisor (knows you), a market (knows the place), and a home (knows the house once you walk it) — and the app is just the surface they play on. You don't get all three at once. They're summoned one at a time as your intent deepens: signing up wakes your advisor; zeroing a home on Zillow gets you a one-page mini-brief from listing data alone; opening the board gets you a real card and a conversation; double-clicking to “go deep” wakes the market agent for the expensive public-records dive. The whole thing baby-steps people out of housing crisis — it meets you at an honest floor (can you actually afford this, with no surprises?) and walks you toward the aspiration (how does this home drive your cost of living toward zero?). The legible vessel for that walk is the Home Zero Score, a personalized house-by-you number that starts honest and shallow and sharpens as you climb. Your advisor is yours — a real agent on a little Linux box whose brain is plain files you can take with you. The market is ours — a commons built from everyone's signal that you structurally can't own. That asymmetry is the honest trust story. Two commitments run underneath all of it: everything the advisor does is a skill it performs, not a formula it runs — it's your own assistant (a friendlier, more playful OpenClaw that can also send an email or drop a showing on your calendar), not a search widget — and it's multiplayer: you invite your partner (and a contractor) into one shared board and one shared advisor — the household's advisor, owned by whoever signed up first. And it companions the whole journey, not just the search: a six-phase arc from affording a home to keeping it, each phase its own board.
01
Home Zero is three agents and a surface. The agents are summoned layer by layer as the user's intent deepens — cheap to expensive, shallow to deep, keyed to the user's own escalating commitment. The product baby-steps people out of housing crisis: it meets them at an honest floor and walks them toward the aspiration.
Most people arrive in crisis at the floor. You don't lecture them about the north star on day one. You earn the right to walk them there, one rung at a time, as they lean in.
01a
Underneath every rung is one build commitment: these are agents performing skills, not an app running formulas. Writing the mini-brief, condensing a listing, scoring cost-to-zero — each is the agent doing it, an act of judgment, not a calculation a backend spits out. We build the product out of skills, not formulas. A formula is a feature anyone clones in a weekend; an agent that reasons and knows you is not. That's the novelty, and it's the moat (Pillar 10).
Skills are free to use software where precision matters — pull the tax record, run the mortgage math, hit an API. The judgment wraps the tool; the tool never wraps the judgment. Even the Home Zero Score is a skill that may call a calculator — not a spreadsheet wearing an agent costume.
And the model for what the advisor is comes from what people loved about OpenClaw — having their own assistant. OpenClaw is the inspiration, not the tech: we build the advisor on Pi, the customizable agent harness it already runs on, so we can shape exactly the assistant we want. The advisor is a little OpenClaw-in-spirit with more form and fun (the board) and a dance of specialists behind it. So its reach is a general personal assistant's, not a home-search bot's: WhatsApp, sending an email, putting a showing on your calendar are in scope from the start. It's your assistant who happens to be world-class at the biggest purchase of your life — not a real-estate widget that can also chat.
(Build status: the advisor already runs on Pi with WhatsApp wired. Email ships day one too; calendar is intended. Deliberate day-one scope — see §11, not Open Question.)
02
Each agent is summoned by a deeper signal of commitment, and the data it touches widens exactly as the user leans in. This is Pillar 1 — intent-gated activation. Nothing expensive runs until the user has paid for it in intent.
(The “Pillar N” scheme this doc tags sections against: Pillars 1–9 come from the how-it-works.html / agent-model material; Pillars 10 (agentic-not-formulaic) and 11 (multiplayer board) are new in this doc. None of these are the five locked specs' markers — those use D6/D15/D16 and §-numbers. Don't try to cross-check a “Pillar N” against the locked specs; it won't be there.)
Meaning settled, surface deferred
“Double-click” — meaning settled, surface deferred. What it means is locked: it's the user asking for the full deep briefing on this home — a synthesis of the Zillow listing plus everything gettable in the cloud (county records, water rights, permits, satellite). Producing that requires engaging the market agent, the one with the domain to go get it all. What's deferred is only the affordance — the concrete surface (a card action? a “Go deep” button? a literal double-click?) is undefined and should not be wired as a literal dblclick handler off this doc. Treat every “double-click” below as “the deliberate request for the deep briefing.” Affordance is Open Question #6.
| Rung | User signal | Agent summoned | Data it touches | Status |
|---|---|---|---|---|
| 0 | Sign up | Advisor born | Nothing yet — frames the search, learns who you are | MVP |
| 1 | Zero a home on Zillow | Advisor (already born) | Zillow listing only — writes a mini-brief / one-page tear-off, the first look | MVP |
| 2 | Open the board | Advisor (already born) | The cards across your homes — cards each home, densely; asks what you liked | MVP |
| 3 | Double-click / “go deep” (the scan) | Market engaged (an attach, never born per-buyer) | Public records, water rights, permits, satellite — the deep dive, surfaced as new layers on the card | MVP |
| 4 | “I want to visit” | Home born | The tour — a Granola-style capture; notes split three ways (you / market / home) | Deferred |
| 5 | “I might buy” | Home (already born) | The return visit — measurements, photos, a guided self-inspection | Deferred |
Read the table top to bottom and you can see the spine: the advisor is present from rung 0 and never leaves; the market is gated behind a deliberate second intent signal (the double-click), not engaged on the first zero; the home agent has a concrete trigger (the tour) the prior specs left open.
Engaged, not born
“Engaged,” not “born” — the market is an attach. Rungs 0 and 4 born a per-user agent (your advisor, your home). Rung 3 is different in kind: it engages a standing, shared market cell for deep work on this home — it does not birth anything per-buyer. The market is one-per-territory (the-flow.md §10: “No market cell has ever been birthed… Delta is an attach to a standing cell”; market-cell.md makes it the commons). Don't read the rung-3 column as “birth a market on double-click” — that would contradict the “market = ours, commons, one per territory” thesis in §7. The double-click engages an existing market cell (the attach); for an uncovered place, the act that ensures a market cell exists is the cheap onboarding germ (§11), not a per-buyer birth at rung 3.
The advisor now knows every house you're interested in. That's the quiet payoff of rung 1 — every zero, even before any deep dive, teaches the advisor what you're drawn to. That signal is what makes the board (rung 2) and the deep dive (rung 3) sharp.
Refines · advisor-born-first
Refines the locked specs (advisor-born-first). the-flow.md (#2) and onboarding.md (delta 5) lock “Finish births two agents” — market and advisor up together at one event. This design supersedes that timing: at signup only the advisor is born. The market's deep work is deferred behind the double-click (rung 3); for a covered place the market is merely attached at onboarding (cheap), and for an uncovered place even the market birth is deferred to rung 3 (refining onboarding.md delta 5's “births the market at Finish”). See §11 for the covered-vs-uncovered split and how we keep onboarding's Screen-1 reflection alive.
02a
The ladder above is how the agents wake. This is the bigger frame: the journey the user is on. Buying — and keeping — a home is a six-phase arc, and Home Zero is a companion through all of it, not a search tool that quits at the front door.
| Phase | What it is |
|---|---|
| Footing | Can I do this — what can I afford, what do I qualify for, which programs. The real floor, and the crux most people never get a real version of. |
| Targeting | What and where, given your actual number. Options to point at. |
| Sizing up a home | One specific place, deeply — condition, disclosures, comps, and the true cost to own over time, not the sticker. |
| Making the move | Offer strategy, terms, negotiation. |
| The gauntlet | Under contract — contingencies, deadlines, inspection, appraisal, financing. Where deadlines bite and the board earns its keep. |
| Keys, and staying in | Close, then keep it affordable and build equity. The goal outlives the transaction. |
Each phase is its own board (a project) — its own issues, its own character. The user is only ever in one phase at a time, so the structure clarifies rather than crowds: you see the phase you're in, not all six at once.
The advisor is the throughline across all six. Same one relationship, phase to phase. The other agents show up only where they're needed: the market in Sizing up; the home agent in Sizing up and The gauntlet. The phases are the journey; the agents are the workers moving through it.
Where the rungs live. The intent-gated ladder (§2) plays out inside the discovery-and-evaluation phases: Targeting is the rung-1/2 discovery board (zero homes → mini-briefs → sort), and Sizing up is rungs 3–5 (the scan, the walkthrough, the deep scan). So “go deep” gets a sharper meaning — a home graduating from Targeting into Sizing up: “I'm serious about this one now.” The promotion is the gesture.
Cost-to-zero spans the arc, not a single card. Its floor is set in Footing (your number, your eligibility — §5); it sharpens through Sizing up (the true cost to own); and it's realized over time in Keys (the home driving your cost of living toward zero — the brand). The Home Zero Score is the through-metric of the whole journey, not a per-home gimmick.
Build order. We start with Targeting — the discovery board. Footing is the true front door for a real user (you need your number before you target), so it's the highest-leverage phase to build next. The rest come online as users reach them.
03
The advisor is the single throughline. With you from signup, through the board, into the tour (where it captures what the tour reveals about you). One hand on the board, one voice to the human.
Market and home agents work behind it. Their findings surface as layers on the card, never as separate voices. In MVP there are no competing agent presences — the user talks to one entity. (If we ever expose more, that's a later call, deliberately made, not a default.)
This is Pillar 2, and it composes cleanly with the locked model:
advisor-briefing-flow.md already runs the advisor loop every zero (greet-first → lens + one question), and the question is home-signal × lowest-confidence yearning. That survives intact at rung 1 and rung 2.market-cell.md is explicit that “the question and 👍/👎 are the advisor's private layer.” The market authors body/facts; the advisor authors the lens, the one question, and the reactions. That seam holds.The one thing to keep honest: the asks stay advisor-authored. The board's questions come from the advisor's read of you, never from the market. The market never asks a question and never owns a 👍/👎.
04
The kanban board is not an imagination board — not a free-form, put-anything-anywhere canvas. That's the wrong model. Agents need structure and form to organize against. The board gives just enough structure to organize against, not so much it cages them. This is Pillar 8.
And showing that structure to the user is itself the product. Two things happen at once:
The board is the shared medium of human–agent interplay — the communication protocol between you and your advisor — not a feature bolted onto a feed. Card movement is a first-class input, not decoration.
04a
Nobody house-hunts alone, so the unit isn't a person — it's a household. There is one board and one advisor per household, and multiple people share both. Whoever signs up first gets the advisor — the Pete advisor — and invites the others in: a spouse as a co-buyer, a contractor as a helper. If the wife signs up first, she invites the husband; if the husband first, he invites the wife. Either way, there is exactly one advisor working that board. This is Pillar 11.
The advisor runs a separate session per person — it knows who it's talking to by their channel (one partner's WhatsApp is not the other's) and attributes signal per person: one loves the light, one loves the lot, the contractor flags the foundation. But it all synthesizes into one brain. Over time the advisor isn't anonymous — it becomes “the Pete-and-Melana advisor” (with Tony as a helper): one relationship that happens to know a whole household.
This sharpens Pillar 2 rather than complicating it — the single voice on the board is now literally one shared advisor for everyone, not a committee:
One household → one board → one advisor → many people.
The advisor is shared, not personal; it's owned by the account holder, who invites the rest.
You don't co-own an advisor; you co-own a board. Each person keeps their own private advisor (their own cell, their own brain, their own zip). Both publish their person's signal onto the shared board and read the shared board to see how the hunt is organizing. That's what lets the board be multiplayer without a crack in self-sovereignty — the shared thing is the surface, not the brain.
Roles. The owner (first to sign up) holds the account. Co-buyers (the invited spouse) get a full seat — full signal, full voice. Helpers / experts (the invited contractor) get a scoped seat — they see the homes and add their read, not the household's finances. Later, a helper could even earn their own expert-agent serving many households (the expert-agent tier already exists — the national parcel-resolver is the precedent); in MVP they're simply invited participants on the one advisor.
Ownership lands on the owner (see §7). Because there's one advisor owned by the account holder, self-sovereignty is the owner's: Pete owns and exports the one household advisor whole. An invitee who wants their own advisor just signs up themselves and becomes an owner. No per-person brains to reconcile — one shared brain, one owner, one export.
Day-one, and a light lift. This isn't a fast-follow — the product is built collaboratively (Pete + a partner + a contractor on one board), so it's a day-one commitment. And it's light on Convex, where real-time multiplayer is native: a multiplayer kanban is not hard to build, and one shared advisor is less to coordinate than many. The schema gains an invite / participants model (owner + invited people, roles, per-person channel-as-identity) on both the board and the advisor's sessions; the advisor's two-hats per-channel sessions already distinguish who's speaking, so the identity hook is half-built. The one care-point is keeping per-person attribution clean inside the single brain — who said what — not routing across brains. Design is Open Question #8.
05
This is the spine of the whole product (Pillar 4). Cost-to-zero = what it takes for housing to stop being a problem, in two parts.
Down payment + closing + the work to make the house right for you — the kitchen, the roof, the furnace. This is personalized, and fit falls out of it: a house that doesn't fit you (a tear-down/rebuild to become livable for you) carries a huge on-ramp, and therefore a low score. Fit isn't a separate axis you score; it's an emergent consequence of computing the personalized on-ramp.
Mortgage + tax + insurance + utilities + upkeep — net of what the home gives back: solar, ADU rent, a garden that offsets groceries, a shorter commute. The net-of-what-it-gives-back is the takes-care-of-you part nobody computes. Zillow shows you the gross carry; nobody nets it against what the place returns to you. That's the whole game.
B is the next step from A, on one continuum. Most people arrive in crisis at A. You walk them to B as they're ready.
A personalized score (house × you): honest at the floor, aspirational at the ceiling. It starts honest / A-flavored (shallow, Zillow-only, rung 1) and shifts toward B as the user climbs the rungs — because depth is what makes the path-to-zero computable. You can't compute “does the Stewart Ditch water plus a south-facing roof drive your carry down?” from a listing. You can compute it after the deep dive.
Watching the score sharpen on the card is the user literally walking from A toward B.
(Real home, already in the system: 229 Colorado Ave, Paonia, CO 81428 — 3 bd / 2 ba, 1,512 sq ft, three city lots / 0.21 ac, built 1967, original-owner.)
The score didn't change because the house changed. It sharpened because the depth changed — and depth is gated behind the user's own intent.
Real data only
Use only real 229 Colorado facts. Everything above traces to the brief already in the system (homezero/design/brief-homezero-229-colorado.html). Do not attach invented prices, owners, or numbers to this home.
06
The brief is not a page. It's a collection of estimates, each one sharpening along two axes (Pillar 3):
The agents' job is to tend a set of sharpening estimates, not to write a brief once and freeze it. The on-ramp is an estimate. The carry is an estimate. The net-of-what-it-gives-back is an estimate. The Home Zero Score is the legible roll-up of those estimates. They all get sharper with depth and with volume. And each estimate is a skill the advisor tends, not a formula it runs (§1a) — which is exactly why the math is deferred below: it lives inside a skill, wrapped in judgment and free to call a tool where precision demands.
Deferred
Estimator mechanics are deferred. How each estimate is computed and tuned — the math, the model, the confidence intervals — is a later session. This doc describes the shape (estimates that sharpen on depth and volume), not the math. Don't build the math from this doc.
07
Ownership maps to architecture (Pillar 5). This is the honest trust story, and it's load-bearing.
You own the agent that knows YOU; you cannot own the one that knows the MARKET.
That asymmetry is the point — it's what makes the trust story honest instead of a slogan.
Shared advisor, single owner · §4a
Shared advisor, single owner — that's how collaboration and self-sovereignty coexist (§4a). A household shares one advisor, but it's owned by the account holder, who invited the others in. So ownership isn't diluted — it's located: the owner owns and exports the one shared brain; invitees are guests with their own sessions, not their own brains. Want your own advisor? Sign up and you're the owner of yours.
For the export to be whole, the advisor cannot be a thin client pointing at the market's brain — the link snaps the moment you leave. So the advisor absorbs findings into its own brain. And more than a copy: a synthesis. It metabolizes each finding, weaves it into your wiki, links it to your other homes, connects it to what it knows you care about. That organized, contextualized understanding cannot be replicated by holding the data elsewhere. The market computes; your advisor understands — for you; you own the understanding.
Two consequences fall out:
The architecture already does most of this, and we should say so without overclaiming:
/root/memory/MEMORY.md + topical user_*.md / feedback_*.md / yearnings/*.md files, plus advisor.db); dream-based synthesis (a nightly consolidate pass that merges, resolves contradictions, prunes — the defining property of an agent); the Convex-vs-cell data split (below); and a whole-cell checkpoint → R2 primitive.delta-market; “commons” is the jurisdiction-keyed shared data plane, not yet multi-tenant).The pillar is honest if it says: brains are plain files you take with you — a one-click zip ships day one — while being clear that the fully-published open standard and the turnkey off-Mac re-host mature behind that first artifact.
08
Two data layers, and the split is the system's #1 principle (Pillar 7; the architecture decision is tagged D8 in the agent-model / how-it-works material — note this tag is not one of the D6/D15/D16 markers used in the five locked specs, so cross-check it against how-it-works.html, not market-cell.md).
The proof case is already specced: WhatsApp transcripts never touch Convex; only conclusions mirror to BUYER.md → the public buyers row. Convex holds the seam; the cell holds the understanding.
For the market, the brain is three-layered (aspirational direction, flagged): a store (facts), memory (what the facts taught it, via dream), and a wiki (interlinked briefs = the comps graph). “The store holds facts; memory holds what the facts taught it.” That's the synthesis claim, verbatim — and it's why the brief portfolio (§6) compounds.
09
The ladder is the freemium ladder (Pillar 9). Each rung is a conversion pressure point toward a premium subscription, and the cost of going deeper is exactly where you ask for money — compute, public records, the market agent.
| Rung | What's gated | Allowance | Note |
|---|---|---|---|
| 1 — zero onto the board (advisor + Zillow only) | Board card + advisor lens | Generous — up to 50/week (the pinned high cap) | The habit-builder. Every zero also enriches the public Zillow overlay (network effect). |
| 3 — double-click / market deep dive (the scan) | Public-records deep dive + market layers | Metered — small free allowance, order of ~10, then premium | This is the expensive artifact. This is the wall. |
Premium — $25/mo (determined). Unlocks the deep dives + the full advisor relationship. Billing rides Clerk billing (intended: the app is already on Clerk for auth, so subscription state can ride the same identity — feasibility not yet validated).
Fixed vs directional
Which ladder numbers are fixed vs directional. Fixed: the subscription is $25/mo (determined), and the board-zero high cap is 50/week (pinned). Directional / TBD: the ~10 free deep dives before the wall, and the exact board-zero floor. On record, briefing.md's free-tier candidates were 3 briefs/week or 10 lifetime — those must be reconciled against the new two-unit split (board-zero vs deep-scan); see Open Question #4.
Disambiguation · the hook
Two units, one word disambiguated — what “the hook” means now. briefing.md (locked) says “the hook is the home brief you get when you zero.” This design keeps that literally: the free, ungated thing is the rung-1 advisor mini-brief on zero — the habit-builder, and still the hook in briefing.md's sense. What this design adds is a second, paid unit — the rung-3 market deep dive, which is the wall, not the hook. To avoid inverting briefing.md: “hook” = the free rung-1 brief; “wall” = the paid rung-3 scan. We do not call the deep dive “the hook.” The free brief hooks; the deep dive converts.
Supersedes · meter location
Supersedes the meter location. briefing.md meters at “the extension zero” — every brief, 3/wk. This design relocates the meter: the free, ungated thing is the advisor mini-brief on zero (rung 1, generous — the hook); the paywall (the wall) is the market's full deep dive (rung 3, metered). The metered unit also changes (from “a brief” to two distinct units: a free board-zero and a metered deep-scan), so the on-record “3 briefs/week” no longer maps cleanly and must be reconciled against the ~10-free deep-scan allowance.
Supersedes · one-time scan
Supersedes the one-time Deep Scan. The live landing sells a one-time $25 Deep Scan. briefing.md already flagged the one-time → recurring pivot as “Decision pending.” This design lands on metered + recurring and supersedes the one-time scan. The landing story must be re-cut. (See Open Questions.)
10
We do not throw anything out. The tend-the-board engine (PR #31) and the Convex/app half it shipped hold almost entirely. What changes is who authors what, when, and on which data.
homeCardKey(zpid) / zpid keying (board.ts:18/:21). Every home card converges on home:zpid:<zpid>; the mini-brief and any later market deep-dive layer upsert in place on the same key. Unchanged.inboxReceipt(ctx, {...}) (board.ts:32) as the on-zero upsert — by (userId, sourceKey) via by_user_sourceKey, INSERT-on-first-zero / patch-on-re-zero, never patching stage (advisor placement wins). The receipt is already authoredBy:"advisor", authorCell:"zero-advisor" — so the advisor is already the on-zero author. (See the load-bearing nuance below.)tendDigest (board.ts:509), markTended (board.ts:490), buyers.lastTendedAt (schema.ts:100). The tend cursor and digest surface are agnostic to who authored; they hold. (readyInbox (board.ts:562) — its copy shifts, its join may stand; see re-points.)boardCards schema (schema.ts:263). authoredBy already admits advisor|market|twin; body is already markdown. No schema change.backfillFromTakes (zpid-keyed, board.ts:477), dismissLegacySlugCards (board.ts:588), and all buyer-curation mutations — pinCard / answerCard / setStage / cardSignal / setTour, plus addCard / highlightCard / dismissCard / setStageInternal — untouched.cardsForUser reactive useQuery (page.tsx:92). Every write still propagates live.inboxReceipt's body: "" (board.ts:65). Today the body is empty on zero and filled only later, during the heartbeat tend pass, after the market's Brief lands. Re-points to: the advisor's Zillow-only mini-brief, authored synchronously on zero (rung 1). The new model doesn't add an author on zero — the receipt is already advisor-authored — it fills the body on zero instead of leaving it empty until the heartbeat.stars.starHome (stars.ts:81) schedules internal.doorbell.zeroCreated({zpid}) (stars.ts:98) only inside the uncovered branch (else if (args.zpid)) and only when pending.created is true (stars.ts:91–98) → POST {hook:"zero-created", zpid} to ZERO_DOORBELL_URL (doorbell.ts:258–276) → host-bridge → market cell. So the ring fires on a first uncovered zero — a covered zero (a home delta-market already analyzed) never rings the doorbell today. Re-points to: under “market waits for a double-click,” this uncovered-zero ring stops being the on-zero trigger and moves to the deliberate rung-3 signal (the double-click). Note the asymmetry this exposes: the rung-3 deep dive is most interesting on covered homes (where a market cell already exists and can actually go deep), and those never rang today — so rung 3 doesn't merely relocate the existing ring, it adds a deep-dive trigger on the covered path that has no on-zero ring at all. The synchronous on-zero author becomes the advisor mini-brief, not a market wake, on every zero (covered or not).stage:"inbox" renders as “Analyzing — brief soon” (page.tsx:244–248) and presumes the market Brief is already inbound. readyInbox (board.ts:562) joins an inbox home card to a covered listings row by zpid (board.ts:568–579) — i.e. it fires whenever a listings row exists for the zpid, which is already true for every covered home at zero time, no market work needed. Re-points to: the inbox stage copy (“Analyzing — brief soon,” page.tsx:245) is the clear casualty — with the market deferred, it no longer describes what's happening on zero and must re-point to the double-click gate (deep dive requested / inbound). The readyInbox join is muddier: for covered homes it already fires on listing existence (not on a deep Brief), so it doesn't simply “lose its trigger.” Whether the join needs rework depends on a build choice — is the rung-3 deep layer a new field on the listing (then the join must gate on that field), or just listing existence (then the join stands and only the copy changes)? Decide in Open Question #7.The inbox receipt already exists and is already advisor-authored (authoredBy:"advisor"). So the new model does not introduce a new author on zero. It does two precise things: fills the body on zero (advisor, Zillow-only) and defers the market ring to rung 3 (the double-click). That's the entire mechanical delta on the write path.
Re-points · locked relay
Re-points the locked relay too. the-flow.md (§7) and market-cell.md have the market author the card body on zero (zero-created doorbell → market cell). This design makes the first authored body advisor-made and Zillow-scoped; market depth is a later, gated layer. That's the explicit supersession of “market authors on zero.”
Seam · advisor mini-brief
The advisor “mini-brief” must stay on the right side of the seam. advisor-briefing-flow.md (§2) says the advisor never authors market facts. Resolve it this way: the rung-1 mini-brief is the advisor reading the listing basics it already has at greet-first and writing a lens on them — the first look, the tear-off — not the advisor producing new place/public-record facts. Public-record facts remain the market's job, gated to rung 3. The advisor reads Zillow's own listing data and reflects it back; it does not go get water-rights or permit facts. That keeps the two-agent boundary intact.
Two pillars add capability today's code doesn't have at all. Flagged honestly as additions, not re-points:
boardCards and cardsForUser (board.ts) resolve one user's board, and buyers is one row per person. Multiplayer adds an invite / participants model: one owner plus invited people (co-buyer / scoped helper) sharing one board and one advisor, with per-person channel-as-identity and attributed signal (whose 👍, whose tap, whose card-move) kept clean inside the single advisor brain — not routed across separate brains. The advisor's two-hats per-channel sessions are the nearest existing hook. Committed day-one; the design is Open Question #8.11
inboxReceipt body-fill above.)cardsForUser.This is not a minimal MVP. A few things we know we want are committed for day one rather than staged — building them in from the start beats retrofitting, and some are load-bearing for how we build (we dogfood the product collaboratively):
onboarding.md keeps a 4-screen scaffold; Screen 1 reflects the real market back (the reflection beat, locked #8), and that reflection is the market's first read. Deferring the market behind the double-click threatens the reflection's onboarding home. Resolution: keep Q1 (place → market) at onboarding and hold it as a germ — the place is resolved/known at onboarding (Screen-1 reflection still ships, market resolution still happens), but the market cell is not woken / engaged for deep work until the double-click (rung 3). The germ is cheap; the deep dive is gated. This preserves the reflection without re-introducing “team birth at Finish” for the expensive market work.
Refines · onboarding delta 5
Covered vs uncovered — what “germ” means, and where this refines onboarding.md delta 5. onboarding.md (delta 5, “Calls,” locked) says Finish births two agents: mother births the advisor and “ensures the market agent for the place exists (births/attaches).” Split that by coverage:
onboarding.md unchanged.onboarding.md is an expensive market birth at Finish. This design refines that: the onboarding germ resolves the place and may queue/seed the territory, but the expensive market work — and, where a birth is required, the birth itself — is gated to the rung-3 double-click, not paid at Finish. The reflection (Screen-1) still ships from the cheap resolution; the territory's first deep dive is what pays for the heavy lift.So for the uncovered case this supersedes onboarding.md delta 5's “births the market at Finish” in favor of “resolve the place at Finish, defer the market birth/engage to the double-click.” Open Question #1 carries the ratification of this split.
12
onboarding.md contradiction it must resolve. §11 holds Q1 (place→market) at onboarding as a germ so the Screen-1 reflection survives: the market is resolved (cheap, reflection ships) but not engaged for deep work until rung 3. For covered places this composes with onboarding.md cleanly (resolve = attach). For uncovered/coverable places it is a direct contradiction with onboarding.md delta 5's locked “Finish births two agents”, where “ensure the market exists” = an expensive market birth at Finish — exactly what this design defers to the double-click. Ratify the split: at Finish, resolve the place (and optionally queue/seed the territory); defer the uncovered-place market birth and all deep work to rung 3. If instead the reflection itself is judged to require the birth, Q1 stays at Finish for uncovered places and only the deep dive defers — and onboarding.md delta 5 stands. Pick one; do not leave Finish-vs-double-click ambiguous for uncovered places.readyInbox / stage re-copy — and the covered-vs-uncovered join split. With the market deferred, stage:"inbox" (“Analyzing — brief soon,” page.tsx:245) needs new copy keyed to the double-click. The readyInbox join (board.ts:562) is the subtler call: today it fires on a covered listings row existing (not on a deep market Brief), so for covered homes it already fires at zero time. Decide whether the rung-3 deep layer is a new listing field the join must gate on, or just listing existence (join stands, only copy changes) — and specify the new stage vocabulary accordingly.