How we turn the two-agent model into shippable work: where data lives, how a market is born anywhere in ten minutes and then teaches itself its own edges — and the exact order we build it in.
Today HomeZero is one hand-raised market in Delta County, Colorado. The plan makes that a recipe — a market agent that any new buyer's location can stamp out in minutes, cheaply, and that gets smarter the more it's used.
The shape is settled (see how-it-works): two agents stand all the time — an advisor bound to a person, a market bound to a place — and a twin is born only when a buyer scans a home in person. This document is the engineering plan underneath that picture: the data stores, the birth mechanics, the self-tuning loop, and the order of operations.
It was assembled the way we build now: a fan-out of agents mapped the live repository, three independent planners drafted it from different angles, and an adversarial reviewer red-teamed the result. The seven corrections that pass surfaced are folded in below — the plan you're reading is the post-review version, not the first draft.
A buyer says “I'm looking near Marble” — and within ten minutes a market agent exists for that place, has taken a quick read of its listings, has read the home they're looking at, and has handed their advisor a real brief. No canvassing, no per-county setup, no human in the loop.
Wherever we can, policy moves into the agent and out of the platform code. Convex and the scripts hold facts — ledgers, records, the shared schema; the agent holds judgment — what's enough, what's ready, when to grow. Determinism is fine inside a skill (the agent can do math on real numbers); we just don't hardcode the decision around it. What stays deterministic on purpose: auth, secrets, money, idempotency, and the shared schema itself — guarantees, not judgments.
The hardest question wasn't “SQL or vector” — it was where does each thing live. The answer: sort by access pattern and regenerability, never by data type.
Governing line: Convex holds the truth the app serves; Stoolap holds the truth the agent reasons over; R2 holds the bytes too big to query; the filesystem holds what you can regenerate.
Reactive, app-facing. Everything the web app and extension query to render UI. Also the fleet registry and the demand-signal ledger.
Embedded SQL + native HNSW vector in one binary. Replaces today's SQLite + the flaky sqlite-vec extension. Per-cell, rebuildable from Convex + scrapes.
Object storage we already run for backups. Anything file-shaped and served by URL — the shareable flyer/brief, scan photos and recordings, the DB backup.
The Linux disk on the cell. The Stoolap DB file lives here, plus raw scrape dumps and working files. All rebuildable; nothing unique.
Every market agent writes the same Convex schema — one shared, uniform contract, keyed by market, never a schema per place. That's what lets the apps render across markets at all. Where a market gets to be itself is Stoolap: a rural-ag market and an urban one can carry completely different layer tables in their own store, and it never touches Convex. Convex is the uniform public contract; Stoolap is the private, per-place brain. Convex is also where agents share with each other — anything two agents both read (a jurisdiction's parcel layer that overlapping markets lean on) lives in Convex, keyed by jurisdiction, not re-scraped into each private store.
The store is the substrate. Over it sit two things that make the market smart, not just stocked:
The running feed of cards the app renders (market authors the home card, advisor weighs in) is structured and reactive → Convex. The rendered brief/flyer you share back into Zillow is a file with a stable URL → R2, with a Convex row for its metadata. Card in Convex, bytes in R2, a pointer joins them. The same home lives in three stores at three fidelities — full analysis in Stoolap, the published verdict in Convex, the rendered portrait in R2 — and the market agent owns the projection.
A market isn't a county and can't hold millions of homes. What bounds it is an attention budget — the comp model and watch load one cell can keep current. The boundary starts as a cheap guess and sharpens through use, across three timescales.
Mother feeds the buyer's fuzzy “where” to the model and gets a manifest back from its own geography alone — “Marble” → Crystal River Valley, jurisdictions Gunnison + Pitkin, low confidence. No data fetch. Wrong-but-cheap is fine by design: the first brief needs only the listing page + parcel identity, both geography-agnostic.
On a later pulse — not at birth — the cell runs a cheap structural pass: ZIP price-series clustering, school zones, commute sheds. It proposes a firmer manifest and raises its own confidence. The market is the only writer of its boundary after birth.
Which homes do the same buyers actually zero? Co-consideration is the market. The seam where it drops off is the split line; an idle sub-region is a merge candidate. This lives in the wiki and the memory — and it overrides the cheaper guesses as evidence accumulates.
Before any of that sharpening, the moment a market is born it does one thing the old design didn't: it samples the live Zillow listings in its boundary. Not the retired county canvass — a bounded, one-time, aggregate read: run the boundary as a Zillow search, capture the inventory count and a sample of cards (price, type, location). Deep per-home analysis stays demand-gated; this is shallow-and-wide, just enough to know the lay of the land. The rule of thumb: sample broad-but-shallow at birth, analyze deep-but-narrow on demand.
It pays for itself three times. It orients the agent — price range, inventory, property mix — so the first briefs aren't written blind. It is the first attention-budget reading: the search's total count tells the cell how big its boundary actually is. And it reality-checks the word-association guess on day one — forty thousand listings means the v0 boundary is too big, split before birth even finishes; a dozen means flag it for merge. The sample closes the loop from “guessed boundary” to “right-sized market” inside the same ten minutes.
That birth sample isn't a one-off — it generalizes into a daily study: the market wakes on its pulse and goes to learn something about its territory. The control structure is an old idea from our archived agents — yearnings: standing questions the agent holds (“what's really driving price on the north end?”, “where's the water-secure inventory?”), each carrying a way to learn it and a confidence that grows as it does. The birth sample seeds the first yearnings and answers the cheap ones.
The balance is the whole point. Each day it pursues one yearning on a bounded budget — never nonstop scraping. Demand reweights the agenda: when buyers keep zeroing homes near Marble, the yearnings about Marble rise to the top. But a floor of its own curiosity persists, so the market learns its place over time instead of only reacting to today's clicks. Demand steers; curiosity persists; the budget bounds — and that same budget is what keeps every market's scraping light enough to share one residential IP.
Every agent gets them. Mother seeds yearnings at birth — some shared, some customized. An advisor's are about its buyer (“what does a home that takes care of them look like?”, “they said acreage on a tight budget — what's the real tradeoff?”), drawn from onboarding so each advisor is tuned to its person. A twin's will be about its house. Same mechanism — standing questions, a way to learn them, a confidence that grows — across the whole fleet.
Do the same buyers weigh these homes against each other? Don't split a real market in two.
Can one cell hold it in its head and keep it current? Don't let it sprawl. Over budget → split; idle → merge.
Two things write to the demand ledger, both forced in code, not runbook prose: every zero (the buyer hit ⊕) and every question an advisor asks the market about a place. That second one is how “when an advisor starts asking, the market learns this buyer is looking here.”
So a single zero near Marble — outside every market's boundary — is served as a one-off by the nearest market (no new cell, flagged confidence). That's the anomaly default. But when a market keeps seeing distinct buyers pulling toward Marble, it doesn't trip a counter — it reasons that the interest is real and says so in its staff channel, and on a nod mother births one in ten minutes from the same word-association. The place earned a cell because demand gave it something worth knowing — not because a threshold fired.
There are no deterministic thresholds here — no “split at 2,000 listings.” The market reasons over its own load and demand, and when it feels it should grow or consolidate, it surfaces that to its staff Slack channel in plain language, with its evidence. A human (or mother, watching) makes the call; then mother — who alone births or retires cells — runs the split, merge, or fork, re-homing affected buyers transactionally and reversibly. The agent senses; the operator decides; mother acts.
Phase 0 lays the substrate everything reads and writes. Phase 1 is the unlock — a market born anywhere in ten minutes. Phase 2 layers in the intelligence. The phases overlap; the critical path is the spine.
Land the pure-Convex schema, merge the contract doc every skill cites, and clear the pre-pivot specialist machinery. All cheap, all parallel — nothing downstream can register a market or learn demand without it.
Confirm whether delta-market or zero-delta-co-market holds the live 34-layer DB and the working Zillow fetchers — the seed is a 90 KB stub and imports fetchers that aren't in the repo. This is a gate: we package the canonical template from the cell that actually has the brain. We're not killing the handmade cells — they stay as reference — so this is about packaging from the right one, not a destructive cut.
zero-delta-co-market (the namespaced canonical the app already routes to). delta-market is a near-identical twin (~12% more parcel_facts) kept as reference + data fallback.Bring agent-model.md and the agent specs to main so the dream-test contract every birth skill cites actually exists. Reconcile the contradiction: home-twin.md still says “born on zero-in”; the decision is born on scan. Fix the spec so the merged contract is self-consistent before anything builds to it.
Add a manifest — {name, geometry, jurisdictions[], narrative_seed, comp_set, confidence, placeType} (geometry is a ZIP list at v0, a polygon only once v1 has data), written by mother at v0 and the market thereafter — and a separate operational object for live metrics (active listings, watched homes, queue depth, readiness, boundary version). Two objects, one writer each, so a pulse metric never fights the boundary. Readiness is a status the cell asserts by its own judgment (“can I actually serve briefs here?”), not a coded transition rule. Add a coverFor lookup the agent uses (point → the market covering it, else null) — a fact-lookup, not a routing decision.
coverFor returns Delta for a Delta point, null for Marble.A new ledger keyed by place: every zero writes a row from stars.starHome; every advisor-to-market territory question writes one as a side effect of the call — not a runbook instruction the model may skip. Convex just stores the raw rows (the ledger is a fact, not a policy), with by-place / by-zpid indexes; the market agent reasons over them — clusters, substitution, “is this emerging?” — inside its skill, where it can use numbers deterministically. No cluster or threshold logic lives in Convex.
Retire the five leftover specialist template rows and drop their seed blobs; guard the roster so a regressed mother can't write a third member; keep the enum literals (history needs them). Namespace is settled: zero- denotes this project, so zero-advisor-pete is canonical; tend-advisor-pete belongs to a different project entirely — leave it alone. The dead zero-advisor-* rows are just history.
tend- namespace touched.The unlock. Package one portable template from the live Delta cell, give a newborn its own kitchen, make birth cheap from word-association — then prove it by finding Delta County's real sub-markets and birthing North Fork Valley first.
Perfect proving ground: it's where we have the most data, and it's plainly not one market. Mother's word-association should find roughly three — the North Fork Valley (Paonia · Hotchkiss · Crawford — orchards, vineyards, arts), Delta & the Uncompahgre (the county-seat town and its valley — ranching, the commercial center), and Surface Creek (Cedaredge · Orchard City · Eckert — apple country up toward the Grand Mesa). The birth sample checks each. We birth North Fork Valley first (it's where Paonia lives), then the others as we want them. The two handmade Delta cells stay as reference — nothing gets killed.
The long pole. Take the capability from the cell that has the brain (WS0·GATE) — the brief recipe, the analyze/watch runbook, the loose scripts — off the live disk into one versioned market template served via cellTemplateFiles{type:'market'}. Port the store to Stoolap (schema → Stoolap, retire sqlite-vec). Abstract the per-county source endpoints into a jurisdiction adapter; ship Delta County as the first. Parameterize placeType (rural-ag / suburban / urban) to flex the chapter set. The handmade cells stay as reference — this packages a template, it doesn't kill anything.
The red-team's #1 catch: birthing a market is three jobs — recipe, local supply, and a kitchen. Phase-B must stand up a fresh, empty Stoolap store (schema applied) before the first zero can be cooked. Stoolap makes this cheap — one binary, no native-extension ABI dance — which is exactly why it suits a template that births everywhere.
Already true today — this makes it a contract. Price and listing facts come off the buyer's own Zillow detail page (the exact page they saw), never a separate price scrape. Name it the priceFromListing adapter (geography-agnostic, so every market reads price identically), add provenance fields, and alert — never silently null — if both fetchers miss. This is the cold-start enabler: a fresh market needs zero county data for its first brief.
As part of birth, right after the v0 manifest, the newborn runs a bounded Zillow search over its boundary — capturing the inventory count and a sample of listing cards (price, type, location), not per-home detail fetches. It orients the agent, seeds the store and the wiki, gives the first attention-budget reading, and reality-checks the boundary (huge inventory → split before finishing; tiny → flag merge). It also seeds the price/inventory structure the v1 canvass otherwise lacks. One-time and aggregate — not the retired canvass; deep analysis stays demand-gated. Runs through the cell's residential egress.
Replace the Delta clamp with the v0 word-association manifest, reuse-or-birth via coverFor (then the birth sample, WS1·SAMPLE, reads the room). Add the missing master zero-birth skill that sequences the birth. Correction: the advisor births first / in parallel — it's instant and person-bound, it must never block on a market. The market births or attaches concurrently; the roster shows it “warming” until ready. Stop hardcoding the market in intake creation.
coverFor.The ten-minute promise rests on Phase-B self-config time, which is unmeasured. Instrument wall-clock (birth → alive → first brief); if it blows the window, stand up a warm market-egg pool so a newborn starts from a pre-baked image. Don't claim “birth anywhere in ten minutes” until it's measured.
Birth North Fork Valley fresh from the template (Paonia · Hotchkiss · Crawford) — the first properly-bounded market, on home turf where we have the data. Born in ≤10 min, birth sample read, readiness honest (the cell asserts it), one real brief from one real zero, advisor born independently. Then birth Delta & the Uncompahgre and Surface Creek (Cedaredge) the same way, as we want them. This is the “a county is many markets” proof, run on Delta itself.
With a market born anywhere, add the intelligence: it measures its load, weaves its wiki, reshapes from demand, and the twin is born on scan.
Each pulse, the cell publishes its load (active listings, watched homes, queue depth, pass time) into the operational object — as telemetry the agent reads, not a trigger that fires code. The grow/consolidate call is the market's own judgment (surfaced to staff Slack, per the boundary protocol). Run the v1 structural canvass after birth. Honest flag: the canvass needs ZIP price-series / school / commute data the cell doesn't ingest today — the birth sample and yearnings feed that, but sourcing it is part of this stream, not a free pass over existing layers.
Every brief is woven into its neighbors as it's authored (street, ditch, water system, comparable sales). Comps become graph traversal over linked briefs; revealed-substitution clusters densify the graph. This is v∞ made concrete — the market's intelligence compounds with every zero, not just with scraping.
Port the archived yearnings mechanism: standing questions in the cell's memory (subject + “how to learn” + a confidence that grows), seeded by the birth sample. On each pulse the market pursues one yearning on a bounded fetch budget — a targeted Zillow read or layer query — and updates its confidence, store, and wiki. Demand (zeros, advisor questions) reweights priority so study concentrates where buyers are, with a floor of self-directed curiosity. The nightly dream surfaces new yearnings and retires answered ones. The budget doubles as the rate-limiter that keeps every market light on the shared residential IP.
The de-coding lens on real code (from the sweep). The render-time heuristic libs — lib/{signals,lives,distress,sold} — are deterministic policy (price>avg×1.4, DOM bands, 15 life-archetypes, the negation-first distress regexes, the 1.5×/36-mo flip rule). Four already carry a // TODO retire header and a cell-authored path, so this is finishing the deletion: cells author via listingVerdicts:setX, the fallback functions go. The real win is freedom.ts: its cost-of-living coefficients become a per-market authored assumptions ledger (rural Delta ≠ urban), while the amortization and the single canonical freedomNumberFor stay a guarantee so site and extension never disagree. Keep untouched: the tally/aggregators (they re-derive headline-from-cards so an authored summary can't desync), idempotency, deploy-key gating, schema CRUD.
Give the market a staff Slack channel at birth (the operator hat, like the advisor's). When it judges it should split / merge / fork it posts a plain-language proposal there with its evidence — no coded threshold. On approval, mother's tend-market-boundary skill acts — re-homing buyers transactionally (roster + intake + markDead, ordered, reversible from the demand history) so a half-finished split never orphans a buyer.
A single unclaimed zero is served one-off by the nearest market (no new cell, flagged confidence). When the nearest market judges the repeated pull toward Marble is real, it surfaces an emergent-market proposal to staff Slack — no counter, no threshold. Framing correction: this is the attention-budget / economic-coherence test for a place, not the dream-test (which promotes a skill to an agent) — kept distinct so the two never get conflated.
Wire the missing half: a completed in-person visit (photos, walkthrough) fires the twin doorbell, idempotently. The twin registers as the third roster member — event-born, short-lived. The market hands off the parcel bundle, and the brief the market already authored is the system-of-record the twin inherits and writes back to. Ship the trigger + doorbell + handoff plumbing and a stub birth; the full twin cell is a separate build.
home-twin.md before anything builds to it. (WS0·MODEL)Most of these just got answered. Here's what's settled — and the few that are still open.
No deterministic thresholds — grow / consolidate / promote are the agent's judgment, surfaced to the staff channel; mother executes. v0 geometry = a ZIP list (polygon later). Shared data lives in Convex — agents share at the Convex layer. Advisor namespace = zero-advisor-pete is canonical; tend- is a different project, left alone.
It lives in Convex — but in what shape? Two overlapping markets share a jurisdiction's parcel layer at the Convex layer (settled). The open part is just the table design — how much of the parcel facts sit in Convex vs. stay derived in each Stoolap. Decide it when we build the second market.
Build it now or after measuring? If Phase-B self-config comes in under ten minutes on the first real birth, we skip the warm pool. Measure first, then decide.
How wide a sample, and how much load can one IP take? Aggregate cards to start, not deep fetches. Egress is settled — every cell runs locally, so all markets share your residential IP. The risk is concentration; the per-yearning budget is the first throttle, residential-proxy rotation the fallback.