geolocal-io/REVIEW.md

Review package - planning-selfserve-audit

Repo: Ty_Tech/geolocal-io
Review branch: planning-selfserve-audit
Package tip: 1dfbbcd26d66643b10b71c620feaf22454509055
Primary SoT: docs/SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md
Strategy spine: docs/BUSINESS_PLAN.md §1 North Star
Conventions: docs/CONVENTIONS.md · docs/writing-rules.md
Parallel (non-SoT): docs/ALTERNATE_BUSINESS_PROPOSAL.md · docs/research-brief.pdf
Field / API evidence (Core 3): 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 FLAGged 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.