# 09 — RealScout Replacement (Smart Property Alerts)

## Context
Fogbreak replaces RealScout for property alerts and matching. The existing `properties.php` has saved searches and basic alert generation. This instruction upgrades to AI-powered property matching that understands client preferences beyond simple field matching.

## What RealScout Does
- Collaborative home search between agent and client
- AI-powered property recommendations
- Client preference learning (likes/dislikes refine future matches)
- Beautiful property presentation (not just MLS data dump)
- Saved searches with instant alerts
- Agent-curated collections
- Market activity feeds
- Client engagement tracking (what did they view, save, dismiss)
- Lifestyle-based matching (not just beds/baths/price)

## What Already Exists
- `properties.php`: Listings table, saved searches, basic alert generation
- `property_alerts` table
- Cron: `property_alerts` job checks for matches
- Branded alert templates (three brands)

## What to Build

### 1. AI-Powered Property Matching
Upgrade from simple field matching to semantic understanding:
- Use RAG (from instruction 03) to embed property descriptions
- Match on lifestyle signals: "walkable to restaurants", "quiet cul-de-sac", "ocean view"
- Client preference profile builds over time from reactions
- Match score 0-100 with AI explanation ("This matches because of the updated kitchen and proximity to downtown, which you've preferred in past saves")

### 2. Client Preference Learning
```sql
-- Track every client interaction with properties
CREATE TABLE property_interactions (
    id SERIAL PRIMARY KEY,
    tenant_id INT NOT NULL,
    client_id INT NOT NULL,
    property_id INT NOT NULL,
    interaction_type VARCHAR(20) CHECK (interaction_type IN ('viewed','saved','loved','dismissed','shared','toured','offered')),
    time_spent_seconds INT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
```

AI analyzes patterns:
- Client always saves homes with large yards → boost yard size weight
- Client dismisses condos → reduce condo match scores
- Client spends 3 minutes on craftsman-style homes, 10 seconds on modern → learn style preference

### 3. Agent-Curated Collections
Agents create themed property collections for clients:
- "Carmel Cottages Under $1.5M"
- "Ocean View Homes in Pebble Beach"
- Collections are shareable links (branded)
- Client can react to items in collection (love, like, dismiss)
- AI suggests properties to add to collections

### 4. Smart Alert System
Upgrade the basic alert engine:
- Instant alerts when a new listing matches above threshold
- Daily digest option (bundle matches into one email)
- Weekly market summary with new listings, price changes, sold comps
- Price reduction alerts on saved/viewed properties
- Back-on-market alerts
- Open house alerts for matched properties

### 5. Beautiful Property Presentation
Not just raw MLS data — designed presentation:
- Hero photo with address overlay
- Room-by-room photo gallery
- Key features highlighted
- Walk score, school ratings, commute times
- Similar sold properties (AI-generated comps)
- Neighborhood description (AI-generated, market-aware)
- Agent branding on every presentation

### 6. Collaborative Search
Client portal feature:
- Client logs in and sees their matches
- Swipe left/right (dismiss/save) on mobile
- Add notes to properties
- Share with spouse/partner (both can react)
- Chat with agent about specific properties
- Schedule showing directly from property card

### 7. Market Activity Feed
Per-client feed showing:
- New listings in their search area
- Price reductions on listings they've viewed
- Recently sold comps (what did similar homes go for?)
- Days-on-market trends
- Inventory level changes

### 8. Engagement Analytics
Track and report:
- Which properties get most views/saves
- Client engagement score (active, passive, dormant)
- Alert open rates and click-through rates
- Time-on-page per property
- Conversion: alert → view → showing → offer

## API Endpoints
```
POST /api/properties.php?action=smart_search       # Create AI-powered search
GET  /api/properties.php?action=matches&client=X   # Get AI matches for client
POST /api/properties.php?action=react              # Client reaction (love/dismiss)
POST /api/properties.php?action=create_collection  # Agent creates collection
GET  /api/properties.php?action=collection&id=X    # Get collection
GET  /api/properties.php?action=market_feed&client=X  # Market activity feed
GET  /api/properties.php?action=engagement&client=X   # Engagement analytics
POST /api/properties.php?action=share_collection   # Share with client
```

## Cron Jobs
- `smart_match`: Run AI matching for all active searches (every 15 min)
- `price_reduction_alerts`: Check for price drops on saved properties
- `back_on_market_alerts`: Check for relisted properties
- `weekly_market_digest`: Generate and send weekly summaries
- `engagement_scoring`: Calculate client engagement scores

## Acceptance Criteria
- [ ] AI property matching with semantic understanding (not just field matching)
- [ ] Client preference learning from interaction history
- [ ] Agent-curated property collections with sharing
- [ ] Smart alerts: instant, daily digest, price reductions, back-on-market
- [ ] Beautiful property presentation with AI descriptions
- [ ] Collaborative search: client portal with reactions and notes
- [ ] Market activity feed per client
- [ ] Engagement analytics and reporting
- [ ] All features tenant-aware and market-aware