Clara and the PMS help desk

Camellia Apartments, 2026-10-16. A prospect who toured on Oct 13 could not open her lease.

So Clara's guess was plausible, but not what the vendor says for an account that was never activated.

Sources: AppFolio help articles "FAQs: Sending Online Lease Documents" and "FAQs: FolioSpace Online Portal Activations", from our scraped knowledge base. The separate bug where the photo-only text produced an empty office email is fixed in propflowai PR #20491 and is not this page's subject.

"not bloating the prompt, having it be dynamic, where do we store it, what if it goes out of date, what if the vendor updates the instruction."

Ordinary turns carry zero extra prompt text. Only a portal or app question pulls in vendor facts, and only for that one turn (flow at the top).

Account status can only come from the PMS adapter's portal-status read, and that read exists for AppFolio tenants only, not applicants.

Fede: "a better version would be to teach Clara how to resend if needed." Clara resends the lease or portal activation email herself, and forwards to the office only when she can't.

• Today: no code path can resend an AppFolio online lease or portal activation. The move-in robot's send-activation flags (src/lib/integrations/appfolio-browser-agent/l4-core.ts, ~lines 1452–1453) are never used for a resend.
• AppFolio's paths (help articles): "Resend to Tenants" on the lease preview (Leasing > Leases), and "Send a FolioSpace Online Portal Activation" on the tenant page. Both go to the Login Email under Online Portal Status, so first check that it is the email she uses.
• Shape: one new PMS adapter capability ("resend portal invitation", "resend lease for signature"). AppFolio first, via the browser robot; Yardi later. Core code never names AppFolio (Fede, 2026-10-15).
• Rollout: a new customer-facing action (Clara writes to their PMS, the applicant gets an email). So, unlike the fact set: one company setting, default off, proven at Willows and the sandbox company, then Fede turns it on per customer.

B also breaks Fede's 2026-10-15 rule: PMS facts live in the adapter, never in core code or customer data. In C, each fact row carries the provider, topic, short resident-facing wording, the vendor article title and link, the date scraped, and a fingerprint (content hash) of the source article.

We already scrape AppFolio's help center into a private knowledge-base repo: 1,250 articles in today's scraped index. The scraper exists in the app's PMS agentic layer branch.

1. A weekly re-scrape compares each source article's fingerprint.
2. A changed article flips its facts to "needs re-review", and they drop out of retrieval.
3. Until re-approved, Clara falls back to today's behavior: forward to the office. She never recites an outdated step.
4. The change opens a small PR with the new article text, so the update is reviewed, never silent.

All sourced from the scraped help articles. Wording written short and plain; vendor prose is never pasted.

The voice renewal check for portal claims already scores zero for any statement about a person's activation status. The same rule carries over:

• May: describe the vendor's steps, and resend the lease or activation email herself.
• Never: "your account isn't activated", unless the PMS adapter's read says so.

The fact set improves something Clara already does, so it ships with no switch, live everywhere once proven.

1. Replay the Camellia turn locally and show the grounded answer.
2. Run the knowledge-coverage judge over the guest cards we hold, for portal and login questions. Report how many are answerable before vs after.
3. Control: remove the fact set and confirm the same turn forwards to the office again.

The resend climbs further:

1. A Willows applicant asks; the activation email arrives in the test inbox (message id as evidence).
2. Control: setting off, Clara forwards to the office instead.

What happened. Situs Group, 2026-10-31, 2:29 PM. A Spanish-speaking resident called Clara: she forgot her portal password, the app said locked, and she wanted to pay rent. Clara took a note and emailed the office. Fede opened her AppFolio tenant page and clicked Send Reset Password Email; Clara then texted her (by hand, as Clara) that the reset link was on its way. The whole fix was one click Clara could have made herself.

How often. 7 of 770 tenant or caller conversations since Aug 2 (about 1 in 100), from roughly 3 people; 6 of the 7 were phone calls. Every one ended in "the team will get back to you". Counted read-only over the production records; treat 7 as a floor.

Rollout. New customer-facing action, so it stays behind portalInviteResendEnabled (default off). Proof is a real resident call or text at the Willows that ends with the reset or activation email landing in a corporate test mailbox. Fede pre-approved the turn-on at Situs Group and Western Slope on 2026-10-31 ("yes"); it happens as soon as the Willows proof passes, and the proof link goes here. The fact set (sections 3 to 10) is a separate decision and is not blocked by this.

14 real cases, 18 contacts. 9 reached Clara (7 calls, 1 text, 1 email), 5 were in the office's own AppFolio texts. Handled well: 2. Partly: 6. Badly: 4. Slow or unclear: 2. English 12, Spanish 2.

The Camellia case (Oct 16). An approved applicant could not open her lease; Clara deferred to the office twice, the 5 PM deadline passed, then Clara guessed "Forgot password" from a screenshot. When she called back on Oct 22 asking for a person, Clara rang Camellia's office through the shared ring line; nobody picked up, she reached the office voicemail, and Clara emailed the office her callback number. (An earlier read of this as a transfer to another customer's line was wrong: the ring line is shared and rang the right office. A separate defect, the ring line finding no saved call record and hanging up on 4 October callers, is being fixed on its own PR.)

Full table with conversation ids: session 009 scratch file portal/real-examples.md; the counts above are read-only reads of production, not estimates.

Recommendation. Clara reads AppFolio's own help through one look-up tool that works the same on text, email and calls: resident wording from AppFolio's public resident page (English and Spanish), office fixes from the scraped help center, both refreshed weekly into our database, no help text in code. Where PropFlow can act (balance, repairs, a resend), Clara acts instead of pointing to the portal.

Resident or applicant, any channel, any language
  "me pide un código y no me llega"
        |
        v
Clara calls portal_help with ONE topic from a short fixed list
(that choice is the classifier; not about the portal -> normal reply)
        |
        v
PMS adapter: the building's PMS, else the company's
(core code never names AppFolio; no identity needed)
        |
        v
Vendor help rows in our database, per PMS / topic / language
  <- weekly: AppFolio public resident page, EN + ES
  <- weekly: help-center office articles, robot's read-only route
        |  1-2 resident sections + office-fix lines + never-say rules
        v
Clara answers in her own words, in their language
        |  only if the platform can act, and only for a verified resident
        v
Their tenancy: their one home in the line's company (two homes -> ask)
        |
        v
Act: resend invite | reset email | clear two-step (later)
     | repair (already automatic) | team note naming the office fix

Three shapes compared

Spanish: works, with a gap. AppFolio has no Spanish section yet for two-step codes or password reset, so Clara translates the English and warns that AppFolio's emails arrive in English.

Where Clara acts instead of explaining

Company lines: finding the resident's home

A resident matched by phone at ring to one home in the company gets a thread at that home. Everyone else on a company line (other number, two homes, identified mid-call) starts at the line's own record, and the only function that can re-file a thread refuses to move it, on purpose. The tenant checks look only at the thread's building, so balance, lease terms, work-order list and invite resend say "not on file" even once Clara knows the person. 5 of the 7 real lockouts were filed at a company line's record (four Western Slope, one Situs).

Fix: teach the existing tenant-context helper the company-line case and move the four tools onto it: not per handler, not in the PMS adapter. It lists the person's active homes in the line's company only. One: used for that call. None: not on file. Two or more: Clara asks which and accepts only one of theirs. The thread is never re-filed.

Never, in any shape

• Claim an account is active, locked or on two-step without a live PMS read.
• Ask for or accept a password, code, card or bank number.
• Give office-only steps (portal status, unticking two-step, deleting the login email, which also cancels autopay).
• Say an email arrived: sent is not received.
• Invent a portal link, pick a home for a two-home resident, or look outside the line's company.
• End without the team note when the steps failed.

PR cut

1. Help rows and weekly job. The adapter names AppFolio's pages and office articles; nothing reads them yet. Infrastructure, no switch. Proof: first production run's row counts, sections spot-checked against live pages.
2. portal_help tool, identity-free, company-level PMS, on every channel. Improves live answers: no switch. Proof: replay the 14 real cases, then live Willows text, email and calls in both languages.
3. Company-line case in the tenant-context helper, four tenant tools moved onto it. Bug fix: no switch. Proof: read-only replay of every company-line thread with a known resident, then live Willows company-line calls (identified mid-call, and two homes).
4. Verified path, the #20544 lane already open: app PRs #24200 and #24202 (armed) plus the voice PR (in progress); the account-status read moves outside the send switch in that voice PR. Needs robot PR #647 and PR 3.

Decision for Fede

Superseded: the Western Slope phone question now lives in section 14, decisions.

Shipped (2026-11-01)

Switch portalInviteResendEnabled is on at the Willows test property only; Situs and Western Slope turn on when the Willows text proof passes (pre-approved).

Proven end to end on the Willows test property, 2026-11-01. By phone (13:12Z): the resident reached Resident Services, Clara said she was checking, the tool ran, and the AppFolio activation email landed in the corporate test mailbox 49 seconds into the call (call conv_voice_1ddae2d4, email from support@onlineportal.appfolio.com). By text (13:42Z, after the stale-lookup fix #24292): the account lookup ran again, the invite was sent, and the email landed 37 seconds after the resident's text (thread fcedd940). Turned on at Situs Group and Western Slope at 13:51Z under Fede's approval of 2026-10-31; Willows was already on. ConAm and the staff org stay off. Password-reset branch by text (13:59Z, after activating the test resident's portal): the account showed active, the reset ran, and the AppFolio reset email landed (from donotreply@appfolio.com, "Change your FolioSpace login"). Natural-phrasing call (14:58Z, after the routing fix): the resident only said "I'm locked out of the resident portal", the front desk handed the call to Resident Services, the reset ran once, and the reset email landed 56 seconds in (call conv_voice_668db4ca). All three branches proven on every channel. Fixes shipped from the proofs: #24309 (the front desk now hands locked-out residents to Resident Services instead of reading help steps), #24313 (Clara names the real sender of the AppFolio email), #24316 (a repeat call on the same conversation says the email was just sent and to where), #24317 (the help-article tool no longer claims locked-out asks), #24319 (the adapter names the real sender of the reset email); the account-status lookup column fix is in review. Follow-ups: #24326 (front-desk handoff line promised a send and named the wrong email), #24325 (team note dropped that a reset was already sent), #24310, #24311, #24312, #24314, #24315, #24269, #24300, #24301.

Portal help live proof (#24270). Live proof on the Willows test property, 2026-11-01: text in English PASS (tenant 1900, conversation 4a346881: autopay steps straight from AppFolio's help pages, no links, no made-up claims). Text in Spanish PASS as designed (a code that never arrives always goes to the team; the team note carries the 2FA reset). Phone PASS (call conv_voice_8328541c). Email: not run. Our test mailboxes all sit on the company domain, which the app treats as staff mail, so no test resident can email the Willows mailbox; needs a sender on another domain. Follow-ups filed: #24300 (Spanish answers should warn that AppFolio's emails arrive in English), #24301 (the team-note writer failed twice, so raw words went out), #24269 (Clara asked a recognised caller for their number).

Proposed, pending Fede's review. Read-only, Oct 31 night: code, production records, every call Sep 1 to Oct 31, two independent deep dives, 7 live Willows calls, a 70-case replay. Central time.

Decided (Fede's rulings)

• Turn-on is Fede's call on Nov 1.
• One Resident Services module across channels; no per-channel settings ("I don't love having a bunch of settings").
• Key pickup has no setting; offered only where the customer's facts (office handoff, hours, calendar) exist: Camellia only today. No general office-appointment concept.
• Lease & Billing becomes Resident Services. Triage stays. Turnover intake and vendor outbound are lab. Unknown Caller questioned (decision 3).

1. What Resident Services is

2. Why Western Slope turned it off

Sep 22, 9:53 AM Central (8:53 Mountain, 7 minutes before the office opened). Dylan L., co-tenant, lease starting Oct 1. 43 seconds.

Fede, about 10:40 AM: "he never asked about his keys", "this should have just taken a message", "we don't know how they do key pickup so we should be off", "lets disable this agent for this client".

What actually went wrong.

• Unprompted offer. The prompt maps "move in" to key pickup ("This is the one thing you schedule"). Western Slope hands keys over at the home, as its knowledge says.
• "I can't". A co-tenant lookup bug (fixed that morning, #10767), spoken as a bare refusal.
• No message. The agent has no message tool, so it offered one instead of taking it. conv_0301m34sp4e7emx8zfyapadzngmz

3. Battle test, Oct 31 night

Live calls to the Willows test line (robot caller, graded by the judge). 6 of 7 pass.

Every real resident ask, Aug to Oct, replayed through today's code (writes blocked), graded against the records.

Asks: payments 21, balance 14, key pickup 14, other 21. 6 dropped: a person but no home attached. Control: planted wrong amounts and a card ask grade FAIL; unchanged replies PASS.

Worst three.

1. JP&Co, a $90 money order: "it looks like the payment did get processed". A zero total does not show that money order was applied. Invented. conv_voice_99b28729-721f-4c67-9c89-6a47d2abed37
2. Situs, text, replying to an eviction notice, "What date will that be?": "this might be the start of our conversation". The history was there. f4f65d36-e426-4cf6-839a-4d0f17b17021
3. Western Slope, a $44.19 charge, caller wanted a person: Clara read the balance and never handed off or took a message. conv_voice_c8cbe2a4-fe92-4ce7-b374-8214b613e8d0

Dylan's call, replayed: on "Move in." she still reaches for key pickup, now with the honest reason (no signed lease), and still promises a message she has no tool to take.

4. The two switches, and one module

Recommendation: delete the old switch; the module is the only control. The builder's branch adds a per-channel row in its place: drop it, keep the deletions and the replay (212 resolutions, 8 companies, 0 differ; its control catches the Western Slope flip). It merges with today's turn-on, or after Western Slope reads Off on the Modules card, never as a surprise turn-on.

Where the two deep dives disagree

5. Proposed agent map

Triage sorts by verified resident, then topic, and it holds: no repair or renewal ask reached the resident agent in two months; 12 of 150 hand-offs (8%) misrouted, mostly vendors.

11 active agents become 9. Folding Unknown Caller adds 4,400 to 29,900 characters to Triage's 95,700, depending on how much moves; its one unique power (ringing the manager for a vendor on site) was never used.

6. Key pickup by policy facts

Offered only when the facts say keys are handed over at the office, residents may book, hours are on file and a calendar is connected. Otherwise Clara states the move-in fact and takes a complete message. Today's check ignores the key policy and always says "at the leasing office".

Camellia's fact is written before the gate merges, or it loses booking.

7. Data: leases are not stale

The sync runs every 5 minutes, 143 buildings, 0 errors in 24 hours. The "last synced" stamp moves only when a lease changes.

Situs's 44 tenants with no linked lease: 33 at Bryant Gardens (rows exist, person link blank since onboarding; repair script exists; running it is Fede's call), 8 Section 8 (rent billed under the voucher, so no lease is made; bug fix in flight), 3 not gaps (parking space, Nov 1 move-in, ended lease).

8. Fix list and PR cut

9. Decisions for Fede

Sources: session 009 scratch folders portal/, part1/, part3/.

Progress since approval (2026-11-01)

Fede approved all four decisions in section 9 on Nov 1. Central time.

Found, not a bug. A payment text at Willows looked unanswered. Clara's reply was held for review because Collections is Supervised there, as designed. Two wording follow-ups: #24275, #24276.

Question (Fede): did folding Unknown Caller into the front desk bloat it? Answer: the fold added about 2%. The front desk was already far too big. Read-only audit of the live prompt against 510 real calls (Sep 1 to Nov 1). Proposed, pending Fede. Full report in session 009's proof ledger.

Growth: 21k on Jun 1, 66k Aug 1, 89k Sep 1, 99k today. ElevenLabs' own guide says prompts over 2k tokens cost latency; we are 12 times that. Speed is not the problem (first reply 0.75 s, same as the smaller agents). Rule-following and cost are.

Biggest finding: one hard rule is ignored 87% of the time. The prompt says never dial the client's main line when none is set up. On real calls, 47 of 54 main-line dials happened with no line set up (30 at Western Slope in October). The caller hears "let me connect you" and then gets a message. The server's fallback saves those calls, not the prompt. The fix belongs in the per-call handoff instructions, which contradict the rule.

Rules that never fired on a real call in two months: muted caller, escalated-thread posture, maintenance backup line, leasing-off text, three-transfer cap, property manager turnover walk. Near-dead: maintenance-off text (1), staff rule (2), language-known (3). Contradictions found: "they'll follow up with you" next to a ban on follow-up promises; "one moment" banned in one place and scripted in another; "taking a message is your ONE action tool" while the agent holds 15 tools; "never move a vendor's visit" while the reschedule tool is attached.

Fede, 2026-11-01: fix the ignored main-line rule now (cut 1). Shipped as #24371, live 2026-11-02 03:42Z: the per-call handoff text says "take a message" when the call has no main line (all 47 past failures now render that way; a front desk re-run on 43 real calls dropped wrong dials from 10 to 13 down to 2 to 3). Before, Western Slope Oct 28: "Let me connect you with someone on the team." then "Nobody can pick up right now". After, Willows Nov 2 after hours: "The office is closed right now, I'll leave the team a note with your number and your question." (conv_voice_533c88a0). Found on the way: the second half of the fix, new wording on the connect tool itself, never reached ElevenLabs because the agent sync ignores parameter wording when deciding what changed (#24405; every past tool-wording change had the same gap). Fixed by #24408: the 04:33Z sync found the drift and pushed the connect tool text; the live tool now matches the code. Both halves of the fix are live as of 2026-11-02 04:40Z. Follow-ups: #24366 (front desk rings leasing instead of taking a message, ~20 of 43), #24372 (emergency step still names a main line that may not exist), #24406 (name correction refused after the note is filed). The size trims (cuts 2 to 5): "seems fine for now", parked.

Original ask (for the record): cut 1 is a fix and ships under the standing grant. Cuts 2 and 4 are behavior-preserving and can ship as one PR each with the proofs above. Cuts 3 and 5 rewrite wording the drift tests pin; recommendation is to do them as one "prompt diet" PR proven by a full replay like July's. Recommended: yes to 1, 2, 4 now; 3 and 5 as the diet PR next week.