Listing Alignment

All steps (reference)

1. Step 1. Open Alignment under Local listings

   From a project, open Business → Local listings, then the Alignment tab (or go directly to the Alignment hub). Without the Pennant flag the tab and routes are unavailable (404). Use **Confirm profile** to jump to Local SEO when no identity exists yet.

   What to do: Project sidenav → Business → Local listings → Alignment

   Where: local-listings.alignment.index

   

   Expected (pass)

   • Page title Listing Alignment
   • Listings | Alignment tabs visible
   • Empty state prompts confirming a business profile; Confirm profile links to Settings → Local SEO

   Negative cases (must fail safely)

   • Pennant off → 404
   • Local listings addon off → 403
   • Cross-org project → 403/404

2. Step 2. Confirm the canonical business profile on Local SEO

   Owner or Admin confirms public name, phone (E.164), website, country, and street address or service-area business on **Project Settings → Local SEO** (Listing Alignment identity section). Places search autofills phone/website/structured address when available. Prefill may also come from a linked Directory GBP or AI Business Profile. Confirmed fields are never auto-overwritten by crawls or AI refresh. Managers can save Local SEO defaults but only Owner/Admin confirm Alignment. Multi-location edit is deferred — hub Edit appears for the primary profile only.

   What to do: Settings → Local SEO (or hub Confirm profile) → fill NAP → Save

   Where: projects.settings

   

   Expected (pass)

   • Local SEO tab shows Listing Alignment identity fields when Pennant listing-alignment is on
   • Form validates website as a safe public URL
   • After Save, Hub shows the primary profile as Confirmed

   Negative cases (must fail safely)

   • Viewer → cannot open confirm redirect / cannot save Alignment
   • Manager → Local SEO saves without confirming Alignment
   • Missing required NAP fields → validation errors (Owner/Admin)

   Tips

   • Alignment-only orgs (no Local Rankings / GeoGrid) still get Local SEO for Owner/Admin so confirm is not stranded.
   • Legacy /alignment/profile/create bookmarks redirect here with a toast.

3. Step 3. Raise source coverage (crawl, Places, GBP, URLs)

   Before expecting high coverage: run a site architecture crawl for Website/Schema; confirm the Google listing when search is ambiguous (prefer **Use this Google listing** showing the Local SEO name and address — not a Place ID); connect or link GBP on the Listings tab; paste Yelp/BBB (and optional industry) URLs under Confirm listing URLs. The Sources table shows status and a next-step link for GBP when needed.

   What to do: Crawl site → Confirm Google listing / link Listings / paste URLs as needed

   Where: local-listings.alignment.index

   Expected (pass)

   • Confirm Google listing section when entitled to map sources
   • Sources table lists core directories with status badges
   • GBP next step links to Local listings when not connected or unmapped

   Negative cases (must fail safely)

   • No crawl → Website/Schema Not tested with guidance to run a site scan
   • Viewer → cannot confirm Places or save listing URLs

   Tips

   • When Local SEO already has a Google pin, confirm with “Use this Google listing” (name and address shown — no Place IDs).
   • Otherwise paste a Google Maps link for the business; candidates from an ambiguous search also appear after a Core run.

4. Step 4. Run a Core or Full audit and read coverage

   Members+ with run permission open **Run audit**, choose Core or Full in the slide-over (remaining monthly quota and 1-unit cost are shown), then start. The hub updates while the job runs. Coverage is tested/applicable sources — not a composite score. Health reflects open Fix now / Fix soon findings when present. Apple/Azure may show Not tested when gates forbid live checks.

   What to do: On a confirmed profile → Run audit → pick Core or Full → Start → wait for the hub to refresh after the job completes

   Where: local-listings.alignment.index

   

   Expected (pass)

   • Run audit opens the mode slide-over with remaining Core/Full quota
   • Latest run status, coverage explanation, and next steps after completion
   • View findings and Tasks actions when a run exists
   • Flash message if profile unconfirmed, overlapping run, or quota exhausted

   Negative cases (must fail safely)

   • Unconfirmed profile → blocked with message
   • Second concurrent run → overlapping-run error
   • Core/Full quota exhausted → Start disabled / quota exception message

   Tips

   • Full adds Angi/Trustpilot/G2 and up to five capped industry/CSV mappings on top of Core.
   • Quota defaults: Pro 10 Core / 2 Full per month (Filament overrides).

5. Step 5. Re-run after linking a listing

   Linking a directory and checking it are separate steps, and the check can finish seconds before the link finishes saving — so a directory you just linked can still read **Not tested**. When a listing is linked or re-mapped after the most recent audit, the hub says so and points you at running it again. The row keeps the URL you entered either way, including when a lookup ended without success, so there is always something to see and act on.

   What to do: Link a listing on Listings → return to Alignment → read the notice → Run audit again

   Where: local-listings.alignment.index

   

   Expected (pass)

   • Notice: your listings changed since the last audit
   • Directory row still shows the requested listing URL
   • Yelp / BBB rows that are not settled link to the Listings tab

   Negative cases (must fail safely)

   • Audit newer than every link → no notice
   • Another org linked a listing → no notice on this project

   Tips

   • The notice is about freshness, not failure — the statuses below it were simply recorded before your change.

6. Step 6. Review findings and close tasks

   Open View findings for the latest run, inspect field mismatches, and Mark resolved when the directory is fixed (or acknowledge). Tasks list open remediation work created automatically for Fix now / Fix soon findings.

   What to do: Latest run → View findings → open a finding → Mark resolved (or open Tasks)

   Where: local-listings.alignment.tasks.index

   Expected (pass)

   • Run detail lists findings ordered by priority
   • Finding detail shows field, source, priority, and recommended action
   • Mark resolved closes the finding and its open task for Members+

   Negative cases (must fail safely)

   • Viewer → can read findings/tasks but cannot Mark resolved
   • Cross-org finding/run URL → 404

7. Step 7. Admin: quotas, gates, and aggregator kill-switch

   Support/SuperAdmin open Filament → Listing Alignment → Alignment Settings to adjust per-tier quotas, Apple/Azure acquisition gates, aggregator enablement, freshness windows, coordinate bands, and evidence retention.

   What to do: Filament → Listing Alignment → Alignment Settings → Save

   

   Expected (pass)

   • Apple/Azure gate selects: Not tested / URL·CSV only / Proven
   • Citation aggregator toggle defaults off
   • Save shows success notification

   Negative cases (must fail safely)

   • Non-ops role → page inaccessible

   Tips

   • Set Azure gate to Proven only after AZURE_MAPS_SUBSCRIPTION_KEY is configured and POI calls are approved.
   • Leave aggregator off until a vendor endpoint is contracted.