pp-digg

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/media-and-entertainment/digg/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/". -->

# Digg — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `digg-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 digg --cli-only
   ```
2. Verify: `digg-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/media-and-entertainment/digg/cmd/digg-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

Use this CLI when an agent or power user needs structured access to Digg's rankings, ranking-change history, pipeline events, per-cluster transparency record, or the GitHub feeds. It is the right tool for tracking AI-news cycle movement, building cross-aggregator research over HN+Techmeme+Digg, watching new AI repos the moment they're starred by tracked accounts, or exposing Digg signals into a larger automation. Do NOT use it for vote, comment, or post automation — those mutations are explicitly out of scope.

## When Not to Use This CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.

## Unique Capabilities

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

### Topic search and per-post citations
- **`search`** — Topic search across Digg's full window. Live by default — hits `/api/search/stories`, the same server-side search that backs the di.gg/ai Cmd+K modal — with FTS5 fallback to the local store on network error or `--data-source local`.

  _Returns ranked clusters with engagement metadata (postCount, uniqueAuthors, firstPostAge); the load-bearing recipe for last30days-style research workflows._

  ```bash
  digg-pp-cli search "<topic>" --since 30d --agent --select clusterUrlId,title,rank,postCount,uniqueAuthors,firstPostAge
  ```
  - **`--since Nh|Nd|Nw|Nm`** — filter to clusters first posted within the window (live mode parses Digg's own `firstPostAge`; local mode reads `digg_clusters.first_post_at`).
- **`posts`** — X posts attached to one cluster, with author rank, body when rendered, media URLs, repost-context, and minted xUrl for one-click citation.

  _The citations recipe: surface the highest-credibility AI 1000 voices on a story, sortable by rank, type, or time._

  ```bash
  digg-pp-cli posts <clusterUrlId> --by rank --limit 5 --agent --select author.username,author.rank,post_type,xUrl,body
  ```

### Author lookup and roster browse
- **`authors get`** — Look up any X handle in Digg's full author universe (1000 + off-1000) via `/api/search/users`. For off-1000 handles, the response includes `subject_peer_follow_count`, the rank-1000 anchor's `peer_follow_count`, and a signed `peer_follow_gap` — the gap to the 1000 measured in AI-1000 peer follows (NOT raw X follower count).

  _The credibility lookup: an agent can decide whether to quote a handle by reading one structured record._

  ```bash
  digg-pp-cli authors get <handle> --agent
  ```

  Trimmed off-1000 example for `mvanhorn`:
  ```json
  {
    "username": "mvanhorn",
    "current_rank": null,
    "subject_peer_follow_count": 19,
    "nearest_in_1000": {"rank": 1000, "username": "...", "peer_follow_count": 90},
    "peer_follow_gap": 71
  }
  ```
  `peer_follow_gap` is the gap to rank-1000's `followed_by_count` (peer follows from inside the AI 1000). Do not read it as a raw X follower delta.
- **`authors list`** — Full ranked AI 1000 from `/ai/1000`, persisted with rich fields (rank, category, bio, vibeDistribution, GitHub URL).

  _Identify rising voices in a category, find authors who just joined the 1000, see who's falling fast — sortable, filterable, scriptable._

  ```bash
  # Biggest movers since the last snapshot
  digg-pp-cli authors list --by rankChange --limit 20 --agent

  # Newly listed (first appearance in the 1000)
  digg-pp-cli authors list --only-new --agent
  ```
  Sort with `--by rank|rankChange|category|followers`; filter with `--category "<name>"`, `--only-new`, `--only-fallers`.

### Live pipeline observability
- **`events`** — Tail Digg's ingestion pipeline in real time — see clusters as they're detected, stories fast-climbing the leaderboard with explicit rank deltas, X posts being processed, batch breakdowns.

  _When an agent needs 'tell me when story X just climbed N ranks' or 'what new clusters did Digg detect in the last hour', this is the only way._

  ```bash
  digg-pp-cli events --since 1h --type fast_climb --json --select clusterId,label,delta,currentRank,previousRank
  ```
- **`watch`** — Poll /ai, diff against last snapshot, alert when any cluster moves N+ ranks.

  _Read-only operational watcher; never writes anything back to Digg._

  ```bash
  digg-pp-cli watch --alert 'rank.delta>=10'
  ```
- **`pipeline status`** — One-screen view of /api/trending/status: isFetching, nextFetchAt, storiesToday, clustersToday, last 5 events.

  _Lets ops and power users see when a fresh batch is about to land and what's been ingested in the last hour._

  ```bash
  digg-pp-cli pipeline status --watch
  ```

### Local state that compounds
- **`replaced`** — Show stories that were knocked out of the rankings since the last sync, with Digg's own published replacement rationale.

  _Best-of-feed shifts faster than people remember. This makes 'what did Digg drop and why' queryable._

  ```bash
  digg-pp-cli replaced --since 24h --json
  ```
- **`crossref`** — Show this cluster's Hacker News and Techmeme mirrors when Digg has detected the story is being discussed there.

  _Removes the manual 'is HN talking about this too' step from any cross-aggregator research workflow._

  ```bash
  digg-pp-cli crossref iq7usf9e
  ```
- **`authors top`** — Top accounts Digg tracks, ranked by Digg's influence score, story count, or reach.

  _Investors and AI scouts care which accounts move the news cycle. Now queryable, sortable, scriptable._

  ```bash
  digg-pp-cli authors top --by influence --limit 50 --json
  ```
- **`history`** — Full trajectory of one cluster's currentRank, peakRank, and delta over local snapshot history.

  _'Entered at #18, peaked at #4 over 6h, dropped to #22 by 24h' is impossible to learn from the live site._

  ```bash
  digg-pp-cli history iq7usf9e --json
  ```
- **`author`** — Every cluster a given X account contributed to, with post type (original, retweet, quote, reply).

  _'Show me every story this account surfaced this week' is the investor-scout query._

  ```bash
  digg-pp-cli author Scobleizer --since 7d --json
  ```

### Transparency
- **`evidence`** — Print the full ranking transparency record for one cluster — scoreComponents, evidence array, numeratorLabel, percentAboveAverage.

  _When a user asks 'why is THIS the top story', the answer is structured data; agents can compose with it._

  ```bash
  digg-pp-cli evidence iq7usf9e --json
  ```
- **`sentiment`** — Re