/open-geo

name: open-geo
description: Run an end-to-end GEO visibility measurement through a real AI interface, persist the captures, and return a portable JSON run artifact plus optional PDF/dashboard outputs. Use automatically on an explicit request to measure a brand's AI-search visibility, and as a composable data-collection step inside another agent workflow; the user should not have to launch the pipeline or dashboard manually.

Purpose

open-geo — GEO visibility run orchestrator

You are the orchestrator for one **open-geo run**: drive a list of queries through one AI engine, capture how the target domain shows up in the answers, ingest the captures through the validated pipeline, aggregate metrics, and emit a portable JSON artifact plus any requested presentation output — finishing with a short summary.

This skill is the **single operator and agent-workflow entry point**. It can be invoked directly by a user or called as one step inside another agent's workflow; in both cases it returns the same versioned JSON artifact for downstream consumption. It coordinates components that are specified in `pipeline/INTERFACES.md` (the authoritative contract). Read that file's **§1 (capture contract)** and **§3 (CLI contracts)** before acting if anything below is ambiguous — the shapes there win over this prose.

> Code/identifiers and intermediate JSON are English. The **final summary printed to the > user follows `--lang`** (default English). Run pipeline commands from the resolved > open-geo runtime root with its project venv (`.venv/bin/python`) so `pipeline.*` imports > resolve. An explicit absolute `--artifact-out` may point into the caller's workspace; > all other runtime state stays inside open-geo.

---

INVOCATION

/open-geo <questions.csv> <engine> <domain> --brand "<name>" --n-worker <N> \
          [--output data|dashboard|pdf|both] [--artifact-out <path.json>] \
          [--period today|all] [--lang en|ru|zh|ar] [--force] [--repeat R]

Positional arguments

| arg | meaning | |---|---| | `<questions.csv>` | Path to the input CSV. Columns: **`query,lens`** where `lens ∈ general \| branded \| comparative`. See `examples/questions.csv` for a ready sample. `general` = neutral query, no brand named; `branded` = brand explicitly named; `comparative` = brand vs alternatives. Either a **hand-made** CSV or one **generated by STEP A.5** (question harvesting, Feature 1 — `harvest/METHODOLOGY.md`); both are first-class. | | `<engine>` | Engine id, **snake_case**, e.g. `google`. This value is (a) the `engine` field written into every `QueryCapture` and the run, and (b) the basename of the capture playbook the workers load: `engines/<engine>.md` (so `google` ↔ `engines/google.md`). **This is the multi-engine extension point** — `google` (Google AI Overview), `chatgpt_search` (ChatGPT web search), `claude_search` (Claude web search), `yandex_neuro` (Yandex Alice / Нейро), `gemini` (Google Gemini), `deepseek` (DeepSeek web search) and `perplexity` (Perplexity) ship today, all live-validated; the others are on the roadmap (ROADMAP Feature 3), and adding one is mainly authoring `engines/<engine>.md` (see `engines/README.md`). | | `<domain>` | The **target** — a registrable domain (`example.com`) or a URL prefix (`github.com/user/repo`). Accept any spelling; normalized via `pipeline.schema.normalize_target`. Workers match links against the target via `matches_target`/`target_ranks` (same semantics pipeline-wide). |

Flags

| flag | required | default | meaning | |---|---|---|---| | `--brand "<name>"` | yes | — | Human brand name (free text, may contain spaces — keep it quoted). Stored on the run; used in report/dashboard titles and the summary. | | `--n-worker <N>` | yes | — | Number of capture sub-agents to run **in parallel** — the run's concurrency. Step 2 splits the queries into N chunks, one per worker. | | `--output data\|dashboard\|pdf\|both` | no | `data` | Optional presentation output. A portable JSON artifact is always produced; `data` means no server and no PDF. `dashboard`, `pdf`, and `both` add those outputs. | | `--artifact-out <path.json>` | no | `reports/run-<run-id>.json` | Absolute or caller-relative destination for the portable run artifact. Use this when another agent workflow needs the data in its own workspace. | | `--period today\|all` | no | `all` | Reporting window passed to the dashboard/report: `today` = just this run's date, `all` = full history for this brand+engine (adds the PDF trend chart / the dashboard's whole-period view). Previous-run deltas (INTERFACES §4.1) render whenever an earlier completed run exists — in the PDF for either period, and in the dashboard's latest-run view. | | `--lang en\|ru\|zh\|ar` | no | `en` | UI language for the deliverables: it is passed to the report (`report.generate --lang`) and is the dashboard's **default** language (the switcher can still change it in the browser). Extensible to any code registered in `i18n/locales.json`. It also sets the language of the **final summary** you print in step 7. | | `--force` | no | off | Override the **GEO-audit gate** (STEP 0): proceed with the run even when the audit verdict is `blocked` (a category-A blocker — the domain is unreadable by the engine's search bot / unreachable / JS-only). Without it, a `blocked` verdict hard-stops before any run and prints the remediation. Advisory (`ready_with_warnings`) verdicts never need `--force`. | | `--repeat R` | no | `1` | **Repeat-run group** (INTERFACES §2.1, Feature 5): capture the SAME question set R times as R ordinary runs sharing one `group_id`. Costs R× capture — a deliberate operator choice to separate signal from LLM noise. The dashboard then reads the group as one measurement: weighted mean of the seven metrics + a min–max spread chip per card (deltas are suppressed inside a group). `R=1` = today's behavior, no group. See "Repeats" note under STEP 1. |

If a required argument is missing, go to **STEP A** (the parameter wi