Key concepts

Contacts and leads

Every person Matilda talks to is a contact, keyed by phone number. A contact has a role, either lead or agent. Leads are the buyers and sellers Matilda qualifies. Agents are your own team members who text Matilda for help with follow-ups.

A lead moves through a fixed status ladder:

Status	Meaning
new	First contact, nothing captured yet
qualifying	Intake in progress, some fields captured
qualified	All five milestones captured
showing	A showing has been arranged
nurture	Not ready now, keep in touch

Qualification milestones

Exactly five fields make a lead qualified:

1. Name
2. Intent, one of buy, sell, or browsing
3. Budget
4. Timeline
5. Pre-approval, one of yes, no, in progress, or unknown

Each captured milestone adds 20% to the lead's qualification score. When all five are present, Matilda promotes the lead to qualified automatically. The handoff email fires exactly once, on the first transition from an earlier status to qualified.

Matilda also captures areas of interest and a property interest where they come up, but those do not gate qualification.

Intake

When a contact is new or incomplete, Matilda runs a light intake flow. She asks one question per reply, always the first field still missing, in a natural order:

1. Introduce herself and ask for a name
2. Ask about intent
3. Ask about budget and timeline
4. Confirm pre-approval and offer a showing

She never re-asks a field that is already filled. If nothing is missing and the contact is onboarded, she skips intake and just helps.

Known contact block

Before every turn, Matilda receives a fresh summary of who she is talking to: their name, everything already captured, their long-term memory, and a list of what is still missing. She treats this block as the source of truth over anything in the message history.

Memory

Each contact has a memory field of curated long-term facts. After each turn a separate extraction pass reads the exchange and updates the profile and memory. This is what lets Matilda remember that someone prefers mornings, has a dog, or is relocating for work.

Conversations and sources

Every message is stored with a source:

• matilda for messages exchanged through the agent, whether over BlueBubbles or the web chat
• personal_imessage for threads synced from the realtor's own Mac by the Matilda Worker

Worker-synced threads are captured but never auto-replied to.

Lead events

The Captured timeline on a lead's detail page is built from lead events. Each event records a kind, capture, status, or fub, along with the field and value involved. Events are written by the worker ingest path and are display-only.

Handoff

When a lead becomes qualified, Matilda generates a share token and builds a public lead sheet at /lead/<token> with a PDF twin. If Resend is configured, the brokerage notification list receives the link.

Organization, teams, and roles

Operators sign in to the dashboard with an email and password. Each belongs to an organization and any number of teams. Teams are a label only. They never scope what data someone can see. Access is governed by three roles: Viewer, Admin, and Owner. See Organization and roles.

Settings precedence

Every integration can be configured in the environment file or live on the dashboard Setup page. A value saved on the dashboard is stored in the database and wins over the environment value. No restart is required.