pp-surgegraph

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/ai/surgegraph/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# SurgeGraph — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `surgegraph-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install surgegraph --cli-only
   ```
2. Verify: `surgegraph-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/ai/surgegraph/cmd/surgegraph-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI when an agent needs to operate against SurgeGraph for any AI-search content task: monitoring AI Visibility deltas, drafting and publishing articles in bulk, auditing knowledge-library impact, or seeding another agent with a project's current state. Every visible web-app feature is also a CLI command, and every transcendence command is an MCP tool — the agent that opened the loop can close it without leaving the terminal.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds

- **`visibility delta`** — See exactly what moved in AI Visibility week over week — overview, trend, sentiment, or traffic — without screenshotting two dashboard tabs and diffing them by hand.

  _Use this when the user asks what changed in AI Visibility or wants a movers report; it answers without burning a follow-up API roundtrip._

  ```bash
  surgegraph-pp-cli visibility delta --project proj_abc123 --window 168h --metric overview,trend --agent
  ```
- **`visibility prompts losers`** — Surface tracked prompts whose citation count or first-position rank dropped vs the prior window — the report a CMO asks for every Monday and the dashboard can't produce.

  _Pick this when the user is hunting for visibility regressions; gives the agent a ranked, actionable list instead of two raw snapshots to compare._

  ```bash
  surgegraph-pp-cli visibility prompts losers --project proj_abc123 --since 720h --agent --select prompt_id,prompt,citation_delta,position_delta
  ```
- **`visibility citation-domains rank-shift`** — Watch which domains gained or lost citation share for your project's AI-tracked prompts over a 30-day window — useful when a competitor starts crowding the answer set.

  _Use when monitoring competitive share-of-voice in AI answers._

  ```bash
  surgegraph-pp-cli visibility citation-domains rank-shift --project proj_abc123 --window 720h --agent
  ```
- **`docs stale`** — List writer and optimized docs not updated in the last N days, ranked by recent AI-source traffic — the refresh queue in one query.

  _Use when prioritizing a content refresh queue._

  ```bash
  surgegraph-pp-cli docs stale --project proj_abc123 --older-than 90 --agent --select document_id,title,last_updated,ai_traffic_30d
  ```
- **`visibility portfolio`** — Roll up AI Visibility deltas across every project in the organization — the agency-portfolio view the single-project UI doesn't produce.

  _Use when the user manages multiple projects (agency, multi-brand) and asks for an executive summary._

  ```bash
  surgegraph-pp-cli visibility portfolio --window 168h --agent
  ```
- **`account burn`** — Project credit exhaustion from your last 30 days of usage snapshots — a pre-flight check before queueing a large bulk-publish run.

  _Pick this before kicking off a bulk operation to confirm you have credits._

  ```bash
  surgegraph-pp-cli account burn --window 720h --agent
  ```

### Cross-entity joins no single API call returns

- **`knowledge impact`** — Rank a project's knowledge libraries by how often their grounded URLs actually appear in tracked AI citations — answers "is this library worth maintaining?".

  _Pick this when the user audits knowledge libraries or asks which library is paying off._

  ```bash
  surgegraph-pp-cli knowledge impact --project proj_abc123 --agent
  ```
- **`research drift`** — Diff a topic_research's hierarchical map against the writer_documents you've already shipped — covered vs gap, ranked for action.

  _Use when planning a content sprint from a topic research; tells the agent exactly which subtopics still need articles._

  ```bash
  surgegraph-pp-cli research drift --research-id res_xyz789 --project proj_abc123 --agent --select topic,parent,covered
  ```
- **`research domain diff`** — Set-diff a competitor's domain_research topic tree against your own topic_research — instant view of what they cover and you don't.

  _Pick this when comparing topical coverage against a named competitor._

  ```bash
  surgegraph-pp-cli research domain diff --project proj_abc123 --mine res_xyz789 --theirs dom_res_aaa --agent
  ```
- **`visibility traffic-citations`** — For each top-traffic page, list the tracked prompts whose AI citations resolved to it — answers "why is this page getting AI traffic?".

  _Use when explaining traffic patterns or planning new content based on what's already pulling AI clicks._

  ```bash
  surgegraph-pp-cli visibility traffic-citations --project proj_abc123 --agent --select page_url,ai_visits,citations
  ```

### Compound workflows that span products

- **`research gaps publish`** — Take topic-gap output, bulk-create documents in 50-doc batches, and queue them into a WordPress integration — one idempotent command for the content-ops ritual.

  _Pick this when the user wants to ship articles for every gap from a topic research; collapses a multi-tab manual workflow into one call._

  ```bash
  surgegraph-pp-cli research gaps publish --research-id res_xyz789 --project proj_abc123 --integration wp_int_456 --dry-run --agent
  ```

### Agent-native plumbing

- **`context bundle`** — Emit a JSON blob shaped for an agent's context window covering prompts, citations, docs, and topic-maps for one project — the handoff payload an agent's loop needs.

  _Use to seed another agent's working memory with everything you know about a SurgeGraph project, in one round-trip._

  ```bash
  surgegraph-pp-cli context bundle --project proj_abc123 --include prompts,citations,docs,topics
  ```
- **`search`** — Full-text search across local cache: AI Visibility prompts, citations, writer documents, optimized documents, and topic-map nodes — one query, multi-entity hits.

  _Pick this when an agent needs to locate any signal — a prompt, a citation, a draft — across the whole local cache._

  ```bash
  surgegraph-pp-cli search "AI search optimization" --kind prompts,citations,docs,topics --agent --select kind,id,title,snippet
  ```
- **`sync diff`** — Emit per-resource sync cursors and total row counts from the local store — the inspection primitive for agent loops that need to know whether a re-sync is due.

  _Run after `sync` to inspect cursor freshness, or in an agent loop to decide whether the local store needs to be re-synced before reading._

  ```bash
  surgegraph-pp-cli sync diff --agent
  ```

## Command Reference

**create-ai-visibility-prompt** — Manage create ai visibility prompt

- `surgegraph-pp-cli create-ai-visibility-prompt` — Create a new prompt to AI Vis