feat(agents): add native GEO Audit Agent

[vibegui]

Summary

Installs a per-org Virtual MCP — GEO Audit Agent — that runs the open-source geo-seo-claude toolkit inside Studio's warm sandbox to audit a website's visibility to AI search engines (ChatGPT, Claude, Perplexity, Google AI Overviews) and produce a composite GEO Score with a prioritized action plan.

The agent is fully native and declarative — no separately deployed MCP, no Python rewrite, no new external infrastructure. The agent's metadata.instructions orchestrates the audit using Studio's built-in VM tools (bash/read/write/share_with_user); the geo-seo-claude repo is cloned fresh on the first turn of every thread and pip install + playwright install are gated by marker files for warm-pool reuse.

What's in the diff

• apps/mesh/src/agents/geo-seo/prompt.md — ported SKILL.md, XML-structured to match the studio-pack convention. Sandbox bootstrap, per-audit-type dispatch table (full | quick | citability | crawlers | llmstxt | brands | schema | technical | content | platforms), composite scoring formula, archive via share_with_user, quality gates.
• apps/mesh/src/agents/geo-seo/index.ts — installGeoAuditAgent() mirroring installStudioPack, with stable geo-audit_<orgId> id and idempotent findById skip.
• apps/mesh/src/auth/org.ts — seedOrgDb hook installs the agent for every new org alongside the studio pack.
• apps/mesh/migrations/077-install-geo-seo-agent.ts — backfill for existing orgs, idempotent via onConflict.doNothing. Owner attribution follows the same pattern as 048-merge-projects-agents.

Out of scope (flagged for follow-up)

• GitHub issue creation: the sandbox does not yet expose GITHUB_TOKEN to the gh CLI (apps/mesh/src/tools/vm/start.ts:306-313 bakes the token into the clone URL only). v1 archives only via share_with_user. Wiring gh would unlock the "open issues per finding when a repo is attached" branch already noted in the prompt.
• PDF report generation (scripts/generate_pdf_report.py) — present in the cloned repo but not dispatched by the prompt.
• CRM features (geo-prospect, geo-proposal, geo-compare) — would need a geo_prospects storage table; deferred.

Test plan

• bun run --cwd=apps/mesh migrate succeeds; existing org gets a geo-audit_<orgId> row with subtype = 'agent'.
• bun run dev boots cleanly; GEO Audit Agent appears in the agents list with the violet BarChart02 avatar.
• Click the agent → new thread → paste https://example.com. Observe SSE: first-turn bash calls clone the repo, install requirements, install Playwright; subsequent turns reuse the warm sandbox (the .deps_installed / .playwright_installed marker files short-circuit the install steps).
• Audit produces /workspace/out/GEO-AUDIT-REPORT.md and the agent returns a share_with_user presigned URL in chat with a compact summary table (composite score + top 3 actions).
• Quick audit (quick https://example.com) returns an inline 60-second snapshot without writing files.
• down() removes only geo-audit_* VIRTUAL connections.

🤖 Generated with Claude Code

---

Summary by cubic

Add a native, per‑org GEO Audit Agent that runs geo-seo-claude inside Studio’s warm sandbox to audit a site’s visibility in AI search and produce a composite GEO Score with a prioritized action plan. Fully virtual (no external infra) and idempotent per org.

• New Features

  • Per‑org Virtual MCP with stable id geo-audit_<orgId> and violet BarChart02 icon.
  • Runs audits via built‑in VM tools (bash/read/write/share_with_user); clones geo-seo-claude on first turn, caches installs with marker files.
  • Prompt defines bootstrap, dispatch for full, quick, citability, crawlers, llmstxt, brands, schema, technical, content, platforms, plus composite scoring and report archiving.

• Migration

  • 077-install-geo-seo-agent backfills the agent for existing orgs; onConflict.doNothing keeps it safe to re-run.
  • seedOrgDb installs the agent for new orgs.
  • down() removes only geo-audit_* VIRTUAL connections.

^{Written for commit 096b091. Summary will update on new commits.}

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Suggested: Minor (2.312.0) — based on feat: prefix

React with an emoji to override the release type:

Reaction	Type	Next Version
👍	Prerelease	2.311.12-alpha.1
🎉	Patch	2.311.12
❤️	Minor	2.312.0
🚀	Major	3.0.0

Current version: 2.311.11

Note: If multiple reactions exist, the smallest bump wins. If no reactions, the suggested bump is used (default: patch).

[cubic-dev-ai]

2 issues found across 5 files

_{You’re at about 94% of the monthly review limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/migrations/077-install-geo-seo-agent.ts">

<violation number="1" location="apps/mesh/migrations/077-install-geo-seo-agent.ts:28">
P2: This migration reads prompt content from a live source file, so rerunning it later can produce different data (or fail if the file moves). Store an immutable prompt snapshot in the migration itself (or a migration-local snapshot file) instead.</violation>
</file>

<file name="apps/mesh/src/agents/geo-seo/prompt.md">

<violation number="1" location="apps/mesh/src/agents/geo-seo/prompt.md:87">
P2: Archive instructions assume every non-full audit has a markdown artifact, but `quick` has no file output and `llmstxt` outputs `llms.txt`, so the current rule can fail for valid audit modes.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: This migration reads prompt content from a live source file, so rerunning it later can produce different data (or fail if the file moves). Store an immutable prompt snapshot in the migration itself (or a migration-local snapshot file) instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/migrations/077-install-geo-seo-agent.ts, line 28:

<comment>This migration reads prompt content from a live source file, so rerunning it later can produce different data (or fail if the file moves). Store an immutable prompt snapshot in the migration itself (or a migration-local snapshot file) instead.</comment>

<file context>
@@ -0,0 +1,101 @@
+const AGENT_ICON = "icon://BarChart02?color=violet";
+
+export async function up(db: Kysely<unknown>): Promise<void> {
+  const instructions = readFileSync(PROMPT_PATH, "utf-8");
+  const metadata = JSON.stringify({ instructions });
+
</file context>

[cubic-dev-ai]

P2: Archive instructions assume every non-full audit has a markdown artifact, but quick has no file output and llmstxt outputs llms.txt, so the current rule can fail for valid audit modes.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/agents/geo-seo/prompt.md, line 87:

<comment>Archive instructions assume every non-full audit has a markdown artifact, but `quick` has no file output and `llmstxt` outputs `llms.txt`, so the current rule can fail for valid audit modes.</comment>

<file context>
@@ -0,0 +1,102 @@
+   - **Methodology appendix** — list which scripts ran and the geo-seo-claude commit hash from the bootstrap output.
+
+5. **Archive and reply.**
+   - Use `share_with_user` to upload `/workspace/out/GEO-AUDIT-REPORT.md` (or the type-specific markdown if not a full audit). Pass the returned URL back to the user as a clickable link.
+   - In chat, render a compact summary table (composite score + per-category scores + top 3 actions). Do NOT paste the full report into chat.
+   - If a GitHub repo is attached to this thread (a "Repo Environment" block appears at the top of these instructions when one is set), append a one-line note: "GitHub repo detected: `{owner}/{repo}` — automatic issue creation will be available once sandbox-side `gh` credentials are wired up." (Issue creation is a follow-up; v1 archives only via `share_with_user`.)
</file context>