# Tool Library Inventory Scout ## The Problem Community tool libraries are a beautiful form of mutual aid—neighbors sharing power drills, ladders, and sewing machines instead of everyone buying their own. But most operate on sticky notes and memory, leading to confusion about what's actually available, duplicate donations of items nobody needs, and missed opportunities to acquire the tools neighbors actually want. Without simple inventory tracking and demand signals, these libraries stay small and chaotic when they could be thriving community infrastructure. ## Who Uses It **Library Stewards** — The 1-3 volunteers who manage the tool library (often out of a church basement, community center garage, or their own shed). They need to know at a glance what's in stock, what's out on loan, and what's broken. They're usually doing this on their phone between other tasks. **Neighbors** — Community members who want to borrow tools or donate ones they no longer need. They want to quickly see if the library has a circular saw before buying one, or request that the library acquire a pressure washer for spring cleaning season. **Occasional Volunteers** — People who help with inventory days, pickup/dropoff, or scouting for free tools online. They need simple tasks they can complete in 15 minutes without training. ## Core Features 1. **Quick-Add Inventory**: Any volunteer can add a tool by snapping a photo, speaking or typing a name, and selecting a category. The system auto-suggests condition ratings (Good/Fair/Needs Repair) and generates a simple ID sticker to print. 2. **Loan Tracking with Trust**: When someone borrows a tool, a volunteer marks it out with the borrower's first name and phone number. No accounts required—the system texts a gentle reminder after 2 weeks and again at 4 weeks. Returns are one-tap. 3. **Neighbor Wish List**: Anyone can submit "I wish we had a ___" requests. The system tallies votes on existing wishes so stewards can see demand patterns. Wishes display how many neighbors want each item. 4. **Free Item Scout Integration**: The system pulls nearby free items from WellSpr.ing and highlights matches for your wish list or inventory gaps. "Someone's giving away a table saw 2 miles away" with one-tap directions. 5. **Seasonal Pattern Dashboard**: Simple visualization showing when certain tools get requested most. "Ladders spike in April" or "Sewing machines trend in October-November" helps stewards plan acquisition and maintenance timing. 6. **Condition & Maintenance Log**: Each tool tracks its history—when it was last serviced, any repairs needed, and a simple "flag for attention" button any volunteer can tap when something seems off. 7. **Public Catalog View**: A simple browsable page (no login) where neighbors can see current available inventory and the wish list, with a "Text us to borrow" call-to-action that uses reach_number for privacy. ## WellSpr.ing Integration Points ### MCP Tools (via POST to https://wellspr.ing/mcp using JSON-RPC 2.0) **`get_free_items`** — *Core integration*. Poll regularly (or on-demand) to fetch free items being given away nearby. Filter results for tool-related keywords and surface matches against your inventory gaps and wish list. Display these as "Restock Opportunities" for stewards to claim. ```json { "jsonrpc": "2.0", "method": "get_free_items", "params": { "location": "02139" }, "id": 1 } ``` **`reach_number`** — Generate privacy-preserving contact numbers for the public catalog. Neighbors can text to inquire about borrowing without exposing the steward's personal number or requiring the neighbor to create an account. **`ask_ody`** — Power a simple "Ask about tools" feature where neighbors can describe their project ("I need to remove a tree stump") and get suggestions for which tools in your inventory might help, plus links to how-to resources. **`search_civic_services`** — Help stewards discover if their city has official tool lending programs, hazardous waste disposal for broken power tools, or grants for community lending libraries. **`get_civic_ideas`** — Display community ideas related to tool sharing, maker spaces, or repair cafes. Let stewards see what adjacent communities are thinking about. ### REST Endpoints **`GET https://wellspr.ing/api/geo/portals?area_code=NNN`** — On initial setup, fetch the local portal info to properly scope free item searches and understand the library's service area. ### Future: Covenant Commerce (Roadmap — not yet live) When WellSpr.ing's merchant and payment rails are available, the Tool Library could: - Accept small donations ("buy a new blade for the circular saw") - Coordinate paid delivery/pickup for mobility-limited neighbors - Enable inter-library tool transfers between adjacent communities *Do not build to these yet—they're on the roadmap but not active.* ## Data Model ### `tools` | Field | Type | Notes | |-------|------|-------| | id | uuid | Primary key | | name | string | "Circular Saw", "Extension Ladder 20ft" | | category | enum | POWER_TOOL, HAND_TOOL, GARDEN, KITCHEN, CRAFT, OTHER | | photo_url | string | Stored image reference | | condition | enum | GOOD, FAIR, NEEDS_REPAIR, RETIRED | | added_date | timestamp | | | notes | text | "Blade recently sharpened", "Missing case" | ### `loans` | Field | Type | Notes | |-------|------|-------| | id | uuid | | | tool_id | fk | References tools | | borrower_name | string | First name only | | borrower_phone | string | For reminder texts | | checked_out | timestamp | | | due_date | timestamp | Default: 2 weeks out | | returned_at | timestamp | Null while out | ### `wishes` | Field | Type | Notes | |-------|------|-------| | id | uuid | | | item_description | string | "Pressure washer", "Tile cutter" | | requested_by | string | Optional first name | | created_at | timestamp | | | vote_count | integer | Neighbors can +1 | | fulfilled | boolean | Steward marks when acquired | ### `maintenance_log` | Field | Type | Notes | |-------|------|-------| | id | uuid | | | tool_id | fk | | | logged_at | timestamp | | | action | enum | SERVICED, REPAIRED, FLAGGED, NOTE | | notes | text | "Replaced cord", "Blade dull" | ### `seasonal_stats` (derived/aggregated) | Field | Type | Notes | |-------|------|-------| | month | integer | 1-12 | | category | enum | | | loan_count | integer | Historical aggregate | | wish_count | integer | | ## Vibe Coding Prompt to Get Started Paste this into Claude, Cursor, or Replit Agent: --- **Build a Tool Library Inventory Scout web app with these specs:** **Stack:** React frontend + Express backend, SQLite database (easy to deploy, no config). Use Tailwind CSS for styling. Deploy target: Replit or Vercel. **First Milestone (2-hour target):** Get the core inventory working. 1. Create the database schema with tables: `tools`, `loans`, `wishes`, `maintenance_log` 2. Build these screens: - **Inventory List**: Shows all tools with photo thumbnails,