# Refresh Peec Aeo Snapshot

> Refresh the Peec AEO snapshot for the docs cross-link audit. Use when the snapshot in aeo-snapshots/docs/example-topic/ is stale (older than 14 days) or when the scheduled cloud audit posted a stale-snapshot Slack alert. Must run in a local agent session where Peec MCP is authenticated.

- Skill: `warpdotdev/refresh-peec-aeo-snapshot` (Agent Skill)
- Install (CLI): `npx skillmds@latest add warpdotdev/refresh-peec-aeo-snapshot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/warpdotdev/refresh-peec-aeo-snapshot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: warpdotdev (https://skillmd.com/u/warpdotdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/warpdotdev/refresh-peec-aeo-snapshot

---


# Refresh Peec AEO snapshot

Refresh the Peec snapshot that the scheduled AEO cross-link audit cloud agent reads before each run.

**This skill must run in a local agent session.** Peec MCP requires OAuth authentication, which is not available in cloud agent environments. Do not attempt to run this in a cloud agent — it will fail silently and produce a useless export.

## Why this exists

The scheduled docs cross-link audit reads a pre-exported Peec snapshot from the `buzz` repo because cloud agents cannot authenticate with Peec directly. This snapshot must be refreshed on a cadence that keeps it under 14 days old. If it exceeds 14 days, the cloud audit agent aborts the run and posts a stale-snapshot Slack alert instead of auditing docs or opening a PR.

## Pre-flight check

Before starting:

1. **Verify Peec MCP is connected.** You should see the Peec MCP server active in your local <BRAND> session. If it is not connected, add it to your local <BRAND> MCP configuration and restart the session before continuing.
2. **Verify write access to the buzz repo.**
3. **Pull latest main in the buzz repo:**

```bash
git -C <path-to-buzz> pull
```

Replace the path above with your local `buzz` repo path if different.

## Workflow

### Step 1: Collect raw Peec data

Run this prompt in your current local agent session using the Peec MCP:

```text
Use Peec MCP to collect AEO source signals for your docs, focused only on your chosen <TOPIC_AREA>.

Create a raw JSON export at /tmp/peec-aeo-export.json with this structure:
- project: the Peec project id and name for your brand
- start_date and end_date: last 30 days
- summary: 2-4 sentence human-readable summary of the relevant Peec signals
- prompts: raw output from list_prompts, filtered or annotated for <TOPIC_AREA> relevance
- search_queries: raw output from list_search_queries for the relevant prompts or topic
- actions_overview: raw output from get_actions with scope=overview
- actions_drilldowns: follow-up get_actions outputs for the most relevant owned/editorial/reference/UGC slices
- url_report: relevant source URL rows from get_url_report if useful
- candidate_docs_areas: path hints in docs that likely matter
- open_questions: questions a docs reviewer should consider

Use source data only. Do not invent Peec recommendations. Keep the export compact enough for a cloud agent to consume.
```

Confirm that `/tmp/peec-aeo-export.json` was written and contains a non-empty `project` field and at least a few `prompts` rows before continuing.

### Step 2: Normalize the snapshot

Run the normalization script from the buzz repo root:

```bash
python3 <path-to-buzz>/scripts/generate_peec_aeo_snapshot.py \
  --input /tmp/peec-aeo-export.json \
  --output-dir <path-to-buzz>/aeo-snapshots/docs/example-topic
```

Replace the paths above with your local repo path if different.

This writes four files:
- `aeo-snapshots/docs/example-topic/latest.json`
- `aeo-snapshots/docs/example-topic/latest.md`
- `aeo-snapshots/docs/example-topic/history/YYYY-MM-DD.json`
- `aeo-snapshots/docs/example-topic/history/YYYY-MM-DD.md`

### Step 3: Spot-check the output

Verify the snapshot looks valid before committing:

```bash
python3 -c "
import json
d = json.load(open('<path-to-buzz>/aeo-snapshots/docs/example-topic/latest.json'))
print('generated_at:', d['generated_at'])
print('prompts:', len(d.get('prompts', [])))
print('query_clusters:', len(d.get('query_clusters', [])))
"
```

Expected: today's date in `generated_at`, and at least a few prompts. If the snapshot is empty or malformed, check whether the Peec MCP export in step 1 was complete.

### Step 4: Commit and push

```bash
cd <path-to-buzz>
git add aeo-snapshots/docs/example-topic/
git commit -m "chore: refresh peec aeo snapshot $(date -u +%Y-%m-%d)"
git push
```

Confirm the push succeeds. The scheduled cloud audit agent reads the snapshot from the committed `buzz` repo, so the push must complete before the next audit run.

### Step 5: Verify (optional)

```bash
git -C <path-to-buzz> show --stat HEAD
```

## After refreshing

The next scheduled audit run will automatically pick up the fresh snapshot. No additional action is needed — the cloud agent runs on its own weekly schedule.

If you want to trigger the next audit immediately before the scheduled window, use the <CLOUD_PRODUCT> web app or CLI to start a new run of the `aeo_crosslink_audit` scheduled agent.

## Freshness target

Refresh every 10–12 days to stay comfortably under the 14-day threshold, even if a scheduled run is slightly delayed. The current snapshot age is always visible in `aeo-snapshots/docs/example-topic/latest.json` under `generated_at`.