Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

fix

Tong40939a96a90f
diff --git a/bin/preamble.md b/bin/preamble.md
new file mode 100755
index 00000000..cd38a6a1
--- /dev/null
+++ b/bin/preamble.md
@@ -0,0 +1,14 @@
+## Preamble (run first)
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
+
+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
+
+---
+
diff --git a/bin/toprank-config b/bin/toprank-config
new file mode 100755
index 00000000..cc0d0a5e
--- /dev/null
+++ b/bin/toprank-config
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# toprank-config — read/write ~/.toprank/config.yaml
+#
+# Usage:
+# toprank-config get <key> — read a config value
+# toprank-config set <key> <value> — write a config value
+# toprank-config list — show all config
+#
+# Env overrides (for testing):
+# TOPRANK_STATE_DIR — override ~/.toprank state directory
+set -euo pipefail
+
+STATE_DIR="${TOPRANK_STATE_DIR:-$HOME/.toprank}"
+CONFIG_FILE="$STATE_DIR/config.yaml"
+
+case "${1:-}" in
+ get)
+ KEY="${2:?Usage: toprank-config get <key>}"
+ grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true
+ ;;
+ set)
+ KEY="${2:?Usage: toprank-config set <key> <value>}"
+ VALUE="${3:?Usage: toprank-config set <key> <value>}"
+ mkdir -p "$STATE_DIR"
+ if grep -qE "^${KEY}:" "$CONFIG_FILE" 2>/dev/null; then
+ _tmpfile="$(mktemp "${CONFIG_FILE}.XXXXXX")"
+ sed "s/^${KEY}:.*/${KEY}: ${VALUE}/" "$CONFIG_FILE" > "$_tmpfile" && mv "$_tmpfile" "$CONFIG_FILE"
+ else
+ echo "${KEY}: ${VALUE}" >> "$CONFIG_FILE"
+ fi
+ ;;
+ list)
+ cat "$CONFIG_FILE" 2>/dev/null || true
+ ;;
+ *)
+ echo "Usage: toprank-config {get|set|list} [key] [value]"
+ exit 1
+ ;;
+esac
diff --git a/bin/toprank-update-check b/bin/toprank-update-check
new file mode 100755
index 00000000..a089d31f
--- /dev/null
+++ b/bin/toprank-update-check
@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# toprank-update-check — periodic version check for toprank skills.
+#
+# Output (one line, or nothing):
+# JUST_UPGRADED <old> <new> — marker found from recent upgrade
+# UPGRADE_AVAILABLE <old> <new> — remote VERSION differs from local
+# (nothing) — up to date, snoozed, disabled, or check skipped
+#
+# Env overrides (for testing):
+# TOPRANK_DIR — override auto-detected toprank root
+# TOPRANK_REMOTE_URL — override remote VERSION URL
+# TOPRANK_STATE_DIR — override ~/.toprank state directory
+set -euo pipefail
+
+TOPRANK_DIR="${TOPRANK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+STATE_DIR="${TOPRANK_STATE_DIR:-$HOME/.toprank}"
+CACHE_FILE="$STATE_DIR/last-update-check"
+MARKER_FILE="$STATE_DIR/just-upgraded-from"
+SNOOZE_FILE="$STATE_DIR/update-snoozed"
+VERSION_FILE="$TOPRANK_DIR/VERSION"
+REMOTE_URL="${TOPRANK_REMOTE_URL:-https://raw.githubusercontent.com/nowork-studio/toprank/main/VERSION}"
+CONFIG_BIN="$TOPRANK_DIR/bin/toprank-config"
+VERSION_RE='^[0-9]+(\.[0-9]+)+$'
+
+# State dir must exist early so any writes below succeed.
+mkdir -p "$STATE_DIR"
+
+# ─── Force flag (busts cache + snooze for standalone /toprank-upgrade) ──
+if [ "${1:-}" = "--force" ]; then
+ rm -f "$CACHE_FILE"
+ rm -f "$SNOOZE_FILE"
+fi
+
+# ─── Step 0: Check if updates are disabled ────────────────────
+_UC=$("$CONFIG_BIN" get update_check 2>/dev/null || true)
+if [ "$_UC" = "false" ]; then
+ exit 0
+fi
+
+# ─── Snooze helper ──────────────────────────────────────────
+# check_snooze <remote_version>
+# Returns 0 if snoozed (stay quiet), 1 if not snoozed (should output).
+#
+# Snooze file format: <version> <level> <epoch>
+# Level durations: 1=24h, 2=48h, 3+=7d
+# New version resets snooze.
+check_snooze() {
+ local remote_ver="$1"
+ if [ ! -f "$SNOOZE_FILE" ]; then
+ return 1
+ fi
+ local snoozed_ver snoozed_level snoozed_epoch
+ snoozed_ver="$(awk '{print $1}' "$SNOOZE_FILE" 2>/dev/null || true)"
+ snoozed_level="$(awk '{print $2}' "$SNOOZE_FILE" 2>/dev/null || true)"
+ snoozed_epoch="$(awk '{print $3}' "$SNOOZE_FILE" 2>/dev/null || true)"
+
+ if [ -z "$snoozed_ver" ] || [ -z "$snoozed_level" ] || [ -z "$snoozed_epoch" ]; then
+ return 1
+ fi
+ case "$snoozed_level" in *[!0-9]*) return 1 ;; esac
+ case "$snoozed_epoch" in *[!0-9]*) return 1 ;; esac
+
+ if [ "$snoozed_ver" != "$remote_ver" ]; then
+ return 1
+ fi
+
+ local duration
+ case "$snoozed_level" in
+ 1) duration=86400 ;; # 24 hours
+ 2) duration=172800 ;; # 48 hours
+ *) duration=604800 ;; # 7 days (level 3+)
+ esac
+
+ local now
+ now="$(date +%s)"
+ local expires=$(( snoozed_epoch + duration ))
+ if [ "$now" -lt "$expires" ]; then
+ return 0 # still snoozed
+ fi
+ return 1 # snooze expired
+}
+
+# ─── Step 1: Read and validate local version ─────────────────
+LOCAL=""
+if [ -f "$VERSION_FILE" ]; then
+ LOCAL="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')"
+fi
+if [ -z "$LOCAL" ]; then
+ exit 0
+fi
+# Reject malformed local VERSION to avoid writing garbage to cache.
+if ! echo "$LOCAL" | grep -qE "$VERSION_RE"; then
+ exit 0
+fi
+
+# ─── Step 2: Check "just upgraded" marker ─────────────────────
+# Exit immediately after printing JUST_UPGRADED — do not fall through
+# to the network fetch or we'd produce two output lines.
+if [ -f "$MARKER_FILE" ]; then
+ OLD="$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]')"
+ rm -f "$MARKER_FILE"
+ rm -f "$SNOOZE_FILE"
+ if [ -n "$OLD" ]; then
+ echo "JUST_UPGRADED $OLD $LOCAL"
+ fi
+ exit 0
+fi
+
+# ─── Step 3: Check cache freshness ──────────────────────────
+# UP_TO_DATE: 60 min TTL. UPGRADE_AVAILABLE: 720 min TTL (keep notifying).
+if [ -f "$CACHE_FILE" ]; then
+ CACHED="$(cat "$CACHE_FILE" 2>/dev/null || true)"
+ case "$CACHED" in
+ UP_TO_DATE*) CACHE_TTL=5 ;;
+ UPGRADE_AVAILABLE*) CACHE_TTL=720 ;;
+ *) CACHE_TTL=0 ;;
+ esac
+
+ STALE=$(find "$CACHE_FILE" -mmin +$CACHE_TTL 2>/dev/null || true)
+ if [ -z "$STALE" ] && [ "$CACHE_TTL" -gt 0 ]; then
+ case "$CACHED" in
+ UP_TO_DATE*)
+ CACHED_VER="$(echo "$CACHED" | awk '{print $2}')"
+ if [ "$CACHED_VER" = "$LOCAL" ]; then
+ exit 0
+ fi
+ ;;
+ UPGRADE_AVAILABLE*)
+ CACHED_OLD="$(echo "$CACHED" | awk '{print $2}')"
+ if [ "$CACHED_OLD" = "$LOCAL" ]; then
+ CACHED_NEW="$(echo "$CACHED" | awk '{print $3}')"
+ if check_snooze "$CACHED_NEW"; then
+ exit 0
+ fi
+ echo "$CACHED"
+ exit 0
+ fi
+ ;;
+ esac
+ fi
+fi
+
+# ─── Step 4: Slow path — fetch remote version ────────────────
+REMOTE="$(curl -sf --max-time 5 "$REMOTE_URL" 2>/dev/null || true)"
+REMOTE="$(echo "$REMOTE" | tr -d '[:space:]')"
+
+# Validate: must look like a version number (reject HTML error pages, etc.)
+if ! echo "$REMOTE" | grep -qE "$VERSION_RE"; then
+ _TMP="$CACHE_FILE.$$.tmp"
+ echo "UP_TO_DATE $LOCAL" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
+ exit 0
+fi
+
+if [ "$LOCAL" = "$REMOTE" ]; then
+ _TMP="$CACHE_FILE.$$.tmp"
+ echo "UP_TO_DATE $LOCAL" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
+ exit 0
+fi
+
+# Versions differ — upgrade available
+_TMP="$CACHE_FILE.$$.tmp"
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
+if check_snooze "$REMOTE"; then
+ exit 0
+fi
+
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE"
diff --git a/google-ads/shared/preamble.md b/google-ads/shared/preamble.md
index 324edf0c..887523db 100644
--- a/google-ads/shared/preamble.md
+++ b/google-ads/shared/preamble.md
@@ -2,6 +2,18 @@
Every google-ads skill reads this before doing anything else. It handles MCP detection, authentication, and upgrade checks in one place — so individual skills don't repeat this logic.
+## Step 0: Check for toprank updates
+
+```bash
+_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
+ ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
+
+If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
+
## Step 1: Check config cache
Read `~/.adsagent/config.json`. If both `apiKey` and `accountId` are present, skip to Step 4. The MCP server is already configured and the account is selected — no further setup needed.