diff --git a/README.md b/README.md index d00c293..e56cad9 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,38 @@ -# geolocal.io — planning-rev2 +# geolocal.io — planning-selfserve-audit -**Net-new planning branch** (2026-09-15 session). Not a clone of `main`. Do not merge main docs here. +**Review surface branch** (from `planning-rev2` 2026-09-15 session lineage). Hot self-serve / remediation work 2026-10-01. Not a clone of `main`. Do not merge main docs here. + +**Start here for Ty review:** [`REVIEW.md`](REVIEW.md) ## Map (locked) | Path | Role | | :--- | :--- | +| `REVIEW.md` | Review package (requirements, decisions, flags, branch map, checklist) | | `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 | ## Placement rules (agents must follow) 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/-.md` with source URL. Link from the plan; don’t paste essays into the plan. +4. External survey / report → `docs/evidence/-.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: +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. ## Process diff --git a/REVIEW.md b/REVIEW.md new file mode 100644 index 0000000..b837109 --- /dev/null +++ b/REVIEW.md @@ -0,0 +1,183 @@ +# Review package — planning-selfserve-audit + +**Repo:** Ty_Tech/geolocal-io +**Review branch:** `planning-selfserve-audit` +**Tip at package write:** `8337408f5b8ea1414d322bafa0ff33dbaeb48a96` (re-verify after this commit) +**Primary SoT:** [`docs/SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md`](docs/SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md) +**Strategy spine:** [`docs/BUSINESS_PLAN.md`](docs/BUSINESS_PLAN.md) §1 North Star +**Conventions:** [`docs/CONVENTIONS.md`](docs/CONVENTIONS.md) · [`docs/writing-rules.md`](docs/writing-rules.md) +**Parallel (non-SoT):** [`docs/ALTERNATE_BUSINESS_PROPOSAL.md`](docs/ALTERNATE_BUSINESS_PROPOSAL.md) · [`docs/research-brief.pdf`](docs/research-brief.pdf) +**Field / API evidence (Core 3):** [`docs/product/genre-packs/SOURCES.md`](docs/product/genre-packs/SOURCES.md) + +## Goal + +Make this branch review-ready so Ty can approve without re-litigating. Decisions and open flags live in-repo here. No product closures invented in this file: contradictions are **FLAG**ged for Ty. + +## SoT pointers + +| Layer | File | Owns | +| :--- | :--- | :--- | +| Product architecture | CONCEPT | Remediation stack, fan-out honesty, lanes, genre parents, phases | +| Strategy / GTM / wedge | BUSINESS_PLAN | North Star intent, Discovery foundation / Core 3, owner workflow, MCP distribution | +| Parallel thesis (non-SoT) | ALTERNATE + research-brief.pdf | Action-plan / warehouse framing; denser aggregator evidence | +| Core 3 field/API only | SOURCES + core3-field-map | Do not treat as deep edit URL inventory for ranks 1–14 | + +Amend CONCEPT in place only. Evidence under `docs/evidence/`. No twin PLAN/NOTES/BRIEF beside CONCEPT. Do not merge or kill ALTERNATE. No force-push to `main`. + +## Requirements (what “done enough to review” means) + +- [ ] Mission readable without jargon: help owners get AI to recommend them; MCP = pipe not product; industry graph = Northstar, not v1 +- [ ] Scoreboard explicit: Presence + Recommendability +- [ ] Problem = black box of NAP/category copies; claim once → correct outward +- [ ] Solution still labeled architect-not-built: audit findings → correction tickets; held multi-platform verification as moat +- [ ] Stakeholder verify / prove-the-shop-is-theirs treated as first-class pain (not optional) +- [ ] Lane model present: Lane A umbrellas (Data Axle, Localeze, Foursquare) + Lane B per-platform majors +- [ ] Every material claim either cited or marked BLOCKED / FLAG +- [ ] No sibling PLAN/CONCEPT twins for the same subject (CONVENTIONS) + +## Research-backed requirements + +Musts already encoded in CONCEPT (morning 2026-10-01 commits). Do not weaken in review copy. + +- **Ticket shape (must):** field + wrong value + right value + proof URL (GBP / claimed truth). Same shape for Lane A and Lane B. +- **Two lanes (must):** Lane A umbrellas (Data Axle, Localeze, Foursquare) stop feed regen; Lane B claim / suggest-edit on own-DB surfaces. Umbrella-only or platform-only both fail. +- **One-click = ticket set (must):** not one syndication rewrite of the internet. Mint GBP-proof + Lane A + Lane B; re-audit = success check. +- **Fan-out ceiling (must productize honesty):** Localeze claim-once → many publishers, partner cadence often ~30–90 days, no partner-acceptance guarantee; Google fast-path needs separate verify/sync inside their product; Data Axle hours to ~two weeks on hard cases; **no free public one-to-many SMB fan-out API**; Yext-class = paid pipe not destination; GBP does **not** outbound-syndicate NAP; Apple writes Apple ecosystem only. +- **Held verification:** multi-platform verified status = moat; paid / fulfillment architecture, not free first-hour (align with BUSINESS_PLAN paid cleanup = fulfillment, not the product center). +- **Presence score inputs (open):** Core 3 min-bar lives in BUSINESS_PLAN + genre-packs. CONCEPT still open on Yelp + aggregators in v1 Presence. **FLAG** before claiming “we check X.” +- **V1 shell FLAG:** CONCEPT = interactive web first, revisit MCP ~3 months; BUSINESS_PLAN Owner MCP P0 parallel with web chat. Packaging must not pick a side. **FLAG for Ty.** + +## Decisions locked (do not re-litigate in review) + +1. Agent-era local SMB discoverability is the spine; MCP is implementation option, not the strategy product. +2. Industry graph is longer-term Northstar, not v1. +3. Single SoT file for self-serve AI discoverability = CONCEPT (amend in place). +4. Presence + Recommendability as the two scored outcomes of the North Star intent. +5. Two-lane remediation: umbrellas (A) + per-platform (B); ranked majors with owner remediation paths. +6. Stakeholder verification before honest audit / warehouse overwrite is core pain and action-plan step A. +7. Collaborator/chat-first process: write only on explicit amend/capture; no doc mill. + +## Remediations: resolve vs flag taxonomy + +| Class | Meaning | Reviewer action | +| :--- | :--- | :--- | +| **Resolve** | Owner (or product) can complete a concrete correction path with a known surface. Acceptance can be tracked. | Expect ticket shape: wrong value → right value → proof link → platform channel. | +| **Flag** | Known gap, commercial unknown, or timing risk that blocks shipping a path. | Keep visible; do not invent a product decision to close it. | +| **Hybrid (demoted)** | Earlier hybrid genre/parent framing — demoted to a flag unless CONCEPT re-elevates it. | Do not treat as locked architecture. | + +Lane A: Data Axle, Localeze/TransUnion, Foursquare. Lane B: GBP first as proof, then other ranked platforms (see CONCEPT 1–14). + +### Ranked stack 1–14 (status for review) + +Documented with owner workflows in CONCEPT (commits `20b1f9f` → `95cd0a1` → `967ba9a`). All are **architect-not-built** Resolve paths unless noted Flag. + +| Rank | Surface | Lane | Status | +| :---: | :--- | :--- | :--- | +| 1 | Google Business Profile | B (claim hub / Core 3) | Resolve path documented | +| 2 | Apple Business Connect | B (Core 3) | Resolve path documented | +| 3 | Bing Places | B (Core 3) | Resolve path documented | +| 4 | Foursquare Places | A + B | Resolve path documented | +| 5 | Yelp | B | Resolve path documented | +| 6 | Data Axle Local Listings | A | Resolve path documented | +| 7 | Localeze / TransUnion | A | Resolve path documented | +| 8 | YP / Thryv | B (long-tail feeds) | Resolve path documented | +| 9 | Tripadvisor | B (vertical) | Resolve path documented; **FLAG** thin for bakery/salon v1 genre gate | +| 10 | Facebook / Meta | B (low weight) | Resolve path documented | +| 11 | MapQuest / HERE / in-car / long-tail | A by default | Monitor after umbrellas; **FLAG** thin for v1 genre gate | +| 12 | Dun & Bradstreet | Low for consumer local | Skip unless B2B; **FLAG** thin for v1 | +| 13 | CityGrid | Legacy | Only if still stomping; **FLAG** thin for v1 | +| 14 | Yext / Uberall / BrightLocal (pipes) | Route through existing paid pipe | Not destinations; score publishers not pipe brand | + +## Platform links / fan-out — confirm / flag + +Desk pass against CONCEPT hyperlinks and fan-out section (commit `967ba9a` / `44c2d6c`). No external re-research in this package. + +| Item | Verdict | Notes | +| :--- | :--- | :--- | +| Ranks 1–14 marketing-root hyperlinks in CONCEPT | **CONFIRM** | Canonical pages linked in SoT (`967ba9a`) | +| Deep correction URLs / API per rank 1–14 | **FLAG** | SOURCES covers Core 3 field/API only; need second table for deep edit channels | +| Localeze “80–100+” vs ALTERNATE “80–90+” | **SOFT FLAG** | Align publisher-count language across CONCEPT and ALTERNATE | +| Localeze ~30–90d partner cadence + Google sync separate | **CONFIRM** | Encoded in CONCEPT fan-out section | +| Data Axle timing / free vs Premium docs link | **CONFIRM** | Hours–~2 weeks hard cases; Premium docs linked | +| Yext-class “often 200+” direct publisher APIs | **FLAG** | Cite evidence or soften number before locking | +| Foursquare suggest/edit (`POST /places/{id}/suggest/edit`) | **CONFIRM** | In CONCEPT workflows | +| No free public one-to-many fan-out API | **CONFIRM** | Product rule: one-click = ticket set | +| GBP no outbound NAP syndicate; Apple ≠ rivals | **CONFIRM** | Architect rule in CONCEPT | + +### Platform link inventory (marketing roots in CONCEPT) + +| # | Label | URL in CONCEPT | +| :---: | :--- | :--- | +| 1 | Google Business Profile | https://business.google.com | +| 2 | Apple Business Connect | https://business.apple.com | +| 3 | Bing Places | https://www.bingplaces.com | +| 4 | Foursquare | https://foursquare.com | +| 5 | Yelp | https://www.yelp.com | +| 6 | Data Axle Local Listings | https://www.data-axle.com/marketing-solutions/local-listings-management/ | +| 6b | Local Listings Premium docs | https://local-listings-premium.data-axle.com/docs | +| 7 | Localeze / TransUnion | https://neustarlocaleze.biz/ | +| 8 | YP / Thryv | https://www.yellowpages.com | +| 9 | Tripadvisor | https://www.tripadvisor.com | +| 10 | Facebook / Meta Business | https://www.facebook.com/business | +| 11 | MapQuest | https://www.mapquest.com | +| 12 | Dun & Bradstreet | https://www.dnb.com | +| 13 | CityGrid | https://www.citygrid.com | +| 14 | Yext | https://www.yext.com | +| 14b | Uberall | https://www.uberall.com | +| 14c | BrightLocal | https://www.brightlocal.com | + +## Weak / contradictory — flag before Ty reviews + +1. **MCP vs web-first:** BUSINESS_PLAN §8 (Owner MCP P0 parallel) vs CONCEPT (interactive web first, MCP ~3 months). Do not pick a side in packaging. **FLAG for Ty.** +2. **Rank vs regeneration:** FSQ/Yelp sit above Data Axle/Localeze in discoverability rank; that is not the same as regeneration-stop priority. Keep both frames labeled. **FLAG** if copy conflates them. +3. **Thin verticals in 1–14:** Tripadvisor / MapQuest / D&B / CityGrid are thin for bakery/salon v1. Gate the 14-stack by genre for v1 packs. **FLAG.** +4. **Held verification moat:** Do not sell as free checkup. How (OAuth / agency / ToS) is unproven. **FLAG.** +5. **Marketing roots ≠ deep edit links:** Need a second table; SOURCES pattern is Core 3 only today. **FLAG.** +6. **Localeze publisher count:** Align CONCEPT 80–100+ with ALTERNATE 80–90+. **SOFT FLAG.** +7. **Yext 200+:** Cite or soften. **FLAG.** + +## Open decisions already listed in CONCEPT (do not invent closures) + +- First genre cluster pack(s) to ship +- Web-only v1 vs also embed in a chat shell (see MCP FLAG above) +- Presence providers for v1 (Core 3 ± Yelp ± aggregators) +- How to measure Recommendability without overclaiming +- Where “email on file” for verify comes from +- Free vs paid; what never goes to a human vs escalation +- Veterinary: healthcare/regulated vs own call (GBP Pets ~59 leaves) +- v1 demand: ads/self-start only, intermediate-first, or both + +## Top review checklist + +1. Open CONCEPT first — baker/owner story include prove-you-own-it + black-box copies? +2. Solution still “to architect,” not claimed shipped? +3. Tickets: every audit finding → same ticket shape; GBP as proof? +4. Moat: held multi-platform verified status? +5. Genre parents match latest CONCEPT (destination workshop split, beauty ≠ healthcare, hybrid = flag)? +6. ALTERNATE clearly non-SoT; action plan coherent with CONCEPT lanes? +7. BUSINESS_PLAN §1 intent verbatim where North Star quoted? +8. Evidence under `docs/evidence/` only for cited research? +9. PDF vs ALTERNATE research section — match or note drift? +10. No new sibling docs without announced path (CONVENTIONS)? +11. Fan-out honesty visible (ticket set, not one rewrite)? +12. MCP vs web-first contradiction left as FLAG (not silently resolved)? + +## Branch map + +| Branch | Tip (at package prep) | Role for this review | +| :--- | :--- | :--- | +| **`planning-selfserve-audit`** | `8337408` (+ this REVIEW commit) | **YES — review surface.** Self-serve concept SoT, remediation 1–14, fan-out, alternate proposal, writing rules. | +| `planning-rev2` | `9efd554` | Background. Sep 15 SEO desk unslop; BUSINESS_PLAN / genre-packs / evidence lineage. Parent of hot branch. | +| `main` | `2aa7a2c` | Historical. July strategy / SSP archive. Raw material only; not current SoT on this review. | +| `ssp-refinement` | `a4cc4cd` | Historical. Conversational SSP UC-04/05 (July). Behind `main`; not current SoT. | +| `review/ready` | (optional integrator scratch) | Earlier mechanical prep fork; prefer **this** branch (`planning-selfserve-audit`) as Ty review surface. | + +Do not mass-delete remote branches. Prefer documenting over force-rewriting history. + +## Out of scope for this review package + +Coding, production deploy, force-push `main`, SlabUploader work, expanding ALTERNATE/PDF without Ty naming paths, inventing Presence “we check X” lists, closing MCP vs web-first without Ty. + +## Research flags (Desk) + +Desk confirm/flag table is above. Remaining open research items for Ty (not closed here): deep edit URL table; Localeze count align; Yext 200+ cite-or-soften; genre-gated 14-stack for v1 packs. diff --git a/docs/BUSINESS_PLAN.md b/docs/BUSINESS_PLAN.md index f308685..b839968 100644 --- a/docs/BUSINESS_PLAN.md +++ b/docs/BUSINESS_PLAN.md @@ -1,6 +1,6 @@ # geolocal.io — Business Plan (working draft) -**Branch:** `planning-rev2` +**Branch:** `planning-selfserve-audit` **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.