feat: CLI-first discovery, context verification (show whoami; confirm unless clear match)

AGENTS.md

@@ -15,7 +15,7 @@ All skills MUST conform to the [Agent Skills specification](https://agentskills.
 - `name`: max 64 chars, lowercase `a-z`, numbers, and hyphens only. Must match the parent directory name exactly. No consecutive hyphens. Cannot start or end with a hyphen.
 - `description`: max 1024 chars. Third person. Describes what the skill does AND when to use it with specific trigger phrases.
 - SKILL.md body: **under 500 lines** (< 5000 tokens). Move detailed content to `references/` files.
-- File references: **one level deep** from SKILL.md only. SKILL.md links to reference files; reference files do not chain to other reference files.
+- File references: **one level deep** from SKILL.md only. SKILL.md links to reference files. Reference files may link to other reference files for workflow (e.g. 01→02→04) or "see also"; avoid long chains (A→B→C→D).
 - Reference files over 100 lines: include a table of contents at the top.
 - Progressive disclosure: `name` and `description` are loaded at startup for all skills. Full SKILL.md is loaded when the skill is activated. Reference files are loaded only on demand.
 
@@ -142,6 +142,10 @@ Skills are static files that become stale as the product evolves. Every SKILL.md
 
 Most Hookdeck doc pages are available as markdown by appending `.md` to the URL. See `event-gateway/references/referencing-docs.md` for the complete URL index. Use `allowed-tools: WebFetch` in SKILL.md frontmatter to let agents pull live docs on demand.
 
+**CLI reference:** The full CLI reference lives at `/docs/cli` and is served there as a single HTML page. The same content is also split into separate markdown files (e.g. `/docs/cli/request.md`, `/docs/cli/event.md`, `/docs/cli/metrics.md`) so agents can fetch only the command or section they need — use these `.md` URLs when linking to a specific CLI command or when tools fetch docs as markdown for gradual discovery.
+
+**API reference:** The full API reference lives at `/docs/api` as a single HTML page. Sub-resources (e.g. inspect, bulk, connections) are **not** separate HTML pages; they exist as markdown files (e.g. `/docs/api/inspect.md`, `/docs/api/bulk.md`, `/docs/api/connections.md`). Link directly to `.md` URLs for API sub-resources so agents and tools get fetchable content; links to `/docs/api/foo` without `.md` will 404.
+
 ### What belongs in SKILL.md vs references
 
 **SKILL.md:** Concise overview, key concepts, decision trees, quick copy-pasteable examples, links to reference files and live docs. Under 500 lines.
@@ -150,10 +154,16 @@ Most Hookdeck doc pages are available as markdown by appending `.md` to the URL.
 
 Rule of thumb: if content is needed for every task involving this skill, it belongs in SKILL.md. If it's only needed for a specific sub-task, put it in a reference file.
 
+### When to use CLI vs API (and Terraform for IaC)
+
+Direct the agent to the right resource based on the task. **CLI** = good first touch point (tasks, simple scripts: single commands or short multi-command workflows from the shell). **API** = valid for querying (events, requests, attempts, metrics), complex scripts, applications, automation; and for **dynamic resource creation** (e.g. application creating sources/connections at runtime). **When in doubt, start with the CLI to explore.** For resource management (sources, destinations, connections, transformations): **API** when resources are created **dynamically** (e.g. from an app at runtime); **Terraform** or **CLI/scripts** for **effectively static** definition management (IaC); mention the [Terraform provider](https://github.com/hookdeck/terraform-provider-hookdeck) for IaC. Skills should give this top-level guidance; surface both CLI and API querying; link to main docs for how-to details.
+
 ### Prescriptive guidance over syntax documentation
 
 Reference files should teach the agent **how to think** about the problem. Provide decision trees, top patterns, and common gotchas. Link to live docs for comprehensive syntax reference. Follow the Neon model: minimal examples, point to live docs for the rest.
 
+**Commands and options:** Include a **reasonable capability summary** (e.g. key commands with brief purpose) so the agent can discover what's possible without fetching first; then the agent fetches the canonical reference for the full list. Summaries may go slightly out of date—acceptable for discovery. Always **link to the canonical reference** (e.g. [CLI reference](https://hookdeck.com/docs/cli), API docs). Avoid exhaustive lists that duplicate the docs.
+
 ### Working examples
 
 The `examples/` directory contains runnable code (Express, Next.js, FastAPI Hookdeck verification handlers). Stage `02-scaffold` references these for agent scaffolding. Keep examples focused on the minimum needed to demonstrate the pattern.
@@ -185,7 +195,7 @@ When you are **adding a new skill** or **updating an existing skill** in this re
    - Prefer **try install first:** have the agent run `npx skills add hookdeck/webhook-skills --skill <provider>-webhooks` to verify the provider skill exists; if install fails, fall back to looking up the webhook-skills repo or informing the user.
    - Keep provider guidance **generic:** refer to "provider SDK verification and event construction" and "constructs provided by the provider's SDK" (e.g. Stripe `constructEvent`, Shopify HMAC as examples, not Stripe-only).
    - Instruct the agent to **recommend to the user** that they install the provider webhook skill (e.g. "I recommend installing the stripe-webhooks skill... Run: `npx skills add hookdeck/webhook-skills --skill stripe-webhooks`").
-4. **One level deep:** All references from SKILL.md must be to files directly in that skill's directory (e.g. `references/...`). Reference files do not chain to other reference files.
+4. **One level deep:** All references from SKILL.md must be to files directly in that skill's directory (e.g. `references/...`). Reference files may link to other reference files for workflow or see-also; avoid long chains.
 5. **Link to live docs** inline where a concept or feature is first mentioned; do not consolidate links in a single section.
 
 ---
@@ -200,13 +210,14 @@ Before merging a new or updated skill, verify:
 - [ ] `name` matches parent directory name exactly
 - [ ] `description` is third person with "Use when..." trigger phrases
 - [ ] SKILL.md body is under 500 lines
-- [ ] All file references are one level deep from SKILL.md
+- [ ] All file references are one level deep from SKILL.md; ref→ref only one-hop (workflow/see-also), no long chains
 - [ ] Reference files over 100 lines have a table of contents at the top
 
 ### Hookdeck conventions
 
 - [ ] Uses correct terminology from the glossary above
 - [ ] When mentioning requests, events, and attempts together, uses order **request → event → attempt** (data flow)
+- [ ] **When to use CLI vs API:** Direct the agent to the right resource based on the task; tasks/simple scripts → CLI, complex scripts/apps/automation → API, when in doubt start with CLI to explore; both querying paths present; main docs for details. Optional: when resource management (sources, destinations, connections, transformations) is in scope, mention the [Terraform provider](https://github.com/hookdeck/terraform-provider-hookdeck) for IaC.
 - [ ] Links to at least one live documentation page
 - [ ] No general webhook/API education that agents already know
 - [ ] No time-sensitive information (dates, version predictions)
@@ -216,6 +227,7 @@ Before merging a new or updated skill, verify:
 ### Quality
 
 - [ ] Provides Hookdeck-specific value (CLI commands, filter syntax, config patterns, URL formats)
+- [ ] **Capability summaries:** Reasonable command/option summaries for discovery; always link to canonical reference (CLI/API docs) for full, current list; avoid exhaustive lists that duplicate docs
 - [ ] Quick examples are copy-pasteable
 - [ ] Decision trees or conditional workflows where multiple paths exist
 - [ ] Cross-references related skills where appropriate

skills/event-gateway/SKILL.md

@@ -46,15 +46,17 @@ When the user asks to verify the Hookdeck signature or build a webhook handler t
 - **Prefer the example codebases in this skill** — they are runnable, proven, and tested. Point the user at the right one for their framework: [examples/express/](examples/express/), [examples/nextjs/](examples/nextjs/), [examples/fastapi/](examples/fastapi/).
 - Do not use third-party webhook libraries; use only the verification code from this skill.
 
-## Workflow Stages
+## Workflow Stages (getting started)
 
-Follow these in order for a new Hookdeck integration:
+This is the recommended path for a new integration: create sources, destinations, and connections (or have the CLI create them via `listen`), then build your handler and iterate. Follow these stages in order:
 
 1. **[01-setup](references/01-setup.md)** -- Create account, install CLI, create connection
 2. **[02-scaffold](references/02-scaffold.md)** -- Build handler from provider skill examples + Hookdeck verification
 3. **[03-listen](references/03-listen.md)** -- Start `hookdeck listen`, trigger test events
 4. **[04-iterate](references/04-iterate.md)** -- Debug failures, fix code, replay events
 
+> **Before any queries or metrics:** Run `hookdeck whoami` and show the user the output. Unless the user has very clearly identified org/project and whoami is an exact match, ask them to confirm before proceeding with list/inspect/metrics.
+
 Stage 02: when the user is working with a provider (Stripe, Shopify, etc.), complete [references/provider-webhooks-checklist.md](references/provider-webhooks-checklist.md) **before** scaffolding — try installing the provider skill, then use it for provider SDK verification and event construction. Include Hookdeck setup and usage in the project README (run app, `hookdeck listen` with `--path`, Source URL for provider).
 
 ## Quick Start (Receive Webhooks)
@@ -73,7 +75,17 @@ hookdeck login
 hookdeck listen 3000 --path /webhooks
 ```
 
-The CLI creates a Source URL, a Destination pointing at `localhost:3000`, and a Connection linking them. Configure your webhook provider to send to the Source URL. Use `--path` to match your handler path (e.g. `--path /webhooks` when your handler is at `POST /webhooks`).
+The CLI creates a Source URL, a Destination pointing at `localhost:3000`, and a Connection linking them. Configure your webhook provider to send to the Source URL. Use `--path` to match your handler path (e.g. `--path /webhooks` when your handler is at `POST /webhooks`). For a full step-by-step with account and handler (create connection, scaffold, listen, iterate), follow the **Workflow Stages** above.
+
+## Context verification (organization and project)
+
+**Before running any queries or metrics**, verify you are on the correct [organization and project](https://hookdeck.com/docs/projects). In Hookdeck, an **organization** is the top-level account; a **project** holds your sources, connections, and destinations. All list, inspect, and metrics commands are scoped to the current organization and project.
+
+1. Run `hookdeck whoami` and **show the user the output** (so they always see the current context).
+2. **Unless** the user has very clearly identified the organization and project (e.g. "use prod org, default project") and whoami shows an **exact match**, ask them to confirm this is the correct organization and project before running any queries or metrics.
+3. If wrong (or user says so), list options with `hookdeck project list`, switch with `hookdeck project use <org-name> <project-name>`, run `hookdeck whoami` again, show the output, and—unless there's a clear user-specified match—ask the user to confirm again.
+
+See [references/cli-workflows.md](references/cli-workflows.md#project-management) for details.
 
 **Production:** Two options. **(1) Same project:** Keep the same project and connections; update the [Destination](https://hookdeck.com/docs/destinations) to your production HTTPS endpoint (e.g. `https://api.example.com/webhooks`) via the [Dashboard](https://dashboard.hookdeck.com) or [API](https://hookdeck.com/docs/api). **(2) New project:** Create a [new project](https://hookdeck.com/docs/projects) in Hookdeck and duplicate your setup (Sources, Connections) with Destinations pointing to your production HTTPS URLs. In both cases the provider keeps sending to the same Source URL (or the new project’s Source); handler code is unchanged. Before going live, consider: **rate limiting / max delivery rate** ([Destinations](https://hookdeck.com/docs/destinations)), **configuring retries** ([Retries](https://hookdeck.com/docs/retries)), and **issue notifications** ([Issue triggers](https://hookdeck.com/docs/issue-triggers), [Issues & Notifications](https://hookdeck.com/docs/issues)). Hookdeck docs are the source of truth; see [Receive webhooks quickstart — Deliver to production](https://hookdeck.com/docs/use-cases/receive-webhooks/quickstart#deliver-to-your-production-webhook-endpoint) and the linked Destinations, Retries, and Issue triggers docs for the full production checklist.
 
@@ -98,11 +110,19 @@ Use as needed (not sequential):
 
 ### Development & Operations
 
+Direct yourself to the right resource based on the task. **Use the CLI first to explore** and for simple tasks; then choose the API or Terraform when things are more complex. The CLI is a good first touch for tasks and for some analysis; you can use the API for querying too. **Tasks and simple scripts** (single commands or short multi-command workflows from the shell) **→ use the CLI.** **Complex scripts, applications, and automation → use the API.** When in doubt, start with the CLI to explore. For **resource management** (sources, destinations, connections, transformations): use the **API** when resources are created **dynamically** (e.g. from an application at runtime); use **Terraform** or CLI/scripts for **effectively static** definition management (IaC) — [Terraform provider](https://github.com/hookdeck/terraform-provider-hookdeck). For details on performing querying, metrics, or inspection (either path), see the main documentation.
+
 | Area | Resource | When to use |
 |------|----------|-------------|
-| CLI | [references/cli-workflows.md](references/cli-workflows.md) | CLI installation, connection management, project switching |
-| API | [references/api-patterns.md](references/api-patterns.md) | REST API automation, bulk operations, publish |
-| Monitoring | [references/monitoring-debugging.md](references/monitoring-debugging.md) | Failed deliveries, event lifecycle, troubleshooting |
+| **Context verification** (organization and project) | `hookdeck whoami` → **show output**; confirm with user unless they clearly specified org/project and it matches | Run whoami and show the result; ask for confirmation before queries/metrics unless user clearly identified org/project and whoami matches; see [references/cli-workflows.md](references/cli-workflows.md#project-management) |
+| **Resources** (sources, destinations, connections, transformations) | [references/01-setup.md](references/01-setup.md), [references/cli-workflows.md](references/cli-workflows.md) | First connection or adding/changing sources, destinations, connections, transformations: 01-setup for initial setup; cli-workflows for CLI create/upsert; [Sources](https://hookdeck.com/docs/sources), [Destinations](https://hookdeck.com/docs/destinations), [Connections](https://hookdeck.com/docs/connections), [Transformations](https://hookdeck.com/docs/transformations) for full reference |
+| Monitoring | [references/monitoring-debugging.md](references/monitoring-debugging.md#monitoring) | Event lifecycle, where to observe (TUI, Dashboard) |
+| Debugging | [references/monitoring-debugging.md](references/monitoring-debugging.md#debugging) | Troubleshooting, issues, replay |
+| Querying (CLI) | [references/monitoring-debugging.md](references/monitoring-debugging.md#cli-querying) | List, inspect, retry request/event/attempt; detailed search; main docs for details |
+| Metrics (CLI) | [references/monitoring-debugging.md](references/monitoring-debugging.md#cli-metrics) | Event volume, failure rates, backlog; aggregated view; main docs for details |
+| CLI | [references/cli-workflows.md](references/cli-workflows.md) | Install, listen, connection/resource management, project switching |
+| API | [references/api-patterns.md](references/api-patterns.md) | Querying; building apps; **dynamic** resource creation (e.g. app creating sources/connections at runtime); complex scripts; main docs for details |
+| Terraform | [terraform-provider-hookdeck](https://github.com/hookdeck/terraform-provider-hookdeck) | **Static** resource management (sources, destinations, connections, transformations) as IaC; [Registry docs](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs) |
 | Iterate | [references/04-iterate.md](references/04-iterate.md) | Debug failures, replay events, CLI inspect/retry workflow |
 
 ### Verification Code

skills/event-gateway/references/04-iterate.md

@@ -103,4 +103,4 @@ curl -X POST https://api.hookdeck.com/$API_VERSION/events/{event_id}/retry \
   -H "Authorization: Bearer $HOOKDECK_API_KEY"
 ```
 
-See [api-patterns.md](api-patterns.md) for full API patterns and [referencing-docs.md](referencing-docs.md) for the API version.
+See [API Patterns](api-patterns.md) for an overview of common uses of the Hookdeck Event Gateway API. See the [API docs](https://hookdeck.com/docs/api.md) for full API details. To see how to reference documentation and a general overview of key available docs, see [referencing-docs.md](referencing-docs.md).

skills/event-gateway/references/api-patterns.md

@@ -137,8 +137,8 @@ curl "https://api.hookdeck.com/$API_VERSION/events?limit=25&next=cursor_xxx" \
 
 ## Documentation
 
-- [API overview](https://hookdeck.com/docs/api)
-- [Connections API](https://hookdeck.com/docs/api/connections)
-- [Inspect API (requests, events, attempts)](https://hookdeck.com/docs/api/inspect)
-- [Bulk operations](https://hookdeck.com/docs/api/bulk)
-- [Publish API](https://hookdeck.com/docs/api/publish)
+- [API overview](https://hookdeck.com/docs/api.md)
+- [Connections API](https://hookdeck.com/docs/api/connections.md)
+- [Inspect API (requests, events, attempts)](https://hookdeck.com/docs/api/inspect.md)
+- [Bulk operations](https://hookdeck.com/docs/api/bulk.md)
+- [Publish API](https://hookdeck.com/docs/api/publish.md)