CRM respec · Working draft — not yet built

One client record the whole system agrees on — not five screens that don't talk.

The first CRM build was torn out — every module worked in isolation but nothing connected: a pipeline card that didn't reflect the contact page, a task list with no relationship to a client, an activity log that couldn't move a deal forward. A reference spec (a third-party "Realtor CRM" PRD) was supplied as a guide for the rebuild. This is that spec reconciled against what KeyRingOS actually is, what's already been decided this project, and what's real vs. invented — for review before anything gets wireframed or coded.

closingboss.io/docs/crm-spec

01 — What the reference spec gets right

Three ideas worth keeping, independently arrived at before this document existed.

Worth naming plainly: nothing here is a concession to the reference spec for its own sake. Three of its structural ideas match conclusions this project already reached the hard way, through direct feedback on the first build — reassuring convergence, not new direction.

One activity type, not three. The reference schema's tasks table spans a task_type from MANUAL to CALL to ESIGN to CONTINGENCY, tied to both a contact and a deal — structurally the same call this project already made independently: a scheduled call and a completed call are the same kind of row at two points in its life, not two different entities (matches how Pipedrive itself behaves). Kept.
Documents need a real taxonomy, not one generic bucket. The reference's ESIGNABLE / STORE_REVIEW / WET_INK three-way split is the same distinction already built here as esign / storage / physical across 27 document types in five transaction-chronology categories. Already right — nothing to change.
A daily action list needs contextual actions, not a bare checkbox. The reference's "Daily Action Queue" gives each row a one-click action matched to what it actually is (call it, text it, send for signature) instead of one generic "done" toggle. A real upgrade over the first Tasks build — adopted, see §08.

02 — What's cut, and why

The reference spec is a generic multi-agent CRM vendor's PRD. This is a solo agent's platform.

Several of its modules solve problems KeyRingOS doesn't have, or were already explicitly ruled out this project. Cutting them isn't a scope reduction so much as not building for a customer (a brokerage with a routing pool, a marketing team running SMS blasts) that isn't the one being served.

Reference proposes

Smart Lists & saved segments
Round-robin lead routing across agents
Unified Inbox — 2-way Twilio SMS threads
Gmail/Outlook OAuth email sync
Click-to-dial (softphone integration)
"Hot" lead-temperature score per contact
A separate top-level Reports module
5-tab Contact "Command Center"

Cut, and why

Redundant with Pipeline — already ruled out: "i don't think we need a smart list at all"
A multi-agent brokerage feature; KeyRingOS is one agent, one queue
Real 2-way SMS threading needs a Twilio number and per-message cost — out of scope, see §04
A real inbox sync is a large, separate integration; not what "doing emails" asked for — see §04
No telephony vendor in the stack; would be a dead button
No real signal computes this — would be an invented number on a client record, same rule that already killed target price
Analytics already exists and covers this ground; a second reporting surface would fragment it
Fragmenting Communication / Tasks / Milestones into separate tabs was already tried in spirit and explicitly walked back: "we should simplify things quite a bit"

03 — Communication channels

Call and text stay free deep links. Email is the one channel that actually sends.

The reference's "Unified Inbox" bundles three different levels of integration into one module, which is what made it look like scope creep. Split apart, each piece has a different real cost:

Call — tel: deep link. Opens the phone's own dialer. Free, no vendor, no number to provision. Logged as an Activity the moment it's initiated.
Text — sms: deep link, no Twilio. Opens the phone's own Messages app pre-filled, same as Call. Free, no per-message cost, no 2-way thread inside KeyRingOS — the conversation happens on the phone, KeyRingOS just logs that it happened. This is the one item revised mid-respec: dropped entirely at first pass, restored once the distinction was clear — the deep link stays, only the Twilio-backed 2-way inbox is what's cut.
Email — real send, via Resend. The channel actually gets built, not just linked out to. An agent composes and sends from the contact record; the send is real (already-provisioned Resend, same as every other transactional email in this codebase), logged as a kind: "email" Activity with the real subject/body, not a mailto: stub.

No inbox, either direction. None of the three channels sync incoming replies into KeyRingOS — a client's callback, reply text, or reply email lands on the agent's own phone/inbox, same as today. Building a real synced inbox (IMAP/OAuth for email, a Twilio number for SMS) is a materially larger integration than "doing emails" asked for; worth its own respec later if it's actually wanted, not folded in here by default.

04 — Information architecture

Manage stays a sibling group. CRM keeps its own three screens inside it.

Already decided this project and unaffected by the respec: Calendar and Documents moved out from under CRM to sit beside it, because a task or a signature request isn't only ever CRM work. The reference's flat top-level routing (/inbox, /deals, /tasks as siblings of everything else) is closer to that shape than to the original nested-under-CRM version — but "Inbox" isn't rebuilt (§03) and "Smart Lists"/"Reports" aren't rebuilt (§02), so the flattening mostly doesn't apply here.

Rail group	Item	Route
Manage	CRM → Pipeline	`/crm/pipeline`
	CRM → Contacts	`/crm/contacts`, `/crm/contacts/[id]`
	CRM → Tasks	`/crm/tasks`
	Calendar	`/calendar`
	Docs & e-sign	`/documents`, `/documents/[id]`, `/documents/upload`

Same route shapes as before the teardown. Nothing here is new versus the deleted build — restated for confirmation, not as a change, since the rebuild isn't evolving the old code and needs its own clean start.

05 — Contact, the hub

One timeline, one document list, one right-rail summary — not a 5-tab command center.

The reference's Contact Detail splits into five horizontal tabs (Profile & Identity, Communication, Live MLS Activity, Documents & E-Sign, Tasks & Milestones) plus a separate 3-column panel. Already tried in spirit and walked back once: a call, a text, a stage change, and a favorited listing are all just entries in one Activity timeline with a provenance tag (Agent / Site / System) on each row — that's what replaces four of those five tabs. Kept from the reference: the idea that a Contact page should feel like a real command center, not a form — just built as one unified surface instead of five.

Right-rail summary — identity, editable pipeline stage, tags, co-buyer/referred-by, and whichever of these two apply and are real: seller → their actual listing (a real row, real price, real status); buyer → their saved search + favorited listings (both derived from the Activity log, not separately invented)
Center — Activity timeline — every call, text, email, note, meeting, showing, consultation, deadline, stage change, and favorite, provenance-tagged, newest first, same list that also powers Tasks and Calendar
Documents panel — this contact's rows from the documents repo, status and signers visible without leaving the page

Two fields worth adding back, both real — proposing, not deciding. The reference's Pre-Approval field (amount + named lender, e.g. "$850,000 — Chase") is a different category of fact than the target-price/budget figures already ruled out: those were guesses with no source, this is an agent-verified fact tied to a named real lender. Worth adding as an optional field the agent enters once they've actually seen the letter — never shown unless a lender name is attached, so it can't degrade into a bare guess. Second: a buyer currently has no listingId once they write an offer — worth setting one at "Offer Written," sourced from whichever listing they were actually shown or favorited, not a new invented fact. Flagging both for a decision, not assuming yes.

06 — Pipeline

Stale-deal and lead-source badges are real today. A dollar total isn't, yet.

The reference's board adds a metric strip (Total Pipeline $, Est. GCI, Closing This Month, Stale Deals) and per-card badges (lead source, lead temperature, pre-approval status) on top of the stage columns already built. Sorted by what's actually derivable versus what would have to be invented:

Stale Deals badge — buildable now. lastActivityDaysAgo() already exists as a real derived value; a card with no activity in >10 days gets the badge, no new data needed.
Lead-source badge — buildable now. Every contact already carries a real source (Home valuation, Digital card, Site contact form, etc.) — just surface it on the card.
Pre-approval badge — buildable if §05's field is approved. Depends on that decision, not a separate one.
Lead-temperature ("Hot") badge — not buildable honestly. No scoring signal exists to compute it from; cut per §02 rather than faked with a placeholder value.

Total Pipeline $ and Est. GCI — open question, not decided here. A seller's deal value could be their real linked listing price, no invention needed. A buyer's deal value has no real number to point to until they're under contract at a real price, which isn't tracked yet. Est. GCI additionally needs a real commission rate on file for the agent, which doesn't exist as a field today. Recommendation: skip both metrics for now rather than approximate them — revisit once a buyer's contract price and an agent commission rate are both real fields, not before.

07 — Tasks → Daily Action Queue

Each row's primary action matches what the row actually is.

The one clear upgrade from the reference worth adopting outright (§01). The first Tasks build had a single "mark complete" checkbox for every row regardless of kind; the reference's per-row contextual action is a real improvement and everything it needs already exists on the Activity type:

Activity kind	Primary action	Always available
call	Call (`tel:`)	Mark done · Snooze (+1 day)
text	Text (`sms:`)
email	Send email
deadline / note	View contact
meeting / showing / consultation	View contact
stage / favorite	— (system rows are always `done: true`, never queued)

Snooze is new. Not present in the first build. A real, small addition — pushes dueInDays by one, same field that already drives sort order and overdue/today/upcoming grouping, nothing new to keep in sync.

08 — Documents & e-sign, data model

Already right. Comes back close to as-was, no schema changes needed.

The reference's own three-way ESIGNABLE / STORE_REVIEW / WET_INK split (§01) confirms the existing 27-type, five-category taxonomy rather than asking for a different one — this module's rebuild is closer to a restore than a redesign. One real, separate note on the reference's Prisma schema: it models deals as their own table, distinct from contacts, so one contact can carry multiple deals over their lifetime (a past client becoming a new lead years later). KeyRingOS's fixtures still treat a contact as one deal — correct for now, since there's no schema or auth yet to migrate, but worth flagging as a real future question rather than a decision made by omission.

09 — What's next

Review this, then wireframe — in that order, same as asked.

Nothing below is live — the CRM was fully torn out pending this document. Two decisions in §05 and §06 are flagged rather than assumed (pre-approval + lender field, buyer offer listingId, and the Total Pipeline $ / Est. GCI skip) because they're genuine product calls, not implementation details. Once this is confirmed, the rebuild starts fresh against this spec — not evolved from the deleted code.