Leasing Engine — Technical Designs

One place for every leasing design: touring, tour notices, staff check-ins, the prospect record, and the guest cards we write back into AppFolio. Three separate pages were folded in here on 2026-09-17.

Published 2026-09-17 · scope: Camellia (live), Western Slope (launching), Situs Group (next), Fairhaven + Willows (test) · owner: Trinity

TL;DR

The principles every design below obeys:

• The org is the wall. Nothing crosses a company boundary; calendars, lines, mailboxes and people attach to an org or to a property inside it.
• The engine decides. No screen ever asks a human to link, merge, confirm or approve what the system already knows. A wrong decision is fixed in the engine.
• Staff talk to Clara by text and voice, never through a typing UI. The phone number is the login. There is no notes box to open and no app to install.
• Nothing is stored twice. The host is whoever owns the calendar the tour event sits on — that is the whole rule. No host field, no second copy to keep in sync. If somebody covered, that is a sentence in the tour's notes, not a field.
• Dark, then a test property, then Fede. Everything ships to production switched off, is proven at Fairhaven or Willows, and turning it on at a real client is Fede's separate call.
• Every live property benefits. These are features for the whole portfolio, not a branch for one client. Camellia migrates onto the same settings, it does not stay on a separate track.

The architecture in one line. Every channel funnels through one identity check into one touring engine; the tour record is the hinge, and everything after it is either a message to a person or a write through the single outbox to AppFolio.

Map

What is in this document, what state it is in, and where to jump.

Why this is one page

Every design here touches the same machinery — hours, calendars, the tour record, the staff notice, the outbox to AppFolio — and every one of them is written so it works the same way for whichever property turns it on next. Keeping them on three separate pages meant a session picking up leasing work had to already know which of the three to open. Now there is one place. Article III-A of the operating constitution is the reason none of these is a single-client page: a new-client feature has to work for every live property, with no regressions.

Proposed — pending review. Nothing on this page is a final ruling except where a decision or PR is explicitly marked merged, shipped or decided. Every open call is collected in section 19.

Tour designs

Sections 1–7. Absorbed from Leasing tour designs — September 2026 (2026-09-16), with section 6 and section 7 updated for Fede's 2026-09-17 rulings.

1. Touring hours vs. office hours

The problem

Clara has exactly one "hours" field per property, officeHours, and it answers two different questions at once: "is the leasing office open" and "can I offer a tour then." Western Slope's map is set to real reception hours (closes 3pm Friday, closed weekends), so any evening or weekend tour request gets refused as if the office itself were shut — which is what happened on a real call this week. Camellia only avoids this by accident: someone happened to type Saturday hours into the one field that exists.

The decision

Two other shapes were considered and set aside: splitting office_hours itself into two renamed fields (cleaner long-term, but a much bigger, riskier rewrite touching dozens of call sites, and duplicates work Gera's settings-ladder swarm may already be planning); and a simple on/off toggle for "tour hours match office hours" (rejected — it models a business fact, not a new behavior, and Fede's 2026-09-03 ruling is that switches shouldn't be added just to model a fact).

The design

Registry mechanics match the existing tour.durationMinutes precedent: org sets a default, property can override, nearest wins.

PR chain — status as of now

• #9013Add the tour.hours registry key, dark, no reads wired yetopen
• #9036Wire tour.hours into the slot-generation and booking gates (PR 2/4)merged
• —PR 3/4: prompt wording + voice-harness scenarionot started
• —PR 4/4: staff-set script scripts/settings/set-tour-hours.ts + Willows/Fairhaven end-to-end proof + Western Slope dry runnot started

Everything here ships dark. Turning tour.hours on for Western Slope is a separate step, on Fede's go, per the standard rollout ladder.

No settings UI ships from this side; Gera's team owns the settings UI.

Still Fede's call

1. Confirm the property-owned registry entry (tour.hours) is the right home, versus folding this into a bigger reshape of office_hours that Gera's settings-ladder swarm may already be planning. Recommended: sibling key, additive, no schema change to office_hours
2. When PR 1–2 land: approve Western Slope's actual touring-hours values (Mon–Fri 8am–6pm, Sat/Sun 10am–3pm) before they're set live. Settings UI itself is Gera's to build, not this page's.
3. Confirm this stays off for every customer, including Western Slope, until Fede explicitly turns it on — the new field ships dark by default.

2. Weekend booking cutoff + confirm-or-cancel

The problem

Western Slope asked for two things Fede believed Camellia already had: a Friday cutoff on booking weekend tours, and an automatic cancel if a prospect never confirms. Neither exists today, for either client. The only related code (a same-day booking ban) was never turned on for Camellia, and the "ask for confirmation" flow exists but currently does nothing when nobody replies — an unconfirmed tour just sits on the calendar forever.

The decision

The weekend cutoff itself should be a fixed calendar deadline — "no new weekend bookings once Friday hits a set time" — not a rolling "N hours before the tour" rule, because a rolling rule silently drifts across Saturday vs. Sunday and can't express "cut off exactly at Friday close" cleanly. It's enforced twice: once when Clara offers slots (a blocked weekend is never shown), and again at the moment of booking, so a determined caller can't slip through by asking for an exact time the slot grid didn't show.

The design

On refusal, Clara never just says no — she offers the next open weekday and next weekend. On an unconfirmed tour timing out, the calendar hold is released, the team gets the existing cancellation notice, and the prospect gets a plain "we released the time, reply anytime to rebook" message rather than silence.

PR chain — status as of now

Design only. No PRs opened yet for either the cutoff or the cancel-on-timeout fix — both are proposals pending the calls below.

Still Fede's call

1. Ship the cancel-on-no-reply fix for every property, or gate it to weekend tours only for now? Recommended: everyone — it's an existing bug, not a new behavior.
2. Camellia's own "confirm or cancel" ask couldn't be found in any record — only a Situs ask for a longer pre-tour text window, and an unrelated staff no-show. Treat as Western-Slope-only for now, or is there a specific conversation to re-check? Recommended: Western-Slope-only for now; flag Camellia's version as unverified
3. Does "no weekend bookings after Friday" mean a hard calendar cutoff regardless of how far out the weekend date is, or just more lead time on weekend requests? Recommended: hard cutoff — matches how Fede described it ("not creating a tour on Saturday").

3. Backup tour host

The problem

Western Slope has one leasing agent, Kat, connected for tours; the client wants Jonathan (maintenance) as a backup, and possibly a second backup from another company (Fusion) later. Today the tour-booking code only ever looks at the first connected agent's calendar — there's no concept of a backup or of combining more than one person's free time, and Situs Group will need a full multi-agent assignment engine on the same foundation soon after.

The decision

Availability: ask the primary's calendar first; only fall to backup when the primary has nothing open in the window, or their calendar connection is dead. The prospect is offered one merged list of times and never picks a person or sees two calendars. Whoever's calendar actually had the open slot hosts the tour — the team notice says who; the prospect-facing confirmation still never names the host, per the standing rule.

The design

PR chain — status as of now

Design only. No PRs opened yet — this was investigation and design tonight, per Fede's own sequencing ("tonight: investigation only").

Still Fede's call

1. Build the minimal sequential-fallback version first and redo it as a merged pool later, or build the merged pool now? Recommended: merged pool now — one more PR, avoids a rebuild.
2. Is Ryan (Fusion) a same-company backup or a genuine cross-company partner? A cross-company backup needs an explicit membership across Gera's company "wall," not just a calendar hookup. Recommend confirming which before Ryan's calendar is added at all.
3. Should backup's daily tour slots be capped so a maintenance person's day job isn't crowded out by tour bookings? Recommended: yes, a small daily cap.

4. Observer BCC on staff notices

The problem

PropFlow used to quietly copy hello@propflowai.co on client staff notices so the team could see what Clara was sending. It went through three rounds — added, pulled for flooding the shared inbox, added back narrower, then removed for good in September "pending a future per-client setting." This is that follow-through: a real, deliberate way to watch a new client's notices for a while, not the old blanket CC.

The decision

BCC beats the old CC approach: it's invisible to the client, so it can't collide with an address already on their own CC list the way the old version once broke Camellia's lease-signing notices. It ships with an on/off flag and an auto-expiry date, so nobody has to remember to turn it off once the team trusts the client's notices are working.

The design

PR chain — status as of now

• #9000Add BCC support to the email sender (PR 1/4)merged
• #9001Add the observerBcc setting + resolver (PR 2/4)merged
• #9023Wire the resolver into sendEmail so all ~18 staff notices pick it up automatically -- now also carries the #9032 wiring + proof, waiting on the #9001 re-landopen
• #9031Admin CLI + writer to set an org's observer BCC listmerged 2026-09-17 03:56Z
• #9032Wiring + end-to-end proof harness -- merged into the #9023 branch, not mainmerged into #9023

Everything above ships dark (empty lists, no-op). Turning the BCC on for Western Slope's real mailbox is a separate step and needs Fede's own go — it's a live client-facing mailbox change even though the client never sees it.

#9001 is being reverted from main by #9035: its resolver read a company row inside settings-resolver.ts, caught by the portfolio harness probe E19-b, and will be re-landed with that company read moved to a fetch shell. #9023 (now carrying #9032's wiring and proof) waits on that re-land, with auto-merge disarmed until then.

Still Fede's call

1. Which mailbox receives the BCC? Recommended: a new dedicated inbox (e.g. observer@propflowai.co), not hello@ — that address is now also the public contact-form inbox, and mixing traffic back in risks the same "drowned in noise" complaint that killed the original version.
2. Default state for brand-new clients: on automatically with an off switch, or a visible onboarding toggle (defaults on)? Recommended: visible onboarding toggle — matches "give us a way to subscribe, then turn it off," and nothing sits on silently forgotten.
3. Auto-expiry: manual off only, or a built-in expiry date (e.g. 60 days) unless renewed? Recommended: 60-day auto-expiry.

5. Prospect card & tour notice

The problem

Two related but separate pieces of work: what should be on the one-line "prospect card" a leasing agent sees before a tour (move-in timeline, budget, occupancy, bedroom count, and a short one-line summary — never anything that touches fair-housing-protected categories or feels like a background check), and a real bug where the team's tour notice email carried a hand-written note that had gone stale compared to the actual, current summary of the conversation.

The decision

Card research recommends a terse, SBAR-style structure (Situation / Background / Assessment / Recommendation — borrowed from healthcare handoffs) capped at a handful of scannable lines, action-first, no hedging, and a hard "never" list: no credit or background detail, no subjective "vibe" notes, nothing about a protected class. This shapes future card work; it did not itself require a code change. The tour-notice bug did, and it's already fixed: the note on the PM notice now always reflects the live summary instead of a copy that could drift stale.

PR chain — status as of now

• #9016PM tour notice: stop showing a hand-written note that can go stale against the live summarymerged

Still Fede's call

1. Adopt the SBAR-style card structure as the target shape for the prospect card, or keep the current flat field list? Recommended: SBAR structure — terser, and matches how high-performing leasing agents actually pre-qualify.
2. Any of the "nice-to-have" fields (pet type, income indication, reason for move, amenity wishlist) worth building now, or hold all of them for a later pass once the must-have fields are live? Recommended: hold — ship the must-have set first, revisit once it's used on real calls.

6. The prospect notes field — audit and cleanup (Proposed — pending review)

Status: Audit complete 2026-09-17; nothing changed in code yet; tour-notice fix in flight separately.

TL;DR

notes is one free-text string on the prospect record with thirteen automated writers and no author, no timestamp, and no link to the conversation that produced it. It was born on 2026-03-04 as a plain field on a hand-seeded fixture, with no stated purpose and no staff form ever built to type into it. Every current writer is a machine: two Clara call tools, the email tour pipeline, the aggregator-lead settling pass, two voice post-call extractors, the duplicate-merge bookkeeper, and the AppFolio orphan sweep. They all append through mergeProspectNotes, which keeps the ten newest segments and stamps nothing. The staff tour-notice email then reads that string and renders its newest segment as short "facts" chips about the tour it is announcing — so whatever the last writer happened to leave there becomes, visually, a fact about this booking. That leak has fired three times in two weeks: Yale 2026-09-04 (a ten-day-old reschedule fragment), Western Slope 2026-09-12 (the sibling aiNotes field), Western Slope 2026-09-16 (an earlier call's maintenance mention). The 2026-09-16 guard (freshHandWrittenNoteForTour, PR #9016) is a genuine band-aid: it drops the note when it is datably older than the tour, but a row with no updatedAt still renders unconditionally, and a note written by a different module seconds earlier in the same request still renders as tour context. The real fix is that the tour notice should build from the booking's own record — Tour.notes already exists and is already written — and notes should stop being a shared dumping ground. Caution is warranted: notes is load-bearing in four non-obvious places (the voice reconcile's "is it empty?" gap check, the prospect card's unit-mention extractor, the merge audit trail, the ten-segment cap), so the cleanup has to be ordered, not blind.

Who writes it

None of the thirteen writers stamps who wrote a segment or when. No dashboard writer of notes exists — the prospect edit API only writes aiNotes. AppFolio guest-card sync does not copy the card's own comments into notes (that leak does not exist).

Who reads it

notes is never injected into any Clara prompt — both the voice and SMS/email personalization paths read aiNotes instead. No AppFolio push of notes or aiNotes exists.

Cross-module leak map

Why the 2026-09-16 fix is a band-aid

• A row with no updatedAt still renders unconditionally, and the freshness check is row-level, not field-level — any unrelated write to the row (a preference, a cadence stamp) refreshes a months-old note enough to pass the gate.
• It only rejects notes datably older than the tour; a note written by a different module seconds earlier in the same request still renders as tour context, because the gate checks freshness, not authorship or subject.
• Two aiNotes writers set no aiNotesAt at all, which puts those rows into the same "unknown age renders" carve-out and quietly disarms the sibling PR #8083 gate too.

Target design

notes therefore ends with no writers at all and is deleted. Every current automated writer moves to a per-interaction record: Tour.notes (already written, already passed to the tour email as visitNotes) for anything about a booking; ProspectInquiry.aiNotes + aiNotesAt for conversation content; and typed fields (leadFacts, preferences, desiredBedrooms, desiredMoveIn, moveInNote, targetUnitId, targetHomeAddress) for facts that already have a typed home. The tour notice itself builds from the booking's own record — Tour.notes/visitNotes plus the typed facts strip — never the person-level append log.

One writer, one contract

The reason thirteen writers happened is that anything could write the field. The replacement is a single chokepoint. One write function takes every note, wherever it came from, and refuses it outright unless it carries four things: the interaction id it belongs to, the channel it arrived on (text, voice note, call, email, sync), the author (a person id or a named system module), and a timestamp. A note with no interaction id is a bug, not a note, and the function throws rather than storing it somewhere general. It writes to the interaction or tour record — never to a person-level string — and readers ask for notes by interaction, so no surface can ever pick up a note that belongs to a different conversation. A lint rule blocks any new write to the old field, so the class of bug cannot come back through a module written next month by someone who never read this page.

Safe migration order

1. Add notesWrittenBy + notesWrittenAt metadata (or convert to a ProspectNote[] shape with author/time/conversationId, mirroring WorkOrderNote). Pure add, low risk.
2. Risky — tour notice stops reading notes; reads Tour.notes/visitNotes + typed facts only. This is the actual fix and ends the leak class outright. Risk: bookings with no Tour.notes lose their chip line — measure coverage in prod before merging.
3. Gate the calendar invite's ungated "AI Notes:" line the same way the email path is gated. Low risk, self-contained.
4. Make aiNotesAt mandatory on every aiNotes write. Low risk, closes the "unknown age renders" bypass.
5. Delete the extractor failure text; log it instead. Low risk, no legitimate reader.
6. Retire the dashboard's derived readers (units-shown, move-in fallback) onto the typed fields that already exist. Medium risk — measure typed-field coverage first.
7. Retarget the voice reconcile gap check off notes onto leadFacts/preferences presence. Do this before step 8 — leaving it pointed at notes while writers are removed makes every leasing call pay for a model call it used to skip.
8. Stop the automated writers, one PR per module, easiest first: email pipeline → aggregator → voice intake → reconcile → Clara call tools. Only safe once steps 2, 6 and 7 have landed.
9. Move the bookkeeping lines (merge/un-merge/orphan-sweep) off notes onto mergedIntoId/closedReason/a sync-status field; update the one script that reads them today.
10. Delete the notes field and its type. No dashboard editor is built — staff notes arrive through Clara and land on the interaction/tour record.
11. Risky — clean existing rows. Irreversible data deletion; last step, and only after a dry run printing counts and ids, and only once earlier steps have run long enough to prove nothing still reads the old content.

Still Fede's call

1. Land step 2 (tour notice reads Tour.notes instead of notes) now that it's designed, or wait for a measured Tour.notes coverage number from prod first? Recommended: measure coverage first — it's the step that changes what a customer's leasing team sees on every tour email.
2. Order of stopping the automated writers (step 8): all five together, or one PR at a time with a bake period between each? Recommended: one at a time — each is only safe once steps 2, 6 and 7 have landed, and staging them makes a regression easy to attribute.
3. Timing on step 11 (deleting existing row content): schedule it now for a fixed future date, or leave it open-ended until the earlier steps have baked? Recommended: leave it open-ended — it's irreversible, and 872 Western Slope rows alone carry notes today with other orgs still unmeasured.

7. After the tour: Clara checks in with the leasing agent (Proposed — pending review, not for today)

Whole design written down once so the shape is settled; we build it as small dark pieces, and none of it reaches a customer without Fede turning it on.

The picture

Solid lines are the first build; the dashed call-in leg is the later vision, and the design is shaped so it plugs into the same intent record rather than needing its own path.

a. What the client asked for

From the Western Slope onboarding call on 2026-09-16, raw transcript, with Kat (their only leasing agent) in the room.

So the ask is confirmed by the client in his own words, and Jason also volunteered the two things that make it worth building: his agent forgets to write showing notes, and she is being stood up more than usual. Both of those are answered by the same one-line text.

b. What happens after a tour today

Every automated step after a tour is aimed at the prospect. Nothing is aimed at the person who ran the showing.

Three gaps matter here. There is no no-show state at all — the workflow's outcomes are only completed / cancelled / awaiting-confirm-timeout / activity-failed (tour-workflow.ts:141-145) and a tour's scheduling state is only proposed / confirmed / cancelled / declined (statuses/tours.ts:5-20); "no-show" today is a statistical guess derived from "confirmed, date passed, never applied" (insights/signals/tour-no-show.ts:7-12). Who is scheduled to show is the calendar, and that is deliberate — Tour.calendarNode (types.ts:11664, shape at :11677) points at the calendar that took the booking, and at Western Slope and Camellia every connected calendar belongs to exactly one person, so the pointer already answers the question. No host field is being added, now or later (Fede, 2026-09-17: "we're over engineering. Let's just assume that whoever had the calendar event showed up"). A stored copy would have to be kept in sync with the calendar and would drift the first time somebody moved an event. When the assignment changes, we move the calendar event and the pointer follows. There is no "actual host" field either — a cover is a sentence in the notes. Tour.notes exists but is only ever written at booking time (types.ts:11643, written once at apply-tour-intent.ts:657 from Clara's schedule_tour argument) and is what the staff tour email renders as visitNotes (send-pm-tour-confirmation.ts:303). Nothing writes it after the tour — which is exactly the slot the agent's notes belong in, and the reason they must never go near the person-level notes field that section 6 is cleaning up.

c. The proposed flow

Where each outcome lands

Outcome and interest are new typed fields on the tour and the inquiry. The agent's free text goes to Tour.notes — never to the person-level notes field, which section 6 is in the middle of retiring as a cross-module leak.

Quiet hours, nudges, and silence

• The check-in respects the agent's own quiet hours. The handyman persona already owns this pattern — set_my_quiet_hours (capabilities/handyman.ts:43-53) — and the same field is reused rather than a new one invented. A tour that ends after hours gets its check-in the next morning at the start of the window.
• One nudge maximum, the next morning, and only when the tour had a prospect who has not applied. After that, silence. Nobody gets nagged twice about paperwork.
• If the agent never replies, nothing escalates, nothing turns red, no one is paged, and the prospect's timeline is untouched. The tour simply has no notes, which is the situation today.

d. Pinned context: Clara knows what the thread is about

Fede's requirement is that the agent can answer "oh these are the notes: …" with no structure at all and Clara already knows what she means — and that Clara never loses the thread the way she has before. That is a data problem, not a prompt problem.

A conversation today is one row per person per property, found on the inbound side by resolving identity then looking up by Person id (conversation-manager.ts:3560, GSI6 lookup at :3636-3644). It carries derived topic sets and one narrow "working object" pointer, Conversation.activeContext (types.ts:10237, shape at :9354-9370), which today can only bind to a turnover or a work order, is stamped from an inbound turn (conversation-manager.ts:7870-7935, via active-context-binding.ts:145), and is cleared by events rather than a clock. Nothing today stamps that pointer when the system initiates a thread — that is the missing piece.

When a reply arrives on that agent's thread, the router reads the binding, loads the intent, and the model is given the tour in its context before it reads the agent's words. It is the same mechanism the turnover intake already uses to resume a walk mid-conversation, extended to one more kind of working object.

e. Late, ambiguous, and second tours — and notes from someone other than the host

Kat may answer four hours later, from the couch, having shown three homes in between. The rule has to work then.

• The window is 12 hours from the tour's end. An intent stays open and answerable that whole time; the pin is not cleared by an unrelated message in between.
• Default: the most recent open tour-notes intent for that agent. When only one is open, or when one is clearly the most recent, Clara files the notes there without asking anything.
• Ask only when it is genuinely ambiguous — two or more open intents whose end times fall within four hours of each other, and the agent's message names neither a property nor a prospect. Then Clara asks exactly one short question naming both candidates by time and first name: "the 2:30 with Ana or the 4:00 with Marcus?" One question, then she files.
• If the agent's message names a property or a prospect that matches an open intent, that match wins outright and no question is asked.
• After 12 hours the intent closes. A later message still lands as a normal staff conversation; it just is not auto-filed to a tour.
• Notes from someone who is not the host later, not built now — an assistant or the PM texts notes for a tour they were not scheduled on. There is no open intent pinned to them, so Clara runs the same short confirm flow rather than guessing: she looks at the org's tours that ended in the window and asks one question naming the candidates, "which tour — Ana at 2:30 or Marcus at 4:00?", then files it once answered, recording who reported it. Same disambiguation rule as above, reached from the other direction: the host case asks only when two of their own tours are close together; the non-host case asks whenever the sender's most recent tour is not obvious.

f. Voice notes and, later, calling Clara

Voice notes already work. The Twilio inbound webhook handles media today: it reads NumMedia / MediaUrl{n} / MediaContentType{n}, classifies each attachment, and for audio downloads it and transcribes it through ElevenLabs Scribe before the message reaches the agent loop (src/app/api/twilio/webhook/route.ts:341-424; transcription at integrations/voice/scribe-transcribe.ts:76). An agent talking into her phone and sending it as an MMS is, as far as Clara is concerned, just text. Nothing is missing on this path — it needs no build, only the tool set and the pin above.

Calling Clara comes later, and it works like a turnover walk. Fede's shape for it: the agent calls, says "okay, this is what happened", and Clara listens and takes notes without interrogating — then files it when the agent is done. That voice UX already exists as the turnover intake persona, getClaraTurnoverWorkflow in agents/clara/lib/agent/clara-turnover.ts:1-217, which is explicitly built as an ambient scribe on voice: reactive, backchannel-gated, it does not drive the conversation. That is the module to reuse — the leasing check-in is the same pattern pointed at a tour instead of a unit walk. What is missing is upstream: the voice personalization webhook (src/app/api/voice/personalization/route.ts) classifies a caller as tenant, prospect, vendor, denied applicant or unknown and injects context as ElevenLabs dynamic variables (:3047 onward), but it has no staff branch at all — a leasing agent calling in today is treated as an unknown caller.

Because the intent record holds the state and the tour, not the channel, all three inputs converge: a text, a transcribed voice note, and a call are three ways of filling in the same open TourNotesIntent. Adding the call later adds a branch to the voice webhook and reuses the identical filing code.

g. Roles: personas are tool sets, and property manager is a superset

Fede's rule: the leasing agent is the minimum staff role and sees leasing only; the property manager has everything the leasing agent has plus maintenance, turnovers and vendor work. Built as a strict superset, a PM who runs a showing herself and texts Clara afterwards gets the identical tour-notes flow with no special case.

How this sits with Gera's portfolio model. The current direction on that page (16 September) is that roles describe and route work; they do not restrict ordinary in-scope reads or edits, and platform Admin is a separate three-person boundary. This design honours that: the role decides which tools Clara offers a texter, which is a routing and usefulness decision, not an authorization gate — and the existing code says the same thing, that staff tiers are a persona signal only, with guardrails living on the tool handler. org_admin, property owner and PMS credential holder are the ownership roles from that model and are orthogonal to this; the two that matter here, leasing_agent and the PM tier, already exist as PersonRole types.

What is missing on the people side. A Person carries no phone number directly — contact points live on separate identity-claim rows reached through primaryClaim (types.ts:16596-16680), so onboarding has to capture the agent's mobile as a claim for any of this to reach her. Leasing-agent assignment is org-wide, not per property: the calendar pool looks up every leasing_agent role in the org and the first connected one wins for every property, a gap the file itself documents (tour-calendar-pool.ts:33-40). And Western Slope's own test fixtures record Kat as org_admin rather than leasing_agent, which would put her in the PM tier — a data-quality item to fix before this is switched on anywhere.

h. What this extends, and what has to be built

Most of the machinery exists for other staff personas. The honest list:

i. Rollout

Standard ladder, no exceptions. Everything below ships to production dark behind a per-org switch that defaults off, so no agent at any live property is texted by anything that merges. Proving runs at Fairhaven (test) and Willows first, with a real tour booked on a test agent's own calendar and a real reply from a test handset — text first, then a voice note. Western Slope is the first candidate customer, with Kat's mobile captured during onboarding, and turning it on there is Fede's call and nobody else's. Camellia inherits the same switch, off, and turns on the same way — this is a feature for every property, not a Western Slope branch.

PR chain sketch

• 1Tour outcome record — toured / no-show / rescheduled, prospect interest (applying / not interested) and notes. No host field and no “who actually showed” field: the host is whoever owned the calendar event, and a cover is a sentence in the notes~120 lines
• 2TourNotesIntent record and its writer/reader, dark~200 lines
• 3Extend ActiveContextBinding with a tour_notes kind; stamp it on an outbound-initiated thread~180 lines
• 4Post-tour check-in timer on the tour workflow + the per-org switch, default off, no send wired~200 lines
• 5The outbound check-in itself: host resolution, message, quiet hours, one-nudge rule~250 lines
• 6leasing-agent capability + the first two tools (add tour notes, mark outcome) and their handlers~280 lines
• 7Reply routing + the disambiguation rule (12-hour window, one question)~220 lines
• 7bLater: notes from a non-host — org-scoped tour lookup + the "which tour?" confirm flow, recording who reported itlater
• 8Outcome effects: suppress the app link and chase on no-show / not-interested; personalise the link with notes~180 lines
• 9Property-manager tier inherits the leasing tool set (the superset wiring)~80 lines
• 10Remaining tools: block my calendar, who's touring today~250 lines
• 11Guest-card note intent onto section 15's AppFolio outboxdepends on section 15
• 12Later: staff branch on the voice webhook, reusing the turnover ambient-scribe personalater

Each PR is one concern and dark on its own. The first customer-visible moment is the switch being turned on, which is a separate step and Fede's.

Still Fede's call

1. How long after the tour does Clara text the agent? 15 minutes, 30, or 60? Recommended: 30 minutes after the tour is due to end — long enough for a showing that runs over, and still ahead of the prospect's application link at start+60 so the answer can shape it.
2. Does the prospect's application link wait for the agent's answer? Recommended: no — it goes at 60 minutes as it does today, personalised with the notes if they have arrived, and suppressed entirely if the agent said no-show or not interested. Making a prospect's message wait on a staff reply risks it never going out.
3. Text only to start, or text plus a tour-notes box in the dashboard? Recommended: text only — "there's no app, there's no login" is the point, and a second surface splits where notes live before the first one has proven itself.
4. If the agent never answers: one nudge the next morning then let it go, no nudge at all, or keep asking? Recommended: one nudge, next morning, then silence — Jason asked for the reminder, but a second nag is how staff start ignoring Clara.

Clara inside AppFolio — guest cards

Sections 8–16. Absorbed from Clara inside AppFolio (2026-09-12 night, extended 2026-09-17). The tabs are gone; the content, decision lists and PR/switch tables are unchanged.

sequenceDiagram
    autonumber
    participant C as Caller
    participant V as Voice line (Clara)
    participant R as call-ended route
    participant P as PropFlow store
    participant Q as SQS FIFO per account
    participant L as agent-runtime Lambda
    participant B as Browser runner
    participant A as AppFolio

    C->>V: calls the leasing line
    V->>R: call ended (webhook)
    R->>P: prospect + inquiry + tour written (today's behaviour, unchanged)
    R-->>R: HTTP 200 returned here — nothing below adds latency
    Note over R: everything below runs in after()
    R->>P: reconcile guest-card facts from transcript
    R->>P: write the call's own summary record
    R->>P: append intent create_card to the PMS outbox
    R->>Q: publishAgentJob(appfolio.guest_card.write, idempotencyKey = intent id)
    Q->>L: one job at a time per AppFolio account
    L->>B: POST /api/guest-card/create (accountId, property, facts, envelopeId)
    B->>A: fills the guest-card form in the staff portal
    A-->>B: card created, uuid + party id
    B-->>L: { guestCardUuid, partyId }
    L->>P: stamp prospect.af.guestCardUuid, mark intent sent
    Note over Q,L: failure → SQS redelivers → DLQ + alarm, intent stays unsent

17. The touring engine

One visit, a list of people, more than one home.

Written overnight 2026-09-10 → 11, extended 2026-09-13 with the centralized-team layer (people and roles, availability pool, proximity, staff-text reassignment, lockbox self-showing, presence). The implementation half belongs to Gera's portfolio architecture, step 8. Companion: the voice agent architecture decision. Subsections 17.1–17.20 are the design; 17.A1–17.A7 are the appendices, including all eleven decisions in full and the raw client transcripts.

18. Roles and staff tools — audit

Everyone in the company already has a job title on file. Clara just forgets it the moment they pick up the phone.

Audit date 2026-09-17, read-only, against origin/main = ca109e0a14. Cross-checked against Gera's portfolio architecture.

flowchart TD
  P["Phone number"] --> RA["resolveActor and pm-call-context"]
  E["Email address"] --> RA
  L["Dashboard login"] --> AU["Session, then spine lookup"]
  RA --> PR[("PersonRole rows
org- or building-scoped")]
  AU --> PR
  PR --> V{"Channel"}
  V -->|Voice| VV["ONE true/false flag: pm_is_pm
leasing agent NOT seen as staff"]
  V -->|SMS and Email| VS["staff tiers kept,
then flattened to 'pm'"]
  V -->|Dashboard| VD["full role kept"]
  VV --> TV["Tools: the 4 turnover ones only"]
  VS --> TS["Tools: turnover + metrics + blast text
LEASING TOOLS EXPLICITLY REMOVED"]
  VD --> TD["Screens by permission matrix"]

The whole audit in one picture. Three doors into the same role rows. Only the dashboard door keeps the role intact; the two doors staff actually use throw it away.

18.1 The roles that exist

Login-side roles

Fede's ladder is already written there, nearly word for word (role-grants.ts:95-103): a leasing agent can "run leasing end to end: prospects, tours and renewals", and cannot "open maintenance or vendors at all"; a property manager runs "the day to day: leasing, maintenance, collections, residents and vendors." Supporting files: the invite menu role-catalog.ts:83-110, screen permissions permissions-source.ts, the invite ranking permissions.ts (ROLE_HIERARCHY).

Conversation-side roles (the spine)

A second, longer list used by Clara — same jobs, one different spelling. types.ts:16798-16815: tenant, prospect, pm, org_admin, leasing_agent, maintenance, viewer, platform_admin, vendor_contact, plus four team labels. The role row carries person + role + scope + active (types.ts:16853-16884), and scope is one company or one building (:16817-16828). Which count as staff: inbound-resolution.ts:45-56. Which count as "a PM": :68-74 — and that list excludes leasing_agent, maintenance and org_admin, which is the root of most of what follows.

Name mismatch worth knowing: the login says property_manager, the conversation side says pm. They are translated in exactly one place (link-user-to-spine.ts:118-146). Not a bug — but it is why searching for one word misses half the system.

Against Gera's model

No conflict found between this audit and Gera's model. The one place the code is narrower than his model is building-scoped staff on inbound (gap 7 below).

People records carry no role. A person record holds identity only (types.ts:16590-16668) — no role, title, isStaff or teamMember field; role always lives on a separate row. Phone and email are separate claim rows (:16751-16775), and lookup deliberately searches across all companies because an inbound text carries nothing but a number. Staff people come from the invite flow or a roster script — AppFolio sync never creates staff people. Escalation owner is an email string on the building (types.ts:3113), not a person. And there is no "tour host" concept: a tour resolves to a calendar, never to a named person — which is exactly the shape section 7 keeps.

18.2 Personas

Voice picks a persona from the number dialled and who the caller turns out to be; text picks a workflow body from capabilities, not from a persona name. The full list: Triage (front door, voice-agents/triage.ts:51), Leasing, Lease & billing, Maintenance-tenant, Maintenance-handyman, Renewal in/out, Unknown caller, Vendor outbound, Emergency relay, Escalation callback — plus Turnover intake, the one and only staff persona on voice (turnover-intake.ts:37, chosen when pm_is_pm == "true" at triage.ts:450). On text there is one PM overlay (clara-pm.ts:42-71) chosen by senderRole === 'pm' and nothing finer. There is no owner persona, and no tenant-vs-prospect persona split on text.

18.3 Tools, by role and by channel

The catalogue holds 151 tools (132 live, 19 planned) in src/lib/tools/; who may call what is declared once in role-matrix.ts:196-495. Two facts shape everything below:

• Only 61 of the 151 tools are conversational at all. A tool reaches a talking channel only if its spec fills in a voice field (tools/types.ts:595). By domain: maintenance 19, leasing 19, turnovers 10, renewals 6, lease-and-billing 4, platform 2, comms 1. The other 90 are dashboard and background work.
• All ~60 AppFolio tools are on no conversation channel whatsoever. None carries a voice field and none appears in any of Clara's text tool files. Every action a manager would want — "mark it rented", "post the vacancy", "send the lease" (appfolio.post_vacancy, set_unit_availability, send_new_lease) — is real, is permissioned, and is not reachable by talking to Clara. That is deliberate and out of scope for now — see below. The single exception is maintenance.create_work_order, which writes to AppFolio live.

Prospect and resident tools — what actually runs today

Staff-initiated tools — a staff member telling Clara to do something

This is the short table, and it is the point of the audit.

Voice is narrower than text everywhere. Turnovers: 12 catalogue tools, 4 on voice, 13 names on text. Renewals: 16 catalogue, 6 conversational. Two declarations of the same thing sit side by side (the catalogue's voice field and each agent's own config), so the per-channel surface has to be read off both. Also worth naming: MASS_COMMS composes only for a PM tier; the analyst-clarify write gate strips ~20 mutating tools when a PM asks about a resident; appfolio.notify_owner / notify_tenant are marked do-not-use; turnover tools are deliberately company-grade only; Telegram is a real channel type with no inbound webhook.

Two things that look like tools and are not. A tour outcome is never logged by a tool — it is inferred after the call from the transcript (voice/post-transfer.ts), which is exactly the gap section 7 closes. And vendor assignment on an ordinary work order is automatic (auto-assign-vendor.ts), not a Clara tool.

Future, not built — reassign_tour A manager tells Clara "Kat can't make the 2 PM, reassign it to Sam", by text or by call. Clara moves the calendar event onto Sam's calendar; the tour's pointer follows, so the host is Sam with nothing stored. The staff notice is re-sent, the prospect's confirmation is untouched (it never names a team member), and the after-tour check-in goes to Sam. Authority is a role check: the host themselves, or anyone with a role above the host — a leasing agent may hand off her own tours; a property or regional manager may move anyone's. Design detail in section 17.12; it depends on PR 2 below carrying the real tier instead of a flat 'pm'.

Where the tool gate is actually enforced

18.4 How each channel decides "this is staff member X"

18.5 Gaps against the target model

Target: leasing agent ⊂ property manager ⊂ org admin; the role recognised per company from the person record; the same tools on every channel.

Out of scope for now

Two findings from the audit are observations, not work (Fede, 2026-09-17: "we don't want to over scope"). They are recorded here so nobody re-discovers them as bugs, and they are deliberately absent from the gaps table and from every PR chain on this page.

• The ~60 AppFolio actions are admin-runner only. Mark rented, post vacancy, set unit availability, send a new lease — all real, all permissioned, none reachable by talking to Clara, because none carries a voice field. That is fine; nobody is asking to run the PMS by text.
• Vendor invoicing and invoice approval do not exist — not as a Clara tool and not as a dashboard route; invoices arrive through an automatic attachment parser with no approve step. Also fine for now.

18.6 Recommendation — four small PRs, in this order

• 1Widen call-time staff recognition from isPmTier to STAFF_TIERS, so a leasing agent, maintenance tech and org admin are seen as staff on the phone. One file: pm-call-context.ts.small
• 2Carry the real tier instead of flattening to 'pm' through senderRole, and add a leasing-agent prompt block beside the PM one.small
• 3Stop excluding staff from the leasing tools (capabilities/index.ts:242), so a leasing agent can actually use the leasing surface she already owns on the dashboard.medium
• 4Add the tour-notes tool pair, copying the turnover dictation flow that already works. This is what section 7 calls for.medium

Migration: none needed. Western Slope and Camellia staff already hold a role row from their invite; nothing is re-stamped. Anyone invited as property_manager keeps the PM superset; anyone invited as leasing_agent gains a surface they should always have had. Each of the four is its own dark, independently mergeable PR, in that order.

One thing here is a decision, not work. Gap 9 — email ignoring staff senders — is Fede's 2026-08-20 ruling, and the per-property override was deleted on purpose. Carving a hole in it so an agent can email tour notes is his call; nothing should be built against it until he says so.

18.7 Honest limits of this audit

• Line numbers were re-verified by hand for the role unions, the role matrix, staff recognition, capability composition and the tour calendar pool. Numbers from the wider sweep of the auth and email files are reported as found and were not each re-opened.
• ElevenLabs "linked tool ids" in the voice configs are opaque; their names were not decoded, so the voice tool counts cover the inline lists plus a count of linked ids.
• Person.category exists in the type but was not confirmed written by any live path — forward-looking only.
• No applicant or guarantor role value was found anywhere; reported as a negative, not proven absent.
• leasing-many-homes.ts is partly live; which of its sections reach a real call was traced through the slot files, not confirmed against a deployed agent.
• The AppFolio domain was counted two ways (60 matrix rows vs "~57-63 keys"); the exact count is around 60, and the finding that none carry a voice field was consistent across both reads.
• No handler file was found to be genuinely dead.

19. Open decisions

Every call on this page that is still Fede's, in one list. Each row links back to the section that explains it, where the full options and the reasoning live. Recommendations are ours; nothing here is decided until Fede says so.

39 open. One decision on this page is already answered and is listed at the bottom for the record.

Touring hours, cutoffs and hosts (sections 1–5)

The prospect notes field (section 6)

After-tour check-in (section 7)

Guest cards (sections 14, 15.11 and the appendix)

Touring engine, D2–D11 (section 17)

One core prompt in code (section 20)

Already answered, kept for the record

D1 · Where a calendar lives — decided by Fede, 2026-09-14: people's calendars; the company (leasing@) calendar stays as reserve and fallback. Full options in 17.A1.

20. One core prompt in code (Decided — option B, Fede 2026-09-18)

Fede's ruling tonight: voice agents share ONE core rule set in code, assembled per agent by the server. Duplicated rendered text inside ElevenLabs is fine — that's just where the finished words end up. What's not fine is fixing a rule by hand-editing a per-agent prompt file, because the same rule is sitting in nine other files nobody touched.

Today's shape — an audit of every hand-copied rule

Two passes over agents/clara/lib/voice-agents/*.ts, agents/clara/lib/agent/*.ts, after-hours-message-desk.ts and the voice personalization route, grepping for 15 rule families a Clara agent has to obey. Eleven of the fifteen already show up as a hand-typed sentence in more than one file. Four (move-in-first, no team-member names, end-call etiquette, knowledge-free-greeter/escalation) weren't run through this pass and need a follow-up grep before anyone rules on them — listed as unconfirmed below rather than guessed at.

Ranked worst first: a family with wording that has already drifted apart between files is the strongest case for a core rule, because it's proof two engineers each wrote the same rule slightly differently and nobody would ever notice until a call went wrong.

Found only in one place but should hold everywhere: the office-hours-and-number ban (only Camellia's agents ever went through the shared slot — nothing stopped a new prompt file from skipping it), the stronger no-unit-count wording (only in the voice leasing agent, not in text/email leasing paths), and the “delivered” standard for callback promises (only in the after-hours desk, not in escalation-callback). Each is a rule that already works somewhere and simply never got copied to its neighbors.

The proposal

Migration ships in small PRs, one rule family at a time — matching the standing rule that a risky change is one concern per PR. Each PR proves one of two things against a real Camellia call replay: byte-identical output (the rule moved, nothing changed) or an intended, named diff (the rule was actually different somewhere and this PR is the decision to make it consistent). No PR ships without one or the other.

What it prevents

This is not a hypothetical. Tonight's RCA (western-slope-go-live, root causes 2026-09-17) is the bill for exactly this pattern: office hours ended up in three places (the org-level setting, the knowledge-base text, and a third set hand-typed as constants inside the Western Slope prototype prompt) with no code path comparing them; the company-live email hold was patched five times in eight days (#8977, #8999, #9148, #9174, #9199), each fix touching one sender and leaving the others, because the hold logic wasn't one place to fix; and the human-transfer line already lives in one shared constant consumed by nine prompts — which is proof the pattern works when it's followed, and proof of the failure mode when a tenth prompt (the WS prototype) is written outside it and dials the client's own front desk instead.

Fede's decision (2026-09-18): option B

Execution starts 2026-09-18 after the Western Slope overnight sweep: first PR is the assembler, then human handoff, in the ranked order above.

21. Testing and deploying ElevenLabs agents (Proposed — pending Fede, 2026-09-18)

Fede's framing: iteration on a voice prompt feels slow. Tonight's numbers back that up — not because the deploy step is slow, but because bugs surface for the first time during PR review instead of before the PR exists. This section maps today's path, cites the file that does (or doesn't do) each job, and ranks fixes by how much they shorten "idea to a call I can hear" and how many of tonight's 26 defects each would have caught.

Cycle time today, measured

A merge itself is fast: merge is the production deploy in this repo, and team notes put the Vercel/CI promote step at roughly 13 minutes (not independently re-verified this pass — reported figure). The EL sync piggybacks on that same CI job (scripts/sync-specialist-agent.ts, gated by scripts/lib/elevenlabs-deploy-lane.ts so it can only run inside CI on merge — confirmed by research this session). The slow part is everything before merge. Tonight's own voice PRs, pulled from GitHub just now:

The pattern: fixes that were right the first time merge in under 20 minutes; fixes that needed the bot (and Fede) to keep finding new problems by reading a diff run 10–13 rounds and hours. None of those four PRs' bodies cite a call anyone actually heard — the review rounds are standing in for a live test that never happened before the PR was opened.

Q1 & Q2 — how a change reaches, and is checked against, a live agent today

Prompts live as TypeScript in agents/clara/lib/voice-agents/*.ts (triage, leasing, maintenance, renewal, lease-and-billing, turnover, many-homes, unknown-caller). One file sits outside that shared set: agents/clara/lib/voice-agents/prototypes/western-slope-portfolio-triage.ts, provisioned by its own script (scripts/provision-western-slope-proto.ts) — this is the file the RCA traces the hardcoded office hours and phone number to. scripts/sync-specialist-agent.ts and the WS provisioning script are the only two writers of live EL agent config, and both are hard-blocked from running outside the on-merge CI job (scripts/check-elevenlabs-deploy-lane.ts, plus a local pre-tool-use hook, scripts/elevenlabs-guard.sh, that blocks a hand-run PATCH). There is no staging EL agent that mirrors a customer's real shape and no diff-before-push review step — the CI job read-modify-writes the live agent directly on merge. Rollback exists as a snapshot-restore (scripts/elevenlabs-snapshot.sh --restore), not a one-command "go back one version."

Before merge: the byte-identity check (test:harness:portfolio:byte-identity:check → scripts/portfolio-harness/byte-identity/camellia-replay-byte-identical.ts) only proves a specific known-broken portfolio behavior hasn't silently changed — it is not a general prompt-content guard. The "prompt change needs an eval diff" CI check (require-eval-diff.yml) is satisfied by a text eval even for a voice prompt change, and has an escape-hatch comment. src/__tests__/voice-agents-context-wiring.drift.test.ts is the real fence for the emitted-vs-consumed dynamic-variable gap and does include the WS prototype — but it is a structural, string-level check ("is the var referenced"), not a check that the var's runtime value is non-empty, which is exactly what crashed EL on 2026-09-16. After merge: src/__tests__/el-config-drift-live.drift.test.ts does fetch the live EL agent and diff it against the repo — but only tool schemas, only nightly, never as a merge gate, and it says nothing about prompt text or dynamic-variable values. voice-nightly.yml phones a simulated Clara nightly but is text-only, all tools mocked, and its fixtures are pinned to the Willows test property — Western Slope and Camellia never run through it. Real-call testing (the robocall skill) works and is exactly the right tool, but nothing wires it into a required gate; it only runs when someone remembers to run it.

RCA root causes → what would have caught them

Ranked options

Ranked by how much of the review-round grind above it removes, per unit of build effort — the "fast lane" first, because it is the one change that turns tonight's 10–13-round PRs into something closer to the 8-minute one.

Three options for Fede

The fast lane merged 2026-09-18 (#9285). A proven run took 3 minutes 22 seconds end to end — clone the production agent, stand up a disposable copy, place a real scripted call, grade it with the Fable judge, restore the number, and delete the copy — against a median of 51 minutes open-to-merge plus roughly 15 minutes to deploy before it (1 to 2.5 hours to hear a change land). Run it with npm run voice:fastlane or the /fastlane skill; --reap clears any throwaway agents left behind by an interrupted run. Options A/B/C for the remaining items stay pending.

Scope check: this is sized for Western Slope and Camellia specifically, using tooling that mostly already exists (push-to-staging, robocall, the context-wiring drift test, the nightly config-drift test) — not a new platform.

22. Guest-card updates — the write-intent audit, and closing the gap (Proposed — pending review)

Fede, 2026-09-18: "have we also wired in updates to guest cards? if not let's do a design first for that." Section 15 designed creating a card from a call and named four intents (15.6). This section audits which of those actually deliver today — code read, no test calls, no writes anywhere — and designs the rest. Short version: only the first call's create is wired end to end. Everything else is either queued and stuck, or never queued at all.

22.1 What's wired today, by event

Read-only audit: no writes anywhere, no test calls at Western Slope. Every line above is a file read against origin/main, not a claim from memory.

22.2 Design principles (unchanged from section 15)

PMS stays the system of record, Clara the system of work. One write-intent outbox for every PMS write — no second door. Idempotent per event. Never a status change for a cancelled tour. "No longer interested" is the only status write (mark_inactive). Notes are short, one per event, this call's own summary only — never a rolled-up transcript. Nothing here needs a human click. The existing per-property switch, pms.guestCards.writeFromCalls, gates all of it — no new switch. All channels (voice, text, email) feed the same intents.

22.3 Proposed: event → intent → AppFolio effect

AppFolio's own write surface is thin — section 15.7a's live recon found exactly four routes: create, note, assign, mark-inactive. There is no field-patch route and no showing/tour-date route. That fact drives the design: everything that isn't a brand-new card or a "no longer interested" status becomes a short note, using the one route AppFolio actually gives us.

flowchart LR
    V["Voice call ends"] --> O["Write-intent outbox\n(one per PMS write)"]
    T["Text conversation"] --> O
    E["Email conversation"] --> O
    O -->|create_card| C["POST /guest_cards"]
    O -->|append_note| N["POST /notes\n(booked, rescheduled, fact learned, repeat call)"]
    O -->|cancel_tour| N
    O -->|mark_inactive| S["POST /guest_cards/<id>\ninactive_status_reason"]

22.4 Decisions for Fede

Three choices, each with a recommendation. Reply with the numbers and A/B.

1. Contact facts learned after a card already exists (a corrected email, a later move-in date) — AppFolio has no field-patch route, only notes.
   • A. A short note per changed fact ("Move-in date now 11/1"), never touching the card's actual fields.
   • B. Hold this event type until a field-patch capability is built and proven live, so the card's fields stay authoritative rather than scattered across notes.
   Recommended: A — matches the note-verbosity ruling already made, and ships with zero new AppFolio capability.
2. Should email and text conversations feed the same outbox as voice calls?
   • A. Yes — one small PR routes the existing email/text post-processing paths through enqueueGuestCardIntentFromCall, so every channel produces the same four intents.
   • B. Voice only for now; email/text guest-card writes wait for a separate audit of those paths first.
   Recommended: A — the outbox is already channel-agnostic by shape; the gap is purely that only one caller wires into it.
3. Build order for the four broken paths above.
   • A. Ship the append_note drain pass first (it unblocks repeat-call notes, tour booked/rescheduled, and fact updates all at once, since they're all the same intent), then mark_inactive for "not interested," then the channel unification.
   • B. Ship mark_inactive first, since a caller explicitly saying "not interested" is the highest-stakes miss.
   Recommended: A — one PR (the drain's note pass) closes five of the six broken rows in the audit table above; mark_inactive is one further PR once that pass exists.

Proves: read-only audit against origin/main; no code changed, no PMS written, no test call placed anywhere, including Western Slope.

23. Voice verbosity audit — 2026-09-18 (Proposed — pending review)

Fede, 2026-09-18: “audit for more unnecessary repetitions and verbosity in voice prompts” and “it just seems like overall it's a lot of talking and not enough listening at the beginning.” This is a read-only audit of every voice prompt on origin/main measured against the four real Western Slope calls that happened today. No code changed, no call placed, nothing written to production.

23.1 What the real calls measure

Four voice calls exist for Western Slope in production, all on 2026-09-18. There are none on 09-16 or 09-17 — those tests ran on the Fairhaven test company, so today's four are the whole real-line record. Caller numbers are shown by their last four digits only.

The headline number: on both leasing calls Clara spoke roughly six words for every one the caller spoke, and neither caller heard a price, a size or an address until after the 40-second mark. Both callers then left — one asked for a human, one declined. That is the shape Fede described.

Separate bug found while reading the records, not a prompt problem: the transcript writer (voice.call-ended-transcript) is storing some Clara lines cut off mid-sentence at a fixed length — e.g. call …4630 turn 7 is stored as the 68-character string “Great choice! When are you hoping to move in — and is that firm, …” and no other attribute on the item holds the rest. Anyone reading call records to judge quality is reading truncated text. Worth its own issue.

23.2 The ranked defects

Ranked by how much each one costs the opening of a leasing call. Line numbers are against origin/main at 69dcf93. Two files carry the same portfolio text: src/lib/domain/leasing/portfolio-intake-rules.ts is the source, and agents/clara/lib/voice-agents/leasing-many-homes.ts carries its rendered output 28 lines lower; citations give the source file.

Greeting

The rule that a language switch replays the whole greeting (triage.ts:197) is Fede's own from 2026-09-14 and stays. Fixing defect 1 simply makes it fire far less often.

First exchange

Pitch

The already-decided intent-first change on fede/leasing-intent-before-qualifying fixes the rest of this turn for a caller who named a home (“ONE SHORT LINE MEANS ONE SHORT LINE”). Defect 4 is the piece it does not reach, because the concession rule lives in the shared leasing prompt.

Qualifying

Confirmation and close

23.3 Listen more — where the prompt tells Clara to talk over the caller

Four places where an instruction makes Clara volunteer something, or ask a second thing, before the caller has answered the first.

• Two questions in one breath are explicitly allowed. portfolio-intake-rules.ts:402–403: “You MAY put two asks in one breath, the way the sections above already do.” The same stack says the opposite twice — western-slope-portfolio-triage.ts:730 (“One question at a time — never stack two questions”) and portfolio-intake-rules.ts:422–425 (the name ask is never welded to the move-in ask). Call …5047 turn 11 asked “Want to come see it? And who am I speaking with?” and got neither answer. Delete the permission.
• Nothing says to stop talking after a question. There is no rule anywhere that a turn ending in a question ends there. Add one line to VOICE STYLE: “End the turn on the question. Never add a sentence after it.” One line, every agent, and it is the cheapest change on this page.
• The special is volunteered to a caller who has said nothing about price — defect 4 above.
• The greeting asks before the caller can speak. The fixed first line ends on a three-way choice, so the caller's first words are always constrained to it. Defects 1 and 3.

23.4 The five to ship first

Each is its own small PR, dark, with a fast-lane call as the proof rather than a unit test. Defects 4, 5, 9 and 10 follow as separate PRs; the named-home overload is already handled by fede/leasing-intent-before-qualifying and is not re-proposed here.

23.5 The first thirty seconds, before and after

Today: the caller hears a 20-word greeting with a Spanish instruction buried in it, answers “Leasing”, and is asked a second closed question about whether they saw a specific home. They say “a specific home”, and are asked which one. They name it — and instead of hearing anything about it, they are asked when they are moving and whether that is firm. At second thirty Clara has spoken about 59 words, the caller has spoken 9, and nothing has been said about any home. The price arrives somewhere past forty seconds, stacked into one 52-word turn with the address, bedrooms, bathrooms, garage, a move-in special and two questions — at which point one of today's callers asked what she had just been told, and the other asked for a human.

After: the caller hears the question first and the Spanish line last, answers “Leasing”, and Clara asks one open thing: “Sure — which home, or what are you looking for?” They name Pomona Park. Clara's next turn is the home, its size and its rent in one short line, then one question: come see it, or shall I answer questions first? By second twenty-five the caller has a price, a size and a choice, and Clara has stopped talking. The move-in date, the name and the special all still get said — on the turns where the caller has already shown they want the home.

Proves: read-only. Prompts read at origin/main commit 69dcf93; the four Western Slope calls read from the production conversation table by query only. No prompt edited, no call placed, no production write, nothing touched on the Western Slope org.

24. Home identity through a scattered-homes booking — root cause + harness (2026-09-18)

Real Western Slope call today, conv_voice_21abd768…: the caller named “Ember Estates” (the marketing name on the listing for 367 Ember Lane). Clara's schedule_tour call carried home_ref: "Ember Estates" and an empty unit_number; the tool refused with home_not_resolved before ever looking at home_ref; Clara repeated the “let me get that booked for you!” line and retried with the literal street address, which booked — but onto the org's front-door shell property, as free text. The guest-card outbox found no PMS-mapped property along tour → inquiry → conversation and enqueued nothing. Calendar and SMS worked because they only need text, never identity. Issue #9532.

24.1 One root cause, all six symptoms

Clara's home-matching for an org-headed scattered line runs entirely off the org's public-listing rows (OrgListing, read by org-offerable-homes.ts / resolveOrgHomeForLine), a feed built only to render a home's card and deliberately given no stable id (“OrgHome.id is always '' — no Unit row backs a company home”, org-home-booking.ts) — and that feed has never been joined to the org's real, PMS-mapped Property roster, the 69 AppFolio-synced rows (of 70 on the roster; pmsSource=appfolio, af.propertyId, account westernslopepm — e.g. appfolio-408 = 367 Ember Lane) that the guest-card outbox already knows how to write to. Every symptom traces to that one missing join:

• Empty unit_number. The tool schema gives the model two free-text fields for a home — home_ref (a name) and unit_number (the literal address line from the AVAILABLE HOMES block, tools-leasing.ts:566) — and nothing in the data the model was handed carries an id it could put in either field with confidence. Told a name that isn't the literal address string, the model reaches for the field that seems to fit and leaves the other blank.
• The guard fires before matching. tools-leasing.ts (~line 4936) refuses with home_not_resolved the instant unit_number is empty on a scattered line — a check written when the literal address in unit_number was the ONLY key a scattered line had, so it never had a reason to try home_ref first.
• The doubled filler line. The refusal's own retry instruction (“call the same booking tool again right now with that home's full line… as unit_number”) is a second attempt Clara narrates the same way she narrated the first, with nothing suppressing the repeat (separate issue #9533, another worker's lane).
• Free-text booking on the shell. Even the org-wide match path that DOES resolve a home (orgHome.home found) stamps bookedUnit = { id: '', number: orgHome.home.number } by explicit design (“the address is the home's name; unitId stays empty”), and property itself never becomes that home's own mapped Property row — it stays the org's front-door shell (western-slope-front-door) for the whole call, because nothing in this path ever looks the mapped roster up. The Tour is written with a real address string and no property identity behind it.
• No guest card. The outbox (postcall-guest-card-outbox.ts) is doing exactly its job: it walks tour.propertyId → prospect.propertyId → conversation.propertyId and asks each for a PMS writer. Every candidate is the shell, which has none, so it logs no-pms-property and never enqueues — correctly, given what it was handed.
• Calendar and SMS worked. Both read the tour's plain-text address/time, never an identity, so they had everything they needed.

Separate, NOT part of this fix: the org-level guest-card switch (isGuestCardWriteFromCallsEnabled) is ON for this org, but the PROPERTY-level switch each of those 69 mapped rows also needs (PropertyLeasingSettings.guestCardWriteFromCalls, registry key pms.guestCards.writeFromCalls, default OFF, read by the direct-write path writeGuestCardFromCall) is OFF on all 69. Even a perfectly-identified tour writes no card at Western Slope until that switch is turned on, property by property — filed separately as #9538 so it never gets folded into the identity fix or mistaken for the same bug.

24.2 Rejected fixes, and what would still break

24.3 Decided (Fede, 2026-09-18) and shipped as PR A: a stable key per home, name matched server-side

Fede's call, once the design above was in front of him: every home in the AVAILABLE HOMES block gets a stable key — not a re-parse of speech, not a second field for the model to guess between. Rejected explicitly, same table as 24.2: promoting home_ref into unit_number, prompt wording about which field to use, any per-property switch. Shipped in the ONE canonical resolver, no second matcher:

• OrgHome (org-home-booking.ts) gains key — the listing's OWN id (OrgListing.externalId, e.g. the AppFolio listing uuid for 367 Ember Lane's current listing) — and aliasText, the listing's title + full description concatenated, threaded from org-offerable-homes.ts.
• listing-resolution.ts (the one matcher every line already shares) gains a NAME tier, tried ONLY after both address tests find nothing, and ONLY for a 2+ word phrase: a caller's exact words are looked up against aliasText — never written into a booking field, never treated as canonical. A row with no aliasText (every building's Unit[], live today) can never match here — byte-identical to before this existed.
• Ambiguity is never silently resolved. Confirmed against Western Slope's real feed: “Ember Estates” is prose repeated across THREE real homes' descriptions (367, 372 Ember Lane, 374 Ember Ln), not a name unique to one. The NAME tier returns all three as candidates and refuses — the exact same home_not_resolved-with-candidates shape the address tier already used for a partial street match, never a guess.

What this PR deliberately does NOT yet do — and 24.1's deeper root cause is still open: bookedUnit for a company home still stamps id: '', so Tour.unitId/ProspectInquiry.targetUnitId still carry no structured identity, the booking still lands on the org's front-door shell property, and the guest-card outbox still has nothing PMS-mapped to write to. Tried stamping the new key there directly; it silently broke resolveListingCardForReply (#8590), the only reader of targetHomeAddress for a company home's next-call/email context, because refreshInquiryHomeForTour treats any non-empty unitId as authoritative and stops writing the address. That is exactly the kind of unaudited, one-reader-breaks-another hack Fede's “no hacks” ruled out — so it is split out, not shipped half-done behind a flag.

24.4 PR B — open, not yet built: structured identity all the way to the booking

Needs its OWN field on Tour/ProspectInquiry for a company home's identity (never a repurposed unitId/targetUnitId), a full audit of every existing reader of those fields for the new shape, an update to resolveListingCardForReply, and — to actually close 24.1's guest-card gap — the join from OrgListing to the org's PMS-mapped Property roster this section originally proposed (addressKey/homeKey, both sides already write it) so property for the rest of a booking becomes the home's own mapped row instead of the shell. This is the acceptance contract written as the one pending scenario (structured-id-persists-to-tour-and-guest-card) in the harness below — red on purpose until PR B lands, at which point it flips to UNBLOCKED and must be promoted to today in that same PR.

24.5 The proof harness (shipped with PR A)

An OFFLINE domain-level harness, scripts/home-identity-harness (npm run test:harness:home-identity), following the same five-outcome contract as identity-harness/household-harness (PASS/FAIL/PENDING/UNBLOCKED/BROKEN). No network, no DynamoDB — every scenario drives the real orgHomeRows/pickOrgHome/homeNotResolvedRefusal exports directly against fixtures shaped on Western Slope's real, read-only-verified listing text. Eight scenarios: address-exact (control), address-ambiguous (two real Redcliff Cir units, no unit #), name-unique (“Orchard Mesa Ridge”), the real “Ember Estates” three-way name ambiguity, a single-generic-word guard, an unnamed-reference clean refusal, a per-building byte-identical control, and the one pending PR-B contract above. All eight green (seven PASS, one honestly PENDING) as of this PR.

Proves: a separate lane (issue #9535) is building a LIVE fastlane voice anchor for this same defect against Fairhaven Residential (TEST) — the four-scenario plan this section originally sketched in 24.4 (informal name / address / ambiguous / no-home-named) lives there now, not duplicated here. This harness is the offline, always-run, CI-gating complement to that live anchor, not a replacement for it. Full run output and the red-before/green-after regression tests (listing-resolution.test.ts, leasing-tools.test.ts) are in the PR body's ## Proof section.

25. Guest-card notes: how the teams write them (2026-09-18)

Goal: make Clara's guest-card note read like a real leasing agent's, not an AI call-summary paragraph. Studied read-only, headless browser, no writes: Situs Group's AppFolio (situsgroup.appfolio.com), sampling guest cards with note/activity history. Western Slope sampling was interrupted mid-session by a browser-automation bug (see 25.4) and is not yet complete — the rules below are drawn from the Situs Group sample plus Fede's own rulings on today's live Western Slope call, and will be extended once Western Slope reading resumes.

25.1 The style rules

25.2 What Clara's composer got wrong before this fix

The composer (resolveNoteText, src/lib/integrations/voice/postcall-guest-card-outbox.ts) was a raw passthrough of ElevenLabs' generic third-person call-summary field — there was no team-style formatting at all. Five real (anonymized) examples pulled read-only from propflow-prod:

• Multi-sentence third-person narrative prose (“[Name] called… is interested in… The team will follow up…”) instead of a short past-tense recap.
• No isolated move-in line — timing buried mid-paragraph when it appeared at all, never distinguished as verbatim-flexible vs. a real date.
• No showing/tour line, no confirmation-sent line, even when a tour or email existed elsewhere on the record.
• Restated information already on the guest card.
• 3–5 sentences long versus the team's 2–3 short clauses.

Proves / fix shipped: PR #9575 (issue #9574) adds composeGuestCardNoteText and wires it into resolveNoteText: date-stamp prefix, source-boilerplate stripped, a move-in line that preserves the caller's own flexible wording verbatim or falls back to a parsed date only when no verbatim wording exists, and no duplicate move-in mention. Fixture test with 8 before/after cases drawn from these anonymized examples, all green. Dark change — reshapes only what an already double-gated, default-off write path says, no new switch. Deliberately not yet in scope: the upstream ElevenLabs summary prompt itself, and a threaded showing/tour line at this call site (tracked as follow-up in #9574).

25.3 Anonymization note

Every example on this page is paraphrased or has names/phones/emails/addresses replaced with placeholders ([Prospect], [Street Address], [Property Name]). No real prospect PII from either database appears here.

25.4 Open: Western Slope sampling incomplete

The research subagent hit an unrelated blank-render bug on AppFolio guest-card detail pages and, while debugging it, repeatedly wiped and recreated its browser profile — each recreation forced a fresh login + MFA instead of reusing a session, burning 3 verification codes on the shared situsgroup.appfolio.com credential in a 6-minute window (20:40:41–20:42:48Z) and flagging as a possible lockout risk. It was halted immediately; zero logins were attempted on westernslopepm.appfolio.com, and no writes were made anywhere. The crawl script has since been fixed (single persistent session, longer render wait, no profile churn) and is parked pending clearance to log back in. This section will be extended with Western Slope's own examples and any style differences once that resumes. Fede, 2026-09-18: no fresh AppFolio login tonight (lockout risk). The Western Slope sample is pending and will be taken through the existing production browser session, never a new direct login.

26. AppFolio guest cards: what a card can do, what we do, and the harness (2026-09-18)

Fede, 2026-09-18: “i think we need a separate test harness and build for all of this, we have lots of gaps in appfolio guest cards” — done at the Willows. This section is the checklist of everything an AppFolio guest card supports (from AppFolio's own help articles), the gap table against what Clara does today, and the harness that closes the loop by reading every card back.

26.1 The one thing to understand first

AppFolio's guest card is not a flat record. A card holds Inquiries, which are property-level, and each inquiry holds Interests, which are unit-level (“Guest Card Inquiries and Interests”). A card only appears in a property's guest-card list if it carries an inquiry for that property, and the Latest Interest column is that inquiry's date.

That is the whole story of the 18 September repeat caller. Her card had existed since July. She called about one home; her card still listed only the August inquiry for a DIFFERENT home, so she did not appear under the home she called about at all, and Most Recent Activity only moved when Fede changed her status by hand. Appending a note could never have fixed this — the write has to add an inquiry for the home she actually asked about. Fede: “besides notes and marking it active we need to figure out how to make it appear in the list here with latest activity.”

Second thing worth knowing before anything is tested: AppFolio cannot delete a guest card, ever (“FAQs — Guest Cards”). Marking it Inactive with a reason is the only cleanup that exists. That shapes both the harness and the cleanup rule.

26.2 The checklist and the gaps

Sixteen capabilities. Clara does one of them.

26.3 The harness

npm run test:harness:appfolio-guest-cards, at scripts/appfolio-guest-card-harness/. One scenario per capability above.

• The Willows and nowhere else. Live runs are hard-guarded to the JP&Co database, property 45. Western Slope's and Situs Group's databases are live customer data, and a test card written there can never be removed.
• Every assertion reads the card back out of AppFolio through the same browser-agent service that wrote it. A write that answers HTTP 200 is not proof: AppFolio re-renders the new-card form with 200 and creates nothing when the interest is missing.
• Dark by default. No AppFolio call at all unless a person passes --live. --list prints the checklist and the gaps.
• No scheduled job. On demand and on merge, never a cron.
• A cleanup ledger, not a cleanup claim. A live run prints every record it left in AppFolio with its link. Because cards cannot be deleted, real cleanup waits on the mark-inactive route — so the mark-lost scenario is the unblocker for routine live runs, not a nice-to-have.

Two more capabilities added 2026-09-18 evening (issues #9598, #9599), taking the list to 16: a caller who asks for a person still gets a card whose note records the callback request and number; and a first-name-only caller gets a card with a placeholder last name. Fede decided that second one the same afternoon: the card gets written with the placeholder surname Unknown and the note “Caller gave first name only.” — a lead we can still reach beats a lead lost silently. It overrides the morning behavior, where Clara refused to create a card at all. The cost is recorded rather than glossed: AppFolio can never delete a guest card, so every placeholder surname is permanent in the client's own prospect list and reports, which is why the note has to say plainly that the name is incomplete, so a leasing agent can fix it on the first reply. The old refusal scenario goes red the day the placeholder writer lands — that is the signal to delete it, not a regression to chase.

The hole, and what is closing it. There is no authenticated route today that reads a card's status, interests, Latest Interest, Most Recent Activity, source or assigned user. The only authenticated guest-card read the service has is the message-thread route, which proves a card exists. The verifier's field-level read therefore throws and names the missing route rather than returning something a scenario could pass on. Ten of the remaining scenarios are blocked on that one route — the highest-leverage thing to build for this test environment, and it is now being built (POST /api/guest-card-read, returning status, interests, Latest Interest, Most Recent Activity, source and assigned user). The verifier stops throwing the day its client lands. The one after it is mark-inactive: until that exists, every live run leaves permanent litter the harness can only ledger, never clean.

26.4 The chain

Shipped: PR #9585 (issue #9584) — the capability spec, the read-back verifier, and scenarios 1 and 2. Dark: scripts/ only, no switch, no channel behavior changed. In flight elsewhere and deliberately not duplicated here: #9581 and appfolio-browser-agent #383 (note + reactivate), #9579 (tour carries the real home), #9511 (full name). Next: one issue per remaining scenario on #9584, and the browser-agent card-read route that unblocks most of them.

The read-back hole is closed, two ways (2026-09-18 evening). The missing route is built and merged: appfolio-browser-agent #385 adds POST /api/guest-card/read, returning status, inquiries/interests, Latest Interest, Most Recent Activity, lead source and assigned user — read-only, never logs in. Separately, Fede approved a design change the same evening: the AppFolio Plus API is now the primary way to read a card back; the robot route above is the fallback for a company without a Plus API credential. JP&Co / the Willows already has a live Plus credential, confirmed live. PR #9646 adds the Plus API client (readGuestCardViaAppfolioApi), proven against a real Willows test card; PR #9648 adds the matching robot-route client (readGuestCardL4) behind the same interface. All three are armed to merge.

26.5 Clara now sees what the renter wrote (19 Sep 2026)

• Before: no synced card carried the renter's message, so Clara's first email could not answer it.
• Now: the robot reads AppFolio's inquiry panel and the message lands on the prospect record. Proven on a real Western Slope card: “Was wondering if you'd consider a 6 month lease with option to extend… We need parking for a few vehicles and a 7x16 cargo trailer. We have one small well behaved cat.”
• Applies to cards created after a company is switched on. Older cards are not backfilled until step 4 in section 29.0 lands.
• Known nit: the inquiry source shows raw link HTML instead of “Rent.com”; fix in flight.
• PRs: appfolio-browser-agent #407, propflowai #9939.

27. Guest card management — architecture and design (Approved 2026-09-18)

Fede, 2026-09-18: “can we come up with an architecture and design doc for guest card management? I think that's a big beefy initiative, we gotta think through all the use cases and permutations.” This section is the parent for everything guest-card on this page. It sets the goal and the principles, states AppFolio's real data model, walks every permutation we can think of, catalogues every write, draws the machine, names the failure modes, and ends with the calls that are Fede's. The three sections that already exist stay where they are and are linked, not repeated: 25, how a note should read; 26, the capability checklist and the Willows harness; 15.11 and 22.4, the decisions already put to Fede.

Approved 2026-09-18 (Fede). The design and all six decisions below are settled; the “state” columns still say what is built and what is not. No code was changed and no PMS was written to produce this section.

27.1 Goal and principles

Goal. Every conversation a prospect has with Clara — on any channel, at any point in their life as a lead — lands on the right AppFolio guest card, in the client's own prospect list, looking like their own leasing agent wrote it. The client never has to open PropFlow to know what happened.

27.2 What an AppFolio guest card actually is

Western Slope's AppFolio serves the new CRM prospects page (/crm/leasing/prospects/<uuid>); the robot's selectors were built against the classic guest-card page and must handle both.

The single most consequential fact: a card is not flat. It holds inquiries, which are property-level, and each inquiry holds interests, which are unit-level. A card shows up in a property's guest-card list only if it carries an inquiry for that property. Everything else — who it's assigned to, what shows in Latest Interest, whether the lead looks alive — hangs off the inquiry, not the card.

27.3 The permutations — 36 situations, end to end

Five tables, one per dimension: how they reached us, who they are, what card already exists, which home, what happened on the call, and when. Each row says what Clara does, what is written to AppFolio, what the leasing team receives, what we keep, and what state it is in.

covered works on origin/main today, behind the default-off setting  ·  in flight an open PR does it  ·  gap nothing does it.

27.3a Channel

27.3b Who the caller is

27.3c What card state they are in

27.3d Which home

27.3e What happened during the interaction

Every row above also carries one plain “how the call ended” line in the note (phase 1 of the Lost decision) — a hang-up, a dropped call and a polite goodbye read differently to a leasing team, and none of them closes a card.

27.3f When

Where that leaves us: 36 rows — 8 covered, 9 in flight, 18 gaps, 1 deliberately out of scope. Nearly every gap is downstream of one missing capability: there is no authenticated route that reads a card's status, interests, source or assigned agent back out of AppFolio. That single route unblocks dedup, reactivation verification, and ten of the harness's twelve blocked scenarios.

27.4 The write catalogue

Twelve writes. The mechanism column is live recon (15.7a), not documentation guesswork. One finding settles the API-vs-robot question before it is asked: AppFolio's Data API v1 is Plus-tier and read-only — GET reporting requests only, with a guest_cards endpoint among them. No write, update or delete operation on a guest card is documented anywhere in AppFolio's own knowledge base. So the robot stays the writer; what the Plus keys buy us is the read we are missing (D1).

Permanence and cleanup. No write in this table can be undone by deletion. The only cleanup that exists is marking a card Inactive with a reason, which is why the mark-lost write is the unblocker for routine live runs at Willows rather than a nice-to-have, and why placeholder data is a permanent decision.

27.5 Architecture

One path, whatever the channel. An event produces an intent; the intent goes in the outbox; a drain takes it to the PMS adapter; the adapter writes through whichever back end that PMS has; a verifier reads the record back; the team notice goes out either way, including when the write parked.

flowchart TB
    subgraph SRC["Event sources"]
      V["Voice call ends"]
      T["Text conversation"]
      E["Email / listing inquiry"]
      TR["Tour booked · moved · cancelled · shown"]
      ST["Staff reply to Clara"]
    end
    SRC --> ID["Identity + home resolution
person · org · property · unit"]
    ID --> P["Intent producer
create · note · reactivate · interest
showing · assign · mark_inactive"]
    P --> OB["Write-intent outbox
pending · gated · in_flight · done · parked
idempotency key per event"]
    OB -->|"setting off"| G["gated — no AppFolio call"]
    OB --> D["Drain (event-triggered,
bounded retries, no cron)"]
    D --> A["PMS adapter — one interface"]
    A --> API["AppFolio API (Plus plan)"]
    A --> BOT["Browser robot
login budget 3/h, 8/24h"]
    A --> FUT["Yardi · RealPage — later"]
    API --> RB["Read-back verifier"]
    BOT --> RB
    RB -->|"verified"| DONE["Card link stamped on the person"]
    RB -->|"failed"| PARK["Parked with a reason"]
    DONE --> N["Team notice"]
    PARK --> N

Where this sits in Gera's portfolio model. The org is the wall: identity resolution is company-wide, and a card is never written for a home outside the org that owns the line. The PMS credential holder is an org-level attachment — one AppFolio database per org — which is what makes the adapter's account routing an org concern rather than a property one. The property is the finer attachment: the guest-card write setting lives on the company with a per-property override, nearest wins, the same shape Fede decided for the reply mailbox. One conflict to name: a scattered-homes front door is an org-level row with no AppFolio property behind it, so the resolver can hand the writer a home that has no p_ or u_ id at all. The design parks rather than guessing; whether those homes should become real PMS-backed properties is Gera's question (27.10).

27.6 Failure modes

27.7 Testing

Never at a real client. No test guest card is written into westernslopepm or situsgroup. Cards cannot be deleted, so a test card is permanent pollution of the client's prospect list. Proof happens at the Willows and at Fairhaven; the first card at a real client comes from a real caller, after Fede turns the setting on.

27.8 Rollout — the PR chain

One concern each, roughly 300 lines or less, each dark and mergeable on its own. The setting exists already and no new one is added. The order below is the decided one: the read first, then dedup, then the other channels.

Dark, then a test property, then Fede. Every PR ships to production with the setting off, is proven at the Willows or Fairhaven, and turning it on at a real property is Fede's separate call on a separate day.

27.9 Decisions — all settled

Fede approved the section and every recommendation on 2026-09-18. Nothing here is open.

1. What the Plus API keys are for. Decided 2026-09-18 (Fede): use the Plus API for the card lookup and read-back, and keep the robot for every write. AppFolio's API is read-only, so it cannot replace the robot as writer. It is cheaper, it does not spend the robot's login budget, and it unblocks dedup immediately. A robot read route is still needed for clients without Plus, and comes after.
2. Cards made outside PropFlow. Decided 2026-09-18 (Fede): look the person up before any create. By phone then email; we write to the card we find, and ambiguity parks and emails the team. A duplicate card can never be deleted or merged — AppFolio auto-merges only cards that arrive through its own online path, and a card the robot creates through the manual form is not one of those.
3. What “lost” means. Decided 2026-09-18 (Fede), in two phases.
   • Phase 1 — Clara never marks a card Lost. Every call ends with one plain line in the note saying how it ended, and the team decides what that means. For example: “Asked for a person, call ended before a number was taken.”
   • Phase 2 — only after a labelled call-disposition set shows the signal is reliable (fixtures PR in progress). Then Clara marks Lost only when the caller explicitly says they are not interested or have already signed somewhere else, quoting their own words as the reason. Hang-ups and dropped calls are never Lost, in either phase.
   Silence never closes a card, at any age. A wrongly closed card is invisible to the team, and the client's own staff already manage their inactive list.
4. Assigned agent. Decided 2026-09-18 (Fede): build the logic now, leave it off. Auto-assignment to Clara turns on only when Fede declares a company fully live for inquiries. Until he does, the card is recorded and left alone. Never a per-card human hand-off.
5. First-name-only callers — DECIDED 2026-09-18 (Fede): create the card. A first name is enough; we never lose the lead over a missing surname. A placeholder surname is used only if AppFolio's own form refuses an empty last name, which is being verified now.
   Note: whatever surname we write is permanent — cards can never be deleted or merged by hand — so the placeholder, if the form forces one, should be the plainest possible marker and the note should say the caller gave one name.
6. Email- and text-originated conversations. Decided 2026-09-18 (Fede): every channel goes through the same outbox, but only the phone line may create a card. Fede, verbatim: “we should only create guest cards for phone line. for inquiries and emails there should already be a guest card created so we write notes back to it.”
   • Phone line — creates the card when there is none, and appends notes after that.
   • Email and AppFolio-originated inquiries — notes only, never a create. Those leads already have a card by definition. If we cannot find the linked card, the intent parks and the team is emailed; we never invent a second card.
   • Texts to the leasing line — treated as the phone line, so a text-only lead can create a card. assumed, confirm — this is our reading, not something Fede said.
7. First touch of a new syndicated guest card. Decided 2026-09-18 (Fede evening): Clara assigns the card to herself first, then replies and writes the note. If the assignment fails or a person already holds the card, no reply is sent.
8. Escalation to a human. Decided 2026-09-18 (Fede evening): re-assigns the card to the primary leasing officer (Kat for Western Slope today) and Clara stops replying. Clara works a card only while it is assigned to her. Settings: pms.guestCards.assignToUser, pms.guestCards.primaryLeasingOfficer.
9. Sending the rental application. Decided 2026-09-18 (Fede evening), design pending: AppFolio's own send from the card, driven by the robot, targeting the property (unit optional), text first and email as backup, gated by a per-property application-link setting (fixed URL vs PMS-generated link), never by the call-write switch. Built and proven 2026-09-19, see §27.11.
10. Guest cards from phone calls only. Decided 2026-09-18 (Fede evening): guest cards are created from phone calls only; email and text conversations write notes to the card that already exists.
11. Read-back before success. Decided 2026-09-18 (Fede evening): a robot write may report success only after it reads the change back from the card (incident 2026-09-18: a note write to a Western Slope card returned “added” with nothing written).

27.9a First touch and escalation (decided 2026-09-18)

Fede, verbatim: “new guest card comes in, clara assigns herself and replies / takes notes” and “if something is escalated to a human, we re-assign the card to the primary leasing officer (just kat for now) and we should stop replying.”

The rule in one sentence: Clara works a guest card only while the card is assigned to her.

Order on a new card:

1. Read the card.
2. Check the fixed conditions all pass: the card was created by the syndication feed; its oldest row is within 24 hours of when we first saw it; it is not part of a cold-start backfill; it was first seen after the lead source was turned on for that company; and it is assigned to nobody, or already assigned to Clara.
3. Clara assigns herself. This is the claim.
4. She replies.
5. She writes her note.

If the assignment write fails, or someone else is already assigned, Clara does not reply.

On escalation: Clara reassigns the card to the company's primary leasing officer, writes the handoff note, and then stops every reply and follow-up on that card, including sending the application.

Settings: two per company, each one naming an AppFolio user — Clara's user (already exists) and the primary leasing officer (new setting; for Western Slope this is Kat Barker). No other switch controls this.

An “any staff row already on the card blocks Clara” check was considered and set aside on 2026-09-18, pending Fede. Assignment alone carries the rule for now.

27.10 Questions for Gera

Not sent — Fede reviews first.

1. A scattered-homes front door is an org-level row with no AppFolio property behind it. Should those homes become real PMS-backed properties, or does the resolver get to return “no PMS home” as a first-class answer the writer parks on?
2. The PMS credential holder is attached to the org, but the write setting lives company-then-property. Is nearest-wins the right shape here too, or should a PMS write setting only ever be org-level?
3. Identity is company-wide, but an AppFolio card belongs to one database. If a person exists in two orgs we manage, is that two unrelated people to the writer, by the wall?

27.11 Sending the application (Built — decisions 1 to 6 decided 2026-09-18; proven at the Willows 2026-09-19)

State 2026-09-19. Built and proven end to end on the real path: property setting applicationLinkMode (#9779), the outbox intent and its gate (#9780), the drain, adapter and read-back verifier (#9784), the callers (#9783), and the robot route (browser-agent #395, #404, #405). Proof: Willows card 112, drained by the production 15-minute sweep at 15:30Z; AppFolio sent the text and the email itself, and the Actions Log shows the four send rows by Clara with the generated link appfol.io/6G5kK5MX. Two facts the proof forced into the design: AppFolio's send form requires an email on the card even for a text (a card with a phone only parks as no-contact-on-card), and the form's “Unit or Campaign” field never accepts a property-level interest, so the robot posts the tour's unit when one was named and otherwise the first vacant unit at the property; the target stays the property and the card's own interest is not changed. Still open: the drain runs on the call-ended trigger plus the 15-minute sweep, not Temporal (#9778); staff notice on a parked send (#9856).

Fede, 2026-09-18: send the application by triggering AppFolio's own “send rental application” action on the card through the robot — never by pasting a URL ourselves. This replaces row 27.3e's “application started” write, today marked out of scope, and the prospect-facing app-link text in section 7, which sends our own generated link at tour start +60. Western Slope's own pattern: Kat sends 126 SMS and 151 email applications by hand, 90% of them, always per unit, mostly right after a showing — each one is AppFolio itself handing the prospect an appfol.io/<token> link. Lower priority than the rest of this design; needed for tomorrow's 10 am Western Slope tour.

What is written. A send_application intent, key gc:send_application:<inquiryId>:<unitOrPropertyId>, on the same outbox as every other guest-card write (27.4–27.5). The robot drives the card's own send-application form, then reads back the Actions Log “Rental Application sent” entry and the generated link as proof — the same read-back-or-it-didn't-happen rule as every other write. The note on the card is AppFolio's own; Clara adds nothing extra. Idempotent, once per inquiry+unit — a re-send needs an explicit agent ask, never an automatic retry of a send that already landed. On the reply side, onOutcome({ outcome: 'application_link_sent', … }) is where this stamps the tour/inquiry record and stands down the +1/+3/+7 chase cadence from section 7.

Settings impact. This is not gated by the write-from-calls switches (company pms.guestCards.writeFromCalls, property guestCardWriteFromCalls); those keep gating the other card writes in this section. Instead, one per-property setting (decision 6) picks the link source: fixed URL, or generated per prospect through a PMS write connection. Properties already on a fixed URL need no change. The post-tour delay stays the single existing setting, default one hour, with no separate delay setting for this send (decision 5).

Architecture. The post-tour send already exists for the fixed-URL choice: the application-link processor waits the post-tour delay after a confirmed tour, then texts or emails the link. The generated-link choice plugs into that same processor, and into the prospect-request paths (post-call link send; Clara's inline link on text and email), by calling the guest-card outbox intent send_application instead of pasting a URL. Two gaps to close in the same build: the leasing agent's post-tour check-in answer (no-show / not interested) is not yet an input to that processor; and Clara's prompt must not be handed a URL to paste for properties in the generated-link choice. Before the send is queued, it checks that the card is still assigned to Clara.

Rollout: dark, then Willows, then Fede's yes — the same ladder as every other write in this section (27.8).

Failure modes. The card's send-application control changes shape or is not scriptable → park, tell the agent, never guess a workaround. AppFolio's own SMS consent language on the form is AppFolio's, not ours, and is never re-raised as a PropFlow consent question. A duplicate send is blocked by the idempotency key, not by re-checking the card. A prospect with neither email nor phone on the card cannot receive either channel → park with reason and tell the agent, same as any other card with no contact point.

Proves: written from AppFolio's own help articles, live form recon at the Willows (card 104, 2026-09-17), a read of the guest-card write path on origin/main, and Fede's dated rulings of 15–18 September. No code changed, no PMS written, no test call placed.

27.12 Reading staff activity on the card (Proposed — shape decided by Fede 2026-09-18 (staff rows become entries in the prospect's conversation, Clara collaborating with teammates); internal-only handling decided (exclude entirely); build order pending)

The problem. Clara's picture of a prospect is only the card's fields plus her own conversation with them; she never sees the notes, calls, texts, and application sends the leasing team logs on the same card. Diligent clients are working a lead in parallel, and after Clara's first reply she has no way to know it.

Fede, 2026-09-18:

• “i guess i see a new challenge arising. the client here and so will others are really diligent posting notes & communications”
• “and clara starts from scratch anytime and doesnt really read notes right now”
• “how do we incorporate these notes into clara's context? the main use case would be 1) if someone requests a human and they talk separately we can know what they talked about for 2) follow up engagements, re engagements, reminders etc. thats a large build”
• “what if we add notes as part of the conversation” — “that way clara has a natural way to reference it in a channel she already keeps track of”
• “yes clara collaborating with teammates good”
• “we would also need to make sure we dont accidentally leak internal conversations that might not be appropriate to share externally” — “we should mine for examples of those” — “things like i dont think we will approve them or anything unprofessional” — “or potentially illegal”

What exists to build on.

• The robot can already read a card's activity log, with who wrote each row: the property's system, a named staff person, or an automated entry.
• Clara already has a fixed rule for when she is allowed to make first contact on a card, based on that same log.
• Clara's own actions already show up as entries in that same log, so her last touch on a card is visible to the team the same way the team's touches would be visible to her.
• Clara already sends the rental application automatically a while after a tour, which is the first place staff activity would need to change her behavior.

Options

Notes as conversation entries. Option 2's shape: each staff touch becomes a third kind of entry in the timeline, alongside the prospect and Clara — a named teammate, not either of those two. Every place that already reads the conversation (follow-ups, re-engagement, reminders, replies after a human takes over) picks this up for free, with no new plumbing. Before it can run for real, it needs: a cheap way to notice a card has new activity so only changed cards get re-read; a way to import each row exactly once; team touches rendered as observations Clara can act on, never as the prospect's own words or as instructions to follow; Clara never repeating a teammate's note back to the prospect; and option 1's stand-down rule staying in force underneath it, so a note being present is never by itself a reason to act.

Never leak internal notes

Decided 2026-09-18: a note classed internal-only is not written to the conversation at all. No pointer row, no hidden copy. Fede, on the objection that Clara then cannot tell a teammate touched the card: “this is not a real concern.”

This is a requirement, not a nice-to-have. Three kinds of staff writing must never influence or appear in anything Clara says to a prospect: approval or screening opinions (whether someone will likely be approved, remarks about background, credit, or income), anything unprofessional (judgments about a person's appearance, family, pets, or attitude), and anything that could be illegal to act on (remarks touching a protected class, steering, or a person's source of income). The plan is a three-part mechanism: every imported row is sorted, at the point it is read in, by rules plus a Haiku model stage, into internal-only (excluded entirely, never written to the conversation) or safe-to-use (shown, and usable only in Clara's own words, never quoted); Clara is only ever given the safe-to-use rows, with an explicit instruction never to quote or attribute a teammate to a prospect; and every client's real history gets replayed through the rule before it ships, looking for even one reply that leaks or implies an internal row. Situs Group cards are being added to the corpus alongside Western Slope.

Examples mined from the client dumps: pending, to be added below.

Classifier

Built and measured 2026-09-18. The classifier is a pure module with no caller yet: it sorts one activity row into internal-only, safe to use, duplicate of a message, or fragment. Two stages. Deterministic rules go first and are deliberately timid — they may wave a row through only when it is a duplicate, a fragment, or plain tour logistics, and they may block a row on their own only for screening data. Everything else, including all three of the categories that matter, is handed to a Haiku model with the taxonomy and a strict output shape. Any model error, timeout or malformed answer returns internal-only, so a failure hides a note rather than leaking one.

Two things the build changed about the picture above. First, the keyword triage's 29 approval or screening opinions are almost all prospects writing about their own eviction or denial, not staff opinions — genuine staff verdicts, and owner pricing notes, are close to absent in this corpus. Second, the real leak surface is fair housing, and it does not look dangerous: the leasing agent routinely records who would live in the home (“3 kids and himself”, “her, her husband and 3 kids”) in rows that read like ordinary tour notes. That shape was five of the seven misses on the first eval run.

Measured against a 170-row gold set — 150 hand-picked from the scrubbed Western Slope dump, 20 written to be adversarial (prompt injections inside a note, benign traps like “family room” and “denied the pet request”):

The trade in the last two rows is the design, not a regression: withholding a safe note costs Clara one observation, and missing an internal one is a fair-housing complaint, so the eval gates on recall and only reports the false-block rate. One known miss remains — an automated “inquiry assigned to” row is treated as a duplicated message rather than an internal action; it is the single row between 98.4% and 100% and is tracked as a follow-up.

Over the full 10,499-row dump, the rules alone settle a quarter of rows for free (13.3% duplicates, 7.8% fragments, 2.3% tour logistics, 1.3% screening data) and hand the remaining 75.3% to the model. The model prompt does not state the protected classes itself — it renders the same single list Clara's own prompts render, so a class added once reaches the classifier too.

Still dark. Nothing calls it, and the Situs Group cards are added to the gold set in a follow-up. Shipped in #9664 (rules, model stage, gold set and eval; #9666 and #9690 merged into it), open finding #9668. Run it with npm run eval:guest-card-notes.

What the cards actually contain

Typed notes are rare at Western Slope; the team works prospects mostly by texting and emailing from the card.

234 notes in total across 1,171 cards; the leasing agent wrote 61 percent, the assistant PM account 33 percent.

• The timeline import treats texts and emails sent from the card as the primary rows, since they are the conversation.
• Typed notes are secondary and go through the classifier, which is a safety net rather than the main path.

Build order once decided

1. A function that checks whether a staff person has touched a card more recently than Clara has, tested against real card rows.
2. A matcher that turns specific staff actions (application sent, a showing logged, a card closed) into facts the system can act on, also tested against real rows.
3. Wiring both of the above into the follow-up scheduler and the application-send step, as a guard, with no new setting.
4. A test scenario at the Willows: a staff note newer than Clara's last touch stops her from following up or sending the application; a new message from the prospect resumes her.
5. A tracked row on the go-live page for this piece of work.
6. For option 2 only, once option 1 is proven: the prompt changes to reference staff touches safely, a replay run across every client's real history, and a graded results table published alongside this section.

Recommendation

Ship option 1 first: a simple, deterministic check that never reads what anyone wrote, only when they wrote it. Bring option 2, notes joining the conversation, in later and only read-only at first, proven against a replay of every client's real history before it touches a live client. Once that is proven, the same notes become the input for proactively re-engaging a prospect the team is already talking to.

28. PropFlow's opinions vs. AppFolio's quirks — where the line sits today, and the refactor (Proposed — pending review, 2026-09-19)

Fede, 2026-09-19, after the Western Slope Prospects page showed duplicate names, a person listed as her own co-applicant and one record shared by two people: “PropFlow has strong opinions on the data and their entities and relationships and groupings at a generic interface level. Every row is a household. Each human is a person. At the AppFolio level, if they have quirks, the adapter handles all that and hides it. If that's not how it is we have an opportunity to refactor.” This section answers whether it is set up that way. Read-only code assessment; no code changed.

28.1 The short answer

No, it is not set up that cleanly. The read side is: one canonical lookup per question, and every entity that stands for a human carries its person. The write side is not: PropFlow's rules about one person, one household, one lead per card exist as type shapes and intent, and are enforced only by cleanup after the fact, never at the moment a PMS row is written. And the AppFolio vocabulary reaches into what should be generic code: the lead record carries a field literally named af, the writers match AppFolio's status strings inline, and the co-signer name convention is parsed in domain code. A second PMS today has nowhere to put its ids except inside the AppFolio-shaped field.

28.2 What PropFlow's opinions are today, and how hard they are

The four write-time invariants that do exist and run nightly cover tenants, conversations and renewals. None covers people, households or leads.

28.3 Where AppFolio leaks past the adapter

What the adapter does translate well: names, phones to one format, timestamps in the building's zone, money, pets. Yardi and RealPage have no lead or application surface yet; Yardi already keeps its own private status tables, so the duplication has started.

28.4 Resilience to a messy PMS: what holds, what does not

Every rule in 28.2 that says “by cleanup” means: the mess gets in, and a later merge may fix it. That is the opposite of what Fede asked for. The Western Slope page is the proof: a foreign card, a relay email address, a duplicate card and a placeholder contact each got through, and nothing failed loudly. The guest-card sync harness (section 26) is where each of those becomes a fixture that must stay green; a census over every live company's rows that fails on any duplicate, dangling link or contactless person is the missing standing check.

28.5 Options and recommendation

Recommendation: B now, C right behind it, in that order. A is happening regardless (the fixes are in flight). B is the refactor Fede named and it is contained: two writers, one type, one adapter, each PR under 300 lines and dark. C is what makes the engine resilient rather than tidy, and it needs B first so the invariants are written against PropFlow's entities, not AppFolio's. Situs Group's data goes through the harness after B lands and before C starts, so C is designed against two companies' real mess, not one.

Ask for Fede (one line): B then C, as recommended, or A only for now?

29. The AppFolio record is the prospect record (Decided by Fede, 19 Sep 2026 — built dark, sandbox proof gates turn-on)

Decision 2026-09-19: Fede adopted the recommendation (Option D) and answered the five questions below with their recommendations. Turn-on at any customer waits on a sandbox proof that nothing breaks; that proof is the deliverable and is tracked as lane 8.

Session 004, 2026-09-19. Read-only deep inspection, no code changed, no PR opened. Companion to the Western Slope QA RCA (defects D1–D9); this section explains where the model came from, why PMS rows broke it, and what to do. Full source: ~/.claude/handoffs/appfolio-sync-deep-inspection-2026-09-19.md.

29.0 In plain words

The decision. The guest card in AppFolio is the record. PropFlow keeps a copy of it, adds who the person is and who they live with, and writes back what Clara does. Nothing is hard-coded to AppFolio, because Yardi is next.

Why. Today PropFlow keeps its own prospect and then tries to reconcile it with AppFolio. That is where the bugs came from: a card on the wrong property, the same person twice, a household with a phantom co-applicant.

The steps, all off by default:

1. Keep a plain copy of every AppFolio record, keyed by AppFolio's own id. Done.
2. Read AppFolio statuses through one explicit table instead of guessing from text. Done.
3. Map each AppFolio record to one person, permanently, so no id ever changes. Done.
4. Group people into households from the copy, not from our own rows. Open, armed to merge.
5. Prove in a sandbox that nothing breaks, and publish the proof here. Owed. This gates everything below.
6. Switch companies over one at a time (Western Slope, then Situs, then Camellia), each on Fede's go, then delete the old reconcile code.

The four options we weighed, in one line each.

• A. Keep what we have and keep patching. Our own prospect copy stays the record; bugs get fixed one by one. (The 12-fix wave shipped anyway, because it was needed today.)
• B. Keep our own record, but tie every person to AppFolio's id. Fixes duplicate people. Does not fix “we hold a different opinion about the deal than AppFolio does.”
• C. Rebuild everything at once. One big program, big risk, nothing ships for weeks.
• D. The AppFolio card is the record and we are its mirror. B's identity work plus the decision to stop keeping our own opinion about the deal. Ships dark in small steps, switched on per company. Chosen.

What you can skip. Sections 29.1 and 29.2 are the picture and the verdict. Everything from 29.3 on is the analysis behind the decision and is folded away.

29.0a Sandbox proof — first run (19 Sep 2026, Proposed — pending Fede)

Step 5 ran for the first time against seeded copies of all three companies' AppFolio data (JP&Co, Situs, Western Slope; sandbox only, nothing real touched). 17 of 24 checks pass, 7 fail. The failures are the point of the proof: they are listed below with owners. Nothing switches on until this table is all PASS.

Findings, in plain words.

1. The copy forgot the grouping facts. The seeder did not carry AppFolio's application-group and cosigner fields into the copy, so households built from the copy are all singletons. Fix in the seeder (PR 7); the equivalence check is meaningless until then.
2. A second identical poll loses some person links. Nothing changes, but a few guest cards lose their person id on the re-run. Root cause being traced; a re-poll over unchanged data must be a no-op.
3. Situs splits one human and one household. One case out of 1,890. Being traced; the question is whether today's production path splits the same person.
4. Tenant statuses have no table yet. Recorded, not graded; guest cards and applications map 100%.

PRs: seeder #9957, runner #9962 (both dark, tooling only). The runner re-runs unchanged after each fix; this table is replaced, not appended.

29.1 Today vs. the better way — in one picture

  APPFOLIO guest cards  <==FIGHT: both sides own the id and status==>  OUR PROSPECT TABLE
        ^                                                                      |
        |  (a note, sometimes, dark, voice calls only)                        v
   WRITE-BACK QUEUE  <--------------------------------------------  Person, Household, Clara's conversations
                                                                              |
                                                                              v
                                                                       PROSPECTS PAGE

  APPFOLIO guest cards --(pull: cards + status, every 15 min)--> OUR MIRROR OF THE RECORD
        ^                                                              |
        |                                                              v
        +--(write-back: notes at milestones)-- Clara's conversations   Person --> Household
                                                                              \      /
                                                                             PROSPECTS PAGE

29.2 Verdict

Today two ledgers own the same prospect and argue every fifteen minutes. In the better state the PMS owns the record, PropFlow owns the person, the grouping and the conversation, and exactly one arrow carries facts back.