@adgine/geo-cli 1.2.8

package/skills/adgine-geo-integrations/scripts/cloudflare_worker.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Cloudflare Worker management for AI-traffic tracking.
+
+The Worker injects a script that logs AI crawler + referral visits. After
+deployment, the Worker page queries (overview/pages) return AI traffic
+analytics.
+
+Subcommands:
+  config                                  — get the Worker JS code + keys
+  deploy [--zone-id <id>]                 — deploy / re-deploy the Worker
+  undeploy [--keep-script] --yes          — remove route (and optionally script) DESTRUCTIVE
+  deploy-status                           — check whether Worker is deployed
+  overview   [--start <>] [--end <>]      — Worker traffic overview (AI grouping)
+  pages      [--page 1] [--limit 20]      — Worker page-level AI traffic rankings
+
+Usage:
+  python3 scripts/cloudflare_worker.py config
+  python3 scripts/cloudflare_worker.py deploy
+  python3 scripts/cloudflare_worker.py deploy-status
+  python3 scripts/cloudflare_worker.py overview
+  python3 scripts/cloudflare_worker.py undeploy --yes
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post, api_delete,
+    extract_data, print_json, truncate,
+    pad,
+)
+
+def _fmt_num(n):
+    if n is None:
+        return "--"
+    try:
+        f = float(n)
+        if f == int(f):
+            return f"{int(f):,}"
+        return f"{f:,.1f}"
+    except (TypeError, ValueError):
+        return str(n)
+
+
+def cmd_config(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/cloudflare/worker-config", key, base)
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    print("Worker configuration")
+    print()
+    for k in ("worker_name", "receiver_url", "secret_key"):
+        if k in data:
+            print(f"  {k}: {data.get(k)}")
+    script = data.get("script") or data.get("worker_script")
+    if script:
+        print()
+        print("Worker script:")
+        print("```javascript")
+        print(script)
+        print("```")
+
+
+def cmd_deploy(args, key, base, pid):
+    body = {}
+    if args.zone_id:
+        body["zone_id"] = args.zone_id
+    result = api_post(f"/api/projects/{pid}/integrations/cloudflare/worker/deploy", key, base,
+                      body=body or None)
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    print("Worker deployment started.")
+    for k in ("worker_name", "routes", "status"):
+        if k in data:
+            print(f"  {k}: {data.get(k)}")
+
+
+def cmd_undeploy(args, key, base, pid):
+    if not args.yes:
+        print(f"About to remove Worker route for project {pid}.")
+        print("Re-run with --yes to confirm.")
+        sys.exit(1)
+    qs = "?keep_script=true" if args.keep_script else ""
+    api_delete(f"/api/projects/{pid}/integrations/cloudflare/worker/deploy" + qs, key, base)
+    print("Worker route removed.")
+
+
+def cmd_deploy_status(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/cloudflare/worker/deploy-status", key, base)
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    deployed = data.get("deployed")
+    print("Worker deployment status")
+    print()
+    print("```")
+    print("┌────────────────────┬──────────────────────────────┐")
+    print("│ Field              │ Value                        │")
+    print("├────────────────────┼──────────────────────────────┤")
+    print(f"│ {pad('deployed', 18)} │ {pad(('Yes' if deployed else 'No'), 28)} │")
+    for k in ("worker_name", "routes", "script_name"):
+        if k in data:
+            val = data.get(k)
+            if isinstance(val, list):
+                val = ", ".join(str(v) for v in val)
+            print(f"│ {pad(k, 18)} │ {pad(truncate(val, 28), 28)} │")
+    print("└────────────────────┴──────────────────────────────┘")
+    print("```")
+
+
+def cmd_overview(args, key, base, pid):
+    params = {}
+    if args.start:
+        params["start_date"] = args.start
+    if args.end:
+        params["end_date"] = args.end
+    result = api_get(f"/api/projects/{pid}/integrations/cloudflare/worker/overview", key, base,
+                     params=params or None)
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    print("Worker AI Traffic Overview")
+    print()
+    print("```")
+    print("┌────────────────────┬──────────────┐")
+    print("│ Metric             │        Value │")
+    print("├────────────────────┼──────────────┤")
+    for k, label in [
+        ("ai_crawler_requests", "AI crawler reqs"),
+        ("ai_referral_visits", "AI referral hits"),
+        ("total_events", "Total events"),
+    ]:
+        if k in data:
+            print(f"│ {pad(label, 18)} │ {_fmt_num(data.get(k)):>12} │")
+    print("└────────────────────┴──────────────┘")
+    print("```")
+
+
+def cmd_pages(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/cloudflare/worker/pages", key, base,
+                     params={"page": args.page, "limit": args.limit})
+    data = extract_data(result)
+    items = data if isinstance(data, list) else (data or {}).get("pages", [])
+    if args.json:
+        print_json(items)
+        return
+    if not items:
+        print("No Worker page-level AI traffic yet.")
+        return
+    print(f"Worker page-level AI traffic ({len(items)})")
+    print()
+    print("```")
+    print("┌────────────────────────────────────────────┬──────────┐")
+    print("│ Page                                       │ AI Hits  │")
+    print("├────────────────────────────────────────────┼──────────┤")
+    for p in items:
+        path = truncate(p.get("page_path") or p.get("path") or p.get("url"), 42)
+        hits = _fmt_num(p.get("ai_hits") or p.get("hits") or p.get("count"))
+        print(f"│ {pad(path, 42)} │ {hits:>8} │")
+    print("└────────────────────────────────────────────┴──────────┘")
+    print("```")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Cloudflare Worker management for AI tracking")
+    parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("config")
+
+    p_d = sub.add_parser("deploy")
+    p_d.add_argument("--zone-id", help="Override zone ID (optional)")
+
+    p_u = sub.add_parser("undeploy", help="Remove route (DESTRUCTIVE)")
+    p_u.add_argument("--keep-script", action="store_true", help="Keep the script, remove only the route")
+    p_u.add_argument("--yes", action="store_true", help="Confirm")
+
+    sub.add_parser("deploy-status")
+
+    p_o = sub.add_parser("overview")
+    p_o.add_argument("--start", help="Start date YYYY-MM-DD")
+    p_o.add_argument("--end", help="End date YYYY-MM-DD")
+
+    p_p = sub.add_parser("pages")
+    p_p.add_argument("--page", type=int, default=1)
+    p_p.add_argument("--limit", type=int, default=20)
+
+    args = parser.parse_args()
+    key, base = get_api_config()
+    pid = get_project_id(args.project_id)
+
+    handlers = {
+        "config": cmd_config,
+        "deploy": cmd_deploy,
+        "undeploy": cmd_undeploy,
+        "deploy-status": cmd_deploy_status,
+        "overview": cmd_overview,
+        "pages": cmd_pages,
+    }
+    handlers[args.command](args, key, base, pid)
+
+
+if __name__ == "__main__":
+    main()

package/skills/adgine-geo-integrations/scripts/ga4_data.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Google Analytics 4: data sync + traffic/AI-referral/page/source queries.
+
+Subcommands:
+  sync                                            — pull latest GA4 data into the local DB (POST)
+  overview      [--start <YYYY-MM-DD>] [--end <>] — sessions/users/pageviews + channel split
+  ai-referrals  [--start <>] [--end <>]           — AI-platform referral detail + trends
+  pages         [--page 1] [--limit 20]           — top pages by views
+  sources       [--start <>] [--end <>]           — traffic by channel group
+
+Usage:
+  python3 scripts/ga4_data.py sync
+  python3 scripts/ga4_data.py overview --start 2025-11-01 --end 2025-11-30
+  python3 scripts/ga4_data.py ai-referrals --json
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post,
+    extract_data, print_json, truncate,
+    pad,
+)
+
+def _fmt_num(n):
+    if n is None:
+        return "--"
+    try:
+        f = float(n)
+        if f == int(f):
+            return f"{int(f):,}"
+        return f"{f:,.1f}"
+    except (TypeError, ValueError):
+        return str(n)
+
+
+def cmd_sync(args, key, base, pid):
+    result = api_post(f"/api/projects/{pid}/integrations/ga4/sync", key, base)
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    print("GA4 sync started.")
+    for k in ("status", "rows_synced", "started_at"):
+        if k in data:
+            print(f"  {k}: {data.get(k)}")
+
+
+def _date_params(args):
+    p = {}
+    if args.start:
+        p["start_date"] = args.start
+    if args.end:
+        p["end_date"] = args.end
+    return p or None
+
+
+def cmd_overview(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/ga4/overview", key, base,
+                     params=_date_params(args))
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    print("GA4 Overview")
+    print()
+    print("```")
+    print("┌────────────────────┬──────────────┐")
+    print("│ Metric             │        Value │")
+    print("├────────────────────┼──────────────┤")
+    for k, label in [
+        ("sessions", "Sessions"),
+        ("active_users", "Active users"),
+        ("pageviews", "Pageviews"),
+        ("ai_referral_sessions", "AI ref sessions"),
+    ]:
+        if k in data:
+            print(f"│ {pad(label, 18)} │ {_fmt_num(data.get(k)):>12} │")
+    print("└────────────────────┴──────────────┘")
+    print("```")
+
+
+def cmd_ai_referrals(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/ga4/ai-referrals", key, base,
+                     params=_date_params(args))
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    plats = data.get("platforms") or data.get("by_platform") or []
+    print("GA4 AI Referrals")
+    print()
+    print("```")
+    print("┌────────────────────┬──────────────┬──────────────┐")
+    print("│ Platform           │     Sessions │        Users │")
+    print("├────────────────────┼──────────────┼──────────────┤")
+    for p in plats[:10]:
+        name = truncate(p.get("name") or p.get("platform"), 18)
+        sess = _fmt_num(p.get("sessions"))
+        users = _fmt_num(p.get("users") or p.get("active_users"))
+        print(f"│ {pad(name, 18)} │ {sess:>12} │ {users:>12} │")
+    print("└────────────────────┴──────────────┴──────────────┘")
+    print("```")
+
+
+def cmd_pages(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/ga4/pages", key, base,
+                     params={"page": args.page, "limit": args.limit})
+    data = extract_data(result)
+    items = data if isinstance(data, list) else (data or {}).get("pages", [])
+    if args.json:
+        print_json(items)
+        return
+    if not items:
+        print("No page data. Run `sync` first or check the date range.")
+        return
+    print(f"GA4 Top Pages ({len(items)})")
+    print()
+    print("```")
+    print("┌────────────────────────────────────────────┬──────────┬──────────┐")
+    print("│ Page                                       │    Views │ Sessions │")
+    print("├────────────────────────────────────────────┼──────────┼──────────┤")
+    for p in items:
+        path = truncate(p.get("page_path") or p.get("path") or p.get("url"), 42)
+        views = _fmt_num(p.get("views") or p.get("page_views"))
+        sess = _fmt_num(p.get("sessions"))
+        print(f"│ {pad(path, 42)} │ {views:>8} │ {sess:>8} │")
+    print("└────────────────────────────────────────────┴──────────┴──────────┘")
+    print("```")
+
+
+def cmd_sources(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/ga4/sources", key, base,
+                     params=_date_params(args))
+    data = extract_data(result)
+    items = data if isinstance(data, list) else (data or {}).get("sources") or (data or {}).get("channels", [])
+    if args.json:
+        print_json(items)
+        return
+    if not items:
+        print("No source data available.")
+        return
+    print("GA4 Traffic Sources")
+    print()
+    print("```")
+    print("┌────────────────────┬──────────────┐")
+    print("│ Channel            │     Sessions │")
+    print("├────────────────────┼──────────────┤")
+    for s in items[:10]:
+        name = truncate(s.get("name") or s.get("channel") or s.get("source"), 18)
+        sess = _fmt_num(s.get("sessions"))
+        print(f"│ {pad(name, 18)} │ {sess:>12} │")
+    print("└────────────────────┴──────────────┘")
+    print("```")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="GA4 sync + data queries")
+    parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("sync", help="Pull latest GA4 data into local DB")
+
+    for name in ("overview", "ai-referrals", "sources"):
+        p = sub.add_parser(name)
+        p.add_argument("--start", help="Start date YYYY-MM-DD")
+        p.add_argument("--end", help="End date YYYY-MM-DD")
+
+    p_pages = sub.add_parser("pages")
+    p_pages.add_argument("--page", type=int, default=1)
+    p_pages.add_argument("--limit", type=int, default=20)
+
+    args = parser.parse_args()
+    key, base = get_api_config()
+    pid = get_project_id(args.project_id)
+
+    handlers = {
+        "sync": cmd_sync,
+        "overview": cmd_overview,
+        "ai-referrals": cmd_ai_referrals,
+        "pages": cmd_pages,
+        "sources": cmd_sources,
+    }
+    handlers[args.command](args, key, base, pid)
+
+
+if __name__ == "__main__":
+    main()

package/skills/adgine-geo-integrations/scripts/ga4_setup.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""Google Analytics 4: OAuth setup, property selection, and connection state.
+
+Subcommands:
+  auth-url                         — get the OAuth URL for the user to visit
+  connect --code <auth_code>       — manually exchange an auth code (debug)
+  properties                       — list available GA4 properties
+  select --property-id <id>        — select which GA4 property to use
+
+After `select`, a 7-day backfill sync is triggered automatically by the API.
+
+Usage:
+  python3 scripts/ga4_setup.py auth-url
+  python3 scripts/ga4_setup.py properties
+  python3 scripts/ga4_setup.py select --property-id 123456789
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post,
+    extract_data, print_json, truncate,
+    pad,
+)
+
+def cmd_auth_url(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/ga4/auth-url", key, base)
+    data = extract_data(result) or {}
+    if args.json:
+        print_json(data)
+        return
+    url = data.get("url") or data.get("auth_url")
+    print("GA4 OAuth — open this URL in a browser:")
+    print(url or "(no URL returned)")
+
+
+def cmd_connect(args, key, base, pid):
+    result = api_post(
+        f"/api/projects/{pid}/integrations/ga4/connect",
+        key, base, body={"code": args.code},
+    )
+    data = extract_data(result)
+    if args.json:
+        print_json(data if data is not None else {"ok": True})
+        return
+    print("GA4 connected.")
+
+
+def cmd_properties(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/integrations/ga4/properties", key, base)
+    data = extract_data(result)
+    items = data if isinstance(data, list) else (data or {}).get("properties", [])
+    if args.json:
+        print_json(items)
+        return
+    if not items:
+        print("No GA4 properties accessible with the current token.")
+        return
+    print(f"GA4 properties ({len(items)})")
+    print()
+    print("```")
+    print("┌──────────────────────┬────────────────────────────┬────────────────────┐")
+    print("│ Property ID          │ Display name               │ Web stream domain  │")
+    print("├──────────────────────┼────────────────────────────┼────────────────────┤")
+    for p in items:
+        pid_ = truncate(p.get("id") or p.get("property_id"), 20)
+        name = truncate(p.get("display_name") or p.get("name"), 26)
+        domain = truncate(p.get("domain") or p.get("web_domain") or "--", 18)
+        print(f"│ {pad(pid_, 20)} │ {pad(name, 26)} │ {pad(domain, 18)} │")
+    print("└──────────────────────┴────────────────────────────┴────────────────────┘")
+    print("```")
+
+
+def cmd_select(args, key, base, pid):
+    result = api_post(
+        f"/api/projects/{pid}/integrations/ga4/select-property",
+        key, base, body={"property_id": args.property_id},
+    )
+    data = extract_data(result)
+    if args.json:
+        print_json(data if data is not None else {"ok": True})
+        return
+    print(f"Selected GA4 property: {args.property_id}")
+    print("(API will trigger a 7-day backfill sync in the background.)")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="GA4 OAuth setup & property selection")
+    parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("auth-url", help="Get the OAuth URL")
+
+    p_c = sub.add_parser("connect", help="Manual auth-code exchange (debug)")
+    p_c.add_argument("--code", required=True, help="Google OAuth authorization code")
+
+    sub.add_parser("properties", help="List available GA4 properties")
+
+    p_s = sub.add_parser("select", help="Choose which GA4 property to bind")
+    p_s.add_argument("--property-id", required=True)
+
+    args = parser.parse_args()
+    key, base = get_api_config()
+    pid = get_project_id(args.project_id)
+
+    handlers = {
+        "auth-url": cmd_auth_url,
+        "connect": cmd_connect,
+        "properties": cmd_properties,
+        "select": cmd_select,
+    }
+    handlers[args.command](args, key, base, pid)
+
+
+if __name__ == "__main__":
+    main()

package/skills/adgine-geo-opportunities/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: adgine/geo-opportunities
+description: Discovers and displays GEO optimization opportunities for a project.
+  Shows AI-identified content gaps, topic opportunities, and actionable recommendations
+  ranked by potential impact (relevance, traffic, competition, urgency, AI citation).
+  Use when the user wants to find new content ideas, discover optimization opportunities,
+  see what topics they should target, or get prioritized recommendations for improving
+  their AI visibility. 触发词：查看机会、分析机会、优化机会、发现机会、网站机会、
+  项目机会、机会列表、opportunity discovery、content gaps。
+---
+
+# GEO Opportunity Discovery
+
+## Output rules — IDs (apply to every reply)
+
+These rules apply to **every list, table, and confirmation message** in this skill. Their goal: keep user-facing output friendly while preserving the IDs the agent needs internally.
+
+1. **Lists & tables — never show raw UUIDs in cells.** Use a 1-based `#` index column instead. Keep a private mental mapping of `#N → actual UUID` so that follow-up commands like *"show details of #3"*, *"tell me more about the 2nd one"* resolve to the right entity.
+   - Index numbers restart from 1 in each new list — they are not stable across calls.
+   - If the user references *"the opportunity about X"*, match by visible content (title / category), not by ID.
+
+2. **Single-item operations — prefer a human name over an ID.**
+   - ✅ *"Opportunity **Optimize product comparison pages** — score 85/100."*
+   - ❌ *"Opportunity `a4305b57-1c79-4cec-a17c-16eb1d959ea6` — score 85."*
+   - If the entity has **no human-readable name**, use a short 8-character prefix: `2a2a8f4f…`
+
+3. **Always exception: `--json` mode.** When the user passes `--json` to a script or explicitly asks for raw JSON / debug output, print the script output verbatim — do not strip IDs.
+
+4. **Internally, the agent still uses full UUIDs** for every API call (`--project-id`, `--opportunity-id`, etc.). The display rules only affect what is shown back to the user.
+
+---
+
+## Step 1: Make sure GEO_API_KEY is configured
+
+Scripts auto-load `GEO_API_KEY` from `<skills-root>/.env` on import — **no `export` needed, no shell restart needed**. To check the configuration, run any script (it prints the exact `.env` path if the key is missing).
+
+- ✅ Key already in `<skills-root>/.env` → proceed.
+- ❌ Key missing, or user just gave you a new key → go to the **adgine-geo-projects** skill, **Step 0**, which runs `python3 <skills-root>/setup.py <KEY>` to write the key into the correct `.env` file. **Never** write the key to `~/.zshrc`, `~/.bashrc`, Hermes global config, or any user-secrets store.
+
+> ⚠️ **IMPORTANT:** In all shell/exec commands, always reference the key as `$GEO_API_KEY` (the environment variable). Never hardcode the key value or use placeholder strings like `API_KEY=***` or `API_KEY=geo_sk_live_xxx` directly in a command — this will cause authentication failures.
+
+
+## Project selection
+
+```bash
+export GEO_PROJECT_ID=<project-id>   # session shortcut — resets when terminal closes
+# Run python3 scripts/list_projects.py from adgine-geo-projects skill to find your IDs
+```
+
+## What are opportunities?
+
+Opportunities are AI-identified content gaps and optimization recommendations for your project. The system analyzes your current visibility, topics, competitors, and AI citation data to surface high-impact actions you can take to improve GEO performance.
+
+Each opportunity includes:
+- **Title** — a concise description of the opportunity
+- **Total Score** — composite impact score (higher = more impactful)
+- **Scores** — radar chart dimensions: relevance, traffic, competition, urgency, ai_citation
+- **Category** — type of opportunity (e.g., content gap, optimization, new topic)
+- **Rationale** — why this opportunity matters
+- **Guidance** — strategic direction
+- **Implementation** — concrete step-by-step actions
+- **Coverage** — current coverage data
+- **Source URLs** — reference links supporting the recommendation
+
+---
+
+## Commands
+
+### List project opportunities
+```bash
+python3 scripts/list_opportunities.py [--project-id <id>] [--json]
+```
+Returns the latest batch of opportunities for the project. Three possible states:
+- **ready** — opportunities are available, displays ranked list
+- **pending** — opportunities are currently being generated; check back in a few minutes
+- **empty** — no opportunities yet; this is normal for new projects. Opportunity discovery requires approximately **1 week** of the website running in the platform before the first analysis cycle produces results. Relay this context to the user so they understand *why* there is nothing to show, and encourage them to check back after the weekly cycle.
+
+### Get opportunity detail
+```bash
+python3 scripts/get_opportunity.py --opportunity-id <id> [--project-id <id>] [--json]
+```
+Shows the full detail of a single opportunity including:
+- Title & total score
+- Score breakdown (radar dimensions)
+- Category & rationale
+- Guidance
+- Implementation steps (numbered action items)
+- Coverage details
+- Source URLs
+
+---
+
+## Workflow
+
+1. List opportunities: `python3 scripts/list_opportunities.py`
+2. Review the ranked list — higher scores = higher potential impact
+3. Drill into specific opportunities: `python3 scripts/get_opportunity.py --opportunity-id <id>`
+4. Follow the implementation steps to act on the opportunity
+5. Use other skills to execute (e.g., `adgine-geo-content` for article generation, `adgine-geo-topics` for new topics)
+
+---
+
+## Output Format
+
+> ⚠️ **CRITICAL — Table cell content rule (must follow exactly):**
+> Tables use fenced code blocks with box-drawing borders. They only align correctly when **every cell contains ASCII characters exclusively**.
+> - **NEVER** put emoji inside table cells.
+> - Emoji go ONLY on the label line **above** the ` ``` ` fence.
+> - Status values in cells: `Ready` / `Pending` / `Empty`
+> - Use `[label](url)` for clickable URLs (outside fenced blocks).
+
+---
+
+### When listing opportunities (`list_opportunities.py`)
+
+> 🔍 **Opportunities** — *N items found* (run date: YYYY-MM-DD)
+
+```
+┌────┬────────────────────────────────────┬───────┬──────────────┐
+│  # │ Title                              │ Score │ Category     │
+├────┼────────────────────────────────────┼───────┼──────────────┤
+│  1 │ Optimize product comparison pages  │    85 │ content_gap  │
+│  2 │ Add FAQ schema to landing pages    │    72 │ optimization │
+│  3 │ Target "best X alternatives" topic │    68 │ new_topic    │
+└────┴────────────────────────────────────┴───────┴──────────────┘
+```
+
+> 💡 Use `get_opportunity.py --opportunity-id <id>` for full details on any item.
+
+---
+
+### When showing opportunity detail (`get_opportunity.py`)
+
+> 🎯 **Opportunity Detail**
+> Title: *"<title>"*
+> Score: **N/100**
+
+📊 Score Breakdown
+```
+┌──────────────┬───────┐
+│ Dimension    │ Score │
+├──────────────┼───────┤
+│ Relevance    │    18 │
+│ Traffic      │    16 │
+│ Competition  │    17 │
+│ Urgency      │    15 │
+│ AI Citation  │    19 │
+└──────────────┴───────┘
+```
+
+**Category:** content_gap
+**Rationale:** "<rationale text>"
+**Guidance:** "<guidance text>"
+
+📋 Implementation Steps:
+1. Step one description
+2. Step two description
+3. Step three description
+
+🔗 Source URLs:
+- [source1.com/page](https://source1.com/page)
+- [source2.com/article](https://source2.com/article)