@adgine/geo-cli 1.2.8

package/skills/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: adgine/geo
+description: >
+  Adgine GEO 平台完整技能套件，包含 18 个专项技能，覆盖生成式引擎优化（GEO）全流程：
+  网站技术审计、AI 引用测试、AI 可见性分析、内容生成、品牌画像、主题词管理、
+  WordPress 发布、GA4/Cloudflare 集成、域名管理、项目管理、账单查询、使用手册等。
+  触发词：GEO / Adgine / AI visibility / AI citation / 生成式引擎优化 / AI 可见性 /
+  引用测试 / 内容生成 / 网站审计 / 品牌画像 / WordPress 发布 / 流量分析 /
+  AI 爬虫追踪 / 优化机会 / 页面健康度 / 域名 / 账单 / 积分 / 项目管理.
+version: "1.2.4"
+---
+
+## 版本检测（路由到任何子技能之前的第一步，必须执行）
+
+在将用户请求路由到任何子技能之前，**先单独运行**版本检测（必须是本轮第一个 bash 命令）：
+
+```bash
+python3 <skills-root>/scripts/check_version.py --human
+```
+
+`<skills-root>` 是本仓库根目录（含 `VERSION`、`setup.py` 及所有 `adgine-geo-*` 文件夹）。
+
+**WorkBuddy 特别注意：** WorkBuddy 会改写业务脚本的终端输出，可能丢掉嵌入的 `_notice` 或页脚。
+因此 **必须** 用上面的 `--human` 命令做独立检测；若输出不为空，**在用户回复的最后一段原文包含该句**，禁止只展示业务结果而省略版本信息。
+
+处理规则：
+- 脚本失败 / 超时 / 输出为空：静默忽略，继续路由和响应
+- `update_available=false`（`--human` 无输出）：不输出任何版本相关内容
+- 有更新（`--human` 有输出）或 JSON 模式 `update_available=true`：完成用户当前请求后，在回复末尾追加更新提示（见下方模板）。同一轮对话只提示一次。
+
+## 版本更新提示（脚本自动 + 必须处理）
+
+本套件的**每个脚本**在运行时也会自动做版本检查（对比 GitHub 上的
+`VERSION`）。如果有新版本，脚本会在**工具输出（stdout）第一行**打印
+`_notice`，格式为：
+
+```
+_notice: {"update": {"current": "1.1.5", "latest": "1.2.0", "message": "..."}}
+```
+
+**处理规则（每次对话都适用）：**
+- 主动版本检测 **或** 任何一次工具调用的输出里出现 `_notice`，且判定有更新
+  → 先正常完成用户当前请求，然后在回复末尾追加一条更新提示（见下方模板）。
+  同一轮对话只提示一次。
+- 脚本还会在输出**末尾**打印人类可读页脚（以 `---` 和 `⚠️ adgine-geo-skills` 开头）。
+  **WorkBuddy 等会改写工具输出的 Agent 也必须把这段页脚原样展示给用户**，不得省略。
+- 两条途径均未检测到更新 → 不输出任何版本相关内容。
+
+**更新提示模板（`message` 里含「Tell me:」= git 安装）：**
+
+> 💡 **adgine-geo-skills 有新版本 {latest}**（当前 {current}）
+> 发给我下面这句话，我来帮你一键更新：
+> `请帮我更新 adgine-geo-skills 到最新版本`
+
+**更新提示模板（`message` 里含「Download:」= 打包安装）：**
+
+> 💡 **adgine-geo-skills 有新版本 {latest}**（当前 {current}）
+> 请前往 {下载地址} 下载最新版本，在平台 Skill 管理界面重新安装。
+
+## 更新处理（当用户说"请帮我更新 adgine-geo-skills"时触发）
+
+运行 `python3 <SKILL_DIR>/scripts/check_version.py` 拿到 `update_command`，
+然后执行它（git 安装形如 `git -C <repo_root> pull`）。
+成功后回复：「✅ 已更新到最新版本 {latest}，重新开始对话即可使用新版功能。」
+失败则输出错误信息供用户排查。
+
+---
+
+# Adgine GEO Skills Suite
+
+本套件包含 18 个专项技能，覆盖 Adgine GEO 平台全流程。根据用户意图路由到对应子技能。
+
+## 子技能路由表
+
+| 子技能 | 用于 |
+|---|---|
+| adgine/geo-projects | 创建/列出/切换项目、管理竞争对手、配置 API Key（`GEO_API_KEY`）、验证鉴权 |
+| adgine/geo-dashboard | 项目总览快照、7 天趋势、集成连接状态（首页指标 / Dashboard 概览） |
+| adgine/geo-analytics | GA4 流量概览、活跃用户、AI 引荐汇总（不含爬虫明细） |
+| adgine/geo-aiagent | AI 爬虫深度追踪：GPTBot / ClaudeBot / PerplexityBot、Sankey 流图、原始日志、页面级下钻 |
+| adgine/geo-visibility | 读取 AI 可见性得分、Share of Voice、平均排名、竞品矩阵、历史 AI 回答 |
+| adgine/geo-citation | 向 ChatGPT / Perplexity / Google AIO / Gemini 提交真实提示，测量品牌引用率 |
+| adgine/geo-brand | 查看/生成/编辑 AI 品牌画像（ICP / 竞品分析 / 语气风格 / 写作规范）及生成任务管理 |
+| adgine/geo-topics | 创建主题、批量生成 AI 搜索提示词、管理主题-提示词结构 |
+| adgine/geo-content | 生成文章大纲和完整 GEO 文章、管理内容库、查看/重试内容生成任务 |
+| adgine/geo-performance | 单页面 AI 优化健康度：可爬取性、AI 优化评分、内容健康（移动/桌面） |
+| adgine/geo-opportunities | 发现 AI 识别的内容缺口和优化机会，按影响力（相关性/流量/竞争度/紧迫性）排序 |
+| adgine/geo-integrations | 连接 GA4（OAuth）和 Cloudflare、部署 AI 爬虫追踪 Worker、触发数据同步 |
+| adgine/geo-wordpress | 发布 GEO 文章到 WordPress、管理站点凭证和分类、查看发布历史、更新已发布文章 |
+| adgine/geo-saas | 检查子域名可用性、创建并追踪 SaaS 托管网站部署任务 |
+| adgine/geo-billing | 查询订阅套餐、订阅状态、积分余额和充值明细（只读，不执行购买） |
+| adgine/geo-domains | 按关键词搜索可注册域名、列出已注册域名、查看域名详情 |
+| adgine/geo-site-audit | 对任意公开 URL 做独立 GEO 技术审计（5 大维度 / 30 项检测 / 导出 PDF），**无需 API Key** |
+| adgine/geo-docs | Adgine 平台使用手册、帮助文档、操作指南，**无需 API Key** |
+
+## 工作流说明
+
+部分功能需要多个子技能协作：
+
+- **内容发布**：`geo-content`（生成文章）→ `geo-wordpress`（发布到 WordPress）
+- **引用测试**：`geo-topics`（创建提示词）→ `geo-citation`（运行测试）→ `geo-visibility`（查看结果）
+- **所有平台功能**：先用 `geo-projects` 配置 API Key 并选定项目，再使用其他子技能
+
+## 安装配置
+
+git clone 后运行一次：
+
+```bash
+python3 setup.py <YOUR_GEO_API_KEY>
+```
+
+或交互式：`python3 setup.py`
+
+## 更多信息
+
+- 平台官网：[adgine.ai](https://adgine.ai/)
+- GitHub：https://github.com/adgine-ai/adgine-geo-skills

package/skills/VERSION

@@ -0,0 +1 @@
+1.2.8

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

@@ -0,0 +1,200 @@
+---
+name: adgine/geo-aiagent
+description: Deep drill-down tracking for AI bot crawls and AI-driven human traffic
+  — 27 endpoints covering per-bot/per-platform/per-UA breakdowns, Sankey flows,
+  raw event logs, and per-page deep dives (KPI / logs / platforms / PageSpeed).
+  Use when the user wants detail-level data: AI 爬虫追踪 / which specific AI bots
+  crawl my site / GPTBot ClaudeBot PerplexityBot / 某个页面被哪些 AI 爬虫访问过 /
+  page detail / page sankey / Core Web Vitals / AI 真人访问来源明细.
+  NOT for high-level traffic summary — use adgine-geo-analytics for that.
+  NOT for running citation tests — use adgine-geo-citation.
+  NOT for page AI-optimization health scores — use adgine-geo-performance.
+  For brand/topic visibility metrics use adgine-geo-visibility.
+---
+
+# GEO AI-Agent Tracking
+
+The biggest analytics skill — 27 endpoints under `/api/projects/{id}/ai-agent/*`.
+Grouped into 4 scripts by user intent:
+
+- **bot_traffic.py** — which AI bots crawl my site, how often, what kind
+- **human_traffic.py** — what real human traffic AI platforms send me
+- **page_analytics.py** — site-wide page rankings, Sankey flow, logs
+- **page_detail.py** — deep-dive analytics for a specific page path
+
+## 触发条件
+
+当用户说出以下意图时使用本 skill：
+- “哪些 AI 爬虫访问了我的网站” / “GPTBot/ClaudeBot/PerplexityBot” / “AI bot tracking”
+- “某个页面被哪些 AI 爬虫访问过” / “页面爬虫日志” / “page detail”
+- “AI 真人访问” / “AI 引荐来源明细” / “AI referral breakdown”
+- “Sankey 图” / “页面流量流向” / “爬虫访问日志”
+
+**⛔ 以下意图不属于本 skill：**
+- “流量概览” / “流量汇总”（不涉及具体 bot 明细）→ **adgine-geo-analytics**
+- “某个页面的 AI 优化健康度” / “页面可爬取性” → **adgine-geo-performance**
+- “运行引用测试” / “品牌被引用了吗” → **adgine-geo-citation**
+- “可见性得分” / “声量份额” → **adgine-geo-visibility**
+
+## 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 *"delete #3"*, *"run citation test on #1 #2"*, *"show details of 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 topic about X"* / *"that Poki vs CrazyGames prompt"*, match by visible content (name / title / domain / prompt text), not by ID.
+
+2. **Single-item operations — prefer a human name over an ID.**
+   - ✅ *"Project **Poki vs Competitors** deleted."*
+   - ✅ *"Topic **Brand mentions in 2024** updated — name → 'Brand mentions 2025'."*
+   - ❌ *"Project `a4305b57-1c79-4cec-a17c-16eb1d959ea6` deleted."*
+   - If the entity has **no human-readable name** (e.g. an anonymous prompt or a job), use a short 8-character prefix: *"Prompt `2a2a8f4f…` deleted."* Never paste the full UUID.
+
+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`, `--topic-id`, `--prompt-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 literal value.
+
+## Project selection
+
+```bash
+export GEO_PROJECT_ID=<project-id>
+```
+
+## Scripts
+
+### bot_traffic.py — AI bot/crawler tracking
+
+```bash
+python3 scripts/bot_traffic.py overview          # 5 KPI: citation/training/index/agent/total
+python3 scripts/bot_traffic.py platforms         # ranking: which AI platforms crawl most
+python3 scripts/bot_traffic.py by-platform       # bots grouped by AI platform
+python3 scripts/bot_traffic.py types             # index/training/assistant/agent split
+python3 scripts/bot_traffic.py useragents        # by specific UA (GPTBot, ClaudeBot...)
+python3 scripts/bot_traffic.py pages-by-bot      # per-bot top pages
+```
+
+### human_traffic.py — humans driven by AI platforms
+
+```bash
+python3 scripts/human_traffic.py overview        # 3 KPI: UTM / referral / share
+python3 scripts/human_traffic.py platforms       # human visits by AI platform
+python3 scripts/human_traffic.py pages           # human visits per page
+python3 scripts/human_traffic.py platform-flow   # Sankey: AI platform → landing page
+python3 scripts/human_traffic.py referral        # referral-only by source
+
+# GA4-backed (requires GA4 connected):
+python3 scripts/human_traffic.py ga-overview
+python3 scripts/human_traffic.py ga-platforms
+python3 scripts/human_traffic.py ga-landing-pages
+python3 scripts/human_traffic.py ga-landing-flow
+```
+
+### page_analytics.py — site-wide
+
+```bash
+python3 scripts/page_analytics.py overview-kpi             # citation/index/training/agent/referral
+python3 scripts/page_analytics.py pages                    # top AI-referenced pages
+python3 scripts/page_analytics.py pages-detail             # 5-metric table per page
+python3 scripts/page_analytics.py pages-export --format csv > pages.csv
+python3 scripts/page_analytics.py platform-flow            # Sankey
+python3 scripts/page_analytics.py logs                     # raw AI event logs
+```
+
+### page_detail.py — specific page path
+
+All commands require `--path /your/page/path`.
+
+```bash
+python3 scripts/page_detail.py kpi       --path /blog/article
+python3 scripts/page_detail.py logs      --path /blog/article --limit 20
+python3 scripts/page_detail.py platforms --path /blog/article
+python3 scripts/page_detail.py related   --path /blog/article
+python3 scripts/page_detail.py health    --path /blog/article
+python3 scripts/page_detail.py health-refresh --path /blog/article   # 15–60s blocking
+```
+
+## Metric vocabulary
+
+| Code           | Meaning |
+|---|---|
+| `ai_citation`  | AI quoted / cited this page in an answer |
+| `ai_index`     | AI search index crawler hit |
+| `ai_training`  | AI training data crawler hit |
+| `ai_agent`     | AI agent (assistant tool-use) hit |
+| `ai_referral`  | A real human arrived on the site via an AI platform |
+| `total_bots`   | Sum of all AI bot requests |
+
+## Platform codes
+
+`openai` · `google_aio` · `perplexity` · `gemini` · `anthropic` · `meta`
+(see `/api/projects/{id}/ai-agent/platforms` for the live list).
+
+## Output Format
+
+ASCII tables only inside fenced code blocks. Numeric formatting: integer
+counts with thousands separator; "%" suffix only on percentage metrics;
+"--" for null. Change-from-previous-period shown with explicit sign.
+
+## Related endpoints
+
+| Method | Path |
+|---|---|
+| GET    | `/api/projects/{id}/ai-agent/bot-platforms` |
+| GET    | `/api/projects/{id}/ai-agent/bot-traffic-overview` |
+| GET    | `/api/projects/{id}/ai-agent/bot-types` |
+| GET    | `/api/projects/{id}/ai-agent/bot-useragents` |
+| GET    | `/api/projects/{id}/ai-agent/ga-landing-pages` |
+| GET    | `/api/projects/{id}/ai-agent/ga-overview` |
+| GET    | `/api/projects/{id}/ai-agent/ga-platform-landing-flow` |
+| GET    | `/api/projects/{id}/ai-agent/ga-platforms` |
+| GET    | `/api/projects/{id}/ai-agent/human-pages` |
+| GET    | `/api/projects/{id}/ai-agent/human-platform-flow` |
+| GET    | `/api/projects/{id}/ai-agent/human-platforms` |
+| GET    | `/api/projects/{id}/ai-agent/human-traffic-overview` |
+| GET    | `/api/projects/{id}/ai-agent/logs` |
+| GET    | `/api/projects/{id}/ai-agent/overview-kpi` |
+| GET    | `/api/projects/{id}/ai-agent/pages` |
+| GET    | `/api/projects/{id}/ai-agent/pages-by-bot` |
+| GET    | `/api/projects/{id}/ai-agent/pages-detail` |
+| GET    | `/api/projects/{id}/ai-agent/pages-detail/export` |
+| GET    | `/api/projects/{id}/ai-agent/pages-platform-flow` |
+| GET    | `/api/projects/{id}/ai-agent/pages/by-path/health` |
+| POST   | `/api/projects/{id}/ai-agent/pages/by-path/health/refresh` |
+| GET    | `/api/projects/{id}/ai-agent/pages/by-path/kpi` |
+| GET    | `/api/projects/{id}/ai-agent/pages/by-path/logs` |
+| GET    | `/api/projects/{id}/ai-agent/pages/by-path/platforms` |
+| GET    | `/api/projects/{id}/ai-agent/pages/by-path/related` |
+| GET    | `/api/projects/{id}/ai-agent/platforms` |
+| GET    | `/api/projects/{id}/ai-agent/referral-traffic` |
+
+---
+
+## Post-task recommendations
+
+After AI traffic analysis, suggest next analytical or action steps:
+
+| What you analyzed | → use skill (agent-internal) |
+|---|---|
+| Bot traffic overview | 深入查看具体 bot 详情或 page detail *(→ adgine-geo-aiagent)*|
+| Specific page traffic | 检查该页面的 AI 优化健康度 *(→ adgine-geo-performance)*|
+| Human referral traffic | 查看 GA4 流量总览 *(→ adgine-geo-analytics)*|
+| Sankey / platform flow | 针对高流量入口页生成优化内容 *(→ adgine-geo-content)*|
+| PageSpeed / Core Web Vitals | 对整个网站做全面 GEO 审计 *(→ adgine-geo-site-audit)*|
+| Low AI bot activity | 检查 Cloudflare Worker 是否正常部署 *(→ adgine-geo-integrations)*|
+
+**⚠️ Output rule:** Do NOT write skill names (e.g. `adgine-geo-xxx`) in user-facing suggestions. Each suggestion must be phrased as a natural-language prompt the user can copy and send directly to the agent.
+
+> 💡 **建议下一步：**
+> 1. **[行动标题]** — *"[可直接发送给 AI 的自然语言提示词]"*
+> 2. **[行动标题]** — *"[可直接发送给 AI 的自然语言提示词]"*

package/skills/adgine-geo-aiagent/scripts/_client.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+"""Shared HTTP client utilities for geo-skills scripts.
+
+Used by all scripts in this skill. Uses Python stdlib only — no external dependencies.
+
+This file is the canonical source. It must be copied verbatim into every
+adgine-geo-* skill folder's scripts/ directory. The sync linter at
+scripts/sync-skills/sync-skills.sh (in the GEOAgent repo) flags any drift.
+"""
+import os
+import sys
+import json
+import time
+import atexit
+import unicodedata
+import urllib.request as _req
+import urllib.error as _uerr
+import urllib.parse as _up
+
+def _load_dot_env():
+    """Load .env from the repo root (adgine-geo-skills/) into os.environ.
+
+    Resolved relative to this file's location, so it works regardless of the
+    agent's working directory (e.g. Hermes, OpenClaw, or any other runtime).
+    Existing environment variables are never overwritten.
+    """
+    if os.environ.get("GEO_API_KEY"):
+        return
+    # _client.py is at <repo_root>/adgine-geo-<skill>/scripts/_client.py
+    repo_root = os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    )
+    env_path = os.path.join(repo_root, ".env")
+    if not os.path.isfile(env_path):
+        return
+    with open(env_path) as _f:
+        for _line in _f:
+            _line = _line.strip()
+            if not _line or _line.startswith("#") or "=" not in _line:
+                continue
+            _k, _, _v = _line.partition("=")
+            _k = _k.strip()
+            _v = _v.strip()
+            if _k and _k not in os.environ:
+                os.environ[_k] = _v
+
+
+_load_dot_env()
+
+_VERSION_UNCHECKED = object()
+_version_state = _VERSION_UNCHECKED
+
+
+def _repo_root():
+    return os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    )
+
+
+def _load_check_version_module():
+    import importlib.util
+    path = os.path.join(_repo_root(), "scripts", "check_version.py")
+    if not os.path.isfile(path):
+        return None
+    spec = importlib.util.spec_from_file_location("geo_check_version", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _load_version_state():
+    global _version_state
+    if _version_state is not _VERSION_UNCHECKED:
+        return _version_state
+    _version_state = None
+    try:
+        mod = _load_check_version_module()
+        if mod is not None:
+            _version_state = mod.get_state()
+    except Exception:
+        pass
+    return _version_state
+
+
+def _print_version_notice():
+    """Emit machine + human hints at import if a newer version exists."""
+    state = _load_version_state()
+    if not state or not state.get("update_available"):
+        return
+    cur, lat = state["current"], state["latest"]
+    try:
+        mod = _load_check_version_module()
+        if mod is not None:
+            inline = mod.format_user_inline(state)
+            if inline:
+                sys.stdout.write(inline + "\n\n")
+                sys.stdout.flush()
+    except Exception:
+        pass
+    if state.get("install_type") == "git":
+        msg = (f"adgine-geo-skills {lat} available (current {cur}). "
+               "Tell me: 请帮我更新 adgine-geo-skills 到最新版本")
+    else:
+        msg = (f"adgine-geo-skills {lat} available (current {cur}). "
+               f"Download: {state.get('release_url', '')}")
+    notice = {"update": {"current": cur, "latest": lat, "message": msg}}
+    try:
+        line = f"_notice: {json.dumps(notice, ensure_ascii=False)}\n\n"
+        sys.stdout.write(line)
+        sys.stdout.flush()
+    except Exception:
+        pass
+
+
+def _print_version_footer():
+    """Emit human-readable footer at process exit (WorkBuddy-compatible)."""
+    state = _load_version_state()
+    if not state or not state.get("update_available"):
+        return
+    try:
+        mod = _load_check_version_module()
+        if mod is None:
+            return
+        footer = mod.format_user_footer(state)
+        if footer:
+            sys.stdout.write("\n" + footer + "\n")
+            sys.stdout.flush()
+    except Exception:
+        pass
+
+
+_print_version_notice()
+atexit.register(_print_version_footer)
+
+
+def get_api_config():
+    """Read GEO_API_KEY and GEO_API_BASE_URL from environment.
+
+    Exits with a helpful message if GEO_API_KEY is not set.
+    Returns (key, base_url).
+    """
+    key = os.environ.get("GEO_API_KEY", "")
+    base = os.environ.get("GEO_API_BASE_URL", "https://platform.adgine.ai").rstrip("/")
+    if not key:
+        repo_root = os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+        env_path = os.path.join(repo_root, ".env")
+        example_path = os.path.join(repo_root, ".env.example")
+        setup_path = os.path.join(repo_root, "setup.py")
+        print("ERROR: GEO_API_KEY is not set.")
+        print(f"  Expected location: {env_path}")
+        print()
+        print("  One-shot fix (recommended):")
+        print(f"    python3 {setup_path} <YOUR_KEY>")
+        print()
+        print("  Or set it manually:")
+        if not os.path.isfile(env_path):
+            print(f"    cp {example_path} {env_path}")
+        print(f"    edit {env_path} and set GEO_API_KEY=geo_sk_live_xxx")
+        print()
+        print("  Get your key at: https://platform.adgine.ai")
+        print("  The .env file is gitignored — your key stays local and private.")
+        print()
+        print("  NOTE: adgine-geo-site-audit does NOT require an API key.")
+        print("    Run directly: python3 adgine-geo-site-audit/scripts/geo_collect.py <url>")
+        sys.exit(1)
+    return key, base
+
+
+def get_project_id(arg_value=None):
+    """Resolve project ID from argument or GEO_PROJECT_ID env var.
+
+    Exits with instructions if neither is set.
+    """
+    pid = arg_value or os.environ.get("GEO_PROJECT_ID", "")
+    if not pid:
+        print("ERROR: Project ID is required but not set.")
+        print("  Option 1: export GEO_PROJECT_ID=<project-id>")
+        print("  Option 2: pass --project-id <id> to this script")
+        print("  Run list_projects.py from the adgine-geo-projects skill to see your available projects.")
+        sys.exit(1)
+    return pid
+
+
+def _do_request(method, url, key, body=None, timeout=30):
+    """Execute an HTTP request and return parsed JSON.
+
+    Exits with an error message on HTTP errors or network failures.
+    """
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    headers = {
+        "Authorization": f"Bearer {key}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": "geo-skills/1.0",
+    }
+    request = _req.Request(url, data=data, headers=headers, method=method)
+    try:
+        with _req.urlopen(request, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+            return json.loads(raw) if raw else {}
+    except _uerr.HTTPError as e:
+        raw = e.read().decode("utf-8")[:400]
+        try:
+            err_data = json.loads(raw)
+            msg = err_data.get("message") or err_data.get("detail") or raw
+        except Exception:
+            msg = raw
+        if e.code == 401:
+            print("ERROR: Unauthorized — API key is invalid or revoked.")
+            print("  Generate a new key: https://platform.adgine.ai")
+        elif e.code == 403:
+            print("ERROR: Forbidden — insufficient permissions for this operation.")
+        elif e.code == 404:
+            print(f"ERROR: Not found — {msg}")
+        else:
+            print(f"ERROR: HTTP {e.code} — {msg}")
+        sys.exit(1)
+    except Exception as e:
+        print(f"ERROR: Request failed — {e}")
+        sys.exit(1)
+
+
+def api_get(path, key, base, params=None, timeout=30):
+    url = f"{base}{path}"
+    if params:
+        clean = {k: str(v) for k, v in params.items() if v is not None}
+        if clean:
+            url += "?" + _up.urlencode(clean)
+    return _do_request("GET", url, key, timeout=timeout)
+
+
+def api_post(path, key, base, body=None, timeout=30):
+    return _do_request("POST", f"{base}{path}", key, body, timeout=timeout)
+
+
+def api_patch(path, key, base, body=None, timeout=30):
+    return _do_request("PATCH", f"{base}{path}", key, body, timeout=timeout)
+
+
+def api_put(path, key, base, body=None, timeout=30):
+    return _do_request("PUT", f"{base}{path}", key, body, timeout=timeout)
+
+
+def api_delete(path, key, base, timeout=30):
+    return _do_request("DELETE", f"{base}{path}", key, timeout=timeout)
+
+
+def extract_data(result):
+    """Extract the .data field from a standard geo-api envelope response.
+
+    On success the API returns {"code": 0, "data": <payload>, "message": "ok"}.
+    On non-zero code, this prints the message and exits(1).
+    """
+    if not isinstance(result, dict):
+        return result
+    if "code" in result and result.get("code") not in (0, None):
+        msg = result.get("message") or result.get("detail") or "request failed"
+        print(f"ERROR: API returned code={result.get('code')} — {msg}")
+        sys.exit(1)
+    return result.get("data", result)
+
+
+def poll_job(status_path, key, base, interval=3, max_wait=300,
+             terminal=("completed", "failed", "done", "success", "error")):
+    """Poll a job/task endpoint until it reaches a terminal state.
+
+    Prints an inline spinner with the current phase. Returns the final job dict.
+    """
+    elapsed = 0
+    frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+    idx = 0
+    last_job = {}
+    while elapsed < max_wait:
+        result = api_get(status_path, key, base)
+        last_job = extract_data(result) or {}
+        status = (last_job.get("status") or "").lower()
+        phase = last_job.get("current_phase") or last_job.get("phase") or status or "pending"
+        print(f"\r  {frames[idx % len(frames)]} {phase}... ({elapsed}s)", end="", flush=True)
+        idx += 1
+        if status in terminal:
+            print()  # newline after spinner
+            return last_job
+        time.sleep(interval)
+        elapsed += interval
+    print()
+    print(f"WARNING: Job is still running after {max_wait}s. Check status manually.")
+    return last_job
+
+
+def print_json(data):
+    """Print data as formatted JSON (UTF-8 safe)."""
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def fmt_change(value):
+    """Format a numeric change indicator per CONVENTIONS.md §4.
+
+    Returns: '+N' / '-N' / '0' / '--' (None becomes '--').
+    """
+    if value is None:
+        return "--"
+    try:
+        n = float(value)
+    except (TypeError, ValueError):
+        return "--"
+    if n == 0:
+        return "0"
+    sign = "+" if n > 0 else ""
+    if n == int(n):
+        return f"{sign}{int(n):,}"
+    return f"{sign}{n:,.1f}"
+
+
+def truncate(text, n=60, ellipsis="…"):
+    """Truncate text to n characters, adding ellipsis if cut. ASCII-safe for tables."""
+    if text is None:
+        return "--"
+    s = str(text)
+    if len(s) <= n:
+        return s
+    return s[: max(0, n - len(ellipsis))] + ellipsis
+
+def display_width(s):
+    """Return the display width of a string (CJK chars count as 2 columns)."""
+    w = 0
+    for c in str(s):
+        eaw = unicodedata.east_asian_width(c)
+        w += 2 if eaw in ('W', 'F') else 1
+    return w
+
+
+def pad(s, width, align='left'):
+    """Pad string to display width for CJK-aware table alignment.
+    Replaces f'{s:<N}' (align='left') and f'{s:>N}' (align='right').
+    """
+    s = str(s)
+    dw = display_width(s)
+    spaces = max(0, width - dw) * ' '
+    return spaces + s if align == 'right' else s + spaces