cto-legends · module specification · intelligence · v0.2.2
legends-geogrid: Circular-Lattice Google Maps Rank Tracker & GBP Audit Studio
Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.
GitHub Repository (https://github.com/avalonreset/legends-geogrid) · Handoff: cto-legends handoff legends-geogrid
legends-geogrid is an open-source, agent-operated Google Maps rank checker, local competitive battlefield studio, and Google Business Profile (GBP) title-discrepancy workbench. Rather than relying on SaaS subscriptions that sample distorted square grids and cap visible listings at 20 pins, legends-geogrid orchestrates geodesic circular-lattice sampling (with search_this_area=false and depth=30) through legends-dataforseo at raw provider cost. Every installation includes a complete, zero-credit 10-mile, 0.5-mile spacing study of Home Slice Pizza in Austin, Texas (1,249 sampled origins across 4 search themes, 702 observed competitors, and 165 optically audited business profiles) so operators and agents can inspect the full interactive Leaflet Competitive Map Companion and 18-page vector Letter PDF report before configuring API credentials.
Under the hood, the Python CLI toolchain (tools/study.py, tools/competitive_collect.py, tools/business_name_review.py, tools/battlefield_intelligence.py, and tools/strategy_report.py) enforces strict pre-collection contracts and SHA-256 evidence lineage. When tasked with a business study, the agent reconciles public website text and GBP exact CIDs, validates 3 to 5 distinct customer search themes across shared three-origin intent pilots, and locks a spend ceiling before dispatching Standard-queue tasks. For recurring first-place rivals, the business-name review pipeline refreshes live GBP metadata, scrapes website branding, executes a multi-vantage Google Street View search quest (v0, v1, v2 at progressive 18m to 85m radii), and optionally runs legends-jev 1.14 optical signage recognition to score title-evidence-v1 concern confidence (0 to 5) with counterevidence preserved.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
A raw frontier LLM in a browser chat window cannot query coordinate-locked Google Maps packs across 1,249 geodesic origins, track asynchronous DataForSEO Standard-queue task IDs, compute orthogonal lattice components, or verify physical storefront signage against Street View road graphs. Static prompt wrappers that ask an LLM to 'audit local SEO' inevitably hallucinate rankings, conflate national keyword volume with neighborhood Map Pack visibility, or accuse competitors of keyword stuffing without checking physical signage or DBA counterevidence.
- Geodesic Circular-Lattice Geometry & Viewport Discipline: Square NxN grids over-weight corner zip codes by up to 41% in radial distance. legends-geogrid computes true circular-lattice coordinates on a 6,371.0088 km Earth radius with search_this_area=false, preserving all 30 organic ranked identities per origin and separating confirmed depth-30 absences (NR) from incomplete or pending tasks.
- Two-Key Spend Gates & Append-Only Reservation Ledgers: Every paid collection runner estimates task costs offline by default and refuses network execution unless both --execute and --confirm-cost-usd <ceiling> are explicitly passed. Before HTTP dispatch, tasks are written to an append-only reservation ledger so process interrupts or timeouts can resume via saved task IDs without duplicate purchasing.
- Multi-Vantage Street View Search Quest & Jev 1.14 OCR: To audit GBP keyword stuffing, tools/business_name_review.py queries SingleImageSearch at progressive radii (18m, 30m, 50m, 85m), filters out indoor 360 photospheres (<= 2 road nodes) and historical time-machine panoramas, calculates compass yaw bearings toward the storefront from 3 spatially distinct road vantages, and optionally runs ~200ms Jev 1.14 optical recognition to detect physical signage bounding boxes.
- Hash-Locked Study Lineage & Vector PDF Rendering: Study plans (geogrid-study/v1) bind website captures, GBP responses, and pilot probes by SHA-256 and UTC observation timestamps within a 30-day window. ReportLab and Playwright + OpenFreeMap render 18-page vector Letter PDFs and interactive HTML editions directly from immutable observation records.
CLI Subcommands & Capability Surface
python tools/study.py query-review | validate | run --plan <plan.json> --output-dir <dir> --execute --confirm-cost-usd <budget> — End-to-End Business Study & Pre-Scan Query Review: Validates business identity reconciliation (exact CID, coordinates, domain), source SHA-256 hashes, 30-day freshness windows, and 3-5 evidence-backed search themes with three-origin pilot intent citations. Generates pre-collection HTML/PDF proposals and executes Standard-queue grid collection within an explicit USD ceiling.python tools/lattice_sampling.py & python tools/competitive_collect.py --plan <plan.json> --output-dir <dir> --execute --confirm-cost-usd <budget> — Circular-Lattice Competitive Sampling & Collection: Constructs primary-centered regular lattices clipped to a geodesic radius or multi-phase exploratory competitor footprints (0.65 km 3x3 cores plus 2/5/10 km compass sentinel probes, merging origins within 50m). Retains all 30 organic Maps listings per coordinate and exports the nine-rival focus shortlist alongside the full observed field.python tools/business_name_review.py plan | submit | retrieve | websites | photos [--jev] | export | attach — GBP Business-Name Review & Optical Signage Dossier: Builds one case file per distinct first-place CID across the study. Refreshes current GBP profiles via Standard queue, captures public website branding, downloads GBP main_image/logo plus 3-vantage outdoor Street View panoramas (v0, v1, v2), optionally runs legends-jev 1.14 optical signage verification, and attaches the read-only dossier to the companion viewer.python tools/study.py enhance --run-dir <baseline> --output-dir <enhanced> --execute --confirm-cost-usd <budget> — Incremental Same-Extent Study Enhancement & Radius Composition: Subdivides or extends existing studies by reusing eligible observations within a configurable freshness window (default 24h, 1-168h policy range via --max-age-hours) and purchasing only the unmeasured coordinates. Links parent-child study lineage in the local study library and renders updated HTML and vector PDF reports.python tools/battlefield_intelligence.py --study <companion-study.json> --output-dir <dir> — Battlefield Intelligence & Split-Screen Strategy Room: Partitions 10-mile studies into 9 disjoint regions (core 0-2 mi, inner 2-5 mi directional sectors, outer 5-10 mi sectors) and computes regional rival coverage, near-top-three local blocker pressure (ranks 4-10), orthogonal connected components, and exact CID head-to-head matchups without additional API spend.python tools/geogrid_doctor.py --dataforseo --jev --reports --basemaps & python tools/strategy_report.py --config <config.json> — Zero-Credit Toolchain Readiness & Vector Report Engine: Verifies Python dependencies, DataForSEO transport integration, optional legends-jev OCR availability, ReportLab/Pillow PDF libraries, and Playwright Chromium street basemap rendering offline. Compiles multi-query study models into standalone HTML and 18-page Letter PDF strategy reports with --proof and --require-pdf-qa checks.
Raw Frontier LLM vs. legends-geogrid Execution Matrix
- Spatial Sampling & Rank Depth: Raw LLM (Guesses visibility from a single city-center search or square bounding box that distorts corner distances.) vs. Module (Samples geodesic circular lattices (e.g., 317 origins at 5 mi, 1,249 at 10 mi, 0.5 mi spacing) with search_this_area=false and depth=30.) — Collector receipts and territory-intelligence.js verify all expected lattice coordinates on a 6,371.0088 km Earth radius.
- Competitor Name-Stuffing Audits: Raw LLM (Flags any business title containing a city or service keyword as a policy violation without physical proof.) vs. Module (Refreshes exact CIDs, extracts site branding, captures 3-vantage outdoor Street View, and runs optional Jev 1.14 signage OCR with counterevidence.) — Exports hash-bound name-review.json and photos-manifest.json with 7-day freshness checks and 0-5 title-evidence-v1 rationale.
- Provider Spend & Queue Recovery: Raw LLM (Cannot estimate multi-origin SERP costs or recover interrupted batches without re-running paid calls.) vs. Module (Defaults to offline estimates; requires --execute and --confirm-cost-usd; persists Standard-queue task IDs in a reservation ledger.) — Re-running collection with --confirm-cost-usd 0 retrieves completed queue tasks from disk without new paid submissions.
- Territory & Head-to-Head Math: Raw LLM (Conflates absent listings with rank 21+ and invents opaque 'opportunity scores' across queries.) vs. Module (Distinguishes primaryAhead, rivalAhead, primaryOnly, rivalOnly, neither (depth-30 absence), and unknown (incomplete data) per origin.) — strategy-engine.test.js and unittest suites validate point-state denominators and orthogonal component adjacency.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Why does legends-geogrid use a circular lattice with search_this_area=false instead of a square grid?
- A square NxN grid stretches corner points up to 41% farther from the business than cardinal edge points, skewing coverage percentages toward corner neighborhoods. Sampling a geodesic circular lattice at uniform spacing (such as 0.5 miles across a 5-mile or 10-mile radius) with search_this_area=false measures real distance rings and directional sectors without viewport distortion.
- How does the multi-vantage Street View and Jev 1.14 signage verification prevent false keyword-stuffing accusations?
- Automated keyword heuristics often flag legitimate trading names or DBAs. tools/business_name_review.py refreshes the exact CID, scrapes the business website, pulls up to 3 spatially distinct current-year outdoor Street View panoramas aimed at the storefront (skipping indoor photospheres and blocked angles), and optionally uses legends-jev 1.14 OCR to check whether physical signage or logo badges support the displayed title before recording a 0-5 concern confidence score.
- What happens if a large DataForSEO Standard-queue scan is interrupted or still pending?
- Every submitted task ID and reservation is written to an append-only ledger on disk before and during dispatch. Re-running competitive_collect.py or business_name_review.py retrieve polls only the saved task IDs at $0 additional submission cost, preserving completed envelopes and never blindly re-purchasing tasks.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.