Propflow on any PMS: one Clara core, an adapter per system

1. Today: neutral edges, an AppFolio middle

The house has universal sockets in every room, but the wiring behind the walls only takes one brand of plug.

• ~140 shipped files import AppFolio code from outside the adapter (two recounts: 129 and 144).
• Guest-card writes and work-order create read back; work-order notes and photos don't.
• Fede's build check stops new mentions; 2,715 old ones remain.
• The check skips lambda/** and exempts src/lib/domain/pms/**.

Proves: census at f528ed1bf34, recounted in two review rounds (tab V); agents/clara/lib/email/report-apply.ts:158.

Deeper → A1 census · V review

2. The target: four layers, one direction

An operating system with drivers. Apps never talk to the printer. They print, and the driver for that printer speaks its language.

• This finishes the "ports and adapters" doctrine already in PMS_INTEGRATION.md.
• Layer 4 follows Fede's proposal. Its boundary is built (#470–#476); his step 7 split is not.
• Adapters choose API or robot per capability, with a declared fallback.
• Customers see their own PMS's name, or "property software".

Proves: Fede's Yardi plan §3 and §6; PMS_INTEGRATION.md §1–4.

Deeper → N naming · A7 drafts

3. Paths say what they need; adapters say what they can do

A recipe lists its ingredients and each kitchen lists its pantry. Compare the two and you know which dishes that kitchen can cook tonight.

• No mass rename: renaming would wrongly fence generic ones like collectionsStatus. One small PR.
• One stored binding per (building, module) → PMS connection; it must belong to the company operating the building, or reads fail closed.
• Answers are per building, so a read-only login counts.
• Clara is never handed a tool her building can't back.

Proves: pms/types.ts:20; unit-vacancy-sync.ts:120; ProspectRecordOwner already splits leasing ownership.

Deeper → A5 paths · A7 drafts

4. One write door, at the moment a write leaves us

A post room. You drop the letter in the tray (queued), the clerk sends it (accepted), and the signed receipt comes back (applied). You tell the sender only what has actually happened.

• A write moves from API to robot only after a clean refusal, never after a timeout.
• Each manifest cell says how it confirms, and by when.
• First callers: AppFolio's work-order note and photo, today's receipt gap.
• Any write can be held for a person: the hold rail learns a generic write envelope.

Proves: writer-registry.ts (three factories, :299, :373); guest-card-outbox.ts:314-318; types.ts:6224,6997,23898; work-order-writer.ts:266,289.

Deeper → A3 writes · A7 drafts

5. One sync engine, plus a live lane for the calendar

One mail room on a schedule, plus a front-desk phone for the one question that can't wait: "is 3 pm free?"

• The scheduled sync only creates residents through AppFolio (handler.ts:5617).
• Rent-roll exports use the existing door (applyEntitySync), once its AppFolio refusal becomes a capability check.
• The alarm for a building with no adapter fires, but names the wrong reason.
• AppFolio's budget keys keep their names, so its shared limit never splits.

Proves: reads audit; report-apply.ts:158; calendar/provider/ (Google and Outlook only today); Fede §3 and §7.

Deeper → A4 reads and sync

6. One id shape, tied to the data, not the login

A passport's number belongs to the person, not to the clerk who stamped it. Change clerks and the passport still works.

• A person's PMS ids stay identity claims (many allowed); ref lists live on occupancies and inquiries, not on the person.
• AppFolio moves one record type at a time, each paired with its "stop writing af" PR.
• Lookup key source:instance:kind:id: two databases, or a lead and a resident with the same id, never collide.
• Sandbox stays its own PMS type (Fede, 09-03), as one line in a single registry.

Proves: pms-pointers.ts:83-90; sync-accounts.ts:58; types.ts:3-15 (sandbox design).

Deeper → A2 data model

7. The robot: one credential owner, signed per-call grants

The building's key cabinet sits in one office. A tenant gets a signed slip for one door, for one hour, and the slip is logged.

• Fede §6 already puts Yardi's login shape in propflowai's credential rows.
• A rogue caller can't act without a grant, and the robot can't mint one: it only holds the public key. (A fully compromised robot still holds its warm sessions; grants don't cover that.)
• Each driver lists the form posts that are only reads (Yardi reads are posts); the kill switch blocks everything else.
• The robot's login choke point (withLoginBudget) refuses to log in without a budgeted one-time grant from propflowai, so every caller needs one: scheduled re-mints, the refresh routes, a mid-call 401 and scripts. A fence test finds them all.

Proves: robot lib/runtimeAuth.ts (RUNTIME_SHARED_TOKEN), accountContext.ts:131,466, readonlyLock.ts; Fede §6.

Deeper → A3 writes and robot · A7 drafts

8. Yale 25: what day one is, and what it isn't

Opening a leasing office before the phone system is installed: you take names and preferred times on paper, and call people back to confirm.

• Under Supervised the tour note is itself held, so a tour request passes two people; the confirm timer starts when the note is released.
• Also open: four conflicting facts, the questionnaire, and whether the contract is signed.
• Read 11-04: owned by JP&Co, managed by ConAm since 9-24, no AppFolio fields. Held-reply emails and the text channel still follow the owner (R 0.3a); Fede approves as a Propflow admin.
• Ids with letters would be dropped today; Yardi never uses that path.

Proves: tools-leasing.ts:10408-10420; launch brief; handle-create-work-order.ts:1265.

Deeper → R stage 0 · D decision 1

9. Tenio: our own test PMS (tenio.dev)

A flight simulator. Real cockpit, real controls, fake sky, and a button that makes an engine fail on purpose.

• Park West (the fake building) joins Propflow in prod as a TEST property under the test client company Resio Residential (Gera's go, 11-04). No phone tests.
• Staff reply in its messenger just as Clara is about to: the collision Fede sees on AppFolio.
• Login: email + password, with a switch for the second step (none, text, email, app code).
• Proposed to replace Fede's Willows proof (his D3), his call. ADR-0072's vendor mocks stay.

Proves: Gera's answers, 2026-11-03; ADR-0072's case for keeping mocks outside the app; architecture critic on testing with no sandbox.

Deeper → R stage 1

10. Roadmap: Yale, then new shapes proven on Tenio, then Yardi, then AppFolio

Open the shop with what works, build and test the new wing in a showroom, fit it to the real building when the keys arrive, and rewire the old wing last.

• Stage 0 needs decision 1, ConAm's questionnaire and config fixes, not Yardi.
• Stage 2's first login is gated by a written check that ConAm's contract and Yardi license allow automated access (tab D; this plan proposes Fede adds it to his ConAm questions, which today cover login URL, MFA, roles and concurrent logins).
• Repo rename and package move wait until a second real system works.
• Stage 3 (AppFolio moves) waits on Tenio, not Yardi: it starts once Tenio passes conformance.

Proves: both critics' critical paths, corrected for ConAm's no-email, no-scheduler facts.

Deeper → R roadmap, PR by PR

11. How we'll know it's done

The test of a universal charger is plugging in a phone it has never seen.

• Conformance suite: one test per capability, run for every adapter that claims it.
• "Live" follows the proof ladder in chapter 10; a failing daily check drops it.
• The Paths page shows "Works with Yardi" from the same data.
• A customer switching PMS keeps its history.

Proves: scripts/check-pms-literals.ts allowlist (581 files / 2,715); fact-check recounts (tab V).

Deeper → A1 census · D decisions

S1. What Propflow takes in and sends out

A shipping container. Every port loads it differently, but every ship, crane and truck only has to handle one box shape.

• "Unknown" is a real value, decided once in core. Today each feed guesses differently.
• Each adapter declares its priority scale; a lossy mapping shows on the receipt.
• Balance carries past-due and net separately. Yardi's net is stored as past due today.
• A lead is one person with interests in several buildings, as AppFolio models it.
• A new vendor field is added as optional; no other adapter changes.

Proves: grounded in today's neutral rows (pms/types.ts) and writers; hazards with file:line in A9 §1.6.

Deeper → A9 schemas and mapping tables

S2. Adding a path, and which systems can run it

A new dish on a restaurant chain's menu. Each kitchen checks its pantry: some can cook it tonight, some need one ingredient, some can't yet. The dish never belongs to the kitchen that asked for it.

• No path may name a PMS; the build check enforces it.
• Yardi's 16 "not yet" (the 42-row table at f528ed1, rerun with the eligibility script): all 8 renewal rows, 4 maintenance (incl. the emergency work order's PMS copy), 2 collections, 2 leasing.
• Emergency calls never depend on the PMS; only the emergency work order's PMS copy does.
• Paths page: "Works with / Partly / Not yet", plus what's missing.

Proves: clara-paths.ts (73 rows); elig.py (hand-derived needs table, ids checked against the file); derivations marked "inferred" in A10.

Deeper → A10 path lifecycle and eligibility matrix

A9 · Canonical schemas, inbound and outbound, with mapping tables

Draft grounded in today's neutral rows and writers at f528ed1bf34; vendor columns marked unverified where docs are paywalled. Founder questions it raised are in tab D.

1.0 What exists today, and what is AppFolio-shaped

The repo already has most of the neutral seams. They are uneven, and several neutral types still carry AppFolio's shape.

AppFolio-shaped spots inside the "neutral" types (the canonical schema removes each one):

v7 alignment: where this section's ref shape differs from A7, A7 wins: refs carry kind; instance is an id we mint (vendor names are aliases); a person's PMS ids are identity claims, not a ref list on the person.

1.1 Shared building blocks

// ── Which system, which data space ─────────────────────────────────────────
// Plan A7: replaces the 7 parallel unions. 'appfolio-sandbox' stays its own entry
// (Fede 09-03, pms/types.ts:4-18).
export type PmsSource =
  | 'appfolio' | 'appfolio-sandbox' | 'yardi' | 'onesite' | 'realpage' | 'entrata' | 'tenio';

export interface PmsRef {                 // plan A7
  source: PmsSource;
  kind: PmsRecordKind;                    // 'property' | 'unit' | 'occupancy' | 'resident' | 'lead' | 'workOrder' | …
  instance: string;                       // a data-space id WE mint per connected PMS database; the vendor's names
                                          // (AppFolio database, Yardi server+database, Tenio company) are aliases. Never a login.
  id: string;                             // ALWAYS text. Never Number()'d (Yardi "ZZTEST-LM-01" → NaN today, plan ch. 6)
  displayNumber?: string;                 // what people see ("18752-1", "M-00412"); never our ticker (Gera 10-30)
  secondary?: Record<string, string>;     // other ids the PMS needs: { serviceRequest, workOrderId, uuid, partyId, unitUid, guestCode }
  endedAt?: string;                       // ref kept as history after a PMS switch
}

// Inside one fetch the source + instance are known, so rows carry a PmsKey and the
// sync engine stamps source/instance to make the PmsRef. One place, one rule.
export type PmsKey = Pick<PmsRef, 'id' | 'displayNumber' | 'secondary'>;

// ── Raw passthrough (plan naming tab) ──────────────────────────────────────
export interface PmsDetail {
  source: PmsSource;
  schemaVersion: number;                  // the ADAPTER's own payload version, not the canonical one
  payload: Record<string, unknown>;       // verbatim vendor fields; opaque to core; PII → mirror retention rules
}

// ── An enum the PMS gave us, normalised, with its raw word kept ────────────
// Generalises PMSStatusNormalized + status_raw (status.ts). 'unknown' is a value, never a default to something else.
export interface Coded<T extends string> {
  value: T | 'unknown';
  raw: string | null;                     // verbatim vendor word; null = the PMS sent nothing
}

// ── Values ─────────────────────────────────────────────────────────────────
export type IsoDate = string;             // 'YYYY-MM-DD', a calendar day in the PROPERTY's zone
export type IsoInstant = string;          // RFC 3339 with offset; adapter converts local wall clocks using PMSListParams.timeZone
export type Cents = number;               // integer minor units (precedent: PMSPurchaseOrder.totalCents, types.ts:1162)

export interface PersonName { first: string | null; last: string | null; display: string } // display is natural order, "First Last"
export interface ContactPoint { value: string; kind: 'mobile' | 'home' | 'work' | 'other' | 'unknown'; primary: boolean }
// phones are E.164 or dropped (and the drop counted, as toGuestCard's malformedPhoneSink does today);
// emails are lowercase. An empty array = the PMS has none. Never a fabricated value.

// ── Every inbound row ──────────────────────────────────────────────────────
export interface PmsRowBase {
  key: PmsKey;
  asOf: IsoInstant;                       // when WE read it (today's asOf)
  pmsDetail?: PmsDetail;
}

// ── Three-state optional fields (the rule already used in types.ts:124-129, 240-254) ─
//   field ABSENT  = this adapter does not report it (or did not read it this tick)
//   field = null  = the PMS was asked and said nothing / none
//   field = value = the PMS said this
// Consumers render unknown as unknown ("—"), never as a zero, "no", or a guess.

1.2 Inbound: canonical rows per entity

Each entity lists the canonical type, what it replaces, the capability that backs it, and the AppFolio-shaped part it removes. Required fields are only the ones every real PMS can supply. Everything else is optional under the three-state rule.

1.2.1 Property — capability: none today (read at onboarding); NEW properties read

export interface PmsPropertyRow extends PmsRowBase {
  name: string;                               // as the PMS names it
  marketingName?: string | null;              // Yardi MarketingName
  address: { line1: string | null; line2?: string | null; city: string | null; state: string | null; postalCode: string | null; country?: string | null };
  timeZone?: string | null;                   // IANA if the PMS states one (Yardi TimeZone); else onboarding sets Property.timezone
  active?: boolean | null;
  unitCount?: number | null;
  ownerKeys?: PmsKey[];                       // ownerEntities (PMSOwnerEntityRow, types.ts:975) points the other way today
}

• Replaces: nothing. Today's property rows come from AppFolio onboarding (property_directory) and from YardiProperty (yardi/types.ts:86-103), with no neutral row between them.
• AppFolio-shaped today: Property.af.propertyId: number (data/types.ts:3719).

1.2.2 Unit and its availability — capabilities: rentRoll (shape), unitVacancy (marketing)

export interface PmsUnitRow extends PmsRowBase {
  propertyKey: PmsKey;
  unitNumber: string;                         // what a prospect says ("217"). SEPARATE from key.id even when equal (Yardi UnitCode is both)
  floorplan?: { name: string | null; bedrooms: number | null; bathrooms: number | null } | null; // AppFolio BdBa "0/1.00" parsed here, not in core
  sqft?: number | null;
  marketRentCents?: Cents | null;
  status: Coded<'occupied' | 'vacant' | 'notice' | 'future'>;   // PMSRentRollRow.occupancyStatus (types.ts:317) + unknown
  spaces?: PmsSpaceRow[];                     // NEW: bed/space level (Entrata Unit Space, RealPage beds, Yardi RoomCode (U)). Absent = not a by-the-bed PMS
}
export interface PmsSpaceRow { key: PmsKey; label: string; status: PmsUnitRow['status']; marketRentCents?: Cents | null }

export interface PmsUnitAvailabilityRow extends PmsRowBase {    // = PMSUnitVacancyRow (types.ts:359) neutralised
  unitKey: PmsKey; propertyKey: PmsKey; unitNumber: string;
  status: Coded<'vacant-unrented' | 'notice-unrented' | 'vacant-rented' | 'notice-rented'>; // 'other' becomes 'unknown'; never offerable
  advertised: Array<{ channel: 'internet' | 'website' | 'ils' | string; posted: boolean | null }> | null; // replaces postedToInternet/postedToWebsite
  rentReady?: boolean | null;
  daysVacant?: number | null;
  availableOn?: IsoDate | null;
  nextMoveIn?: IsoDate | null;
  advertisedRentCents?: Cents | null;         // never 0 for "unstated" (types.ts:384-386)
  marketingDescription?: string | null;
  program?: Coded<'pbv' | 'hcv' | 'lihtc' | 'home' | 'deed_restricted'> | null; // programSource moves to pmsDetail
}

• Replaces: the unit half of PMSRentRollRow (types.ts:303-319) and PMSUnitVacancyRow (types.ts:359-411).
• The rule that stays: absence from the availability set means "not offerable", never "occupied" (types.ts:348-353).

1.2.3 Resident and occupancy (the person and the household on a unit) — capabilities: tenantContacts, rentRoll, leaseStates

Two rows, because every PMS separates the household holding the unit from the people in it:

• AppFolio splits OccupancyId from TenantId (af-pms-adapter mapAppfolioTenantDirectoryRow, pms-adapter.ts:1865-1895).
• Yardi's Resident.Code (t0010101) is the household, and the extra people sit in OtherOccupants (yardi/types.ts:127-157).

export interface PmsOccupancyRow extends PmsRowBase {          // key = AppFolio OccupancyId, Yardi Resident.Code
  propertyKey: PmsKey;
  unitKey: PmsKey | null;                     // null only if the PMS has a household with no unit (rare; keep it)
  unitNumber: string | null;
  status: Coded<'current' | 'notice' | 'future' | 'past' | 'month_to_month'>; // + unknown (Yardi maps unknown→'current' today: wrong)
  moveInOn?: IsoDate | null;
  noticeOn?: IsoDate | null;
  moveOutOn?: IsoDate | null;
  moveOutReason?: string | null;
  residentKeys: PmsKey[];                     // who lives here (may be empty if the PMS lists only the household)
}

export interface PmsResidentRow extends PmsRowBase {            // key = AppFolio TenantId, Yardi per-person code (U)
  occupancyKey: PmsKey;
  name: PersonName;
  phones: ContactPoint[];                     // Yardi Phone[] typed; AppFolio "Type: number" list parsed in the adapter
  emails: ContactPoint[];
  role: Coded<'primary' | 'co_tenant' | 'guarantor' | 'occupant'>;  // TenantOccupancyRole (data/types.ts:20141) + occupant
  financiallyResponsible?: boolean | null;
  language?: string | null;
}

• Replaces: PMSTenantContactRow (types.ts:418-429), PMSTenantDirectoryRow (types.ts:1181-1205), and the occupancy half of PMSRentRollRow.
• AppFolio-shaped today:
  • AppFolio does not declare tenantContacts (pms-adapter.ts:310-341). It delivers residents through writers/tenant-directory-daily.ts and the occupancies writer instead.
  • The sync only creates residents through AppFolio (plan ch. 5, handler.ts:5617).
  • TenantOccupancy.appfolioTenantId (data/types.ts:20215).

1.2.4 Lease (the current term on an occupancy) — capabilities: leaseStates, leaseProvenance, leases

export interface PmsLeaseRow extends PmsRowBase {               // key = the PMS lease id where one exists, else the occupancy id
  occupancyKey: PmsKey;
  termStart: IsoDate | null;
  termEnd: IsoDate | null;                    // null + monthToMonth=true = open-ended
  monthToMonth: boolean | null;
  rentCents: Cents | null;
  recurringCharges?: Array<{ code: Coded<BalanceChargeCategory>; amountCents: Cents }> | null;
  lastSignedAt?: IsoDate | null;
  provenance?: Coded<'pms_generated' | 'manually_uploaded'> | null;   // LeaseRenewalSource (types.ts:146)
  securityDepositCents?: Cents | null;
}

• Replaces: PMSLeaseState (types.ts:434-454) and LeaseProvenance (types.ts:148-155).
• AppFolio-shaped today: moveOutReason documented as "AppFolio tickler" (:446).

1.2.5 Balance and ledger — capabilities: balances, collectionsStatus, NEW ledger

This is the deepest disagreement in kind (§1.4.5). The canonical row carries what kind of number the PMS gave, so no adapter has to turn a net balance into a past-due amount.

export interface PmsBalanceRow extends PmsRowBase {             // key = occupancy id
  occupancyKey: PmsKey;
  // At least one of the two amounts; each nullable on its own (null = the PMS did not say; NEVER 0 by default; Mira incident, types.ts:221-234)
  pastDueCents?: Cents | null;                // AppFolio rent_roll.PastDue
  netBalanceCents?: Cents | null;             // signed: negative = credit. Yardi GetResidentBalances.Balance; Buildium/Entrata ledger sum
  includesPendingCharges?: boolean | null;    // also a manifest fact; the row may override
  aging?: { bucketsDays: number[]; amountsCents: Cents[] } | null;   // AppFolio 0-30/31-60/61-90/90+ is ONE layout, not the schema
  agingUnread?: true;                         // types.ts:263-268, unchanged
  oldestOpenChargeOn?: IsoDate | null;        // Yardi OldestOpenChargeDate
  openCharges?: Array<{ key: PmsKey | null; postedOn: IsoDate | null; category: Coded<BalanceChargeCategory>; label: string | null; openCents: Cents }>;
  lastPayment?: { on: IsoDate | null; amountCents: Cents | null };   // three states, atomic pair (types.ts:236-255)
}

export interface PmsCollectionsStatusRow extends PmsRowBase {   // = PMSCollectionsAccountStatusRow (types.ts:97-138)
  occupancyKey: PmsKey;
  inCollections: boolean | null;              // null allowed now: a PMS that cannot say ≠ "not in collections"
  certifiedFundsOnly: boolean | null;         // Yardi PaymentAccepted 'CashEquivalent' looks like this (U)
  paymentsBlocked?: boolean | null;           // Yardi 'DoNotAccept' / 'OnHold' (U)
  onPaymentPlan: boolean | null;
}

export interface PmsLedgerEntryRow extends PmsRowBase {         // NEW; MITS Resident Transactions shape
  occupancyKey: PmsKey;
  kind: Coded<'charge' | 'payment' | 'credit' | 'concession' | 'adjustment' | 'reversal'>;
  chargeCode: Coded<BalanceChargeCategory>;   // raw = the PMS's GL/charge code name
  amountCents: Cents;                         // signed as the PMS signs it, normalised: charge +, payment −
  postedOn: IsoDate | null;
  dueOn?: IsoDate | null;
  openCents?: Cents | null;
  description?: string | null;
}

• Replaces: PMSBalanceRow (types.ts:218-277) and PMSCollectionsAccountStatusRow (types.ts:97-138).
• Kept: BalanceChargeCategory (data/types.ts:5345-5354).
• One change to existing behaviour: collectionsStatus booleans become nullable. Today an occupancy with no row reads "both false" (types.ts:95-96). For a PMS that has no such feed, that silently means "not in collections". Whether dunning may proceed on null is a founder call (§2.4).

1.2.6 Work order — capabilities: workOrders (read), workOrder.* (write)

// The PMS's own lifecycle, NOT PropFlow's. Core maps it to WorkOrderStatus in ONE table (§1.5 rule 3).
export type PmsWorkOrderState =
  | 'new' | 'assigned' | 'scheduled' | 'in_progress' | 'on_hold' | 'work_done' | 'closed' | 'cancelled';

export interface PmsWorkOrderRow extends PmsRowBase {
  // key.id = the id writes address (AppFolio: SR record id = WorkOrder.pmsId, data/types.ts:6978);
  // key.displayNumber = what people see (AppFolio pmsNumber "18752-1", :6989);
  // key.secondary.workOrderId = AppFolio WorkOrderId (the read-side join; pmsid-contract drift test)
  propertyKey: PmsKey;
  unitKey?: PmsKey | null;                    // null = property-level job
  unitNumber?: string | null;
  occupancyKey?: PmsKey | null;               // replaces tenantHint (types.ts:279-295)
  requester?: { name: PersonName | null; phone?: string | null; email?: string | null } | null;
  state: Coded<PmsWorkOrderState>;
  priority: Coded<'low' | 'medium' | 'high' | 'emergency'>;
  category: Coded<WorkOrderCategory>;         // 'plumbing'|'hvac'|'electrical'|'appliance'|'general' (work-order-category.ts:9)
  issueType?: string | null;                  // PMS's own sub-category verbatim (AppFolio WorkOrderIssue, Yardi SubCategory)
  title: string;
  description: string;
  permissionToEnter?: boolean | null;
  accessNotes?: string | null;
  vendorKey?: PmsKey | null;
  vendorName?: string | null;                 // a NAME. Never an id (Yardi VendorCode is put here today: yardi/pms-adapter.ts:394)
  scheduledStart?: IsoInstant | null;
  scheduledEnd?: IsoInstant | null;
  dueOn?: IsoDate | null;
  workDoneAt?: IsoInstant | null;             // when the WORK was done (AppFolio WorkDoneOn)
  closedAt?: IsoInstant | null;               // when the TICKET closed
  cancelledAt?: IsoInstant | null;
  estimatedCostCents?: Cents | null;
  actualCostCents?: Cents | null;
  intakeChannel?: Coded<'call_center' | 'online_intake' | 'portal' | 'pm_assistant' | 'staff'> | null; // PMSWorkOrderIntakeChannel
  createdAt: IsoInstant | null;               // NOT now() when unparseable (pms-adapter.ts toWorkOrderDraft fabricates it today)
  updatedAt: IsoInstant | null;               // NOT a copy of createdAt (pms-adapter.ts toWorkOrderDraft does that today)
  notes?: Array<{ key: PmsKey | null; at: IsoInstant | null; author: Coded<'tenant' | 'staff' | 'vendor' | 'system' | 'clara'>; text: string }>;
  attachmentCount?: number | null;
}

• Replaces: PMSWorkOrderDraft (types.ts:910-965). The AppFolio columns unitTurnCategory, vendorTrade and intakeChannelRaw move into pmsDetail or Coded.raw.
• AppFolio-shaped today: status and priority are emitted in PropFlow's lifecycle (:928-929); WorkOrder.af (data/types.ts:7099-7121); appfolioEnrichment (:7134).

1.2.7 Vendor — capabilities: vendors, vendor.create

export interface PmsVendorRow extends PmsRowBase {              // account-scoped; key.id = AppFolio VendorId / Yardi VendorId "V0001"
  companyName: string | null;
  contact: PersonName;                        // "Allman, John" parsed in the adapter
  phones: ContactPoint[];
  emails: ContactPoint[];
  trades: Array<Coded<WorkOrderCategory>>;    // raw = PMS trade word
  vendorType?: string | null;                 // verbatim category (AppFolio VendorType, Yardi UsualCategoryId)
  usableForWork: boolean | null;              // NEW: AppFolio DoNotUseForWorkOrder (inverted) / Yardi IsInactive (inverted)
  address?: PmsPropertyRow['address'] | null;
}

• Replaces: PMSVendorDraft (types.ts:992-1018). Its own comment asks for the inactive signal to be added "deliberately", and that is usableForWork.

1.2.8 Lead (the PMS's guest card) and its activity — capabilities: guestCards, NEW guestCardActivity

The capability keeps the vendor word guestCards. The row is named for what every PMS API calls the object, a lead (plan naming tab).

The canonical lead is person-level with per-property interests, because AppFolio's card is a person with N inquiries (types.ts:631-650), and MITS models a Prospect holding Customers with Preferences and Events. A PMS whose lead is per-property (Entrata (U), Knock) yields one row per lead, with one interest. The spine (Person + IdentityClaim) decides who the person is (record-adapter/types.ts:73-80), never the adapter.

export interface PmsLeadRow extends PmsRowBase {
  // key.id = AppFolio GuestCardId; secondary.uuid = GuestCardUuid (deep link), secondary.partyId = PartyID (messages)
  name: PersonName;
  phones: ContactPoint[];                     // may be empty
  emails: ContactPoint[];                     // may be empty (AppFolio ingest drops a card with neither: pms-adapter.ts toGuestCard)
  status: Coded<PMSStatusNormalized>;         // the card's state; for AppFolio derived from an activity feed (status.ts header)
  source: Coded<ProspectSource> | null;       // raw = PMS picklist label ("Rent.", "No Source Recorded"); matchChannel lives in core
  receivedAt: IsoInstant | null;
  assignedTo?: { pmsUserKey: PmsKey | null; name: string | null } | null;
  preferences?: {
    moveInOn?: IsoDate | null; bedrooms?: number | null; maxRentCents?: Cents | null; maxRentRaw?: string | null;
    pets?: string | null; monthlyIncomeCents?: Cents | null; creditRange?: string | null;
  };
  interests: PmsLeadInterest[];               // ≥1; one per property asked about
  convertedTo?: { occupancyKey: PmsKey | null; residentKey: PmsKey | null } | null; // AppFolio TenantId
  notesText?: string | null;                  // STAFF notes; never replayed to a prospect (Fede 09-18, types.ts:801-816)
  lastActivity?: { kind: Coded<PmsCardActivityKind>; on: IsoDate | null } | null;
}

export interface PmsLeadInterest {            // = PmsInquiry (types.ts:667-736), neutralised
  key: PmsKey | null;                         // AppFolio data-inquiry-id (was number) → text
  propertyKey: PmsKey | null;                 // null = could not resolve; never "this property" (types.ts:673-676)
  propertyName: string | null;
  unitKey?: PmsKey | null; unitNumber?: string | null;
  status: Coded<PMSStatusNormalized>;
  active: boolean;
  source: string | null;
  receivedBy?: 'system' | 'staff' | null;
  firstMessage: string | null;                // the renter's own words (never a staff note)
  messages?: Array<{ key: PmsKey; at: IsoInstant | IsoDate | null; text: string; source: string | null }>;
  createdOn: IsoDate | null;                  // was a verbatim "09/18/2026"; raw kept in pmsDetail
  lastInterestOn: IsoDate | null;
  inactivatedOn?: IsoDate | null;
  desiredMoveIn?: IsoDate | null;
  quotedRentCents?: Cents | null;             // was "$1,550.00" display string
  bedBathRaw?: string | null;
}

export interface PmsLeadActivityRow extends PmsRowBase {        // NEW; MITS Event / Entrata lead event / Yardi guest activity
  leadKey: PmsKey;
  kind: Coded<PmsCardActivityKind>;           // types.ts:862-885 + unknown
  at: IsoInstant | IsoDate | null;            // precision varies: AppFolio gives a DAY only (types.ts:892-894)
  atPrecision: 'instant' | 'day' | 'unknown';
  channel?: 'sms' | 'email' | 'call' | 'in_person' | 'web' | null;
  direction?: 'inbound' | 'outbound' | null;
  author: Coded<'prospect' | 'staff' | 'system' | 'clara'>;
  text?: string | null;                       // staff-authored text is fenced from Clara/prospects (same rule as notesText)
}

• Replaces: PMSGuestCard (types.ts:746-856), PmsInquiry / PmsInquiryMessage (:652-736), PmsCardLastActivity (:888-895), and NormalizedProspectRecord (record-adapter/types.ts).

1.2.9 Appointment (showing / tour) — capabilities: NEW appointments (read), appointment.* (write)

export interface PmsAppointmentRow extends PmsRowBase {         // key = AppFolio showingId (was number) / CRM IQ appointment id (U)
  propertyKey: PmsKey;
  unitKey?: PmsKey | null;                    // AppFolio REQUIRES one (buildingTour best-guess, guest-card-writer.ts:395-399); others may not
  leadKey?: PmsKey | null;                    // null = a calendar block not tied to a lead (busy time)
  start: IsoInstant;
  end: IsoInstant | null;                     // Knock gives only scheduledAt (realpage/client.ts:59-65)
  timeZone: string;                           // the property's; AppFolio's local "10:00 AM" strings are converted with it
  kind: Coded<'in_person' | 'virtual' | 'self_guided'>;
  status: Coded<'scheduled' | 'confirmed' | 'completed' | 'canceled' | 'no_show'>;   // CardShowing.status (guest-card-writer.ts:514) + more
  host?: { pmsUserKey: PmsKey | null; name: string | null } | null;
  createdAt?: IsoInstant | null;
}

• Replaces: CardShowing (guest-card-writer.ts:504-516) and Tour.af (data/types.ts:14063-14076).
• Plan link: calendar busy reads follow chapter 5. A PMS calendar is a CalendarProviderId, today 'outlook' | 'google' only (domain/calendar/provider/types.ts:174).

1.2.10 Application — capabilities: rentalApplications (read), application.send (write)

export interface PmsApplicationRow extends PmsRowBase {         // key = AppFolio RentalApplicationId; secondary.groupId
  propertyKey: PmsKey | null;                 // Situs rows carry no property id (types.ts:544-552): propertyName fallback stays
  propertyName?: string | null;
  unitKey?: PmsKey | null; unitNumber?: string | null;
  leadKey?: PmsKey | null;                    // AppFolio InquiryID
  groupKey?: PmsKey | null;                   // co-applicants (AppFolio RentalApplicationGroupId)
  applicant: { name: PersonName; phones: ContactPoint[]; emails: ContactPoint[] };   // was required email/phone strings
  status: Coded<'pending' | 'approved' | 'denied' | 'canceled' | 'converted'>;      // PMSStatusNormalized subset
  desiredMoveIn?: IsoDate | null;
  monthlyIncomeCents?: Cents | null;
  receivedAt: IsoInstant | null;
  decidedAt?: IsoInstant | null;
  leadSource?: Coded<ProspectSource> | null;
  applicantReportedSource?: string | null;
  completeness?: { screeningDone: boolean | null; feePaid: boolean | null; allApplicantsSubmitted: boolean | null; screenedOn: IsoDate | null };
  moveInStarted?: boolean | null;             // Fede 10-15 rule: never prepare a second lease
  pets?: string | null;
}

• Replaces: PMSRentalApplication (types.ts:531-610) and PMSApplicationCompleteness (:613-628).
• Removed: createdVia (AppFolio CreatedBy) moves to pmsDetail, and intakeChannel can be added later if a consumer needs it.

1.2.11 Renewal offer — capabilities: renewals, renewalTruth, renewal.*

Adopt the renewal adapter's types as canonical (renewal-adapter/types.ts). They are already neutral. Two changes:

export interface PmsRenewalOfferRow extends PmsRowBase {        // key = AppFolio LeaseDocumentUuid; RenewalRef → PmsRef
  occupancyKey: PmsKey;
  lifecycle: Coded<OfferLifecycle>;           // 'none'|'prepared'|'out_for_signature'|'tenant_signed'|'executed'|'cancelled'
  terms: Array<{ months: number; rentCents: Cents }>;   // months 0 = MTM unless manifest fact mtmAsFlag
  sentAt: IsoInstant | null; respondBy: IsoDate | null; signedAt: IsoDate | null;
  newTermStart: IsoDate | null; newTermEnd: IsoDate | null;
  previousRentCents: Cents | null; chosenRentCents: Cents | null;
}

• Replaces: PMSRenewal (types.ts:494-525), PmsRenewalOfferStatus and PmsRenewalTruthSnapshot (:1034-1078, which become an occupancy + offers read), and RenewalEvent / OpenOffer (renewal-adapter/types.ts:62-92).
• Change 1: RenewalRef.pmsAccount becomes PmsRef.instance.
• Change 2: PmsRenewalOfferStatus maps unknown statuses to 'pending' (types.ts:1030-1033). That is a deliberate fail-safe, and it stays as core's reading of unknown, not the adapter's.

1.2.12 Owner, purchase order, income statement

These keep their current neutral shapes, with ids moved to PmsKey: PMSOwnerEntityRow (types.ts:975), PMSPurchaseOrder (:1118, already in cents and already approvalState: 'unknown'-aware), and IncomeStatementRow (its raw becomes pmsDetail). They are not on Clara's main paths, so this draft does not reshape them.

1.3 Outbound: canonical requests and receipts

1.3.1 The envelope (the plan's write door, A7)

export interface PmsWriteRequest<C extends PMSWriteCapability, P> {
  capability: C;
  propertyId: string;                         // OUR building id: the door resolves (building, module) → adapter + connection
  module: ModuleFlag;                         // routing key (plan ch. 3); also the mode the door takes the writer factories' decision on
  target?: PmsRef;                            // the PMS record written to (absent on creates)
  idempotencyKey: string;                     // caller's (outbox intent id / saga id / note id), as today
  actor: 'clara' | 'staff' | 'system' | 'resident' | 'vendor';
  subject: ModuleSubject;                     // emergency / declared test etc. (module-mode.ts), so the door applies the ONE rule
  payload: P;
}

// WriteReceipt as in A7, plus two proposed fields:
export interface WriteReceipt<R = unknown> {
  status: 'applied' | 'accepted' | 'unconfirmed' | 'refused' | 'not_written';
  capability: PMSWriteCapability; ref?: PmsRef; marker?: string;
  evidence?: { readBackAt: string; observed: Record<string, unknown> };   // required for 'applied'
  confirmBy?: string;
  notWrittenReason?: 'preview' | 'off' | 'mode_unresolved' | 'held' | 'not_supported' | 'unproven' | 'test_property_guard' | 'test_call';
  failure?: { kind: PmsFailureKind; retryable: boolean; detail: string }; // PmsFailureKind = RENEWAL_PMS_FAILURE_KINDS, promoted
  result?: R;                                 // capability-specific (below)
  coerced?: Array<{ field: string; asked: unknown; sent: unknown }>;  // PROPOSED: lossy mappings (priority medium→"Normal")
  dropped?: string[];                         // PROPOSED: optional fields this PMS cannot carry
}

• Field contract per capability: each request field is either required (the adapter must carry it, or the door refuses with not_supported before any call) or optional (the adapter may drop it, and the receipt lists it in dropped). The manifest cell states which optional fields it honours (AdapterCapability.fields?: readonly string[], NEW). This is our version of Apideck's sparse fields and Propexo's ignore_unknown_fields, made loud.
• Writes address target: PmsRef, never a PropFlow id that the adapter re-resolves. Today CreateWorkOrderRequest.propertyId is our id (work-order-writer.ts:79), and that is how the Yardi writer ended up sending our id as PropertyCode (yardi/work-order-writer.ts:60).
• Creates name their parent by ref: payload.propertyRef, payload.unitRef, and so on.

1.3.2 Per capability (the A7 list)

1.3.3 Write verbs the existing writers already need (NEW, same resource.verb style)

PMSWriter (writer.ts:741-847) and today's paths use these verbs, and A7's list omits them. Each is a capability cell in every manifest (default unsupported).

They are also NEW reads: appointments, guestCardActivity, ledger, properties.

1.4 Mapping tables

Legend:

• ⚡ = the systems disagree in kind (type, scale, semantics, id space), not just in name. The "absorbed by" column says how the canonical schema takes it in.
• AppFolio: report column (Reports API) unless marked robot.
• Yardi: SIPP = yardi/types.ts (doc-derived, never live). robot = CRM IQ / Voyager screens, phase 1, all (U) until Fede's recon.
• Others: from the research file. Field-level detail is mostly (U) (partner portals).

1.4.1 Work order

1.4.2 Lead (guest card)

1.4.3 Resident and occupancy

1.4.4 Unit and availability

1.4.5 Balance

1.4.6 Appointment (showing)

1.4.7 Vendor (short)

1.4.8 What Tenio should deliberately do differently

Tenio exists to break assumptions AppFolio lets us keep (plan ch. 9). Each item below is a chaos-panel switch or a fixed design choice, and each has a conformance test.

1. Text ids with letters and prefixes everywhere (wo_7Hq2, lead_…), plus a human number different from the id that arrives after the create (accepted → number later). This tests PmsRef.id: string, displayNumber, and Clara's "the number follows" line.
2. Priority on a 5-level scale (P1…P5) and 8 WO states, plus one undocumented state the panel can switch on. This tests Coded + unknown and the rule that unknown never moves our lifecycle.
3. Lead per (person, property), the opposite of AppFolio's person card, with roommates as separate leads linked by a household id. This tests interests[] and spine-side merging.
4. Ledger only, no balance field. Past due must be computed from dueOn, and credits are negative. This tests the balance split.
5. One by-the-bed building (spaces). This tests spaces and showing a "unit" that is a bed.
6. UTC instants with offsets in the API, local wall-clock strings on the staff screens. This tests that the robot path and the API path normalise to the same IsoInstant.
7. Notes are append-only with their own ids, confirmed late. One switch makes notes replace a single field, like Yardi TechnicianNotes. This tests noteSemantics and read-then-append.
8. Required email on lead create (like Knock) and an optional unit on showings. This tests per-capability required-field contracts.
9. Money in cents, one tenant priced in a second currency. This tests that Cents doesn't assume USD in a display path (I: low priority).
10. A field rename between two "releases" (screen layout change switch). This tests that pmsDetail absorbs the rename and that the recipe check flips the connection cell to failing.

1.5 Rules

Rule 1: core vs pmsDetail. A field goes in the canonical row only if both of these hold:

• (a) a core consumer reads it to decide or say something, and
• (b) its meaning can be stated without naming a vendor.

Everything else the adapter can see goes in pmsDetail.payload, verbatim. That includes vendor ids we don't use, display strings, picklist labels, audit columns, UserDefinedField1-7, and AppFolio's UnitTurnCategory. pmsDetail is opaque to core: no core code may read a key out of it, which the build check can fence (the same fence as check-pms-literals). The adapter may render it (for example, a staff "details from your property software" panel). It is PII and follows the mirror's retention. This is the rule types.ts:1012-1017 already states, made general, with the same precedents as PmsRecord.custom_data and IncomeStatementRow.raw.

Rule 2: no vendor-named field in a canonical type. No appfolio*, no af, no yardiCode. Vendor ids live in PmsRef.secondary under neutral keys (serviceRequest, uuid, partyId, unitUid). The plan's R 3.3 renames the existing ones.

Rule 3: enums are mapped in the adapter, by an explicit table, and unknown stays unknown.

• Every vendor enum becomes Coded<T> through a table in integrations/<pms>/map/<enum>.ts, never by substring sniffing. AppFolio's rent-roll status does sniff today (pms-adapter.ts:1897-1907) and should move to a table.
• An unmatched value becomes { value: 'unknown', raw } and is recorded in the unmapped-value ledger, which already exists for AppFolio WO statuses (writers/guards.ts:336-338, isKnownAfStatus).
• No adapter may pick a "safe-looking" default. Today's defaults to dispatched, pending_dispatch, medium, low, occupied, vacant and current (§1.6) each become unknown.
• What unknown means for a decision is core's call, in one place per enum. Examples: a WO state unknown keeps our current status and flags it; a renewal offer unknown reads as pending (types.ts:1030-1033); a vacancy unknown is not offerable (types.ts:332-335). One table per enum means one place to read the fail-safe.
• Mapping into a vendor enum on writes uses the same table backwards. A lossy write is reported in coerced.

Rule 4: values are normalised at the adapter boundary. The adapter normalises:

• dates to IsoDate/IsoInstant, using the property's zone (PMSListParams.timeZone);
• money to Cents;
• phones to E.164;
• emails to lower case;
• names to PersonName.

An unparseable value becomes null, with the raw value in pmsDetail. Never now(), never 0, never '' for "unknown". The Mira $0 incident is types.ts:221-234, and toWorkOrderDraft's now() fallback breaks this rule today.

Rule 5: absence has three states (§1.1). Every optional field documents what absent / null / value mean, as lastPaymentDate does (types.ts:118-129).

Rule 6: schema versioning.

• Canonical rows are TypeScript types in one repo. Additive changes (a new optional field, a new enum member) need no version bump, because consumers already handle unknown and absent. A breaking change (renaming or retyping a field, or making one required) creates a new type (PmsWorkOrderRowV2) with a dual-read window, and the conformance suite pins which version each adapter emits.
• Persisted shapes carry an explicit schemaVersion: pmsDetail (per adapter), the mirror rows, receipts, and the robot's route contract. The robot is a separate deploy, so its request/response contract is versioned per route (/v1/yardi/guest-cards), and propflowai refuses a response whose version it doesn't know (refused, failure.kind: 'upstream_error').
• Capability vocabulary changes are additive only. A capability is never renamed in place (plan: "Today's 21 names stay"). Retiring one (the vestigial tenants, types.ts:29) is a deletion PR that also touches realpage/pms-adapter.ts:53.

Rule 7: adding a new PMS field without breaking others.

1. Land it in that adapter's pmsDetail first. This touches no core type and no other adapter.
2. When a core consumer needs it, promote it: add an optional canonical field with its three states documented, named in our vocabulary. Never make a new field required on an existing row, because that would force every adapter (types.ts:695-699, 830-836 already follow this "optional so every mapper keeps compiling" posture).
3. Adapters that have the field fill it. The others stay absent, and consumers degrade.
4. If it is a fact about the whole capability (for example "balance includes pending charges", "notes replace", "unit required on showings", or "MTM is a flag"), it goes in the manifest's capability facts (AdapterCapability, like RenewalAdapterCapabilities, renewal-adapter/types.ts:138-148), not on every row.
5. If it creates a new ability (a new verb), it is a new capability (§2.1), not a field.
6. Tenio adds the field too, ideally with a twist, so the conformance test has a second implementation.

Rule 8: writes carry refs, not our ids, and never send a field the PMS will misread. For example, PropertyCode = our propertyId. The door validates that every PmsRef in a request has the connection's source and instance.

1.6 Hazards found in today's mappings

These are the evidence behind the rules. Each one is a concrete bug or trap a builder would otherwise copy into the next adapter.

A10 · Path lifecycle and eligibility per PMS

Required/optional needs per path are derived from the code and marked inferred where so. Counts are reproducible with the eligibility script.

2.1 Lifecycle for adding a new path

The same lifecycle applies whether a path comes from our roadmap or from one customer on one PMS. A request from a Yardi customer produces a Yardi-agnostic path that happens to light up on Yardi first.

The rule against hard-wiring. A path is never written against the PMS whose customer asked for it.

• No PMS literal may appear in clara-paths.ts, in a path's door, or in its pmsNeeds. Extend scripts/check-pms-literals.ts to fence those files (it already gates literals, and plan R 1.15 widens it).
• The path's behaviour reads capabilities through the door and the registry, never pmsSource === 'yardi'.
• The asking customer's adapter is just the first adapter, after Tenio, to fill the cell.
• If the vendor feature has no neutral meaning at all, it does not become a path. It stays a staff tool behind the adapter (the research's "passthrough only for onboarding/admin" rule).

Worked example A: existing capability, partial elsewhere. ConAm (Yardi) asks: "when a prospect says they leased elsewhere, mark the lead lost with the reason in CRM IQ."

• New path leasing.mark_lead_lost, pmsNeeds.required = [guestCard.update(status)].
• guestCard.update already exists. Its status change gains the value lost + reason (an additive enum value, Rule 6).
• Tenio implements lost with a reason code first.
• AppFolio's manifest says guestCard.update.status ∈ {inactive} (it only has markInactive, guest-card-writer.ts:572-578), so on AppFolio the path is partial: the lead lands Inactive plus a note with the reason, and the receipt lists coerced: status lost→inactive.
• Yardi goes live when its CRM IQ recipe passes.
• No code says "Yardi".

Worked example B: a capability nobody has. A customer asks Clara to post a lockout fee to the resident's ledger.

• Add ledger.postCharge (NEW write; request {occupancyRef, chargeCode, amountCents, postedOn, description}; result {entryRef}). All adapters are unsupported.
• Tenio builds it at stage 3 (money).
• The path shows "Not yet with AppFolio / Yardi" until each adapter proves it.
• Whether Clara may post charges at all is a product and money question: founder call.

2.2 Eligibility matrix today

How it is computed (script kept at scratchpad/elig/elig.py, so the counts are reproducible):

• ✔ supported = all required and all optional capabilities present.
• ◐ partial = all required present, some optional missing.
• ✖ unsupported = a required capability is missing.
• — not needed.

Manifests assumed:

• AppFolio (prod). Declared reads (pms-adapter.ts:310-341), plus residents through the tenant directory, plus the writers it implements:

  • guest-card writer, all 12 verbs (integrations/appfolio/guest-card-writer.ts:621-1469);
  • PMSWriter renewal, move-out, unit and listing verbs (integrations/appfolio/pms-writer.ts:157-918);
  • the WO writer;
  • createVendorL4;
  • the inbox text door.

  No appointments busy read (Fede D3 route is dark) and no ledger (open charges only). Per-connection exceptions are not modelled; for example, Situs writes are blocked by our readonly write policy (memory note 10-28, not re-verified here). That is exactly what the connection layer is for.

• Yardi phase 1 = Fede's rows 1-10 on the robot: guestCards, guestCardActivity, guestCard.create, guestCard.note, appointments, appointment.create/update/cancel, rentalApplications, unitVacancy, rentRoll + leaseStates + balances (nightly), tenantContacts (nightly). All of it is planned and none of it is live: recon is all todo, and today's prod Yardi read client and writer are null (pms/registry.ts:395-398). So the honest live count for Yardi today is 0. The column shows phase-1 design eligibility.

• Tenio = plan build order. T1 leasing (leads, showings, calendar, applications incl. application.send, units). T2 maintenance (WO read/write, vendors, plus residents and lease states (I)). T3 money (balances, ledger, collections flags). T4 renewals. T5 breadth (lease, move-out, unit writes, listing, portal, messenger, POs). The cell shows the first stage at which the path reaches that status.

• Generic API PMS = an assumed Buildium/Rent Manager/Entrata-class REST PMS (I/U): leads R/W, applications R, units, residents, leases, ledger+balances, WO R/W without attach, vendors R/W. No appointments, application.send, renewal e-sign, collections flags, lease drafting, move-out, listing publish, portal or messenger.

pmsNeeds below are my derivation from code (I). Where the plan already states one (Fig. 3: inbound lead, collections), it matches.

Leasing (leasing.prospects)

On AppFolio the three tour paths are ◐ only because no PMS calendar busy read exists. Google/Outlook carry them today.

Renewals (leasing.renewals)

Yardi renewals are Fede's row 12, phase 2 (SIPP ItfLeaseRenewal, read only). Plan R 0.5 guards change_renewal_term meanwhile.

Maintenance (maintenance) + emergency WO

• † AppFolio WO note and photo writes discard the robot's "couldn't confirm" (plan ch. 1, citing integrations/appfolio/work-order-writer.ts:266,289). Eligible, but receipts are unconfirmed until R 1.2 lands.
• ‡ Emergency is never gated by a PMS capability. On a ✖ building the work order is kept in Propflow, the team gets it as a note, and no PMS number is promised. The on-call chain, relay call and team alert are PMS-independent paths and always go (ADR-0149; module-mode.ts header). Today, though, pmsManaged: Boolean(prop.pmsSource) promises a number whenever any PMS is set (handle-create-work-order.ts:1266). That is plan R 0.4.

Collections, resident services, owner reports, company

Headline counts (42 PMS-touching paths)

Yardi's 16 ✖:

• all 8 renewal rows in the 42-row needs table (pinned to f528ed1; clara-paths.ts has gained ids since, and R 1.7's pmsNeeds PR recounts from main);
• 4 maintenance (file_work_order, wo_created_text, turnover_writes, emergency.work_order);
• 2 collections (reminder, owner_escalation);
• 2 leasing (new_lease_paperwork, publish_listing).

Set aside by Gera's 11-04 answer (robot only, no Yardi API; tab D answer 3). For the record: Fede's phase 2 (SIPP ItfServiceRequests, ItfLeaseRenewal) would have moved the 4 maintenance ✖ to ✔ and the renewal reads to "required renewals present". Prepare and change-term stay ✖ until a renewal write exists.

PMS-independent paths (31): no pmsNeeds, same on every PMS

• Leasing: after_tour_checkin (its notes land via guest_card_write), self_guided, staff_asked_text, rollout.
• Renewals: rollout.
• Maintenance: appointment_reminders, resident_relay, vendor_chase, rollout.
• Collections: rollout.
• Resident: key_pickup. It is labelled "property software" by mistake (plan A5 2a) and should be relabelled.
• Team notices: renewal_notes, leasing_notes, resident_notes, decision_requests, routine_forwards, tour_notices, text_leasing_agent, general_notes, pm_action_reminders, renewal_review_ask, caller_note, test_notice, test_reply.
• Emergency: oncall_chain, relay_call, team_alert. These must stay PMS-independent.
• Company: unknown_sender, mass_sends, login_codes, transfer_to_person.

Team notices triggered by a PMS-gated path (renewal notes, "lease executed") inherit that path's eligibility, because no trigger means no note. They need no needs of their own.

2.3 How the Paths page and onboarding show it

Paths page (customer page tab, clara-paths.ts):

• New column per building: "Works with <their PMS>", with the brand from pmsBrandForProperty (src/lib/domain/pms/display.ts), else "property software". Words from the plan's naming tab:
  • Works with Yardi (✔).
  • Partly (◐). The (i) says what degrades in one plain sentence per missing optional, for example "Tours are confirmed from your Google calendar; Yardi's calendar is not read yet."
  • Not yet (✖). The (i) names the missing ability in plain words ("Clara can't file work orders in Yardi yet; she keeps them in Propflow and emails the team").
  • No property software needed (—).
• Where routing splits a building by module (leasing on one PMS, back office on another, plan ch. 3), the column shows the adapter that serves that path's module.
• The (i) (metadata behind it, UI taste rule) lists each need with its connection status (live / being proven / failing since <date>), transport (API / robot), and freshness ("updated nightly").
• Enforcement:
  • A ✖ path cannot be switched above Off at that building. The mode writer refuses, and the row is grayed with the reason. This is the same mechanism as readsOwnMode gray-out (clara-paths.ts:130-135). It is consistent with "Clara is never handed a tool her building can't back" (plan ch. 3): the per-turn tool strip (agents/clara/lib/agent/capabilities/tool-registry.ts:20-23) uses the same computation.
  • A ◐ path can be on.
  • Locked emergency and caller-note paths are never grayed by PMS. They show "Works (property software optional)".
• Turning a path on at a real property stays a founder call. The column informs that decision and never flips anything.
• CLI twin (standing rule): pms paths --building <id> prints the same matrix from the same function. That function is also what the conformance dashboard and the daily check use.

Onboarding (customer side):

• Only go-live blockers the customer can fix (standing rule: customer sees only go-live blockers). A required capability that is failing or unproven because of their connection becomes a blocker in their words. Examples: "Your Yardi user needs the CRM IQ agent role"; "We couldn't sign in to AppFolio: reconnect".
• A capability that is ✖ because we haven't built it for their PMS is never customer homework. It shows on the staff go-live card ("Leasing: 14 paths work with Yardi; 2 not yet: new-lease paperwork, listing publish") and in the founders' turn-on decision.
• Everything else is pre-filled, with no confirm buttons.
• Staff go-live card (derivePmsRow, plan R 0.2): per module, counts of ✔/◐/✖ for that building and the list of ✖ with reasons. "Leasing-only, no PMS needed" is shown when every enabled path is ✔ or — without a connection (Yale day one).

Storage: pmsSupport is derived, never stored as truth. It comes from the manifest (code), plus connection capability rows (stored per pmsConnection), plus routing. A cached snapshot for the page is fine. A stored "eligible" flag would split the truth.

2.4 Calls this draft could not make (v9: items 1–4 answered by Gera 11-04, tab D answer 4; item 5 deferred in tab D)

1. Collections on collectionsStatus = null. The plan (Fig. 3) makes collectionsStatus required, but client.ts:441-456 (listCollectionsAccountStatuses doc) says callers proceed without it. The draft follows the plan, which blocks Yardi collections. Answered (D4): no collections text without a status; the safe branch holds it. Yardi's PaymentAccepted might back it once we have the API (U).
2. Past due vs net balance. May collections and resident balance answers use a net balance (Yardi) when no past-due figure exists? The wording differs ("you owe $X" vs "$X is past due"). Answered (D4): past-due only, never net; with a net-only balance the past-due wording is refused.
3. renewals.mtm_warning requires renewals (I) so we never warn a resident who renewed off-platform. Answered (D4): no month-to-month warning without renewal data.
4. Can a ◐ path be on by default at go-live? Answered (D4): no. "Partly" paths are off by default at go-live.
5. ledger.postCharge and any new money-moving write need a product decision, not just a capability. Deferred (tab D): not needed until the money stage.

2.5 Suggested slicing (vertical, ≤300 lines each, all off origin/main)

1. PmsKey/PmsDetail/Coded types plus the PmsWorkOrderRow mapping for the Yardi adapter only. This fixes H1, H2, H5, H8 and H10 (Yardi side), behind the existing mock. Proof: mock tests.
2. pmsNeeds on the 42 rows plus pmsSupport computation plus the CLI twin, read-only. Proof: snapshot equals this document's matrix.
3. Paths page column (Works with / Partly / Not yet) from step 2's function.
4. Balance split (pastDueCents / netBalanceCents) and Yardi H3, ahead of any Yardi collections.
5. Tenio stage-1 conformance tests for guestCards, guestCard.create/note, appointments, appointment.*.

Each is one concern. Steps 2 and 3 are the thinnest end-to-end slice of Part 2.

D · Decisions (v10): answered, gated, settled

Fede's Yardi page is a proposal pending his review. On it, the calendar ("Yardi's property calendar is the building's calendar, read and written") and the 5 Oct instruction to build for N vendors are decided, and the robot's core boundary is built (#470–#476 (six PRs; #475 was never used)). This page follows the rest as proposals and doesn't reopen them.

Founder answers (Gera, 2026-11-04)

Gates (owned, dated, chased)

Open calls for Fede, each with a default: Each is due with the ConAm facts on Fri 11-06; silence means the default. (1) Is he Yale's week-one approver (15-minute target in office hours, paged first when missed)? Default if he declines: Gera is primary and Smith pages Gera. (2) Does he say yes to his own §9 per-account gate, which R 1.10s builds? Default: yes, since it is his proposal; a no moves 1.19. (3) Will he add the written-access question (below) to his ConAm list? Default: Propflow sends it to ConAm on his behalf; R 2.0 waits for the answer either way. (4) May Yale go live before ConAm signs? The plan's default is no. That is this plan's proposal, not an earlier ruling: on 5 Oct Fede only parked the questionnaire, and the launch brief's "send once the contract is signed" is a proposal awaiting his review. Until he says otherwise, go-live waits for the signature. If a gate slips, go-live slips. Gera or Fede makes the go/no-go from R 0.9b's receipts, on a stated day:

How days are counted: ConAm's steps (answers, routing leads) count ConAm business days, which skip Veterans Day, Wed 11-11. Propflow's steps (the Yale check, the go/no-go) count Propflow business days, which include it. The TEST-pair dry run (R 0.9a) needs no contract: it runs Mon 11-09, or the business day after its last code blocker merges if later, and the go/no-go moves with it.

Already settled (stated so nobody re-asks)

N · Naming options: every new word, three choices, one pick

v3: Capability names stay; the receipt gains queued; sandbox stays a type. v2: the robot keeps its name for now, ids key on the data space, and the receipt gains accepted. Only internal names here, so none of this is a founder call. Words already taken in our world, so avoid them for new layers: driver, worker (fleet roles), agent (Clara), connector (propflow-ingest), harness (voice/bench), readiness (onboarding answers), coverage (sync report), writer (inbound sync in domain/pms/writers/), and "capability" in customer copy (it means three things in code already).

R · Roadmap, PR by PR (v10)

Each part branches off origin/main, works on its own, and opens in parallel. Sizes: S ≤150 lines, M 150–300, L = several PRs of ≤300, each split vertically. risky marks a prod write or a live-auth change, named to Gera before it flips. Blocks lists what each row waits on. Proof is the acceptance test the PR must show; the page doesn't pre-assert how the code will look. Tenio rows run in the new tenio repo.

V · Review: rounds of three fresh critics, and what each version changed

Three agents with fresh context each read v1 and the code independently: one for architecture, one for the roadmap and decisions, one fact-checking against the code at f528ed1bf34. None of them saw the others' notes or a view from the author.

Round 10 (on v10, the last scored round): 7.1 · 7.0 · 7.9 → average 7.3. The loop ends here (Gera's rule: ten rounds, then keep the latest)

Every round-10 finding below is applied in this published version. These fixes were not re-scored.

Round 9 (on v9): 7.0 · 7.2 · 7.6 → average 7.3

Round 8 (on v8): 6.7 · 6.5 · 6.4 → average 6.5

Round 7 (on v7): 6.5 · 7.0 · 6.8 → average 6.8

Round 6 (on v6): 7.0 · 7.0 · 6.5 → average 6.8

Round 5 (on v5): 6.6 · 6.5 · 7.0 → average 6.7 (this round's critics were told that details a PR's stated proof would catch are not material)

Round 4 (on v4): 6.0 · 6.0 · 7.0 → average 6.3

Round 3 (on v3): 6.5 · 6.5 · 6.5 → average 6.5

Round 2 (on v2): 6.0 · 6.0 · 6.5 → average 6.2

Round 1 (on v1): 6 · 4 · 6 → average 5.3 (R numbers in this table are v2's)

Findings and what v2 did

Fact-check table (v1 claims)

A1 · Census: where AppFolio lives

Supporting audit, unchanged from v1. Where the fact-check in V corrects a claim below, V wins. File:line citations are at f528ed1bf34.

Regex census over 26,244 tracked files at f528ed1bf34. Comment versus code is a per-line heuristic, and customer-visible lines are candidates. The full CSVs are on the mini.

count in files.csv = appfolio + af_ident + l4 (the "AppFolio family"). Files with zero AppFolio-family hits but some other-PMS hit are bucket OTHER-PMS-ONLY.

3. Files and references per bucket (AppFolio family)

Bucket rules, first match wins: .md/.mdx/.txt -> DOCS; __tests__/__snapshots__/fixtures anywhere, *.test.*/*.spec.*/*.drift.*/.snap, or top-level e2e//evals//tests/ -> TESTS (so src/lib/domain/evals/, src/lib/evals/ and src/app/api/test/ count as shipped code); src/lib/integrations/{appfolio,appfolio-api,appfolio-browser-agent,yardi,realpage,_mock-pms}/ and mock-pms-service/ -> ADAPTER-LEGIT; lambda/ infra/ .github/ config/ vercel.json turbo.json .env* -> INFRA; scripts/ bin/ -> SCRIPTS (an added bucket: ops tooling, not shipped core); every hit in a comment -> DOCS/COMMENTS-ONLY; at least half the code hits are display strings in a UI/prompt/message path -> CUSTOMER-VISIBLE STRING; everything else -> CORE-LEAK. src/lib/domain/pms* is deliberately CORE-LEAK, with a domain_pms_candidate flag for appfolio-named files there.

CORE-LEAK + CUSTOMER-VISIBLE together: 773 files, 13,342 refs, 6,658 in code. Of those files, 36 have AppFolio/af/l4 in their own filename (move-whole candidates); the rest need surgery.

domain_pms_candidate (appfolio-named, non-test, under src/lib/domain/pms or pms-mirror): 20 files, 326 refs: pms-mirror/adapters/appfolio-text-start.ts (38), pms-mirror/adapters/appfolio-source.ts (37), pms-mirror/adapters/appfolio-inbox.ts (34), pms-mirror/adapters/appfolio-tenant-text-start.ts (23), pms/side-effects/appfolio-adapter.ts (22), pms-mirror/adapters/appfolio-text-door.ts (21), pms/appfolio-web-database.ts (19), pms/appfolio-operational-sender.ts (17), pms/print-order/appfolio-executor.ts (16), pms/pm-action-link-appfolio.ts (16), pms/print-order/new-lease-appfolio-executor.ts (16), pms-mirror/adapters/appfolio-media.ts (14), pms-mirror/adapters/appfolio-email.ts (14), pms/print-order/appfolio-history.ts (11), pms/side-effects/appfolio-note-sentence.ts (8), pms/inbox/appfolio-inbox.ts (8), pms/demo-appfolio-access.ts (4), pms-mirror/adapters/appfolio-inquiry-parties.ts (3), pms/tour-card/appfolio.ts (3), pms/legacy-af-inquiry.ts (2)

4. Per top-level area (AppFolio-family refs; files in parentheses)

Rollup by top-level directory

Other-PMS mentions by area

Top 15 by code refs (comments excluded), CORE-LEAK only:

• src/lib/tools/appfolio.ts: 572 code / 631 total
• src/lib/maintenance/eval/checkpoints.ts: 134 code / 214 total
• src/app/api/onboarding/pms/appfolio/import/route.ts: 118 code / 204 total
• src/app/(workspace)/settings/_components/OrganizationSettingsShell.tsx: 94 code / 110 total
• src/app/(workspace)/settings/_components/OrganizationSettings.tsx: 93 code / 105 total
• src/components/feature/admin-dev/pipeline-lab/_shared/WorkOrdersPanel.tsx: 80 code / 95 total
• src/lib/domain/dashboard/chat/tools.ts: 71 code / 92 total
• src/lib/tools/types.ts: 67 code / 125 total
• src/lib/domain/evals/fake-detector/verifiers.ts: 66 code / 104 total
• src/lib/data/types.ts: 62 code / 554 total
• src/lib/tools/tool-modules.ts: 61 code / 70 total
• src/lib/tools/role-matrix.ts: 61 code / 63 total
• src/app/api/admin/dev/tools/run/route.ts: 54 code / 103 total
• src/lib/domain/pms/registry.ts: 53 code / 92 total
• src/lib/integrations/email/webhook-processors.ts: 48 code / 59 total

A2 · Data model and storage

Supporting audit, unchanged from v1. Where the fact-check in V corrects a claim below, V wins. File:line citations are at f528ed1bf34.

Where AppFolio's concepts are built into our own records, ranked by what breaks Yardi first, with the full inventory and a safe migration order.

Category: a = already neutral; b = AppFolio-named but generic (rename); c1 = AppFolio-only, correctly named, wrong place (MOVE into adapter, no rename); c2 = AppFolio-shaped concept leaking into core logic (needs a neutral concept). Risk: code = code-only; attr = touches stored attributes (dual-write/backfill, no key change); key = touches a Dynamo key / stored enum segment.