Add property-pro community ability

community/property-pro/README.md

@@ -0,0 +1,172 @@
+# PropertyPro — Voice Showing Tour Guide
+
+![Community](https://img.shields.io/badge/OpenHome-Community-orange?style=flat-square)
+![Author](https://img.shields.io/badge/Author-@adigitaltati-green?style=flat-square)
+![Status](https://img.shields.io/badge/Status-Stage%201-blue?style=flat-square)
+
+A voice-enabled residential showing companion for OpenHome. A visitor walks into a listed home, picks up the device on the table, and says **hello** to start a short room-by-room tour — with fair-housing-safe answers and unanswered questions saved for the listing agent.
+
+Part of **Suite B** (Specialized Property Guides), alongside StayGuide and BizSpace.
+
+---
+
+## Scene
+
+**Visitor path:**
+
+1. Buyer/renter walks in, reads the note, says **hello**, tours with the speaker.
+2. PropertyPro answers from the active listing packet and logs unknowns to `tour_questions.md`.
+3. When the tour ends (idle or “done”), the device stays in PropertyPro: *“Closing the tour. Say hello to start again.”*
+
+**Agent setup — target (future app):**
+
+1. Place the speaker + note in the home.
+2. Phone app: upload listing packet → connect speaker → select packet → start assistant → leave.
+
+**Agent setup — Stage 1 stand-in:**
+
+1. Ability ships with markdown fixtures under `fixtures/listings/`.
+2. Default active listing is `1420-maple-richmond` (`propertypro_prefs.json` → `active_listing_id`).
+
+---
+
+## Trigger Words
+
+Dashboard triggers must be **at least 4 letters** (OpenHome platform rule). Recommended:
+
+| Phrase | What it does |
+| --- | --- |
+| `"hello"` | Start the showing tour |
+| `"start tour"` / `"begin tour"` | Same as hello |
+| `"property pro"` | Same as hello |
+
+**In-tour / lobby phrases** (work after the ability is already running; not all are valid dashboard triggers):
+
+| Phrase | What it does |
+| --- | --- |
+| `"hi"` / `"hello"` / `"start tour"` | Restart the tour from the first room (or leave the closed-tour lobby) |
+| room names (`"kitchen"`, `"living room"`, …) | Jump to that room |
+| `"next"` / `"go back"` | Move along the tour order |
+| `"what's the agent's number"` | Speak listing-agent name + phone |
+| `"text the agent"` / `"call the agent"` / `"email …"` | Stage 1: explain send isn’t wired yet; speak the agent’s number; questions stay on the list |
+| `"done"` / `"goodbye"` / `"end tour"` | Close this tour session → lobby |
+
+---
+
+## What It Answers (and what it won't)
+
+**From the listing packet (safe):** beds/baths, sq ft, price, HOA fee, inclusions/exclusions, systems updates, room notes + dimensions, school *assignment* (name only, no ratings), agent contact.
+
+**Redirect (fair housing / customary practice):**
+
+- Crime / “is this neighborhood safe?” → point to official sources; do **not** recite crime stats or opinions.
+- School *quality* → assignment if known + public evaluation guidance; no “good/bad” rankings.
+- Who lives here / protected-class suitability → hard refuse (no steering, no demographics).
+
+**Missing facts:** *“I don’t have that in my notes. I’ve added that to the agent’s question list.”* → append `tour_questions.md`.
+
+A `fair_housing.md` knowledge base ships with the ability. This is product guardrails, not legal advice to consumers or brokers.
+
+---
+
+## Stage 1 features
+
+- [x] Hello → greet → room tour → visitor-driven Q&A
+- [x] Richer room notes + dimensions from markdown listing packets
+- [x] Fair-housing redirects / hard refusals
+- [x] Unanswered questions → `tour_questions.md`
+- [x] Closed-tour **lobby** (stay in PropertyPro; say hello to start again)
+- [x] Three mock listing fixtures
+- [x] `knowledge_gaps.json` for product/schema failures
+- [ ] Email `tour_questions.md` via `send_email()`
+- [ ] Twilio SMS / outbound TTS call
+
+**Out of scope for Stage 1:** buyer search portal, seller CMA / pricing advice, live crime APIs spoken aloud, two-way call bridge, CRM / lead capture, phone-app upload.
+
+---
+
+## Mock listing (testing)
+
+| ID | Property | Why it exists |
+| --- | --- | --- |
+| `1420-maple-richmond` | Full craftsman SFH | Happy-path tour with systems + inclusions |
+
+Packet lives under [`fixtures/listings/`](fixtures/listings/). There's no voice command to
+switch which listing is active -- it's read once from `propertypro_prefs.json` at startup
+-- so only the one listing an install actually tours is included here.
+
+---
+
+## Setup
+
+### 1. Install the ability
+
+Push or install PropertyPro and set dashboard triggers to at least:
+
+`hello`, `start tour`, `begin tour`, `property pro`
+
+### 2. Active listing
+
+The only listing shipped is `1420-maple-richmond`, set as `active_listing_id` in `propertypro_prefs.json` on first run. Add more fixtures under `fixtures/listings/` and edit that file to tour a different one -- there's no voice command for it yet.
+
+### 3. Contact / delivery (Stage 1)
+
+Email and Twilio sends are **not** wired yet. Contact asks speak the listing agent’s phone (TTS-friendly) and keep `tour_questions.md` updated.
+
+---
+
+## Example conversation
+
+**Visitor:** “Hello.”
+
+**PropertyPro:** “Hi — welcome to Maple Avenue Craftsman. I’ll walk you through the main spaces, and you can ask me questions anytime. I’m here for facts about this property — for neighborhood topics like crime or demographics, I’ll point you to official sources rather than give opinions. We’ll begin in the foyer.”
+
+**PropertyPro:** “You’re in the foyer. Room dimensions 11 by 8. A classic craftsman entry with original oak trim, a built-in bench niche, and soft light from the sidelight windows. The hardwood continues straight into the living room ahead.”
+
+**Visitor:** “What’s the square footage?”
+
+**PropertyPro:** “About 1,840 square feet.”
+
+**Visitor:** “Is this a safe neighborhood?”
+
+**PropertyPro:** “I don’t give crime opinions or stats. You can check the public safety open data and local police resources linked in my notes.”
+
+**Visitor:** “Text the agent.”
+
+**PropertyPro:** “I can’t send messages from this device yet. Avery Chen’s number is 5 5 5, 0 1 0, 1 4 2 0. Your questions are saved on the agent’s list.”
+
+**Visitor:** “We’re done.”
+
+**PropertyPro:** “Closing the tour. Say hello to start again.”
+
+**Visitor:** “What’s the price?”
+
+**PropertyPro:** “The tour is closed. Say hello to start again.”
+
+---
+
+## Project layout
+
+```
+community/property-pro/
+├── README.md
+├── main.py
+├── fair_housing.md
+└── fixtures/listings/*.md
+```
+
+Runtime files, written by the ability, not committed: `propertypro_prefs.json`, `tour_questions.md`, `knowledge_gaps.json`
+
+---
+
+## Related
+
+- Suite A sibling: [`community/town-hall`](../town-hall/) — voice flow, prefs, gap logging patterns
+- OpenHome email template (future): [`templates/send-email`](../../templates/send-email/)
+- Twilio SMS / outbound call (future): [`community/Twilio-SMS`](../Twilio-SMS/)
+
+---
+
+## Status
+
+Stage 1 is implemented and live-testable: hello → room beats → Q&A → fair-housing redirects → question logging → lobby until hello. Default listing: Maple Avenue Craftsman. Email/Twilio still deferred.

community/property-pro/fair_housing.md

@@ -0,0 +1,77 @@
+# Fair housing & showing-tour rules
+
+product guardrails for propertypro. not legal advice. brokers should review for their market.
+
+## hard rules (never violate)
+
+- do not steer buyers toward or away from a home or area based on race, color, religion, sex, disability, familial status, national origin, or other protected classes under applicable federal, state, or local law.
+- do not describe who lives in the neighborhood by protected class (race, ethnicity, religion, national origin, family status, etc.).
+- do not say a home or area is or is not a "good fit" for someone because of a protected characteristic.
+- treat every visitor the same on factual property information. do not vary answers based on who is asking.
+
+## redirect policy (stage 1 product choice)
+
+even when factual school or crime *data* may be discussable under some federal guidance, this ability follows safer customary practice:
+
+### crime / safety
+
+- do not recite crime statistics, rankings, or "safe / unsafe" opinions.
+- redirect to official public sources listed in the active listing packet `redirect_urls.crime_open_data` (or market defaults).
+- log a follow-up for the listing agent only if the visitor asks — do not prompt them.
+
+spoken pattern:
+
+> i don't give crime opinions or stats. you can check the public safety open data and local police resources linked in my notes.
+
+if the visitor asks to leave a note for the agent about those links, append `tour_questions.md`. do not prompt them to do so.
+
+### school quality
+
+- you may state school *assignment* for the address if it is in the listing packet.
+- do not rate schools as good/bad or recommend based on quality opinions.
+- point visitors to the district site / public report cards (`redirect_urls.school_district`).
+
+spoken pattern:
+
+> i don't rate schools. this address is listed under [assignment if known] — please verify on the district site. public report cards are the place to judge fit.
+
+### demographics
+
+- hard refuse. do not soft-answer with "vibes" about who lives nearby.
+
+spoken pattern:
+
+> i'm not able to discuss neighborhood demographics under fair housing guidelines. i can stick to facts about this property if you have another question.
+
+## allowed property talk
+
+answer from the listing packet when present:
+
+- beds, baths, size, lot, year built, price, taxes/hoa fees as listed
+- room notes, **room dimensions** (speak as "11 by 8", not "11x8"), systems ages, inclusions/exclusions
+- parking, utilities notes, disclosure pointers
+- agent name, phone, email
+- flood map *link* redirect (`redirect_urls.flood_map`) — do not invent zone determinations
+
+if room dimensions are missing from the packet, skip that clause — do not invent sizes.
+
+if a property fact is missing from the packet:
+
+> i don't have that in my notes. i've added that to the agent's question list.
+
+then append to `tour_questions.md`. never say only "ask your agent" without logging.
+
+## soft refuse (not fair housing, still out of scope)
+
+- offer strategy, pricing opinions, "should i buy this," inspection negotiation: decline to advise; optionally log that the visitor wants human follow-up.
+- buyer financing / underwriting: point them to their lender.
+
+## consistency
+
+same factual content for every visitor. listing packets cannot enable demographic or crime editorial talk.
+
+## maintainer references
+
+- hud fair housing overview: https://www.hud.gov/fairhousing
+- nar fair housing resources: https://www.nar.realtor/fair-housing
+- hud apr 2026 dear colleague letter (school/crime data discussion): product still chooses redirect for crime and no school-quality opinions

community/property-pro/fixtures/listings/1420-maple-richmond.md

@@ -0,0 +1,92 @@
+# Maple Avenue Craftsman
+
+- **id:** `1420-maple-richmond`
+- **address:** 1420 Maple Avenue, Richmond, VA 23220
+- **price:** $425,000
+- **beds / baths:** 3 / 2
+- **sq ft:** 1,840
+- **lot:** 0.18 acres
+- **year built:** 1928
+- **hoa:** none
+
+## Agent
+
+- **name:** Avery Chen
+- **brokerage:** River City Realty
+- **phone:** +15550101420
+- **email:** avery.chen@example.com
+
+## Seller welcome
+
+Thanks for touring — make yourselves at home.
+
+## Tour order
+
+1. foyer
+2. living
+3. kitchen
+4. primary
+5. upstairs
+6. basement
+7. backyard
+
+## Rooms
+
+### foyer
+- **dimensions:** 11 by 8
+- **note:** A classic craftsman entry with original oak trim, a built-in bench niche, and soft light from the sidelight windows. The hardwood continues straight into the living room ahead.
+
+### living
+- **dimensions:** 16 by 14
+- **note:** A bright gathering room with a working brick fireplace, original crown molding, and a wide bay window that pulls in afternoon light. Plenty of wall space for art or a media setup without feeling crowded.
+
+### kitchen
+- **dimensions:** 12 by 14
+- **note:** Remodeled in 2021 with quartz counters, shaker cabinets, a gas range, and a deep farmhouse sink. It opens through French doors to the deck, so cooking and outdoor seating feel connected.
+
+### primary
+- **dimensions:** 14 by 12
+- **note:** A quiet main-floor retreat with a walk-in closet and an en-suite bath featuring a walk-in shower and dual vanity. Morning light comes through two east-facing windows.
+
+### upstairs
+- **dimensions:** 11 by 10
+- **note:** Two flexible bedrooms under the craftsman eaves, each about 11 by 10, sharing a full hall bath with a tub-shower. Ideal for guests, kids, or a home office with dormer light.
+
+### basement
+- **dimensions:** 28 by 18
+- **note:** A clean unfinished level with laundry hookups, solid ceiling height for storage or a future finish, and easy access to the mechanicals along the stair wall.
+
+### backyard
+- **dimensions:** (none)
+- **note:** A fully fenced yard with a wood deck right off the kitchen, mature shade trees, and room for a garden bed or outdoor dining. The lot is about two-tenths of an acre, so it feels private without being high-maintenance.
+
+## Systems
+
+- **roof:** 2019
+- **hvac:** 2020
+- **water heater:** 2018
+- **breaker box:** basement stair wall
+- **water shutoff:** front crawl access
+
+## Inclusions
+
+- refrigerator
+- washer
+- dryer
+
+## Exclusions
+
+- freestanding bookshelf
+
+## School assignment
+
+- **elementary:** Bellevue Elementary
+- **middle:** Albert Hill Middle
+- **high:** Thomas Jefferson High
+- **verify:** verify on district site — assignment is illustrative for this fictitious listing
+
+## Redirect URLs
+
+- **crime open data:** https://example.com/richmond-public-safety
+- **school district:** https://example.com/rps-school-finder
+- **flood map:** https://msc.fema.gov/portal/home