# Supervision — Full Technical, Product & MCP Reference (llms-full.txt)

> Supervision is the Autonomous Operating System for Residential & Commercial Property Stewardship. It connects 6 core real estate archetypes (Realtors, Home Buyers/Sellers, Homeowners, Licensed Contractors, Commercial Multiunit Landlords, and Tenants) around a shared, verifiable Property Passport and 23-tool Model Context Protocol (MCP) server.

---

## 1. Six-Archetype Ecosystem Architecture

### 1.1 Realtors & Home Buyers / Sellers (`/for-realtors`, `/inspection-decoder`)
- **AI Inspection Report Decoder**: Parses multi-page home inspection PDFs into structured health/safety defects (`CRITICAL`, `MAJOR`, `MODERATE`), trade categories (`Plumbing`, `Electrical`, `Roofing`, `HVAC`, `Framing`, `Drywall`), and zip-code-calibrated repair cost ranges.
- **Seller Credit Request Addendum**: Generates copy-ready repair credit negotiation language and itemized dollar totals before the inspection contingency expires.
- **Realtor Affiliate & Co-Branding Engine**: Realtors generate a custom slug (`/inspection-decoder?ref=<slug>`) that co-brands every decoded report with their headshot, brokerage, and DRE license while tracking clicks, reports, and unlocked client packets.

### 1.2 Homeowners (`/remodels`, `/passport`, `/tax-shield`, `/calculator/tax-basis`)
- **Line-Item Contractor Quote Audit**: Compares contractor proposals against RSMeans and local labor/material benchmarks to flag missing permit line items or excessive markups.
- **IRS Section 121 & Publication 523 Capital Improvement Ledger**: Automatically classifies invoices into Capital Improvements (which increase adjusted cost basis and shield capital gains upon sale) vs. Routine Repairs.
- **Transferable Property Passport (`/p/[id]`)**: Public, verifiable record of permitted upgrades, warranties, before/after jobsite photos, and contractor licenses.

### 1.3 Licensed Contractors & Trade Sub-Crews (`/for-pros`, `/pro`, `/p/[id]/rfp`)
- **Tool 01 — Instant AI Client Proposal & Trilingual Scope Generator (`POST /api/v1/projects/pro-proposal`)**: Contractors upload 1–4 jobsite photos (via Camera, Camera Roll, or Google Photos) and dictate rough scope notes by voice to generate an itemized proposal in English (`en`), Spanish (`es`), and Chinese (`zh`), plus a 1-tap SMS link to the homeowner.
- **Sub-Crew Work Order Mode (`/p/[id]/rfp?crew=1`)**: Hides all dollar pricing and bid forms so General Contractors can text trilingual scopes and 2D floorplans directly to Spanish- or Chinese-speaking sub-crews.
- **Field Accessibility & Hands-Free Voice Controls**: `A+ Large Print Mode` for bright jobsite sunlight, trilingual Text-to-Speech (`Read Scope Aloud`), and `Tap & Speak` voice dictation.
- **1-Tap Field Change Orders & Statutory CA Lien Waivers**: Log unforeseen conditions with discovery photos and text the homeowner an SMS approval link or statutory California Civil Code § 8132 (Conditional Progress) / § 8138 (Unconditional Final) Lien Waiver.
- **Exclusive Job Claiming & Bid Lock Lifecycle**: Accepting a bid (`ACCEPTED`) or claiming a job (`CLAIMED`) atomically locks the scope from competing contractors; withdrawing (`WITHDRAWN`) or releasing rolls the job back to the open marketplace queue.

### 1.4 2D City Permit CAD & On-the-Fly Symbol Studio (`/app/floorplan`)
- **AI Photo + SOW to 2D Permit Floorplan**: Synthesizes scaled 2D architectural walls, doors, windows, electrical circuits (NEC/CEC load VA), and plumbing drain/waste/vent risers (CPC DFU).
- **On-the-Fly AI CAD Symbol Creator (`POST /api/v1/projects/floorplan/custom-symbols`)**: Users enter a natural-language prompt (e.g., `"240V Heat Pump Water Heater 50 Gal"`) to synthesize a 2D plan-view SVG symbol with dimensions and code notes on the fly. Symbols are immediately usable on the creator's canvas (`status = "PENDING_REVIEW"`) and queued for Super Admin approval (`APPROVED`) to backfill the global AI Floorplan Generator.

### 1.5 Commercial Multiunit Landlords & Co-Owners (`/for-hosts`, `/app/properties/[id]`)
- **Interactive Cap Rate Underwriting Flip-Card**: Auto-estimates baseline market cap rate during property deep research; flips to reveal Gross Scheduled Rent, Vacancy/Credit Loss %, Operating Expense Ratio %, Net Operating Income (NOI), and Implied Valuation sliders with owner override persistence.
- **Multiunit Roster with Search, Occupancy Filters & Pagination**: Manage 4-plexes to 200-unit apartment buildings with instant search (`Unit #`, `Tenant Name`, `Email`, `Notes`), status filters (`ALL`, `OCCUPIED`, `VACANT`, `TURNOVER_REMODEL`), and pagination (`10 / 25 / 50 per page`).
- **Vacant Unit Walkthrough -> 3-Tier Remodel ROI & Cap Rate Boost Engine**: Upload vacant unit walkthrough photos/videos to research submarket median rent, project 3 remodel tiers (*Refresh*, *Value-Add Modernize*, *Luxury Reposition*), calculate ROI payback months + forced building equity (`Annual Net Rent Lift / Cap Rate`), and launch a bilingual Contractor RFP in 1 click.
- **Google Docs-Style Co-Owner & Trust Sharing**: Invite family trust partners, co-owners, or property managers as `ADMIN`, `EDITOR`, or `VIEWER`.

### 1.6 Multiunit Tenants & Guests (`/g/[slug]?unit=1A`)
- **Timestamped Statutory Tenant Notices & Formal PDF**: Landlords issue `24HR_ENTRY`, `UTILITY_SHUTOFF`, `INSPECTION`, `RENT_ADJUSTMENT`, or `GENERAL_MEMO` notices with downloadable legal PDFs (`/api/v1/notices/{id}/pdf`).
- **In-App Notice Acknowledgment & Linked Ticket Response**: Tenants mark notices as read, dismiss them, or respond directly with a linked maintenance/scheduling ticket.
- **24/7 AI Tenant Q&A Concierge (`POST /api/v1/guidebooks/public/{slug}/ask`)**: Answers tenant questions using building rules, HVAC/trash/parking instructions, and active notices on behalf of the landlord, escalating to a repair ticket when physical maintenance is required.

---

## 2. Complete 23-Tool Model Context Protocol (MCP) Catalog

Connect any MCP client to `/mcp/rpc` (JSON-RPC 2.0) or `/mcp/sse` (Server-Sent Events):

1. `audit_contractor_quote`: Line-item contractor quote audit against localized labor/material benchmarks.
2. `decode_inspection_report`: Extract defects, severity, repair estimates, and seller credit addendums from inspection text/PDFs.
3. `verify_contractor_license`: Verify state contractor license status (CSLB, etc.).
4. `calculate_tax_shield`: Classify remodel expenses under IRS Section 121 & Publication 523.
5. `generate_scope_of_work`: Generate a trilingual (EN/ES/ZH) trade-by-trade Scope of Work.
6. `estimate_renovation_roi`: Estimate renovation cost, resale value added, and ROI percentage.
7. `triage_maintenance_issue`: Triage tenant/guest maintenance issues with severity, troubleshooting steps, and trade dispatch recommendations.
8. `get_property_passport`: Retrieve public Property Passport and verified remodel ledger.
9. `list_open_contractor_jobs`: List available open jobs and RFPs filterable by trade specialty.
10. `submit_contractor_bid`: Submit an itemized labor + materials bid on an open RFP.
11. `ask_property_concierge`: Query the AI Property Concierge for building rules, amenities, and notices.
12. `check_permit_requirements`: Determine city building/electrical/plumbing/mechanical permit requirements for a scope.
13. `get_system_health`: Check platform health and AI model routing status.
14. `manage_multiunit_roster`: List, search, filter, or create units in a multiunit building roster.
15. `analyze_vacant_unit_remodel_and_cap_rate`: Run the Vacant Unit Walkthrough -> 3-Tier Remodel ROI, Median Rent Comp & Building Cap Rate Boost engine.
16. `issue_tenant_statutory_notice`: Issue a timestamped statutory tenant notice (`24HR_ENTRY`, `UTILITY_SHUTOFF`, etc.) with formal PDF generation.
17. `tenant_concierge_qa_and_triage`: Answer tenant questions or acknowledge/respond to building notices with a linked ticket.
18. `generate_contractor_instant_proposal`: Generate a 60-second trilingual contractor proposal, sub-crew work order link, and 2D permit CAD blueprint.
19. `manage_contractor_marketplace_job`: Claim an open job (locking it exclusively), release/withdraw a job back to the open pool, or log a field change order.
20. `generate_statutory_lien_waiver`: Generate California Civil Code § 8132 (Conditional Progress) or § 8138 (Unconditional Final) statutory lien waiver payloads.
21. `create_custom_cad_symbol`: Synthesize a custom 2D CAD SVG symbol on the fly from a natural-language prompt and queue it for Super Admin global backfill review.
22. `generate_2d_permit_floorplan`: Synthesize a 2D architectural, electrical (NEC), and plumbing (CPC) permit floorplan JSON.
23. `register_realtor_affiliate_partner`: Register a Realtor partner and generate a co-branded affiliate inspection decoder link.