Onboarding & Settings: one home for every answer
A proposal for Gera and Fede to review before more work is driven: how company policies get stored, asked, pre-filled and shown.
2026-10-05 · follows the Oct 5 Gera + Fede meeting · UPDATED after Gera's review: decisions settled, core list researched · nothing here is built beyond what each chapter says is in progress
The verdict, in plain English
Today the same policy can be written down twice, once as a form field and once as a free-text note, and Clara reads both, so they can disagree.
Fix: 53 researched core topics in 10 areas, each with exactly one home (a structured answer plus an optional note). 30 carry a "Required" badge. Everything else goes in a separate "Custom policies" list.
Onboarding and Settings become two doors into the same answers. AppFolio, old questionnaires and the email we already receive only fill blanks, always showing where each value came from, with full history behind a "View history" menu.
Gera has settled five of the six earlier questions (chapters 4 and 6). What is still open is the expanded list itself and what "Required" means (chapter 10). Pets ships first as one small end-to-end slice.
1. The problem: the same answer lives in two places
Like a fridge with two shopping lists on it: one says milk, the other says no milk, and whoever shops reads both.
- Structured settings and free-form knowledge overlap on the same topics.
- When they disagree, Clara can quote either one.
- AppFolio and Gmail will soon pour in more answers automatically.
- Those answers need predictable buckets that logic can use.
- What genuinely doesn't fit must not be forced into one.
Proves: the Knowledge & policies page as built today: four pet charges at the top, free-form company knowledge below it.
2. 80/20: core vs custom, now researched
Like a rental application: printed boxes for what everyone asks, and one blank "anything else?" area at the end.
- Researched: public lease templates, leasing FAQs, and our own past questionnaires.
- Core grows from about 20 topics to 53, across 10 areas.
- 30 carry a "Required" badge; the rest carry no label at all.
- All six questions asked today are placed; building exceptions become overrides.
- Custom policies stay a separate titled list, never mixed in.
Proves: Gera's review asked for a researched list; sources are in the appendix.
3. One home per topic
Like a mailbox per apartment: every letter for 4B goes in 4B's box, never a second box down the hall.
- Every core topic has exactly one slot.
- Free-form text can never create a second "Pets".
- Anything about a core topic attaches to that topic's details note.
- Slot = structured part for logic, plus optional note for nuance.
- A building can override the company, one topic at a time.
Proves: Fede's Sept 14 ruling that a conflicting building policy always wins, now per topic.
4. Answer types, without a pile of options
Like a light switch and a dimmer: two simple controls beat one dial with forty labelled positions.
- Model the dimension, not more values in one list.
- Anyone can add a new option through "Other…".
- A fast AI check (Claude Haiku) compares it with existing options.
- Similar: "This looks like X. Add anyway?" Confirm, and it's added.
- Unique: added straight away.
Proves: the smoking example from Oct 5, and Gera's ruling in his review on who adds options.
Deeper → Appendix: answer type per topic
5. One store, two doors: Onboarding and Settings
Like a house with a front door and a side door: two ways in, the same rooms inside.
- Onboarding and Settings read and write the same slots.
- Onboarding is a guided view, not a separate copy.
- Already answered in Settings? Onboarding shows it pre-filled.
- Settings are never greyed out or locked by onboarding.
- After go-live, onboarding moves to the Inbox, done but clickable.
Proves: Gera, Oct 5: "I don't want to gray out the settings."
6. Pre-fill from what we already know
Like a pencil draft on a form: it fills the blanks, says where it came from, and never writes over ink.
- Fill only empty slots; never overwrite a customer or staff answer.
- Newest-dated source wins; duplicate notes fold in automatically, with history.
- Each topic's "⋯" menu, "View history": every version, source and date.
- Pre-fill already reads the email we receive, from any provider.
- Gera is starting Google's review for reading Gmail directly.
Proves: Gera's review rulings on Situs, vouchers, Gmail and duplicate notes; the hub already shows Western Slope's answers.
Deeper → Appendix: related evidence pages
7. Settings clean-up
Like a light-switch label: "Kitchen" is enough; the wiring diagram belongs inside the panel.
- Drop the company "General" tab (in progress).
- Replace yellow "Not set anywhere" with muted "Not set" and an open dot.
- Rows show title and value; long descriptions move behind an info icon.
- Calls & messages has the longest rows, the worst offender.
- Show only the current level's settings; no one-to-one mirroring.
Proves: Gera's settings walkthrough, Oct 5 meeting.
8. The Inbox (being built now)
Like a to-do tray on a desk: new things land on top, finished ones stay visible but stamped done.
- Inbox icon in the top bar, right of Clara Insight, with a badge.
- Onboarding is listed first.
- "Set up <Module>" appears when a module enters its setting-up step.
- Also: open questions, items to review, documents.
- Sidebar slot shows only the top open item, e.g. onboarding.
Proves: the Inbox build now in progress, per the Oct 5 meeting.
9. Rollout order: thin slices, Pets first
Like renovating one room fully before starting the next, so the house stays livable the whole time.
- Pets first: core pet fields, one slot, read by Clara and hub.
- The unauthorized pet fee moves to custom policies.
- Then the rest of the core list, area by area.
- Then custom policies and the moderated "Other…" choice.
- Honest note: each merge takes about 2 hours right now.
Proves: current merge times (queue plus re-queues); speeding that up is a separate track.
10. Still open
Like a builder's punch list before pouring concrete: cheap to change now, expensive once it sets.
- Settled in Gera's review: custom options, Situs, vouchers, Gmail, history.
- Those rulings now live in chapters 4 and 6.
- Pets can start now; it is core under any answer.
Proves: what remains after Gera's review of the first draft.
A1 · Appendix — full record
The tables behind the chapters. Example values are illustrative, not any customer's data.
The proposed core list: 53 topics, 30 Required
Every topic has one slot: the structured answer, an optional details note for Clara, and a per-building override. ★ = one of the six questions already asked today. Example values are illustrative. Required = 27 always, plus the 3 pet charges when pets are allowed. No badge means no label: never "optional".
| Area | Topic | Answer type | Example | Badge |
|---|---|---|---|---|
| Applying | Application fee | money | $45 | Required |
| Applying | Application documents ★ | multi-select + note | photo ID, two recent pay stubs | Required |
| Applying | Income requirement | single choice (multiple of rent) | 3 times the rent | Required |
| Applying | Screening criteria ★ | multi-select (credit, rental history, evictions, criminal) + thresholds | credit and rental history, no evictions in 3 years | Required |
| Applying | Application decision time | single choice | 1 to 2 business days | Required |
| Applying | Housing vouchers | yes / no + note | Yes | Required |
| Applying | Co-signers & guarantors | yes / no + note | Yes | |
| Applying | Portable screening reports | yes / no | No | |
| Applying | Occupancy limit | number (people per bedroom) | 2 per bedroom | |
| Applying | Holding a unit | composite: holding deposit $ + days held | $200, 3 days | |
| Money | Security deposit | composite: amount type + amount + refundable + options | 1 month, partly refundable, waiver available | Required |
| Money | Rent due date & grace period | number (day) + number (grace days) | due the 1st, 5-day grace | Required |
| Money | Late fee | composite: flat $ or % + when it starts | $50 after the 5th | Required |
| Money | Payment methods | multi-select (portal, bank transfer, check, money order, cash) | portal, check | Required |
| Money | Move-in funds | multi-select (first month, deposit, prorated rent) | deposit + first month | |
| Money | Admin / move-in fee | money | $150 | |
| Money | Returned payment fee | money | $35 | |
| Money | Pet deposit | money | $300 | Required if pets allowed |
| Money | Pet one-time fee | money | $250 | Required if pets allowed |
| Money | Monthly pet rent | money | $35 | Required if pets allowed |
| Lease | Lease lengths | multi-select (6 / 12 / 18 / month-to-month) | 6, 12 | Required |
| Lease | Month-to-month and notice | yes / no + number (days) | Allowed, 30 days | Required |
| Lease | Notice to move out (fixed term) | number (days) | 30 days | Required |
| Lease | Early termination | composite: allowed? + fee or months of rent + notice | 2 months of rent, 60 days | Required |
| Lease | Renewal timing | number (days before lease end) | offer 60 days before | |
| Lease | Subletting & lease transfer | single choice (no / with approval) | with approval | |
| Pets | Animals allowed | multi-select | cats, dogs | Required |
| Pets | Max count | number | 2 | Required |
| Pets | Size and breed limits | composite: weight limit + note | dogs under 50 lb | |
| Rules | Smoking | two single choices: inside, outside (allowed / not / designated areas only) | Inside: not; Outside: designated areas | Required |
| Rules | Renter's insurance | yes / no + money (minimum coverage) | Required, $100,000 | Required |
| Rules | Guests & overnight stays | number (nights before they count as occupants) | 14 nights | |
| Rules | Quiet hours | time range | 10pm to 8am | |
| Rules | Alterations (paint, nails, fixtures) | single choice | paint with approval | |
| Building & amenities | Parking | composite: included? + assigned? + cost + guest parking | one assigned spot, $50 for a second | Required |
| Building & amenities | Utilities ★ | multi-select per utility (resident / owner pays) + providers | water, sewer, trash included | Required |
| Building & amenities | Laundry | single choice (in unit / shared / none) | shared, on each floor | |
| Building & amenities | Amenities | multi-select | gym, pool | |
| Building & amenities | Storage | yes / no + money | $40 a month | |
| Building & amenities | Packages | single choice (office / lockers / at door) | lockers | |
| Tours & move-in | Tour type | single choice (agent / self-guided / both) | Agent shows it | Required |
| Tours & move-in | Key handoff | single choice + note | At the office on move-in day | Required |
| Tours & move-in | After approval ★ | ordered steps + note | sign within 48 hours, pay deposit | Required |
| Tours & move-in | Move-in inspection | yes / no + number (days to return checklist) | checklist within 3 days | |
| Living there | Maintenance requests | multi-select channel (portal / phone / text) | portal or text | Required |
| Living there | Emergencies | note: what counts + who to call | no heat, flooding, gas: call the line | Required |
| Living there | Entry notice | number (hours) | 24 hours | |
| Move-out | Move-out inspection | yes / no + note | walk-through on the last day | |
| Move-out | Deposit return timeline | number (days) | 30 days | |
| Move-out | Cleaning & key return | note | keys to the office by noon | |
| Office & contact | Office hours | weekly hours | Mon to Fri, 9 to 5 | Required |
| Office & contact | Contact | phone + email | main office line | Required |
| Office & contact | Office location & walk-ins ★ | address + single choice | walk-ins welcome |
Custom, not core: the unauthorized pet fee, pool / grill / balcony rules, and any one-off story. Building exceptions ★ (today one company note) are replaced by the per-topic building override; anything left over becomes a custom policy. Assistance animals are never pets: a fixed rule Clara always applies, not a setting.
Some topics are set by state or city law in places (portable screening reports, deposit return timeline, entry notice, late-fee caps, source-of-income rules for vouchers). The slot records the company's answer; it does not check it against the law.
The six questions asked today, placed
| Today's question (title) | Section id | Placed as |
|---|---|---|
| Application documents | onboarding-application-documents | Core · Applying · Required |
| Screening criteria | onboarding-application-screening | Core · Applying · Required |
| Utilities | onboarding-policy-utilities | Core · Building & amenities · Required |
| Office location | onboarding-office-location | Core · Office & contact (no badge) |
| After approval | onboarding-move-in-after-approval | Core · Tours & move-in · Required |
| Building exceptions | onboarding-policy-building-exceptions | Per-topic building overrides; leftovers → Custom policies |
How the list was built
- Our own data: the hub's fixed questions (
onboarding-knowledge-questions.ts), the old leasing knowledge review's topic families (legacy-knowledge-answers.ts) and the topics it never landed (fees, admin fee, utilities, office, building rules:scripts/lib/questionnaire-backfill-plan.ts). - Apartment List, 36 questions renters ask: payment, fees, guarantors, lease lengths, notice, lease breaking, utilities, maintenance, late fees, subletting, guests, parking, amenities, storage.
- DoorLoop, 27 lease clauses: right of entry, late fees, subletting, renewal, early termination, occupants, noise, surrender, pets, smoking, parking, maintenance, utilities.
- Avail, important lease clauses and TurboTenant standard lease: guests, quiet hours, insurance, early termination.
- RentSpree and ManageCasa on written screening criteria: income multiple, credit, rental and eviction history, applied the same to every applicant.
Not used: the free-form knowledge entries customers wrote in production. Those were not read for this page; the old review's topic families stand in for them.
Pet fields: today vs proposed
| Today | Where it lives | Proposed |
|---|---|---|
| Pet fee (one-time, nonrefundable) | Company: registry fees.petFee via /api/settings/policies. Building: PropertyKnowledge.pricingDetails. Top of the Knowledge & policies grid. | Core Money · Pet one-time fee. Storage unchanged. |
| Pet deposit (refundable) | fees.petDeposit, same routes | Core Money · Pet deposit. |
| Monthly pet rent | fees.petRent, same routes | Core Money · Monthly pet rent. |
| Unauthorized pet fee (one-time) | fees.unauthorizedPetFee, same routes | Moves to Custom policies as a titled entry; value and history kept. |
| "Pet rules" free-text answer | knowledge.section.onboarding-policy-pets (fixed onboarding question) | Split: animals allowed + max count become the structured part; the rest becomes the Pets details note. |
| Pet policy (breed / weight / count) | Registry key pets.policy: declared, schema unspecified, no writer yet | Becomes the Pets slot's structured part. |
| Customer-written free-form "Pets" knowledge entries | knowledge.section.<id>, company knowledge body below the grid | Folded into the Pets details note automatically, every earlier version kept behind "⋯ → View history" (decided in Gera's review). |
⚠️ Today a building's knowledge overrides the company's by matching the section TITLE (lowercased), not the id — leasing-knowledge-block.ts, sectionIdentity. "One home per topic" replaces that with a fixed topic id, so a rename can no longer split a company answer from its building overrides. Knowledge sections append at composition (registry note on knowledge.section.<id>), which is exactly how two Pets entries reach Clara side by side.
Related pages
Sources read (read-only): src/lib/domain/onboarding/onboarding-knowledge-questions.ts, src/app/(workspace)/settings/policies/knowledge-policies-page.tsx, src/lib/domain/settings/scoped-fields/policies.ts, src/lib/domain/policies/pet-policy.ts, src/lib/domain/portfolio/registry/keys.ts.