# Shortlist — Prototype Context

## What This Is
A visual prototype for developers. Not production code — it exists to communicate the idea clearly so a dev team can rebuild it properly from scratch. Use plain HTML and CSS. Vanilla JavaScript only when genuinely needed (tabs, show/hide). No frameworks, no build tools, no backend, no login. Realistic fake data only.

---

## The Idea
A blind bidding marketplace for property management. Property owners post their property anonymously and property managers submit competitive proposals — without seeing the owner's contact info until the owner shortlists them. This disrupts the current "spam-heavy" lead-gen model (e.g. All Property Management) where owners get cold-called by 5 companies after submitting a phone number.

**Terminology:** In the UI, the thing an owner posts is called a **Property** (the owner posts a property, managers submit proposals on it). "RFP" (Request for Proposal) is the underlying concept and may appear in internal docs / data model, but never user-facing.

**Business model:** Lead generation. Shortlist's job ends when the owner shortlists a manager and contact info is exchanged. The owner and manager sign their own deal directly — Shortlist doesn't facilitate contracts.

**Secret sauce (not in prototype):** Scrape rental listings to identify the current property manager, then link that to owner data found in public tax records. This pre-loads both sides of the marketplace before launch, enabling proactive sales outreach rather than waiting for organic signups.

---

## The Two Users

### Property Owner
- Has a rental property they want professionally managed
- Doesn't want to be cold-called by strangers
- Posts their property anonymously, waits for proposals, compares them with guidance, then shortlists their top choice(s)
- Contact info is only revealed after they shortlist someone

### Property Manager
- A professional management company looking for new clients
- Sees available properties seeking management and submits competitive proposals
- Knows enough about the property to price their proposal, but NOT the address or owner identity
- Gets notified when shortlisted; that's when contact is exchanged

---

## Entry Point
Neither side signs up organically — both are brought in via outreach (calls or email campaigns) using pre-scraped data. The prototype entry point assumes the user has already been invited and is logged in.

---

## The Core Flow

### Owner Flow
1. **My Properties** — overview of their posted properties and proposal status
2. **Post a Property** — describe their property anonymously, including goals ranking, involvement preference, and investment willingness (these feed the evaluation engine)
3. **Proposals Received** — accumulated proposals (not rolling review; the proposal window closes after a set window, e.g. 5 days)
4. **Compare Proposals** — side-by-side comparison with evaluation guidance from the engine
5. **Shortlist a Manager** — owner selects their preferred proposal(s); shortlist is *sent* to the manager (not an instant contact reveal)
6. **Awaiting Manager Response** — mutual-interest gate: manager has ~24 hours to confirm they can take the property on. Owner sees a pending state; if manager declines, owner is shown the decline reason and pointed back to the other proposals
7. **Contact Revealed** — only after the manager accepts. The payoff screen; contact info exchanged, platform's job is done

### Manager Flow
1. **Properties Feed** — browse available properties seeking management in their area
2. **View a Property** — see property details (anonymous)
3. **Submit a Proposal** — fill out fees + guarantees + a per-property note. Company identity, stats, services, and pitch come from the persistent Company Profile
4. **My Proposals** — track status of submitted proposals
5. **Owner Shortlisted You** — decision screen: accept to exchange contact, or decline if capacity has shifted since the proposal was submitted. The proposal window can close days before the owner decides, so this gate prevents bad-fit handoffs
6. **Contact Revealed** — only after the manager accepts. Symmetric payoff to the owner side

---

## What Managers See on a Property (Anonymous)
- City / neighborhood
- Property type (single family, duplex, small apartment building, etc.)
- Number of units
- Rough condition
- What the owner is looking for (full management, leasing only, etc.)
- Photos
- **NOT:** exact address, owner name, owner contact info

---

## What a Proposal Contains

**The numbers:**
- Monthly management fee (% of rent)
- Leasing fee (cost to find a new resident)
- Any other fees (maintenance markup, inspection fees, etc.)

**Guarantees:**
- Vacancy guarantee (e.g. "fill in 21 days or we waive our fee")
- Eviction protection (e.g. "we cover legal costs")
- Maintenance response time commitment

**Who the manager is:**
- Number of properties currently managed
- Years in business
- Average vacancy rate
- Short pitch / why pick us

**Services included:**
- Checklist (rent collection, maintenance coordination, monthly reporting, etc.)

---

## The Evaluation Engine
This is a key differentiator — it helps owners **understand value**, not just compare prices. It:
- Translates different fee structures into apples-to-apples annual cost estimates
- Explains what typical fees look like in the market
- Flags when a proposal is unusually low (and why that might be a red flag)
- Helps owners understand whether a price difference between proposals is justified by what's included
- Teaches owners how to evaluate — acts like a knowledgeable friend sitting next to them, not an algorithm picking a winner

Example output: *"Manager B is $800/year cheaper but has no eviction protection and a 45-day vacancy guarantee vs. Manager A's 21 days. Based on average eviction costs in your market, Manager A may be the better value if resident risk is a concern."*

---

## Bidding Model
- **Accumulate and compare** — proposals pile up during a set window (e.g. 5 days), then owner reviews all at once side-by-side
- NOT rolling review (owner decides one-by-one as proposals arrive)
- This model fits the evaluation engine and reduces pressure on owners

---

## After the Shortlist
Platform's job is done. Owner and manager connect directly to finalize terms and sign their own contract. The prototype ends at the contact-revealed screen with a simple note explaining this.

---

## Name
**Shortlist** — named after the key owner action and the satisfying payoff moment of the product.

---

## Views to Build

Both user types share the same prototype — toggle between Owner and Manager via a role switcher at the top (no real login).

| # | View | File | Who sees it | Purpose |
|---|---|---|---|---|
| 01 | **Owner: My Properties** | `owner-properties.html` | Owner | Overview of posted properties: status (open / window closed / shortlisted), proposal count per property, quick actions |
| 02 | **Owner: Post a Property** | `owner-post-property.html` | Owner | Multi-step form: property type, units, condition, management scope, photos, and owner intent (goals ranking, involvement preference, investment willingness). Address and owner identity are NOT collected — they're already on file from outreach |
| 03 | **Owner: Proposals Received** | `owner-bids.html` | Owner | List of all proposals on one property after the proposal window closes; each proposal shows summary (fee %, vacancy guarantee, NARPM designations) and a "View profile →" affordance |
| 04 | **Owner: Compare Proposals** | `owner-compare.html` | Owner | Side-by-side comparison of 2–3 selected proposals; Evaluation Engine output (annual cost translation, red flags, narrative guidance), NARPM designations row, per-column "View profile →" link |
| 04a | **Owner: Shortlist Confirm** | `owner-shortlist-confirm.html` | Owner | Confirmation step before sending the shortlist to the manager. Explains the mutual-interest gate |
| 04b | **Owner: Shortlist Pending** | `owner-shortlist-pending.html` | Owner | Awaiting-manager-response state. Three-step progress (sent → manager confirms → contact exchanged) with a clear ~24-hour window |
| 04c | **Owner: Shortlist Declined** | `owner-shortlist-declined.html` | Owner | The path when the manager declines. Gentle framing, includes the manager's optional note, points back to the other proposals |
| 05 | **Owner: Contact Revealed** | `owner-contact-revealed.html` | Owner | Payoff screen after the manager accepts. Manager's contact info, next-step instructions; platform's job ends here. **This is the only screen that breaks the design grid** — see DESIGN.md |
| 06 | **Manager: Properties Feed** | `manager-feed.html` | Manager | Browse open properties in their area: city/neighborhood, property type, unit count, rough condition, management scope; no owner identity |
| 07 | **Manager: Property Detail** | `manager-property-detail.html` | Manager | Full anonymous property view: all details + photos; "Submit a Proposal" CTA |
| 08 | **Manager: Submit a Proposal** | `manager-submit-bid.html` | Manager | Slim proposal form: fees (management %, leasing fee, other fees), guarantees (vacancy, eviction, maintenance SLA), and a per-property note. Company identity, stats, pitch, services, coverage cities, and credentials come from the persistent profile |
| 08a | **Manager: Company Profile** | `manager-profile.html` | Manager | Persistent profile that feeds every proposal: identity, at-a-glance stats, pitch, services, coverage cities, NARPM designations + license verification, anonymous gallery of recent properties under management |
| 09 | **Manager: My Proposals** | `manager-my-bids.html` | Manager | Track all submitted proposals: pending / under review / shortlisted / not selected. Shortlisted-row CTA routes to the decision screen (not directly to contact reveal) |
| 09a | **Manager: Shortlisted Decision** | `manager-shortlisted-alert.html` | Manager | Decision gate when an owner shortlists: property summary, owner's note, your-proposal recap, and two CTAs — accept to reveal contact, or decline if capacity has shifted |
| 09b | **Manager: Decline Confirm** | `manager-decline-confirm.html` | Manager | Confirmation that the decline was sent; routes back to My Proposals |
| 10 | **Manager: Contact Revealed** | `manager-contact-revealed.html` | Manager | Payoff screen after the manager accepts the shortlist invitation: owner's contact info + property address; same payoff treatment as Owner view 05 but from the manager's perspective |

---

## ILS — out of scope for Shortlist

Shortlist does not own a renter-facing ILS surface. The ILS lives in Wren (the messaging-enablement product); listing data flows through shared canonical tables (`canonical_properties`, `canonical_companies`, listings) and Shortlist consumes it as input — manager track record on profiles, Eval Engine comps, posting enrichment — without rendering a listings browse. Do not propose or build ILS views here.

---

## Design

**The sole design system is documented in `DESIGN.md`. Read it before building any view.** It is locked — do not deviate, do not invent alternatives, do not invoke `wa-design` or `frontend-design`.

**Direction in one line:** *Editorial Instrument* — Newsreader serif + Inter + JetBrains Mono on a warm-cream "paper" ground, hairline rules, no shadows, sharp corners with 4px on inputs/buttons. Light mode is locked; dark mode is the "lamplight on dark paper" counterpart specified in DESIGN.md.

**Both modes are required.** Every view ships light and dark.

**The payoff moment** (Owner/Manager Contact Revealed) is the one screen that breaks the system — full-bleed, oversized Newsreader hero, redacted-text reveal treatment. See DESIGN.md.

**The Evaluation Engine never picks a winner.** No "Recommended" badges, no ranking, no scores. It explains and flags; the owner decides.

---

## Prototype Rules
- Plain HTML + CSS only
- Vanilla JS only if genuinely needed (tabs, show/hide panels, role switcher)
- No framework, no build tool, no backend, no database, no login system
- Realistic fake data throughout (fake property names, fake manager companies, fake fees)
- One file per view — keep it simple and readable for a developer
- All prototype files live in this folder: `/Users/dereklefler/Documents/Projects/walapaloo/prototype planner/shortlist/`