Clara Onboarding Playbook

Everything needed to take a new property-management client from signed to fully live on Clara: the must-haves, the setup steps, how knowledge is collected and applied, how we prove it, and how we turn it on in stages.

Rewritten 2026-09-22 from two weeks of sessions, PRs and incidents. Built from the Camellia (JP&Co), Situs Group and Western Slope onboardings. One page per initiative: add to this page, don't start a new one.

1 · Who this is for

A Claude session or a human engineer onboarding the next client without Fede in the room. Work top to bottom: collect the answers in section 2 from the client first, run the setup in section 3, build and prove knowledge (4 and 5), then turn on in the stages of section 6. Every rule here came from something that broke. When a rule and a newer dated Fede ruling disagree, the newer ruling wins; fix this page in the same turn.

"All the learnings I've had in the last two weeks condense them in one document that is useful for both Claude AI and for a human engineer. So if someone else is onboarding another client, I don't have to be involved directly."

Fede, 2026-09-22, session 010

2 · Go-live must-haves (one checklist)

This replaces the three older checklists (the repeatable playbook, the 18-step pre-go-live list and the Situs list). An item is done only when its proof is pasted on the client's go-live tracker row (for Western Slope, the go-live tracker). Merged code is not proof.

Client record and access

Phone lines

Once a client forwards their main line to Clara, that number is no longer a safe transfer destination: it rings straight back into Clara. Never set any transfer destination to a number that forwards into Clara. Person-transfers go to people. "Everything else" destinations live at the company level, not per property.

Email and calendar

AppFolio

Knowledge

Proof

3 · Setup, step by step

The order that worked. Each step says how, and when it counts as done.

4 · Knowledge: collect, review, apply, test

1. Collect (automatic)

2. Draft against the core checklist

The must-haves are fixed before any client is looked at ("we should know what we need before hand", Fede, 2026-09-15). The pull marks each one found, conflicting or missing; the questionnaire covers the gaps and cannot skip a must-have. Draft in the Camellia shape: 12 to 20 leasing items, split into company policy, home fact, internal-only and settings. A 122-question flat list was rejected on Sep 8.

Western Slope audit against this list, 2026-09-15: 15 filled, 4 conflicting, 5 empty, 2 listing-only. A 397-question bank mined from 5,465 real inbound turns (Situs and Camellia) grades coverage for a client with no history: Situs scored 27% answered, 2% wrong, before any fill.

Consolidation before a human sees anything: documents and system settings auto-confirm; message-mined facts auto-confirm above an evidence floor (5 messages, 2 staff, no contradiction); identical values across homes become one company fact; live state (vacancy, balances, application status) is never a fact; a missing fact goes to the fill list, never a blank for the client to type into. What reaches a person is conflicts only.

3. Review: us first, then the client

1. The draft goes to hello@propflowai.co and Fede reads it before the client sees it. Once two companies have gone through cleanly, this step becomes automatic.
2. The client gets a link and password to the in-product review and confirms, corrects or answers each item, then clicks "I'm done".
3. Their answer is the decision (rule 1 below).

"How do we like automatically create that from their AppFolio and their email and all the other sources we have, and then you send them a link with the questions, with a human in the loop first. So we review it, but eventually autonomous."

Fede, 2026-09-22, session 010

4. Apply to the right layer

• Classify first (Fede, 2026-09-15): each answer splits into what Clara says to prospects, what she knows but never says, and what is not knowledge (a setting, listing data, a question back). Never transcribe the raw answer.
• Held out and listed, never written silently: anything that conflicts with fair housing or the law (a blanket "no assistance animals" rule), an answer that doesn't match its question, and "it depends per home".
• Never in knowledge: internal owner decisions (Aug 5: a Camellia special exception leaked into knowledge), instructions to Clara, hand-typed hours.
• Tools: scripts/knowledge/load-knowledge-gold-set.ts --apply places every approved fact or refuses to finish. apply-knowledge-review (#8650) applies a finished review, dry run by default, and prints a before/after diff.
• Open (no ruling recorded): whether staff edits made after the review always win over a re-apply (recommended), and whether the first company-layer write at a real client waits for Fede's before/after read (recommended).

Hours: one structured setting, never knowledge prose (2026-09-18)

Hours ended up in five places with three values because a knowledge pass hand-typed "Closed weekends and holidays" from the website. The rule: office_hours answers when reception is staffed; tour.hours answers when tours can be booked and falls back to office hours when unset. Never merged. Every channel reads the same resolver. Onboarding writes the setting once from the client's answer. Hand-typing a day or time range into knowledge is forbidden when a structured setting exists. A build check that fails hour-like text in knowledge is an idea, not built.

Rules for the knowledge base writer (Fede, 2026-09-15, from the Western Slope pass)

Fede reviewed the first machine-drafted knowledge base for Western Slope entry by entry. Every rule below is a mistake the draft made. The script, the draft generator and the review page follow them from now on. Result: Western Slope knowledge base.

1. The client's answer is the decision. Once the questionnaire is answered, the answer is the fact. Old charges, unit settings and lease templates are context in the internal note, never a "conflict" and never a question back. (Fee: Jay said $40 twice; the draft flagged it against $32 history.)
2. Ask back only when the client's own answer contradicts itself, and even then take the explicit statement (Friday: "closed Monday and Friday" wins over "Tuesday to Friday 1 to 3").
3. Entries are facts, not lines. Never write what Clara will say ("Tell me which home and I'll give you the amount", "I'll text you the link"). Write the fact; Clara phrases it per channel.
4. Short. Figures as variables, no explanations. "Refundable pet deposit $300 total. Pet rent $35 per pet per month." A caller cannot follow a paragraph.
5. Company table and property table, separate. The general rule lives at the company (a leasing associate hands over keys). The exception lives on the building it names (Pomona Park, Ember Estates, Flats on Elm: door code, keys inside). Never a company entry that lists building exceptions inline, and never a company entry whose only content is naming which buildings differ.
6. Listing data is not knowledge. Rent, deposit amount, utilities included, promotions and the Apply link for a specific home come from the listing. The knowledge base holds only the rule ("deposit is usually one month's rent; amount on each listing").
7. Never ask the client what the platform does or what the listing knows. No "how do prospects book a tour" (Clara books it), no "what is the apply link" (each listing's Apply button), no "what is the move-in payment method" unless a prospect actually asks that.
8. Volunteer nothing sensitive. "No pets" is the entry for 632 Hill. Assistance animals are not mentioned; if asked, Clara's standing behaviour sends it to the leasing team. No "review with counsel" notes on a client page.
9. No investor words. "Portfolio", "units", "screening report" only where the client uses them. "Home", "the office", "the leasing team".
10. The review page is the cleaned version only. Two tables, property above company, columns # / topic / entry. No raw column, no banner, no questions section, no flags unless rule 2 applies.
11. Three layers. Company = the general policy. Property = its exceptions only. Listing = what that home adds on top (rent, deposit amount, utilities, promotions). The writer never copies a listing fact into either table. (Fede, team meeting 2026-09-15: "general ones at the company, some exceptions at the property level, and the listing could specify something in addition.")
12. Short because Clara reads it all. On a call she tends to read the whole entry. Anything per home or at the team's discretion is one line that ends in "on the listing" or "the leasing team decides", never a paragraph. (Fede, same meeting: "I don't want Clara to read all this on a phone call.")
13. "How do people apply" is an action, not an entry. Check how the client's staff do it in their sent mail and guest cards before asking anyone. Western Slope: staff click "Send application" on the guest card in AppFolio; one form per home; no generic link. Clara has no per-home apply link today (one link per property setting); gap logged on the Western Slope page.
14. Classify before writing. Each client answer is first sorted: prospect-facing fact, internal context Clara knows but never says, or not knowledge (listing data, setting, action). Never transcribe the raw answer. (Fede, 2026-09-15.)
15. Tag the audience. Every entry carries who it is for: prospect, resident, staff. A resident-only fact never reaches a prospect. (Fede, 2026-08-26: "how do we segment the knowledge base so we don't give this info out to everyone.")
16. The questionnaire triggers the build. No person writes or runs a script per client. Said in four sessions since 2026-09-02: "that works for one customer, it doesn't work for ten."
17. The knowledge base is public. Rule 17 (Fede, 2026-10-07): the knowledge base is public. Staff cell numbers, personal emails and anything marked do-not-share are never saved, even tagged staff-only.

Required entries before a line goes live (Fede, 2026-10-07)

Western Slope's first real self-guided tour escalated three questions to the PM that every customer must answer at onboarding; Fede: "we should already know all this."

• Application process and link (or AppFolio-generated applications), stored in the company's leasing settings so Clara can send it on request and after a tour.
• Co-signers and guarantors: allowed? Own application and fee? Income rules.
• Roommates and additional occupants: can two people sign one lease; adding someone later.
• Screening basics Clara may state: application fee, what is reviewed, who decides. Never predict outcomes.
• Lease terms offered.
• Pets.
• Parking.
• Utilities included.
• Move-in costs: deposit rules, not amounts, which live on listings.
• Tour format per property (staffed, self-guided by lockbox, video) and what the host must be told.

An onboarding is not complete while any of these is missing; the gap shows as an escalation to staff on the first real prospect.

No rule above is contradicted by a newer ruling. One status note in rule 13 is dated: the application-link mode moved to the company level on 2026-09-19 (Fede: "this should not be per property"), with a PMS-generated option (leasing.applicationLinkMode). The rule itself stands.

The test that keeps these rules alive: western-slope-knowledge-gold-set.json holds Jay's 26 raw answers and the 24 entries Fede approved. A draft generator must reproduce those entries from those answers (topic, tier, every figure) before it merges. Verbosity budget on top: voice one figure and one date per turn; text answer plus figure plus link; email full.

5. Test knowledge

npm run knowledge:verify-live -- --gold <gold-set.json> --property <front-door-property-id>
# renders exactly what Clara reads, diffs it against the approved file.
# must print 0 missing and 0 unplaced; prints how many answers it compared
# (zero compared = failure). Refuses to run if the building map names an unknown building.

• Read back both layers directly (org node and every property row). A review's "open" or "done" status is screen state, never proof.
• One bench call, text and email per home exception (knowledge-exception-* scenarios in scripts/voice-harness/scenarios/), answered from the exception, not the company rule.
• Check no two sources feed one answer with different values (the $27 vs $40 fee).
• Harness for the whole path: scripts/onboarding-harness/knowledge.ts runs create, load, verify red-before and green-after on a scratch org.

4b · Reading the notes managers already keep Proposed — pending review

No new route: same report, four columns we drop today.

A fifth column, showing settings, says "Default Settings" on all 171 buildings, so there is nothing to read.

Before and after

Gera's data grade for Western Slope is 70 of 100 today; it was not re-graded with the notes added.

Your calls

Worth building? Yes, with the source rule above. At Western Slope 1 lasting fact in 7 disagrees with something we hold, mostly normal building exceptions; at Situs 1 in 22.

5 · Testing and proof

Dry runs as a prospect

Before turn-on, the team plays prospects end to end with every channel live: "we have to do real dry runs where we simulate that we're prospects. We're just not gonna do it with real people who submit through AppFolio yet." (Fede, 2026-09-13)

Test organisations

No session creates another test org. Test orgs must reproduce customer issues; no test-only shortcuts in a proof.

Per channel (full mechanics in docs/runbooks/real-path-e2e.md)

Voice  pre-PR:  /fastlane  (throwaway clone of the prod agent, real call, deleted after)
       proof:   /robocall after merge; cite call id + verdict (no pre-merge voice lane)
Email  proof:   scripts/email-stress/run.ts with STRESS_TRANSPORT=ses (or gmail), post-deploy;
                cite message id + a clean Sentry window. sqs transport = smoke only. No --cleanup.
SMS    pre-merge: ./scripts/claim-preview.sh --status first; preview number; --release when done;
                deploy the preview inbound-processor Lambda for src/lib-only diffs
Cards  /guest-card-regression (reply quality) or /household-regress (identity),
       one canonical corpus at ~/.claude/guest-card-corpus; never re-mine

6 · Turn-on stages

"Turning it on YOLO immediately is not a good strategy… a week where it's human in the loop… then after that week if it's good we turn it on fully."

Fede, 2026-09-22, session 010

Stage 1 exit criteria

• A judged replay of every captured guest card for the client, plus Camellia as the no-regression control, scores 0 "do not send" and at least 90% send-as-is (Fede, 2026-09-19: "Practice with every single one of those cards… once that's good we can turn it on autonomous").
• No open correctness bug from the week on the client's own shape: "not until we have this fully baked and all bugs fixed" (Fede, 2026-09-21).
• A fresh-card proof passed after the latest deploy.
• Fede's explicit go for this customer. A sentence like "I want email autonomous too" is a goal, not a go: on 2026-09-21 the hold was flipped off on such a line and reverted within 38 seconds. Confirm in one line.

Known tension in Stage 1: the client's staff can answer before a held draft is approved. Those drafts are rejected, not sent.

Ramp-only restrictions (each must be removed at its stage)

6b · Team intro email (draft, pending Fede review)

Proposed — pending review 2026-10-31 · first use: Situs Group leasing team · not sent

One email from Clara to the whole leasing team on go-live day: who she is, what she does, what to expect, and the three things she needs. Built from shipped copy and Fede's past edits, not new prose. To: everyone who works leads or gives tours. From and Reply-To: clara@propflowai.co, hello@ as a hidden BCC (Fede, 2026-10-30). Plain coworker note, signed "Clara".

Where the words come from

Open questions for Fede

1. "I'll let you know": per-person tour emails are off for the hosts and the tour-day host email is still being built. Turn per-person tour emails on for Lee, Deiby and Miriam before sending? Recommend yes; otherwise cut to "it goes on your Google calendar".
2. "Just email me" to move a tour: no recorded run shows a staff email moving a tour end to end. Recommend one Willows run first; if it fails, say "reply to the tour email".
3. When to send: the after-hours line needs Situs's main number forwarded to Clara, and the after-tour text needs #24225 merged. Recommend the morning both are live.

7 · Switch reference

Go-live is two switches: ours (the company live switch) and theirs (call forwarding). The rest are per-company settings. Each row was checked against the code on 2026-09-22. Settings are staff-only.

The customer page also carries a read-only go-live checklist (GET /api/admin/companies/<id>/go-live-checklist: portfolio connected, escalation owners, email identity, phone line, calendar, mailbox reading, inbox, billing). It never blocks the switch; section 2 is the full list. Removed for good, never re-add: the email shadow switch (2026-09-17), texts delivered through AppFolio (2026-09-20), the per-property mailbox toggle (2026-09-15), the "book on people's calendars" flag (2026-09-16).

8 · Common pitfalls

One line each: what happened → the rule now. Most costly first in each group.

Phone

• 2026-09-17 One empty dynamic voice field failed every call on every line for about two hours → no dynamic field may resolve empty; revert a voice regression first, re-land second.
• 2026-09-22 Catch-all pointed at the client's forwarded main line; three callers dropped → never a forwarded number as a destination; Clara refuses them (#10795).
• 2026-09-21 RingCentral answered before the press-1 prompt; callers never reached staff → ask the phone system first; plain forward is the default (#10567).
• 2026-09-17 Caller recognition beat the client's maintenance route → the client's intake route outranks recognition; a forward is a plain transfer.
• 2026-09-22 A call center's "press 1 for a text" texted Clara's number, not the tenant → passing the caller's number needs Twilio's call-token mechanism, not a caller-id string (Twilio refuses numbers we don't own on that leg). Not built as a setting yet.
• 2026-09-19 The phone-number attach returned an error halfway and left a write-once half state → dry-run the claim and read the agent binding first; repair with attachPhoneLine(), not a re-POST.
• 2026-09-20 to 22 "No press-1" and "no voicemail detection" were treated as one decision → they are two. Making voicemail detection the default is still an open PR (#10835).

Email and guest cards

• 2026-09-17 A leftover shadow switch hid every staff notice from the client from day one → no shadow or redirect switches on outbound email; "email on" means a delivered event.
• 2026-09-22 A first email ignored the home the card named (Western Slope card 2948) → one read-only which-home resolver, never first-match; it answers "ambiguous" rather than guess. Battle test done: 3,390 real cards from 3 clients, 0 wrong homes (#10924).
• 2026-09-21 A race dropped the first email on brand-new cards → every proof includes a fresh card made after deploy (#10423); the created-by race is a bounded retry then an alert (#10926).
• 2026-09-21 A prospect's "That works, thanks!" was filed under a catch-all property and sat an hour unanswered with no alert → a reply must land in the same person's conversation; the conversation belongs to the person, not the home.
• 2026-09-19 Western Slope's first emails went out as bare text from a second send path → one send path and one template for every prospect email.
• 2026-09-16 100 reminder emails hit the client in an hour when a recipient address was set → reminders are opt-in; before writing any recipient address, list every sender that uses it.
• 2026-09-22 A first email asked about move-in instead of offering tours → always offer real tour times, fetched before composing (#10932, open).
• 2026-09-20 Zillow relay emails minted duplicate leads beside AppFolio's cards → set the prospect record owner.
• 2026-09-20 First-email drafting inside the AppFolio sync crashed on a real lead with no alert → the sync only emits "lead received"; the agent loop drafts.
• 2026-09-19 A note reported "added" that AppFolio's new CRM page silently dropped → every write-back is read back; unverified is reported as unverified.
• 2026-09-19 A session invented "never reply to Zillow cards" → no source-based exclusions; the rule is who created the card.
• 2026-09-16 A guest-card sync overwrote a Camellia resident's phone, so Clara treated him as a stranger → the guest card stops writing once an application or tenant exists (#8950).
• 2026-09-21 Assign-to-Clara rode on the send, so held drafts left cards unowned for hours → assign on detection (#10865, open).
• 2026-09-19 A successful application send emailed staff → success is a quiet timeline event in the conversation.
• 2026-09-15 A per-property mailbox toggle was built on an open question → an open question is not a ruling; don't build on it.

Knowledge

• 2026-09-21 Prospect texted $27 against the client's $40: a sync overwrote the verified fee → verified figures are protected from scrapes (#10572); one owner per number.
• 2026-09-16 Home exceptions never loaded; Clara offered in-person tours at a lockbox-only home → the loader refuses unplaced facts; verify what Clara reads.
• 2026-09-21 A session reported the client's answers "never applied" after reading only the property row → read both layers, then run the live check.
• 2026-09-16 The read-back check cried wolf with 21 false alarms, so nobody read it → it is property-aware now (#10712) and fails on zero answers compared.
• 2026-09-18 Hours lived in five places with three values → one structured setting; no hand-typed hours.
• 2026-09-12 A company "deposit is one month's rent" sentence beat each home's real figure → figures that vary by home come from the listing.
• 2026-09-10 The review re-asked for office hours we already had → anything confirmed by a document or setting is never asked.
• 2026-09-08 A 122-question flat review ("insane slop ball") → Camellia shape, four-way split.
• 2026-08-05 An internal special-offer exception was written into Camellia's knowledge → internal decisions never go in knowledge; Clara escalates.

Client record and access

• 2026-09-07 Another client's data and settings were visible to a new admin → isolation check before any invite.
• 2026-09-05 to 15 Two copies of the same company for ten days → one record, from the pull.
• 2026-09-16 Years-old cards and applications imported → 30-day window on import and sync.
• 2026-09-21 Company-wide facts (Clara's AppFolio user, signature, time zone) had been built per property for apartment communities → capture them once at the company.
• 2026-09-30 Situs handoff to Gera: situs-group-onboarding-handoff (current state, remaining steps, knowledge flow). The 09-20 blocker below is superseded: Situs connected AppFolio and its mailbox on 09-29.
• 2026-09-20 Situs could not be created: the import needs AppFolio API credentials and Situs has only a browser login → no placeholder; wait for API access or a browser-based import.

Engineering and proof

• 2026-09-22 A new behavior invented its own rule beside a tuned one (four 8 AM slots, #10932) → find and reuse the existing implementation first.
• 2026-09-21 Proofs only on Willows and Camellia shapes → one lead in the client's own shape before go-live.
• 2026-08-19 Green unit tests and evals, broken for real users → real-path proof for anything a customer receives.
• 2026-09-20 Two "defects" were grader errors → independent mutation controls on every check.
• 2026-09-19 "Done" claimed with six PRs open and no proof run → done means merged and proven, with the artifact.
• 2026-09-17 Twelve empty tour records from an update path → an update never creates a record.
• 2026-09-15 Three pushes in three minutes cancelled each other's deploys and Fede read a stale page twice → send a link only after the deploy is green.
• 2026-09-13 A tour "confirmation window" setting was wired to the wrong meaning and reverted → confirm the meaning in one line before building a timing setting.

9 · Learnings log (dated, append-only)

The history behind the rules above, condensed. Add new entries at the bottom of the right subsection, dated. When a decision is superseded, say by what.

2026-09-01 to 02 · Situs overnight fleet (the first run)

• One run on situsgroup.appfolio.com: 5 h 39 min wall clock, about 24 agent-hours; a re-pull with the toolkit took 1 h 35 min. 17% of effort was noise, almost all from records captured with no post-condition.
• Findings: 23 stable rules, 27 conflict rows, a 2,118-turn replay at 56% acceptable. Loading the full mined knowledge base left the replay at 56%: 64% of question volume needs live PMS data (tour calendar, availability, balances, application status), which no document supplies.
• No policy document was captured at all; the rulebook had to be rebuilt from staff messages. Staff quoted a flat $50 late fee while AppFolio held five schemes: the gap between said and configured is the client conversation.
• Pitch: "overnight", delivered in a few hours.

2026-09-05 to 15 · Camellia, Situs and Western Slope

2026-09-15 to 21 · The Western Slope knowledge days

1. One record per customer from the first hour. The placeholder cost an afternoon and 2,049 deleted rows. What blocked the delete was what pointed at it (a shared id, a workflow re-creating it, a test job): inventory those first.
2. The questionnaire is the decision. Stop debating with our own history ($32 charges vs their $40).
3. Know what the platform does before asking. Clara books tours; applications were a per-home AppFolio button.
4. Name the data source before reasoning about it. A "rent roll" turned out to be a public-page scrape.
5. Entries are facts; Clara does the talking.
6. Subagents draft without product context: every page they write gets a pass against the writer rules before it reaches Fede.
7. 2026-09-16: 17 company facts loaded, 7 home exceptions did not; "reviewed" had meant "the client approved the file". The loader and knowledge:verify-live fixed it.
8. 2026-09-21: company-wide details (Clara's AppFolio user, signature, time zone) were missing because they had been built per property. The first-lead dry run now checks assignment, signature and time zone by eye.
9. 2026-09-21 afternoon: the first single-family, no-unit leads showed five defects: a reply filed to the wrong conversation, one person split into two across email and text, a team handoff dropped because Clara's reply looked complete, a mismatched fee, and no one-step way to pause Clara for one person.
10. 2026-09-21: a press-1 prompt fails on phone systems that answer instantly. Plain forward is the default.

2026-09-21/22 · Retro: the false "never applied" finding

Western Slope answered all 22 review questions on Sep 15, and the apply did run: 18 company facts were written to the org node that day, application fee $40; hours were updated there again on Sep 18. The Sep 21 investigation read only the property row (8 old sections) and the review's "open" status, and concluded wrongly. The real gaps were one Ember Estates exception (written that night) and Redcliff having no property row. The $27 fee came from a scrape overwriting a verified field (#10572). Root cause: company knowledge lives on the org node, exceptions on the property node; a check that reads one of them, or trusts a status field, reports the wrong thing.

2026-09-07 to 17 · Western Slope: what went wrong and the rule that prevents it

PRs behind these rules: 7919, 7962, 8007, 8043, 8060, 8314, 8375, 8378, 8458, 8553, 8606, 8638, 8704, 8726, 8750, 8844, 8861, 8882, 8893, 8900, 8912, 8913, 8923, 8927, 8934, 8958, 8962, 8964, 8968, 8969, 8970, 8973, 8977, 8978, 8979, 8980, 8986, 9013, 9031, 9036, 9046, 9047, 9098, 9103, 9105, 9113, 9135, 9137, 9139, 9140, 9144, 9148, 9155.

2026-09-15 to 20 · Situs Group build notes

• Situs: about 645 homes, browser login only (no Reporting API), full 2025 and 2026 dumps in ~/situs-data, shared AppFolio login with JP&Co at the time.
• Build order Fede set: questionnaire generated from the raw pull and emailed to hello@ first; the "I'm done" submit event; a job that builds knowledge from that event; smoke tests after each build; a per-client Clara login. Clara interviewing the team is long-term only.
• 2026-09-20 blocker: the only path that creates properties from AppFolio (POST /api/onboarding/pms/appfolio/import) needs API credentials. A prod scan found no Situs records at all. Situs waits on AppFolio API access or a browser-based import. Update 2026-09-29: Situs Group connected through the standard connect step today (52 buildings); see the retrospective in section 9.

2026-09-15 · AppFolio: sending the rental application

Documented at the Willows, headless: guest card → Rental Application → Send Rental Application. The form needs a specific unit or campaign (a bare property 400s) and an email even for SMS. It posts to /guest_cards/{id}/email_rental_application keyed on AppFolio's live unit id, which is not PropFlow's id: any automation must re-resolve it at send time or it can send the wrong home. A successful send is a quiet timeline event, never a staff email (2026-09-19).

Import and sync retrospective, Western Slope vs Situs Group (2026-09-29)

TL;DR: Western Slope's import hit 6 real mistakes over 10 days. Four of them cannot happen again (the code now prevents them). One was repeated at Situs today: the sync was connected without the rate-limit protections turned on, and AppFolio started refusing calls within minutes. One is still unfixed at both customers (the property list never refreshes after import).

Western Slope (Sep 11 to 24): the mistakes

1. The first pull hammered AppFolio. We treated a brand-new customer like an existing one: the every-minute sync fired for every building and retried into AppFolio's rate limit. About 25,000 requests in 3 hours and only halfway through. You paused it and ruled that the first pull becomes its own one-time import, run in order, on its own request budget. Fixed for good: the 5-stage onboarding import and the per-customer request budget exist because of this.
2. Import said "done" with a quarter of the homes missing. 159 of 234 units landed, twice, and both runs reported success. Cause: the importer threw away unit names that looked like street addresses (single-family homes). Took two fixes to reach 234. Fixed for good: the import now fails loudly if it gets fewer doors than AppFolio reports.
3. Things we weren't supposed to import. Commercial buildings, mixed-use, owner and bank ledger entities came in as properties; one commercial company became a "resident". Your ruling: residential only. Handled by a hand-made exclusion list, not by the engine.
4. Old records woke Clara up. The import brought in 145 applications and 1,065 guest cards going back months. The reminder job emailed Western Slope's leasing inbox 100 times in one hour. Fixed for good: 30-day window on imports, reminders opt-in, 1,057 stale records deleted.
5. No time zone on any building. All 69 properties imported with a blank time zone, so a follow-up text went to a real prospect at 7 AM. Fixed by hand that day; Camellia had the same gap earlier and it was not carried over. Fixed for good as of today: import now fills the company's zone and never blocks setup on a missing one.
6. Work orders silently skipped. Every building imported without a short code, so the work-order sync failed on all 82, then on 18 buildings for about a week. The import fix is live; the repair for existing buildings shipped dark and is waiting on your go.

Smaller ones: 2.5 baths quoted as 3 (136 units, fixed urgently Sep 25), two people split into duplicate records by the sync (fixed Sep 24), a synced application fee overwrote a verified one, duplicate prospect rows from two guest cards fighting over one person (partly fixed, two issues still open).

What was better the second time (Situs, today)

• The one-time import ran as designed: 52 buildings connected and synced in about 5 minutes, no hours-long crawl.
• Door-count gate, 30-day window, reminders off, per-company credentials and per-database ids all applied automatically. No re-import, no reset script, no wiped tables.
• Co-managed buildings (a building already held by another company) are refused instead of duplicated, built Sep 27 specifically for a second customer.
• Time-zone gap caught at the last setup step and fixed in two PRs the same afternoon instead of after a 7 AM text.

What was NOT better

• The rate-limit mistake repeated. Situs was connected with none of the "one call per portfolio" switches and no request budget row. Within minutes 8 jobs were fanning out one request per building, AppFolio was refusing calls (281 refusals in 15 minutes), and two alarms tripped at 10:02 and 10:10 AM. The same fix that saved JP&Co and Western Slope has to be pressed by a person; the coverage checker cannot even see Situs's connection yet. No recovery notice in #alerts since.
• Hugo selected every property, so bank and LLC entities came in again, same as Western Slope. Gera is disconnecting them by hand. Third customer in a row where the exclusion is manual.
• A tenant split on a hyphenated surname two days before a move-in (the lease and the guest card spell the name differently, and the merge guard refused).

Still open at both customers

• Property names, new buildings and hidden buildings never refresh after the one-time import (Western Slope last re-read Sep 13). A partial fix merged Sep 26 for names and visibility.
• The lease-renewal sync has been off since Sep 12, so lease end dates go stale. 3 leases are duplicated under two id formats at Western Slope.
• No alarm watches AppFolio's refusal rate per customer; the alarms that fired today are global to the sync.
• The onboarding playbook still says Situs is "blocked, waiting for API access".

Recommendation: make the rate-limit switches and request budget part of the connect step (automatic, no human press) and make "residential only" an engine rule at import. Those two would have removed both of today's repeats.

Superseded decisions

2026-10-20 · Notice-to-vacate period was never an intake question

• The renewal "tenant is not renewing" office note cites the days of notice a tenant must give. Western Slope had none on record, so the note would have said "no notice period on record". Fede: 30 days, and "that's a bigger issue with onboarding". Fix: the company topic list above now asks every client for it; Western Slope's answer (30 days) was written to their company knowledge on 2026-10-20. No code default was built.

10 · Sources

Fede's words, 2026-09-22, session 010 (the brief for this rewrite) · mining notes from session 010: phone lines, knowledge, email and turn-on, setup and testing (session memory files, PR history 2026-09-08 to 22, and the pages below) · code on origin/main at f7783a39cd (2026-09-22): src/lib/domain/portfolio/registry/keys.ts, src/lib/domain/organizations/clara-live.ts, src/app/api/admin/companies/[id]/*, src/lib/domain/pms/side-effects/mode.ts, src/lib/domain/leasing/guest-card-reply-eligibility.ts, scripts/set-org-lead-source.ts · docs/runbooks/real-path-e2e.md · PRs #8650, #8950, #10423, #10567, #10572, #10712, #10795, #10924, #10926 (merged); #10835, #10865, #10932 (open at time of writing) · Western Slope go-live tracker · Western Slope issue list · Phone line and hand-off architecture · Gera's portfolio architecture · Western Slope knowledge gold set · Situs Group initiative hub · ~/situs-data/onboarding/ (playbook audit, UX research, question bank) · ~/.claude/propflow-vision-2026-08.txt