pp-table-reservation-goat

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/food-and-dining/table-reservation-goat/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/". -->

# Table Reservation GOAT — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `table-reservation-goat-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 table-reservation-goat --cli-only
   ```
2. Verify: `table-reservation-goat-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/food-and-dining/table-reservation-goat/cmd/table-reservation-goat-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 any time a user or agent needs to search, compare, watch, or book across OpenTable, Tock, and Resy together — and especially for multi-venue questions ('soonest table at any of these'), cancellation hunting, or tracking changes at a specific venue. For single-network simple lookups, the official site UI is faster.

## Unique Capabilities

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

### Cross-network ground truth
- **`goat`** — One query across OpenTable, Tock, and Resy simultaneously, ranked by relevance, earliest availability, and price band.

  _When a user asks an agent to find a table, this is the single command that searches both reservation networks and returns structured ranked results — agents do not need to know which network covers which restaurant._

  ```bash
  table-reservation-goat-pp-cli goat 'tasting menu chicago' --party 2 --when 'this weekend' --agent --select results.name,results.network,results.earliest_slot,results.price_band
  ```
- **`earliest`** — Across a list of restaurants from either network, return the earliest open slot per venue within a time horizon.

  _When a user gives an agent a shortlist of venues and wants the soonest opportunity, this is the right shape — one structured response with one row per venue across all three networks._

  ```bash
  table-reservation-goat-pp-cli earliest 'alinea,le-bernardin,smyth,atomix' --party 4 --within 21d --agent --select earliest.venue,earliest.network,earliest.slot_at,earliest.attributes
  ```

### Local state that compounds
- **`watch`** — Persistent local watcher that polls each network for openings on your target venues and party size, with notifications and optional auto-book.

  _Resy's Notify covers Resy only; tockstalk covers Tock only; restaurant-mcp's snipe covers Resy+OT only. None covers each network; none persists state. Use this when an agent or user needs a hot reservation that isn't currently available._

  ```bash
  table-reservation-goat-pp-cli watch add 'le-bernardin' --party 2 --window 'Fri 7-9pm' --notify slack
  ```
- **`drift`** — Show what changed at a specific venue since the last sync — new experiences, slot price moves, hours changes.

  _Hot-target deep-watch: when an agent or user is hunting one venue, drift surfaces every meaningful change since the last look._

  ```bash
  table-reservation-goat-pp-cli drift alinea --since '2026-04-01' --agent
  ```

## Command Reference

**availability** — Check open reservation slots across OpenTable, Tock, and Resy

- `table-reservation-goat-pp-cli availability check` — Check open slots for a restaurant on a specific date and party size
- `table-reservation-goat-pp-cli availability multi-day` — Multi-day availability for a single restaurant — Mon-Sun matrix

**restaurants** — Search and inspect restaurants across OpenTable, Tock, and Resy

- `table-reservation-goat-pp-cli restaurants get` — Get a restaurant's full detail — hours, address, cuisine, price band, photos, accolades
- `table-reservation-goat-pp-cli restaurants list` — List restaurants across OpenTable, Tock, and Resy; filter by location, cuisine, price band, accolades, and party size

**watch** — Persistent local cancellation watcher across all three networks

- `table-reservation-goat-pp-cli watch add` — Register a watch for a venue, party size, and time window
- `table-reservation-goat-pp-cli watch list` — List active watches
- `table-reservation-goat-pp-cli watch cancel` — Cancel a watch by id
- `table-reservation-goat-pp-cli watch tick` — Run one polling tick across all active watches (for cron / agents)


### Finding the right command

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

```bash
table-reservation-goat-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.

## Location Handling (Agent Playbook)

Every read command (`restaurants list`, `availability check`, `availability multi-day`, `earliest`, `goat`, `watch`) accepts a free-form `--location` flag that parses bare city, city+state, metro qualifier, or coordinates.

**Accepted `--location` shapes:**

```bash
--location bellevue              # bare city (ambiguous — see below)
--location 'bellevue, wa'        # city + state (unambiguous)
--location 'seattle metro'       # metro qualifier
--location '47.6101,-122.2015'   # coordinates (lat,lng)
```

The resolver returns one of three response shapes, classified by the categorical `tier` field:

- **`tier: "high"`** (one match, or specific input): response includes `location_resolved` field with the canonical name, centroid, reason, and any alternates considered. Results are filtered to that region.
- **`tier: "medium"`** (multiple candidates but one dominates): response includes both `location_resolved` and `location_warning`. The warning lists the alternates so the agent can sanity-check against conversation context.
- **`tier: "low"`** (genuinely ambiguous, e.g., bare "bellevue" matches WA/NE/KY): the command refuses to return results. Instead it emits a typed `needs_clarification` envelope with ranked candidates, each carrying `state`, `context_hints`, `tock_business_count`, and `score_if_picked`. The agent disambiguates and re-runs.

Note: `location_resolved.score` is the popularity prior (a mechanical [0,1] number derived from population + provider coverage). Do not branch on this number — Bellevue WA at city+state specificity is HIGH-certain but its absolute score is modest (~0.42), and Seattle at HIGH tier reads ~0.6. The categorical `tier` field is what agents branch on; `score` is informational.

### Three agent rules (load-bearing contract)

**1. Always check `location_resolved.tier` in successful responses.**
The `tier` string is the agent-facing categorical classification — branch on it, not on the numeric `score`.
- `tier == "high"` — the pick is reliable; proceed.
- `tier == "medium"` — alternates exist and the response includes a `location_warning` listing them. Sanity-check the pick against conversation context (e.g., did you pick Portland OR but the user clearly meant Maine?). Surface the pick to the user.
- `tier == "low"` — you'll receive a `needs_clarification` envelope instea