Ty_Tech/geolocal-io
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

planning-rev2 net-new: session docs only

Browse Source 
Drop main pollution. Keep BUSINESS_PLAN, glossary, Core 3 map,
SOURCES, salon/bakery packs from 2026-09-15 session.
This commit is contained in:
porbot
2026-09-15 19:07:33 +00:00
commit 12901e5d5d
11 changed files with 458 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/product/README.md
+3
View File
@@ -0,0 +1,3 @@
# product
Genre packs and Core 3 field map for this planning session. See `genre-packs.md`.
docs/product/genre-packs.md
+36
View File
@@ -0,0 +1,36 @@
# Genre packs
**Structural direction (working):** three layers when surfacing work to owners — not one giant schema dump.
| 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 |
**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.
## Sourced Core 3 map + deep examples (planning-rev2)
- [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
## Earlier planned packs (from main / prior docs)
- Auto repair (see [UC-01](./use-cases/uc-01-endpoint-auto-repair.md))
- Beauty (overlaps salon — reconcile later)
- Home services
- Tourism activity ([UC-02](./use-cases/uc-02-intermediate-tourism-board.md))
- Local retail / general store ([UC-03](./use-cases/uc-03-local-retail-general-store.md))
## Why this matters
Assistants evaluate helpfulness by whether the business answers the *right* questions for its category. Salon booking ≠ bakery known-for products.
## Detail source
Conversation checkpoint on `planning-rev2`; [BUSINESS_PLAN.md](../strategy/BUSINESS_PLAN.md); [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) §1a.
docs/product/genre-packs/SOURCES.md
+55
View File
@@ -0,0 +1,55 @@
# 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 (porbot)
---
## 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).
docs/product/genre-packs/bakery.md
+41
View File
@@ -0,0 +1,41 @@
# 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.
docs/product/genre-packs/core3-field-map.md
+36
View File
@@ -0,0 +1,36 @@
# 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.
docs/product/genre-packs/salon.md
+40
View File
@@ -0,0 +1,40 @@
# 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.