diff --git a/NORTH_STAR.md b/NORTH_STAR.md index a27bb6d..aead152 100644 --- a/NORTH_STAR.md +++ b/NORTH_STAR.md @@ -85,8 +85,12 @@ If we wait, the incumbents win. The agentic economy is being built today, and wh --- -## What's Next? +## What's next? -This document is our compass. It anchors product decisions, fundraising conversations, and go-to-market execution. +This document is a short compass. The full operating strategy is: -Now the real question: **What's the first sprint?** What can we build in the next 30 days that proves the model and starts building the data network? \ No newline at end of file +**[docs/strategy/CANONICAL_STRATEGY.md](./docs/strategy/CANONICAL_STRATEGY.md)** (final draft) + +Product detail: [docs/product/](./docs/product/). Historical exploration: [docs/archive/](./docs/archive/). + +Near-term execution question: what can we ship in the next 30 days that proves Model 1 (HTTP MCP + portal spine + real pilot endpoints) and starts a destination pilot conversation? \ No newline at end of file diff --git a/README.md b/README.md index a324101..3a322af 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,76 @@ # geolocal.io -> AI-native infrastructure for local business discovery, storytelling, visuals, and booking via MCP. Powers the long tail of independent SMBs ignored by big platforms. +AI-native infrastructure for local business discovery, storytelling, visuals, and booking via MCP. Powers the long tail of independent service businesses that big platforms do not serve cleanly in the agent era. -## What Is This? +## Start here -`geolocal.io` makes local service businesses discoverable, bookable, and payable in the agentic AI economy. +1. **[Canonical Strategy](./docs/strategy/CANONICAL_STRATEGY.md)** — operating truth (final draft) +2. **[North Star](./NORTH_STAR.md)** — short compass +3. **[Product overview](./docs/product/overview.md)** — what we build -We do this by: +## What this is -- **Hosting a multi-tenant MCP server** that exposes rich, structured business data (story, visuals, services, pricing, availability) to any AI agent. -- **Providing a simple JSON pointer** (`/.well-known/mcp-server`) that any business can add to their website to connect to our hosted MCP server—no coding required. -- **Enabling a complete transaction loop** by integrating with Cal.com for booking and Stripe for payment capture. -- **Building a partner-first distribution engine** by working through agencies, SEO consultants, and Chambers of Commerce who already serve these businesses. -- **Creating a self-reinforcing data network** where AI agents provide verification and competitive intelligence data through our "related businesses" handshake. +geolocal.io makes local service businesses discoverable, bookable, and measurable inside AI assistants by: -We are not a destination site. We are an invisible, critical layer of infrastructure that powers the agentic economy's discovery of local businesses. +- Hosting a **multi-tenant MCP** agents can call for structured business truth +- Giving businesses a **simple pointer** on their own site (no servers for them to run) +- Providing a **Self-Service Portal** so owners can see and test how AI understands them +- Working with **tourism boards, chambers, and partners** for distribution +- Integrating **Cal.com** and **Stripe** for booking and payment — we orchestrate, we do not rebuild those categories -## The Problem We Solve +We are not a consumer destination site. We are infrastructure. -- **45% of consumers** now use AI tools to find local businesses—up from just **6% one year earlier**. -- **ChatGPT recommends just 1.2% of local businesses**, according to SOCi's 2026 Local Visibility Index. -- **AI is now the third most-used business discovery channel**, behind only Google and Facebook. +## Who should read what -The major platforms (Google, Yelp, OpenAI) are building MCP infrastructure to serve their own data. They are **not** building infrastructure to serve the businesses themselves. We bridge that gap. +### Partners (agencies, SEO, chambers) -## Quick Start +1. [Ideal customer profile](./docs/gtm/ideal-customer-profile.md) +2. [Channel strategy](./docs/gtm/channel-strategy.md) and [Sales and marketing](./docs/gtm/sales-and-marketing.md) +3. [Partner one-pager](./docs/gtm/partner-one-pager.md) -### For Partners (Agencies, SEO Consultants, Chambers) +### Investors -1. Read the **[Ideal Customer Profile](./docs/gtm/Ideal%20Customer%20Profile.md)** to understand who we target. -2. Review the **[Channel Strategy](./docs/gtm/ChannelStrategy.md)** and **[Sales and Marketing](./docs/gtm/Sales%20and%20marketing.md)** for the playbook. -3. Use the **[Partner One-Pager](./docs/gtm/Partner%20One-Pager.md)** as your sell-sheet. +1. [Canonical Strategy](./docs/strategy/CANONICAL_STRATEGY.md) +2. [Market data and analysis](./docs/investors/market-data-and-analysis.md) +3. [Business and financial model](./docs/investors/business-and-financial-model.md) and [Moats and risks](./docs/gtm/competitive/moats-and-risks.md) -### For Investors +### Engineering -1. Read the **[North Star](./NORTH_STAR.md)** document for our vision and principles. -2. Review the **[Market Data & Analysis](./docs/investors/Market%20Data%20&%20Analysis.md)** for the opportunity size. -3. Explore the **[Business and Financial Model](./docs/investors/Business%20and%20financial%20model.md)** and **[Competitive Moats & Risks](./docs/gtm/Competitive%20moats%20and%20risks.md)** for our defensible position. +1. [Canonical Strategy](./docs/strategy/CANONICAL_STRATEGY.md) priorities +2. [Technical roadmap](./docs/engineering/technical-roadmap.md) +3. [code/](./code/) — MCP MVP (TypeScript) +4. [ADRs](./docs/engineering/adrs/) -### For Developers & Engineers +## Repository map (Phase A) -1. Read the **[Technical Roadmap](./docs/engineering/technical%20roadmap.md)** for our phased implementation plan. -2. Explore the **[code/](./code/)** directory for the MCP server implementation. -3. See **[package.json](./code/package.json)** for dependencies and scripts. - -## Repository Structure - -``` +```text geolocal-io/ -├── NORTH_STAR.md # Single source of truth for vision & principles -├── README.md # This file -├── code/ # MCP server implementation (TypeScript) -│ ├── src/ -│ │ ├── index.ts # Server entry point (stdio transport) -│ │ ├── mcp-server.ts # Tool registration (5 MCP tools) -│ │ ├── config.ts # Environment configuration -│ │ ├── manifest-generator.ts # /.well-known/mcp-server JSON -│ │ ├── db/ # PostgreSQL schema + seed data -│ │ ├── tools/ # get_business_info, get_hours, etc. -│ │ └── routes/ # Multi-tenant gateway -│ ├── package.json -│ ├── tsconfig.json -│ ├── Dockerfile -│ └── railway.json +├── NORTH_STAR.md +├── README.md +├── code/ # MCP server MVP (later → apps/mcp-gateway) └── docs/ - ├── investors/ # Market data, financial model - ├── gtm/ # ICP, channel strategy, partner one-pager - ├── engineering/ # Technical roadmap - └── legal/ # Data flow, partnership agreement, IP notes + ├── strategy/ # CANONICAL_STRATEGY.md (operating truth) + ├── product/ # SSP, intermediate, genre packs + ├── gtm/ # channels, sales, competitive/ + ├── investors/ + ├── engineering/ # roadmap + adrs/ + ├── legal/ + └── archive/ # historical exploration only ``` +Later monorepo phases add `apps/`, `packages/`, `genres/`, and `infra/` without changing the docs contract above. + ## Status | Area | Status | -| :--- | :--- | -| **Strategy & Vision** | ✅ Complete | -| **Market Data & Analysis** | ✅ Complete | -| **Competitive Intelligence** | ✅ Complete | -| **Business & Financial Model** | ✅ Complete | -| **Product & Technical Roadmap** | ✅ Complete | -| **GTM Strategy** | ✅ Complete | -| **Legal & Compliance** | ✅ Complete | -| **MCP Server (code/)** | ✅ MVP — 5 tools, TypeScript, Railway-ready | +|------|--------| +| **Canonical strategy** | Final draft | +| **Market / GTM / legal docs** | Present (some GTM still pre-strategy framing) | +| **Product docs** | Scaffolded | +| **MCP server (`code/`)** | MVP — 5 tools, TypeScript, Railway-ready | +| **Self-Service Portal** | Specified; not built | +| **HTTP multi-tenant gateway** | Priority 0 | +## Doc governance +If a document conflicts with [docs/strategy/CANONICAL_STRATEGY.md](./docs/strategy/CANONICAL_STRATEGY.md), fix the conflict on purpose. Historical exploration lives in [docs/archive/](./docs/archive/), not in operating GTM. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..91754d9 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,13 @@ +# Documentation + +| Folder | Role | +|--------|------| +| [strategy/](./strategy/) | **Operating truth** — start with CANONICAL_STRATEGY.md | +| [product/](./product/) | SSP, intermediate, genre packs | +| [gtm/](./gtm/) | Channels, sales, competitive | +| [investors/](./investors/) | Market and financial packaging | +| [engineering/](./engineering/) | Roadmap and ADRs | +| [legal/](./legal/) | Privacy, IP, partnership skeletons | +| [archive/](./archive/) | Historical only — not operating docs | + +Governance: if two docs disagree, resolve against strategy or deliberately change strategy. diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 0000000..9b0fdd7 --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,10 @@ +# Archive + +Historical materials kept for context. **Not operating documentation.** + +| File | What it is | +|------|------------| +| [geolocal-copilot-conversation.md](./geolocal-copilot-conversation.md) | Early exploration conversation that informed the strategy | +| [copilot-activity-history.csv](./copilot-activity-history.csv) | Activity export from that session | + +Operating truth lives in [../strategy/CANONICAL_STRATEGY.md](../strategy/CANONICAL_STRATEGY.md). diff --git a/docs/copilot-activity-history.csv b/docs/archive/copilot-activity-history.csv similarity index 100% rename from docs/copilot-activity-history.csv rename to docs/archive/copilot-activity-history.csv diff --git a/docs/geolocal-copilot-conversation.md b/docs/archive/geolocal-copilot-conversation.md similarity index 100% rename from docs/geolocal-copilot-conversation.md rename to docs/archive/geolocal-copilot-conversation.md diff --git a/docs/engineering/README.md b/docs/engineering/README.md index 9907689..c2ebb0d 100644 --- a/docs/engineering/README.md +++ b/docs/engineering/README.md @@ -1,22 +1,12 @@ -# Engineering — geolocal.io +# Engineering -Architecture, technical roadmap, and implementation. +Architecture, roadmap, and implementation notes. -## Files +| Doc | Purpose | +|-----|---------| +| [technical-roadmap.md](./technical-roadmap.md) | Phased technical plan (align with strategy when they diverge) | +| [adrs/](./adrs/) | Architecture decision records | -| File | Description | -|------|-------------| -| [Technical Roadmap](./technical%20roadmap.md) | 12-week phased plan: MVP → V1 → Scale | +**Operating priorities** come from [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§10). When this folder and the strategy disagree, fix one of them deliberately. -## Code - -The MCP server implementation lives in the repo root [`code/`](../../code/) directory: - -- **`src/index.ts`** — Server entry point (stdio transport) -- **`src/mcp-server.ts`** — Tool registration (5 MCP tools) -- **`src/tools/`** — Individual tool implementations -- **`src/db/`** — PostgreSQL schema + seed data -- **`src/manifest-generator.ts`** — `/.well-known/mcp-server` JSON manifest -- **`railway.json`** + **`Dockerfile`** — Deployment config - -Every technical decision must trace back to [NORTH_STAR.md](../../NORTH_STAR.md). +Current implementation lives in `code/` (MCP MVP). A later monorepo phase moves that to `apps/mcp-gateway`. diff --git a/docs/engineering/adrs/README.md b/docs/engineering/adrs/README.md new file mode 100644 index 0000000..cb9e3d0 --- /dev/null +++ b/docs/engineering/adrs/README.md @@ -0,0 +1,26 @@ +# Architecture Decision Records (ADRs) + +Short, dated decisions so we do not re-litigate the same choices. + +## Format + +Each ADR: `NNNN-short-title.md` + +```markdown +# NNNN — Title + +**Status:** proposed | accepted | superseded +**Date:** YYYY-MM-DD + +## Context +## Decision +## Consequences +``` + +## Index + +| ADR | Title | Status | +|-----|-------|--------| +| — | *(none yet)* | — | + +Candidates worth writing soon: HTTP vs stdio for production MCP; Cal.com orchestration vs rebuild booking; monorepo layout (Phase B). diff --git a/docs/engineering/technical roadmap.md b/docs/engineering/technical-roadmap.md similarity index 100% rename from docs/engineering/technical roadmap.md rename to docs/engineering/technical-roadmap.md diff --git a/docs/gtm/README.md b/docs/gtm/README.md index 35e8968..983e7e8 100644 --- a/docs/gtm/README.md +++ b/docs/gtm/README.md @@ -1,16 +1,14 @@ -# GTM — geolocal.io +# Go-to-market -Partner-first go-to-market strategy and collateral. +Channel, sales, and competitive materials. Must describe the company in [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) — not a thinner or different product. -## Files +| Doc | Purpose | +|-----|---------| +| [ideal-customer-profile.md](./ideal-customer-profile.md) | Who we target | +| [channel-strategy.md](./channel-strategy.md) | Distribution channels | +| [sales-and-marketing.md](./sales-and-marketing.md) | Sales and marketing playbook | +| [partner-one-pager.md](./partner-one-pager.md) | Partner sell-sheet | +| [competitive/intelligence.md](./competitive/intelligence.md) | Competitor landscape | +| [competitive/moats-and-risks.md](./competitive/moats-and-risks.md) | Moats and risks | -| File | Description | -|------|-------------| -| [Ideal Customer Profile](./Ideal%20Customer%20Profile.md) | Who we target: agencies, SEO consultants, CoCs | -| [Channel Strategy](./ChannelStrategy.md) | 3-pronged distribution: agencies, vertical subdomains, SEO | -| [Sales and Marketing](./Sales%20and%20marketing.md) | Playbook, messaging, funnel | -| [Competitive Intelligence](./Competitive%20Intelligence.md) | Competitor mapping and positioning | -| [Competitive Moats & Risks](./Competitive%20moats%20and%20risks.md) | Defensibility and threat analysis | -| [Partner One-Pager](./Partner%20One-Pager.md) | Agency sell-sheet (ready to send) | - -All content here must align with [NORTH_STAR.md](../../NORTH_STAR.md). +**Note:** Some GTM docs still reflect older partner-dashboard-first framing. Treat strategy as source of truth until those docs are revised. diff --git a/docs/gtm/ChannelStrategy.md b/docs/gtm/channel-strategy.md similarity index 100% rename from docs/gtm/ChannelStrategy.md rename to docs/gtm/channel-strategy.md diff --git a/docs/gtm/competitive/README.md b/docs/gtm/competitive/README.md new file mode 100644 index 0000000..5f5c4a7 --- /dev/null +++ b/docs/gtm/competitive/README.md @@ -0,0 +1,8 @@ +# Competitive + +| Doc | Purpose | +|-----|---------| +| [intelligence.md](./intelligence.md) | Competitor landscape | +| [moats-and-risks.md](./moats-and-risks.md) | Moats and risks | + +Parent index: [../README.md](../README.md). diff --git a/docs/gtm/Competitive Intelligence.md b/docs/gtm/competitive/intelligence.md similarity index 100% rename from docs/gtm/Competitive Intelligence.md rename to docs/gtm/competitive/intelligence.md diff --git a/docs/gtm/Competitive moats and risks.md b/docs/gtm/competitive/moats-and-risks.md similarity index 97% rename from docs/gtm/Competitive moats and risks.md rename to docs/gtm/competitive/moats-and-risks.md index 7314746..f4719ab 100644 --- a/docs/gtm/Competitive moats and risks.md +++ b/docs/gtm/competitive/moats-and-risks.md @@ -2,7 +2,7 @@ ## 0. Relationship to the Competitive Intelligence Dossier -This document is the strategic companion to the **Competitive Intelligence Dossier**, which profiles the key players in the local business AI discovery space (Yelp, Google, Pie, Mainstreet, Apify, and others). This analysis assumes familiarity with that landscape and focuses on: +This document is the strategic companion to the **[Competitive intelligence](./intelligence.md)** dossier, which profiles the key players in the local business AI discovery space (Yelp, Google, Pie, Mainstreet, Apify, and others). This analysis assumes familiarity with that landscape and focuses on: 1. **Our defensible positions:** What makes `geolocal.io` hard to replicate 2. **The unseen strength:** Why first-mover advantage and critical mass are the real moats diff --git a/docs/gtm/Ideal Customer Profile.md b/docs/gtm/ideal-customer-profile.md similarity index 100% rename from docs/gtm/Ideal Customer Profile.md rename to docs/gtm/ideal-customer-profile.md diff --git a/docs/gtm/Partner One-Pager.md b/docs/gtm/partner-one-pager.md similarity index 97% rename from docs/gtm/Partner One-Pager.md rename to docs/gtm/partner-one-pager.md index 45a254b..eb66d3c 100644 --- a/docs/gtm/Partner One-Pager.md +++ b/docs/gtm/partner-one-pager.md @@ -103,4 +103,4 @@ Or reply to this one-pager — we'll get you set up and your first client live i --- -> *Full market data and citations: [Market Data & Analysis](../investors/Market%20Data%20&%20Analysis.md)* +> *Full market data and citations: [Market data and analysis](../investors/market-data-and-analysis.md)* diff --git a/docs/gtm/Sales and marketing.md b/docs/gtm/sales-and-marketing.md similarity index 98% rename from docs/gtm/Sales and marketing.md rename to docs/gtm/sales-and-marketing.md index 4c720f0..e7ab5ea 100644 --- a/docs/gtm/Sales and marketing.md +++ b/docs/gtm/sales-and-marketing.md @@ -222,5 +222,5 @@ With `geolocal.io`: --- -> *Full market data and citations: [Market Data & Analysis](../investors/Market%20Data%20&%20Analysis.md)* -> *Full competitive analysis: [Competitive Intelligence](./Competitive%20Intelligence.md)* \ No newline at end of file +> *Full market data and citations: [Market data and analysis](../investors/market-data-and-analysis.md)* +> *Full competitive analysis: [Competitive intelligence](./competitive/intelligence.md)* \ No newline at end of file diff --git a/docs/investors/README.md b/docs/investors/README.md index d75c0eb..d7cc28b 100644 --- a/docs/investors/README.md +++ b/docs/investors/README.md @@ -1,12 +1,8 @@ -# Investors — geolocal.io +# Investors -Pitch materials, market sizing, financial model. +External packaging of market and financial material. Align narrative with [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md). -## Files - -| File | Description | -|------|-------------| -| [Market Data & Analysis](./Market%20Data%20&%20Analysis.md) | $98.8B TAM, consumer AI adoption trends | -| [Business and Financial Model](./Business%20and%20financial%20model.md) | Revenue model, unit economics, projections | - -Align everything to [NORTH_STAR.md](../../NORTH_STAR.md). +| Doc | Purpose | +|-----|---------| +| [market-data-and-analysis.md](./market-data-and-analysis.md) | Market size and adoption signals | +| [business-and-financial-model.md](./business-and-financial-model.md) | Business and financial model | diff --git a/docs/investors/Business and financial model.md b/docs/investors/business-and-financial-model.md similarity index 100% rename from docs/investors/Business and financial model.md rename to docs/investors/business-and-financial-model.md diff --git a/docs/investors/Market Data & Analysis.md b/docs/investors/market-data-and-analysis.md similarity index 100% rename from docs/investors/Market Data & Analysis.md rename to docs/investors/market-data-and-analysis.md diff --git a/docs/legal/README.md b/docs/legal/README.md index 1c6e822..d26c66c 100644 --- a/docs/legal/README.md +++ b/docs/legal/README.md @@ -1,13 +1,11 @@ -# Legal — geolocal.io +# Legal -Compliance, data flow, partnership agreements, IP notes. +Lightweight legal and compliance notes for pilots and product. -## Files +| Doc | Purpose | +|-----|---------| +| [data-flow-and-privacy.md](./data-flow-and-privacy.md) | Data flow and privacy | +| [ip-notes.md](./ip-notes.md) | IP notes | +| [partnership-agreement-skeleton.md](./partnership-agreement-skeleton.md) | Partnership agreement skeleton | -| File | Description | -|------|-------------| -| [Data Flow & Privacy](./Data%20Flow%20&%20Privacy.md) | Data collection, storage, sharing, GDPR/CCPA | -| [Partnership Agreement Skeleton](./Partnership%20Agreement%20Skeleton.md) | Template for agency/CoC partnerships | -| [IP Notes](./IP%20Notes.md) | Trademark, telemetry ownership, open-source strategy | - -Must reference [NORTH_STAR.md](../../NORTH_STAR.md) for principles. +Not a substitute for counsel. Strategy §13 calls for tourism pilot terms, business ToS, and basic telemetry privacy next. diff --git a/docs/legal/Data Flow & Privacy.md b/docs/legal/data-flow-and-privacy.md similarity index 100% rename from docs/legal/Data Flow & Privacy.md rename to docs/legal/data-flow-and-privacy.md diff --git a/docs/legal/IP Notes.md b/docs/legal/ip-notes.md similarity index 100% rename from docs/legal/IP Notes.md rename to docs/legal/ip-notes.md diff --git a/docs/legal/Partnership Agreement Skeleton.md b/docs/legal/partnership-agreement-skeleton.md similarity index 100% rename from docs/legal/Partnership Agreement Skeleton.md rename to docs/legal/partnership-agreement-skeleton.md diff --git a/docs/product/README.md b/docs/product/README.md new file mode 100644 index 0000000..e2a6f3f --- /dev/null +++ b/docs/product/README.md @@ -0,0 +1,13 @@ +# Product + +Product definitions for what we build and sell. Aligns with [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md). + +| Doc | Purpose | +|-----|---------| +| [overview.md](./overview.md) | Product map across the four models | +| [ssp.md](./ssp.md) | Self-Service Portal (primary SMB experience) | +| [intermediate.md](./intermediate.md) | Tourism boards, chambers, visitor bureaus | +| [genre-packs.md](./genre-packs.md) | Vertical primitives strategy | +| [use-cases/](./use-cases/) | Canonical use cases (to be filled) | + +These folders start thin on purpose. Expand them as decisions lock; do not reintroduce conflicting product stories in GTM-only docs. diff --git a/docs/product/genre-packs.md b/docs/product/genre-packs.md new file mode 100644 index 0000000..13f5d35 --- /dev/null +++ b/docs/product/genre-packs.md @@ -0,0 +1,18 @@ +# Genre packs + +Generic business fields are scaffolding. Durable differentiation is **genre-specific primitives** — structured tools and schemas that match how a vertical actually works. + +## Planned early packs + +- Auto repair +- Beauty +- Home services +- Tourism activity (especially with destination pilots) + +## Detail source + +[Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§5.3). + +## Repo note (future) + +Genre packs will live under top-level `genres/` in a later monorepo phase. Product intent is documented here first. diff --git a/docs/product/intermediate.md b/docs/product/intermediate.md new file mode 100644 index 0000000..673ef6f --- /dev/null +++ b/docs/product/intermediate.md @@ -0,0 +1,15 @@ +# Intermediate product (tourism, chambers, visitor bureaus) + +Model 2: destinations and membership organizations as discovery nodes. + +## Intent + +One intermediate relationship should bring many member endpoints online. Boards get an aggregating MCP, member onboarding (via SSP patterns), and a simple dashboard of hits and category demand. Funding often sits in lodging-tax or destination marketing budgets. + +## Detail source + +[Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§4 Model 2, §7 GTM wedge). + +## Build status + +Not implemented. Engineering Priority 1 after Model 1 spine is real. diff --git a/docs/product/overview.md b/docs/product/overview.md new file mode 100644 index 0000000..12549b9 --- /dev/null +++ b/docs/product/overview.md @@ -0,0 +1,20 @@ +# Product overview + +geolocal.io ships **AI-readiness infrastructure** for local services: hosted multi-tenant MCP, a discovery pointer on the business site, the Self-Service Portal, intermediate (destination/chamber) surfaces, and later telemetry and graph products. + +See [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) sections 4–5 for the full product definition and the four business models. + +## Surfaces + +| Surface | Audience | Status | +|---------|----------|--------| +| MCP gateway | AI agents | MVP in `code/` (stdio); HTTP is Priority 0 | +| Self-Service Portal | SMB owners | Specified in strategy; not built | +| Intermediate dashboard | Tourism boards / chambers | Specified; not built | +| Partner surfaces | Agencies / SEO | Distribution; after core attach | + +## Related docs + +- [ssp.md](./ssp.md) +- [intermediate.md](./intermediate.md) +- [genre-packs.md](./genre-packs.md) diff --git a/docs/product/ssp.md b/docs/product/ssp.md new file mode 100644 index 0000000..1b95dd5 --- /dev/null +++ b/docs/product/ssp.md @@ -0,0 +1,17 @@ +# Self-Service Portal (SSP) + +Primary product experience for individual local businesses (Model 1). + +## Intent + +Owners should feel the value before they pay: genre-aware onboarding, site scrape reflection, a live simulation of an AI recommending and booking them, pointer install, in-browser preflight against their MCP, optimization guidance, optional partner handoff, and ongoing reports. + +The portal chat UI is a **test harness** for how *external* AI assistants will interpret the business — not a customer-facing chatbot we sell as the product. + +## Detail source + +Full narrative and priorities: [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§5 Self-Service Portal, §10 priorities). + +## Build status + +Not implemented. Engineering Priority 0 includes the portal spine once HTTP MCP is underway. diff --git a/docs/product/use-cases/README.md b/docs/product/use-cases/README.md new file mode 100644 index 0000000..6ac1357 --- /dev/null +++ b/docs/product/use-cases/README.md @@ -0,0 +1,5 @@ +# Use cases + +Canonical use cases (Bob’s Garage, destination board, etc.) will land here as structured product specs. + +Until then, narrative examples remain in the strategy and archive; do not treat the archive as the product spec. diff --git a/docs/strategy/CANONICAL_STRATEGY.md b/docs/strategy/CANONICAL_STRATEGY.md index 9fc1a68..7cfa77f 100644 --- a/docs/strategy/CANONICAL_STRATEGY.md +++ b/docs/strategy/CANONICAL_STRATEGY.md @@ -295,13 +295,14 @@ Run self-serve SMB in parallel. Prefer short pilot contracts over perfect enterp | Document | Job | |----------|-----| -| `docs/geolocal-copilot-conversation.md` | Historical exploration archive — useful context, not the operating manual | +| `docs/archive/` | Historical exploration only — not the operating manual | | **`docs/strategy/CANONICAL_STRATEGY.md` (this file)** | **Operating strategy the team rallies around** | | `NORTH_STAR.md` | Short compass; must stay consistent with this file | +| `docs/product/*` | Product surfaces (SSP, intermediate, genre packs) | | `docs/gtm/*` | Execution detail for channels and sales; must describe this company, not a different one | | `docs/investors/*` | External packaging of this strategy | -| `docs/engineering/*` | Build plan for the priorities above | -| `code/` | Implementation of Priority 0 | +| `docs/engineering/*` | Build plan and ADRs for the priorities above | +| `code/` | Implementation of Priority 0 (later monorepo: `apps/mcp-gateway`) | If two documents disagree, either this file changes on purpose or the other document changes. Silence is how the project fractures again. diff --git a/docs/strategy/README.md b/docs/strategy/README.md new file mode 100644 index 0000000..dc11f50 --- /dev/null +++ b/docs/strategy/README.md @@ -0,0 +1,7 @@ +# Strategy + +| Doc | Role | +|-----|------| +| **[CANONICAL_STRATEGY.md](./CANONICAL_STRATEGY.md)** | Final-draft operating strategy — team plans, builds, and sells against this | + +If another doc conflicts with the canonical strategy, update that doc or deliberately revise the strategy. Do not leave both live.