# Stoop Sale Scheduler: Coordinate Block Yard Sales ## The Problem Individual yard sales are lonely affairs—hand-painted signs that blow away, three browsers in four hours, and that sinking feeling of hauling everything back inside. Meanwhile, your neighbor two blocks over had their sale last weekend. When sales scatter across weekends, everyone loses: sellers get thin traffic, buyers waste gas hunting for signs, and the neighborhood misses a chance to come together. A coordinated block sale transforms "clearing out the garage" into a genuine community event that draws crowds from adjacent neighborhoods. ## Who Uses It **The Declutterer (Primary)**: Someone moving, downsizing, or doing spring cleaning who wants their sale to actually succeed. They don't have time to go door-to-door recruiting neighbors but would absolutely join a coordinated weekend if the coordination happened for them. **The Block Captain**: That neighbor who already organizes the holiday cookie swap. They'll propose dates, nudge participation, and share the map on Nextdoor and the neighborhood Facebook group. **The Deal Hunter**: Lives two neighborhoods over, plans Saturday mornings around sales. Currently drives around looking for signs—would much rather see a map of 15 clustered sales than stumble on one lonely driveway. **The Local Shop Owner**: The coffee shop, taco truck, or plant nursery that would happily offer a "Stoop Sale Saturday" discount to capture foot traffic already flowing through the area. ## Core Features 1. **Propose a Sale Weekend**: Any resident can propose a weekend date for their block/neighborhood. The proposal shows on a simple calendar view. Others see "3 households interested in May 17th" and can click to add themselves, creating natural clustering. 2. **Declare What You're Selling**: When joining a sale weekend, sellers tag their inventory categories from a fixed list (Kids & Baby, Tools & Garden, Furniture, Books & Media, Clothing, Kitchen, Electronics, Plants, Art & Collectibles, Free Pile). No elaborate listings—just enough for buyers to prioritize stops. 3. **Generate a Shareable Sale Map**: Once 3+ households commit to a weekend, the system generates a simple map with pins, addresses, and category tags. This is a static shareable link—works without an account, easy to post to social media or print as a QR code flyer. 4. **Local Business Specials Board**: Businesses registered with WellSpr.ing can post a same-day special tied to a sale weekend ("Show this screen for $1 off coffee"). Specials appear on the sale map, turning the event into a full neighborhood circuit. 5. **Reach Notification for Participants**: When a new household joins a sale weekend you're participating in, or when the map goes live, you get a notification via WellSpr.ing's reach system—no app install required. 6. **Unsold-to-Free Pipeline**: After the sale, one click converts your listing to "Free Pile" status and cross-posts to WellSpr.ing's free items feed, so stuff finds homes instead of landfills. 7. **Ask Ody for Sale Tips**: Embedded Ody assistant answers questions like "what sells best at yard sales?" or "how do I price kids' clothes?" using local context. ## WellSpr.ing Integration Points ### MCP Tools (POST to https://wellspr.ing/mcp using JSON-RPC 2.0) | Tool | Usage | |------|-------| | `get_businesses` | Fetch local businesses that might want to offer same-day specials. Filter by proximity to sale area. Display on map as "partners." | | `get_business_detail` | When a shopper taps a business pin, pull details (hours, description, contact). | | `get_free_items` | Show existing free items in the neighborhood—complements the sale, surfaces generosity. | | `submit_business` | *Roadmap: not yet live for non-business submissions*—future use for sellers who want a persistent "I do sales regularly" profile. | | `reach_number` | Get or create a reach number for sale participants so they receive notifications (new joiners, map live, post-sale reminder). | | `ask_ody` | Power the "Sale Tips" assistant. Pass user questions with local context (neighborhood, date, categories). | | `get_civic_ideas` | Surface related civic ideas in the area—maybe someone proposed a recurring flea market and this sale could seed it. | | `get_adjacent_nodes` | Check if neighboring WellSpr.ing nodes have active sales the same weekend—potential for cross-neighborhood promotion. | ### REST Endpoints | Endpoint | Usage | |----------|-------| | `GET /api/geo/portals?area_code=NNN` | Determine neighborhood boundaries for clustering sales. A "block sale" shouldn't span the whole city—use portals to scope. | ### WCIB Endpoints | Endpoint | Usage | |----------|-------| | `GET /api/wcib/ideas` | Show other civic projects happening in the neighborhood—cross-pollinate community energy. | | `POST /api/wcib/ody-ask` | Alternative Ody endpoint for WCIB-specific questions about the project itself. | ### Not Yet Available (Roadmap) - **Covenant commerce payment rails**: Future feature could enable pre-sale deposits or business special redemption tracking. Label any payment features as "Future: Covenant Commerce." - **Merchant self-registration for specials**: Currently requires manual business listing. Future: businesses self-post time-limited offers. ## Data Model ``` ┌─────────────────────────────────────────────────────────────────┐ │ sale_weekends │ ├─────────────────────────────────────────────────────────────────┤ │ id (uuid), neighborhood_code, proposed_date, status │ │ (proposed | confirmed | completed), created_by_reach, │ │ participant_count, map_url, created_at │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ participants │ ├─────────────────────────────────────────────────────────────────┤ │ id (uuid), sale_weekend_id (fk), reach_number, address_text, │ │ lat, lng, categories (text[]), notes, status (active | free | │ │ withdrawn), created_at │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ business_specials │ ├─────────────────────────────────────────────────────────────────┤ │ id (uuid), sale_weekend_id (fk), wellspring_business_id, │ │ offer_text, valid_date, created_at │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ free_conversions │ ├─────────────────────────────────────────────────────────────────┤ │ id (uuid), participant_id (fk), item_description, │ │ wellspring_free_item_id (nullable - populated after sync), │ │ created_at │ └─────────────────────────────────────────────────────────────────┘ ``` ## Vibe Coding Prompt to Get