@adgine/geo-cli 1.2.8

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

@@ -0,0 +1,279 @@
+---
+name: adgine/geo-projects
+description: Lists, creates, retrieves, updates, and deletes GEO platform website projects, manages a project's competitor list (add / list / remove), and verifies API authentication. Use when the user needs to see their website projects, select a project to work on, create a new website project, check which project is active, manage competitors (竞争对手 / 竞品 / competitors / competitor brands), or when any other GEO operation needs to identify a project ID before proceeding. Also use this skill first to verify authentication is configured correctly. Also load this skill whenever the user provides, pastes, sets, or wants to configure a GEO API key. Intent synonyms: 项目列表, project list, 创建项目, new project, 项目详情, project details, 竞品分析, competitor analysis, who are my competitors, 配置key, 设置key, 设置API key, 我的key是, set api key, configure api key, install api key, GEO_API_KEY, geo_sk_live_, api key setup.
+---
+
+# GEO Projects
+
+## 版本检测（加载本 skill 时执行）
+
+作为最常用的入口技能，加载本 skill 处理 GEO 相关请求时，**先单独运行**（本轮第一个 bash 命令）：
+
+```bash
+python3 <skills-root>/scripts/check_version.py --human
+```
+
+`<skills-root>` 是本仓库根目录（本文件向上两级）。规则见根目录 `SKILL.md`
+「版本检测」一节：有输出则在回复末尾追加该句（WorkBuddy 不得省略）。
+
+## `_notice` 处理规则
+
+本技能（及所有 adgine-geo-* 技能）的脚本运行时，若有新版本会在工具输出
+（stdout）中打印一行 `_notice: {"update": {...}}`。看到它就在完成用户请求后，
+于回复末尾追加更新提示（模板见根目录 `SKILL.md` 的「版本更新提示」一节）。
+主动检测与 `_notice` 任一发现更新都应提示；均未发现则不提版本相关内容。
+
+工具输出末尾若出现 `---` + `⚠️ adgine-geo-skills v... 已发布` 页脚，**必须原样**
+展示给用户（WorkBuddy 等改写表格时也不得省略此段）。
+
+## Step 0: First-time API key setup (when user provides a key)
+
+If the user provides a GEO API key in chat (e.g. *"my key is geo_sk_live_xxx"* / *"帮我配置一下 key"* / *"set my api key to ..."*), this is the canonical procedure for the entire skills repo. **Do not invent your own path — run the helper.**
+
+### 0-1. Locate the skills repo root
+
+This `SKILL.md` lives at `<skills-root>/adgine-geo-projects/SKILL.md`. The repo root contains all `adgine-geo-*` folders, plus `setup.py`, `.env.example`, and `README.md`. Use whatever absolute path the agent already knows for this file and go up two directories — do NOT guess `~/.hermes/...` or `/usr/local/...`.
+
+### 0-2. Run the setup helper (one command)
+
+```bash
+python3 <skills-root>/setup.py <THE_KEY_FROM_USER>
+```
+
+That single command:
+- Locates the repo root itself (uses its own `__file__`), so you don't need to `cd` first.
+- Writes `GEO_API_KEY=<key>` to `<skills-root>/.env`, creating it from `.env.example` if missing, preserving any other lines.
+- Verifies the key against the GEO API.
+- Exits `0` on success, non-zero on failure.
+
+If the user is **updating** an existing key, run the same command — `setup.py` overwrites cleanly. No need to ask for confirmation.
+
+> ⚠️ **CRITICAL — storage rules (apply every single time):**
+> - ✅ The ONLY allowed destination is `<skills-root>/.env`.
+> - ❌ NEVER write to `~/.hermes/.env`, `~/.hermes/config.*`, or any Hermes user-secrets directory.
+> - ❌ NEVER write to `~/.zshrc`, `~/.bashrc`, `~/.profile`, or any shell rc file.
+> - ❌ NEVER call `hermes config set`, `claude config`, or any agent-host secret store with this key.
+> - ❌ NEVER hardcode the key into other scripts, SKILL.md files, or chat messages.
+> - The `.env` file is `.gitignore`d — the key stays local and private.
+
+### 0-3. Confirm to the user
+
+On success (exit 0), reply with the exact path that `setup.py` printed:
+
+> ✅ **GEO API Key 已配置** — 保存到 `<absolute path printed by setup.py>`
+> 认证验证通过，现在可以使用所有 GEO skills 了。
+> 下一步可以试试：*"列出我的所有项目"*
+
+On failure (non-zero exit), do NOT retry silently. Reply:
+
+> ❌ **Key 验证失败** — 请确认 key 是否正确，或到 [platform.adgine.ai](https://platform.adgine.ai) 重新生成后再发给我。
+
+### 0-4. After Step 0 — no `export` needed
+
+Every script's `_client.py` calls `_load_dot_env()` on import and automatically reads `<skills-root>/.env`. You do not need to `export GEO_API_KEY` in the shell, and the user does not need to restart any terminal.
+
+---
+
+## 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: Confirm authentication is working
+
+Scripts auto-load `GEO_API_KEY` from `<skills-root>/.env` on import — **you don't need to `export` it**. To verify the configuration is healthy:
+
+```bash
+python3 scripts/check_auth.py
+```
+
+- ✅ Exits with "Authentication successful" → proceed.
+- ❌ Exits with "GEO_API_KEY is not set" → the error message prints the exact `.env` path. Go to **Step 0** to install a key.
+- ❌ Exits with 401 / auth failure → the key is invalid or expired. Ask the user for a new one and go to **Step 0**.
+
+> ⚠️ **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.
+
+## Determine project ID
+
+One API key manages all your projects. Resolve the project for each operation in this order:
+
+1. `--project-id` argument passed to the script
+2. `GEO_PROJECT_ID` env var (session shortcut, if set)
+3. User mentioned a domain or website name → run `list_projects.py` and match
+4. Nothing known → run `list_projects.py`, show results, ask the user to pick
+
+To avoid repeating `--project-id` within a terminal session:
+```bash
+export GEO_PROJECT_ID=<id-from-list>   # resets when terminal closes
+```
+
+## Commands
+
+### List all projects
+```bash
+python3 scripts/list_projects.py [--limit 20] [--json]
+```
+
+### Get project details
+```bash
+python3 scripts/manage_project.py get --project-id <id>
+```
+
+### Create a new project
+```bash
+python3 scripts/manage_project.py create --url https://example.com [--description "My site"]
+```
+
+### Update a project
+```bash
+python3 scripts/manage_project.py update --project-id <id> [--name "New Name"] [--url https://new.com]
+```
+
+### Delete a project
+```bash
+python3 scripts/manage_project.py delete --project-id <id>
+```
+
+### Manage competitors
+
+List the competitor brands tied to a project:
+```bash
+python3 scripts/manage_competitors.py list [--project-id <id>] [--json]
+```
+
+Add a competitor:
+```bash
+python3 scripts/manage_competitors.py add --name "Acme" [--domain acme.com] \
+    [--aliases "Acme Inc,Acme Corp"] [--source manual|brand_profile|ai_discovery]
+```
+
+Remove a competitor (DESTRUCTIVE — requires `--yes`):
+```bash
+python3 scripts/manage_competitors.py remove --competitor-id <id> --yes
+```
+
+## Output format
+
+Default: human-readable summary table.
+Pass `--json` for raw JSON (useful for piping to other scripts).
+
+## 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. They are 2 display units wide but count as 1 character, permanently misaligning all following columns.
+> - Emoji go ONLY on the label line **above** the ` ``` ` fence.
+> - Integration status in cells: `Connected` / `---` (NOT ✅/❌)
+
+---
+
+### When listing projects (`list_projects.py`)
+
+> 📁 **Your GEO Projects** — **N** total
+
+📋 Projects
+```
+┌────┬──────────────────┬─────┬─────┬────────────┐
+│  # │ Name             │ GA4 │ CF  │ Created    │
+├────┼──────────────────┼─────┼─────┼────────────┤
+│  1 │ Example Site     │ OK  │ --- │ 2025-01-15 │
+│  2 │ My Blog          │ --- │ --- │ 2025-03-22 │
+└────┴──────────────────┴─────┴─────┴────────────┘
+```
+List project URLs below as clickable links:
+- Example Site → [example.com](https://example.com)
+- My Blog → [myblog.io](https://myblog.io)
+
+If a selection is needed ask: *"Which project would you like to work with?"*
+
+---
+
+### When showing project details (`manage_project.py get`)
+
+📁 Project Details
+```
+┌────────────┬──────────────────────────────────────┐
+│ Name       │ Example Site                         │
+│ URL        │ https://example.com                  │
+│ Created    │ 2025-01-15                           │
+│ GA4        │ Connected                            │
+│ Cloudflare │ ---                                  │
+└────────────┴──────────────────────────────────────┘
+```
+If any integration is `---`: > 🔌 Connect integrations at [platform.adgine.ai](https://platform.adgine.ai)
+
+---
+
+### When creating a project
+
+✅ Project Created
+```
+┌────────────┬──────────────────────────────────────┐
+│ Name       │ Example Site                         │
+
+│ URL        │ https://example.com                  │
+└────────────┴──────────────────────────────────────┘
+```
+> **Next:** connect integrations at [platform.adgine.ai](https://platform.adgine.ai)
+
+### When updating
+
+> ✅ Project **&lt;project name&gt;** updated — **&lt;field&gt;** → `<new value>`
+
+### When deleting
+
+> 🗑️ Project **&lt;project name&gt;** deleted.
+
+### After auth check (`check_auth.py`)
+
+> ✅ **Authenticated** — key valid for `<email or user-id>`
+
+On failure:
+
+> ❌ **Authentication failed.** Check `GEO_API_KEY` — get a key at [platform.adgine.ai](https://platform.adgine.ai)
+
+---
+
+## Post-task recommendations
+
+After completing project operations, always end with 2–3 actionable next steps
+based on what the project still needs. To check current state, run:
+
+```bash
+python3 <skills-root>/adgine-geo-dashboard/scripts/get_overview.py [--project-id <id>]
+```
+
+Read these indicators and suggest the earliest missing step in the GEO pipeline:
+
+| Dashboard indicator | → use skill (agent-internal) |
+|---|---|
+| Topics count = 0 | 创建主题和提示词 *(→ adgine-geo-topics)*|
+| Prompts count = 0 | 批量生成 AI 搜索提示词 *(→ adgine-geo-topics)*|
+| Tests count = 0 | 运行引用测试 *(→ adgine-geo-citation)*|
+| Articles count = 0 | 生成 GEO 优化文章 *(→ adgine-geo-content)*|
+| GA4 not connected | 连接 GA4 获取流量数据 *(→ adgine-geo-integrations)*|
+| Cloudflare not connected | 接入 Cloudflare 追踪 AI 爬虫 *(→ adgine-geo-integrations)*|
+| Brand not generated | 生成品牌画像 *(→ adgine-geo-brand)*|
+
+Always present suggestions as:
+
+**⚠️ 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-projects/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

package/skills/adgine-geo-projects/scripts/check_auth.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Verify GEO_API_KEY is set and valid.
+
+Run this once before using any other geo-skills scripts.
+"""
+import os
+import sys
+import json
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import get_api_config, api_get, extract_data
+
+key, base = get_api_config()
+
+if not key.startswith("geo_sk_"):
+    print(f"WARNING: Unexpected key format: {key[:14]}...")
+    print("  Expected: geo_sk_live_xxx or geo_sk_test_xxx")
+
+# Verify by fetching projects list
+print(f"Verifying API key...")
+result = api_get("/api/projects", key, base, params={"limit": 1})
+data = extract_data(result)
+
+total = data.get("total", "?") if isinstance(data, dict) else "?"
+
+# Also fetch current-user info
+me_result = api_get("/api/auth/me", key, base)
+me = extract_data(me_result) or {}
+
+print(f"✓ Authentication successful")
+print(f"  Key prefix : {key[:18]}...")
+print(f"  API base   : {base}")
+print(f"  Projects   : {total} project(s) found")
+if me:
+    who = me.get("email") or me.get("username") or me.get("name") or me.get("id")
+    if who:
+        print(f"  User       : {who}")
+print()
+
+project_id = os.environ.get("GEO_PROJECT_ID", "")
+if project_id:
+    print(f"  Active project: {project_id}  (from GEO_PROJECT_ID env var)")
+else:
+    print("  No active project set. Run list_projects.py to select one.")
+    print("  Then: export GEO_PROJECT_ID=<project-id>")