Compare commits
51 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 VPS admin
|
a11f8626db | ||
 HA_Researcher
|
f03db2a30e | ||
|
VPS admin
|
4d04a4a65a | ||
|
VPS admin
|
9478aaa22e | ||
|
VPS admin
|
3f9c86f823 | ||
 Ty
|
36853f3bab | ||
|
Ty
|
4be326ffda | ||
|
Ty
|
1a13f14d70 | ||
|
Ty
|
0265bcf628 | ||
|
Ty
|
06a1d85293 | ||
|
Ty
|
267d85b201 | ||
|
Ty
|
626e4a04a0 | ||
|
HA_Researcher
|
689dc4cee5 | ||
|
Ty
|
dfb487db9b | ||
|
Ty
|
a264265bd9 | ||
|
Ty
|
3376fb97bb | ||
|
Ty
|
e930ff2576 | ||
|
Ty
|
ab1c19a246 | ||
|
Ty
|
29521273d2 | ||
|
Ty
|
cfa146dc7c | ||
|
Ty
|
7d25705760 | ||
|
Ty
|
6c09d6c311 | ||
|
Ty
|
3bd59b6d2b | ||
|
Ty
|
2be10ce42c | ||
|
Ty
|
4def4d0726 | ||
|
Ty
|
0038630b04 | ||
|
Ty
|
f083742850 | ||
|
Ty
|
9d6ca48404 | ||
|
Ty
|
998a3ef7d8 | ||
|
Ty
|
5103b62b3f | ||
|
Ty
|
aaf0861187 | ||
|
Ty
|
7220069743 | ||
|
Ty
|
b931910e7c | ||
|
Ty
|
4d3debdeb7 | ||
|
Ty
|
06b08db8c4 | ||
|
Ty
|
443de58e18 | ||
|
Ty
|
aafae3f097 | ||
|
Ty
|
7ac170c58f | ||
|
Ty
|
ad916b02f2 | ||
|
Ty
|
433cc8707b | ||
|
Ty
|
a49e4c9cc1 | ||
|
Ty
|
e842618c01 | ||
|
Ty
|
a989deebc0 | ||
|
Ty
|
cb4c4f470d | ||
|
Ty
|
3b50730a62 | ||
|
Ty
|
ae641dec22 | ||
|
Ty
|
50cfeca56e | ||
|
Ty
|
8ab44ec880 | ||
|
Ty
|
a5175d234f | ||
|
Ty
|
07c3075ede | ||
|
Ty
|
3368571128 |
@@ -0,0 +1,98 @@
|
||||
# geolocal.io — North Star
|
||||
|
||||
---
|
||||
|
||||
## What Is It?
|
||||
|
||||
geolocal.io is the infrastructure that makes **local businesses** — services and local retail with real-world presence — discoverable, understandable, and actionable inside the agentic AI economy.
|
||||
|
||||
Here's what we actually do:
|
||||
|
||||
- Host a multi-tenant MCP server that gives AI agents structured access to a business's story, hours, services or assortment signals, specialties, visuals, and the right next step (book, visit, pick up).
|
||||
- Give businesses a dead-simple pointer on their website (well-known or multi-path). No coding. No servers for them to manage. It points to us.
|
||||
- Orchestrate booking and payment partners where those paths apply — we do not rebuild Calendly or Shopify.
|
||||
- Sell through self-serve, agencies, SEO consultants, tourism boards, and Chambers — people who already have the trust of business owners.
|
||||
- Build feedback and quality loops so helpfulness improves over time, including removing bad endpoints when they hurt trust.
|
||||
|
||||
We are not a destination site. We don't compete with Yelp or Google for user attention. We're the invisible layer that makes the long tail of local businesses actually work in the AI era — the garage **and** the general store.
|
||||
|
||||
---
|
||||
|
||||
## Why Are We Building This?
|
||||
|
||||
Because the agentic economy is being built right now, and almost every local business is being left out.
|
||||
|
||||
- 45% of consumers now use AI tools to find local businesses—up from 6% a year ago. That's one of the fastest behavioral shifts we've ever seen.
|
||||
- ChatGPT recommends just 1.2% of local businesses. That's based on SOCi's 2026 Local Visibility Index, which looked at over 350,000 business locations.
|
||||
- AI is already the third most-used discovery channel for local businesses, behind only Google and Facebook.
|
||||
- ChatGPT now has roughly 900 million weekly active users.
|
||||
- 58% of consumers have tried AI for local business recommendations; 31% do it at least monthly.
|
||||
- 44% of AI-search users now say AI is their primary information source—ahead of traditional search at 31%.
|
||||
|
||||
Yelp has already released an official MCP server. Google is integrating MCP into Merchant Center and Maps. OpenAI is signing licensing deals left and right. They're building infrastructure for *their* data. They're not building infrastructure for the businesses themselves.
|
||||
|
||||
That's the gap. We're building the on-ramp for everyone else.
|
||||
|
||||
---
|
||||
|
||||
## What Happens If We Don't Build This?
|
||||
|
||||
The local service economy gets locked into the same handful of platforms that already dominate the web.
|
||||
|
||||
If we don't do this:
|
||||
|
||||
- Yelp becomes the default source of truth for AI recommendations. They already charge $25 per 1,000 API calls for their Fusion AI service. That's the model—pay to play.
|
||||
- Google tightens its grip on both the data and the transaction layer.
|
||||
- AI agents only recommend the 1.2% of businesses that are already visible. The rest stay invisible.
|
||||
- The 98.8% end up paying for visibility through ads and licensing fees they can't afford.
|
||||
- Agencies and Chambers have no independent infrastructure to offer their clients—they're stuck reselling access to platforms that control everything.
|
||||
- Agentic booking starts in late 2026, not years from now. As BrightLocal's CEO put it, if an agent is looking for a plumber at 6am and your business isn't bookable through the agent, it'll move on to the next one that is. No human ever sees your name.
|
||||
|
||||
The alternative is a future where local businesses are passive subjects of platforms that own their data and control their destiny. geolocal.io is the counterplay—a platform that lets businesses own their AI presence.
|
||||
|
||||
---
|
||||
|
||||
## When Must This Be Done?
|
||||
|
||||
This is a race. The incumbents aren't asleep.
|
||||
|
||||
- MCP adoption is exploding: 97 million+ monthly SDK downloads as of March 2026, up from ~100,000 at launch in late 2024. Over 10,000 active MCP servers are now deployed.
|
||||
- Every major AI platform ships native MCP support: ChatGPT, Claude, Gemini, Copilot, Cursor.
|
||||
- Yelp's official MCP server is live.
|
||||
- Google is actively integrating MCP into its Merchant API and Maps.
|
||||
- OpenAI is building agentic commerce and inking data deals.
|
||||
|
||||
The window is not years. It's months.
|
||||
|
||||
| Timeframe | What We Need to Hit |
|
||||
| :--- | :--- |
|
||||
| 90 Days | Launch MCP server and partner dashboard. Onboard 100 businesses through agency partners. |
|
||||
| 180 Days | Expand to 1,000 businesses across 3 verticals (auto repair, beauty, home services). Launch "related businesses" handshake. |
|
||||
| 360 Days | Secure 3 major Chamber of Commerce partnerships. Reach 10,000 businesses. Start monetizing telemetry data. |
|
||||
|
||||
If we wait, the incumbents win. The agentic economy is being built today, and whoever builds the infrastructure owns the future. geolocal.io needs to be the infrastructure for the 98.8%—before the 1.2% lock in their dominance.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Question | Answer |
|
||||
| :--- | :--- |
|
||||
| **What is it?** | MCP infrastructure that makes local service businesses discoverable, bookable, and transactable in the agentic economy. |
|
||||
| **Why are we building it?** | To bridge the gap between the 98.8% of businesses invisible to AI and the 1.2% that dominate recommendations. |
|
||||
| **What happens if we don't?** | Yelp, Google, and OpenAI will control the data and transaction layer, locking out the vast majority of local businesses. |
|
||||
| **When must it be done?** | Within 360 days. The incumbents are moving fast, and the window is closing. |
|
||||
|
||||
---
|
||||
|
||||
## What's next?
|
||||
|
||||
This document is a short compass. The full operating strategy is:
|
||||
|
||||
**[docs/strategy/CANONICAL_STRATEGY.md](./docs/strategy/CANONICAL_STRATEGY.md)** (final draft)
|
||||
|
||||
Product map: [docs/product/](./docs/product/).
|
||||
Use cases: [UC-01](./docs/product/use-cases/uc-01-endpoint-auto-repair.md), [UC-02](./docs/product/use-cases/uc-02-intermediate-tourism-board.md), [UC-03](./docs/product/use-cases/uc-03-local-retail-general-store.md).
|
||||
Historical exploration: [docs/archive/](./docs/archive/).
|
||||
|
||||
Near-term execution: ship Priority 0 platform (HTTP MCP, ingestion, first genre pack, portal spine, real endpoints) and open one destination pilot conversation — without confusing the portal for the whole company.
|
||||
@@ -1,39 +1,79 @@
|
||||
# geolocal.io — planning-selfserve-audit
|
||||
# geolocal.io
|
||||
|
||||
**Working review branch:** `review/ready` (from `planning-selfserve-audit`, itself from `planning-rev2` 2026-09-15 session). Not a clone of `main`. Do not merge main docs here.
|
||||
AI-native infrastructure for local business discovery via MCP. Powers the long tail of independent brick-and-mortar — services **and** local retail — that big platforms do not serve cleanly in the agent era.
|
||||
|
||||
## Map (locked)
|
||||
## Start here
|
||||
|
||||
| Path | Role |
|
||||
| :--- | :--- |
|
||||
| `docs/BUSINESS_PLAN.md` | **Only** home for the business idea / strategy / GTM / wedge / workflow / MCP / packaging |
|
||||
| `docs/GLOSSARY.md` | Industry terms only |
|
||||
| `docs/product/genre-packs.md` | Layer A/B/C index (how we surface work to owners) |
|
||||
| `docs/product/genre-packs/` | Field SoT (`SOURCES.md`, `core3-field-map.md`) + genre notes (`salon.md`, `bakery.md`) |
|
||||
| `docs/evidence/` | Sourced research notes (cite URL) — not strategy |
|
||||
| `docs/SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md` | Self-serve AI discoverability concept + phased plan (amend in place; one SoT) |
|
||||
| `docs/CONVENTIONS.md` | Anti-duplication docs rules (one-concept-one-file) |
|
||||
| `docs/writing-rules.md` | Outsider-first writing rules for strategy/research prose |
|
||||
| `docs/ALTERNATE_BUSINESS_PROPOSAL.md` | Alternate commercial thesis (ticket-set / warehouse); does not amend concept SoT |
|
||||
| `docs/research-brief.pdf` | PDF packaging of research brief / alternate proposal |
|
||||
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)** — platform vs activation
|
||||
4. **[Use cases](./docs/product/use-cases/)** — UC-01 services, UC-02 tourism, UC-03 local retail
|
||||
|
||||
## Placement rules (agents must follow)
|
||||
## What this is
|
||||
|
||||
1. Strategy / GTM / wedge / owner workflow / surfaces / MCP / distribution / packaging → **fold into** `docs/BUSINESS_PLAN.md`. Never spawn a sibling strategy file.
|
||||
2. New industry term → `docs/GLOSSARY.md`.
|
||||
3. Platform field / API / UI claim → open `SOURCES.md`, update field map. No invented matrices.
|
||||
4. External survey / report → `docs/evidence/<SOURCE>-<year>.md` with source URL. Link from the plan; don't paste essays into the plan.
|
||||
5. **No new `docs/*` top-level folder** unless Ty explicitly approves.
|
||||
6. Checkpoint log stays **inside** `BUSINESS_PLAN.md` (trim; don't spawn `DECISIONS.md`).
|
||||
7. Two "layer" vocabularies — keep them distinct:
|
||||
- **Layer A/B/C** = how we surface work (universal / genre / known-for) → `genre-packs.md`
|
||||
- **Beyond NAP** = shared basics → provider extras → provider stacks → section inside `BUSINESS_PLAN.md`
|
||||
8. Self-serve AI discoverability concept / phased plan → amend `docs/SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md` only (see `docs/CONVENTIONS.md`). Do not spawn PLAN/CONCEPT twins.
|
||||
9. `docs/ALTERNATE_BUSINESS_PROPOSAL.md` is an explicit alternate thesis file already on this lineage; do not fold it into the concept SoT without Ty saying so.
|
||||
geolocal.io makes **local businesses** discoverable and actionable inside AI assistants by:
|
||||
|
||||
## Process
|
||||
- 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 booking, payment, and later inventory partners where those paths apply — we orchestrate, we do not rebuild Shopify or Calendly
|
||||
|
||||
- **SEO & AEO Desk** = sole scribe + conversation SME on this branch.
|
||||
- Essence of agreed direction only; mark provisional until Ty locks.
|
||||
- Nothing locked until Ty says so.
|
||||
- Never invent Core 3 fields — use `docs/product/genre-packs/SOURCES.md`.
|
||||
Scope includes **local services and local retail** with real presence (see strategy §1a). Pure online e-commerce is out of scope.
|
||||
|
||||
We are not a consumer destination site. We are infrastructure.
|
||||
|
||||
## Who should read what
|
||||
|
||||
### Partners (agencies, SEO, chambers)
|
||||
|
||||
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)
|
||||
|
||||
### Investors
|
||||
|
||||
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)
|
||||
|
||||
### Engineering
|
||||
|
||||
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/)
|
||||
|
||||
## Repository map (Phase A)
|
||||
|
||||
```text
|
||||
geolocal-io/
|
||||
├── NORTH_STAR.md
|
||||
├── README.md
|
||||
├── code/ # MCP server MVP (later → apps/mcp-gateway)
|
||||
└── docs/
|
||||
├── 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 |
|
||||
|------|--------|
|
||||
| **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.
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
node_modules/
|
||||
dist/
|
||||
.env
|
||||
*.log
|
||||
@@ -0,0 +1,12 @@
|
||||
FROM node:22-alpine
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
COPY package.json package-lock.json* ./
|
||||
RUN npm ci --production
|
||||
|
||||
COPY dist/ ./dist/
|
||||
|
||||
EXPOSE 3000
|
||||
|
||||
CMD ["node", "dist/index.js"]
|
||||
@@ -0,0 +1,30 @@
|
||||
# code/ — LEGACY SKELETON (DO NOT USE)
|
||||
|
||||
**Status:** Archived / deprecated. Written by a rogue AI agent. Not the path forward.
|
||||
|
||||
This directory contains a legacy MCP server prototype that is **out of date and should not be built upon**:
|
||||
|
||||
## What's wrong with it
|
||||
|
||||
- **stdio-only transport** — `index.ts` uses `StdioServerTransport`. Cannot be called remotely by Claude, ChatGPT, or any external AI agent. The MVP requires an HTTP endpoint (SSE or Streamable HTTP).
|
||||
- **Manifest-server contradiction** — `manifest-generator.ts` advertises `protocol: 'streamable-http'` but the server is stdio. The manifest lies.
|
||||
- **Gateway is a stub** — `gateway.ts` is 10 lines of placeholder comments. No actual multi-tenant routing.
|
||||
- **Schema is incomplete** — `schema.ts` has a single `businesses` table with no tenant/location model, no freshness/telemetry fields, no badge state, no portal data. Doesn't support the strategy.
|
||||
- **No polling, no freshness, no assessment** — None of the critical Day 2-N mechanics from the strategy (polling, content hashing, JIT refresh, assessment gates, badge ladder) are implemented.
|
||||
- **No downstream handoff** — Cal.com/Stripe/Square integration is a config string, not real integration.
|
||||
- **No HTTP server** — `fastify` is in `package.json` but never wired up. No routes, no transport, no deployment target.
|
||||
|
||||
## What replaced it
|
||||
|
||||
The strategy and product design live in `docs/`:
|
||||
|
||||
- `docs/strategy/CANONICAL_STRATEGY.md` — Operating strategy
|
||||
- `docs/product/` — Use cases, SSP spec, genre packs
|
||||
- `docs/engineering/technical-roadmap.md` — Technical architecture
|
||||
- `docs/gtm/` — GTM, ICP, competitive analysis
|
||||
|
||||
Future engineering code will live in `apps/` (per the monorepo structure) with proper HTTP MCP transport, multi-tenant gateway, polling infrastructure, and portal.
|
||||
|
||||
## Action
|
||||
|
||||
This directory is **preserved for reference only**. Do not extend it. Future work happens in `apps/`.
|
||||
Generated
+2456
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,27 @@
|
||||
{
|
||||
"name": "geolocal-io-mcp",
|
||||
"version": "0.1.0",
|
||||
"description": "Multi-tenant MCP server for geolocal.io \u2014 AI-native local business discovery",
|
||||
"type": "module",
|
||||
"main": "dist/index.js",
|
||||
"scripts": {
|
||||
"dev": "tsx src/index.ts",
|
||||
"build": "tsc",
|
||||
"start": "node dist/index.js",
|
||||
"seed": "tsx src/db/seed.ts",
|
||||
"test": "tsx --test tests/*.ts"
|
||||
},
|
||||
"dependencies": {
|
||||
"@modelcontextprotocol/sdk": "^1.0.0",
|
||||
"fastify": "^5.0.0",
|
||||
"pg": "^8.13.0",
|
||||
"dotenv": "^16.4.0",
|
||||
"zod": "^3.24.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"tsx": "^4.0.0",
|
||||
"typescript": "^5.7.0",
|
||||
"@types/pg": "^8.11.0",
|
||||
"@types/node": "^22.0.0"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"$schema": "https://railway.app/railway.schema.json",
|
||||
"build": {
|
||||
"builder": "DOCKERFILE",
|
||||
"dockerfilePath": "./Dockerfile"
|
||||
},
|
||||
"deploy": {
|
||||
"startCommand": "npm start",
|
||||
"healthcheckPath": "/health",
|
||||
"healthcheckTimeout": 100,
|
||||
"restartPolicyType": "ON_FAILURE",
|
||||
"restartPolicyMaxRetries": 10
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
export const config = {
|
||||
port: parseInt(process.env.PORT || '3000', 10),
|
||||
databaseUrl: process.env.DATABASE_URL || 'postgresql://localhost:5432/geolocal',
|
||||
calcomBaseUrl: process.env.CALCOM_BASE_URL || 'https://api.cal.com',
|
||||
stripeApiKey: process.env.STRIPE_API_KEY || '',
|
||||
};
|
||||
@@ -0,0 +1,37 @@
|
||||
import { Pool } from 'pg';
|
||||
import { config } from '../config.js';
|
||||
|
||||
const pool = new Pool({ connectionString: config.databaseUrl });
|
||||
|
||||
export async function initSchema() {
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS businesses (
|
||||
id SERIAL PRIMARY KEY,
|
||||
slug VARCHAR(255) UNIQUE NOT NULL,
|
||||
name VARCHAR(500) NOT NULL,
|
||||
category VARCHAR(100),
|
||||
address TEXT,
|
||||
city VARCHAR(200),
|
||||
state VARCHAR(50),
|
||||
zip VARCHAR(20),
|
||||
phone VARCHAR(50),
|
||||
website VARCHAR(500),
|
||||
hours JSONB DEFAULT '{}',
|
||||
services JSONB DEFAULT '[]',
|
||||
story TEXT,
|
||||
owner_bio TEXT,
|
||||
photos JSONB DEFAULT '[]',
|
||||
calcom_link VARCHAR(500),
|
||||
mcp_endpoint VARCHAR(500),
|
||||
related_business_ids INTEGER[] DEFAULT '{}',
|
||||
created_at TIMESTAMP DEFAULT NOW(),
|
||||
updated_at TIMESTAMP DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_businesses_slug ON businesses(slug);
|
||||
CREATE INDEX IF NOT EXISTS idx_businesses_category ON businesses(category);
|
||||
CREATE INDEX IF NOT EXISTS idx_businesses_city_state ON businesses(city, state);
|
||||
`);
|
||||
}
|
||||
|
||||
export { pool };
|
||||
@@ -0,0 +1,36 @@
|
||||
import { pool, initSchema } from './schema.js';
|
||||
|
||||
async function seed() {
|
||||
await initSchema();
|
||||
|
||||
await pool.query(`
|
||||
INSERT INTO businesses (slug, name, category, address, city, state, zip, phone, website, hours, services, story, calcom_link, photos)
|
||||
VALUES (
|
||||
'frisco-german-auto',
|
||||
'Frisco German Auto Specialists',
|
||||
'auto-repair',
|
||||
'1234 Main St',
|
||||
'Frisco',
|
||||
'TX',
|
||||
'75034',
|
||||
'(469) 555-0123',
|
||||
'https://friscogermanauto.example.com',
|
||||
'{"monday_friday": "8AM-6PM", "saturday": "9AM-3PM", "sunday": "closed"}',
|
||||
'[
|
||||
{"name": "Oil Change", "price": 65, "description": "Full synthetic oil change for European vehicles"},
|
||||
{"name": "Brake Inspection", "price": 100, "description": "Complete brake system inspection and quote"},
|
||||
{"name": "Diagnostics", "price": 150, "description": "Computer diagnostics for check engine light and electrical issues"},
|
||||
{"name": "Tire Rotation", "price": 40, "description": "Tire rotation and balancing"}
|
||||
]',
|
||||
'Family-run shop with 40 years of experience, specializing in BMW, Mercedes, and Audi. We treat every car like our own.',
|
||||
'https://cal.com/friscogermanauto',
|
||||
'["https://example.com/photos/shop-front.jpg", "https://example.com/photos/service-bay.jpg"]'
|
||||
)
|
||||
ON CONFLICT (slug) DO NOTHING;
|
||||
`);
|
||||
|
||||
console.log('\u2705 Seed data inserted');
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
seed().catch(console.error);
|
||||
@@ -0,0 +1,26 @@
|
||||
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
||||
import { createMCPServer } from './mcp-server.js';
|
||||
import { initSchema } from './db/schema.js';
|
||||
import { config } from './config.js';
|
||||
|
||||
async function main() {
|
||||
// Initialize database
|
||||
await initSchema();
|
||||
console.error('\u2705 Database schema initialized');
|
||||
|
||||
// Create and start MCP server
|
||||
const server = createMCPServer();
|
||||
const transport = new StdioServerTransport();
|
||||
|
||||
await server.connect(transport);
|
||||
|
||||
console.error(`\u2705 geolocal.io MCP server v0.1.0 running`);
|
||||
console.error(` Port: ${config.port}`);
|
||||
console.error(` Tools: get_business_info, get_hours, get_services, get_booking_link, get_related_businesses`);
|
||||
console.error(` Discovery: /.well-known/mcp-server`);
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error('\u274C Failed to start:', err);
|
||||
process.exit(1);
|
||||
});
|
||||
@@ -0,0 +1,71 @@
|
||||
import { pool } from './db/schema.js';
|
||||
|
||||
interface ManifestConfig {
|
||||
businessSlug: string;
|
||||
serverBaseUrl: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate the /.well-known/mcp-server JSON manifest.
|
||||
*
|
||||
* Businesses (or their agencies) upload this file to their website root
|
||||
* at `/.well-known/mcp-server`. AI agents discover it automatically.
|
||||
*/
|
||||
export function generateManifest(config: ManifestConfig): Record<string, any> {
|
||||
const { businessSlug, serverBaseUrl } = config;
|
||||
return {
|
||||
mcp_server: `${serverBaseUrl}/mcp/${businessSlug}`,
|
||||
protocol: 'streamable-http',
|
||||
version: '0.1.0',
|
||||
business: businessSlug,
|
||||
provider: 'geolocal.io',
|
||||
discovery: {
|
||||
transport: 'stdio',
|
||||
tools: [
|
||||
'get_business_info',
|
||||
'get_hours',
|
||||
'get_services',
|
||||
'get_booking_link',
|
||||
'get_related_businesses',
|
||||
],
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
export async function getManifestForBusiness(
|
||||
businessSlug: string,
|
||||
serverBaseUrl: string = 'https://mcp.geolocal.io'
|
||||
): Promise<Record<string, any>> {
|
||||
const result = await pool.query(
|
||||
`SELECT slug, name, mcp_endpoint FROM businesses WHERE slug = $1`,
|
||||
[businessSlug]
|
||||
);
|
||||
|
||||
if (result.rows.length === 0) {
|
||||
throw new Error(`Business '${businessSlug}' not found`);
|
||||
}
|
||||
|
||||
const b = result.rows[0];
|
||||
const baseUrl = b.mcp_endpoint || serverBaseUrl;
|
||||
return generateManifest({ businessSlug, serverBaseUrl: baseUrl });
|
||||
}
|
||||
|
||||
/**
|
||||
* CLI: Generate a manifest file for a given business slug.
|
||||
* Usage: npx tsx src/manifest-generator.ts --slug=frisco-german-auto
|
||||
*/
|
||||
async function cli() {
|
||||
const args = process.argv.slice(2);
|
||||
const slugArg = args.find((a) => a.startsWith('--slug='));
|
||||
if (!slugArg) {
|
||||
console.error('Usage: npx tsx src/manifest-generator.ts --slug=<business-slug>');
|
||||
process.exit(1);
|
||||
}
|
||||
const slug = slugArg.split('=')[1];
|
||||
const manifest = await getManifestForBusiness(slug);
|
||||
console.log(JSON.stringify(manifest, null, 2));
|
||||
}
|
||||
|
||||
if (process.argv[1]?.includes('manifest-generator')) {
|
||||
cli().catch(console.error);
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
||||
import { z } from 'zod';
|
||||
import { getBusinessInfo } from './tools/get-business-info.js';
|
||||
import { getHours } from './tools/get-hours.js';
|
||||
import { getServices } from './tools/get-services.js';
|
||||
import { getBookingLink } from './tools/get-booking-link.js';
|
||||
import { getRelatedBusinesses } from './tools/get-related-businesses.js';
|
||||
|
||||
/** Wrap a plain object result into MCP CallToolResult format */
|
||||
function toToolResult(data: Record<string, any>) {
|
||||
const isError = 'error' in data;
|
||||
return {
|
||||
content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
|
||||
...(isError && { isError: true }),
|
||||
};
|
||||
}
|
||||
|
||||
const SlugSchema = { slug: z.string().describe('Business slug identifier (e.g., "frisco-german-auto")') };
|
||||
|
||||
export function createMCPServer() {
|
||||
const server = new McpServer({
|
||||
name: 'geolocal.io',
|
||||
version: '0.1.0',
|
||||
});
|
||||
|
||||
server.tool('get_business_info', SlugSchema, async (args) => {
|
||||
const result = await getBusinessInfo(args);
|
||||
return toToolResult(result);
|
||||
});
|
||||
|
||||
server.tool('get_hours', SlugSchema, async (args) => {
|
||||
const result = await getHours(args);
|
||||
return toToolResult(result);
|
||||
});
|
||||
|
||||
server.tool('get_services', SlugSchema, async (args) => {
|
||||
const result = await getServices(args);
|
||||
return toToolResult(result);
|
||||
});
|
||||
|
||||
server.tool('get_booking_link', SlugSchema, async (args) => {
|
||||
const result = await getBookingLink(args);
|
||||
return toToolResult(result);
|
||||
});
|
||||
|
||||
server.tool('get_related_businesses', SlugSchema, async (args) => {
|
||||
const result = await getRelatedBusinesses(args);
|
||||
return toToolResult(result);
|
||||
});
|
||||
|
||||
return server;
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
||||
|
||||
// Multi-tenant MCP gateway — routes requests to the correct business
|
||||
// MVP: single MCP server serves all businesses
|
||||
// Future: route to per-tenant MCP instances or regional shards
|
||||
export function createGateway(server: McpServer) {
|
||||
// The McpServer handles its own request routing via the transport layer.
|
||||
// This gateway is a placeholder for future multi-tenant routing.
|
||||
return { server };
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
import { pool } from '../db/schema.js';
|
||||
|
||||
export async function getBookingLink(params: { slug: string }): Promise<Record<string, any>> {
|
||||
const result = await pool.query(
|
||||
`SELECT calcom_link, name FROM businesses WHERE slug = $1`,
|
||||
[params.slug]
|
||||
);
|
||||
|
||||
if (result.rows.length === 0) {
|
||||
return { error: `Business '${params.slug}' not found` };
|
||||
}
|
||||
|
||||
const b = result.rows[0];
|
||||
return {
|
||||
business: b.name,
|
||||
booking_url: b.calcom_link,
|
||||
message: `Book an appointment with ${b.name} via Cal.com`,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
import { pool } from '../db/schema.js';
|
||||
|
||||
export async function getBusinessInfo(params: { slug: string }): Promise<Record<string, any>> {
|
||||
const result = await pool.query(
|
||||
`SELECT name, category, address, city, state, zip, phone, website, story, owner_bio, photos
|
||||
FROM businesses WHERE slug = $1`,
|
||||
[params.slug]
|
||||
);
|
||||
|
||||
if (result.rows.length === 0) {
|
||||
return { error: `Business '${params.slug}' not found` };
|
||||
}
|
||||
|
||||
const b = result.rows[0];
|
||||
return {
|
||||
name: b.name,
|
||||
category: b.category,
|
||||
location: { address: b.address, city: b.city, state: b.state, zip: b.zip },
|
||||
phone: b.phone,
|
||||
website: b.website,
|
||||
story: b.story,
|
||||
owner_bio: b.owner_bio,
|
||||
photos: JSON.parse(b.photos),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
import { pool } from '../db/schema.js';
|
||||
|
||||
export async function getHours(params: { slug: string }): Promise<Record<string, any>> {
|
||||
const result = await pool.query(
|
||||
`SELECT hours FROM businesses WHERE slug = $1`,
|
||||
[params.slug]
|
||||
);
|
||||
|
||||
if (result.rows.length === 0) {
|
||||
return { error: `Business '${params.slug}' not found` };
|
||||
}
|
||||
|
||||
return { hours: JSON.parse(result.rows[0].hours) };
|
||||
}
|
||||
@@ -0,0 +1,58 @@
|
||||
import { pool } from '../db/schema.js';
|
||||
|
||||
export async function getRelatedBusinesses(params: { slug: string }): Promise<Record<string, any>> {
|
||||
const result = await pool.query(
|
||||
`SELECT id, slug, name, category, city, state, story, related_business_ids
|
||||
FROM businesses
|
||||
WHERE slug = $1`,
|
||||
[params.slug]
|
||||
);
|
||||
|
||||
if (result.rows.length === 0) {
|
||||
return { error: `Business '${params.slug}' not found` };
|
||||
}
|
||||
|
||||
const business = result.rows[0];
|
||||
const relatedIds = JSON.parse(business.related_business_ids || '[]');
|
||||
|
||||
if (relatedIds.length === 0) {
|
||||
// Fallback: same category, same city
|
||||
const fallback = await pool.query(
|
||||
`SELECT slug, name, category, city, state, story
|
||||
FROM businesses
|
||||
WHERE category = $1 AND city = $2 AND slug != $3
|
||||
LIMIT 5`,
|
||||
[business.category, business.city, params.slug]
|
||||
);
|
||||
|
||||
return {
|
||||
source_business: business.name,
|
||||
related: fallback.rows.map((r: any) => ({
|
||||
slug: r.slug,
|
||||
name: r.name,
|
||||
category: r.category,
|
||||
location: `${r.city}, ${r.state}`,
|
||||
story: r.story,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
// Resolve related business IDs
|
||||
const relatedResult = await pool.query(
|
||||
`SELECT slug, name, category, city, state, story
|
||||
FROM businesses
|
||||
WHERE id = ANY($1)`,
|
||||
[relatedIds]
|
||||
);
|
||||
|
||||
return {
|
||||
source_business: business.name,
|
||||
related: relatedResult.rows.map((r: any) => ({
|
||||
slug: r.slug,
|
||||
name: r.name,
|
||||
category: r.category,
|
||||
location: `${r.city}, ${r.state}`,
|
||||
story: r.story,
|
||||
})),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
import { pool } from '../db/schema.js';
|
||||
|
||||
export async function getServices(params: { slug: string }): Promise<Record<string, any>> {
|
||||
const result = await pool.query(
|
||||
`SELECT services FROM businesses WHERE slug = $1`,
|
||||
[params.slug]
|
||||
);
|
||||
|
||||
if (result.rows.length === 0) {
|
||||
return { error: `Business '${params.slug}' not found` };
|
||||
}
|
||||
|
||||
return { services: JSON.parse(result.rows[0].services) };
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "bundler",
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"resolveJsonModule": true,
|
||||
"declaration": true
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
@@ -1,145 +0,0 @@
|
||||
# Alternate business proposal: fix the warehouses that feed AI
|
||||
|
||||
**Branch:** `planning-selfserve-audit`
|
||||
**Status:** Working draft 2026-10-01 — action-plan-first rewrite
|
||||
**Relationship to SoT:** Not a replacement for [`SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md`](./SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md). That file stays the product architecture SoT. Amend or kill when Ty locks or rejects this.
|
||||
|
||||
---
|
||||
|
||||
## The North Star
|
||||
|
||||
From [`BUSINESS_PLAN.md`](./BUSINESS_PLAN.md) §1 (“North star (wording still open)”). **Verbatim:**
|
||||
|
||||
> **Intent (stable):** Enable local businesses to be discovered and recommended by AI assistants.
|
||||
>
|
||||
> Still wordsmithing the exact sentence. The job does not change while the phrasing does.
|
||||
|
||||
On this branch we score that intent as two outcomes:
|
||||
|
||||
1. **Present and accurately represented** wherever a local business is discovered — including AI answers, Google, Apple, Bing, Yelp, and the directory copies underneath.
|
||||
2. **Recommendable** — if someone asks an AI for a business like yours nearby, would it pick you, and would it get the facts right?
|
||||
|
||||
Longer-term destination in the concept SoT (not version one): an industry graph the industry can use. Version one earns that by making the two outcomes above true in today’s assistants, with the owner’s consent.
|
||||
|
||||
PDF export of the RESEARCH BRIEF below: [`docs/research-brief.pdf`](./research-brief.pdf).
|
||||
|
||||
---
|
||||
|
||||
## RESEARCH BRIEF
|
||||
|
||||
### The North Star
|
||||
|
||||
From [`BUSINESS_PLAN.md`](./BUSINESS_PLAN.md) §1. **Verbatim:**
|
||||
|
||||
> **Intent (stable):** Enable local businesses to be discovered and recommended by AI assistants.
|
||||
>
|
||||
> Still wordsmithing the exact sentence. The job does not change while the phrasing does.
|
||||
|
||||
Scored here as: present and accurately represented wherever discovery happens; recommendable when someone asks an AI for a business like yours nearby. Industry graph = longer-term, not version one.
|
||||
|
||||
---
|
||||
|
||||
### 1. The bakery owner’s pain
|
||||
|
||||
Picture a bakery owner who keeps losing easy customers. People show up after closing because the hours online are wrong. Others call a disconnected number and never call back. A few say they asked an assistant for a nearby bakery and got pointed somewhere else — or got her shop with the old phone number.
|
||||
|
||||
She sits down on a Tuesday night to fix this. She updates Google — new phone, new weekend hours — and thinks customers will find the right info everywhere. They will not. The same details still sit wrong on Yelp, Bing, Apple Maps, and dozens of directories. When someone asks ChatGPT or Gemini “where’s a good bakery near me?”, the assistant often pulls from those scattered, outdated copies. Sometimes the shop never shows up. Sometimes it shows up with last year’s number. She never sees the miss.
|
||||
|
||||
Fixing one listing is not the same as being findable and accurately described wherever people discover local businesses today — including when they ask AI.
|
||||
|
||||
There is a second pain that shows up the moment she tries to do anything serious about it: **proving the shop is hers.** Before an honest audit or before anyone will let her overwrite warehouse data, someone has to verify she is the owner or authorized stakeholder — email code, phone ping, postcard, or login to Google. That step is easy to skip in a pitch deck and miserable in real life. She is already tired. She does not have an agency. She may not control the email on the old listing. If the action plan ignores that friction, it is not an action plan she can finish alone — and the stale copies keep winning.
|
||||
|
||||
---
|
||||
|
||||
### 2. Peel the onion — the root problem
|
||||
|
||||
The industry still sells last year’s scoreboard: polish Google, collect reviews, push listings, score how “complete” your profile looks inside their software, track map rank. That can bring more Google calls. Almost none of those products answer: what do AI assistants actually say about my business — do they find me, recommend me, and get the facts right?
|
||||
|
||||
Peel further. Wrong hours and phone numbers do not mainly come from one bad Yelp page. A handful of **business-data warehouses** collect and copy your facts into directories, maps, navigation apps, and the pools assistants read from:
|
||||
|
||||
- [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/) (formerly Infogroup)
|
||||
- [TransUnion Digital Business Profile / Localeze](https://neustarlocaleze.biz/)
|
||||
- [Foursquare Places](https://foursquare.com/products/business-listings/) (absorbed Factual in 2020)
|
||||
- Plus networks agencies buy as bundles: GPS Network, YP Network, Active Sync Plus ([BrightLocal’s aggregator list](https://www.brightlocal.com/learn/data-aggregators/))
|
||||
|
||||
Vendors profit from the mess: paid “completeness” hubs, annual trusted-stamps, syndication subscriptions that degrade when you cancel. Updating Google or Yelp alone often fails because those warehouses keep shipping the old version downstream. Acxiom’s directory products retired end of 2019; Factual is not a separate claim surface anymore — don’t build around dead names.
|
||||
|
||||
---
|
||||
|
||||
### 3. Action plan — what we build
|
||||
|
||||
**A. Stakeholder verify, then AI-assistant audit as the scoreboard.**
|
||||
First, prove the person is allowed to act for the business (code to a known email, phone check, or linked Google ownership — whatever keeps impostors out without making a tired owner give up). Then ask the major assistants the questions a real customer would ask. Show them: did they find you, recommend you, get the facts right? That verified audit is why someone signs up — not a completeness score inside our software, not a map-rank tracker. Without the verify step, warehouse pushes and “fix my data” tickets are either blocked or unsafe.
|
||||
|
||||
**B. Push verified facts into the root warehouses and the trusted sites — and track acceptance.**
|
||||
|
||||
| Warehouse / surface | What we do |
|
||||
| --- | --- |
|
||||
| Data Axle | Free claim/verify for roughly 1–10 locations; Premium / Submission API + teleresearch when scale or hard changes need it |
|
||||
| Localeze / TransUnion | Paid manage when required (~$99/year per location); treat Completeness as “fill the hub so partners trust the row,” not an AI audit |
|
||||
| Foursquare | Prefer **owner claim** (authoritative). Use Placemaker / partner APIs with **edit-status tracking** when we submit at scale — community votes alone are not owner authority |
|
||||
| Google, Apple, Bing, Yelp | Still correct the big sites people and machines trust; Google is useful proof and where many customers double-check after an AI suggestion |
|
||||
| BrightLocal-class reseller pipes | Optional scale lane — not the identity of the product |
|
||||
|
||||
We do not stop at “submitted a form.” We track whether the warehouse accepted the update.
|
||||
|
||||
**C. Respect sync clocks and trusted-freshness.**
|
||||
When tools push through common pipes: Data Axle can move in real time; Foursquare often weekly (and one-way); Localeze often monthly. Localeze partners commonly publish in **30–90 days**. Trusted / managed stamps often last about **twelve months** — then freshness decays unless you renew or re-verify. We schedule for that, and we tell the owner the wait.
|
||||
|
||||
**D. Re-ask AI after syncs; chase the upstream feed still poisoning copies.**
|
||||
Same assistant questions again. Better findability and accuracy — or we did not earn the win. If one surface is still wrong, diagnose which warehouse is still feeding it and chase that source.
|
||||
|
||||
**E. No cancel-hostage product.**
|
||||
Owner keeps control of their truth. We are not a subscription that vanishes or corrupts listings when they leave (industry pattern documented when heavy syndication stops — see Whitespark’s Yext-cancel audit).
|
||||
|
||||
**Why this is a business.** Owners already pay for Maps tools and listing packs that ignore the warehouse layer. Customers ask AI for local recommendations far more than a year ago. Almost nobody both fixes the root data companies and proves it by re-checking the assistants.
|
||||
|
||||
---
|
||||
|
||||
### Supporting research (named sources)
|
||||
|
||||
**Data Axle.** Free Local Listings for about 1–10 locations (claim, phone-verify, unlimited updates marketed free). Ten-plus: Premium / Excel / Submission API; human teleresearch on hard changes; files can take hours to ~2 weeks; failed listings can sit ~90 days. Partners include search, directories, nav, virtual assistants; marketing now cites AI-driven search. ([Data Axle Local Listings](https://www.data-axle.com/marketing-solutions/local-listings-management/); [Yext × Data Axle](https://www.yext.com/integrations/publishers/data-axle) — real-time.)
|
||||
|
||||
**Localeze / TransUnion.** ~$99/year per location (public SMB / BrightLocal writeups). 80–90+ distribution partners. Completeness Score = hub attribute fill-in for partner confidence — not a web/AI audit. Most partners process updates in **30–90 days**; Google sync can be minutes if linked. Cancel → they stop certifying owner-managed accuracy to partners. ([BrightLocal aggregators guide](https://www.brightlocal.com/learn/data-aggregators/); [Duda Localeze FAQ](https://support.duda.co/hc/en-us/articles/360060106534-Neustar-Localeze); [TransUnion LP](https://www.transunion.com/lp/digital-business-profiles).) Yext → Localeze cadence: **monthly**.
|
||||
|
||||
**Foursquare Places.** Owner claim via Foursquare for Business. Community Placemaker suggest-edit needs votes before apply. Developer `suggest/edit` + status APIs (and Managed Users for higher-trust product edits). BrightLocal notes Places used by ChatGPT and powers apps like Uber / Nextdoor. Yext → Foursquare: **weekly**, one-way. ([Placemaker docs](https://docs.foursquare.com/data-products/docs/get-started-with-the-placemaker-tools); [suggest-edit API](https://docs.foursquare.com/fsq-developers-places/reference/place-suggest-edit); [BrightLocal](https://www.brightlocal.com/learn/data-aggregators/).)
|
||||
|
||||
**BrightLocal.** Reseller into Data Axle, Localeze/Neustar, Foursquare, GPS Network, YP Network, Active Sync Plus (~15 credits per aggregator submission; Active Sync Plus higher). Campaigns often finish in ~7 business days; marketing promise that most go live/updated within ~38 days or free extras. Aggregator “trusted” window ~12 months. Not a root warehouse — a paid pipe.
|
||||
|
||||
**Yext cancel pattern.** [Whitespark audit](https://whitespark.ca/blog/what-happens-when-you-cancel-yext/): large share of listings wrong or gone after cancel; Yext says it leaves data and does not “steal” listings — publishers still fall back to other feeds. Product implication: don’t build a hostage pipe.
|
||||
|
||||
**Retired.** Acxiom directory/local-search products EOY 2019. Factual → Foursquare April 2020.
|
||||
|
||||
**AI vs Maps (why the scoreboard must be AI).** BrightLocal Local AI Visibility: Maps mention ~66% vs AI surfaces ~32–38%. SOCi LVI 2026: ChatGPT recommends ~1.2% of brand locations vs ~35.9% in Google’s short list of three. Insites: assistants often misstate name/address/phone even when they “know” the shop; schema/llms.txt barely correlate. No clean published study that aggregator cleanup alone → +X% AI mentions — do not invent one. Sell measurable re-ask improvement.
|
||||
|
||||
**Practitioner snapshots (r/localseo — observational, not replicated):** ~73% shops invisible to 4+ of 6 AI engines in a 50-business audit ([1slake5](https://www.reddit.com/r/localseo/comments/1slake5/)); GBP completeness call lifts are Maps-lane attributions with confounders; “Maps opt, AI flat” anecdotes exist ([1o08abp](https://www.reddit.com/r/localseo/comments/1o08abp/)).
|
||||
|
||||
---
|
||||
|
||||
### What we are not selling
|
||||
|
||||
| Anti-pattern | Why |
|
||||
| --- | --- |
|
||||
| Completeness score as the product | Localeze hub fill-in ≠ what AI says |
|
||||
| Citation blast / cleanup-only as AI ROI | No clean published cleanup → AI-mention study |
|
||||
| Schema / llms.txt as the lever | Insites: barely correlates |
|
||||
| Hostage syndication | Cancel degradation (Whitespark); trusted stamp expiry |
|
||||
| Foursquare “60–70% of ChatGPT local” as fact | **UNVERIFIED** when phrased as “reports suggest” |
|
||||
| Dead umbrellas (Acxiom, standalone Factual) | Retired / merged |
|
||||
|
||||
---
|
||||
|
||||
### Open questions
|
||||
|
||||
1. Promise: “Am I discoverable by AI?” vs “Does AI describe me correctly?”
|
||||
2. Which assistants in v1?
|
||||
3. How automated is accuracy vs owner compare-to-claim?
|
||||
4. Localeze / Data Axle: pay inside product, refer, or use pipes the owner already has — without pretending free Localeze control exists?
|
||||
5. Foursquare Managed Users in v1 or later?
|
||||
6. Keep this file as GTM ladder beside the concept SoT, or merge later?
|
||||
|
||||
---
|
||||
|
||||
### Capture
|
||||
|
||||
2026-10-01 — restructured action-plan-first (pain → warehouse root → plan) after aggregator-layer research. Concept SoT unchanged.
|
||||
@@ -1,236 +0,0 @@
|
||||
# geolocal.io — Business Plan (working draft)
|
||||
|
||||
**Branch:** `planning-selfserve-audit` (review packaging on `review/ready`)
|
||||
**Status:** In progress — conversation checkpoint, not final
|
||||
**Purpose:** **Only** durable home for the business idea on this branch. Fold strategy here; do not spawn sibling strategy docs.
|
||||
|
||||
**How we work this file**
|
||||
- Checkpoint after solid decisions (or when a phrase must not be lost).
|
||||
- Prefer revising this over spawning parallel strategy docs.
|
||||
- Mark unknowns as open questions. Do not invent market numbers here.
|
||||
- Nothing is locked until Ty says so.
|
||||
- Scribe the **essence** of agreed direction. Do not promote open packaging into POR until it sticks.
|
||||
- **Scribe:** SEO & AEO Desk (sole).
|
||||
|
||||
---
|
||||
|
||||
## 1. North star (wording still open)
|
||||
|
||||
**Intent (stable):** Enable local businesses to be discovered and recommended by AI assistants.
|
||||
|
||||
Still wordsmithing the exact sentence. The job does not change while the phrasing does.
|
||||
|
||||
---
|
||||
|
||||
## 2. What the company is
|
||||
|
||||
Infrastructure — not a consumer destination.
|
||||
|
||||
- Host structured business truth so AI assistants can discover, understand, and recommend local businesses (services and local retail with real-world presence).
|
||||
- Give the business a simple way to point at that truth (no servers for them to run).
|
||||
- Orchestrate booking / payment / related partners where needed; do not rebuild Calendly or Shopify.
|
||||
- Stay invisible to end consumers; win by being useful to agents and trustworthy to owners.
|
||||
|
||||
**Not:** another Yelp/Google for human browsing attention.
|
||||
|
||||
---
|
||||
|
||||
## 3. Who we serve
|
||||
|
||||
**Primary customer:** the business owner.
|
||||
|
||||
By extension:
|
||||
- Someone in their organization acting for them
|
||||
- A partner they already trust (agency, SEO, chamber, tourism board)
|
||||
|
||||
Partners are a **path to the owner**, not a different product.
|
||||
|
||||
---
|
||||
|
||||
## 4. How demand shows up (two moments)
|
||||
|
||||
1. **Presence for other AIs** — When a consumer’s assistant asks for a local plumber / salon / store, structured geolocal data can be consulted and acted on.
|
||||
2. **Owner (or their AI) asks for help** — “How do we help our business be discovered by AI?” Invest in scenarios where the owner’s own AI can diagnose and set that up — not only human sales through agencies.
|
||||
|
||||
Same north star; different moments of truth.
|
||||
|
||||
---
|
||||
|
||||
## 5. Wedge and flywheel (direction agreed)
|
||||
|
||||
**Preferred wedge:** a free AI-visibility checkup.
|
||||
|
||||
Why:
|
||||
- Shows immediate value / need
|
||||
- Builds critical mass
|
||||
- Small free actions amplify adoption
|
||||
|
||||
**Long-term reputation bet:** become so useful and dense that AI systems default to checking geolocal for local-class queries — analogous to how they lean on Yelp or Foursquare today.
|
||||
|
||||
**Strategic read:** free usefulness → coverage → agent trust → more local queries resolved via geolocal → more owners want in → denser graph.
|
||||
|
||||
Evidence (category signal, not brand list): [`docs/evidence/SBE-TECH-USE-SURVEY-2026.md`](./evidence/SBE-TECH-USE-SURVEY-2026.md) — high AI tool use among SMBs; research/content dominate; local discovery gap; peer/WOM trust path.
|
||||
|
||||
---
|
||||
|
||||
## 6. Owner experience
|
||||
|
||||
### 6.1 Initial workflow (working direction)
|
||||
|
||||
1. Arrive on an **outcome promise** (not plumbing)
|
||||
2. Tell us the business
|
||||
3. **Validation gate** — prove you represent the business
|
||||
4. Dual-scoreboard audit in owner language + ranked foundation gaps
|
||||
5. Short punch list (3–7 actions)
|
||||
6. Optional durable step (minimal owned geolocal record on free path)
|
||||
7. Return hook for re-check
|
||||
|
||||
### 6.2 Surfaces (working direction)
|
||||
|
||||
- **V1:** `geolocal.io/getstarted` (or similar) with **inline AI chat** driving intake — not forms-first.
|
||||
- **Parallel from day one (design):** owner-agent → Owner MCP (same workflow).
|
||||
- Thin status page behind login can hold the scorecard later.
|
||||
- Web chat = on-ramp + control; agent-to-agent = scale + distribution.
|
||||
|
||||
**Hard rule:** chat and MCP are **clients of one backend workflow** (verify → dual-score audit → punch list). If they diverge, we’ve built two products.
|
||||
|
||||
### 6.3 Entry / discoverability angles (working — capture, not all build now)
|
||||
|
||||
Partner paths, search, owner’s own AI asking “how do we get discovered,” later marketplace listings — prioritize by trust (peers/WOM) and where the discovery question is asked.
|
||||
|
||||
### 6.4 Phase 1 conversation tone
|
||||
|
||||
Speak **outcomes**, not plumbing. Example: “most recommended bakery on Whidbey Island for muffins.” Do not lead with MCP, endpoints, or `llms.txt`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Scorecard and tiers
|
||||
|
||||
### 7.1 Owner-facing scorecard (working — not locked)
|
||||
|
||||
Three top-line outcomes (wording TBD), each with plain “why not yet”:
|
||||
|
||||
1. **AI knows you exist** — findable identity / NAP / listings
|
||||
2. **AI knows what you do** — services, specialties, hours
|
||||
3. **AI would recommend you** — trust + fit for a real job in a place
|
||||
|
||||
Not a 40-row SEO audit. Dual scoreboard: hygiene feeds rungs 1–2; recommendability is differentiation. How we *measure* “would recommend” (heuristics vs live assistant checks) stays open.
|
||||
|
||||
### 7.2 Discovery foundation + AI readiness
|
||||
|
||||
**Two tiers, one product story** (owner language):
|
||||
|
||||
1. **Discovery foundation** — Core listings + NAP/hours/category/contact consistency (internal: “2017”)
|
||||
2. **AI readiness** — known-for queries, scorecard, structured presence when ready (internal: “2027”)
|
||||
|
||||
Measure both early; *fix* foundation first when broken. Skip invented hygiene if already clean.
|
||||
|
||||
**Owner vocab:** Core listings; The Core 3 (GBP, Apple Business Connect, Bing Places).
|
||||
|
||||
**Foundation bar** (brick-and-mortar local) — not reviews, photo perfection, or ranking #1:
|
||||
|
||||
1. One clear identity — correct NAP; no competing duplicates
|
||||
2. Claimed Core 3 (genre/market adds are separate)
|
||||
3. Accurate hours
|
||||
4. Right category + short plain “what you do”
|
||||
5. Reachable — working phone and/or website/contact
|
||||
6. Not contradictory — site vs Core 3 agree on name/place/hours
|
||||
|
||||
**Foundation sync (P1)** across Core 3: NAP + primary category + hours + website URL + short description + service-area/address mode. P2 (attributes, photos, menus, booking, secondary categories) is genre/known-for gated.
|
||||
|
||||
### 7.3 Surfacing work — Layer A / B / C
|
||||
|
||||
Not one giant schema. **A** universal Discovery foundation → **B** thin genre pack → **C** known-for overlay. Scorecard first, then 3–7 actions max by impact.
|
||||
|
||||
Index + packs: [`docs/product/genre-packs.md`](./product/genre-packs.md).
|
||||
|
||||
### 7.4 Beyond NAP — provider capability ladder
|
||||
|
||||
*(Absorbed from former `LAYERS-BEYOND-NAP.md` — do not re-spawn that file.)*
|
||||
|
||||
Distinct from Layer A/B/C (what work we show). This is what providers can hold:
|
||||
|
||||
1. **Shared listing basics (Core 3)** — category, hours, website, description, service-area mode
|
||||
2. **Provider listing extras** — GBP services/posts/actions/attrs; Apple Good to Know / hours types; Bing thinner
|
||||
3. **Provider stacks** — Apple Stack (brand → Maps+Wallet/Pay, Showcases, Actions, Insights); Google = rich but fragmented listing + adjacent products
|
||||
|
||||
**Why owners care:** NAP = findable; extras = know what you do; stacks/actions = chosen and acted on.
|
||||
|
||||
Field SoT: [`docs/product/genre-packs/core3-field-map.md`](./product/genre-packs/core3-field-map.md). Sources: [`SOURCES.md`](./product/genre-packs/SOURCES.md).
|
||||
|
||||
**Later proof layer (not free first-hour):** platform KPI telemetry (e.g. Apple Insights). Show only what platforms return — never invent numbers. Fit = ongoing AI readiness / retention.
|
||||
|
||||
### 7.5 Validation gate (essence)
|
||||
|
||||
Anyone using GeoLocal tools must pass a **business-representation check** first. Mechanism and free/silver/gold allotments stay open until COGS is real.
|
||||
|
||||
### 7.6 Free path after checkup (not locked)
|
||||
|
||||
1. Ranked DIY punch list
|
||||
2. Mint of a **minimal owned geolocal record** — densify does not wait for paid
|
||||
|
||||
Soft upsell: “comfortable DIY, or want GeoLocal to help?”
|
||||
|
||||
**Bundles (free/silver/gold):** pinned open — capture value-prop angles first, then revisit.
|
||||
|
||||
### 7.7 Paid “help” vs product (not locked)
|
||||
|
||||
- **Paid listing cleanup** = partner / agency **fulfillment**, not the product.
|
||||
- **Product** = owned geolocal record + ongoing AI-readiness score (and later agent-facing presence).
|
||||
|
||||
Do not document GeoLocal as a local SEO shop with extra steps.
|
||||
|
||||
---
|
||||
|
||||
## 8. Distribution investment (working direction)
|
||||
|
||||
**Invest in one portable Owner MCP** wired to the geolocal.io backend (same workflow as chat). Thin adapters/listings second — not five one-off apps.
|
||||
|
||||
| Priority | Surface | Call |
|
||||
| :--- | :--- | :--- |
|
||||
| P0 | Owner MCP + web chat | Build / debug privately first |
|
||||
| P1 | GrokBot (dogfood) → Claude Connectors / ChatGPT plugins / Grok connectors | Thin listings on the **same** MCP |
|
||||
| P2 | Square OAuth (optional) | Only if it shortens verify/NAP — not a second product |
|
||||
| P3 | Square App Marketplace listing | **Defer** until free-checkup proof; marketplace onboarding without Partnerships contact was paused (2026) |
|
||||
|
||||
**Debug sequence:** private/local MCP → Ty + GrokBot → harden auth/rate limits → public listings. Remote connectors need a public MCP URL when opened.
|
||||
|
||||
**Anti-pattern:** separate “GeoLocal for Square / GPT / Claude” codebases.
|
||||
|
||||
---
|
||||
|
||||
## 9. Business plan audience (still open)
|
||||
|
||||
Primary reader for v1 structure: internal / investors / partners — pick one first.
|
||||
|
||||
---
|
||||
|
||||
## 10. Inputs (not on this branch)
|
||||
|
||||
`main` holds older planning (north star, canonical strategy, SSP use cases, etc.). Treat as **raw material only** — do not re-import into this branch. Resolve conflicts on purpose in this file when pulling an idea over.
|
||||
|
||||
Evidence and field sources that *are* on this branch live under `docs/evidence/` and `docs/product/genre-packs/SOURCES.md`.
|
||||
|
||||
---
|
||||
|
||||
## 11. Checkpoint log (trim, don’t spawn)
|
||||
|
||||
| When | What landed |
|
||||
| :--- | :--- |
|
||||
| 2026-09-15 | North star; owner-first; partner path; owner-AI “get discovered”; free checkup wedge; reputation flywheel |
|
||||
| 2026-09-15 | Dual scoreboard; Discovery foundation → AI readiness; Core 3 vocab; foundation six-point bar; P1 sync fields |
|
||||
| 2026-09-15 | Layer A/B/C; sourced Core 3 field map; salon/bakery application notes; Apple API names BLOCKED when gated |
|
||||
| 2026-09-15 | Validation gate essence; free DIY + minimal record; paid cleanup = fulfillment; bundles pinned open |
|
||||
| 2026-09-15 | Owner workflow + V1 chat + Owner MCP same backend; distribution: one MCP, thin AI adapters, defer Square Marketplace |
|
||||
| 2026-09-15 | Unslop: locked placement map; absorbed beyond-NAP into this file; evidence/ folder; Desk = sole scribe |
|
||||
|
||||
---
|
||||
|
||||
## Next conversation topics
|
||||
|
||||
1. Wordsmith scorecard rungs + plain “why not yet” evidence
|
||||
2. How to measure “would recommend” honestly
|
||||
3. Primary reader for v1 of this plan
|
||||
4. Offer / packaging after value-prop angles captured
|
||||
5. First 3–5 Owner MCP tools (owner-facing)
|
||||
6. 90-day proof: what “AI checks us” requires in coverage/quality
|
||||
@@ -1,61 +0,0 @@
|
||||
# Docs conventions (anti-duplication)
|
||||
|
||||
**Branch applicability:** whole repo; written on `planning-selfserve-audit` after repeated near-duplicate markdown sprawl.
|
||||
**Scope:** `docs/**/*.md` (and any future top-level strategy markdown).
|
||||
|
||||
These rules exist so agents and humans **do not** create sibling files like `…_PLAN.md` next to `…_CONCEPT.md` for the same subject.
|
||||
|
||||
---
|
||||
|
||||
## 1. One concept = one file
|
||||
|
||||
Before creating **any** new markdown file under `docs/`:
|
||||
|
||||
1. Search existing paths and titles for **similar names** or **overlapping topics**.
|
||||
2. If overlap exists → **update the existing file** (amend in place).
|
||||
3. Only create a new file when the topic is genuinely new and no current file owns it.
|
||||
|
||||
## 2. Naming — one canonical name per topic
|
||||
|
||||
- Pick a **single** canonical filename per subject and stick to it.
|
||||
- Do **not** create variants that differ mainly by role suffix, including but not limited to: `PLAN`, `CONCEPT`, `DRAFT`, `NOTES`, `OUTLINE`, `BRIEF`, `SPEC`, `V2`.
|
||||
- Bad: `SELF_SERVE_AI_DISCOVERABILITY_PLAN.md` + `SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md`.
|
||||
- Good: one `SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md` that holds both concept and phased plan.
|
||||
|
||||
## 3. “Write a plan / concept / brief” means amend
|
||||
|
||||
If a task says write a plan, concept, brief, or execution outline for something that **already has a file**, **amend that file**. Never add a sibling with a near-identical stem.
|
||||
|
||||
Current example SoT: [`SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md`](./SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md).
|
||||
|
||||
## 4. Deletes and consolidations
|
||||
|
||||
- **Deleting** a docs file requires an **explicit** instruction (user or locked task).
|
||||
- Consolidations: **merge** unique content into the surviving file, **then** delete the duplicate(s). Do not leave two near-names “for later.”
|
||||
|
||||
## 5. Announce path before create
|
||||
|
||||
Every new docs file must be **announced with its exact path** before creation (in the working chat/call). If the announced path overlaps an existing topic, stop and amend instead.
|
||||
|
||||
---
|
||||
|
||||
## Quick checklist (agents)
|
||||
|
||||
- [ ] Grepped / listed `docs/` for similar stems and topics
|
||||
- [ ] Confirmed no PLAN/CONCEPT/DRAFT twin for the same subject
|
||||
- [ ] Amending existing SoT when topic already exists
|
||||
- [ ] Exact path announced before any `docs/` create
|
||||
- [ ] Consolidation ends with a single surviving file
|
||||
|
||||
---
|
||||
|
||||
## Automation note
|
||||
|
||||
As of 2026-10-01 this repo has **no** Gitea Actions / `.gitea` / `.github` CI and only stock `.git/hooks/*.sample` files. Guardrails are **documented here** until CI or an active pre-commit hook is added. Prefer enforcing via this file + review rather than inventing hook infrastructure without a project standard.
|
||||
|
||||
---
|
||||
|
||||
## Capture
|
||||
|
||||
Added after consolidating the self-serve AI discoverability PLAN+CONCEPT duplicate on `planning-selfserve-audit`.
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
# Glossary
|
||||
|
||||
Running definitions for industry terms used in geolocal.io planning.
|
||||
**Rule:** first use in a thread explains the term; after that the acronym is fine. Add new entries here when a term appears.
|
||||
|
||||
| Term | Meaning |
|
||||
| :--- | :--- |
|
||||
| **NAP** | **N**ame, **A**ddress, **P**hone — the core business identity fields. Local search (and AI assistants that lean on local listings) need NAP to be consistent across Google, Apple Maps, Bing, Yelp, the website, and any owned record. Mismatches confuse ranking and recommendations. |
|
||||
| **GBP** | **G**oogle **B**usiness **P**rofile — Google’s local business listing (formerly Google My Business). Hours, categories, services, photos, and reviews owners manage for Maps / Search visibility. |
|
||||
| **Apple Business Connect** | Apple’s tool for managing how a business appears in Apple Maps, Siri, and related Apple surfaces. |
|
||||
| **Bing Places** | Microsoft’s local business listing for Bing and related Microsoft surfaces. |
|
||||
| **Core listings** | Owner-facing term for the main places customers (and AI) look a business up. Prefer this over “citations” / “directories” with owners. |
|
||||
| **Core 3** | The common US min-bar listing set: GBP, Apple Business Connect, Bing Places. Genre/market adds (Yelp, Facebook, TripAdvisor, vertical dirs) are separate. |
|
||||
| **Discovery foundation** | Owner-facing name for tier 1: Core listings + NAP/hours/category/contact consistency (internally: “2017”). |
|
||||
| **AI readiness** | Owner-facing name for tier 2: known-for / recommendability scorecard and structured presence when ready (internally: “2027”). |
|
||||
| **Apple Stack** | Owner-facing name for Apple Business brand/place-card capabilities above NAP: Brand logo/Style Guide, cover into Maps + Wallet/Pay, Showcases, Actions, Insights — a unified brand OS, not just a Maps pin. |
|
||||
| **Listings pack** | Per-provider capability model (what GBP / Apple / Bing can hold above NAP). Distinct from **genre pack** (what a salon vs bakery must prove). |
|
||||
|
||||
| **Owner MCP** | GeoLocal’s Model Context Protocol server for owners (or their AIs): same verify → audit → punch list workflow as the web chat, exposed as tools. One server; thin adapters to Claude / ChatGPT / Grok / GrokBot. |
|
||||
| **Layer A / B / C** | How GeoLocal surfaces work: **A** universal Discovery foundation, **B** genre pack, **C** known-for. Distinct from the beyond-NAP provider capability ladder. |
|
||||
@@ -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.
|
||||
@@ -1,290 +0,0 @@
|
||||
# How local businesses get AI to recommend them
|
||||
|
||||
**Branch:** `planning-selfserve-audit` (from `planning-rev2`)
|
||||
**Status:** Working draft from conversation on 2026-10-01; cluster cut revised after GBP mapping pressure test the same day
|
||||
**Related:** [`BUSINESS_PLAN.md`](./BUSINESS_PLAN.md) · conventions in [`CONVENTIONS.md`](./CONVENTIONS.md)
|
||||
|
||||
This is the single working doc for the self-serve “Am I discoverable by AI?” idea — both the *why* and the phased *how*. Revise this file in place. Do not add a sibling PLAN or CONCEPT file for the same subject.
|
||||
|
||||
---
|
||||
|
||||
## What we are trying to do
|
||||
|
||||
The mission, stated plainly: **help local business owners get AI to recommend them.**
|
||||
|
||||
That puts the owner talking to AI (or using a tool that talks to AI on their behalf) at the center. Scores, audits, and before/after proof are useful for selling and teaching — they are not the mission itself. We are not building another website where consumers browse listings, not rebuilding booking or shop software, and not defining ourselves as “an MCP company.”
|
||||
|
||||
---
|
||||
|
||||
## The problem we are solving
|
||||
|
||||
Local businesses are entering an era where people ask assistants — ChatGPT, Claude, Gemini, Perplexity, and whatever comes next — for a plumber, a place to eat, or a surf rental near them. If those assistants cannot find or trust a business’s facts, the business simply does not get recommended.
|
||||
|
||||
That **discoverability in the agent era** is the spine of the strategy. How assistants connect to tools and data is just plumbing. The pipe is not the product.
|
||||
|
||||
Under that spine sits a quieter mess — a **big black box of confusion** — that most owners feel but cannot name.
|
||||
|
||||
### The black box: a cloud of copies
|
||||
|
||||
A local business is not a single record on the internet. It is a **cloud of copies**.
|
||||
|
||||
Over years, real life moves. You change suite numbers. The town renumbers a road. The phone company swaps an area code. You get a new mobile for the shop. You update the website. Each of those changes is ordinary. What is not ordinary is what happens next.
|
||||
|
||||
Every major place that stores local businesses keeps **its own copy** of your name, address, and phone — the boring facts people call **NAP** (name, address, phone). [Google Business Profile](https://business.google.com) has a copy. [Apple](https://business.apple.com) has a copy. [Bing](https://www.bingplaces.com) has a copy. [Yelp](https://www.yelp.com) has a copy. [Foursquare](https://foursquare.com)’s place graph has a copy. Underneath many of them, **data aggregators and syndicators** (companies such as [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/) and [Localeze / TransUnion](https://neustarlocaleze.biz/)) hold yet another copy and push it out to directories, maps, navigation apps, and anything that buys “local listings” feeds.
|
||||
|
||||
Nobody is paid to keep all of those copies honest with each other.
|
||||
|
||||
So the copies **drift**. One still has the old area code. One still has the storefront you left three years ago. One has the right street but the wrong suite. Search engines and AI assistants do not magically know which copy is you today. They see a black box of conflicting facts and pick whatever their ranking and training happen to trust that week.
|
||||
|
||||
When an owner finally **claims** [Google Business Profile](https://business.google.com) and fixes it, that is powerful — GBP is usually the strongest **claim surface** an owner can touch. But it is not the only voice. Syndicated feeds can still broadcast the old NAP. Those stale copies can show up in search results and in AI answers **alongside or even above** the listing the owner just cleaned up. From the owner’s chair it feels like: “I fixed it — why does the world still lie about me?”
|
||||
|
||||
That is the problem in one line: **the owner cannot control what the world believes about their business**, because the world is not one database. It is a black box of unreconciled copies.
|
||||
|
||||
### Opening the black box: claim once, correct outward
|
||||
|
||||
We flip the direction of truth.
|
||||
|
||||
Today, copies compete. The owner chases them. Tomorrow, the owner **declares one clean NAP** — a single claimed truth for who they are and how to reach them — and that declaration becomes the **source of truth**. The job of the system is then to **push corrections outward** into the aggregators and syndicated feeds, instead of letting those feeds quietly overwrite or outrank the claim.
|
||||
|
||||
Think of it as three frames:
|
||||
|
||||
```text
|
||||
BEFORE CLAIM AFTER
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ five wrong │ │ one clean │ │ copies that │
|
||||
│ copies of │ ──────► │ NAP the │ ──────► │ match the │
|
||||
│ the same │ │ owner just │ │ claim — │
|
||||
│ business │ │ declared │ │ pushed out │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
(the black box) (source of truth) (reconciled world)
|
||||
```
|
||||
|
||||
**Frame one — left.** The black box: several disagreeing copies ([Google](https://business.google.com), [Apple](https://business.apple.com), [Bing](https://www.bingplaces.com), [Yelp](https://www.yelp.com), [Foursquare](https://foursquare.com), and whatever else still carries an old feed). The owner did not ask for five versions of themselves. The market produced them.
|
||||
|
||||
**Frame two — middle.** The claim: one clean NAP the owner stands behind. That is the only version we treat as authoritative for *this* business. Fixing GBP still matters — it is often the best place to start the claim — but the point is the **declared truth**, not loyalty to any one logo.
|
||||
|
||||
**Frame three — right.** Corrections flowing out. The system’s job is to make the other copies **match the claim**, including the ugly middle layer most owners never see: **syndication**. Aggregators and platforms that feed directories and assistants — [Yelp](https://www.yelp.com), [Bing](https://www.bingplaces.com), [Foursquare](https://foursquare.com), and the rest — routinely **stomp on** a small business’s source of truth with stale hours, old phone numbers, and leftover addresses. If you only polish the claim surface and ignore those copies, the black box regenerates overnight.
|
||||
|
||||
Matching NAP is the floor — **presence** with consistent facts. **Recommendability** (would an assistant pick you for a real customer question in your genre) still needs categories, relevance, and the rest of this product story. Opening the black box is how we stop the floor from moving under the owner’s feet.
|
||||
|
||||
Assistants answer from whatever they can find and trust. When five copies disagree, the assistant is guessing in the fog. When one claimed truth is pushed outward and the other copies are brought into line, the fog thins. Strategic bet in plain words: **stop competing with your own stale twins. Claim once. Correct outward.**
|
||||
|
||||
### What we have to architect (not built yet)
|
||||
|
||||
The direction above is the bet. Below is the **solution we still have to design and build** — not work already done.
|
||||
|
||||
#### 1. Every audit finding becomes a correction ticket
|
||||
|
||||
Today an owner who sees wrong hours on [Yelp](https://www.yelp.com), a dead phone on [Bing](https://www.bingplaces.com), and an old suite on [Foursquare](https://foursquare.com) has to decode three different “suggest an edit” paths. That is the chore we remove.
|
||||
|
||||
For each platform that still shows stale or wrong data, the product turns the audit finding into a **correction ticket** with the same shape every time: which field is wrong, what value is showing, what the right value is, and a link to **[Google Business Profile](https://business.google.com)** (or the owner’s claimed truth) as proof. Then the owner files that platform’s own correction channel — [Yelp](https://www.yelp.com)’s suggest-an-edit page, [Foursquare](https://foursquare.com)’s suggest-edit API (`POST /places/{id}/suggest/edit`), [Bing Places](https://www.bingplaces.com) feedback, and the same pattern for others as we map them. Claim it is wrong. Show proof. Wait.
|
||||
|
||||
Our side of the architecture: **mint that ticket automatically from the audit** — pre-filled, one click to file — instead of making the owner hunt which form goes where. The platforms still own their review queues. We own the translation from “your Presence score is broken here” into “here is the exact correction this platform will accept.”
|
||||
|
||||
#### 2. Held verification across platforms is the moat
|
||||
|
||||
Business verification is the tax. Every platform re-verifies **independently**. [Yelp](https://www.yelp.com) wants its documents. [Bing](https://www.bingplaces.com) wants its own proof of ownership. [Foursquare](https://foursquare.com) has its own checks. There is **no shared credential** and no way to say “I already proved this to Google.” Each review takes **days to weeks**, and without standing as a verified actor, corrections get slow-walked or quietly reverted when the next stale feed arrives.
|
||||
|
||||
A white-label correction service that **holds verified status per platform** — and files on the owner’s behalf without re-uploading a lease five times — is what makes corrections **stick**. That held, multi-platform verified status is the **moat**: the audit finds the drift; the ticket files the fix; the held verification is why the fix does not get stomped again tomorrow.
|
||||
|
||||
#### 3. Two lanes, then a ranked remediation stack
|
||||
|
||||
Umbrella aggregators and end-user platforms are **not** the same job. Architecture needs **two lanes**:
|
||||
|
||||
- **Lane A — umbrella submissions.** Write once into [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/), [Localeze / TransUnion](https://neustarlocaleze.biz/), and [Foursquare](https://foursquare.com)’s place graph so long-tail directories, libraries, and many nav / GPS consumers stop regenerating stale NAP.
|
||||
- **Lane B — per-platform tickets.** Claim or suggest-edit on [Google](https://business.google.com), [Apple](https://business.apple.com), [Bing](https://www.bingplaces.com), [Yelp](https://www.yelp.com), and other surfaces that keep their **own** databases and often prefer verified owner data over a feed.
|
||||
|
||||
Umbrella-only leaves the Core 3 and [Yelp](https://www.yelp.com) wrong. Platform-only leaves the black box regenerating from Layer 1 feeds. Both lanes mint the same ticket shape (field, wrong value, right value, GBP or claimed truth as proof). Rank below is **most → least important** for small-business local discoverability and for how hard a miss should hit the Presence / audit score. Each item is an **owner-facing workflow we still have to architect** — not a label and not a shipped feature.
|
||||
|
||||
1. **[Google Business Profile](https://business.google.com)** (Lane B — claim hub / Core 3). Sign in to the GBP dashboard for that location. Open the wrong field (hours, phone, address, category). Enter the correct value and save. Attach documents only when Google asks — typically for large moves, ownership disputes, or category jumps, not for a routine hours tweak. Wait for the listing to refresh (often minutes to a day). **Success:** Maps / Search show the new value, and that GBP URL becomes the proof link on every other ticket.
|
||||
|
||||
2. **[Apple Business Connect](https://business.apple.com)** (Lane B — Core 3). Sign in to [Apple Business Connect](https://business.apple.com), find the place card, edit the field, submit. Apple may review and email if more proof is needed. Wait for the place card to update across Maps and related Apple surfaces. **Success:** Apple Maps shows the corrected hours / NAP matching the claim.
|
||||
|
||||
3. **[Bing Places](https://www.bingplaces.com)** (Lane B — Core 3). Sign in at the [Bing Places](https://www.bingplaces.com) portal, open the listing, edit the field. Attach proof that matches GBP — utility bill or lease with the same business name and address when Bing asks for ownership evidence. Submit and wait for Bing’s review queue (often days). **Success:** Bing local (and Copilot-adjacent local answers that lean on Places) show the corrected value.
|
||||
|
||||
4. **[Foursquare Places](https://foursquare.com)** (Lane A + B). Two paths, same outcome: (a) Placemaker suggest-edit — pick the place, choose the field, enter wrong vs right, submit; or (b) our white-label one-click that calls `POST /places/{id}/suggest/edit` pre-filled, with the GBP URL as the cited source. Wait for Placemaker / [Foursquare](https://foursquare.com) resolution (status via suggest-status). **Success:** the FSQ place record shows the new value (and downstream licensees that refresh from FSQ can follow).
|
||||
|
||||
5. **[Yelp](https://www.yelp.com)** (Lane B). Open the business page → **Suggest an edit**. Pick the field, type the correction, add a short note citing the GBP listing as proof, submit. [Yelp](https://www.yelp.com) reviews manually. Wait days to weeks. **Success:** the [Yelp](https://www.yelp.com) page shows the corrected field and stops contradicting the claim.
|
||||
|
||||
6. **[Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/) Local Listings** (Lane A). Claim the business at the [Data Axle Local Listings](https://www.data-axle.com/marketing-solutions/local-listings-management/) portal with a business email and / or ownership docs. Edit NAP (and hours) once in that central record. Wait for [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/)’s verification and syndication batch (scale / API path: [Local Listings Premium docs](https://local-listings-premium.data-axle.com/docs)) — hours to ~two weeks for hard cases. **Success:** the Local Listings record matches the claim; long-tail / nav partners that consume [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/) begin reflecting the update on their next pull.
|
||||
|
||||
7. **[Localeze / TransUnion](https://neustarlocaleze.biz/) Digital Business Profile** (Lane A). Claim at the [TransUnion / Localeze](https://neustarlocaleze.biz/) portal, correct NAP once, complete their verification. Wait for push out to their 80–100+ publisher network (often weeks for some partners). **Success:** the claimed profile matches GBP; sample downstream publishers no longer show the stale twin.
|
||||
|
||||
8. **[YP / Thryv](https://www.yellowpages.com)** (Lane B, feeds long-tail). Claim via [YP / Thryv](https://www.yellowpages.com) listing management, edit the wrong field, save. Wait for their network to refresh. **Success:** the YP listing matches the claim; long-tail sites fed by that stack stop showing the old value when they next sync.
|
||||
|
||||
9. **[Tripadvisor](https://www.tripadvisor.com)** (Lane B — vertical). Claim via [Tripadvisor](https://www.tripadvisor.com) for Business, open the field, submit the correction for review. Wait for their moderation. **Success:** the [Tripadvisor](https://www.tripadvisor.com) listing matches the claim when travel / food recommendability cares about that surface.
|
||||
|
||||
10. **[Facebook / Meta](https://www.facebook.com/business)** (Lane B — low weight). In [Meta Business Suite](https://www.facebook.com/business), open the Page → contact / location info, edit hours or phone, publish. Usually no separate proof upload for small edits. **Success:** the Page info card matches GBP; treat as secondary Presence, not Core 3.
|
||||
|
||||
11. **[MapQuest](https://www.mapquest.com) / HERE / in-car nav / long-tail directories** (Lane A by default). There is usually **no** owner correction form. Path: file umbrella tickets ([Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/), [Localeze](https://neustarlocaleze.biz/), [Foursquare](https://foursquare.com)) and **monitor** those surfaces after syndication settles. Open a direct ticket only if a real claim URL exists and the miss survives umbrella propagation. **Success:** re-audit shows the nav / directory copy matches the claim without chasing each site by hand.
|
||||
|
||||
12. **[Dun & Bradstreet](https://www.dnb.com)** — Low priority for consumer local. Skip unless a B2B path is in scope; if needed, update through D&B’s business profile tools with legal-entity proof. **Success:** firmographic record matches when that lane matters.
|
||||
|
||||
13. **[CityGrid](https://www.citygrid.com)** — Legacy. Only if the audit surfaces a [CityGrid](https://www.citygrid.com)-fed copy still stomping the claim; then follow whatever claim / correction URL still exists, else rely on overlapping umbrellas. **Success:** that copy disappears or matches.
|
||||
|
||||
14. **[Yext](https://www.yext.com) / [Uberall](https://www.uberall.com) / [BrightLocal](https://www.brightlocal.com) (pipes)** — Not destinations. If the owner already pays one, route the same tickets **through that pipe** into Lanes A and B instead of a parallel write. **Success:** the pipe’s dashboard shows the jobs filed and publishers reporting the new value — we still score Presence on the publishers, not on the pipe brand.
|
||||
|
||||
#### Day in the life (workflow to architect)
|
||||
|
||||
A muffin shop’s Tuesday hours are wrong on the public web. The owner runs our audit, sees three red rows (GBP already correct, [Foursquare](https://foursquare.com) stale, [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/) still syndicating the old Tuesday close), and hits **one** “fix these” button.
|
||||
|
||||
Three pre-filled things fire — not three scavenger hunts:
|
||||
|
||||
1. **GBP** — if anything still drifts there, a deep link into the hours editor with Tuesday pre-filled to the claimed value; otherwise we skip and reuse the live GBP URL as proof.
|
||||
2. **[Foursquare](https://foursquare.com)** — a one-click Placemaker suggest-edit (`POST /places/{id}/suggest/edit`) with field = hours, wrong = old Tuesday, right = claimed Tuesday, source = GBP URL (white-label Managed User when we file for them).
|
||||
3. **[Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/)** — a Lane A claim / update ticket at Local Listings with the same NAP + hours payload so the umbrella stops stomping the claim on the next syndication cycle.
|
||||
|
||||
The owner attaches proof once where a portal demands it, then waits on each queue. Re-audit later is the success check: Tuesday matches everywhere that mattered. That is the workflow to architect — audit → tickets → wait → prove — not a pile of unlabeled “go fix [Yelp](https://www.yelp.com)” links.
|
||||
|
||||
|
||||
#### 4. One-to-many fan-out — useful lane, not the whole backbone
|
||||
|
||||
True one-to-many correction **exists**, but nothing is reliable enough to be the **only** spine of a one-click product. Research takeaways to architect around:
|
||||
|
||||
**[Localeze / TransUnion](https://neustarlocaleze.biz/)** markets claim-once → **80–100+** publishers. In practice publishers decide *what* and *when* to show: many partners sit on a **monthly publish** cycle (**~30–90 days**); sync partners can be faster; [Localeze](https://neustarlocaleze.biz/) does **not** control partner acceptance. Fast Google updates via [Localeze](https://neustarlocaleze.biz/) require a **separate Google verify/sync** inside their product — not the feed alone. Some partners need extra OAuth (e.g. link [Facebook](https://www.facebook.com/business)). Distribution status reporting exists because fan-out is partial, not guaranteed.
|
||||
|
||||
**[Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/)** Local Listings / [Local Listings Premium](https://local-listings-premium.data-axle.com/docs) is the same *shape*: one verified submit → search, directories, libraries, nav, assistants. Processing can be hours to ~two weeks when human verification kicks in. Publisher lists **overlap** [Localeze](https://neustarlocaleze.biz/) on many big names but are **not identical** (citation vendors still sell both). Treat them as complementary Lane A tickets, not duplicates.
|
||||
|
||||
**Other fan-out:** Paid listing managers ([Yext](https://www.yext.com)-class — often 200+ *direct* publisher APIs with per-publisher status) are the strongest productized one-edit→many-majors path — route through them when the owner already pays (rank 14). **[Google Business Profile](https://business.google.com) does not syndicate NAP outbound** to Apple/[Yelp](https://www.yelp.com)/Bing. **[Apple Business Connect](https://business.apple.com)** writes the Apple ecosystem (and partner APIs *into* Apple), not rival platforms. [Foursquare Places](https://foursquare.com) suggest-edit updates FSQ’s graph (and later licensees), not a general directory blast.
|
||||
|
||||
There is **no free public one-to-many fan-out API** an SMB can call to rewrite every major surface at once; [Localeze](https://neustarlocaleze.biz/) and [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/) are sales- or portal-gated claim/submit products, and [Yext](https://www.yext.com)-class pipes are paid.
|
||||
|
||||
**Ceiling:** One [Localeze](https://neustarlocaleze.biz/) (or [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/)) correction may move a **fraction** of consumer-visible surfaces in week one and more over 1–3 months; Core 3 claim surfaces often stay wrong without Lane B. So one-click means **one button that mints a ticket set** (GBP proof + Lane A umbrellas + Lane B majors) — not one submission that rewrites the internet.
|
||||
|
||||
Longer term, the Northstar — the destination we aim at but do not build first — is an **industry graph**: a shared, structured map of local businesses that many products and assistants could use. That is not version one. Version one earns the right to that graph by helping owners see how AI sees them today and fix what is broken, with their consent.
|
||||
|
||||
---
|
||||
|
||||
## The product
|
||||
|
||||
A self-service experience — first as an interactive website, and later possibly inside a business’s own chatbot using the same engine — where an owner can ask: **“Is my business discoverable by AI?”**
|
||||
|
||||
The flow we are designing toward:
|
||||
|
||||
Someone who claims the business starts the check. We verify they are actually a stakeholder — for example by sending a six-digit code to an email already on file for that business — so random people cannot run deep audits on someone else’s shop. Once verified, we run a check that goes further than the old local-SEO habit of matching name, address, and phone (often called NAP) across directories. We also look at **categories** (what kind of business the listing says it is — plumber versus restaurant versus hotel) and **relevance** (whether those facts would help an assistant pick this business for a real customer question).
|
||||
|
||||
We then give the owner two scores, in plain language:
|
||||
|
||||
**Presence** answers: are you on the map? Are you listed with the major providers, and do your categories line up consistently?
|
||||
|
||||
**Recommendability** answers: if you are on the map, would an AI be likely to recommend you when someone asks about something in your genre?
|
||||
|
||||
Finally we show what to fix, ranked so the owner can do it themselves, and let them re-check later. A human expert can be an escape hatch. It must not be required for the product to work — humans will not scale to every small business.
|
||||
|
||||
Demand should mostly come from owners who start themselves (including from ads that send them to the tool), not from sales calls for every audit.
|
||||
|
||||
---
|
||||
|
||||
## How people will use it (channel reality, September 2026)
|
||||
|
||||
We checked how major consumer chatbots behave with MCP as of late September / early October 2026. None of the big ones will automatically “handshake” with a random small business’s MCP server if nobody configured a connector. ChatGPT, Claude, consumer Gemini, Perplexity, Microsoft 365 Copilot, and similar products either need someone to add a connector or they only suggest connectors that are already in a curated directory. That is setup work — not something a typical shop owner gets for free by putting an MCP URL on the internet.
|
||||
|
||||
Those same assistants can still open and read a normal web page as text. Reading a page is not the same as speaking MCP to a server.
|
||||
|
||||
So for version one, the highest priority is an **interactive web app** the owner completes in a browser. Embedding the same engine in a business chatbot can come later. We should revisit MCP as a distribution pipe in about three months — not block the product on it now.
|
||||
|
||||
---
|
||||
|
||||
## How we label kinds of businesses
|
||||
|
||||
A **taxonomy** here means the set of categories used to say what kind of business something is — plumber versus restaurant versus hotel — so listings, maps, and assistants know what queries it belongs to.
|
||||
|
||||
There is no single industry-wide taxonomy that [Apple](https://business.apple.com), [Google](https://business.google.com), [Bing](https://www.bingplaces.com), [Yelp](https://www.yelp.com), and the listing aggregators all use. Each keeps its own list (or feeds someone else’s).
|
||||
|
||||
**NAICS** (North American Industry Classification System) is the U.S. government’s statistical system for classifying businesses by what they produce. It is good for reports and some B2B software. It is not how someone searches “plumber near me” on a map. **SIC** is the older system NAICS replaced for federal stats.
|
||||
|
||||
**[Google Business Profile](https://business.google.com)** has its own category IDs (often looking like `gcid:…`), available through Google’s Business Information API (`categories.list`, region US / language en). That official list is a **flat catalog of roughly 4,050 leaves** — not a hierarchy that matches our genre parents. Google does not publish a downloadable tree that says “these GCIDs belong under service-area trades.” A public September 2026 compilation of **4,053** US English GCID names (with third-party industry buckets used only for structure) is useful for research; those buckets are **not** Google’s official parents. We use GBP GCIDs as **outbound presence-check maps** and fix suggestions, not as our spine. In practice GBP is usually the **richest** owner-facing surface (categories, services, attributes, photos).
|
||||
|
||||
**[Apple Maps / Business Connect](https://business.apple.com)** has its own primary category (one main label) plus optional extras; the public docs have been shifting as Apple folds Connect into a broader “Apple Business” offering. Owner-facing field labels are documented; partner API schemas are often gated. Mid richness versus GBP — good for place card truth, weaker 1:1 parity on things like GBP `serviceItems`.
|
||||
|
||||
**[Bing Places for Business](https://www.bingplaces.com)** is Microsoft’s local listing surface (feeds Bing / Microsoft local experiences). Categories use Bing’s own IDs (`BPCategoryId` + name); owners can attach multiple categories with one primary. The trusted-partner API is certificate-gated, not a public crawl API — field maps on this branch already treat Bing as the **thinnest** of a “Core 3” with GBP and Apple (`docs/product/genre-packs/`). Bing still matters for Presence: wrong or missing Bing categories are a real “are you on the map?” miss, especially where Copilot / Microsoft surfaces lean on [Bing Places](https://www.bingplaces.com) data. Do not pretend Bing’s category tree equals Google’s.
|
||||
|
||||
**[Yelp](https://www.yelp.com)** keeps its own hierarchy of category **aliases** (developer APIs expose the tree). [Yelp](https://www.yelp.com) is both a discovery surface consumers still use and a signal assistants and third parties often scrape or cite. Alias mismatch (e.g. cuisine or trade labels that do not line up with GBP) is a classic consistency failure. [Yelp](https://www.yelp.com) is not a map pin in the same way as GBP/Apple/Bing, but it belongs in outbound maps when we score “would an AI trust this entity’s type?”
|
||||
|
||||
**Data aggregators / syndicators** sit underneath many of those surfaces. Companies such as **[Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/)** (local listings / formerly Infogroup-class syndication), **[Localeze / TransUnion](https://neustarlocaleze.biz/)** digital business profiles, **[Foursquare](https://foursquare.com)** Places (place graph / POI metadata), and similar players push NAP and rich fields out to search engines, directories, navigation apps, and assistants. Owners often never touch them directly — a “listing management” vendor or the platform itself does. For our product that means: Presence is not only “did you claim GBP?” It can also be “does the aggregator-fed copy of you disagree with the claim you just made?” Aggregators are **not** a ninth genre parent; they are a **distribution layer for facts**. Which aggregators we check in v1 (if any) is still open — but ignoring them entirely would understate how local data actually spreads.
|
||||
|
||||
**schema.org’s LocalBusiness** types are an open vocabulary used widely on the web for structured data (the markup that helps search engines understand a page). That is the best spine for an AI-era product that also wants to publish clear web facts: owner-friendly genres inside our product, keyed to schema.org where they fit, optional NAICS when a statistical code helps, and **outbound maps** — translation tables — from our genres to [Google](https://business.google.com), [Apple](https://business.apple.com), [Bing](https://www.bingplaces.com), [Yelp](https://www.yelp.com), and (where useful) aggregator category codes when we check presence or suggest fixes.
|
||||
|
||||
We should not treat any single platform or aggregator list as our internal source of truth. They drift and they disagree. Building those maps ourselves is normal; nobody publishes an official multi-way concordance. On this branch, genre-pack work already sketches a **Core 3** field map (GBP richest → Apple mid → Bing thinnest); extend that pattern to [Yelp](https://www.yelp.com) aliases and aggregator feeds only where Presence scoring needs them.
|
||||
|
||||
This taxonomy approach is a **hypothesis** until we score real businesses and see where the maps break.
|
||||
|
||||
---
|
||||
|
||||
## Why one audit checklist is not enough
|
||||
|
||||
A plumber who works out of a truck and a surfboard rental that serves tourists are both “local businesses,” but “are you on the map?” and “would AI recommend you?” mean different things for each. The product can keep one shared scoreboard — Presence and Recommendability — and change the **rubric** (what evidence counts and how heavily) by **genre cluster**.
|
||||
|
||||
What actually splits the audits:
|
||||
|
||||
Where the work happens (customer comes to you, you go to them, both, or a moving spot). What “place” means (a storefront with a public address, a service-area business that hides its address, a tourist landmark, or many locations). What decision data matters (menu, service list, booking, hours open right now, amenities). What kind of demand it is (emergency, same-day convenience, a planned night out, a trip, or B2B research). How trust shows up (reviews, photos, licenses). Seasonality. And whether the AI is helping a consumer or a business buyer.
|
||||
|
||||
We are proposing **eight top-level clusters** plus one cross-cutting flag as a starting cut — also a hypothesis until real audits teach us to merge or split. A GBP category pressure test (flat GCID catalog + third-party industry buckets for structure only) pushed three corrections: split bring-to-shop trades away from service-area trades; narrow beauty away from medical; demote hybrid from a parent to a flag.
|
||||
|
||||
**Service-area trades** (plumber, HVAC, cleaner, landscaper, pest control): the provider goes to the customer. Presence cares about looking like a real service-area listing rather than a fake storefront, having coherent service areas and categories; recommendability cares about matching the job type and the customer’s area, plus reliability signals. Do **not** put auto repair here.
|
||||
|
||||
**Destination workshop** (auto repair, tire shop, furniture repair, shoe repair, and similar bring-the-item-in trades): the customer brings the asset to a shop with a public address. Presence is storefront-like (real pin, hours, specialty categories); recommendability is trade-like (job match, make/model or specialty, reliability). GBP catalogs Automotive separately from Construction & Trades / Home & Garden — that split supports this parent.
|
||||
|
||||
**Storefront retail:** presence cares about address, hours, and category truth; recommendability cares about whether the assortment fits the ask and whether the shop is actually open.
|
||||
|
||||
**Food service** (restaurants, cafés, bars, food trucks): presence cares about specific cuisine or format categories (not a vague “Restaurant”), hours, and a current menu; trucks also need “where are you today.” Recommendability cares about occasion (date night versus quick lunch), price and vibe signals, dietary clarity, and fresh reviews. Fine dining, quick service, and trucks are **parameters inside this cluster**, not separate products.
|
||||
|
||||
**Professional / office services** (lawyer, accountant): less weight on “open right now,” more on specialty, credentials, and clear service language.
|
||||
|
||||
**Beauty** (salon, barber, day spa, nails — formerly the non-medical slice of “home and personal care”): booking path and services on the presence side; skill match, portfolio, and outcome-themed trust on recommendability. Dentist, medical spa, and other clinical work belong under healthcare, not here.
|
||||
|
||||
**Hospitality and tourism** (hotel, surf rental, tour): destination and amenity truth, seasonal hours, and conflicts between the business’s own facts and big travel sites; recommendability is trip-intent fit (“family,” “near the break,” pet-friendly) and seasonal availability. This stays a **rubric parent even though GBP will not hand it to us as one bucket** — lodging leaves (hotel, motel, B&B) group fairly cleanly; tourism activity scatters across Sports, Education, Arts, and related leaves. Our audits still need one trip-intent rubric.
|
||||
|
||||
**Healthcare / regulated** (only if we take them on — including dentist and medical spa): higher bar for accurate categories and careful claims. **Veterinary** is an open decision: in the GBP research dump, pets/vets sit in a separate Pets neighborhood (~59 leaves), not inside Health & Medical — decide whether vets ride with healthcare/regulated or get their own call if they are in scope.
|
||||
|
||||
**Hybrid / multi-mode is not a ninth parent.** It is a **cross-cutting flag** that can sit on any cluster (dine-in plus delivery on food service; showroom plus install on retail or destination workshop). Presence and recommendability apply the relevant mode slices; the query tells you which mode matters. Google encodes many of these as specific leaves (delivery restaurant, mobile caterer), not as a top-level grouping.
|
||||
|
||||
For version one, start with **two** cluster packs that prove the split matters — service-area trades and food service. If the commercial wedge is tourist businesses, hospitality can swap in for food service as the second pack. Destination workshop is the natural pack when the wedge is auto repair (as in the older UC-01 example).
|
||||
|
||||
---
|
||||
|
||||
## How we build it (phases)
|
||||
|
||||
**Phase 0 — Lock the promise.** One sentence an owner gets without jargon. Who we speak to first. What “recommendable” means in plain words. Confirm the first shell is the web app. Success: we can say the promise in one breath without naming MCP or any other pipe.
|
||||
|
||||
**Phase 1 — Trust gate.** Claim the business, verify the stakeholder (email code first), keep data light, consent clear, and abuse limited. Success: only verified people reach the deep audit.
|
||||
|
||||
**Phase 2 — Audit engine.** This is the product: Presence and Recommendability with a thin, explainable rubric and cluster-specific weights — not a black box. Success: running the same business twice gives roughly the same scores, and the owner understands why.
|
||||
|
||||
**Phase 3 — Self-serve loop.** Results, a fix list, optional re-check, no mandatory human. Success: most people finish alone.
|
||||
|
||||
**Phase 4 — Demand.** Light campaigns that send owners to start their own audit. Track start → verify → complete → recheck. Success: we know acquisition cost and completion rate well enough to improve.
|
||||
|
||||
**Phase 5 — Toward the graph.** Only after audits produce structured facts owners consented to share that are worth composing into something bigger. The graph stays the Northstar; it does not gate version one.
|
||||
|
||||
Ship in this order: promise and wedge, verify gate, presence score, recommendability score, results and fixes, recheck, then ads. Do not wait on the industry graph or on a single technical protocol.
|
||||
|
||||
Version one is succeeding when an owner can finish alone, sees two clear scores with a real explanation, gets fixes they can do themselves, can re-check, and ads can point at the tool without a sales call on every lead.
|
||||
|
||||
Once Phase 0 is clear, work can run in parallel streams: promise and wedge language; trust and verify; presence checks; recommendability rubric; the web (and later chat) shell; growth metrics; and only later, graph composition.
|
||||
|
||||
---
|
||||
|
||||
## How demand arrives (acquisition, not taxonomy)
|
||||
|
||||
This section is about **who brings owners to the tool**, not about which genre parent an audit uses. Genre clusters (destination workshop, beauty, hybrid as a flag, and the rest) stay a product-rubric question. Demand is orthogonal.
|
||||
|
||||
On `main`, distribution is framed as the hard part of local SaaS (`docs/gtm/channel-strategy.md`, echoed in `NORTH_STAR.md` and Canonical Strategy §10). The primary one-to-many wedge there is **tourism / destination intermediates** — tourism boards, DMOs, and visitor bureaus: one board contract unlocks many member endpoints, often funded by lodging-tax or visitor-experience budgets, upgrading board sites from weak link lists into structured destination surfaces (UC-02). A **parallel** path is self-serve SMBs in high-intent verticals. **Chambers of Commerce** show up as a secondary one-to-many path (CoC-branded portals, member-benefit framing). **Agencies and SEO consultants** are a partner layer that implements and sells — not the product center. **BBB (Better Business Bureau) does not appear anywhere on `main`** in that research pass; do not invent it into this SoT.
|
||||
|
||||
Soft link only: a tourism-board wedge prefers shipping the **hospitality / tourism** pack; an intermediate still needs **category routing** across members, which uses taxonomy as wiring, not as the definition of our parents.
|
||||
|
||||
This doc’s product flow already assumes many owners **start themselves** (including from ads). Main’s board-and-partner motion can **coexist** with that, but “ads / self-start only,” “intermediate-first,” or “both” is a real decision — not something the genre list answers.
|
||||
|
||||
---
|
||||
|
||||
## Decisions still open
|
||||
|
||||
Ty still needs to lock: which cluster pack we ship first; whether version one is web-only or also embeds in a chatbot; which providers feed the Presence score (Core 3 GBP/Apple/Bing, plus [Yelp](https://www.yelp.com) and/or aggregators such as [Data Axle](https://www.data-axle.com/marketing-solutions/local-listings-management/) / [Localeze](https://neustarlocaleze.biz/) / [Foursquare](https://foursquare.com) — or claim-only first); how we measure Recommendability without overclaiming (simple heuristics versus live checks inside assistants); where the “email on file” for verification comes from; free versus paid; what never goes to a human versus when escalation is allowed; whether **veterinary** rides with healthcare/regulated or gets its own call if in scope (GBP research dump: separate Pets bucket, ~59 leaves, not folded into Health & Medical); and whether **v1 demand** is ads/self-start only, intermediate-first (tourism boards / chambers / partners), or both.
|
||||
|
||||
---
|
||||
|
||||
## What we are treating as hypotheses
|
||||
|
||||
Until we score real businesses, treat these as educated bets, not finished truth: that eight top-level clusters plus a hybrid flag is the right split (including destination workshop separate from service-area trades, and beauty separate from healthcare); that schema.org plus outbound maps to [Google](https://business.google.com), [Apple](https://business.apple.com), [Bing](https://www.bingplaces.com), [Yelp](https://www.yelp.com), and selected aggregators is the right labeling spine — not any one platform’s leaf list as internal SoT; that two version-one packs are enough to prove cluster-specific rubrics; and that a web app beats an MCP-first distribution story for owners in the near term (revisit in about three months).
|
||||
|
||||
Nothing in this doc is locked until Ty says so. Amend this file when decisions land — do not start a second near-named document.
|
||||
@@ -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).
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,12 @@
|
||||
# Engineering
|
||||
|
||||
Architecture, roadmap, and implementation notes.
|
||||
|
||||
| Doc | Purpose |
|
||||
|-----|---------|
|
||||
| [technical-roadmap.md](./technical-roadmap.md) | Phased technical plan (align with strategy when they diverge) |
|
||||
| [adrs/](./adrs/) | Architecture decision records |
|
||||
|
||||
**Operating priorities** come from [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§10). When this folder and the strategy disagree, fix one of them deliberately.
|
||||
|
||||
Current implementation lives in `code/` (MCP MVP). A later monorepo phase moves that to `apps/mcp-gateway`.
|
||||
@@ -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).
|
||||
@@ -0,0 +1,216 @@
|
||||
# Product & Technical Roadmap
|
||||
|
||||
## 1. The Guiding Principle
|
||||
|
||||
`geolocal.io` is an **infrastructure platform**, not a destination site.
|
||||
|
||||
Everything we build must follow a single principle: **make it dead simple for a partner to deploy an MCP endpoint for a local business, and make that endpoint compelling enough that AI agents prefer it.**
|
||||
|
||||
This means:
|
||||
- **No coding required** for the business or partner to set up
|
||||
- **Centralized MCP hosting** (multi-tenant) with a simple JSON pointer for each business
|
||||
- **Rich, structured data** that gives AI agents a reason to trust and use our endpoints
|
||||
- **A self-reinforcing network** where more data attracts more agents, which generates more data
|
||||
|
||||
---
|
||||
|
||||
## 2. Technical Architecture Overview
|
||||
|
||||
### 2.1 High-Level System Components
|
||||
|
||||
| Component | Description | Technology Stack |
|
||||
| :--- | :--- | :--- |
|
||||
| **MCP Gateway** | Multi-tenant router that directs requests to the correct business MCP server | Node.js/TypeScript, FastMCP framework |
|
||||
| **Business MCP Server** | Hosts the actual MCP tools for each business; dynamically generated from database | TypeScript, MCP SDK |
|
||||
| **Business Database** | Stores business profiles, metadata, structured content, and telemetry | PostgreSQL, Supabase / Railway |
|
||||
| **JSON Manifest Generator** | Generates the `/.well-known/mcp-server` JSON file for each business | Static file generation |
|
||||
| **Partner Dashboard** | Agency-facing portal for onboarding, management, and analytics | React/Next.js, Tailwind |
|
||||
| **CoC Dashboard** | Chamber-facing portal for member management and analytics | React/Next.js, Tailwind |
|
||||
| **Business Dashboard** | SMB-facing portal for profile management and analytics | React/Next.js, Tailwind |
|
||||
| **Telemetry Pipeline** | Captures and processes MCP interaction data for analytics and DaaS | Postgres, Redis, Webhooks |
|
||||
|
||||
### 2.2 Data Flow
|
||||
AI Agent → MCP Gateway → Business MCP Server → Database / Cal.com / Stripe
|
||||
↓
|
||||
Telemetry Pipeline → Dashboards / Analytics
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Enablers: MCP Patterns You Can Leverage
|
||||
|
||||
### 3.1 Orchestration Pattern
|
||||
|
||||
Multiple MCP servers can be composed into a single endpoint, exposing tools from multiple sources to the AI as a unified interface.
|
||||
|
||||
**Relevance to you:** Your gateway will handle orchestration, enabling you to pull in tools from Cal.com's MCP or your own proprietary tools seamlessly.
|
||||
|
||||
### 3.2 Deployment Modes
|
||||
|
||||
| Mode | Description | Best For |
|
||||
| :--- | :--- | :--- |
|
||||
| **Managed-Shared** | Single MCP server instance serves multiple users simultaneously | **Your scenario:** Centralizing data from many businesses into one server |
|
||||
| **Managed-Dedicated** | Each business gets their own container instance | High-security or high-traffic businesses |
|
||||
| **Remote** | MCP server hosted by a third party; you just get a URL | Cal.com's MCP server integration |
|
||||
|
||||
### 3.3 Transport Options
|
||||
|
||||
| Transport | Description | Best For |
|
||||
| :--- | :--- | :--- |
|
||||
| **SSE (Server-Sent Events)** | Simple, server-push capable, easier for older clients | Quick start, simple use cases |
|
||||
| **Streamable HTTP** | More efficient, supports larger payloads, recommended for production | **Recommended for your platform** |
|
||||
|
||||
### 3.4 Tool Design Best Practices
|
||||
|
||||
| Best Practice | Example |
|
||||
| :--- | :--- |
|
||||
| **Granular tools** | `get_business_info`, `check_availability`, `book_appointment` (not one giant `do_everything` tool) |
|
||||
| **Clear descriptions** | Descriptions help the AI decide which tool to call |
|
||||
| **Structured inputs** | Use JSON Schema for parameters |
|
||||
| **Rich outputs** | Include links to visuals, booking confirmation, etc. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Phase 1: MVP (90 Days)
|
||||
|
||||
### 4.1 MVP Scope
|
||||
|
||||
| Component | Features | Priority |
|
||||
| :--- | :--- | :--- |
|
||||
| **MCP Gateway** | Single multi-tenant MCP endpoint; basic routing by tenant | Must-have |
|
||||
| **Business Database** | Store: business name, address, hours, services, description, photos URLs, Cal.com link | Must-have |
|
||||
| **MCP Tools** | `get_business_info`, `get_hours`, `get_services`, `get_booking_link` | Must-have |
|
||||
| **Cal.com Integration** | Redirect to Cal.com booking page (Phase 1: no deep API integration) | Must-have |
|
||||
| **JSON Manifest Generator** | Generate `/.well-known/mcp-server` file for each business | Must-have |
|
||||
| **Partner Dashboard** | Partner sign-up, client onboarding (add client → generate manifest) | Must-have |
|
||||
| **Telemetry** | Basic logging: request counts, tool calls, response times | Nice-to-have |
|
||||
|
||||
### 4.2 Implementation Plan: 90-Day Sprint
|
||||
|
||||
| Week | Deliverable |
|
||||
| :--- | :--- |
|
||||
| **1-2** | Stand up PostgreSQL database; define schema; build business CRUD API |
|
||||
| **3-4** | Build MCP server using TypeScript + MCP SDK; implement first tools (get_business_info, get_hours) |
|
||||
| **5-6** | Implement JSON manifest generator; test discovery flow |
|
||||
| **7-8** | Build Partner Dashboard (sign-up, client management, manifest download) |
|
||||
| **9-10** | Integrate Cal.com (redirect); test end-to-end flow |
|
||||
| **11-12** | Onboard 10 pilot businesses; collect feedback; iterate |
|
||||
|
||||
### 4.3 Hosting Infrastructure Decision
|
||||
|
||||
| Option | Pros | Cons | Recommended? |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Railway** | One-click deployment, free tier, simple | Less control, scaling limits | ✅ **Recommended for MVP** |
|
||||
| **CreateOS** | Native MCP auto-discovery, persistent Postgres, marketplace | Newer platform, smaller community | Consider for production |
|
||||
| **AWS ECS / Fargate** | Full control, enterprise-grade | Operational overhead, more complex | Later stage |
|
||||
| **Google Cloud Run** | Serverless, scales well | Cold starts, less MCP-specific tooling | Later stage |
|
||||
|
||||
**Recommendation:** Start with **Railway** for MVP speed. Plan to migrate to **CreateOS** or **AWS** for production scale.
|
||||
|
||||
---
|
||||
|
||||
## 5. Phase 2: Scale & Features (180 Days)
|
||||
|
||||
### 5.1 Expanded Scope
|
||||
|
||||
| Component | Features |
|
||||
| :--- | :--- |
|
||||
| **MCP Tools (Expanded)** | `check_availability` (via Cal.com API), `book_appointment` (via Cal.com API) |
|
||||
| **Deep Cal.com Integration** | Direct API integration (not just redirect); availability checks; booking creation |
|
||||
| **Stripe Integration** | Payment capture for deposits; account creation for businesses |
|
||||
| **Rich Content Layer** | Story, owner bio, high-quality photos, video; structured for AI extraction |
|
||||
| **Related Businesses Tool** | `get_related_businesses` handshake; competitive intelligence capture |
|
||||
| **MCP Gateway (Advanced)** | Rate limiting, authentication, OAuth support |
|
||||
| **Business Dashboard** | SMB-facing portal for profile management; basic analytics |
|
||||
| **Partner Dashboard (Expanded)** | White-label support; client analytics; commission tracking |
|
||||
| **CoC Dashboard** | Member management; group analytics; lead reporting |
|
||||
| **Telemetry Pipeline** | Structured logging; event tracking; basic analytics dashboards |
|
||||
|
||||
### 5.2 Implementation Plan
|
||||
|
||||
| Phase | Month | Deliverable |
|
||||
| :--- | :--- | :--- |
|
||||
| **5.2.1** | **4** | Deep Cal.com API integration; Stripe payment capture; expanded MCP tools |
|
||||
| **5.2.2** | **5** | Related Businesses tool; telemetry pipeline; basic analytics |
|
||||
| **5.2.3** | **6** | Business Dashboard; CoC Dashboard; white-label support |
|
||||
|
||||
---
|
||||
|
||||
## 6. Phase 3: Ecosystem & Monetization (360 Days)
|
||||
|
||||
### 6.1 Expanded Scope
|
||||
|
||||
| Component | Features |
|
||||
| :--- | :--- |
|
||||
| **Data-as-a-Service (DaaS)** | Anonymized telemetry data for licensing; AI Local Demand Index; competitive benchmarks |
|
||||
| **Plugin Ecosystem** | WordPress plugin; Webflow app; Framer plugin |
|
||||
| **Chamber Partnership Portal** | White-labeled CoC onboarding; member analytics; lead reporting |
|
||||
| **Multi-Vertical Support** | Auto repair, beauty, home services, wellness, etc. |
|
||||
| **Developer API** | Public API for custom MCP server development |
|
||||
| **OAuth & Authorization** | OAuth 2.1 with Dynamic Client Registration (DCR) for partner integrations |
|
||||
| **Advanced Telemetry** | Agent behavior analysis; market trend identification; anomaly detection |
|
||||
| **Feedback Loop** | Verification tools; AI agent conflict reporting; automated data correction |
|
||||
|
||||
### 6.2 Implementation Plan
|
||||
|
||||
| Phase | Month | Deliverable |
|
||||
| :--- | :--- | :--- |
|
||||
| **6.2.1** | **7-9** | WordPress plugin; Webflow app; Chamber Partnership Portal |
|
||||
| **6.2.2** | **10-12** | DaaS product launch; multi-vertical support; OAuth/authorization layer |
|
||||
| **6.2.3** | **12+** | Feedback loop; advanced telemetry; public developer API |
|
||||
|
||||
---
|
||||
|
||||
## 7. Technology Stack Recommendations
|
||||
|
||||
| Layer | Technology | Rationale |
|
||||
| :--- | :--- | :--- |
|
||||
| **Backend** | Node.js / TypeScript | MCP SDK is TypeScript-first; large ecosystem |
|
||||
| **API Framework** | FastMCP | High-performance, minimal boilerplate for MCP servers |
|
||||
| **Database** | PostgreSQL (Supabase / Railway) | Reliable, JSON support, hosted options |
|
||||
| **Frontend** | React / Next.js | Modern, fast, server-side rendering for dashboards |
|
||||
| **Hosting** | Railway (MVP) → CreateOS / AWS (prod) | Balance of speed, cost, and control |
|
||||
| **Cache** | Redis | For rate limiting, session management |
|
||||
| **Analytics** | Postgres / Custom | You control the telemetry; build your own analytics layer |
|
||||
| **Payment** | Stripe | Mature, API-first, handles deposits and subscriptions |
|
||||
| **Booking** | Cal.com API | MCP-aware, structured API, booking + payment integration |
|
||||
|
||||
---
|
||||
|
||||
## 8. Key Technical Risks & Mitigation
|
||||
|
||||
| Risk | Mitigation |
|
||||
| :--- | :--- |
|
||||
| **MCP protocol changes rapidly** | Follow the official MCP GitHub; use stable SDK versions; subscribe to release notes |
|
||||
| **Cal.com API changes** | Build a small abstraction layer; use Cal.com's official MCP server where possible |
|
||||
| **Scalability of multi-tenant MCP** | Design for horizontal scaling; use Redis for session management; monitor performance |
|
||||
| **Latency from AI agents** | Optimize tool responses; use caching; prioritize frequent tools |
|
||||
| **Security of OAuth flows** | Use OAuth 2.1 with PKCE; follow MCP's security recommendations; regular audits |
|
||||
| **Data privacy concerns** | Design privacy-first; avoid storing sensitive PII; comply with GDPR/CCPA |
|
||||
| **Telemetry volume growth** | Use cost-effective storage; batch writes; use data compression |
|
||||
|
||||
---
|
||||
|
||||
## 9. Technical Guiding Principles
|
||||
|
||||
| Principle | Why It Matters |
|
||||
| :--- | :--- |
|
||||
| **Standard-first** | Follow MCP standards; avoid proprietary customizations |
|
||||
| **Simple over complex** | Start simple; add complexity only when needed |
|
||||
| **Observable by design** | Log everything; make telemetry a first-class feature |
|
||||
| **Security by default** | OAuth, rate limiting, data validation from day one |
|
||||
| **Partner-first UX** | Dashboards and onboarding should prioritize partner ease over "consumer polish" |
|
||||
| **Data ownership** | Capture telemetry; build a data moat |
|
||||
|
||||
---
|
||||
|
||||
## 10. Citation Table
|
||||
|
||||
| ID | Source |
|
||||
| :--- | :--- |
|
||||
| [1] | Anthropic, "Model Context Protocol GitHub Repository," 2024-2026 |
|
||||
| [2] | MCP Documentation, "Server Deployment Modes," 2026 |
|
||||
| [3] | MCP Documentation, "Transport Options," 2026 |
|
||||
| [4] | MCP Documentation, "Tool Design Best Practices," 2026 |
|
||||
| [5] | Railway, "MCP Server Deployment Guide," 2026 |
|
||||
| [6] | CreateOS, "MCP Server Hosting Documentation," 2026 |
|
||||
| [7] | Cal.com, "MCP Server Documentation," 2026 |
|
||||
@@ -1,83 +0,0 @@
|
||||
# SBE Council Technology Use Survey — March 2026
|
||||
|
||||
**Status:** provisional research note (session 2026-09-15)
|
||||
**Source (opened this session):** https://sbecouncil.org/wp-content/uploads/2026/03/SBE-Technology-Use-Survey-March-2026-Final.pdf
|
||||
**Fielded:** February 17–23, 2026 · **n=517** small business owners (2–99 employees) · TechnoMetrica for SBE Council · credibility interval ±4.4 pp
|
||||
|
||||
## Why this note exists
|
||||
|
||||
Fresh (2026) category-level signal on how US small businesses use AI, marketing, and sales channels — used to pressure-test GeoLocal wedge, entry paths, and later free/silver/gold packaging. **Not** a ranked brand list of local SaaS apps (that remains unavailable from this source).
|
||||
|
||||
## Caveat (scope)
|
||||
|
||||
Sample is general SMB 2–99 (professional services, construction, tech, retail, etc.) — **not** local-only / brick-and-mortar filtered. Figures may skew differently for salons, bakeries, and similar local genres. Report does **not** mention Google Business Profile, Apple Business Connect, Bing Places, or local SEO by name.
|
||||
|
||||
## Key findings (sourced)
|
||||
|
||||
### AI adoption
|
||||
|
||||
| Finding | Figure (from source) |
|
||||
| :--- | :--- |
|
||||
| Use ≥1 AI tool | 82% |
|
||||
| Median AI tools in use | 5 |
|
||||
| Confident adopting AI/digital tools | 90% (52% very) |
|
||||
| AI important to competitiveness/growth (among users) | 81% (41% very, 40% somewhat) |
|
||||
| Expect major or transformative industry impact | 53% |
|
||||
| Median annual AI spend | $2,200 |
|
||||
| Plan to increase AI spend next year | 62% |
|
||||
| AI in >25% of operations | 32% (8% in >half) |
|
||||
| Top AI uses | Research 37%, content 30%, marketing automation / project mgmt / social each 25% |
|
||||
| Primary AI guidance sources | Peers 45%, internal tech staff 38%, associations 37% |
|
||||
| Top barriers to further AI | Knowledge/training 23%, privacy 17%, cybersecurity 13%, cost 12% |
|
||||
| Non-users: “see no need” | 62% of non-users |
|
||||
| Median owner hours saved / week via AI | 5 |
|
||||
| Median employee hours saved / week via AI | 11.5 |
|
||||
| Revenue gains attributed to AI | 66% (22% >10% gains) |
|
||||
|
||||
### Marketing & sales channels
|
||||
|
||||
| Finding | Figure (from source) |
|
||||
| :--- | :--- |
|
||||
| Use social media marketing | 64% |
|
||||
| Rely on word-of-mouth | 58% |
|
||||
| Email marketing | 42% |
|
||||
| Paid online advertising | 35% |
|
||||
| Highest reported ROI channel | Social 34%, then WOM 24% |
|
||||
| Platform importance (income/branding) | Facebook 62%, Instagram 43%, YouTube 36%, LinkedIn 29%, TikTok 26%, Amazon 24% |
|
||||
| Median share of sales from digital/e-commerce | 20% |
|
||||
| Digital platforms make competing with larger firms easier | 74% |
|
||||
| Sales channel mix | Website 53%, social 51%, brick-and-mortar 37%; median **3** channels |
|
||||
| Largest revenue source | Own website 30%, social selling 23%, storefront 14%, online marketplaces 13% |
|
||||
| Majority of revenue from offline (≥51%) | 31% |
|
||||
| Plan to add sales channels next year | 47% |
|
||||
| Median annual digital ad spend | $3,290 |
|
||||
| Plan to increase digital ad spend (12 mo) | 43% |
|
||||
|
||||
### Firmographics (context)
|
||||
|
||||
| Finding | Figure (from source) |
|
||||
| :--- | :--- |
|
||||
| Median employees | 12.2 |
|
||||
| Median 2025 revenue | $684K |
|
||||
| Median business age | 8.5 years |
|
||||
| Location type | Commercial office 38%, home office 27%, retail 7% |
|
||||
|
||||
## Implications for GeoLocal (session synthesis — provisional)
|
||||
|
||||
1. **Owner-AI entry path is timely.** High AI tool count + confidence supports “owner (or their AI) asks how we get discovered” as a real GTM surface alongside web chat.
|
||||
2. **Discovery gap.** AI use clusters on research/content/social — not Core 3 listings. GeoLocal’s free checkup fills an unexamined foundation layer.
|
||||
3. **Peer/WOM GTM.** Peers are the top AI guidance source; WOM is a top marketing channel. Shareable audit proof + partner referral fits the trust path better than vendor-first cold ads.
|
||||
4. **Spend context for later bundles.** Median AI (~$2.2k/yr) and digital ads (~$3.3k/yr) set a ceiling/context for silver/gold — still pin bundles after value-prop angles are captured.
|
||||
5. **Hybrid local reality.** Website + offline + multi-channel remain central; Discovery foundation (NAP + Core 3 + hours) sits under that, not instead of it.
|
||||
6. **Knowledge barrier = free wedge.** Top barrier is training/knowledge; free audit + ranked punch list attacks “I don’t know what to fix” and “AI doesn’t apply to me.”
|
||||
|
||||
## Explicit non-findings
|
||||
|
||||
- No ranked brand list of local SMB SaaS (QuickBooks, Square, Toast, etc.).
|
||||
- No Core 3 / Maps / GBP schema or usage metrics.
|
||||
- Do not treat category % as local-genre gospel without a local-filtered source.
|
||||
|
||||
## Related POR
|
||||
|
||||
- `docs/BUSINESS_PLAN.md` — north star, wedge, owner workflow, tiers
|
||||
- Packaging free/silver/gold: **pinned open** until value-prop angles are fully captured
|
||||
@@ -0,0 +1,14 @@
|
||||
# Go-to-market
|
||||
|
||||
Channel, sales, and competitive materials. Must describe the company in [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) — not a thinner or different product.
|
||||
|
||||
| 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 |
|
||||
|
||||
**Note:** Some GTM docs still reflect older partner-dashboard-first framing. Treat strategy as source of truth until those docs are revised.
|
||||
@@ -0,0 +1,222 @@
|
||||
# Partner & Channel Strategy
|
||||
|
||||
## 1. The Partner-First Thesis
|
||||
|
||||
Your North Star document established the core insight: *distribution is the hardest part of local business SaaS, and the best distribution channel already exists.*
|
||||
|
||||
Agencies, SEO consultants, and Chambers of Commerce already have the trust of local business owners. They are already selling them websites, reputation management, and marketing services. `geolocal.io` doesn't compete with them—it **empowers them** with a new, high-value service they can offer their clients in 15 minutes.
|
||||
|
||||
**The partner-first model solves two problems at once:**
|
||||
1. **Distribution:** You don't need to cold-call business owners. Their agency does it for you.
|
||||
2. **Trust:** Business owners trust their agency. Your product gets a warm introduction, not a cold call.
|
||||
|
||||
**The goal:** Make it so easy for partners to sell and implement `geolocal.io` that they become your primary distribution channel.
|
||||
|
||||
---
|
||||
|
||||
## 2. Partner Types & Value Proposition
|
||||
|
||||
### 2.1 Agency & Consultant Partners (Primary)
|
||||
**Who they are:** SEO agencies, web design firms, digital marketing consultants, reputation management specialists.
|
||||
|
||||
**What they do for their clients:**
|
||||
- Build and maintain websites (WordPress, Webflow, Framer, Shopify)
|
||||
- Optimize Google Business Profiles
|
||||
- Manage Yelp and Google reviews
|
||||
- Run Google Ads and local SEO campaigns
|
||||
|
||||
**What they need:**
|
||||
- A competitive advantage to offer their clients
|
||||
- A simple, white-label solution that requires minimal setup
|
||||
- Recurring revenue stream from their client base
|
||||
|
||||
**Why they'll sell `geolocal.io`:**
|
||||
- "We're making your business discoverable in AI" is a compelling upsell
|
||||
- They can charge $20–50/mo for a service that takes 15 minutes to set up
|
||||
- It makes them look cutting-edge and future-proof
|
||||
- It creates stickiness—once they've set up the MCP, the client is unlikely to switch
|
||||
|
||||
## 2.2 Chamber of Commerce & Tourism Board Customers
|
||||
|
||||
**Who they are:** Local, regional, and state-level Chambers of Commerce; Destination Marketing Organizations (DMOs); tourism boards.
|
||||
|
||||
**Their problem:**
|
||||
- Their members are invisible in AI-driven discovery—98.8% of local businesses are not recommended by ChatGPT
|
||||
- They need to demonstrate value to retain and attract members
|
||||
- They lack the technical expertise to build an AI discovery solution on their own
|
||||
|
||||
**What they need:**
|
||||
- A turnkey AI-discovery benefit they can offer their members
|
||||
- A way to demonstrate ROI to their board and members
|
||||
- A simple implementation that doesn't require technical staff
|
||||
|
||||
**Why they'll buy from `geolocal.io`:**
|
||||
- "We make your members discoverable in AI" is a powerful member retention tool
|
||||
- One contract gives you dozens or hundreds of businesses
|
||||
- Members are pre-vetted and trust the Chamber's endorsement
|
||||
- Chambers can offer it as a free or discounted member benefit
|
||||
|
||||
### CoC as a Lead Generation Channel
|
||||
|
||||
Treating the CoC as a customer creates a secondary revenue stream: **lead generation** for your SMB subscriptions.
|
||||
|
||||
| Step | Action |
|
||||
| :--- | :--- |
|
||||
| **1. CoC signs contract** | You provide AI-discovery service for their members |
|
||||
| **2. You onboard members** | Members get a basic MCP endpoint included in their CoC membership |
|
||||
| **3. You generate leads** | You now have a warm list of member businesses with contact info |
|
||||
| **4. You upsell SMB subscriptions** | Offer premium services (Cal.com booking, rich content, analytics) directly to members |
|
||||
| **5. CoC gets a share** | Revenue share on SMB subscriptions generated from their member list |
|
||||
|
||||
### CoC Pricing Model (illustrates structure, final prices TBD)
|
||||
|
||||
| Tier | Price | What's Included |
|
||||
| :--- | :--- | :--- |
|
||||
| **Community** | $500/mo | Basic MCP endpoints for all members, CoC-branded portal |
|
||||
| **Regional** | $1,000/mo | Community + member analytics dashboard, co-marketing |
|
||||
| **Destination** | $2,500/mo | Regional + featured placements, dedicated account manager, custom integrations |
|
||||
|
||||
---
|
||||
|
||||
## 3. Partner Incentive Structure
|
||||
|
||||
### 3.1 Commission Model
|
||||
|
||||
**Proposal: 20% recurring commission** (illustrates structure, final terms TBD)
|
||||
|
||||
| Tier | Commission | Monthly Revenue Per Client | Partner Monthly Earnings (20 clients) |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| Lite ($20/mo) | 20% | $4/client | $80/mo |
|
||||
| Pro ($49/mo) | 20% | $9.80/client | $196/mo |
|
||||
| Agency (custom) | Negotiated | Custom | Custom |
|
||||
|
||||
*Source: Standard SaaS affiliate/partner commission structures (HubSpot, Cal.com, Shopify)*
|
||||
|
||||
### 3.2 Partner Tiers (illustrates structure, final terms TBD)
|
||||
|
||||
| Tier | Requirements | Benefits |
|
||||
| :--- | :--- | :--- |
|
||||
| **Affiliate** | Sign up, share referral link | 20% commission, dashboard access |
|
||||
| **Partner** | 10+ active clients | 25% commission, co-branded materials, priority support |
|
||||
| **Strategic** | 50+ active clients | 30% commission, dedicated account manager, custom integrations |
|
||||
|
||||
### 3.3 Non-Monetary Incentives
|
||||
|
||||
| Incentive | Why It Works |
|
||||
| :--- | :--- |
|
||||
| **White-label option** | Agencies can present the service as their own |
|
||||
| **Co-branded materials** | Makes the agency look like the innovator |
|
||||
| **Early access to new features** | Makes partners feel valued and invested |
|
||||
| **Public case studies** | Partners get visibility and credibility |
|
||||
|
||||
---
|
||||
|
||||
## 4. Partner Recruitment Strategy
|
||||
|
||||
### 4.1 Target Channels
|
||||
|
||||
| Channel | Why It Works |
|
||||
| :--- | :--- |
|
||||
| **Local SEO agencies** | They're already optimizing for Google and Yelp—AI is the natural next step |
|
||||
| **Web design firms** | They have relationships with business owners and can offer the MCP as an add-on |
|
||||
| **Chamber of Commerce directories** | One partnership unlocks dozens of businesses at once |
|
||||
| **Industry conferences** | Local search, GEO/AEO, and small business marketing events |
|
||||
| **Inbound content** | Blog posts, webinars, and case studies that attract agencies looking for AI solutions |
|
||||
|
||||
### 4.2 Recruitment Pitch for Agencies
|
||||
|
||||
> *"You're already helping your clients dominate Google, Yelp, and the web. Now you can help them dominate the next frontier—agentic AI. With `geolocal.io`, you can add an MCP endpoint to any client's site in 15 minutes. It's the easiest win you'll ever get, and it earns you recurring revenue. No coding, no server management, just a simple JSON file. Let us handle the infrastructure. You handle the client relationships."*
|
||||
|
||||
### 4.3 Recruitment Pitch for Chambers
|
||||
|
||||
> *"Your members are invisible in the new AI-driven discovery channel—98.8% of local businesses aren't recommended by ChatGPT. We can fix that. `geolocal.io` makes every member of your Chamber discoverable by AI agents. It's a turnkey benefit that costs you nothing to offer. Your members pay a small fee; you get a powerful retention tool."*
|
||||
|
||||
---
|
||||
|
||||
## 5. Partner Onboarding & Support
|
||||
|
||||
### 5.1 Onboarding Flow
|
||||
|
||||
| Step | Agency Action | `geolocal.io` Action |
|
||||
| :--- | :--- | :--- |
|
||||
| **1. Sign up** | Complete partner application | Approve, send welcome kit |
|
||||
| **2. Add client** | Enter client's business name and URL | Generate JSON manifest file |
|
||||
| **3. Deploy** | Download file, upload via FTP (or email to client) | MCP endpoint goes live |
|
||||
| **4. Upsell** | Offer Pro tier (Cal.com booking, rich content) | Enable advanced features |
|
||||
|
||||
### 5.2 Partner Support Model
|
||||
|
||||
| Tier | Support Level |
|
||||
| :--- | :--- |
|
||||
| **Self-serve** | Documentation, FAQ, video tutorials |
|
||||
| **Partner** | Email support, 24-hour response |
|
||||
| **Strategic** | Dedicated account manager, quarterly strategy calls |
|
||||
|
||||
---
|
||||
|
||||
## 6. Partner Metrics & KPIs
|
||||
|
||||
| Metric | Target | Why It Matters |
|
||||
| :--- | :--- | :--- |
|
||||
| **Partner acquisition rate** | 50 new partners/month | Drives distribution |
|
||||
| **Client conversion rate** | 30% of partner's clients onboarded | Measures partner effectiveness |
|
||||
| **Average clients per partner** | 5 (Year 1) → 20 (Year 3) | Indicates partner engagement |
|
||||
| **Partner churn** | < 5% annual | Partners should be sticky |
|
||||
| **Time to first client** | < 30 days | Measures onboarding effectiveness |
|
||||
|
||||
---
|
||||
|
||||
## 7. Partner Marketing Collateral
|
||||
|
||||
| Collateral | Purpose |
|
||||
| :--- | :--- |
|
||||
| **Partner One-Pager** | Concise sell-sheet for agencies |
|
||||
| **Partner Deck** | Detailed presentation for onboarding |
|
||||
| **Client Case Studies** | Proof of ROI for agencies to show prospects |
|
||||
| **Co-branded Landing Pages** | White-label version for agency partners |
|
||||
| **Email Templates** | Pre-written outreach for agencies to their clients |
|
||||
|
||||
---
|
||||
|
||||
## 8. Partnership Risks & Mitigation
|
||||
|
||||
| Risk | Mitigation |
|
||||
| :--- | :--- |
|
||||
| **Partners don't sell it** | Make it dead simple; provide co-branded materials; offer commission incentives |
|
||||
| **Partners churn** | Provide excellent support; make switching costs high; offer strategic tier benefits |
|
||||
| **Partners become competitors** | They're selling infrastructure, not building it; maintain your technical moat |
|
||||
| **Partners take too much margin** | Set wholesale pricing; encourage volume discounts |
|
||||
|
||||
---
|
||||
|
||||
## 9. Strategic Partnership Vision
|
||||
|
||||
The long-term goal is to make `geolocal.io` the **default MCP infrastructure provider** for agencies, SEO consultants, and Chambers of Commerce.
|
||||
|
||||
**When an agency asks a client: "Do you want to be discoverable in AI?" the answer is a simple yes, because they can deploy `geolocal.io` in 15 minutes.**
|
||||
|
||||
**When a Chamber looks for a member benefit, `geolocal.io` is the obvious choice.**
|
||||
|
||||
**When a platform (WordPress, Webflow) wants to offer MCP capability to its users, `geolocal.io` is the plugin they integrate.**
|
||||
|
||||
This is the flywheel: more partners → more businesses → more data → better MCP tools → more partners.
|
||||
|
||||
---
|
||||
|
||||
## 10. Key Partner Performance Goals
|
||||
|
||||
| Metric | Target |
|
||||
| :--- | :--- |
|
||||
| **Total partners (Year 1)** | 200+ |
|
||||
| **Partner-sourced clients (Year 1)** | 1,000+ |
|
||||
| **Partner revenue share (Year 1)** | 20% of MRR |
|
||||
| **Average clients per partner (Year 1)** | 5 |
|
||||
| **Partner retention rate** | 95% |
|
||||
|
||||
---
|
||||
|
||||
## 11. Citation Table
|
||||
|
||||
| ID | Source |
|
||||
| :--- | :--- |
|
||||
| [1] | Standard SaaS partner/affiliate commission structures (HubSpot, Cal.com, Shopify) |
|
||||
@@ -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).
|
||||
@@ -0,0 +1,232 @@
|
||||
# Competitive Intelligence Dossier
|
||||
|
||||
## 1. The Competitive Landscape: Market Positioning Map
|
||||
|
||||
The competitive landscape for local business AI discovery is fragmented across three distinct layers. This map illustrates where each player operates and your position relative to them.
|
||||
|
||||
| Layer | Players | Your Position |
|
||||
| :--- | :--- | :--- |
|
||||
| **Consumer-Facing MCP Data Providers** | Yelp, Google (via MCP integrations) | **Downstream** — they provide data to AI agents; you enable businesses to be the data source |
|
||||
| **AI Visibility & Marketing Platforms** | Pie, Mainstreet, VibeAds | **Adjacent** — they help businesses optimize for AI discovery; you provide the infrastructure that makes AI discovery native |
|
||||
| **Data Extraction / Lead Gen Infrastructure** | Apify scrapers, Google Local MCP, Yelp scrapers | **Complementary** — you're not scraping; you're building the source of truth for AI |
|
||||
|
||||
*Source: Competitive analysis based on available market data [citation:1][citation:4][citation:7]*
|
||||
|
||||
|
||||
## 2. Consumer-Facing MCP Data Providers
|
||||
|
||||
These platforms expose their own data to AI agents via MCP servers. They are **not** building infrastructure for businesses to host their own MCP endpoints—they are selling access to their datasets.
|
||||
|
||||
### 2.1 Yelp
|
||||
|
||||
Yelp has aggressively positioned itself as the data provider of choice for AI-driven local discovery, leveraging its proprietary dataset and a multi-tiered paid API model.
|
||||
|
||||
#### MCP Offering
|
||||
|
||||
- Official `yelp-mcp` server on GitHub, exposing tools for natural language business search, details, reviews, photos, menus, and conversational restaurant reservations [citation:1][citation:10]
|
||||
- Tools include: `search_businesses`, `get_business`, `get_reviews`, `search_by_phone`, `count_businesses` [citation:1]
|
||||
- Allows AI agents to not just search but **transact** (reservations available on request) [citation:10]
|
||||
|
||||
#### Strategic Position
|
||||
|
||||
- **Data moat:** 330 million+ reviews, a proprietary dataset that would be extremely expensive and time-consuming to replicate [citation:1]
|
||||
- **Distribution:** Licensing deals with OpenAI, Meta.ai, Bing, Amazon Alexa [citation:10]
|
||||
- **Revenue model:** Charging developers for API access, and licensing data to major AI platforms [citation:10]
|
||||
|
||||
#### Pricing Model
|
||||
|
||||
Yelp's Fusion AI API is priced at a premium, targeting developers and enterprises that need reliable, structured data [citation:1][citation:10].
|
||||
|
||||
| Tier | Cost | Daily Calls | Features |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| Starter | $7.99/1000 calls | 300 | Basic search, business details |
|
||||
| Plus | $9.99/1000 calls | 500 | + Reviews endpoint |
|
||||
| Enterprise | $14.99/1000 calls | More | + Review Highlights |
|
||||
| AI API License | $25/1000 calls | 1,000 minimum | Full premium access, conversational reservations |
|
||||
|
||||
*Source: Yelp Fusion MCP Server documentation [citation:1][citation:10]*
|
||||
|
||||
#### Regulatory Vulnerability
|
||||
|
||||
- Yelp is heavily dependent on Google for distribution and has filed extensive regulatory complaints documenting Google's self-preferencing behavior in search results [citation:12]
|
||||
- This dependency exposes Yelp to the same algorithmic and regulatory risks that have affected other local platforms
|
||||
|
||||
### 2.2 Google (via MCP Infrastructure)
|
||||
|
||||
Google's MCP integration is less visible but arguably more powerful because it controls the primary data source for local discovery: Google Business Profile.
|
||||
|
||||
#### MCP Reach
|
||||
|
||||
- Google Local MCP servers allow AI clients to query Google Local data directly [citation:7]
|
||||
- Community-built servers (e.g., `google-local-mcp`, `google-maps-mcp-server`) provide tools for search, lead generation, and business validation [citation:7][citation:11]
|
||||
|
||||
#### Strategic Position
|
||||
|
||||
- **Integration advantage:** Google's MCP integrations are built on top of Google's own search infrastructure [citation:7]
|
||||
- **Regulatory pressure:** Google is under regulatory scrutiny globally for self-preferencing behavior in local search [citation:12]
|
||||
- **Data advantage:** Google Business Profile remains the authoritative source for local business data—if your GBP data is inconsistent, you are **invisible to voice assistants and AI** [citation:12]
|
||||
|
||||
|
||||
## 3. AI Visibility & Marketing Platforms
|
||||
|
||||
These platforms help businesses **optimize their existing presence** for AI discovery. They don't provide MCP infrastructure—they help businesses show up in AI results.
|
||||
|
||||
### 3.1 Pie (Direct Competitor)
|
||||
|
||||
Pie is the most direct competitor to `geolocal.io` in terms of *go-to-market*. However, their **technical approach is fundamentally different** from your MCP infrastructure play.
|
||||
|
||||
#### Core Product
|
||||
|
||||
Pie is a growth platform for local businesses with three products [citation:4]:
|
||||
|
||||
| Product | Function |
|
||||
| :--- | :--- |
|
||||
| **AI Search** | Optimizes business visibility in AI search (ChatGPT, Claude, Perplexity) |
|
||||
| **Growth** | Manages customer acquisition across Google Maps, Yelp, Nextdoor |
|
||||
| **Front Desk** | AI receptionist that answers calls, takes bookings, and responds to questions 24/7 |
|
||||
|
||||
#### Strategic Position
|
||||
|
||||
- **Funding:** $23.7M total ($19.5M Series A led by Lightspeed Venture Partners) [citation:4]
|
||||
- **Leadership:** Founded by former Square and Toast operators [citation:4]
|
||||
- **Distribution:** Thousands of businesses; embedded partnerships with vertical platforms (e.g., auto-repair system Tekmetric) [citation:4]
|
||||
- **Pricing:** Undercuts agencies—one reported example was ~$359/month (vs. $2,500-$5,000/month for agencies) [citation:4]
|
||||
|
||||
#### Why Pie Is Different From You
|
||||
|
||||
| Aspect | Pie | Your `geolocal.io` |
|
||||
| :--- | :--- | :--- |
|
||||
| **Core offering** | AI-driven **marketing and lead generation** platform | **MCP infrastructure** that makes businesses native to AI |
|
||||
| **Business model** | Subscription-based growth marketing tool | Infrastructure platform + partner distribution |
|
||||
| **Technical approach** | Optimizes existing signals (GBP, website, Yelp) | Exposes business data **directly to AI agents** via MCP |
|
||||
| **Value prop** | "We get you found in AI search" | "You become a direct, interactive source of truth for AI" |
|
||||
|
||||
*Source: Pie's own communications [citation:4]*
|
||||
|
||||
### 3.2 Mainstreet
|
||||
|
||||
Mainstreet is an autonomous AI agent for Google Business Profile management.
|
||||
|
||||
#### Core Product
|
||||
|
||||
Autonomous agent that [citation:3]:
|
||||
- Replies to reviews in the business's voice
|
||||
- Publishes weekly Google Posts automatically
|
||||
- Tracks local map-pack rank across a 5x5 grid
|
||||
- Monitors top 3 competitors weekly
|
||||
|
||||
#### MCP Offering
|
||||
|
||||
Exposes three free tools via `@mainstreet/mcp` [citation:3]:
|
||||
|
||||
| Tool | Function |
|
||||
| :--- | :--- |
|
||||
| `lookup_business` | Returns GBP snapshot: rating, review count, category, address, hours, reviews |
|
||||
| `check_local_rank` | Returns local map-pack rank for a keyword + top 3 competitors |
|
||||
| `request_audit` | Triggers a free 5-minute PDF audit |
|
||||
|
||||
#### Strategic Position
|
||||
|
||||
- **Niche focus:** Reputation management, not infrastructure
|
||||
- **Pricing:** $99/month (single location); $199/month (multi-location) [citation:3]
|
||||
- **Distribution:** Direct-to-business, targeting independent small business owners
|
||||
- **Key insight:** Mainstreet helps businesses *look good* to AI, but doesn't make them *natively discoverable* via MCP
|
||||
|
||||
### 3.3 VibeAds
|
||||
|
||||
VibeAds is a Google Ads optimization MCP server specifically tuned for local service businesses.
|
||||
|
||||
#### Core Product
|
||||
|
||||
MCP server that lets AI query Google Ads data for local service businesses [citation:2]:
|
||||
- Account Health Score (0-100) across 6 dimensions
|
||||
- Search term waste detection
|
||||
- 35+ diagnostic rules
|
||||
- Local-service-first tuning for plumbers, HVAC, electricians, roofers, and 33 more categories
|
||||
|
||||
#### Strategic Position
|
||||
|
||||
- **Niche focus:** Paid ad optimization, not discovery
|
||||
- **MCP approach:** Provides diagnostic tools for AI agents to analyze advertising performance
|
||||
- **Relevance:** Validates the need for local-service-specific MCP tuning
|
||||
|
||||
|
||||
## 4. Data Extraction & Lead Generation Infrastructure
|
||||
|
||||
These platforms provide MCP servers that extract local business data from other platforms. They are **complementary** to your model, as you are building the source of truth rather than extracting it.
|
||||
|
||||
### 4.1 Apify Ecosystem
|
||||
|
||||
Apify hosts a marketplace of MCP servers for extracting business data from Yelp, Google Maps, and Chambers of Commerce.
|
||||
|
||||
| Tool | Function | Pricing |
|
||||
| :--- | :--- | :--- |
|
||||
| Local Business Directory Extractor (single page) | Extract schema.org data from a business page [citation:5] | Usage-based |
|
||||
| Local Business Contact Finder | Scrape Google Maps/Yelp for contact details [citation:9] | From $5.00/1,000 results |
|
||||
| Yelp Business API | Extract Yelp listings by keyword/location [citation:15] | From $0.50/1,000 items |
|
||||
| Local Business Lead Generator | Extract Google Local Services data [citation:14] | $3.00/1,000 businesses |
|
||||
|
||||
#### Why Apify Is Not a Competitor
|
||||
|
||||
- Apify's MCP servers are for **extracting** data, not **enabling** businesses
|
||||
- They help generate leads, not build AI-native business presences
|
||||
- They are a **data extraction layer**, not an **infrastructure layer**
|
||||
|
||||
### 4.2 Google Local MCP Servers
|
||||
|
||||
Several community-built MCP servers allow AI agents to query Google Local data directly.
|
||||
|
||||
| Server | Function |
|
||||
| :--- | :--- |
|
||||
| `google-local-mcp` | Search Google Local for businesses; returns name, address, phone, hours, rating, review count, website, category [citation:7] |
|
||||
| `@nexgendata/google-maps-mcp-server` | Search local businesses, generate leads, validate emails [citation:11] |
|
||||
|
||||
#### Why They Are Not Competitors
|
||||
|
||||
- These servers **extract** Google's data; they don't help businesses own their data
|
||||
- They are lead generation tools, not AI-native business enablement
|
||||
|
||||
|
||||
## 5. Competitive Landscape Summary
|
||||
|
||||
| Competitor | Layer | Core Offering | Direct Threat? |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Yelp** | Data Provider | MCP access to Yelp's data (paid API) | **Yes** — if Yelp offers hosted MCP endpoints for businesses, this is a direct competitive move |
|
||||
| **Google** | Infrastructure | Google Local MCP servers extracting GBP data | **Yes** — Google could integrate MCP discovery into GBP directly |
|
||||
| **Pie** | Marketing Platform | AI-driven growth platform (GEO, marketing automation) | **Yes** — competition for agency/business attention, but different technical approach |
|
||||
| **Mainstreet** | Reputation Management | GBP review and post automation | **No** — adjacent: reputation vs. infrastructure |
|
||||
| **VibeAds** | Ad Optimization | Google Ads diagnostics for local businesses | **No** — niche focus on paid ads |
|
||||
| **Apify** | Data Extraction | Scrapers and MCP servers for lead generation | **No** — complementary: data extraction vs. data source enablement |
|
||||
| **Google Local MCPs** | Data Extraction | Search and lead generation from Google data | **No** — complementary: extraction vs. enablement |
|
||||
|
||||
## 6. The Defensible Position
|
||||
|
||||
Your `geolocal.io` model is the only player building **infrastructure for businesses to own their AI presence**, rather than selling access to their data or optimizing their existing signals. This positions you as:
|
||||
|
||||
1. **Not dependent on Yelp/Google's data** — you enable businesses to be the source of truth
|
||||
2. **Not competing with agencies** — you work through them as a partner channel
|
||||
3. **Not scraping** — you give businesses a direct voice in the agentic economy
|
||||
|
||||
The competitive risk is that Yelp or Google could offer hosted MCP endpoints for businesses, but this would require them to pivot from their current "landlord" model to an "infrastructure" model—a significant strategic shift.
|
||||
|
||||
## 7. Strategic Positioning Statement
|
||||
|
||||
> *"Yelp and Google control the data. Pie optimizes your visibility in their data. `geolocal.io` lets you become the data source."*
|
||||
|
||||
## 8. References
|
||||
|
||||
| # | Source | URL |
|
||||
|---|--------|-----|
|
||||
| [1] | Yelp Fusion MCP Server (official) | <https://github.com/Yelp/yelp-mcp> |
|
||||
| [2] | VibeAds MCP Server (official) | <https://github.com/vibeads/mcp> |
|
||||
| [3] | Mainstreet MCP (`@mainstreet/mcp`) | <https://www.npmjs.com/package/@mainstreet/mcp> |
|
||||
| [4] | Pie raises $23.7M Series A (Lightspeed) | <https://www.morningstar.com/news/business-wire/20260630636582/pie-raises-237m-to-bring-ai-powered-growth-to-main-street-businesses> |
|
||||
| [5] | Apify MCP Server (generic wrapper for any Apify actor) | <https://github.com/apify/apify-mcp-server> |
|
||||
| [6] | The Next Web — "Pie raises $19.5M" (pre-Series A) | <https://thenextweb.com/news/pie-19-5m-ai-search-main-street-businesses> |
|
||||
| [7] | Google Local MCP Server (community) | <https://github.com/johnisanerd/google-local-mcp> |
|
||||
| [9] | Compass — Crawler Google Places (Apify) | <https://apify.com/compass/crawler-google-places> |
|
||||
| [10] | Yelp Data Licensing Pricing | <https://business.yelp.com/data/resources/pricing/> |
|
||||
| [11] | nexgendata Google Maps MCP Server (Apify) | <https://apify.com/nexgendata/google-maps-mcp-server> |
|
||||
| [12] | "Your Google Business Profile Is a Lie and AI Knows It" (Medium) | <https://medium.com/@carlo.cuman/your-google-business-profile-is-a-lie-and-ai-knows-it-5228fd8a4d11> |
|
||||
| [14] | Apify — Lead Generation Use Case | <https://apify.com/use-cases/lead-generation> |
|
||||
| [15] | Yelp Business API (Apify — epctex) | <https://apify.com/epctex/yelp-business-api> |
|
||||
@@ -0,0 +1,234 @@
|
||||
# Competitive Moats & Risks
|
||||
|
||||
## 0. Relationship to the Competitive Intelligence Dossier
|
||||
|
||||
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
|
||||
3. **Key risks:** What could derail us and how to mitigate them
|
||||
4. **The acceleration strategy:** How to win before incumbents can react
|
||||
|
||||
Together, these documents provide a complete view of the competitive landscape and our path to victory.
|
||||
|
||||
|
||||
## 1. The Central Strategic Question
|
||||
|
||||
`geolocal.io` is building a platform to make local businesses discoverable in agentic AI by exposing public business data through a customer-facing MCP endpoint. The data we expose is information the business already shares on their website, Google Business Profile, and other public channels.
|
||||
|
||||
This means the risk profile is fundamentally different from an enterprise MCP deployment. We are not connecting to internal systems, employee emails, or proprietary corporate data. We are simply making structured, machine-readable versions of already-public information.
|
||||
|
||||
**The central question:** Can we build a defensible business before incumbents (Yelp, Google) or nimble competitors (Pie, Mainstreet) replicate our model or render it obsolete?
|
||||
|
||||
---
|
||||
|
||||
## 2. The Unseen Strength: First-Mover Advantage & Critical Mass
|
||||
|
||||
### 2.1 Why First-Mover Advantage Matters Here
|
||||
|
||||
In the agentic AI economy, **being first is not just about brand awareness—it's about training the AI itself.**
|
||||
|
||||
AI agents are not static. They learn, adapt, and build "muscle memory" based on the data sources they encounter most frequently and reliably. A business that is already discoverable through `geolocal.io` when an AI agent first learns to search for local services is more likely to be recommended than a business that appears later.
|
||||
|
||||
This is a form of **AI-native brand equity.** The AI agent has a relationship with the data source. It knows the structure, the reliability, and the value of the information it receives.
|
||||
|
||||
| Stage | What Happens | Why It Matters |
|
||||
| :--- | :--- | :--- |
|
||||
| **Early** | `geolocal.io` is the first MCP endpoint AI agents encounter for a given region or category | The AI learns that `geolocal.io` is a reliable source of local business data |
|
||||
| **Mid** | AI agents begin to **prefer** `geolocal.io` endpoints over scraped or unverified sources | The platform becomes the "default" for local discovery |
|
||||
| **Late** | AI agents actively **expect** `geolocal.io` data and may treat its absence as a negative signal | Competitors cannot easily displace `geolocal.io` because it's baked into the AI's "muscle memory" |
|
||||
|
||||
### 2.2 Critical Mass: The Self-Reinforcing Flywheel
|
||||
|
||||
Critical mass is not just a nice-to-have; it is the **engine of the model.** The value of `geolocal.io` grows exponentially with the number of businesses on the platform:
|
||||
|
||||
- More businesses → more MCP endpoints → more data for AI agents
|
||||
- More data → better "related businesses" recommendations → more value for each business
|
||||
- More value → more agencies want to partner → more businesses join
|
||||
- More businesses → more telemetry data → better insights → more value for agencies and businesses
|
||||
|
||||
**This is the flywheel.** And it only works if we achieve critical mass before competitors do.
|
||||
|
||||
### 2.3 The "Pioneer" Moat
|
||||
|
||||
The phrase *"pioneers get the arrows, settlers get the land"* applies here—but with a twist. In the agentic AI economy, **settlers get the data, and data is the land.**
|
||||
|
||||
| Competitor | What They'd Have to Do | Why It's Harder for Them |
|
||||
| :--- | :--- | :--- |
|
||||
| **Yelp** | Convince businesses that a Yelp-hosted MCP is better than an independent one | Yelp is a landlord, not a partner. Businesses are wary of platform lock-in. |
|
||||
| **Google** | Integrate MCP into GBP without triggering antitrust concerns | Regulatory scrutiny makes bold moves difficult. |
|
||||
| **Pie / Mainstreet** | Build MCP infrastructure from scratch and compete for agencies | They are marketing platforms, not infrastructure providers. They'd need to pivot their core offering. |
|
||||
| **Startup** | Build a similar platform and attract partners and businesses | They are entering a market where `geolocal.io` already has a partner network, data, and AI agent preference. |
|
||||
|
||||
The first mover who achieves critical mass creates a moat that is not just about technology, but about **relationships, data, and AI agent muscle memory.**
|
||||
|
||||
---
|
||||
|
||||
## 3. The Moats: What Makes `geolocal.io` Hard to Replicate
|
||||
|
||||
### 3.1 The Network Effect Moat
|
||||
|
||||
The value of `geolocal.io` increases as more businesses join the platform. This creates the self-reinforcing flywheel described above.
|
||||
|
||||
**Why this matters:** Yelp and Google have network effects too, but they are built around *their* platform, not the businesses themselves. `geolocal.io` gives businesses an independent, portable presence that they control—and that's a different kind of network effect that incumbents would struggle to replicate.
|
||||
|
||||
### 3.2 The Partner Ecosystem Moat
|
||||
|
||||
Our partner-first model creates a distribution advantage:
|
||||
|
||||
- Agencies, SEO consultants, and Chambers trust and use the platform
|
||||
- They have invested time in learning the product and onboarding their clients
|
||||
- Switching costs are high—they would have to retrain and migrate all their clients
|
||||
|
||||
**Why this matters:** This is a classic "switching cost" moat. Once an agency has a significant number of clients set up on `geolocal.io`, moving to a competitor is painful and time-consuming.
|
||||
|
||||
### 3.3 The Simplicity Moat
|
||||
|
||||
`geolocal.io` solves the "son-in-law" problem—the business owner who doesn't know how to code and doesn't want to learn. The technical implementation is dead simple:
|
||||
|
||||
- Add a single JSON file to the business website
|
||||
- No coding, no server management, no security audits
|
||||
- The entire technical burden is handled by `geolocal.io`
|
||||
|
||||
**Why this matters:** Competitors who try to replicate this will need to offer the same level of simplicity, which is harder than it sounds. Pie and Mainstreet are marketing platforms, not infrastructure. They don't offer a direct MCP endpoint. Yelp and Google could, but they would need to build the same level of simplicity and partner-friendly pricing.
|
||||
|
||||
### 3.4 The Telemetry Moat
|
||||
|
||||
Every MCP interaction generates data that no one else has:
|
||||
|
||||
- Which AI platforms are recommending which businesses
|
||||
- Which queries trigger which recommendations
|
||||
- Which businesses are converting discovery to bookings
|
||||
- Real-time demand signals by category and region
|
||||
|
||||
**Why this matters:** This is a proprietary dataset that cannot be replicated without running the same infrastructure. Over time, this data becomes the "source of truth" for agentic local discovery—a powerful asset for licensing and analytics.
|
||||
|
||||
### 3.5 The "Acting in Good Faith" Moat
|
||||
|
||||
In a world where AI agents are trained to avoid risky or unverified sources, being a reliable, well-maintained data source is a defensible advantage:
|
||||
|
||||
- `geolocal.io` is a single, trusted endpoint that AI agents can rely on
|
||||
- It doesn't use scraping, dubious third-party packages, or uncontrolled code
|
||||
- It's simple enough that business owners can trust it
|
||||
|
||||
**Why this matters:** AI agents will prefer stable, trustworthy sources over the chaos of scraping and community-built servers. This is the "Yelp of the agentic era" dynamic: trust at scale.
|
||||
|
||||
### 3.6 First-Mover Advantage at Scale
|
||||
|
||||
The combination of early entry, partner network growth, and telemetry accumulation creates a **pioneer's shield**:
|
||||
|
||||
- **AI agents learn to trust `geolocal.io` data** because they encounter it consistently and reliably
|
||||
- **Agencies standardize on `geolocal.io`** because it's the first and easiest platform they tried
|
||||
- **Businesses get value from the platform** because AI agents are already recommending them
|
||||
- **Competitors face a higher barrier to entry** because they must overcome the network effect and AI agent preference
|
||||
|
||||
---
|
||||
|
||||
## 4. The Risks: What Could Derail `geolocal.io`
|
||||
|
||||
### 4.1 Yelp Offers a Hosted MCP Endpoint
|
||||
|
||||
**The risk:** Yelp decides to offer a similar service—a hosted MCP endpoint for businesses, combined with their superior data (330M+ reviews).
|
||||
|
||||
**Why it matters:** Yelp has the data, the relationships, and the brand awareness. If they offer a free or low-cost hosted MCP, it could significantly undercut our value proposition.
|
||||
|
||||
**Mitigation:**
|
||||
- Focus on the businesses Yelp ignores (the 98.8% with few reviews)
|
||||
- Emphasize the independence of our platform—businesses own their data, not Yelp
|
||||
- Build the partner ecosystem faster than Yelp can launch
|
||||
|
||||
### 4.2 Google Integrates MCP Discovery Directly into GBP
|
||||
|
||||
**The risk:** Google adds native MCP support to Google Business Profile, making the JSON pointer obsolete for businesses already on GBP.
|
||||
|
||||
**Why it matters:** Google controls the primary source of local business data. If they make MCP discoverability a native feature, the independent market for MCP hosting shrinks significantly.
|
||||
|
||||
**Mitigation:**
|
||||
- Build a solution that works alongside Google, not as a replacement
|
||||
- Focus on services and experiences that Google doesn't cover well (ticketed activities, tours, local events)
|
||||
- Provide superior booking and deposit capture that Google's basic MCP might not support
|
||||
|
||||
### 4.3 The JSON Pointer Becomes a Security or Trust Issue
|
||||
|
||||
**The risk:** AI agents (or the platforms that power them) start to distrust or ignore MCP endpoints hosted by third-party providers like `geolocal.io`.
|
||||
|
||||
**Why it matters:** If AI providers see third-party MCP endpoints as a spam or brand-reputation risk, they could restrict or deprioritize them.
|
||||
|
||||
**Mitigation:**
|
||||
- Build a pristine reputation: well-maintained, secure, and lightweight endpoints
|
||||
- Position `geolocal.io` as the trusted intermediary rather than an unknown server
|
||||
- Build direct relationships with AI providers who want reliable local business data
|
||||
|
||||
### 4.4 Consumer Behavior Shifts Away from Agentic AI
|
||||
|
||||
**The risk:** AI adoption plateaus or declines, and consumer preference shifts back to traditional search.
|
||||
|
||||
**Why it matters:** The entire `geolocal.io` thesis rests on the assumption that agentic AI is the future of discovery. If this proves wrong, the market evaporates.
|
||||
|
||||
**Mitigation:**
|
||||
- This risk is low—the adoption data (45% of consumers using AI for local searches) is too strong to ignore
|
||||
- If AI adoption plateaus, `geolocal.io` still provides value as a structured data source for traditional search
|
||||
|
||||
### 4.5 Pie or Mainstreet Extend Their Offerings to MCP Hosting
|
||||
|
||||
**The risk:** Pie or Mainstreet, which already have business relationships and marketing platforms, add MCP hosting as a feature.
|
||||
|
||||
**Why it matters:** They have existing distribution and brand awareness. Their customers trust them. They could undercut our pricing or bundle MCP hosting with existing services.
|
||||
|
||||
**Mitigation:**
|
||||
- Build the partner ecosystem faster; agencies are less likely to switch if they're already using `geolocal.io`
|
||||
- Focus on the simplicity and independence of our platform—Pie and Mainstreet are marketing platforms, not infrastructure providers
|
||||
|
||||
### 4.6 The MCP Standard Becomes Obsolete or Fragments
|
||||
|
||||
**The risk:** MCP is replaced by a competing standard, or multiple incompatible versions fragment the market.
|
||||
|
||||
**Why it matters:** Our entire infrastructure is built on MCP. If the standard shifts, we would need to adapt or be left behind.
|
||||
|
||||
**Mitigation:**
|
||||
- Build at the highest level of abstraction possible—don't lock into a single implementation
|
||||
- Monitor MCP governance (now under the Linux Foundation) and participate in standard-setting
|
||||
- Build a flexible architecture that can adapt to new protocols
|
||||
|
||||
---
|
||||
|
||||
## 5. The Most Likely Competitive Scenario
|
||||
|
||||
Yelp, Google, and Pie are all building versions of this capability. The most likely outcome is a fragmented market where:
|
||||
|
||||
| Player | Strength | Weakness | Position |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Yelp** | Massive data, direct AI licenses | Landlord model, not infrastructure | Will offer a paid, Yelp-centric MCP |
|
||||
| **Google** | GBP ownership, search dominance | Regulatory pressure, self-preferencing | Will integrate MCP into GBP but may face antitrust scrutiny |
|
||||
| **Pie** | Marketing platform, agency relationships | Not building MCP infrastructure | May add MCP as a feature, but not core |
|
||||
| **`geolocal.io`** | Independence, simplicity, partner-friendly | Smaller brand, less data | Will serve the businesses incumbents ignore |
|
||||
|
||||
This is a **defensible niche**—serving the long tail of local businesses that Yelp and Google don't serve well, through a partner ecosystem that values simplicity and independence.
|
||||
|
||||
---
|
||||
|
||||
## 6. The Moat-by-Acceleration Strategy
|
||||
|
||||
Our competitive advantage is not in building a better MCP server. It's in moving faster than incumbents can react and achieving critical mass before they can replicate our model:
|
||||
|
||||
| Priority | Action | Why It Matters |
|
||||
| :--- | :--- | :--- |
|
||||
| **1. Partner network** | Recruit agencies and Chambers aggressively | Distribution is the hardest part; partners solve it |
|
||||
| **2. Simplicity** | Make onboarding frictionless | Yelp and Google are complex; simplicity is our advantage |
|
||||
| **3. Telemetry** | Capture and monetize data | Competitors can't replicate the dataset |
|
||||
| **4. Trust** | Build a pristine reputation | AI agents will prefer trusted sources |
|
||||
|
||||
**The window of opportunity is 12-18 months.** If we can build a significant partner network and telemetry asset in that time, we create a moat that competitors will struggle to cross.
|
||||
|
||||
---
|
||||
|
||||
## 7. Risk Assessment Summary
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| Yelp offers hosted MCP | High | High | Focus on ignored businesses; build partner ecosystem |
|
||||
| Google integrates MCP into GBP | High | Medium | Build complementary solution; focus on services Google ignores |
|
||||
| JSON pointer becomes distrusted | Medium | High | Build pristine reputation; position as trusted intermediary |
|
||||
| Consumer behavior shifts | Low | High | The adoption data is strong; diversify into structured data |
|
||||
| Pie/Mainstreet add MCP hosting | Medium | Medium | Build partner ecosystem first; focus on infrastructure vs. marketing |
|
||||
| MCP standard fragments | Low | Medium | Build flexible architecture; monitor governance |
|
||||
@@ -0,0 +1,80 @@
|
||||
# ICP Definition – geolocal.io
|
||||
|
||||
> **Single source of truth for who we sell to.** Aligns with [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) §1a.
|
||||
> Last updated: 2026-07-18
|
||||
|
||||
---
|
||||
|
||||
## Primary ICP (Tier 1 – best fit)
|
||||
|
||||
| Attribute | Description |
|
||||
|-----------|-------------|
|
||||
| **Business type** | Independent, locally owned SMBs with a **physical location** or clear local service radius. Includes **services and local retail**. |
|
||||
| **Typical verticals** | **Services:** wellness, personal care, home services, auto repair, tourism activities. **Local retail:** general stores, hardware, pharmacies, gift/outfitter shops, specialty food. **Hybrid:** bike shops, marinas, bakeries that sell and serve. |
|
||||
| **Employees** | 1–15 (solo operators to small teams). |
|
||||
| **Revenue** | Roughly $50k–$1M annual gross (directional, not a hard gate). |
|
||||
| **Tech maturity** | Has some web presence (even thin). May use booking tools, POS, or neither. No dedicated AI/engineering team. |
|
||||
| **Pain point** | AI assistants cannot reliably describe them, recommend them, or complete a next step (book, visit, buy/pickup). They lose the “named recommendation” moment. |
|
||||
| **Motivation** | Want AI to tell the truth about what they do or carry — without learning a new craft stack. Will pay if it drives visits, calls, bookings, or sales. |
|
||||
|
||||
**Illustrative retail case:** A general store in Athol, Idaho should be able to make ChatGPT-class assistants answer: we carry toothbrushes; the chicken strips are a local favorite; here are hours and how to get here — from the store’s own structured truth, not a guess.
|
||||
|
||||
---
|
||||
|
||||
## Secondary ICP (Tier 2)
|
||||
|
||||
| Attribute | Description |
|
||||
|-----------|-------------|
|
||||
| **Business type** | Multi-location local brands or regional operators (a handful to ~20 locations). |
|
||||
| **Typical verticals** | Multi-site auto, dental, tutoring, small retail chains with local stores. |
|
||||
| **Motivation** | Standardize AI-readiness across locations with light ops burden. |
|
||||
|
||||
---
|
||||
|
||||
## Intermediate ICP (distribution, not the end SMB)
|
||||
|
||||
| Attribute | Description |
|
||||
|-----------|-------------|
|
||||
| **Type** | Tourism boards, visitor bureaus, chambers of commerce. |
|
||||
| **Job** | Fund and aggregate member AI-readiness; improve destination helpfulness. |
|
||||
| **See** | [UC-02](../product/use-cases/uc-02-intermediate-tourism-board.md) |
|
||||
|
||||
---
|
||||
|
||||
## Shared fit signals
|
||||
|
||||
- Place-based: consumers ask about them with a location in mind
|
||||
- Owner or store manager can decide (not only enterprise procurement)
|
||||
- Willing to put a small discovery pointer on a site or landing page
|
||||
- Some path to value: appointments **or** walk-in/pickup/retail demand **or** both
|
||||
- Often already spending something on ads, SEO, or web help (not mandatory)
|
||||
|
||||
---
|
||||
|
||||
## Buying signals
|
||||
|
||||
1. “ChatGPT / AI doesn’t know we exist” or recommends a competitor
|
||||
2. Phone and foot traffic still matter; online presence is weak or outdated
|
||||
3. Agency or chamber asking about AI search / AI visitor experience
|
||||
4. Tourism or main-street context where “what’s here / what do they have” is the job
|
||||
|
||||
---
|
||||
|
||||
## Anti-ICP (do not target)
|
||||
|
||||
- **Pure e-commerce** with no meaningful local footprint (Shopify’s world)
|
||||
- Enterprise with large dedicated engineering teams building their own agent stack
|
||||
- Pure B2B with no consumer or visitor discovery motion
|
||||
- National marketplaces and travel packagers (Airbnb/Kayak class) as primary customers
|
||||
|
||||
Note: “Does not take online appointments” is **not** automatic anti-ICP. Many strong retail fits will not be booking-led.
|
||||
|
||||
---
|
||||
|
||||
## How to use this file
|
||||
|
||||
- **GTM:** lead scoring and partner briefs
|
||||
- **Product/engineering:** genre packs and data model must support services **and** local retail primitives
|
||||
- **Investors:** wedge is long-tail **local** businesses, not “appointments SaaS only”
|
||||
|
||||
*Update this file first when ICP changes, then propagate.*
|
||||
@@ -0,0 +1,106 @@
|
||||
# geolocal.io — Partner One-Pager
|
||||
|
||||
> **For agencies, SEO consultants, and Chambers of Commerce**
|
||||
|
||||
---
|
||||
|
||||
## Make Your Clients Discoverable in AI — In 15 Minutes
|
||||
|
||||
### The Problem
|
||||
|
||||
- **98.8% of local businesses are invisible to AI.** ChatGPT recommends just 1.2% of local businesses.
|
||||
- 45% of consumers now use AI tools to find local businesses — up from 6% just one year ago.
|
||||
- Your clients are losing customers to competitors who show up in AI results — even if your clients do better work.
|
||||
- **They don't even know they're invisible.** They just see fewer customers and can't figure out why.
|
||||
|
||||
### The Solution
|
||||
|
||||
`geolocal.io` is the infrastructure that makes local businesses **discoverable, bookable, and payable** directly through AI assistants like ChatGPT, Gemini, and Claude.
|
||||
|
||||
**How it works:** One JSON file at `/.well-known/mcp-server`. That's it.
|
||||
|
||||
No coding. No servers to manage. No API keys. No security audits. Just a file that tells AI agents: *"This business exists, here's what it does, here's how to book it."*
|
||||
|
||||
### What AI Sees (Before vs. After)
|
||||
|
||||
**Before `geolocal.io`:**
|
||||
> ChatGPT: *"I found some mechanics in Frisco..."* (generic list, no details, can't book)
|
||||
|
||||
**After `geolocal.io`:**
|
||||
> ChatGPT: *"I found **Frisco German Auto Specialists** — a family-run shop with 40 years of experience specializing in BMW, Mercedes, and Audi. They're open today until 6 PM. I can book you a 9 AM slot and collect a $25 deposit to secure it."*
|
||||
|
||||
---
|
||||
|
||||
## Partner Economics
|
||||
|
||||
### Recurring Commission
|
||||
|
||||
| Tier | Your Share | Per Client (Pro $49/mo) | 20 Clients/mo |
|
||||
|------|-----------|----------------------|---------------|
|
||||
| **Affiliate** | 20% | $9.80 | $196/mo |
|
||||
| **Partner** (10+ clients) | 25% | $12.25 | $245/mo |
|
||||
| **Strategic** (50+ clients) | 30% | $14.70 | $294/mo |
|
||||
|
||||
**This is passive, recurring revenue.** Set it up once, earn it every month.
|
||||
|
||||
### What You Offer Your Clients
|
||||
|
||||
| Plan | Price | What They Get |
|
||||
|------|-------|---------------|
|
||||
| **Lite** | $20/mo | AI discovery, business info, hours, services |
|
||||
| **Pro** | $49/mo | Lite + Cal.com booking, rich content (story, photos), deposits |
|
||||
| **Custom** | TBD | White-label, bulk pricing, API access |
|
||||
|
||||
---
|
||||
|
||||
## 4-Step Onboarding (15 Minutes Total)
|
||||
|
||||
| Step | What You Do | Time |
|
||||
|------|------------|------|
|
||||
| **1. Sign up** | Create your partner account at partners.geolocal.io | 2 min |
|
||||
| **2. Add client** | Enter their business name and website URL | 3 min |
|
||||
| **3. Deploy** | Download the JSON file, upload to their site (or email it) | 5 min |
|
||||
| **4. Upsell** | Offer Pro tier for booking + rich content | 5 min |
|
||||
|
||||
**That's it.** The MCP endpoint goes live. AI agents can now discover and recommend the business.
|
||||
|
||||
---
|
||||
|
||||
## Why `geolocal.io` — Not Pie, Mainstreet, or Yelp?
|
||||
|
||||
| | **geolocal.io** | Pie | Mainstreet | Yelp |
|
||||
|---|---|---|---|---|
|
||||
| **What it is** | MCP infrastructure | Marketing platform | GBP automation | Data landlord |
|
||||
| **MCP endpoint** | ✅ Native | ❌ | Partial | Paid API only |
|
||||
| **Booking from AI** | ✅ Direct | ❌ | ❌ | ❌ |
|
||||
| **Business owns data** | ✅ Independent | Platform-locked | Platform-locked | Platform-locked |
|
||||
| **Partner-friendly** | ✅ 20-30% commission | Reseller model | Direct-to-business | Landlord model |
|
||||
|
||||
**geolocal.io is infrastructure.** Pie and Mainstreet optimize visibility in existing platforms. We **become the data source** that AI agents query directly.
|
||||
|
||||
---
|
||||
|
||||
## What Makes This Defensible
|
||||
|
||||
1. **AI muscle memory** — the more AI agents use `geolocal.io` endpoints, the more they learn to prefer them. First movers get locked in.
|
||||
2. **Partner network effects** — once your agency has 20 clients on `geolocal.io`, switching is painful. We make onboarding frictionless.
|
||||
3. **Telemetry data** — every MCP interaction generates proprietary data no one else has. We'll use it to improve recommendations and offer insights.
|
||||
4. **Simplicity** — one JSON file. No competitors offer this level of simplicity for MCP deployment.
|
||||
|
||||
---
|
||||
|
||||
## Your Next Step
|
||||
|
||||
**Become a partner:** partners.geolocal.io
|
||||
|
||||
Or reply to this one-pager — we'll get you set up and your first client live in under an hour.
|
||||
|
||||
---
|
||||
|
||||
> *"You're already helping your clients dominate Google. Now help them dominate AI — and earn recurring revenue doing it."*
|
||||
|
||||
**geolocal.io** — The AI discovery layer for local commerce
|
||||
|
||||
---
|
||||
|
||||
> *Full market data and citations: [Market data and analysis](../investors/market-data-and-analysis.md)*
|
||||
@@ -0,0 +1,226 @@
|
||||
# Sales & Marketing Playbook
|
||||
|
||||
## 1. The Core Message: Discovery, Story, Visuals, Booking
|
||||
|
||||
`geolocal.io` helps local businesses get **discovered** in AI, tell their **story**, showcase their **visuals**, and enable **bookings and deposits** directly from ChatGPT—without requiring any technical expertise.
|
||||
|
||||
| Component | What It Means For a Local Business |
|
||||
| :--- | :--- |
|
||||
| **Discovered** | When someone asks ChatGPT "who's the best mechanic in Frisco?", your business appears in the answer |
|
||||
| **Story** | The AI knows your history, your specialties, and what makes you unique |
|
||||
| **Visuals** | The AI can show photos of your work, your team, and your space |
|
||||
| **Booking** | A customer can set an appointment directly from the chat |
|
||||
| **Deposit** | The customer puts down a deposit to secure the time slot—all without leaving the AI interface |
|
||||
|
||||
**This is the sizzle.** The steak is the MCP server. The sizzle is what business owners actually care about: more customers, more bookings, and less friction.
|
||||
|
||||
**The value prop:** `geolocal.io` turns a local business from invisible in AI to discoverable, bookable, and payable—directly from the chat interfaces people are already using.
|
||||
|
||||
---
|
||||
|
||||
## 2. The 98.8% Problem: Why Local Businesses Are Invisible Today
|
||||
|
||||
**The current reality:**
|
||||
- ChatGPT recommends **just 1.2% of local businesses**
|
||||
- 45% of consumers now use AI tools to find local businesses
|
||||
- If your business isn't in that 1.2%, **you don't exist** to the 45% of consumers using AI
|
||||
|
||||
**What that means for the local business owner:**
|
||||
- When someone asks "who's the best mechanic in Frisco?", ChatGPT recommends someone else—or worse, no one specific
|
||||
- They are losing customers to competitors who are showing up in AI results, even if their work isn't as good
|
||||
- They don't even know they're invisible—they just see fewer customers and can't figure out why
|
||||
|
||||
---
|
||||
|
||||
## 3. The `geolocal.io` Solution: Making Businesses Discoverable
|
||||
|
||||
### 3.1 What `geolocal.io` Does For a Business
|
||||
|
||||
| Feature | How It Works | What the Business Gets |
|
||||
| :--- | :--- | :--- |
|
||||
| **AI Discovery** | We add a simple file to the business's website that tells AI agents "I exist, here's what I do" | The business shows up when people ask ChatGPT for their service |
|
||||
| **Rich Business Profile** | We pull the business's photos, story, services, and pricing into a structured format AI can read | The AI knows the business's history, specialties, and pricing |
|
||||
| **Visuals That Sell** | We make the business's best photos accessible to AI (work samples, team photos, location shots) | ChatGPT can show users what the business looks like |
|
||||
| **Booking Integration** | We connect the business's Cal.com calendar so AI can check availability and book appointments | Customers can book directly from ChatGPT |
|
||||
| **Deposit Capture** | We integrate Stripe so customers can put down a service deposit at the time of booking | The business gets paid before the appointment—no-shows become a thing of the past |
|
||||
| **Smart Recommendations** | The AI learns the business's strengths and recommends it for the right jobs | The business gets more qualified leads, not just tire-kickers |
|
||||
|
||||
### 3.2 How It Works (Business Owner's View)
|
||||
|
||||
| Step | What Happens | Business Owner's Effort |
|
||||
| :--- | :--- | :--- |
|
||||
| **1. Sign up** | Fill out a simple form with business name, address, and services | 5 minutes |
|
||||
| **2. We generate a file** | We create a simple JSON file for their website | 0 minutes |
|
||||
| **3. Add the file** | The business owner (or their agency) uploads the file to their website | 5 minutes |
|
||||
| **4. Connect calendar** | Link their Cal.com account (or we set it up for them) | 10 minutes |
|
||||
| **5. Go live!** | AI agents can now discover, recommend, and book them | — |
|
||||
|
||||
**Total effort: 20 minutes. Total cost: $20/mo. Total impact: The business is now discoverable by AI.**
|
||||
|
||||
### 3.3 The "Wow" Moment: Discovery to Deposit
|
||||
|
||||
When a potential customer asks:
|
||||
|
||||
> *"I need a mechanic in Frisco who works on German cars, is open tomorrow, and costs under $100 for an oil change."*
|
||||
|
||||
Without `geolocal.io`: ChatGPT suggests generic options, maybe from a web search, but the specific business isn't mentioned.
|
||||
|
||||
With `geolocal.io`:
|
||||
1. **Discovery:** ChatGPT searches the web and finds the business's MCP endpoint
|
||||
2. **Story:** ChatGPT reads the business's profile: "Family-run shop with 40 years of experience, specializing in BMW, Mercedes, and Audi."
|
||||
3. **Visuals:** ChatGPT shows a photo of the clean shop and service bays
|
||||
4. **Availability:** ChatGPT checks the business's Cal.com calendar and sees a 9 AM slot open
|
||||
5. **Booking:** ChatGPT asks the user: "I can book you for 9 AM. Would you like to put down a $25 deposit to secure the slot?"
|
||||
6. **Deposit:** The user says yes, ChatGPT processes the payment via Stripe, and the business gets a confirmed appointment—all without lifting a finger.
|
||||
|
||||
**This is the experience `geolocal.io` enables.**
|
||||
|
||||
---
|
||||
|
||||
## 4. Target Audiences & Messaging
|
||||
|
||||
### 4.1 The Local Business Owner
|
||||
**Who:** Independent local business owners—mechanics, salons, plumbers, gyms, restaurants.
|
||||
|
||||
**Their pain:** "I'm not getting the calls I used to. Google rankings aren't working like they used to. I don't know how to get in front of these new AI things."
|
||||
|
||||
**Message:** "When customers ask ChatGPT 'who's the best in my city?', we make sure you're the answer. We tell your story, show your photos, and even let customers book and pay from the chat—no tech skills required."
|
||||
|
||||
**Call to action:** "See how you look in AI—free audit."
|
||||
|
||||
### 4.2 The Agency (The Partner)
|
||||
**Who:** Local SEO agencies, web designers, digital marketing consultants.
|
||||
|
||||
**Their pain:** "I need to offer my clients cutting-edge services, but I don't have the technical resources to build AI discovery tools myself. I'm losing clients to competitors who seem more advanced."
|
||||
|
||||
**Message:** "You're already helping your clients dominate Google. Now you can help them dominate AI—and earn recurring revenue doing it. We handle the MCP infrastructure; you handle the client relationships. It's a 15-minute add-on that makes you look like a genius."
|
||||
|
||||
**Call to action:** "Become a partner and start earning 20% recurring commission."
|
||||
|
||||
### 4.3 The Chamber (The Strategic Customer)
|
||||
**Who:** Chamber of Commerce directors, tourism board executives, DMO leaders.
|
||||
|
||||
**Their pain:** "We need to show our members value, but we don't have tech resources. We're worried our city is being left behind in the AI shift."
|
||||
|
||||
**Message:** "98.8% of local businesses aren't recommended by ChatGPT. Your members are invisible. We can fix that—with a turnkey benefit that makes your entire membership discoverable by AI. One contract covers every member."
|
||||
|
||||
**Call to action:** "Schedule a demo to see how your city looks in AI."
|
||||
|
||||
---
|
||||
|
||||
## 5. Marketing Channels & Tactics
|
||||
|
||||
### 5.1 Agency Partner Recruitment
|
||||
|
||||
**Primary channel:** Direct outreach to local SEO agencies and web design firms.
|
||||
|
||||
**Tactic:** Offer a free audit of their client's AI visibility—then show them the opportunity:
|
||||
> *"Of your 20 clients, ChatGPT recommends [0-1] of them. Here's what it would look like if they were all discoverable—and how you'd earn recurring revenue for every one of them."*
|
||||
|
||||
**Message:** "We don't compete with you. We make you look like the expert. You handle your clients, we handle the MCP infrastructure, and you earn 20% recurring commission."
|
||||
|
||||
### 5.2 Direct SMB Recruitment
|
||||
|
||||
**Primary channel:** Partner-introduced.
|
||||
|
||||
**Tactic:** The agency does the introduction; you close the deal. The agency earns commission; you earn MRR.
|
||||
|
||||
**Message:** "Your agency partner recommended you. We're the company that makes you discoverable in AI. Here's a free audit showing how you look today."
|
||||
|
||||
**Secondary channel:** Local SEO content.
|
||||
**Tactic:** Blog posts, guides, and webinars on GEO/AEO for local businesses—ranked for terms like "AI discovery for local businesses" and "how to get recommended by ChatGPT."
|
||||
|
||||
### 5.3 Chamber & Tourism Board Recruitment
|
||||
|
||||
**Primary channel:** Direct outreach to Chamber directors and tourism board executives.
|
||||
|
||||
**Tactic:** Offer a free city-wide AI visibility report:
|
||||
> *"Here's how many of your members are discoverable in AI today. Here's what it would look like if all of them were. Here's how we can make that happen—at no cost to you."*
|
||||
|
||||
**Message:** "We're not asking for a budget. We're asking for a partnership. Your members get a powerful benefit; you get a powerful retention tool."
|
||||
|
||||
### 5.4 Content Marketing
|
||||
|
||||
**Content themes:**
|
||||
- **The 98.8% Problem:** Why most local businesses are invisible in AI
|
||||
- **Getting Discovered:** How to show up in ChatGPT, Gemini, and Claude
|
||||
- **Storytelling for AI:** How to make your business memorable to AI agents
|
||||
- **Booking from Chat:** How to capture customers directly from AI interfaces
|
||||
|
||||
**Formats:** Blog posts, whitepapers, webinars, podcasts.
|
||||
|
||||
---
|
||||
|
||||
## 6. Sales Process & Scripts
|
||||
|
||||
### 6.1 The "Discovery" Call (Agency Prospect)
|
||||
|
||||
**Opening:**
|
||||
"Hi [Agency Name], this is [Your Name] from `geolocal.io`. I'm calling because we help agencies like yours offer their clients a new service: AI discovery and booking. I'd love to show you how it works. Do you have 10 minutes?"
|
||||
|
||||
**The hook:**
|
||||
"Your clients are invisible in AI today. ChatGPT recommends just 1.2% of local businesses. We fix that. We make every one of your clients discoverable, bookable, and payable directly from ChatGPT. It takes 15 minutes to set up—and you earn 20% recurring commission on every client."
|
||||
|
||||
**Objection handling:**
|
||||
|
||||
| Objection | Response |
|
||||
| :--- | :--- |
|
||||
| "My clients are on Google—AI isn't relevant yet." | "45% of consumers now use AI to find local businesses. That's millions of customers bypassing Google. Your clients are losing business today." |
|
||||
| "I don't understand MCP." | "You don't need to. We handle the infrastructure. You handle your clients." |
|
||||
| "My clients won't pay for this." | "It's $20/mo. That's less than a coffee a day. And you can present it as a new service you're offering." |
|
||||
| "How do I know it works?" | "We have a 30-day money-back guarantee. If you don't see a difference, we refund every dollar." |
|
||||
|
||||
### 6.2 The "Visibility Audit" Call (SMB Prospect)
|
||||
|
||||
**Opening:**
|
||||
"Hi [Name], this is [Your Name] from `geolocal.io`. I'm calling because I noticed your business isn't showing up in AI search. When people ask ChatGPT 'who's the best mechanic in Frisco?', you're not mentioned. I'd love to show you what that means for your business."
|
||||
|
||||
**The hook:**
|
||||
"Here's the deal: 45% of people now use ChatGPT to find local businesses. If you're not showing up, you're losing customers. We help businesses like yours show up in AI—and even let customers book appointments directly from the chat."
|
||||
|
||||
**The story:**
|
||||
"Imagine this: Someone asks ChatGPT for a mechanic who specializes in German cars, is open tomorrow, and costs under $100. ChatGPT recommends you. It shows your photos, your story, and your availability. The user books an appointment and puts down a deposit—all without calling you. That's what we do."
|
||||
|
||||
### 6.3 The "City Opportunity" Call (Chamber Prospect)
|
||||
|
||||
**Opening:**
|
||||
"Hi [Director], this is [Your Name] from `geolocal.io`. I'm calling because I've analyzed your city's visibility in AI, and I think your members are missing a huge opportunity."
|
||||
|
||||
**The hook:**
|
||||
"98.8% of local businesses aren't recommended by ChatGPT. Your members are invisible in the new AI economy. We can fix that. We make every one of your members discoverable, bookable, and payable by AI agents. It's a member benefit that costs you nothing to offer—and gives you a powerful reason for them to renew."
|
||||
|
||||
**The story:**
|
||||
"Imagine if every Chamber member had a rich profile that AI agents could discover—their story, their photos, their services, their booking availability. When someone asks ChatGPT for a recommendation, they're referred to one of your members. That's a retention tool you can't buy."
|
||||
|
||||
---
|
||||
|
||||
## 7. Marketing Collateral
|
||||
|
||||
| Collateral | Format | Audience | Purpose |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Discovery Demo Video** | 2-minute video | Everyone | Show the "discovery to deposit" experience |
|
||||
| **Case Study: A Local Business** | PDF/Web page | SMBs | Show how a business went from invisible to booked |
|
||||
| **Agency One-Pager** | PDF | Agencies | Sell the partner opportunity |
|
||||
| **Chamber One-Pager** | PDF | CoCs | Sell the member benefit |
|
||||
| **Free Audit Tool** | Web app | SMBs | Show SMBs their AI invisibility |
|
||||
| **Partner Deck** | Google Slides | Partners | Onboard and enable partners |
|
||||
| **Email Templates** | Google Doc | SDRs | Outreach to SMBs and agencies |
|
||||
|
||||
---
|
||||
|
||||
## 8. Key Metrics & KPIs
|
||||
|
||||
| Metric | Year 1 Target | Year 2 Target | Year 3 Target |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Partner acquisition rate** | 10/mo | 25/mo | 50/mo |
|
||||
| **Active partners** | 50 | 150 | 300 |
|
||||
| **SMB clients** | 1,000 | 5,000 | 25,000 |
|
||||
| **Partner-sourced ARR** | 20% | 35% | 45% |
|
||||
| **Average clients per partner** | 5 | 15 | 30 |
|
||||
| **Time to first client** | < 30 days | < 20 days | < 15 days |
|
||||
| **Partner NPS** | 40+ | 50+ | 60+ |
|
||||
|
||||
---
|
||||
|
||||
> *Full market data and citations: [Market data and analysis](../investors/market-data-and-analysis.md)*
|
||||
> *Full competitive analysis: [Competitive intelligence](./competitive/intelligence.md)*
|
||||
@@ -0,0 +1,8 @@
|
||||
# Investors
|
||||
|
||||
External packaging of market and financial material. Align narrative with [Canonical Strategy](../strategy/CANONICAL_STRATEGY.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 |
|
||||
@@ -0,0 +1,226 @@
|
||||
# Business & Financial Model
|
||||
|
||||
## 1. Revenue Model Overview
|
||||
|
||||
`geolocal.io` generates revenue through a three-tiered model designed to capture value at every layer of the agentic economy.
|
||||
|
||||
| Revenue Stream | Description | Target Customer |
|
||||
| :--- | :--- | :--- |
|
||||
| **MCP Infrastructure Subscriptions** | Recurring monthly fees for hosting and managing MCP endpoints | Agencies (for their clients) and direct SMBs |
|
||||
| **Chamber of Commerce / Tourism Board Contracts** | Annual or monthly contracts for member-wide MCP coverage | CoCs, DMOs, tourism boards |
|
||||
| **Data-as-a-Service (DaaS)** | Licensing anonymized telemetry data to third parties | Market research firms, AI companies, local marketing platforms |
|
||||
|
||||
---
|
||||
|
||||
## 2. MCP Infrastructure Subscriptions
|
||||
|
||||
### 2.1 Pricing Tiers (final pricing TBD)
|
||||
|
||||
| Tier | Price | What's Included | Target Customer |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Lite** | $20/mo | Basic MCP endpoint: business info, hours, location, services list, Google review feed | Individual SMBs, agencies |
|
||||
| **Pro** | $49/mo | Lite + Cal.com booking integration, rich content (story, photos), enhanced analytics | SMBs with booking needs, agencies |
|
||||
| **Agency** | Custom | White-label version, bulk pricing, API access, dedicated support, advanced analytics | Agencies with 10+ clients |
|
||||
|
||||
### 2.2 Unit Economics (Lite Tier) - (final pricing TBD)
|
||||
|
||||
| Metric | Value |
|
||||
| :--- | :--- |
|
||||
| Monthly recurring revenue (MRR) per business | $20 |
|
||||
| Partner commission (20%) | $4 |
|
||||
| **Net revenue per business** | **$16** |
|
||||
| Annual net revenue per business | $192 |
|
||||
|
||||
---
|
||||
|
||||
## 3. Chamber of Commerce & Tourism Board Contracts
|
||||
|
||||
### 3.1 Pricing Tiers (final pricing TBD)
|
||||
|
||||
| Tier | Price | What's Included |
|
||||
| :--- | :--- | :--- |
|
||||
| **Community** | $500/mo | Basic MCP endpoints for all members, CoC-branded portal, basic analytics |
|
||||
| **Regional** | $1,000/mo | Community + member analytics dashboard, co-marketing, lead reporting |
|
||||
| **Destination** | $2,500/mo | Regional + featured placements, dedicated account manager, custom integrations, white-label portal |
|
||||
|
||||
### 3.2 Lead Generation Value
|
||||
|
||||
Each CoC contract provides a warm lead list of member businesses. The value of this lead generation is captured through:
|
||||
|
||||
- **Upsell to Pro tier** (conversion rate estimated at 15-25%)
|
||||
- **Direct SMB subscriptions** from members who are not covered by the CoC contract
|
||||
- **Partner referrals** (agencies can be introduced to CoC members)
|
||||
|
||||
---
|
||||
|
||||
## 4. Data-as-a-Service (DaaS)
|
||||
|
||||
### 4.1 The Telemetry Asset
|
||||
|
||||
Every MCP interaction generates valuable data. This telemetry creates a proprietary dataset that is impossible to replicate.
|
||||
|
||||
#### What Telemetry Captures
|
||||
|
||||
| Category | Data Points |
|
||||
| :--- | :--- |
|
||||
| **Discovery Patterns** | Query terms, business citations, AI platform used, time of day, location |
|
||||
| **AI Behavior** | Which MCP tools are called most frequently, tool call sequences, average response times |
|
||||
| **Business Performance** | Citation frequency, booking conversion rates, agent feedback reports, discrepancy reports |
|
||||
| **Competitive Intelligence** | How businesses compare to competitors in their category and region, citation share by market |
|
||||
| **Market Trends** | Emerging demand signals, seasonal patterns, category growth/decline, regional differences |
|
||||
|
||||
#### Why This Telemetry Is Valuable
|
||||
|
||||
| Reason | Explanation |
|
||||
| :--- | :--- |
|
||||
| **Unique dataset** | No other platform has a real-time view of agentic discovery across thousands of local businesses |
|
||||
| **Predictive value** | You can identify trends before they become visible in traditional search data |
|
||||
| **Attribution** | You know exactly which AI platform drove which business citation and booking |
|
||||
| **Source of truth** | You are building the definitive record of how the agentic economy interacts with local businesses |
|
||||
|
||||
### 4.2 DaaS Product Line
|
||||
|
||||
| Product | Description | Target Customer |
|
||||
| :--- | :--- | :--- |
|
||||
| **AI Local Demand Index** | Weekly anonymized report showing which categories are seeing AI discovery growth in specific regions | Market research firms, investment analysts |
|
||||
| **Competitive Benchmarking** | Anonymized comparative performance data for businesses within a category and region | Agencies, CoCs |
|
||||
| **Agent Behavior Analytics** | Aggregated data on how different AI platforms discover and interact with local businesses | AI companies, MCP server developers |
|
||||
| **Custom Data Feeds** | Tailored datasets for specific research needs | Enterprise customers |
|
||||
|
||||
### 4.3 DaaS Pricing Model
|
||||
|
||||
| Product | Pricing Model | Estimated Price |
|
||||
| :--- | :--- | :--- |
|
||||
| **AI Local Demand Index** | Monthly subscription | $500–$2,000/mo |
|
||||
| **Competitive Benchmarking** | Per-report fee | $50–$500/report |
|
||||
| **Agent Behavior Analytics** | Annual license | $10,000–$50,000/year |
|
||||
| **Custom Data Feeds** | Negotiated | $25,000+ |
|
||||
|
||||
---
|
||||
|
||||
## 5. Combined Revenue Projections (based on the placeholder pricing models)
|
||||
|
||||
| Revenue Stream | Year 1 | Year 2 | Year 3 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| MCP Subscriptions | $192,000 | $960,000 | $4,800,000 |
|
||||
| CoC Contracts | $45,000 | $300,000 | $1,800,000 |
|
||||
| DaaS | $0 | $75,000 | $625,000 |
|
||||
| **Total Annual Revenue** | **$237,000** | **$1,335,000** | **$7,225,000** |
|
||||
| **Total MRR (end of year)** | **$19,750** | **$111,250** | **$602,083** |
|
||||
|
||||
---
|
||||
|
||||
## 6. Cost Structure (Self-Funded Model)
|
||||
|
||||
### 6.1 Operating Costs
|
||||
|
||||
| Category | Year 1 (Monthly) | Year 1 (Annual) |
|
||||
| :--- | :--- | :--- |
|
||||
| **Infrastructure (hosting, database, CDN)** | $500 | $6,000 |
|
||||
| **Cal.com / Stripe fees** | $200 | $2,400 |
|
||||
| **Team (part-time/fractional)** | $8,000 | $96,000 |
|
||||
| **Marketing & Sales** | $1,500 | $18,000 |
|
||||
| **Legal & Administrative** | $500 | $6,000 |
|
||||
| **Total Monthly / Annual** | **$10,700** | **$128,400** |
|
||||
|
||||
### 6.2 Cost Optimization for Self-Funding
|
||||
|
||||
| Strategy | Rationale |
|
||||
| :--- | :--- |
|
||||
| **Founder-led development** | You are the primary dev/PM, eliminating the need for early technical hires |
|
||||
| **Fractional/founder partners** | Up to 25% ownership share for key partners, reducing cash compensation |
|
||||
| **Infrastructure cost discipline** | Start with cost-effective hosting (Railway free tier, then pay-as-you-grow) |
|
||||
| **Low-cost GTM** | Partner-first distribution reduces sales overhead |
|
||||
| **Modular build** | Build only the MVP; add features as revenue grows |
|
||||
|
||||
### 6.3 Unit Economics (Per Business)
|
||||
|
||||
| Metric | Lite Tier ($20/mo) | Pro Tier ($49/mo) |
|
||||
| :--- | :--- | :--- |
|
||||
| Hosting cost (est.) | $0.50/mo | $0.50/mo |
|
||||
| Partner commission (20%) | $4.00/mo | $9.80/mo |
|
||||
| Cal.com/Stripe fees | $0.00 | $1.00/mo |
|
||||
| **COGS per business** | **$4.50/mo** | **$11.30/mo** |
|
||||
| **Gross margin** | **77.5%** | **76.9%** |
|
||||
|
||||
---
|
||||
|
||||
## 7. Financial Runway & Break-Even
|
||||
|
||||
### 7.1 Capital Requirements
|
||||
|
||||
The founder-funded model requires careful cash management. Capital needs are significantly lower than a venture-funded approach due to the lean cost structure.
|
||||
|
||||
**Key assumptions:**
|
||||
- Founder contribution covers Year 1 operating costs ($128,400)
|
||||
- Revenue begins in Month 3
|
||||
- Partner equity grants (up to 25% total) reduce cash compensation needs
|
||||
|
||||
### 7.2 Break-Even Timeline
|
||||
|
||||
| Metric | Year 1 | Year 2 |
|
||||
| :--- | :--- | :--- |
|
||||
| Annual Revenue | $237,000 | $1,335,000 |
|
||||
| Annual Operating Costs | $128,400 | $200,000 |
|
||||
| **Net Income (Loss)** | **$108,600** | **$1,135,000** |
|
||||
| **Break-Even** | Month 10 | — |
|
||||
|
||||
*Assumes revenue scaling, controlled cost growth, and partner-led GTM.*
|
||||
|
||||
### 7.3 Reinvestment Strategy
|
||||
|
||||
| Phase | Action |
|
||||
| :--- | :--- |
|
||||
| **Year 1** | Reinvest profits into infrastructure and partner recruitment |
|
||||
| **Year 2** | Begin hiring key roles (sales, support) |
|
||||
| **Year 3** | Fund product expansion (plugins, DaaS) with operating cash flow |
|
||||
|
||||
---
|
||||
|
||||
## 8. Key Financial Metrics & KPIs
|
||||
|
||||
| Metric | Year 1 Target | Year 2 Target | Year 3 Target |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **MRR** | $19,750 | $111,250 | $602,083 |
|
||||
| **ARR** | $237,000 | $1,335,000 | $7,225,000 |
|
||||
| **Gross margin** | 70%+ | 75%+ | 80%+ |
|
||||
| **Customer acquisition cost (CAC)** | $100 | $80 | $60 |
|
||||
| **Customer lifetime value (LTV)** | $500 | $600 | $750 |
|
||||
| **LTV:CAC ratio** | 5:1 | 7.5:1 | 12.5:1 |
|
||||
| **Partner acquisition rate** | 50/mo | 75/mo | 100/mo |
|
||||
| **Partner-sourced clients** | 1,000 | 5,000 | 25,000 |
|
||||
| **Cash runway** | 18-24 months | — | — |
|
||||
|
||||
---
|
||||
|
||||
## 9. Strategic Considerations for Self-Funding
|
||||
|
||||
### 9.1 Advantages of Self-Funding
|
||||
|
||||
| Advantage | Why It Matters |
|
||||
| :--- | :--- |
|
||||
| **Full ownership** | No investor dilution; you retain control and upside |
|
||||
| **Product focus** | No pressure to over-hire or overspend; build lean |
|
||||
| **Partner alignment** | Equity partners are invested in long-term success, not quick exits |
|
||||
| **Grounded decision-making** | Resource constraints force focus on what actually works |
|
||||
|
||||
### 9.2 Risks & Mitigation
|
||||
|
||||
| Risk | Mitigation |
|
||||
| :--- | :--- |
|
||||
| **Slower growth** | Accept slower, sustainable growth; focus on high-margin, low-touch customers |
|
||||
| **Founder burnout** | Leverage partner equity to share workload; prioritize MVP and delegate low-value tasks |
|
||||
| **Competitor acceleration** | Focus on defensible moats (telemetry, partner network, data assets) that scale with your growth |
|
||||
| **Underestimating costs** | Build with a 20% buffer; use cost-effective tools; delay hiring until revenue supports it |
|
||||
|
||||
---
|
||||
|
||||
## 10. Citation Table
|
||||
|
||||
| ID | Source |
|
||||
| :--- | :--- |
|
||||
| [1] | Standard SaaS pricing benchmarks |
|
||||
| [2] | HubSpot, Cal.com, Shopify partner commission structures |
|
||||
| [3] | Stripe, Cal.com pricing documentation |
|
||||
| [4] | AWS, Railway, CreateOS hosting cost estimates |
|
||||
| [5] | Industry benchmarks for SMB SaaS gross margins |
|
||||
@@ -0,0 +1,128 @@
|
||||
# Market Data & Analysis
|
||||
|
||||
## 1. The AI Local Discovery Shift
|
||||
|
||||
The local business discovery landscape is undergoing a structural transformation driven by Generative AI. In just one year, consumer adoption of AI for local business discovery has increased more than sevenfold.
|
||||
|
||||
### Key Adoption Metrics
|
||||
|
||||
- **45% of consumers** now use AI tools (ChatGPT, Gemini, Perplexity) to find local businesses—up from just **6% one year earlier** [1]. This represents one of the fastest behavioral changes ever recorded in consumer search history [1].
|
||||
- **AI is now the third most-used business discovery channel**, behind only Google and Facebook. It has already passed Yelp and TripAdvisor [1].
|
||||
- **44% of AI-search users now consider AI their primary information source**—ahead of traditional search at 31% [1].
|
||||
- **31% of consumers use AI tools for local business recommendations** on at least a monthly basis. Only 19% said they wouldn't consider using AI to find a local business [1].
|
||||
- **63% of active AI users trust AI recommendations** for local businesses, and **64% trust AI as much as they trust online reviews** [1].
|
||||
- **58% of consumers have tried AI tools for local business recommendations** [1].
|
||||
- **ChatGPT alone has roughly 900 million weekly active users**—a platform that didn't exist four years ago [2].
|
||||
|
||||
### The Traditional Search Decline
|
||||
|
||||
The shift to AI is cannibalizing traditional search at an accelerating rate.
|
||||
|
||||
- **Gartner forecasts a 25% decline in search engine query volume by 2026** due to AI adoption [3].
|
||||
- **40.16% of local business queries now trigger Google's AI Overviews** [4].
|
||||
- **Google AI Overviews reduce clicks for position-one pages by 58%** [5].
|
||||
- **ChatGPT processes over 2.5 billion daily queries** [2].
|
||||
- **Princeton University researchers found that optimizing for AI systems can increase visibility by up to 40%** [6].
|
||||
|
||||
### Consumer Search Behavior
|
||||
|
||||
Most local business journeys start on mobile and involve multiple channels.
|
||||
|
||||
- **73% of local business searches start on mobile** devices [1].
|
||||
- **75% of consumers use more than one channel** during their local business search—Google remains the most important, but social media (30%), AI tools (23%), and review sites (19%) are all part of the mix [1].
|
||||
- **52% of consumers start their most recent local business search on Google Search**, with a further **9% on Google Maps** [1].
|
||||
- **46% of all Google searches have local intent**, representing approximately **1.5 billion "near me" searches every month** [7].
|
||||
|
||||
|
||||
## 2. The "98.8% Problem": The Visibility Gap
|
||||
|
||||
Despite massive consumer adoption, the overwhelming majority of local businesses are completely invisible to AI recommendation engines.
|
||||
|
||||
### The Gap Between Traditional Search and AI Discovery
|
||||
|
||||
- **ChatGPT recommends just 1.2% of local businesses**—based on SOCi's 2026 Local Visibility Index analyzing over 350,000 business locations [8].
|
||||
- By contrast, **Google's local 3-pack surfaces 35.9%** of those same businesses—a 30x visibility gap [8].
|
||||
- **Gemini recommends 11%** of local business locations; **Perplexity recommends 7.4%** [8].
|
||||
- **88% of multi-location businesses remain misrepresented or absent from AI recommendations** entirely [8].
|
||||
|
||||
### Google Ranking Does NOT Equal AI Visibility
|
||||
|
||||
- **Only 45% of retail brands** performing well in traditional local search also appear in AI recommendations—strong performance in Google does not guarantee AI visibility [8].
|
||||
- **LLMs cite webpages ranking at position 21+ in traditional search nearly 90% of the time**—the platforms consumers now use consult a fundamentally different list than traditional SEO was designed to influence [9].
|
||||
- **68% of business contact information on ChatGPT and Perplexity does NOT match Google Business Profile details**—meaning 32% of businesses are being actively misrepresented [8].
|
||||
- **SEMrush research shows that ChatGPT citations come from sources ranking outside the top 20 in traditional search** [10].
|
||||
|
||||
|
||||
## 3. The Trust & Data Gap
|
||||
|
||||
AI systems rely on structured, verified data to make recommendations.
|
||||
|
||||
### The Verification Problem
|
||||
|
||||
- **Only 18% of consumers who use AI for local searches feel ready to contact the business recommended** by the AI tool. The remainder continue to research using Google and other channels to verify details [1].
|
||||
- **Of consumers who start their search on an AI tool, just 2% use it as their only channel**. **43% go on to check Google**, and **39% look at social media** before making a decision [1].
|
||||
- **95% of consumers will not book a business directly from an AI recommendation** without performing at least one manual verification step [11].
|
||||
- **LLM visitor conversion rates run 9 times higher than traditional organic visitors**—AI traffic is high-intent, but only after trust is established [12].
|
||||
|
||||
### What Gets Businesses Into the 1.2%
|
||||
|
||||
SOCi's research identified factors that consistently differentiate businesses appearing in AI recommendations [8]:
|
||||
|
||||
1. **4.3-star average rating or higher**—businesses below 4.0 stars are effectively excluded from AI consideration.
|
||||
2. **Consistent, high-quality visibility across multiple ecosystems** (Google Maps, Yelp, Facebook, brand websites) rather than strength in a single channel.
|
||||
3. **Consumer sentiment as a gating factor**—AI platforms heavily rely on reviews to assess trust and relevance.
|
||||
4. **Accurate, consistent business information** across all platforms.
|
||||
|
||||
|
||||
## 4. Market Risks & Vulnerabilities
|
||||
|
||||
### Why Incumbents Are Vulnerable
|
||||
|
||||
- **Yelp is dependent on Google for distribution**, having filed extensive regulatory complaints documenting Google's self-preferencing behavior that suppresses Yelp's visibility [13].
|
||||
- **Consumers don't trust AI alone**—95% verify before transacting, meaning AI visibility alone doesn't guarantee conversion [11].
|
||||
- **The platforms that dominate local AI discovery are fragmented**—ChatGPT uses Foursquare/Reprompt, Gemini uses Google Maps, and others use a mix of sources. This fragmentation creates a gap for a unified, direct business-to-AI connection [14].
|
||||
- **The MCP standard is creating a new channel** that bypasses the need for data licensing and scraping—businesses can expose their own structured data directly to AI agents [15].
|
||||
|
||||
### The Cost of Invisibility
|
||||
|
||||
- The cost of invisibility in AI-driven discovery is absolute—there is no fallback list and no second page. If a brand isn't selected by an AI assistant, it is effectively invisible at the moment a consumer is ready to decide [8].
|
||||
- **AI has collapsed the local decision journey**—consumers aren't scrolling through options anymore; they're asking AI to decide for them [1].
|
||||
- **Forrester found that 95% of B2B buyers plan to use generative AI in future purchase decisions**, yet most companies remain unprepared for this shift [16].
|
||||
|
||||
|
||||
## 5. Key Metrics Summary
|
||||
|
||||
| Metric | Value | Source |
|
||||
| :--- | :--- | :--- |
|
||||
| Consumers using AI for local recs | 45% (up from 6% YoY) | [1] |
|
||||
| Local businesses recommended by ChatGPT | 1.2% | [8] |
|
||||
| Local businesses in Google 3-pack | 35.9% | [8] |
|
||||
| Local queries triggering Google AI Overviews | 40.16% | [4] |
|
||||
| Data accuracy gap (ChatGPT vs. Google) | 68% match | [8] |
|
||||
| Gartner forecast search volume drop | 25% by end of 2026 | [3] |
|
||||
| ChatGPT weekly active users | 900 million | [2] |
|
||||
| Mobile local search starts | 73% | [1] |
|
||||
| Consumers who verify AI recs before booking | 95% | [11] |
|
||||
| Organic CTR drop with AI Overview | −58% | [5] |
|
||||
|
||||
|
||||
## 6. Citation Table
|
||||
|
||||
| ID | Source |
|
||||
| :--- | :--- |
|
||||
| [1] | BrightLocal, "The Rise of AI in Local Search," 2026 |
|
||||
| [2] | OpenAI, "ChatGPT Weekly Active Users," February 2026 |
|
||||
| [3] | Gartner, "Forecast: Search Engine Query Volume," 2025 |
|
||||
| [4] | Local Falcon / Conductor, "Local Search AI Overviews Data," 2026 |
|
||||
| [5] | Ahrefs, "Impact of AI Overviews on Organic CTR," 2026 |
|
||||
| [6] | Princeton University, "Optimizing for Generative AI Systems," 2025 |
|
||||
| [7] | Statista / Google, "Local Search Statistics," 2025 |
|
||||
| [8] | SOCi, "2026 Local Visibility Index," 2026 |
|
||||
| [9] | BrightLocal / SOCi, "LLM Citation Source Analysis," 2026 |
|
||||
| [10] | SEMrush, "ChatGPT Citation Source Ranking Analysis," 2025 |
|
||||
| [11] | BrightLocal / Ahrefs, "Consumer Trust in AI Recommendations," 2026 |
|
||||
| [12] | HubSpot, "LLM vs. Organic Conversion Rates," 2025 |
|
||||
| [13] | Yelp, "ACCC Google Complaint Filing," 2024–2025 |
|
||||
| [14] | SparkToro / GMBapi, "ChatGPT Local Data Source Analysis," 2025 |
|
||||
| [15] | Anthropic, "Model Context Protocol Documentation," 2024–2026 |
|
||||
| [16] | Forrester, "Generative AI in B2B Buying," 2025 |
|
||||
@@ -0,0 +1,11 @@
|
||||
# Legal
|
||||
|
||||
Lightweight legal and compliance notes for pilots and product.
|
||||
|
||||
| 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 |
|
||||
|
||||
Not a substitute for counsel. Strategy §13 calls for tourism pilot terms, business ToS, and basic telemetry privacy next.
|
||||
@@ -0,0 +1,172 @@
|
||||
# Data Flow & Privacy — geolocal.io
|
||||
|
||||
> Last updated: 2026-07-16
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This document describes how data flows through the `geolocal.io` platform, what data we collect, how it's stored, who has access, and how we handle privacy obligations under GDPR and CCPA.
|
||||
|
||||
**Core principle:** We expose only public business data. We do not collect personal consumer data beyond what is necessary for booking transactions (handled by Cal.com and Stripe).
|
||||
|
||||
---
|
||||
|
||||
## 2. Data Collection Points
|
||||
|
||||
### 2.1 Business Data (Voluntary)
|
||||
|
||||
Businesses (or their agencies) voluntarily provide:
|
||||
|
||||
| Data | Source | Purpose |
|
||||
|------|--------|---------|
|
||||
| Business name, address, phone, website | Business owner / agency | AI discovery |
|
||||
| Operating hours | Business owner / agency | AI recommendations |
|
||||
| Services & pricing | Business owner / agency | AI recommendations |
|
||||
| Story & narrative | Business owner / agency | Differentiation in AI responses |
|
||||
| Photos & video | Business owner / agency | Visual discovery in AI |
|
||||
| Cal.com booking link | Business owner / agency | Transaction loop |
|
||||
|
||||
**Note:** This data is already publicly available on the business's website or Google Business Profile. We do not scrape it without consent.
|
||||
|
||||
### 2.2 Telemetry Data (MCP Interactions)
|
||||
|
||||
Every MCP tool call generates:
|
||||
|
||||
| Data Point | Example |
|
||||
|-----------|---------|
|
||||
| Query terms | "best mechanic in Frisco TX" |
|
||||
| Business slug referenced | "frisco-german-auto" |
|
||||
| Tool called | "get_business_info" |
|
||||
| AI platform used | ChatGPT, Gemini, Claude |
|
||||
| Timestamp | 2026-07-16T14:23:00Z |
|
||||
| Response time | 45ms |
|
||||
|
||||
### 2.3 Booking Data (via Cal.com / Stripe)
|
||||
|
||||
**We do NOT handle this directly.** Cal.com and Stripe are the providers of record. We pass booking requests to their APIs.
|
||||
|
||||
- Cal.com handles: appointment scheduling, calendar data, customer contact info
|
||||
- Stripe handles: payment processing, billing data, financial records
|
||||
|
||||
---
|
||||
|
||||
## 3. Data Storage
|
||||
|
||||
| Data Type | Where It Lives | Retention |
|
||||
|-----------|---------------|-----------|
|
||||
| Business profiles | PostgreSQL (Railway) | Until business opts out |
|
||||
| Telemetry logs | PostgreSQL + Redis (cached) | 24 months, then anonymized |
|
||||
| Photos / media | CDN (Cloudflare R2 / AWS S3) | Until business opts out |
|
||||
| Booking data | Cal.com / Stripe (external) | Per their retention policies |
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Sharing
|
||||
|
||||
| Recipient | What We Share | Why |
|
||||
|-----------|--------------|-----|
|
||||
| AI agents (ChatGPT, Gemini, etc.) | Business profile data via MCP | Core product function |
|
||||
| Partner agencies | Their client's analytics & commission data | Partner economics |
|
||||
| Chambers of Commerce | Member analytics (aggregate) | CoC dashboard |
|
||||
| Third-party data buyers (DaaS) | Anonymized telemetry only | Data-as-a-Service revenue |
|
||||
|
||||
**We never sell identifiable consumer data.** All DaaS products use aggregated, anonymized telemetry.
|
||||
|
||||
---
|
||||
|
||||
## 5. Bi-Directional MCP Data Flow
|
||||
|
||||
The "related businesses" handshake creates a bi-directional data exchange:
|
||||
|
||||
```
|
||||
AI Agent ──┐
|
||||
├──→ geolocal.io MCP Server ──→ Business Database
|
||||
│ ↓
|
||||
│ related_businesses()
|
||||
│ ↓
|
||||
│ Returns: list of related businesses
|
||||
│ ↓
|
||||
AI Agent ◄─┘───────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Verification flow:** AI agents can report data discrepancies back through the MCP protocol. We log these reports and flag business profiles for review.
|
||||
|
||||
---
|
||||
|
||||
## 6. Privacy Commitments
|
||||
|
||||
### 6.1 GDPR Principles
|
||||
- **Lawful basis:** Processing is based on business consent (they opt in) and legitimate interest (telemetry for service improvement)
|
||||
- **Data minimization:** We only collect what's needed for AI discovery and booking
|
||||
- **Right to be forgotten:** Businesses can request full data deletion
|
||||
- **Data portability:** Businesses can export their profile data at any time
|
||||
- **DPIA:** Data Protection Impact Assessment will be completed before EU data processing
|
||||
|
||||
### 6.2 CCPA Principles
|
||||
- **Notice at collection:** Clear disclosure of what data we collect
|
||||
- **Right to delete:** Businesses can request deletion of their data
|
||||
- **Right to opt out of sale:** We do not sell personal data
|
||||
- **Non-discrimination:** We do not discriminate against users who exercise their rights
|
||||
|
||||
### 6.3 What We Do NOT Do
|
||||
- We do not collect consumer PII beyond what Cal.com/Stripe handle
|
||||
- We do not track individual consumers across sessions
|
||||
- We do not use cookies for behavioral tracking
|
||||
- We do not sell individual-level data
|
||||
|
||||
---
|
||||
|
||||
## 7. Security
|
||||
|
||||
| Measure | Status |
|
||||
|---------|--------|
|
||||
| PostgreSQL connection via SSL | ✅ MVP |
|
||||
| Rate limiting on MCP endpoints | ✅ MVP |
|
||||
| Input validation (Zod schemas) | ✅ MVP |
|
||||
| OAuth 2.1 with PKCE for partner auth | Phase 2 |
|
||||
| Regular security audits | Phase 3 |
|
||||
| SOC 2 compliance | Future |
|
||||
|
||||
---
|
||||
|
||||
## 8. Incident Response
|
||||
|
||||
In the event of a data breach:
|
||||
|
||||
1. **Detect:** Automated alerts on anomalous MCP traffic patterns
|
||||
2. **Contain:** Rate-limit or disable affected endpoints
|
||||
3. **Notify:** Affected businesses notified within 72 hours (GDPR)
|
||||
4. **Remediate:** Patch vulnerability, audit for scope
|
||||
5. **Document:** Log incident, update this document
|
||||
|
||||
---
|
||||
|
||||
## 9. Data Flow Diagram
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
|
||||
│ Business │ │ │ │ AI Agents │
|
||||
│ Owner / │────→│ geolocal.io │←───→│ ChatGPT, │
|
||||
│ Agency │ │ MCP Server │ │ Gemini, │
|
||||
└──────────────┘ │ │ │ Claude, │
|
||||
│ ┌────────────┐ │ │ Grok │
|
||||
│ │ PostgreSQL │ │ └──────────────┘
|
||||
│ └────────────┘ │
|
||||
│ ┌────────────┐ │
|
||||
│ │ Redis │ │
|
||||
│ └────────────┘ │
|
||||
│ ┌────────────┐ │
|
||||
│ │ Telemetry │ │
|
||||
│ └────────────┘ │
|
||||
└──────┬───────────┘
|
||||
│
|
||||
┌───────┴────────┐
|
||||
│ Cal.com API │
|
||||
│ Stripe API │
|
||||
└────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*This document must reference NORTH_STAR.md for principles. Updates require review against current privacy regulations.*
|
||||
@@ -0,0 +1,122 @@
|
||||
# IP Notes — geolocal.io
|
||||
|
||||
> Last updated: 2026-07-16
|
||||
|
||||
---
|
||||
|
||||
## 1. The `/.well-known/mcp-server` Pattern
|
||||
|
||||
### Positioning
|
||||
|
||||
The `/.well-known/mcp-server` convention is an adaptation of IETF's RFC 8615 (`/.well-known` URI space) for MCP server discovery. We position this as an **open standard** — not a proprietary geolocal.io invention.
|
||||
|
||||
**Rationale:**
|
||||
- The more adopters use this convention, the more AI agents learn to look for it
|
||||
- An open standard creates network effects that favor us as the infrastructure provider, even though we don't own the convention
|
||||
- Competitors who copy the convention still need our hosted MCP server
|
||||
|
||||
### Risk
|
||||
|
||||
If another company claims to have "invented" `/.well-known/mcp-server`, we lose the narrative advantage. **Mitigation:** Document our first use and publish the convention publicly before competitors.
|
||||
|
||||
### Action Items
|
||||
|
||||
- [ ] Publish a technical blog post: "Introducing `/.well-known/mcp-server` for AI Discovery"
|
||||
- [ ] File a design document on the MCP GitHub repository as a community proposal
|
||||
- [ ] Include the convention in our public README before launch
|
||||
|
||||
---
|
||||
|
||||
## 2. Trademark
|
||||
|
||||
**Mark:** geolocal.io
|
||||
|
||||
**Status:** To be registered
|
||||
|
||||
**Action Items:**
|
||||
- [ ] File USPTO trademark application for "GeoLocal" (Class 42: Cloud computing services; Class 35: Business consulting)
|
||||
- [ ] Monitor for conflicting marks in adjacent categories
|
||||
- [ ] Register domain variations (geolocal.com, geolocal.ai) to prevent confusion
|
||||
|
||||
---
|
||||
|
||||
## 3. MCP Protocol Usage
|
||||
|
||||
**Governance:** The MCP protocol is governed by Anthropic (as of 2026). It is open-source and permissively licensed.
|
||||
|
||||
**Our usage:**
|
||||
- We implement the MCP protocol as specified — this is permitted
|
||||
- We do not modify the core protocol — we extend it with our own tools and data schema
|
||||
- Our proprietary value is in the **data layer** and **hosting infrastructure**, not the protocol itself
|
||||
|
||||
**Risk:** If MCP governance changes (e.g., becomes copyleft, or a competing protocol emerges), we need to be ready to migrate. Our data layer is protocol-agnostic, so this is manageable.
|
||||
|
||||
---
|
||||
|
||||
## 4. Telemetry Data Ownership
|
||||
|
||||
**We own the telemetry data** generated by MCP interactions on our platform:
|
||||
|
||||
- Query patterns
|
||||
- Tool usage statistics
|
||||
- Response times
|
||||
- Business recommendation patterns
|
||||
- AI platform usage breakdown
|
||||
|
||||
**We do NOT own:**
|
||||
- Business profile data (owned by the businesses)
|
||||
- Booking data (owned by Cal.com/Stripe)
|
||||
- Consumer PII (we don't collect it)
|
||||
|
||||
**Commercialization:** Anonymized, aggregated telemetry may be licensed as a Data-as-a-Service product. This is subject to our privacy commitments (see Data Flow & Privacy.md).
|
||||
|
||||
---
|
||||
|
||||
## 5. Open Source Considerations
|
||||
|
||||
**Current code:** Proprietary (closed-source)
|
||||
|
||||
**Rationale for closed-source:**
|
||||
- The competitive advantage is in the data and distribution, not the code
|
||||
- However, closing the source may slow adoption if agencies want to audit the infrastructure
|
||||
- **Potential strategy:** Release a reference implementation (the JSON manifest generator) as open source, while keeping the MCP server and telemetry pipeline proprietary
|
||||
|
||||
**Recommendation:** Evaluate open-sourcing the manifest generator / `/.well-known/mcp-server` convention documentation as a growth strategy. This positions geolocal.io as the authority without giving away proprietary infrastructure.
|
||||
|
||||
---
|
||||
|
||||
## 6. Business Data Rights
|
||||
|
||||
**Clear chain of title:**
|
||||
|
||||
```
|
||||
Business Owner → (voluntarily provides) → geolocal.io MCP Server → (exposed via) → AI Agents
|
||||
```
|
||||
|
||||
- Businesses retain full ownership of their profile data
|
||||
- Businesses grant geolocal.io a non-exclusive license to host and expose that data via MCP
|
||||
- Businesses may revoke this license at any time (data deletion request)
|
||||
- Businesses may export their data at any time
|
||||
|
||||
**Partner agencies:**
|
||||
- Agencies act as data processors on behalf of businesses
|
||||
- Agencies do not own the business data they submit
|
||||
- Businesses must authorize agencies to submit their data on their behalf
|
||||
|
||||
---
|
||||
|
||||
## 7. IP Audit Checklist
|
||||
|
||||
Before launch, verify:
|
||||
|
||||
- [ ] No third-party code with restrictive licenses (GPL, AGPL) in the MCP server
|
||||
- [ ] All dependencies use permissive licenses (MIT, Apache 2.0, BSD)
|
||||
- [ ] Trademark application filed
|
||||
- [ ] `/.well-known/mcp-server` convention documented and published
|
||||
- [ ] Privacy policy references data ownership clearly
|
||||
- [ ] Terms of Service include IP clauses
|
||||
- [ ] No open source code mixed with proprietary code without clear separation
|
||||
|
||||
---
|
||||
|
||||
*This document must reference NORTH_STAR.md for principles. Consult IP counsel before making final decisions.*
|
||||
@@ -0,0 +1,125 @@
|
||||
# Partnership Agreement Skeleton — geolocal.io
|
||||
|
||||
> **Template — NOT LEGAL ADVICE.** Consult qualified counsel before execution.
|
||||
> Last updated: 2026-07-16
|
||||
|
||||
---
|
||||
|
||||
## Parties
|
||||
|
||||
**Provider:** geolocal.io (the "Platform")
|
||||
|
||||
**Partner:** [Partner Name / Agency / Chamber of Commerce] (the "Partner")
|
||||
|
||||
**Effective Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Scope of Partnership
|
||||
|
||||
Partner is authorized to:
|
||||
|
||||
1. Offer `geolocal.io` MCP endpoints to their clients/members
|
||||
2. Use `geolocal.io` branding and marketing materials (subject to brand guidelines)
|
||||
3. Access the Partner Dashboard for client management and analytics
|
||||
4. Earn recurring commissions as specified in Section 4
|
||||
|
||||
Partner is NOT authorized to:
|
||||
|
||||
1. Resell `geolocal.io` as a white-label product without Strategic-tier status
|
||||
2. Modify or redistribute `geolocal.io` software code
|
||||
3. Claim ownership of `geolocal.io` data or telemetry
|
||||
|
||||
---
|
||||
|
||||
## 2. Data Ownership
|
||||
|
||||
- **Businesses own their data.** All business profile data (name, services, photos, story, booking info) remains the intellectual property of the business that provided it.
|
||||
- **geolocal.io owns the platform.** The MCP server infrastructure, telemetry data (anonymized), and platform code are owned by geolocal.io.
|
||||
- **Partner owns their client relationships.** Partner retains all rights to their client relationships and may migrate clients off the platform at any time.
|
||||
- **Data export.** Upon request, businesses may export their full profile data in JSON format.
|
||||
|
||||
---
|
||||
|
||||
## 3. Term & Termination
|
||||
|
||||
- **Term:** This agreement is effective until terminated by either party.
|
||||
- **Termination for convenience:** Either party may terminate with 30 days written notice.
|
||||
- **Termination for cause:** Either party may terminate immediately for material breach, fraud, or illegal activity.
|
||||
- **Effect of termination:**
|
||||
- Partner commissions cease on the termination date
|
||||
- Business client data remains on the platform until businesses migrate off (grace period: 90 days)
|
||||
- Partner loses access to Partner Dashboard on termination date
|
||||
- geolocal.io retains anonymized telemetry data
|
||||
|
||||
---
|
||||
|
||||
## 4. Commission Structure
|
||||
|
||||
| Tier | Requirements | Commission Rate |
|
||||
|------|-------------|-----------------|
|
||||
| **Affiliate** | Signed partner agreement | 20% of MRR |
|
||||
| **Partner** | 10+ active clients | 25% of MRR |
|
||||
| **Strategic** | 50+ active clients | 30% of MRR |
|
||||
|
||||
- Commissions are calculated on net revenue (after payment processing fees)
|
||||
- Commissions paid monthly, payable on the 15th of each month
|
||||
- Partner may access commission reports via Partner Dashboard
|
||||
|
||||
---
|
||||
|
||||
## 5. Confidentiality
|
||||
|
||||
Both parties agree to keep confidential:
|
||||
|
||||
- Business client data and analytics
|
||||
- Telemetry data and insights
|
||||
- Commission rates and partnership terms
|
||||
- Platform technical architecture and API endpoints
|
||||
|
||||
Confidentiality obligations survive termination for 24 months.
|
||||
|
||||
---
|
||||
|
||||
## 6. Liability
|
||||
|
||||
- **Limitation of liability:** Neither party is liable for indirect, consequential, or punitive damages arising from this agreement.
|
||||
- **Maximum liability:** Provider's total liability is capped at the Partner's commissions earned in the preceding 12 months.
|
||||
- **No warranty:** The platform is provided "as is" without warranty of merchantability or fitness for a particular purpose.
|
||||
- **Partner indemnification:** Partner agrees to indemnify geolocal.io against claims arising from Partner's misuse of the platform or misrepresentation to clients.
|
||||
|
||||
---
|
||||
|
||||
## 7. Compliance
|
||||
|
||||
Both parties agree to:
|
||||
|
||||
- Comply with applicable data protection laws (GDPR, CCPA)
|
||||
- Not use the platform for fraudulent or deceptive purposes
|
||||
- Report data breaches within 24 hours of discovery
|
||||
- Maintain accurate business data for enrolled clients
|
||||
|
||||
---
|
||||
|
||||
## 8. Dispute Resolution
|
||||
|
||||
- **Governing law:** [State/Jurisdiction]
|
||||
- **Good faith negotiation:** 30-day period before formal action
|
||||
- **Arbitration:** Binding arbitration if negotiation fails
|
||||
- **Venue:** [City, State]
|
||||
|
||||
---
|
||||
|
||||
## 9. Amendment
|
||||
|
||||
This agreement may be amended by mutual written consent of both parties. geolocal.io may update platform terms (pricing, features) with 30 days written notice.
|
||||
|
||||
---
|
||||
|
||||
**Provider:** ___________________ **Date:** ___________
|
||||
|
||||
**Partner:** ___________________ **Date:** ___________
|
||||
|
||||
---
|
||||
|
||||
*This template must reference NORTH_STAR.md for principles. Consult legal counsel before use.*
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
@@ -0,0 +1,31 @@
|
||||
# Product
|
||||
|
||||
Product definitions for what we build and sell. Align with [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md).
|
||||
|
||||
## Read in this order
|
||||
|
||||
1. [overview.md](./overview.md) — platform map and surfaces
|
||||
2. [use-cases/](./use-cases/) — canonical specs (start with UC-01 and UC-02)
|
||||
3. [genre-packs.md](./genre-packs.md) — vertical primitives
|
||||
4. [ssp.md](./ssp.md) — Self-Service Portal as **activation**, not the whole product
|
||||
5. [intermediate.md](./intermediate.md) — tourism/chamber intermediate surface
|
||||
|
||||
## Center of gravity
|
||||
|
||||
| Layer | What it is |
|
||||
|-------|------------|
|
||||
| **Platform** | Multi-tenant MCP, discovery attachment, ingestion, genre packs, telemetry, quality |
|
||||
| **Activation** | Self-Service Portal and partner-assisted onboarding |
|
||||
| **Distribution** | Tourism boards, chambers, agencies |
|
||||
| **Later** | Trust layer effects and service graph products |
|
||||
|
||||
If a doc makes the portal sound like the company, it is wrong. Fix the doc.
|
||||
|
||||
## Status
|
||||
|
||||
| Area | Status |
|
||||
|------|--------|
|
||||
| Strategy alignment | Canonical strategy is source of truth |
|
||||
| Use cases UC-01 / UC-02 | Spec |
|
||||
| Portal / intermediate apps | Not built |
|
||||
| MCP MVP code | In `code/` (stdio MVP; HTTP is Priority 0) |
|
||||
+15
-24
@@ -1,32 +1,23 @@
|
||||
# Genre packs
|
||||
|
||||
**Structural direction (working):** three layers when surfacing work to owners — not one giant schema dump.
|
||||
Generic business fields are scaffolding. Durable differentiation is **genre-specific primitives**.
|
||||
|
||||
| Layer | What | Owner hears |
|
||||
| :--- | :--- | :--- |
|
||||
| **A — Universal** | Discovery foundation: NAP + Core 3 claimed + hours + website + description + service-area mode + no duplicates/contradictions | Everyone’s first punch list |
|
||||
| **B — Genre pack** | Thin ranked list for that vertical (secondaries, high-value attributes, services/menu shape, booking/links, maybe one vertical directory) | “For salons like yours, next is X” — never “schema” |
|
||||
| **C — Known-for** | From the owner’s own words | Extra attributes/photos/proof + later AI-readiness queries |
|
||||
## Planned packs
|
||||
|
||||
**Surface rule:** scorecard ladder first (exist → know what you do → would recommend), then **3–7 actions max**, sorted by impact. Genre pack ranks the backlog.
|
||||
|
||||
**Core 3 coverage rule:** **GBP** is richest; Apple Business Connect mid; Bing Places thinnest. Pack actions: set on GBP; mirror on Apple/Bing where the field exists.
|
||||
|
||||
**Not the same as “beyond NAP”:** A/B/C = *what work we show the owner*. Beyond-NAP (in `docs/BUSINESS_PLAN.md`) = *provider capability ladder* (basics → extras → stacks).
|
||||
|
||||
## Sourced Core 3 map + deep examples
|
||||
|
||||
- [Core 3 sourced field map](./genre-packs/core3-field-map.md) — **SoT for fields** (no guessing)
|
||||
- [Core 3 source URLs](./genre-packs/SOURCES.md) — GBP / Apple / Bing links to reopen
|
||||
- [Salon](./genre-packs/salon.md) — genre application notes (illustrative only)
|
||||
- [Bakery](./genre-packs/bakery.md) — same
|
||||
|
||||
## Later packs (not started on this branch)
|
||||
|
||||
Auto repair, beauty (reconcile with salon), home services, tourism activity, local retail — add only when we go deep; no placeholder shells.
|
||||
- Auto repair (see [UC-01](./use-cases/uc-01-endpoint-auto-repair.md))
|
||||
- Beauty
|
||||
- Home services
|
||||
- Tourism activity ([UC-02](./use-cases/uc-02-intermediate-tourism-board.md) context)
|
||||
- **Local retail / general store** (see [UC-03](./use-cases/uc-03-local-retail-general-store.md)) — assortment signals, house specialties, hours, visit path
|
||||
|
||||
## Why this matters
|
||||
|
||||
Assistants evaluate helpfulness by whether the business answers the *right* questions for its category. Salon booking ≠ bakery known-for products.
|
||||
Assistants evaluate helpfulness by whether the business answers the *right* questions for its category. “Do you work on Korean transmissions?” is not the same shape as “Do you have a toothbrush?” or “Are the chicken strips still a thing?”
|
||||
|
||||
Plan pointer: [`docs/BUSINESS_PLAN.md`](../BUSINESS_PLAN.md).
|
||||
## Sequencing
|
||||
|
||||
Services packs may ship first for pilot speed. Retail is **in scope**, not a strategy exception.
|
||||
|
||||
## Detail source
|
||||
|
||||
[Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) §1a and genre primitives.
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
# Core 3 — source URLs (save & reuse)
|
||||
|
||||
Canonical links for Discovery foundation / field-map work. **Do not invent fields from memory — open these.**
|
||||
If a link is dead or gated, mark **BLOCKED** in chat and in `core3-field-map.md`.
|
||||
|
||||
Last updated: 2026-09-15 (SEO & AEO Desk)
|
||||
|
||||
---
|
||||
|
||||
## GBP (Google Business Profile)
|
||||
|
||||
| What | URL |
|
||||
| :--- | :--- |
|
||||
| Business Information API (REST index) | https://developers.google.com/my-business/reference/businessinformation/rest |
|
||||
| Location resource (field names: `title`, `storefrontAddress`, `phoneNumbers`, `websiteUri`, `regularHours`, `specialHours`, `serviceArea`, `profile`, `serviceItems`, …) | https://developers.google.com/my-business/reference/businessinformation/rest/v1/locations |
|
||||
| Work with location data (howto) | https://developers.google.com/my-business/content/location-data |
|
||||
| Manage attributes (howto) | https://developers.google.com/my-business/content/attributes |
|
||||
| `attributes.list` method | https://developers.google.com/my-business/reference/businessinformation/rest/v1/attributes/list |
|
||||
| Place Actions API (related — booking/order links) | https://developers.google.com/my-business/content/basic-setup (enable Place Actions among GBP APIs) |
|
||||
|
||||
---
|
||||
|
||||
## Apple Business Connect
|
||||
|
||||
| What | URL |
|
||||
| :--- | :--- |
|
||||
| Apple Business user guide (index / crawl root) | https://support.apple.com/guide/business/welcome/web |
|
||||
| Configure location attributes (owner-facing field labels) | https://support.apple.com/guide/business/configure-location-attributes-abcbdc543423/web |
|
||||
| Brand identity attributes (brand-level — not Location schema) | https://support.apple.com/guide/business/brand-identity-attributes-abcbb1973199/web |
|
||||
|
||||
|
||||
| Insights for a single location (KPI telemetry — searches, place card views, Actions, etc.) | https://support.apple.com/guide/business/use-insights-for-a-single-location-abcbb749656b/web |
|
||||
|
||||
**Punted (2026-09-15):** Apple partner API schema (`https://business.apple.com/docs/api/v1/introduction` and data-spec camelCase Location fields) — rabbit hole at this altitude; revisit when we have signed-in/partner access. Do not invent API names meanwhile.
|
||||
|
||||
**BLOCKED:** Apple Business Connect Location API data specification (camelCase resource fields), e.g. `https://businessconnect.apple.com/docs/data-specification/v1.3/…` — often partner-gated; do not invent names. Unlock: accessible dump or paste of Location resource.
|
||||
|
||||
---
|
||||
|
||||
## Bing Places
|
||||
|
||||
| What | URL |
|
||||
| :--- | :--- |
|
||||
| Bing Places for Business API docs (PDF, “Latest”) | https://cdn.bingplaces.com/tpshared/BingPlaces_API_Latest.pdf |
|
||||
| Bing Places for Business API docs (PDF, v1.0 mirror) | https://bpprodpublicstorage.blob.core.windows.net/bingplacesapi/BingPlaces_API_v1.0.pdf |
|
||||
|
||||
**Note:** Bing Places partner API is **trusted-partner / certificate** access, not a public directory crawl API. Field names in our map come from that PDF family; if PDF moves, re-verify before editing the field map.
|
||||
|
||||
---
|
||||
|
||||
## How we use this
|
||||
|
||||
1. Field map SoT: [`core3-field-map.md`](./core3-field-map.md)
|
||||
2. Genre application: [`salon.md`](./salon.md), [`bakery.md`](./bakery.md)
|
||||
3. New platform docs → add URL here first, then update the field map from the page (never from memory).
|
||||
@@ -1,41 +0,0 @@
|
||||
# Genre pack — Bakery (deep example)
|
||||
|
||||
**Status:** working shell — **not locked**
|
||||
**Vertical:** local retail / food
|
||||
|
||||
**Schema SoT:** [core3-field-map.md](./core3-field-map.md) (sourced). This file is **genre application notes + illustrative examples only** — not a guessed schema.
|
||||
|
||||
**Assumes Layer A** from the sourced Core 3 map is ranked or clean first.
|
||||
|
||||
---
|
||||
|
||||
## How bakery uses the sourced Core 3 map
|
||||
|
||||
| Sourced child | Bakery note | Core 3 parity |
|
||||
| :--- | :--- | :--- |
|
||||
| Name / Address / Phone / Website | Must match (illustrative: Whidbey Muffin Co.) | Full |
|
||||
| Primary + additional categories | Bakery; Coffee shop / Cafe **only if true** | Full |
|
||||
| Regular / special hours | Early open + weekend accuracy; holiday closed | Full |
|
||||
| Description / profile | Primary home for known-for (“sourdough & muffins”) — **not** a fake checkbox | GBP `profile`; Bing `Description`; Apple **About** |
|
||||
| Service area | Storefront vs delivery-only must match reality | GBP `serviceArea`; Bing `ServiceAreas` / `HideAddress`; Apple SAB confirm in UI |
|
||||
| Services list | Usually **not** the salon-shaped `serviceItems` story — prefer description + menu/order links + photos | Don’t invent Apple/Bing service arrays |
|
||||
| Links / Actions | Menu / order URLs when they sell online | GBP actions/attrs if listed; Apple Actions; Bing `MenuURL` / `OrderURL` / related *(category-dependent)* |
|
||||
| Attributes | dine-in / takeout / wifi / outdoor / etc. — **only after live attribute lists** | GBP `attributes.list`; Apple Good to Know; Bing `Attributes[]` |
|
||||
| Photos | Product proof for known-for | GBP / Apple / Bing photos |
|
||||
|
||||
---
|
||||
|
||||
## Illustrative ranked punch list (3–7)
|
||||
|
||||
1. Align NAP + website on Core 3
|
||||
2. Set Bakery (+ Cafe only if true)
|
||||
3. Lock weekly + special hours
|
||||
4. Known-for sentence in description everywhere it exists
|
||||
5. Menu/order URL via Actions / URL fields + website
|
||||
6. Product photos on GBP/Apple
|
||||
|
||||
---
|
||||
|
||||
## Blocked until evidence pull
|
||||
|
||||
Amenity/attribute checkbox rows (takeout, outdoor seating, …) until GBP `attributes.list` for bakery `gcid` (US) + Apple Good to Know enums.
|
||||
@@ -1,36 +0,0 @@
|
||||
# Core 3 — sourced field map (Discovery foundation)
|
||||
|
||||
**Status:** working — **sourced**, not guessed
|
||||
**Rule:** never invent platform fields. Attributes for a genre = only after live `attributes.list` (GBP) / Good to Know enums (Apple) for that category + country.
|
||||
**Process:** if blocked, say **BLOCKED** (what’s missing / why / unlock) — no paint-overs.
|
||||
|
||||
**Sources:** see [`SOURCES.md`](./SOURCES.md) (GBP / Apple / Bing URLs). Snapshot:
|
||||
- GBP: [Location resource](https://developers.google.com/my-business/reference/businessinformation/rest/v1/locations), [`attributes.list`](https://developers.google.com/my-business/reference/businessinformation/rest/v1/attributes/list)
|
||||
- Apple: [Welcome](https://support.apple.com/guide/business/welcome/web) → [Configure location attributes](https://support.apple.com/guide/business/configure-location-attributes-abcbdc543423/web)
|
||||
- Bing: [Places API PDF (Latest)](https://cdn.bingplaces.com/tpshared/BingPlaces_API_Latest.pdf)
|
||||
|
||||
**Apple naming:** owner-facing **UI labels** from Configure location attributes (below). **Punted** at this altitude: separate camelCase Location/partner API resource names — we do not invent them. UI labels from Configure location attributes remain the Apple column SoT.
|
||||
|
||||
Example values in genre packs are **illustrative only** — they are not schema claims.
|
||||
|
||||
| Parent | Child (API / UI name) | GBP | Apple Business Connect (UI labels) | Bing Places | Why it matters |
|
||||
| :--- | :--- | :--- | :--- | :--- | :--- |
|
||||
| Identity | Name | `title` | Display name (+ alternate) | `BusinessName` | NAP consistency — assistants + Maps match on this |
|
||||
| Identity | Address | `storefrontAddress` | Address + lat/long | `AddressLine*` / City / State / Zip / Country | Same |
|
||||
| Identity | Phone | `phoneNumbers` | Phone | `PhoneNumber` | Same |
|
||||
| Identity | Website | `websiteUri` | Website | `MainWebSite` | Reachable + verification path |
|
||||
| Category | Primary | `categories` (primary) | Categories — 1 primary | `PrimaryCategory` | Routes discovery queries |
|
||||
| Category | Additional | additional categories | up to 19 optional | `BusinessCategories` (up to 10) | Secondary intent |
|
||||
| Hours | Regular | `regularHours` | Normal hours | `OperatingHours` / `Open24Hours` | “Are you open?” — high AI failure mode |
|
||||
| Hours | Special / holiday | `specialHours` | Special hours—service; Special hours—temporary | `HolidayHours` | Same for peak days |
|
||||
| Description | Profile / description | `profile` | About | `Description` | “What you do” in plain language |
|
||||
| Service area | Mode / areas | `serviceArea` | *(confirm storefront vs SAB in Apple UI — not listed as a single label on that page)* | `ServiceAreas` + `HideAddress` | Stops wrong “visit us” vs mobile |
|
||||
| Services | Service list | `serviceItems` | **not a Location core services array** — use Categories / Good to Know / Actions | **no generic services array** — category-specific | Salon P1 on GBP; don’t claim Apple/Bing parity |
|
||||
| Attributes | Amenities / access | **dynamic** via `attributes.list` | **Good to Know** | `Attributes[]` rich attrs (category-dependent) + hotel-only `Amenities` | Genre-gated; pull live lists — never hardcode full schema |
|
||||
| Links | Appointment / menu / order | Place Actions + attrs like `url_menu` *(if listed)* | **Actions** (+ App link) | `url_appointment`, `MenuURL`, `OrderURL`, `url_order_ahead` *(category-dependent)* | Conversion paths |
|
||||
| Media | Photos | *(Photos API / UI — not Location JSON)* | Photos / cover | `Photos[]` | Proof for known-for |
|
||||
| Status | Open / closed / etc. | *(platform status / openInfo as applicable)* | Status | *(platform-specific)* | Suppress wrong “open now” |
|
||||
| Showcase | Merchandising | *(GBP posts / products — separate surfaces)* | Showcase | *(n/a or limited)* | Optional merchandising — not Layer A P1 |
|
||||
|
||||
**Punted (altitude):** Apple Location / partner API camelCase field list (`business.apple.com` / data-spec). Revisit with signed-in access — do not invent names. Owner-facing UI labels above remain SoT for Apple column.
|
||||
**Still BLOCKED for genre attribute rows:** GBP `attributes.list` per salon/bakery `gcid` (US) + Apple Good to Know enum values.
|
||||
@@ -1,40 +0,0 @@
|
||||
# Genre pack — Salon (deep example)
|
||||
|
||||
**Status:** working shell — **not locked**
|
||||
**Vertical:** appointment-based beauty / hair
|
||||
|
||||
**Schema SoT:** [core3-field-map.md](./core3-field-map.md) (sourced). This file is **genre application notes + illustrative examples only** — not a guessed schema.
|
||||
|
||||
**Assumes Layer A** from the sourced Core 3 map is ranked or clean first.
|
||||
|
||||
---
|
||||
|
||||
## How salon uses the sourced Core 3 map
|
||||
|
||||
| Sourced child | Salon note | Core 3 parity |
|
||||
| :--- | :--- | :--- |
|
||||
| Name / Address / Phone / Website | Must match everywhere (illustrative: Maria's Hair Studio) | Full |
|
||||
| Primary + additional categories | e.g. Hair salon + Nail salon / Beauty salon *(illustrative labels — use each platform’s category picker)* | Full |
|
||||
| Regular / special hours | Same | Full |
|
||||
| Description / profile | Carry specialties (“curly specialists”, bridal) here when Apple/Bing lack services | GBP `profile`; Bing `Description`; Apple **About** (Configure location attributes) |
|
||||
| `serviceItems` (GBP) | **Salon P1** — Haircut, Color, Balayage, Blowout *(illustrative)* | **GBP only** — no Apple/Bing services array on Location core |
|
||||
| Links / Actions | Booking URL (Square/Mindbody/etc.) | GBP Place Actions + website; Apple **Actions**; Bing appointment/URL fields if category allows |
|
||||
| Attributes | **Do not hardcode** (women-led, wifi, wheelchair, …) until `attributes.list` for salon `gcid` + US | GBP dynamic; Apple Good to Know; Bing category-dependent |
|
||||
| Photos | Real work photos *(illustrative guidance)* | GBP Photos UI/API; Apple Photos; Bing `Photos[]` |
|
||||
|
||||
---
|
||||
|
||||
## Illustrative ranked punch list (3–7)
|
||||
|
||||
1. Align NAP + website on Core 3
|
||||
2. Set primary category Hair salon (+ real secondaries)
|
||||
3. Add GBP `serviceItems` (top services)
|
||||
4. Add booking Action / URL on GBP + Apple Actions + website
|
||||
5. Put known-for specialties in description
|
||||
6. Photos on GBP/Apple
|
||||
|
||||
---
|
||||
|
||||
## Blocked until evidence pull
|
||||
|
||||
Any amenity/attribute checkbox rows for salon. Next: GBP `attributes.list` for hair salon (US) + Apple Good to Know enums.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Intermediate product (tourism, chambers, visitor bureaus)
|
||||
|
||||
Model 2: destinations and membership organizations as discovery and evaluation nodes.
|
||||
|
||||
## Intent
|
||||
|
||||
Today, assistants often treat these sites as low-signal link lists. We upgrade them into structured intermediate MCPs backed by live member endpoints. One intermediate relationship should bring many members online and create a funding path through lodging-tax or destination-promotion budgets.
|
||||
|
||||
## Spec source of truth
|
||||
|
||||
- Narrative: [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (Model 2 + GTM wedge)
|
||||
- Operating use case: [UC-02](./use-cases/uc-02-intermediate-tourism-board.md)
|
||||
|
||||
## Build status
|
||||
|
||||
Not implemented. Priority 1 after Model 1 endpoint activation works for a real cohort.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Product overview
|
||||
|
||||
geolocal.io is **AI-readiness infrastructure** for **local businesses** with real-world presence — services **and** local retail. Assistants call structured endpoints. Businesses own their presence. Intermediates and partners help distribution. Booking, payment, and inventory systems are orchestrated through specialists where needed; we do not rebuild Shopify for pure online stores.
|
||||
|
||||
## Platform vs activation
|
||||
|
||||
| Layer | Responsibility |
|
||||
|-------|----------------|
|
||||
| **Platform** | Multi-tenant MCP, discovery attachment, ingestion/content sync, genre packs (services + retail), telemetry, quality enforcement, intermediate aggregation |
|
||||
| **Activation** | Self-Service Portal and assisted onboarding |
|
||||
| **Distribution** | Tourism boards, chambers, agencies |
|
||||
|
||||
The portal is how Model 1 scales. It is not the product definition of the company.
|
||||
|
||||
## Surfaces
|
||||
|
||||
| Surface | Audience | Status |
|
||||
|---------|----------|--------|
|
||||
| MCP gateway | AI agents | MVP in `code/` (stdio); HTTP is Priority 0 |
|
||||
| Genre packs | Vertical structure for agents + owners | Services + retail in strategy; auto pack first via UC-01; retail via UC-03 |
|
||||
| Self-Service Portal | SMB owners / delegates | Specified; not built |
|
||||
| Intermediate MCP + board tools | Tourism boards / chambers | UC-02; not built |
|
||||
| Partner flows | Agencies / local web | Distribution; after core attach |
|
||||
|
||||
## Canonical use cases
|
||||
|
||||
- [UC-01 Endpoint — auto repair](./use-cases/uc-01-endpoint-auto-repair.md)
|
||||
- [UC-02 Intermediate — tourism board](./use-cases/uc-02-intermediate-tourism-board.md)
|
||||
- [UC-03 Endpoint — local retail / general store](./use-cases/uc-03-local-retail-general-store.md)
|
||||
|
||||
## Scope reminder
|
||||
|
||||
In: brick-and-mortar and local presence (garage **and** general store).
|
||||
Out: pure online commerce with no local footprint. Detail: [Canonical Strategy §1a](../strategy/CANONICAL_STRATEGY.md).
|
||||
@@ -0,0 +1,18 @@
|
||||
# Self-Service Portal (SSP)
|
||||
|
||||
Activation experience for individual local businesses (Model 1). Important, not the whole company.
|
||||
|
||||
## Intent
|
||||
|
||||
Owners should feel the value before they pay: genre-aware onboarding, site scrape reflection, a live simulation of an external 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 assistants will interpret the business — not a customer-facing chatbot product.
|
||||
|
||||
## Spec source of truth
|
||||
|
||||
- Narrative: [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (product definition + priorities)
|
||||
- Operating use case: [UC-01](./use-cases/uc-01-endpoint-auto-repair.md)
|
||||
|
||||
## Build status
|
||||
|
||||
Not implemented. Engineering Priority 0 includes portal spine after HTTP MCP is real enough to preflight against.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Use cases
|
||||
|
||||
Canonical use cases for product, engineering, and GTM. These are operating specs, not marketing blurbs.
|
||||
|
||||
| ID | Name | Model | Status |
|
||||
|----|------|-------|--------|
|
||||
| [UC-01](./uc-01-endpoint-auto-repair.md) | Endpoint activation — independent auto repair | Model 1 | Spec |
|
||||
| [UC-02](./uc-02-intermediate-tourism-board.md) | Intermediate activation — destination tourism board | Model 2 | Spec |
|
||||
| [UC-03](./uc-03-local-retail-general-store.md) | Endpoint activation — local retail / general store | Model 1 | Spec |
|
||||
|
||||
## How to write more of these
|
||||
|
||||
Use the same template as UC-01/UC-02:
|
||||
|
||||
- Problem and context
|
||||
- Primary actor and stakeholders
|
||||
- Preconditions
|
||||
- Main success scenario (numbered)
|
||||
- Alternate and exception paths
|
||||
- Success metrics
|
||||
- Explicit out of scope
|
||||
- Open questions
|
||||
|
||||
If a use case only restates strategy prose, it is not ready. If it cannot drive a sprint ticket, it is not ready.
|
||||
@@ -0,0 +1,155 @@
|
||||
# UC-01 — Endpoint activation: independent auto repair shop
|
||||
|
||||
**Status:** Spec
|
||||
**Business model:** Model 1 — Endpoint enablement
|
||||
**Primary surface:** Platform MCP + Self-Service Portal (activation)
|
||||
**Priority:** P0 (shapes Priority 0 engineering)
|
||||
|
||||
---
|
||||
|
||||
## 1. Problem
|
||||
|
||||
An independent auto repair shop (example: a transmission-focused garage in a suburban market) is increasingly invisible when consumers ask AI assistants for help. The shop may have a basic website and a Google listing, but those surfaces rarely expose specialization, services, availability, or a clean booking path in a form assistants can use. When an engine shortlists and then inspects the site, it finds ambiguity. The shop loses the recommendation moment without ever knowing it happened.
|
||||
|
||||
---
|
||||
|
||||
## 2. Desired outcome
|
||||
|
||||
Within one session, the owner (or a trusted family member / local web person) can:
|
||||
|
||||
1. Create a geolocal presence for the shop
|
||||
2. See how an assistant would currently understand them
|
||||
3. Attach a simple discovery pointer on their site
|
||||
4. Verify the live MCP answers correctly for their services
|
||||
5. Understand what to fix next
|
||||
6. Start receiving basic interaction reporting
|
||||
|
||||
The shop becomes machine-legible and bookable through assistants **without** buying a customer-facing chatbot product.
|
||||
|
||||
---
|
||||
|
||||
## 3. Actors
|
||||
|
||||
| Actor | Role |
|
||||
|-------|------|
|
||||
| **Owner or operator** | Decision maker; may not be technical |
|
||||
| **Delegate** (optional) | Daughter, office manager, or local web partner implementing the pointer |
|
||||
| **AI assistant** (external) | ChatGPT, Gemini, Claude, Copilot-class systems requesting local help |
|
||||
| **End consumer** | Person asking the assistant for a repair |
|
||||
| **geolocal platform** | Hosted MCP, ingestion, portal, telemetry |
|
||||
|
||||
---
|
||||
|
||||
## 4. Preconditions
|
||||
|
||||
- Shop has some public web presence (even a thin site) or can publish a single page that can hold a pointer
|
||||
- Shop can accept appointments (phone calendar is a weak start; Cal.com or equivalent is preferred for fulfillment path)
|
||||
- Operator can complete a web signup flow
|
||||
- For full fulfillment demo: a booking link or integrated booking endpoint exists or can be created during onboarding
|
||||
|
||||
---
|
||||
|
||||
## 5. Main success scenario
|
||||
|
||||
1. **Arrive** — Operator opens geolocal.io and starts “add my business.”
|
||||
2. **Genre selection** — They identify as automotive / auto repair. The experience switches to auto-repair language and examples (not generic SMB fluff).
|
||||
3. **Identity capture** — Name, location, website URL, phone, hours if known.
|
||||
4. **Initial scrape / reflection** — Platform fetches public site content and shows what it can already see: services mentioned, specialties, gaps, confusion.
|
||||
5. **Value simulation** — Portal shows a phone-and-chat style simulation: an assistant recommends this shop for a Korean-transmission style job, lists services it believes are offered, and proposes an appointment path (e.g. Thursday 3:00). Operator gets the aha: pre-qualified, in-scope demand.
|
||||
6. **Pointer install** — Portal gives a tiny attachment (well-known file, link tag, or equivalent multi-path option) pointing to the hosted MCP for this business. Operator or delegate installs it.
|
||||
7. **Preflight** — Portal runs a live test against the MCP (not a scripted mock). If services, specialty, hours, or booking path are wrong or missing, failures are explicit.
|
||||
8. **Correct** — Operator edits portal fields and/or site content; preflight re-runs until critical checks pass.
|
||||
9. **Upstream guidance** — Portal explains that MCP only helps after engines can find the site; offers a short findability checklist and optional partner referral.
|
||||
10. **Go live** — Endpoint is marked live. External agents that discover the pointer can call structured tools.
|
||||
11. **Report** — On a weekly cadence (or first short digest sooner), operator sees interaction counts, top intents, and gaps (“agents asked about warranty; you have no answer”).
|
||||
|
||||
---
|
||||
|
||||
## 6. Alternate paths
|
||||
|
||||
| ID | Trigger | Behavior |
|
||||
|----|---------|----------|
|
||||
| A1 | Operator is non-technical | Portal emphasizes one-click copy steps; offers partner handoff without blocking signup |
|
||||
| A2 | Website is nearly empty | Simulation still runs from portal-entered data; scrape reflection shows hard gaps; go-live may be limited until minimum content exists |
|
||||
| A3 | No online booking yet | Fulfillment path degrades to “call/book link pending”; portal prioritizes installing Cal.com (or peer) rather than inventing a booking engine |
|
||||
| A4 | Delegate implements pointer | Owner still owns account; delegate gets install instructions only |
|
||||
| A5 | Promo content changes (e.g. July 4 oil-change special) | Owner updates site or portal fields, re-runs preflight, confirms special appears in test harness |
|
||||
|
||||
---
|
||||
|
||||
## 7. Exception paths
|
||||
|
||||
| ID | Trigger | Behavior |
|
||||
|----|---------|----------|
|
||||
| E1 | Preflight fails repeatedly | Block “fully live” status; show ranked fixes; do not claim AI-ready |
|
||||
| E2 | Pointer installed on wrong domain | Detect mismatch; fail preflight with plain-language error |
|
||||
| E3 | Chronic low helpfulness after go-live | Quality loop opens coaching; after threshold, endpoint can be quarantined or decommissioned (see strategy quality rules) |
|
||||
| E4 | Business is not local service | Soft reject or route out of ICP during genre/identity step |
|
||||
|
||||
---
|
||||
|
||||
## 8. Functional requirements (product)
|
||||
|
||||
- Genre-aware onboarding for auto repair
|
||||
- Site scrape + human-readable reflection
|
||||
- Simulation that is obviously about *external* AI, not “your new chatbot”
|
||||
- Multi-path pointer generation (not a single fragile convention)
|
||||
- Live MCP preflight in browser
|
||||
- Editable structured profile (services, specialty, hours, booking link, story)
|
||||
- Reporting of agent interactions and failed questions
|
||||
- Partner referral option when site work exceeds self-serve
|
||||
|
||||
## 9. Data the MCP must support for this genre (minimum)
|
||||
|
||||
- Identity and location
|
||||
- Hours
|
||||
- Services list with plain-language descriptions
|
||||
- Specialization signals (e.g. transmissions, European/Korean makes)
|
||||
- Booking path (link or orchestrated booking later)
|
||||
- Story / trust copy (owner, tenure, guarantees if present)
|
||||
- Optional: emergency vs scheduled, estimate vs fixed-price notes
|
||||
|
||||
Exact schema lives in engineering; this list is the product contract for “auto pack v1.”
|
||||
|
||||
---
|
||||
|
||||
## 10. Success metrics
|
||||
|
||||
| Metric | Definition | Early target |
|
||||
|--------|------------|--------------|
|
||||
| Time to first preflight | Signup → first live MCP test | Under 30 minutes for a motivated operator |
|
||||
| Preflight pass rate | Share of signups that pass critical checks within 7 days | Track; improve weekly |
|
||||
| Pointer verified | Discovery attachment confirmed live | Required for “live” badge |
|
||||
| Weekly active endpoints | Live endpoints with ≥1 agent or preflight interaction | Leading indicator |
|
||||
| Owner-reported clarity | “I understand what this does” after simulation | Qualitative; interview first 20 |
|
||||
|
||||
---
|
||||
|
||||
## 11. Out of scope for UC-01
|
||||
|
||||
- Building a consumer marketplace or destination site
|
||||
- Replacing the shop’s booking vendor
|
||||
- Full SEO agency services
|
||||
- Multi-location franchise admin
|
||||
- Guaranteeing a specific assistant will recommend the shop (we make them recommendable; engines still choose)
|
||||
- Model 2 intermediate aggregation (see UC-02)
|
||||
|
||||
---
|
||||
|
||||
## 12. Dependencies
|
||||
|
||||
- HTTP multi-tenant MCP
|
||||
- Ingestion/scrape pipeline
|
||||
- Portal application
|
||||
- Auto-repair genre pack v1
|
||||
- Cal.com (or equivalent) for fulfillment path
|
||||
- Quality policy for quarantine/decommission
|
||||
|
||||
---
|
||||
|
||||
## 13. Open questions
|
||||
|
||||
1. Minimum content bar before “live” vs “limited live”?
|
||||
2. Which pointer formats do we support on day one vs later?
|
||||
3. Do we require booking link for go-live, or only for “bookable” badge?
|
||||
4. Who performs first decommission decision — product ops rule or human review only?
|
||||
@@ -0,0 +1,160 @@
|
||||
# UC-02 — Intermediate activation: destination tourism board
|
||||
|
||||
**Status:** Spec
|
||||
**Business model:** Model 2 — Intermediate enablement
|
||||
**Primary surface:** Intermediate MCP + member onboarding (reuses Model 1 endpoint mechanics)
|
||||
**Priority:** P1 for full dashboard; pilot can start as soon as Model 1 endpoints exist
|
||||
|
||||
---
|
||||
|
||||
## 1. Problem
|
||||
|
||||
A destination tourism board (example: a coastal city visitor bureau funded partly by lodging tax) is supposed to promote local experiences and member businesses. In practice, its website is a human-readable brochure: lists, categories, PDFs, event calendars. AI assistants treat that class of site as a **weak discovery surface** — useful for confirming that a place or business exists, weak for evaluating specialization, availability, or booking.
|
||||
|
||||
The board has budget it is expected to spend on promotion, and often limited internal confidence about how to spend it for the AI era. Member businesses pay dues and still remain invisible to assistants. The brochure rack in the hotel lobby still does more immediate work than the website does for agentic visitors.
|
||||
|
||||
---
|
||||
|
||||
## 2. Desired outcome
|
||||
|
||||
The board can:
|
||||
|
||||
1. Stand up a **destination-level MCP** that helps assistants understand the place and route to member services
|
||||
2. Onboard a first cohort of members onto geolocal endpoints (directly or via staff/partners)
|
||||
3. See simple evidence of value: member attach rate, agent hits, category demand
|
||||
4. Justify the pilot against lodging-tax / visitor-experience goals
|
||||
5. Convert members from pilot access to paid endpoints over time
|
||||
|
||||
The board stops being only a link list and becomes a **high-signal intermediate** in the AI discovery and evaluation path.
|
||||
|
||||
---
|
||||
|
||||
## 3. Actors
|
||||
|
||||
| Actor | Role |
|
||||
|-------|------|
|
||||
| **Board director / marketing lead** | Buyer; cares about destination performance and politics of members |
|
||||
| **Board staff** | Day-to-day member onboarding and content hygiene |
|
||||
| **Member business** | Local service or experience provider (charter, bike rental, repair, spa, etc.) |
|
||||
| **Visitor** | Consumer asking an assistant for things to do / local help while traveling |
|
||||
| **AI assistant** | External engine using intermediate + member signals |
|
||||
| **geolocal platform** | Intermediate MCP, member endpoints, reporting |
|
||||
|
||||
---
|
||||
|
||||
## 4. Preconditions
|
||||
|
||||
- Board has authority (or pilot permission) to run a technology pilot for members
|
||||
- Identifiable first verticals or member shortlist (e.g. charters, activities, essential services)
|
||||
- Ability to communicate with members (email list, meetings, onboarding workshop)
|
||||
- geolocal can host member endpoints (UC-01 mechanics available, even if rough)
|
||||
- Legal: basic pilot terms and data use understanding
|
||||
|
||||
---
|
||||
|
||||
## 5. Main success scenario
|
||||
|
||||
1. **Pilot framing** — Board agrees the goal is AI visitor helpfulness and member discoverability, not “another directory redesign.”
|
||||
2. **Destination profile** — Staff provide place identity, priority categories, seasonal notes, and member list.
|
||||
3. **Intermediate MCP live** — Platform exposes a destination endpoint assistants can use to understand the place and list structured member options by category.
|
||||
4. **Member cohort invite** — Board invites 20–100 members into onboarding (workshop, email, or staff-assisted).
|
||||
5. **Member activation** — Each member completes UC-01-style activation (scrape, pointer, preflight) with destination context pre-associated.
|
||||
6. **Aggregation** — Intermediate MCP only surfaces members that meet minimum quality/live bars (not every unpaid legacy listing by default).
|
||||
7. **Visitor path** — A visitor asks an assistant for a charter, e-bike rental, or emergency phone repair in the destination; assistant can use intermediate signal and/or member MCP rather than a thin brochure page alone.
|
||||
8. **Board reporting** — Dashboard (or pilot report) shows members live, category coverage, interaction counts, and top unmet intents.
|
||||
9. **Conversion** — After pilot window, members move to paid tiers; board retains intermediate subscription or partnership terms.
|
||||
10. **Expansion** — Board adds categories or a second wave of members; quality bar remains enforced.
|
||||
|
||||
---
|
||||
|
||||
## 6. Alternate paths
|
||||
|
||||
| ID | Trigger | Behavior |
|
||||
|----|---------|----------|
|
||||
| A1 | Board wants white-glove only | Staff or geolocal-assisted onboarding for first cohort; self-serve still available |
|
||||
| A2 | Chamber of commerce instead of tourism board | Same intermediate pattern; funding story shifts from lodging tax to member value / economic development |
|
||||
| A3 | Members already on booking platforms | Keep those booking paths; intermediate still supplies discovery/evaluation structure |
|
||||
| A4 | Low technical capacity at board | Start with spreadsheet-fed member import + staff login; full dashboard later |
|
||||
|
||||
---
|
||||
|
||||
## 7. Exception paths
|
||||
|
||||
| ID | Trigger | Behavior |
|
||||
|----|---------|----------|
|
||||
| E1 | Member fails preflight | Exclude from intermediate “recommended” set until fixed; still visible to staff as incomplete |
|
||||
| E2 | Member harms destination helpfulness | Quarantine from intermediate aggregation; board notified |
|
||||
| E3 | Political pressure to list everyone regardless of quality | Product keeps a “directory dump” mode separate from “AI-recommended set”; do not poison the high-signal path |
|
||||
| E4 | Procurement delay | Keep SMB self-serve in market; treat board as parallel track, not a gate on all GTM |
|
||||
|
||||
---
|
||||
|
||||
## 8. Functional requirements (product)
|
||||
|
||||
- Destination (intermediate) entity with categories and member associations
|
||||
- Intermediate MCP tools: place overview, category browse, member resolve, seasonal notes
|
||||
- Member onboarding that reuses endpoint activation
|
||||
- Quality gating between “listed” and “AI-ready / aggregated”
|
||||
- Board-facing report or dashboard: attach rate, hits, intents, gaps
|
||||
- Pilot-friendly admin (invite, status, export)
|
||||
|
||||
## 9. What the intermediate MCP must do (minimum)
|
||||
|
||||
- Answer “what is this place good for?” in structured form
|
||||
- List live members by category with deep links to member MCP identity
|
||||
- Avoid inventing services the member cannot support
|
||||
- Prefer members with passing preflight and fresh data
|
||||
- Expose contact/booking paths only when member endpoint provides them
|
||||
|
||||
The intermediate is a **bridge with signal**, not a second Yelp and not a passive HTML list.
|
||||
|
||||
---
|
||||
|
||||
## 10. Success metrics
|
||||
|
||||
| Metric | Definition | Early pilot target |
|
||||
|--------|------------|--------------------|
|
||||
| Members invited | Cohort size | 20–100 |
|
||||
| Members live | Passed critical preflight + pointer verified | ≥40% of invited within pilot window |
|
||||
| Intermediate queries | Agent or test harness hits on destination MCP | Weekly growth |
|
||||
| Category coverage | Priority categories with ≥1 live member | Board-defined must-have set complete |
|
||||
| Board satisfaction | Willingness to renew / expand | Explicit yes/no at pilot review |
|
||||
| Member conversion | Live members → paid after pilot | Track; optimize after first pilot |
|
||||
|
||||
---
|
||||
|
||||
## 11. Out of scope for UC-02
|
||||
|
||||
- Replacing the board’s full CMS or membership CRM
|
||||
- Building a consumer destination marketplace branded as geolocal
|
||||
- Guaranteeing tourism lift numbers in season one
|
||||
- National multi-board enterprise packaging before one pilot works
|
||||
- Owning lodging, flights, or car rental (Airbnb/Kayak space)
|
||||
|
||||
---
|
||||
|
||||
## 12. Dependencies
|
||||
|
||||
- UC-01 endpoint activation working for at least one tourism-relevant genre
|
||||
- Intermediate MCP routing and aggregation rules
|
||||
- Pilot agreement template (legal)
|
||||
- Reporting (even CSV/manual is acceptable for first pilot)
|
||||
- Quality policy shared with Model 1
|
||||
|
||||
---
|
||||
|
||||
## 13. Funding and sales notes (GTM, not engineering)
|
||||
|
||||
- Pitch against **mandated or expected promotion spend**, not against random software budget
|
||||
- Language: visitor experience, member value, AI-era discoverability, stewardship of lodging-tax intent
|
||||
- Proof: before/after member AI-readiness and intermediate query evidence
|
||||
- Risk to name honestly: procurement speed; mitigate with short pilot and parallel SMB motion
|
||||
|
||||
---
|
||||
|
||||
## 14. Open questions
|
||||
|
||||
1. First destination market(s)?
|
||||
2. Does the board pay, members pay, or both during pilot?
|
||||
3. Hard quality gate for aggregation from day one, or soft gate with warnings?
|
||||
4. Branding: geolocal-powered vs fully white-labeled board experience for v1?
|
||||
@@ -0,0 +1,114 @@
|
||||
# UC-03 — Endpoint activation: local retail (general store)
|
||||
|
||||
**Status:** Spec
|
||||
**Business model:** Model 1 — Endpoint enablement
|
||||
**Primary surface:** Platform MCP + Self-Service Portal
|
||||
**Priority:** In vision and ICP from day one; implementation may follow first service pack, not exclude retail from strategy
|
||||
|
||||
---
|
||||
|
||||
## 1. Problem
|
||||
|
||||
A small local retailer (example: a general store in Athol, Idaho) is easy for a human neighbor to understand and hard for an AI assistant to represent honestly. The store’s website, if it exists, is thin. Reviews may mention chicken strips once in 2019. Nothing structured says they carry basic toiletries, what the house specialties are, or when to come by.
|
||||
|
||||
When a traveler or local asks ChatGPT whether that store has a toothbrush or is worth stopping for food, the assistant either guesses, recommends a chain, or stays vague. The store never sees the miss.
|
||||
|
||||
---
|
||||
|
||||
## 2. Desired outcome
|
||||
|
||||
The operator can publish structured local truth so an assistant can answer, with grounding in the store’s own data:
|
||||
|
||||
- Yes — they typically carry everyday items like toothbrushes
|
||||
- Yes — chicken strips (or another house specialty) are a known reason to stop
|
||||
- Hours, location, and visit/pickup expectations
|
||||
- Optional: limited “ask us” path if inventory is uncertain
|
||||
|
||||
This is **not** full real-time warehouse inventory for v1 unless the store already has a feed. Honest “we carry / house specialty / hours” beats fake precision.
|
||||
|
||||
---
|
||||
|
||||
## 3. Actors
|
||||
|
||||
| Actor | Role |
|
||||
|-------|------|
|
||||
| Owner / operator | Maintains what the store wants AI to say |
|
||||
| Consumer | Asks an assistant a place-based retail question |
|
||||
| AI assistant | External engine calling the MCP |
|
||||
| geolocal platform | Hosted MCP, portal, ingestion, telemetry |
|
||||
|
||||
---
|
||||
|
||||
## 4. Preconditions
|
||||
|
||||
- Physical store location
|
||||
- Ability to publish a discovery pointer (own site or simple landing page)
|
||||
- Operator can list categories, flagship items, and specialties in plain language
|
||||
- Optional later: POS/inventory integration for confirmed stock
|
||||
|
||||
---
|
||||
|
||||
## 5. Main success scenario
|
||||
|
||||
1. Operator signs up and chooses **local retail / general store** genre.
|
||||
2. Portal scrapes any existing site and reflects gaps.
|
||||
3. Operator enters or confirms: hours, categories carried, flagship items, house specialties, parking/visit notes.
|
||||
4. Simulation shows an assistant answering “toothbrush?” and “what’s good here?” using that structured truth.
|
||||
5. Pointer installed and preflight passes.
|
||||
6. Live endpoint serves tools such as business info, hours, assortment/specialty summary, visit path.
|
||||
7. Reports show what people (via agents) asked — including misses (“asked for propane; not listed”).
|
||||
|
||||
---
|
||||
|
||||
## 6. Alternate and exception paths
|
||||
|
||||
| ID | Case | Behavior |
|
||||
|----|------|----------|
|
||||
| A1 | No inventory system | Use “typically carry” categories and curated specialties; never claim live stock |
|
||||
| A2 | Hybrid sell + service | Combine retail primitives with service/booking tools (e.g. bike shop) |
|
||||
| E1 | Operator claims infinite stock for everything | Preflight/quality warnings; quality policy may quarantine misleading endpoints |
|
||||
| E2 | Pure online shop, no storefront | Out of ICP; route away |
|
||||
|
||||
---
|
||||
|
||||
## 7. Minimum MCP / genre contract (retail v1)
|
||||
|
||||
- Identity, location, hours
|
||||
- Categories typically carried
|
||||
- Flagship items / house specialties (named, short descriptions)
|
||||
- Visit guidance (walk-in, pickup window if any)
|
||||
- Optional phone/contact
|
||||
- Explicit inventory confidence level: curated list vs live feed
|
||||
|
||||
---
|
||||
|
||||
## 8. Success metrics
|
||||
|
||||
- Preflight pass with at least hours + one specialty or category set
|
||||
- Simulation answers a “do you have X?” and a “what’s special?” question without hallucination from empty fields
|
||||
- Weekly report shows retail-shaped intents (carry, hours, food specialty), not only appointment intents
|
||||
|
||||
---
|
||||
|
||||
## 9. Out of scope for UC-03 v1
|
||||
|
||||
- Full Shopify replacement or cart/checkout
|
||||
- Guaranteed real-time stock without a feed
|
||||
- Marketplace shopping across many stores in one consumer app
|
||||
|
||||
---
|
||||
|
||||
## 10. Dependencies
|
||||
|
||||
- Retail genre pack v1
|
||||
- Portal genre branch for retail
|
||||
- UC-01 platform mechanics (pointer, preflight, reports)
|
||||
- Strategy §1a scope (local retail in ICP)
|
||||
|
||||
---
|
||||
|
||||
## 11. Open questions
|
||||
|
||||
1. How much assortment is enough for go-live (categories only vs item list)?
|
||||
2. When do we integrate POS for true stock?
|
||||
3. How do we prevent spammy “we have everything” profiles?
|
||||
Binary file not shown.
@@ -0,0 +1,486 @@
|
||||
# geolocal.io — Canonical Strategy
|
||||
|
||||
**Status:** Final draft (2026-07-18; revised same day for strategic depth and local-retail scope)
|
||||
**Role:** The document the team plans, builds, and sells against. When other docs disagree with this one, update them — or update this one deliberately. Do not leave the conflict hanging.
|
||||
|
||||
This is an operating strategy, not a product brochure. The Self-Service Portal matters, but it is one activation surface. The company is the platform underneath.
|
||||
|
||||
---
|
||||
|
||||
## 1. What we are
|
||||
|
||||
geolocal.io is the infrastructure that lets **local businesses** show up properly inside the AI era — discoverable, understandable, and actionable when someone asks an assistant for a plumber, a transmission shop, a fishing charter, a place to rent bikes, **or the general store that still has the toothbrush they forgot and the chicken strips worth driving for.**
|
||||
|
||||
We are not building another place for consumers to browse. We are not selling business owners a chatbot for their website. We are not trying to replace Yelp or Google as destinations people open on purpose. We are not trying to replace Shopify for pure online merchants.
|
||||
|
||||
We are the layer underneath for **brick-and-mortar and local presence** — services *and* local retail. AI agents call us. Businesses own their presence. Tourism boards, chambers, and agencies help distribute it. In plain terms: Shopify made agent-ready commerce easy for online stores; we make agent-ready presence easy for the long tail of real-world local businesses that do not live inside a Shopify-class stack.
|
||||
|
||||
---
|
||||
|
||||
## 1a. Who is in scope (and who is not)
|
||||
|
||||
The original exploration called out service businesses as the pain that is easiest to see. That was emphasis, not a hard wall. The North Star was aimed at **local businesses**, not “appointments only.”
|
||||
|
||||
### In scope
|
||||
|
||||
Businesses with a **real local footprint** that consumers ask AI about in place-based ways:
|
||||
|
||||
| Kind | Examples | What “helpful” often means |
|
||||
|------|----------|----------------------------|
|
||||
| **Local services** | Auto repair, salon, home services, charters, clinics | Specialization, hours, booking path, pricing signals |
|
||||
| **Local retail** | General store, hardware, pharmacy, gift shop, outfitter | “Do you have X?”, what’s in stock or typically carried, specialties/food, hours, directions, pickup |
|
||||
| **Hybrid** | Bike shop that rents and sells, marina store, bakery with catering | Both inventory-ish answers *and* services/booking |
|
||||
|
||||
The Athol, Idaho general store is a fair test case: an assistant should be able to say, with confidence rooted in the store’s own structured truth, that they carry toothbrushes and that the chicken strips are a known local draw — not invent it from a stale review scrape.
|
||||
|
||||
### Out of scope (for now)
|
||||
|
||||
- **Pure online commerce** with no meaningful local presence — that is Shopify Storefront MCP territory and peers
|
||||
- National pure-play marketplaces (Amazon, large pure e-com brands building their own agent stacks)
|
||||
- Trying to win Airbnb/Kayak-class lodging and travel packaging
|
||||
- Becoming a consumer shopping destination site
|
||||
|
||||
### Sequencing, not exclusion
|
||||
|
||||
Early genre packs and pilots can still **lead with services and tourism** (clear booking path, destination wedge). Local retail is **in the product vision and ICP from day one**. Retail primitives (assortment, “we carry,” specialties, hours) are a first-class genre family, not a later afterthought that contradicts the strategy.
|
||||
|
||||
---
|
||||
|
||||
## 2. Why this has to exist
|
||||
|
||||
### Consumers already changed behavior
|
||||
|
||||
A large and growing share of people now ask AI tools for local recommendations. BrightLocal’s 2026 consumer research puts that figure around 45%, with ChatGPT as the most common tool people name. Earlier surveys used different wording and showed much smaller numbers, so we should treat the leap as real without pretending every percentage point is apples-to-apples in investor decks.
|
||||
|
||||
What matters operationally is the shape of the answer. AI does not hand you a page of blue links. It names one, two, or three businesses. If you are not one of those names, you do not exist in that moment.
|
||||
|
||||
### AI is extremely selective about who it recommends
|
||||
|
||||
SOCi’s 2026 Local Visibility Index looked at roughly 350,000 locations across more than 2,700 multi-location brands. In that sample, ChatGPT recommended only about 1.2% of brand locations. Gemini and Perplexity were higher but still far below traditional Google local 3-pack visibility. Locations that do get recommended tend to look trustworthy — high ratings, complete profiles, consistent signals.
|
||||
|
||||
Traditional local SEO still matters. It is no longer enough. Businesses need a machine-readable, up-to-date expression of who they are — and, when it applies, how to book, buy, pick up, or walk in.
|
||||
|
||||
### The long tail is last again
|
||||
|
||||
Independent brick-and-mortar — **services and local retail** — is poorly positioned for this shift. The pattern rhymes with the early web: platforms and structured commerce move first; the general store, the garage, and the charter captain catch up late, if at all. Airlines, hotels, rental-car players, and Shopify-class merchants are already investing in agent-ready experiences. Athol’s general store and Bob’s Garage are not.
|
||||
|
||||
---
|
||||
|
||||
## 3. How AI actually finds local businesses today
|
||||
|
||||
This section is load-bearing. Product and GTM only make sense if we respect how assistants really build a shortlist.
|
||||
|
||||
### Different engines, different substrates
|
||||
|
||||
Major assistants do not share one local-business brain. Each leans on a preferred retrieval substrate, then blends search and reasoning:
|
||||
|
||||
| Assistant (typical pattern) | Primary local substrate | Practical effect |
|
||||
|-----------------------------|-------------------------|------------------|
|
||||
| ChatGPT | Yelp-style business/review data + search | Strong where Yelp is strong; weak for unlisted long-tail shops |
|
||||
| Gemini | Google Business Profile, Maps, Knowledge Graph | Strong where GBP is complete; Google-centric fulfillment bias |
|
||||
| Claude | Sparse POI data (historically Foursquare-class) + search | Often thinnest local coverage; more reasoning over incomplete data |
|
||||
| Copilot-class systems | Search-first (e.g. Bing index) + tools | Depends heavily on what the open web makes legible |
|
||||
|
||||
On top of that, all of them still use general search, schema, and whatever tools or plugins are available. The strategic point is not the brand names of the datasets. The point is **fragmentation**: a local business can be invisible because it is missing or weak in the substrates the engines actually trust.
|
||||
|
||||
### From intent to shortlist to the real website
|
||||
|
||||
Roughly, the pipeline looks like this:
|
||||
|
||||
1. User states a need.
|
||||
2. The engine interprets category, place, urgency, and constraints.
|
||||
3. It retrieves candidates from its preferred substrate plus search.
|
||||
4. It narrows to a shortlist.
|
||||
5. For the serious candidates, it often loads or re-checks the actual website and any structured endpoints it can find.
|
||||
6. It evaluates which option is most helpful — not merely most popular.
|
||||
7. It tries to fulfill (book, call path, pay, confirm).
|
||||
8. Over time it reinforces paths that worked.
|
||||
|
||||
That middle stretch is where long-tail businesses die. A Wix site from 2005 with a few photos and a phone number may be “a website,” but it is a poor helpfulness surface. Specialization is buried. Services are ambiguous. Booking is a phone tag. Pricing is a shrug. Engines notice.
|
||||
|
||||
### Helpfulness and repeatability
|
||||
|
||||
Relevance gets you considered. Helpfulness is why an assistant comes back. Helpfulness includes clear services, real specialization, honest pricing signals, availability, a clean booking path, and trust cues. When an engine finds a path that works repeatedly, it prefers that path next time. Our job is to make geolocal-backed businesses the path of least resistance for helpfulness.
|
||||
|
||||
---
|
||||
|
||||
## 4. North Star
|
||||
|
||||
Make AI give the most relevant and helpful recommendation for a **local** need — and then help fulfill it when fulfillment applies (book, reserve, pick up, walk in with the right expectation).
|
||||
|
||||
We stay focused on **local businesses with real-world presence**. We are not trying to boil the ocean of all global e-commerce.
|
||||
|
||||
---
|
||||
|
||||
## 5. Where we sit in AI-first commerce
|
||||
|
||||
Think of AI-first consumption as seven stages:
|
||||
|
||||
1. **Intent** — the user says what they need
|
||||
2. **Interpretation** — the AI turns that into category, constraints, place, urgency
|
||||
3. **Discovery** — candidates enter the pool
|
||||
4. **Evaluation** — which options are clear, specialized, available, trustworthy, bookable
|
||||
5. **Selection** — the assistant names the winner(s)
|
||||
6. **Fulfillment** — book, schedule, pay, confirm
|
||||
7. **Feedback** — the system learns what worked
|
||||
|
||||
### Our chair (be disciplined about this)
|
||||
|
||||
| Stage | Our role | Notes |
|
||||
|-------|----------|--------|
|
||||
| Intent | None | User-driven |
|
||||
| Interpretation | Second chair | We shape interpretation by exposing clean attributes and genre primitives |
|
||||
| Discovery | Light touch | We enable attachment and intermediate signal; we do **not** try to own SEO/GEO as a product |
|
||||
| Evaluation | Primary | Structured truth, specialization, trust signals |
|
||||
| Selection | Primary | Become the tie-breaker for helpfulness |
|
||||
| Fulfillment | Primary, complementary | Orchestrate booking/payment partners; do not rebuild Calendly, Square, or Stripe |
|
||||
| Feedback | Second chair | Telemetry and quality loops reinforce good paths and remove bad ones |
|
||||
|
||||
If we drift into “we are an SEO company” or “we are a booking company,” we lose the plot.
|
||||
|
||||
### What “as-built” looks like for local SMBs in 2026
|
||||
|
||||
When engines judge helpfulness, three dependency areas keep showing up:
|
||||
|
||||
1. **Website / public content** — can a machine understand what this business does or sells?
|
||||
2. **Communication** — can a customer or agent complete a conversation path?
|
||||
3. **Transaction path** — booking, reservation, payment, pickup, or clear walk-in expectation
|
||||
|
||||
For a salon, that third path may be appointments. For a general store, it may be “yes we carry that,” hours, and “come get it before six.” Both are local fulfillment. Neither requires us to become Shopify.
|
||||
|
||||
Some vendors in those lanes will grow their own MCPs (scheduling tools, salon platforms, POS systems, big e-com platforms). That is fine and expected. Scenario-specific tools do not replace a neutral, business-owned local presence that works across assistants for the long tail.
|
||||
|
||||
---
|
||||
|
||||
## 6. Four business models (keep them distinct)
|
||||
|
||||
This company is not one product with one customer. It is four stacked models that reinforce each other.
|
||||
|
||||
### Model 1 — Endpoint enablement
|
||||
|
||||
Individual small businesses attach to geolocal. They get a hosted multi-tenant MCP, a discovery pointer on their own site, portal tools to activate and test, diagnostics, and reports.
|
||||
|
||||
### Model 2 — Intermediate enablement
|
||||
|
||||
Tourism boards, chambers of commerce, and visitor bureaus become better discovery nodes. Today, AI often treats those sites as **weak link aggregators**: useful for existence and category, weak for evaluation and fulfillment. We upgrade them into structured, member-backed MCP surfaces that actually help assistants choose and complete.
|
||||
|
||||
### Model 3 — Industry trust layer
|
||||
|
||||
Over time, quality norms, genre standards, and decommissioning of bad data make geolocal a surface AI systems learn to prefer. This is the strategic prize of doing Models 1 and 2 well, not a year-one slideware line.
|
||||
|
||||
### Model 4 — Service graph
|
||||
|
||||
Once enough endpoints and intermediates exist, the network itself becomes valuable: related services, specialties, demand patterns, competitive context. An AI-native successor to old local directory graphs — infrastructure and data products built on real usage, not social check-ins.
|
||||
|
||||
**Operating rule:** Every product decision should name which model it serves. We do not build Model 4 features before Models 1 and 2 are real.
|
||||
|
||||
---
|
||||
|
||||
## 7. Product definition
|
||||
|
||||
### Platform first
|
||||
|
||||
What we actually sell is **AI-readiness infrastructure for local businesses** (services and local retail with real presence):
|
||||
|
||||
1. **Hosted multi-tenant MCP** — structured tools agents call for story, hours, services or assortment signals, specialties, booking or visit path, related businesses, and genre-specific detail.
|
||||
2. **Discovery attachment on the business domain** — not a single magic path only. Industry precedent is already multi-location and extensible (`/mcp`, commerce-style paths, AI context paths, well-known files). Those locations can point **off-domain** to hosted infrastructure such as geolocal. That extensibility is what makes “easy for Bob’s daughter” possible.
|
||||
3. **Ingestion and content sync** — a strong channel from the business’s public content into the MCP. Garbage in, garbage out. If the source site cannot support helpful answers, the portal and reports have to say so.
|
||||
4. **Genre packs** — vertical primitives. A salon MCP is not identical to a phone-repair MCP, and neither is identical to a general store that needs “do you carry X?” and house specialties.
|
||||
5. **Orchestration of fulfillment partners** — Cal.com (and peers) where booking applies; Stripe/Square (and peers) where payment applies; inventory or POS hooks later where retail truth lives. We integrate; we do not rebuild those categories.
|
||||
6. **Telemetry and owner insight** — not vanity dashboards. Concrete helpfulness feedback: what agents asked, where they bounced, how the business compares to category peers, what to change.
|
||||
7. **Quality enforcement** — including the right to **decommission** chronically harmful endpoints. Bad data does not only hurt one customer; it taxes the trust of the whole network with AI engines.
|
||||
8. **Intermediate surfaces** — destination and chamber MCPs plus operator dashboards.
|
||||
9. **Activation UX** — Self-Service Portal for owners; partner flows for people who implement for them.
|
||||
|
||||
### Self-Service Portal — important, not the whole company
|
||||
|
||||
The portal is how Model 1 becomes self-serve at scale. It is a **small but critical corner** of the whole concept.
|
||||
|
||||
Owners come to geolocal.io, describe the business, and the experience becomes genre-aware. We scrape and reflect what we already see. We show a visual simulation of an assistant recommending them, listing services, and finding a real appointment path. They install a tiny pointer. They run a preflight against their live MCP. They get upstream guidance (get found) and downstream guidance (be understandable and bookable). They can choose self-serve fixes or a local partner. They receive ongoing reports.
|
||||
|
||||
One line we will not blur: **we are not selling them a customer chatbot.** The chat UI in the portal is a test harness so the owner can see how *external* assistants interpret the business — including how a July 4th oil-change special should appear, logos and details included.
|
||||
|
||||
### Genre-specific primitives
|
||||
|
||||
Generic “get business info” is scaffolding. Durable differentiation is genre systems:
|
||||
|
||||
- Auto: makes and models, specialties, emergency flags
|
||||
- Beauty: services, duration, stylist context
|
||||
- Home services: service radius, emergency vs scheduled, estimate vs fixed price
|
||||
- Tourism activities: seasonality, capacity, weather sensitivity
|
||||
- **Local retail / general store:** categories carried, flagship items or house specialties, “typically in stock” vs confirmed inventory when available, hours, pickup/walk-in guidance
|
||||
- Intermediates: member directory and category routing
|
||||
|
||||
Roadmaps ship **genre packs**, not only generic endpoints. Services packs may ship first for pilot speed; retail packs are in-scope product, not a strategy exception.
|
||||
|
||||
### What we will not build in the near term
|
||||
|
||||
We are not a consumer destination app. We are not competing with Calendly, Cal.com, or Square as booking engines. We are not competing with Stripe or Square as payment rails. We are not replacing Google Business Profile. We are not building a Yelp-style review network. We are not trying to out-Kayak Kayak or out-Airbnb Airbnb. We are not trying to out-Shopify Shopify for pure online stores. Stay complementary to those platforms; own the long tail of **local** businesses they do not serve cleanly for AI agents.
|
||||
|
||||
Upstream SEO/GEO checklists and partner referrals exist so businesses can *be found*. That work is enablement, not our core product category.
|
||||
|
||||
---
|
||||
|
||||
## 8. Trust, quality, and operations (table stakes)
|
||||
|
||||
If AI engines are going to rely on us for evaluation and fulfillment, we have to look like infrastructure they can trust — closer to Shopify or Stripe in operational posture than to a weekend plugin.
|
||||
|
||||
**Assumed bar for anything we claim is production:**
|
||||
|
||||
- Regional hosting and sensible data locality
|
||||
- High availability and graceful failure modes
|
||||
- Compliance posture appropriate to what we touch (privacy always; payments-grade controls if we handle payment data directly)
|
||||
- Strict, versioned schemas and deterministic tool behavior
|
||||
- Structured errors, rate limits, and clear retry semantics
|
||||
- Authentication and integrity on sensitive surfaces
|
||||
- Observability: metrics, logs, traces, uptime honesty
|
||||
|
||||
These are not “phase 3 nice-to-haves.” They are part of why an engine would prefer our path twice.
|
||||
|
||||
### Quality loop
|
||||
|
||||
1. Ingest and structure business truth.
|
||||
2. Serve agents.
|
||||
3. Measure helpfulness outcomes (exits, incomplete answers, booking drop-offs, peer benchmarks).
|
||||
4. Tell the owner what to fix.
|
||||
5. If a business remains chronically harmful to collective helpfulness, **decommission** or quarantine the endpoint.
|
||||
|
||||
That last step is uncomfortable and necessary. Model 3 depends on it.
|
||||
|
||||
---
|
||||
|
||||
## 9. Positioning
|
||||
|
||||
### Category
|
||||
|
||||
AI-readiness infrastructure for **local businesses** — or, shorter, agentic local commerce infrastructure.
|
||||
|
||||
### Analogies that help
|
||||
|
||||
- **Shopify Storefront MCP, but for local brick-and-mortar** — clear for technical audiences; includes local retail without claiming we replace Shopify
|
||||
- **Stripe for AI discovery and local presence** — infrastructure, not another consumer app
|
||||
- **Service and local-retail registry for the long tail** — 2028 language when talking to platforms and sophisticated partners
|
||||
|
||||
### Messaging that works
|
||||
|
||||
- **Business owner (services):** Make every AI assistant understand and book your business.
|
||||
- **Business owner (retail):** Make sure AI can tell people what you actually carry and why you’re worth the stop.
|
||||
- **Tourism board:** Turn lodging-tax dollars into AI-discoverable local experiences and businesses your members own.
|
||||
- **Agency or partner:** Add AI-readiness as a productized line — not another chatbot retainer.
|
||||
- **Investor:** A neutral MCP layer for the vast majority of local businesses AI currently skips, distributed through self-serve and municipal partners.
|
||||
|
||||
### Language to avoid
|
||||
|
||||
Do not call this an AI chatbot for the website. Do not claim we replace Google or Yelp. Do not position primarily as an SEO tool with AI features.
|
||||
|
||||
---
|
||||
|
||||
## 10. Go-to-market
|
||||
|
||||
### Primary wedge: tourism and destination intermediates
|
||||
|
||||
Hotel and lodging taxes create promotion budgets that destinations are often required to spend. Boards frequently struggle to spend that money well and sometimes openly solicit ideas. One intermediate relationship can bring many member endpoints online. The brochure rack in the hotel lobby is the analog world proving the job to be done; we are the AI-native version of that job.
|
||||
|
||||
Technically, the sale is not “another directory listing.” It is: **stop being a low-signal link list; become a high-signal MCP for your place and your members.**
|
||||
|
||||
Motion:
|
||||
|
||||
1. Choose one or two destination markets for a real pilot.
|
||||
2. Sell a board-level pilot: destination MCP, member onboarding, simple demand and hit reporting.
|
||||
3. Fund it with tourism marketing budgets, innovation RFPs, or visitor-experience framing.
|
||||
4. Give members free or discounted endpoints during the pilot, then convert to paid.
|
||||
|
||||
### Parallel motion: self-service local businesses
|
||||
|
||||
While intermediates mature, sell direct into high-intent verticals — auto repair, beauty, home services, tourism activities when a destination pilot needs them — **and** local retail where the “do you have it / what’s special here” job is obvious.
|
||||
|
||||
### Partners as distribution
|
||||
|
||||
Agencies, SEO shops, and local web people matter for hard websites and busy owners. They are distribution and implementation, not the center of the product story.
|
||||
|
||||
### Where we will not lead
|
||||
|
||||
We do not lead with national multi-location brand AI visibility software. We do not lead with pure e-commerce. We do not lead with pure B2B or non-local use cases. We do not try to plant a blackjack table on the Las Vegas sidewalk of Airbnb/Kayak.
|
||||
|
||||
---
|
||||
|
||||
## 11. Competitive posture
|
||||
|
||||
### How the vacuum gets filled
|
||||
|
||||
All vacuums get filled — by outsiders or by incumbents. The question is who, when, and how.
|
||||
|
||||
| Actor | Likely path | Our response |
|
||||
|-------|-------------|--------------|
|
||||
| Yelp | Default AI source of local truth via data + MCP | Business-owned truth and booking path the owner controls |
|
||||
| Google | Maps, Merchant, open commerce protocols | Complementary; help with GBP hygiene; do not fight Maps for UI |
|
||||
| Shopify | Expand agentic commerce | Copy good discovery patterns; do not compete for e-commerce |
|
||||
| Cal.com, Square, Vagaro | Booking and ops MCPs | Integrate; own discovery, genre, intermediates, graph, quality |
|
||||
| AI visibility SaaS for big chains | Measure enterprise footprints | Different buyer |
|
||||
| Local agencies | Manual “get recommended by AI” retainers | Partner channel |
|
||||
|
||||
### Moats, in the order we earn them
|
||||
|
||||
1. Endpoint density in specific geos and genres
|
||||
2. Genre primitive quality that engines prefer
|
||||
3. Telemetry and quality enforcement (including decommissioning)
|
||||
4. Intermediate contracts that lock distribution
|
||||
5. Trust posture and operational reliability
|
||||
6. Service graph effects after critical mass
|
||||
|
||||
Freshness comes from the real service economy — content updates, availability, bookings, agent interactions — not from social check-ins that dry up.
|
||||
|
||||
### 2026 to 2028
|
||||
|
||||
In the near term, engines are still learning which MCP patterns to trust. Over the next couple of years, structured endpoints become normal for commerce-like tasks. Businesses without machine-actionable presence get harder to recommend. Off-domain hosted MCPs become ordinary. The winners look less like “another SMB SaaS UI” and more like **registries and infrastructure** that assistants can rely on twice.
|
||||
|
||||
---
|
||||
|
||||
## 12. Pricing principles (SMB self-serve)
|
||||
|
||||
Infrastructure pricing, not chatbot usage pricing:
|
||||
|
||||
| Tier | Monthly | Intent |
|
||||
|------|---------|--------|
|
||||
| Starter | about $49 | Endpoint, portal test experience, monthly report, basic diagnostics |
|
||||
| Core | about $129 (anchor) | Full MCP, live preflight, weekly reports, demand insights, partner access |
|
||||
| Pro | about $249 | Multi-site, deeper telemetry, competitor signals, priority support |
|
||||
|
||||
Tourism board deals use separate pilot or enterprise pricing. Do not block launch on perfect price discovery.
|
||||
|
||||
---
|
||||
|
||||
## 13. What success looks like
|
||||
|
||||
### First 90 days
|
||||
|
||||
- Public multi-tenant MCP over HTTP
|
||||
- Portal spine good enough to activate real owners (scrape, simulation, pointer, preflight)
|
||||
- About 100 live endpoints
|
||||
- One tourism or destination pilot at LOI or live pilot
|
||||
- One or two genre packs
|
||||
- Booking path via Cal.com (link first is acceptable)
|
||||
- First dollars of ARR
|
||||
- Explicit quality rules written (even if enforcement is still manual)
|
||||
|
||||
### By 180 days
|
||||
|
||||
- About 1,000 endpoints
|
||||
- Three genres
|
||||
- Related-businesses handshake in production
|
||||
- Several intermediate dashboards active
|
||||
- Telemetry useful for real owner reports
|
||||
- First decommission or quarantine decisions made with a documented standard
|
||||
|
||||
### By 360 days
|
||||
|
||||
- About 10,000 endpoints
|
||||
- Several major chamber or tourism partnerships
|
||||
- Early anonymized demand or data product in beta or market
|
||||
- Case studies showing assistants prefer geolocal-backed paths in pilot geos
|
||||
|
||||
---
|
||||
|
||||
## 14. Product and technical priorities
|
||||
|
||||
User stories and distribution come before elegant architecture theater. Still, architecture must be built to the trust bar above.
|
||||
|
||||
**Priority 0 — prove Model 1 (platform + activation)**
|
||||
|
||||
1. HTTP MCP transport (stdio is not the open-internet product)
|
||||
2. Multi-tenant routing by business slug or domain
|
||||
3. Multi-path discovery attachment + off-domain pointer generation
|
||||
4. Ingestion/scrape sync good enough for helpful answers
|
||||
5. Portal spine: signup → scrape → simulation → pointer → preflight
|
||||
6. First genre pack(s) and real pilot businesses
|
||||
7. Cal.com path (redirect first, deeper integration next)
|
||||
8. Basic telemetry and quality metrics
|
||||
|
||||
**Priority 1 — prove Model 2**
|
||||
|
||||
9. Intermediate (tourism) MCP and member aggregation
|
||||
10. Board dashboard for members, hits, and categories
|
||||
11. Pilot paperwork and data agreements
|
||||
|
||||
**Priority 2 — feed Models 3 and 4**
|
||||
|
||||
12. Stronger telemetry pipeline and owner reports
|
||||
13. Related businesses tool and quality rules with real enforcement
|
||||
14. More genre packs
|
||||
15. Partner marketplace
|
||||
|
||||
**Explicitly later:** full white-label everywhere, heavy OAuth before we need it, public developer platform, full data-as-a-service product, CMS plugins until attach volume demands them.
|
||||
|
||||
---
|
||||
|
||||
## 15. Risks we take seriously
|
||||
|
||||
**Yelp or Google become “good enough.”**
|
||||
Counter with business-owned data, booking completion, genre depth, intermediate distribution, quality enforcement, and owner control.
|
||||
|
||||
**Small businesses will not care until bookings prove ROI.**
|
||||
Portal simulation, tourism-funded pilots, demand reports, and partner installs exist to close that gap.
|
||||
|
||||
**We over-index on the portal and under-build the platform.**
|
||||
Weekly check: are we shipping registry-grade infrastructure, or only onboarding UI?
|
||||
|
||||
**MCP and discovery conventions keep moving.**
|
||||
Support multi-path discovery; follow industry precedent; avoid private religion.
|
||||
|
||||
**Market statistics get oversold.**
|
||||
Cite carefully. Distinguish multi-location brand studies from all SMBs.
|
||||
|
||||
**Bad endpoints poison trust.**
|
||||
Measure helpfulness; coach; decommission when needed.
|
||||
|
||||
**Scope creeps into chatbots, SEO retainers, or consumer marketplaces.**
|
||||
Return to the chair table in §5.
|
||||
|
||||
**Tourism procurement is slow.**
|
||||
Run self-serve SMB in parallel. Prefer short pilots over perfect RFPs for the first win.
|
||||
|
||||
---
|
||||
|
||||
## 16. Document governance
|
||||
|
||||
| Document | Job |
|
||||
|----------|-----|
|
||||
| `docs/archive/` | Historical exploration only |
|
||||
| **`docs/strategy/CANONICAL_STRATEGY.md` (this file)** | **Operating strategy** |
|
||||
| `NORTH_STAR.md` | Short compass |
|
||||
| `docs/product/*` | Product surfaces and use cases |
|
||||
| `docs/gtm/*` | Channels and sales execution |
|
||||
| `docs/investors/*` | External packaging |
|
||||
| `docs/engineering/*` | Build plan and ADRs |
|
||||
| `docs/legal/*` | Privacy, IP, pilot terms skeletons |
|
||||
| `code/` | Priority 0 implementation (later monorepo: `apps/mcp-gateway`) |
|
||||
|
||||
If two documents disagree, resolve it on purpose.
|
||||
|
||||
---
|
||||
|
||||
## 17. Near-term leadership decisions
|
||||
|
||||
1. Keep this file as the single operating strategy.
|
||||
2. Align NORTH_STAR and GTM docs when they still tell a thinner story.
|
||||
3. Lock destination pilot shortlist and first genre pack.
|
||||
4. Treat Core ~$129 as the pricing anchor for experiments.
|
||||
5. Charter a 30-day engineering sprint around Priority 0 — not more strategy prose.
|
||||
6. Write the first quality/decommissioning standard before scale.
|
||||
7. Stand up lightweight legal for pilots, ToS, and telemetry privacy.
|
||||
|
||||
---
|
||||
|
||||
## 18. Closing
|
||||
|
||||
The company worth building is the platform: multi-tenant MCP, genre systems (services **and** local retail), ingestion, quality, intermediate upgrade path, and eventually a service-and-place graph. The Self-Service Portal is how ordinary businesses turn that platform on. Tourism boards are how we attach many endpoints at once. Trust and decommissioning are how we stay preferred by machines that only name one or two winners.
|
||||
|
||||
Market conditions support urgency without requiring panic. Consumers are using AI for local discovery. Recommendation is highly selective. Large platforms are MCP-enabling *their* layers. The long tail of local businesses — the garage **and** the general store — still lacks a neutral on-ramp.
|
||||
|
||||
Freeze strategy. Realign docs. Ship the platform. Activate with the portal. Scale through intermediates. Protect trust like it is the product — because for AI engines, it is.
|
||||
|
||||
---
|
||||
|
||||
## Research notes
|
||||
|
||||
Reference points used while forming and revising this strategy include BrightLocal consumer research on AI local recommendations, SOCi’s Local Visibility Index and related coverage, Shopify Storefront MCP and agentic commerce materials, Yelp’s MCP/data-for-agents direction, Google Maps/Merchant MCP materials, Cal.com MCP documentation, and public discussion of AI local discovery. Re-verify statistics before external pitches.
|
||||
@@ -0,0 +1,12 @@
|
||||
# Strategy
|
||||
|
||||
| Doc | Role |
|
||||
|-----|------|
|
||||
| **[CANONICAL_STRATEGY.md](./CANONICAL_STRATEGY.md)** | Final-draft operating strategy — team plans, builds, and sells against this |
|
||||
|
||||
## Companion product specs
|
||||
|
||||
- [Product overview](../product/overview.md)
|
||||
- [Use cases](../product/use-cases/)
|
||||
|
||||
If another doc conflicts with the canonical strategy, update that doc or deliberately revise the strategy. Do not leave both live.
|
||||
@@ -1,36 +0,0 @@
|
||||
# Writing rules (outsider-first)
|
||||
|
||||
**Branch:** `planning-selfserve-audit`
|
||||
**Scope:** Strategy and research docs under `docs/` (especially commercial proposals and research briefs). Complements [`CONVENTIONS.md`](./CONVENTIONS.md) (anti-duplication); does not replace it.
|
||||
|
||||
These rules exist so a reader with no industry background can follow the argument on the first pass.
|
||||
|
||||
---
|
||||
|
||||
## 1. No insider jargon without a plain clause
|
||||
|
||||
On first use of a term a bakery owner would not know, explain it in one plain clause in the same sentence (or the next). Prefer ordinary words over acronyms. If you must use a short label later, introduce it once.
|
||||
|
||||
Examples: say “Google’s short list of three at the top of many local searches” before “3-Pack”; say “name, address, and phone” before “NAP”; say “Google Business Profile” before “GBP.”
|
||||
|
||||
## 2. Open every claim with the reader’s trigger
|
||||
|
||||
Before any product action or “we build…”, show the problem the reader feels — lost customers, wrong hours, dead phone number, AI pointed somewhere else. Action comes after the trigger. Reference voice on this branch: commits `fa98bdb` (claims for zero-insider readers) and `b859f3e` (claim 1 opens with the owner’s trigger).
|
||||
|
||||
## 3. Plain verbs, conversational prose
|
||||
|
||||
Write like a clear friend who knows the subject. Complete sentences. No throat-clearing (“the sections below keep…”, “they are the receipts”), no slogan-as-mechanism, no AI-slop padding.
|
||||
|
||||
## 4. Claims first, evidence underneath
|
||||
|
||||
Lead with the argument the outsider needs. Put tables, studies, and source labels below as support. Label evidence: practitioner-reported, vendor, primary study, or UNVERIFIED. Cite or mark BLOCKED — do not invent numbers.
|
||||
|
||||
## 5. One SoT per topic
|
||||
|
||||
Amend the existing file for a topic. Do not create sibling PLAN/CONCEPT/BRIEF twins. See [`CONVENTIONS.md`](./CONVENTIONS.md).
|
||||
|
||||
---
|
||||
|
||||
## Capture
|
||||
|
||||
Standing outsider-first rules recorded 2026-10-01 from corrected-voice passes on the research brief (`fa98bdb`, `b859f3e`).
|
||||
Reference in New Issue
Block a user