pp-pcgs

What this skill does

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

# PCGS — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `pcgs-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 pcgs --cli-only
   ```
2. Verify: `pcgs-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/other/pcgs/cmd/pcgs-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 you need to verify PCGS certs at scale, extract full CoinFacts metadata for downstream import, or keep a local snapshot of population / price-guide / auction data refreshed under a tight 1,000-call daily budget. It is upstream of any personal collection system, not a replacement for one. Reach for it when an agent needs the raw PCGS record, not a curated subset.

## 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.

### Quota-aware orchestration
- **`coin batch`** — Parse a CSV / JSON wrapper / JSONL / plain-text cert list and look up every cert against PCGS. --dry-run forecasts cost (live calls, cache hits, %-of-quota) without spending a single call. --resumable + --checkpoint split a list larger than the 1,000/day cap across UTC days. --list-certs emits the parsed cert list to stdout without calling. Non-cert input columns round-trip to output as `_keep.<col>` for downstream re-keying.

  _Use this any time you have more than one cert to look up. The dry-run mode answers 'does this fit today's quota?' for free; --resumable makes multi-day batches idempotent._

  ```bash
  pcgs-pp-cli coin batch --file ./pcgs-coin-list.csv --dry-run --json
  ```
- **`refresh`** — Refresh cached coins by updating only the fields PCGS can actually change — Population, PopHigher, PriceGuideValue, AuctionList, Images, CoinFactsNotes — while leaving cert identity fields untouched. Emits a per-field diff. --dry-run --older 30d --field price-guide lists which cached coins need refresh without calling the API.

  _This is the safe way to keep market data current without putting cert identity at risk. Pair --dry-run --older with --field to find what to refresh before spending quota._

  ```bash
  pcgs-pp-cli refresh --all --older 7d --json
  ```

### PCGS-specific content patterns
- **`coin pop-curve`** — Pull every grade 1–70 (and PlusGrade variants, plus the 82–98 Details codes when --include-details) for one PCGSNo in one command, persist the full population curve to local store, and print the scarcity table.

  _Use this when you need scarcity context across grades — dealer pricing, key-date analysis, or seeing where Details-grade coins fit relative to numerical grades._

  ```bash
  pcgs-pp-cli coin pop-curve 7356 --plus --include-details --json
  ```
- **`order hydrate`** — Take a PCGS submission number, fetch the order, then fan out CoinFacts (and optionally images) for every cert in the order. Respects cache and refuses to start when remaining quota is less than the cert count.

  _Use this the moment a PCGS submission posts. It turns one submission number into a fully-cached, fully-hydrated set of coins in one command._

  ```bash
  pcgs-pp-cli order hydrate 12345678 --with-images --json
  ```

### Local state that compounds
- **`audit`** — Query the lookup_log table directly: every API call, its endpoint, IsValidRequest, ServerMessage, and request hash. Aggregate by day, by endpoint, or by cert; filter to failed calls only.

  _Reach for this when quota usage looks off, when you want to spot which certs return IsValidRequest=false, or when triaging a sync diff._

  ```bash
  pcgs-pp-cli audit --since 7d --failed --by-endpoint --json
  ```
- **`search`** — FTS5 + numeric filters over your local cache: search by Name, Country, SeriesName, Category, Designer, MintLocation, or variety fields, plus range filters on Year, Grade, PriceGuideValue, Population, PopHigher, Mintage, Weight, Diameter. --max-pop and --top-pct flags expose continuous rarity slicing (e.g. --top-pct 5 = top 5% rarest in the scoped cohort) — no API call.

  _Use this any time you need to slice your cached collection without burning quota. --top-pct 1 surfaces apex-rarity coins; --max-pop N for explicit thresholds._

  ```bash
  pcgs-pp-cli search --text "morgan dollar" --year 1881 --top-pct 5 --json --select Name,Year,Grade,Population,PriceGuideValue
  ```

## Command Reference

**banknote** — PCGS Banknote lookups: facts and images. Same shape as coins, separate endpoint family.

- `pcgs-pp-cli banknote facts-cert` — Full banknote metadata for one PCGS Banknote cert. Optional language code for translated text.
- `pcgs-pp-cli banknote facts-grade` — Banknote snapshot for a (PCGSNo, GradeNo) tuple.
- `pcgs-pp-cli banknote images` — Image URLs for one PCGS Banknote cert.

**coin** — PCGS-graded coin lookups: CoinFacts metadata, Auction Prices Realized (APR), and images.

- `pcgs-pp-cli coin apr-barcode` — Auction Prices Realized by holder barcode with optional date window.
- `pcgs-pp-cli coin apr-cert` — Auction Prices Realized for one PCGS cert number.
- `pcgs-pp-cli coin apr-grade` — Auction Prices Realized for a (PCGSNo, GradeNo, PlusGrade) tuple with optional date window and result limit.
- `pcgs-pp-cli coin facts-barcode` — CoinFacts metadata by holder barcode. Supports PCGS and competitor-service barcodes (NGC, ANACS, ICG, SEGS).
- `pcgs-pp-cli coin facts-cert` — Full CoinFacts metadata for one PCGS cert number. The IsValidRequest + ServerMessage envelope tells you if the cert...
- `pcgs-pp-cli coin facts-grade` — CoinFacts snapshot for a (PCGSNo, GradeNo, PlusGrade) tuple. Used by pop-curve to fan grades 1-70 + Plus + Details...
- `pcgs-pp-cli coin images` — TrueView and stock images for one PCGS cert (URLs only; no binary download).

**order** — PCGS submission and order lookups for submitters.

- `pcgs-pp-cli order range` — Orders within a date window (paginated).
- `pcgs-pp-cli order submission` — Orders associated with one PCGS submission number.


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
pcgs-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Recipes


### Verify one cert and dump every field

```bash
pcgs-pp-cli coin facts-cert 53972744 --json --select data.Name,data.Year,data.Grade,data.Population,data.PopHigher,data.PriceGuideValue,data.CoinFactsLink,data.IsValidRequest,data.ServerMessage
```

Single l