Add Owner MCP spec document (post-MVP) to docs

docs/owner-mcp.md

@@ -0,0 +1,32 @@
+# Owner MCP (post‑MVP)
+
+**Purpose** – a dedicated MCP endpoint for *business owners* (and their trusted assistants) to manage their listing *outside* the public discovery flow. It is the *conversational* channel that lets owners:
+
+- Rescan their website for freshness
+- Add temporary notices (e.g. “closed for funeral”, “holiday hours”)
+- Set dated promotional offers
+- Accept or reject pending site‑diff suggestions
+- View and climb the badge ladder (Bronze → Platinum)
+- Query roll‑up telemetry for their own listing
+
+**Auth model** – OAuth 2.0 with scopes per listing (`view`, `edit`, `badge`). Tokens are stored in the Hermes profile `ha_researcher` under `oauth/geolocal-io`. The Owner MCP server runs on a separate port (`:9234`) behind Caddy with JWT validation. Public discovery MCP must *not* expose any of these tools.
+
+**Tool catalog** (exposed to owners via chat in Grok/ChatGPT)
+
+| Tool | Description | Required scope |
+|------|-------------|----------------|
+| `request_rescan` | Triggers an immediate origin fetch; returns `crawl_status` and a diff preview. | `edit` |
+| `set_temporary_notice` | Sets a time‑boxed notice (e.g. “closed Tue for funeral”). | `edit` |
+| `set_dated_offer` | Adds a promotional offer with start/end dates (used for the “July 4th bucket special”). | `edit` |
+| `accept_diff` | Marks a pending site‑diff as approved; updates the portal DB. | `edit` |
+| `list_pending_diffs` | Returns diffs awaiting owner confirmation. | `view` |
+| `badge_status` | Returns current badge tier, blockers, and roll‑up metrics. | `view` |
+| `get_demand_summary` | Demand themes, volume, funnel intent % for the last 30 days. | `view` |
+
+**Interaction pattern (owner chat)** – Example: *Owner*: “Add a notice that we’re closed on Dec 25”. *Owner MCP* receives `set_temporary_notice`, writes to portal, returns `notice_id` and an updated badge status. The next weekly email will reflect the new notice in the “site report”.
+
+**Security** – All calls are authenticated; the MCP logs `owner_id`, `listing_id`, `tool`, and a short `event_hash` (SHA‑256 of the payload). No raw site HTML is ever stored; only portal‑derived fields are mutated.
+
+**Relation to public MCP** – The public discovery MCP serves **structured business truth**; the Owner MCP is a *privileged* API that can *mutate* that truth. The two are separate servers behind the same Caddy instance, but share the same user model and badge engine.
+
+---