The board is the buyer's codebase and the advisor's workspace. For the advisor (a pi cell) to actually run it — place homes, write reads, pin questions, digest answers — it needs a robust, scriptable interface. That's a CLI (board) the cell calls, plus a skill (the runbook for when and why). This doc specs both, and how the advisor's yearnings and memories decide what it asks.
Convex is the board's system of record (the boardCards table). The web app reads it live; the advisor writes it as an agent action with its deploy key. The CLI is a thin, well-shaped wrapper over those Convex functions — no new datastore, just ergonomic verbs and JSON in/JSON out, so the agent can compose them freely.
# the advisor cell, mid-tend: board inbox --buyer josh # what needs me? new zeros, fresh answers, moves board place --buyer josh --zpid 12345 --stage worth-seeing \ --synopsis "Owned water, in-town. Strongest fundamentals on your board." \ --verdict good --image https://imagedelivery.net/.../public board ask --card c_abc --control yn \ --prompt "That roof's ~$14k — deal-breaker, or can you handle it?" \ --options "Deal-breaker,I can handle it" \ --why "yearning:tradeoffs · mem:josh flinched at the furnace quote"
One shape the UI renders and the CLI writes. Added to boardCards (back-compatible):
imageUrl?: string // the home's face (pix illustration or listing photo) ask?: { // the pinned "agent zone" question prompt: string // what the advisor wants to know control: "yn" | "this-or-that" | "chips" | "knob" options?: string[] // labels for yn / this-or-that / chips knobLow?, knobHigh?: string // the knob's end labels answer?: string // the buyer's tap (present = answered) why?: string // WHY it asked — the yearning + memory behind it }
A home card carries an ask pinned to that home; a standalone question card with a stage is an ask about the whole column. why is the load-bearing new field — see below.
Read — the agent's senses:
| Verb | Does |
|---|---|
board ls --buyer X | The whole board, by stage. --stage shortlist to scope. |
board show --card C | One card in full (synopsis, verdict, ask + answer, history). |
board inbox --buyer X | What needs me now — unplaced zeros, freshly-answered asks, buyer moves & signals since last tend. The tend loop's front door. |
board pull --buyer X --since T | The raw digest of buyer activity for reasoning (answers, drags, taps). |
Write — the agent's hands:
| Verb | Does |
|---|---|
board place | Create/place a home card in a stage with a synopsis + verdict + image. |
board move --card C --stage S | Re-stage a card (advance the hunt). |
board set --card C --synopsis … --verdict … --image … | Update a card's read as the advisor learns more. |
board ask --card C --control … --prompt … [--why …] | Pin a question to a card's agent zone. |
board ask-column --buyer X --stage S --control … --prompt … | Pin a standalone question about a whole column. |
board image --card C --prompt "…" | Generate the home's face via pix and set imageUrl. |
Every verb is --json-clean (machine-readable out), idempotent where it can be (place upserts by zpid), and bearer-gated to the buyer's board. The skill, not the CLI, holds the judgment.
The questions in the agent zone are not a fixed form and not random. They are how the advisor pursues its yearnings against what it already knows — its memory — about this person and this place.
Every cell is born with yearnings: durable things it wants to learn, seeded by the mother at birth (some shared across all advisors, some cut from this buyer's onboarding). They aren't tasks; they're appetites. For the advisor they read like:
· What does this buyer actually value when money is tight? · Where's their real ceiling vs. their stated one? · Which trade-offs are dealbreakers, which are noise? · How do they react to a flaw I surface?
A yearning is what makes the advisor want to ask. Every pinned question is a yearning reaching for an answer it doesn't have yet.
The advisor carries a brain (Markdown + advisor.db, synthesized nightly — the "dream"). Memory does two jobs for an ask:
It suppresses the obvious. If memory already says "Josh will stretch for water," the advisor doesn't ask about the water premium again — it asks the next unknown. It sharpens the question. Memory turns a generic "do you like this?" into "the roof's the same story as the furnace you flinched at — deal-breaker this time?" — concrete, personal, answerable in one tap.
why = yearningmemory trace.The board is the surface where the advisor's yearnings get fed. Cost-to-zero is the north star; the yearnings are how it learns each person's path to it.
That's why why is a real field, not a comment. It (a) lets us see the agent's reasoning when we debug a bad ask, (b) powers a future "why am I being asked this?" affordance for the buyer (trust), and (c) is the join back to the memory note + yearning the answer should update. An ask with no why is a smell — the advisor asked without knowing why.
board runbookThe CLI is the hands; the skill is the judgment. A SKILL.md on the advisor cell that says how to tend:
· One ask at a time per card. The agent zone is precious; don't crowd it. · Every ask names its meaning — never a bare 👍/👎; the buyer must know what answering does. · Always pass --why (the yearning + memory). No why, no ask. · Prefer the cheapest control that captures the answer; reserve the knob/chips for genuinely graded questions. · Read before you write — inbox then reason, never blind-write. · The column question is for the column — scheduling, narrowing, the whole stage — not a home.
It plugs into the tend-the-board engine (the 30-min heartbeat + the zero doorbell): each tend pass = board inbox → reason against yearnings+memory → a few place/move/set/ask writes → memory updated. The CLI makes that loop scriptable; the skill makes it wise.