vanara 0.1.0 → 0.3.0

package/catalog/packs/security-pack/PACK.md

@@ -0,0 +1,128 @@
+---
+name: security-pack
+description: Build and ship secure software — threat modeling at design time, OWASP code audits, dependency/secret scanning, and secure auth and secrets handling, sequenced into one shift-left workflow.
+type: pack
+version: 2.0.0
+updated: 2026-07-06
+agents: [threat-modeler, security-auditor, vuln-scanner]
+skills: [owasp-top10, secure-auth, secrets-management]
+---
+# Security Pack
+
+Security is cheapest when it moves **left** — designed in at the whiteboard, enforced while the code
+is written, verified before merge, and monitored in the supply chain. This pack bundles three agents
+and three skills that cover that whole arc and, more importantly, teaches **which one to reach for at
+each stage of a feature's life**.
+
+The value of a pack is not the list of items — it is the sequencing. A threat model with no audit is
+a document nobody enforces; an audit with no threat model is a checklist with no context. This
+document ties them into one repeatable loop: **model → build → audit → scan → ship**.
+
+## Who this is for
+
+- Security engineers who own the security posture of a product or service.
+- Developers who own the security of the features they build — the ones expected to threat-model,
+  self-audit, and keep their dependencies clean before asking for review.
+- Tech leads introducing a shift-left practice to a team that currently bolts security on at the end.
+
+If you only need a one-off review of an existing diff, the `security-auditor` agent alone is enough.
+Reach for the full pack when you are carrying a feature **from design through to a clean merge** and
+want security enforced at every handoff instead of a single gate at the finish line.
+
+## What's included
+
+| Item | Kind | Job in the workflow |
+|---|---|---|
+| `threat-modeler` | agent | STRIDE-style threat modeling at design time — enumerate attack surface, trust boundaries, and abuse cases before code exists |
+| `security-auditor` | agent | OWASP-focused code review of the diff — injection, auth flaws, broken access control, unsafe crypto |
+| `vuln-scanner` | agent | Dependency CVE scanning and secret detection across the tree and git history |
+| `owasp-top10` | skill | Per-risk defenses for the OWASP Top 10 — the reference the auditor and you apply |
+| `secure-auth` | skill | Correct password hashing, session/token handling, and MFA construction |
+| `secrets-management` | skill | Keep secrets out of source, load them safely, and rotate without downtime |
+
+Agents *do* the work; skills are the *reference* they (and you) apply while doing it. Pair an agent
+with its matching skill — `security-auditor` + `owasp-top10`, or building auth with `secure-auth` —
+so the output is both produced and grounded in a standard.
+
+## The end-to-end workflow
+
+A secure feature moves through five stages. The pack maps one primary item to each:
+
+```text
+1. Model   → threat-modeler   (+ owasp-top10)        enumerate threats before code
+2. Build   → secure-auth / secrets-management        implement the risky parts correctly
+3. Audit   → security-auditor (+ owasp-top10)        review the diff, security-first
+4. Scan    → vuln-scanner                            CVEs in deps + secrets in the tree
+5. Ship    → gate on: no open CRITICAL/HIGH, clean scan
+```
+
+Model **first**, before any code. A threat model produced after the feature is built is a
+rationalization, not a design tool — its whole purpose is to change what you build. The threats it
+surfaces become the audit checklist in stage 3 and the abuse-case tests you write while building.
+
+### Worked example: adding "password reset via email link"
+
+```text
+threat-modeler   → surfaces: token guessability, token reuse/replay, host-header poisoning in the
+                   reset link, user enumeration on the "email sent" response, rate-limit bypass
+owasp-top10      → maps those to A01 (access control), A07 (auth failures), A04 (insecure design)
+secure-auth      → reset token = 256-bit random, single-use, 15-min TTL, hashed at rest; response is
+                   identical whether or not the email exists (no enumeration)
+secrets-management → the email-provider API key is loaded from the secret store, never in the repo
+security-auditor → confirms token is compared in constant time, is invalidated on use, and the
+                   "sent" response leaks nothing; flags the missing rate limit as HIGH
+vuln-scanner     → the email SDK pulls a transitive dep with a known SSRF CVE — flagged, bump required
+```
+
+Every item earned its place: the threat model set the agenda, the skills shaped the implementation,
+the auditor verified it, and the scanner caught a supply-chain issue no human review would have.
+
+## How to choose the right item
+
+- **Designing a feature that touches auth, money, or user data?** `threat-modeler` + `owasp-top10`
+  first — enumerate abuse cases before a line is written.
+- **Implementing login, sessions, or MFA?** `secure-auth` — do not hand-roll password hashing or
+  token generation.
+- **About to reference a credential, key, or token?** `secrets-management` — it never belongs in
+  source, config committed to git, or a client bundle.
+- **Diff ready for review?** `security-auditor` — security pass before correctness, every time.
+- **Before merge, always?** `vuln-scanner` — CVEs and leaked secrets are invisible to code review.
+
+See `references/choosing-the-right-tool.md` for the full decision table, `references/workflow.md` for
+the stage-by-stage playbook, and `references/threat-model-to-remediation.md` for the discipline
+playbook that connects a threat model to concrete fixes. Two complete runs are in `examples/`.
+
+## Common pitfalls (anti-patterns this pack prevents)
+
+- **Threat-modeling after the build.** A model written to justify existing code enumerates the
+  threats you already handled and misses the ones you didn't. The workflow puts it at stage 1 so it
+  can actually change the design.
+- **Auditing without a threat model.** A generic OWASP checklist misses domain abuse cases (e.g. a
+  refund flow that can go negative). The threat model *is* the audit's context.
+- **Treating secret scanning as one-time.** A secret committed once lives in git history forever even
+  after it's deleted from HEAD. `vuln-scanner` checks history, and the fix is rotation, not just
+  removal.
+- **Rolling your own crypto/auth.** Hand-rolled password hashing, JWT verification, or token
+  comparison is a reliable source of criticals. `secure-auth` points to vetted constructions.
+- **Fixing the secret, forgetting to rotate.** Deleting a leaked key from source does not un-leak it.
+  Any exposed secret must be rotated, not just removed.
+
+## When NOT to use this pack
+
+- **Compliance/audit-trail work** (GDPR, SOC 2 evidence) — that's `compliance-auditor` and the
+  privacy/audit-logging skills, not this pack's application-security focus.
+- **Infrastructure and network hardening** — firewall rules, TLS termination, and cloud IAM are
+  DevOps/network territory, not application-code security.
+- **A one-line, no-risk change** — a copy tweak or a CSS fix does not need a threat model; a single
+  `security-auditor` pass (or nothing) is proportionate.
+- **Smart-contract security** — use `smart-contract-auditor` and `smart-contract-security`; the
+  threat surface there is different.
+
+## Files in this package
+
+- `references/workflow.md` — the five-stage security workflow in detail, with entry/exit criteria.
+- `references/choosing-the-right-tool.md` — full decision table: symptom → item.
+- `references/threat-model-to-remediation.md` — the discipline playbook connecting STRIDE threats to
+  audited, tested remediations.
+- `examples/threat-model-then-audit.md` — a feature threat-modeled at design time, then audited.
+- `examples/owasp-vuln-triage-and-fix.md` — an OWASP-class vulnerability triaged and remediated.

package/catalog/packs/security-pack/examples/owasp-vuln-triage-and-fix.md

@@ -0,0 +1,66 @@
+# Walkthrough: triaging and fixing an OWASP-class vulnerability
+
+Not every task starts at design time. This shows the pack applied to a vulnerability found in
+existing code — where `security-auditor` leads and the workflow compresses.
+
+## The finding
+
+A routine `security-auditor` pass on a diff flags:
+
+```md
+### CRITICAL
+- `api/documents.js:73` — GET /documents/:id loads the record by id and returns it with no check
+  that the document belongs to the requesting user. Any authenticated user can read any document by
+  guessing/enumerating ids. (A01 Broken Access Control — IDOR)
+```
+
+Intermittent guessing isn't needed — the ids are sequential integers, so this is trivially
+enumerable. CRITICAL is correct.
+
+## Classify (`owasp-top10`)
+
+This is **A01 Broken Access Control**, the IDOR variant: the endpoint authenticates ("are you logged
+in?") but does not authorize ("is this *your* document?"). The reference is clear — authorization must
+be checked server-side against the resource owner on every request, deny-by-default.
+
+## Reproduce as a failing test first (`security-auditor` direction)
+
+Before touching the handler, lock the bug down as a regression test:
+
+```text
+✗ user B requesting user A's document id receives 404, not 200 + the document
+```
+
+It fails against current code — confirming the vulnerability and giving the fix a target. (404, not
+403, so the endpoint doesn't confirm the id exists — avoids the enumeration side channel too.)
+
+## Fix the access-control check
+
+Add the ownership guard *before* the record is returned:
+
+```text
+const doc = await Documents.findById(id);
+if (!doc || doc.ownerId !== session.userId) return res.status(404).end();
+return res.json({ data: doc, error: null });
+```
+
+The check runs for every request and denies by default. Test goes green. A grep for the same pattern
+across sibling routes (`/documents/:id/download`, `/documents/:id/versions`) confirms whether the same
+gap exists elsewhere — IDOR is rarely a single-endpoint problem.
+
+## Re-audit + scan (`security-auditor` + `vuln-scanner`)
+
+- `security-auditor` re-reviews: the guard is present on all three routes, the 404 leaks nothing, no
+  new finding introduced.
+- `vuln-scanner` runs on the branch: dependencies clean, no secret introduced by the change.
+
+## Ship
+
+CRITICAL closed, sibling routes patched, regression tests in place, scan clean. The fix ships.
+
+## The lesson
+
+The pack turned a single flagged line into a *class* fix: classify the vulnerability (A01/IDOR), lock
+it with a failing test, apply the deny-by-default mitigation, then sweep for the same pattern
+elsewhere. Fixing only line 73 would have left the download and versions routes exploitable — the
+OWASP framing is what prompts checking the whole class, not just the reported instance.

package/catalog/packs/security-pack/examples/threat-model-then-audit.md

@@ -0,0 +1,77 @@
+# Walkthrough: threat-modeling "password reset via email", then auditing it
+
+A complete run through the five stages for a classic high-risk feature, showing which pack item leads
+at each point.
+
+## Stage 1 — Model (`threat-modeler` + `owasp-top10`)
+
+Trust boundaries: browser → API → email provider → token store. Walking STRIDE surfaces:
+
+```text
+- Token guessability      → tokens must be cryptographically random (A07)
+- Token reuse / replay     → single-use, short TTL, invalidated on use (A07)
+- Host-header poisoning    → reset link host must not come from the request header (A04)
+- User enumeration         → "email sent" response identical for known/unknown emails (A01)
+- No rate limit            → attacker can brute-force or spam resets (A04/A07)
+```
+
+Each threat is tagged with its OWASP class and a planned mitigation. This list becomes the audit
+agenda.
+
+## Stage 2 — Build (`secure-auth` + `secrets-management`)
+
+Implement against the vetted construction:
+
+- Reset token = 256-bit CSPRNG value, stored **hashed** at rest, single-use, 15-minute TTL.
+- The "we sent you an email" response is byte-identical whether or not the account exists.
+- The reset link's host is built from server config, not the incoming `Host` header.
+- The email-provider API key is loaded from the secret store via `secrets-management` — it never
+  appears in source or committed config.
+
+Abuse-case tests are written alongside:
+
+```text
+✗ a used reset token cannot be redeemed a second time
+✗ /forgot-password returns the same body for known and unknown emails
+✗ /forgot-password returns 429 after 5 attempts in the window
+```
+
+Implement until green.
+
+## Stage 3 — Audit (`security-auditor` + `owasp-top10`)
+
+The auditor reviews the diff against the stage-1 list:
+
+```md
+### HIGH
+- `auth/reset.js:41` — token compared with `===`; use a constant-time compare to avoid a timing
+  oracle on the token value.
+- `auth/reset.js:12` — no rate limiter on the request-reset endpoint (threat listed in the model,
+  not yet implemented). Add per-IP + per-account throttling.
+
+### LOW
+- `auth/reset.js:58` — TTL is 60 min; model called for 15. Tighten.
+```
+
+The timing-compare and rate-limit findings are fixed and re-reviewed. No CRITICAL/HIGH remains.
+
+## Stage 4 — Scan (`vuln-scanner`)
+
+```text
+CVE: email-sdk@2.3.0 → transitive dep `node-fetch@2.6.1` has a known SSRF advisory.
+     Fix: bump to email-sdk@2.4.1 (pulls patched fetch).
+Secrets: none in tree; git history clean.
+```
+
+Dependency bumped; scan re-run clean.
+
+## Stage 5 — Ship
+
+Audit clean, scan clean, no committed secret. The feature ships with its abuse-case tests as
+permanent regression guards.
+
+## The lesson
+
+The threat model did the heavy lifting: it predicted the rate-limit gap and the enumeration risk
+*before* code existed, and it gave the auditor a precise agenda. Without it, stage 3 would have been a
+generic pass that could easily have missed the missing rate limiter.

package/catalog/packs/security-pack/references/choosing-the-right-tool.md

@@ -0,0 +1,37 @@
+# Choosing the right item: symptom → tool
+
+When you're mid-feature and not sure what to reach for, match the symptom to the item.
+
+| Symptom / task | Reach for | Why |
+|---|---|---|
+| "New feature touches auth, money, or PII" | `threat-modeler` + `owasp-top10` | Enumerate abuse cases before code exists |
+| "Which OWASP risk applies here?" | `owasp-top10` | The per-risk defense reference |
+| "I'm building login / sessions / MFA" | `secure-auth` | Vetted hashing, tokens, session handling |
+| "I need to reset passwords / issue tokens" | `secure-auth` | Single-use, TTL'd, constant-time compared |
+| "Where does this API key / credential go?" | `secrets-management` | Never in source; loaded from a store |
+| "Diff is ready for review" | `security-auditor` + `owasp-top10` | Security-first code review before merge |
+| "Is a dependency vulnerable?" | `vuln-scanner` | CVEs, including transitive, are invisible to review |
+| "Did a secret get committed?" | `vuln-scanner` | Scans tree *and* git history |
+| "A secret leaked — now what?" | `secrets-management` | Rotate, don't just delete |
+
+## Agent + skill pairings
+
+Each agent has a natural skill partner. Use them together:
+
+- `threat-modeler` + `owasp-top10` — enumerate threats *and* tag each with the risk category that
+  drives its defense.
+- `security-auditor` + `owasp-top10` — the auditor reviews against a concrete Top 10 checklist rather
+  than a vibe.
+- Building auth or handling secrets — apply `secure-auth` / `secrets-management` *while writing*, not
+  as an afterthought the auditor has to catch.
+
+## Escalation boundaries
+
+- Regulatory/compliance evidence (GDPR, SOC 2, audit trails) → `compliance-auditor` and the
+  privacy/audit-logging skills, not this pack.
+- Infrastructure, network, TLS, and cloud IAM hardening → DevOps/network specialists; this pack is
+  application-code security.
+- Smart-contract vulnerabilities → `smart-contract-auditor` + `smart-contract-security`; the threat
+  surface differs from web app security.
+- A CVE with no available patch → this is a risk-acceptance decision (document + mitigate), not
+  something `vuln-scanner` resolves for you.

package/catalog/packs/security-pack/references/threat-model-to-remediation.md

@@ -0,0 +1,69 @@
+# From threat model to remediation: the discipline playbook
+
+A threat model only pays off if its threats become fixes. This playbook is the connective tissue
+between `threat-modeler`'s output and a clean `security-auditor` pass — how a STRIDE finding turns
+into a mitigation, a test, and an audited change.
+
+## Step 1 — Enumerate with STRIDE (`threat-modeler`)
+
+Walk each trust boundary in the feature and ask the six STRIDE questions. For every "yes", write a
+one-line abuse case in the attacker's voice:
+
+```text
+Spoofing        → "I replay another user's session token to act as them."
+Tampering       → "I change the price field in the checkout request."
+Repudiation     → "I perform a refund and there's no log tying it to me."
+Info disclosure → "The error response tells me whether an email is registered."
+DoS             → "I hit the reset endpoint 10k times with no rate limit."
+Elevation       → "I call the admin endpoint with a normal user's token."
+```
+
+## Step 2 — Classify and prioritize (`owasp-top10`)
+
+Tag each abuse case with its OWASP category and a severity driven by *impact × likelihood*:
+
+| Abuse case | OWASP | Severity |
+|---|---|---|
+| Session token replay | A07 Auth failures | HIGH |
+| Price tampering | A04 Insecure design / A08 | CRITICAL |
+| Missing refund audit log | A09 Logging failures | MEDIUM |
+| Email enumeration | A01 Access control | MEDIUM |
+| No rate limit on reset | A04 / A07 | HIGH |
+| Privilege escalation | A01 Broken access control | CRITICAL |
+
+Fix CRITICAL/HIGH before shipping; schedule MEDIUM/LOW with an owner.
+
+## Step 3 — Design the mitigation (skills)
+
+Each category has a known defense — reach for the skill, don't improvise:
+
+- Access control (A01) → deny by default; authorize every request server-side against the *resource
+  owner*, not just "is logged in".
+- Auth failures (A07) → `secure-auth`: strong hashing, single-use tokens, constant-time compare,
+  rotate on privilege change.
+- Insecure design (A04) → re-derive trusted values (price, role) server-side; never trust the client.
+- Sensitive data (A02) → `secrets-management` for keys; encrypt at rest; identical responses to
+  prevent enumeration.
+
+## Step 4 — Test the abuse case, then implement
+
+Turn each abuse case into a failing test *first*, so the fix has a target and a regression guard:
+
+```text
+✗ a request with user B's token cannot mutate user A's resource   (A01)
+✗ POST /checkout ignores a client-supplied price field            (A04)
+✗ /password-reset returns 429 after N attempts per window         (A07)
+```
+
+Implement until green. The test now permanently encodes the threat.
+
+## Step 5 — Audit and scan (`security-auditor` + `vuln-scanner`)
+
+Hand the diff to `security-auditor` with the stage-2 severity table as the agenda — it verifies each
+mitigation is present and correct, citing `file:line`. Then `vuln-scanner` sweeps dependencies and
+history. Ship only when the CRITICAL/HIGH rows are all closed and the scan is clean.
+
+## The through-line
+
+Threat → OWASP class → mitigation skill → failing abuse-case test → audited fix. When a finding
+skips a step — a threat with no test, or a fix with no audit — that's where regressions re-enter.

package/catalog/packs/security-pack/references/workflow.md

@@ -0,0 +1,56 @@
+# The five-stage security workflow
+
+Each stage has an owner (the primary item), the skills it applies, and an explicit **exit criterion**
+— you don't advance until the criterion is met. This is what keeps security from collapsing into a
+single rushed review at the end.
+
+## Stage 1 — Model
+
+- **Owner:** `threat-modeler` · **Applies:** `owasp-top10`
+- Draw the trust boundaries (client, server, third parties, data store). For each boundary, walk
+  STRIDE — Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of
+  privilege — and write down the concrete abuse cases for *this* feature.
+- Map each threat to its OWASP Top 10 category so the audit later has a checklist.
+- **Exit criterion:** a written list of threats, each tagged with an OWASP category and a planned
+  mitigation, that the build and audit stages can reference.
+
+## Stage 2 — Build
+
+- **Owners:** `secure-auth`, `secrets-management` (as the feature demands)
+- Implement the risk-bearing parts against a vetted construction, not from memory. Auth: correct
+  hashing, single-use tokens, constant-time comparison, no user enumeration. Secrets: loaded from a
+  store or environment, never committed, never shipped to the client.
+- Write the abuse-case tests from stage 1 alongside the implementation.
+- **Exit criterion:** the risky paths are implemented per the skills' guidance and the abuse-case
+  tests pass.
+
+## Stage 3 — Audit
+
+- **Owner:** `security-auditor` · **Applies:** `owasp-top10`
+- Review the diff security-first, using the stage-1 threat list as the agenda: broken access control
+  (IDOR/authorization), injection, auth failures, unsafe crypto, sensitive-data exposure. Every
+  finding cites `file:line`, a severity, and a concrete fix.
+- **Exit criterion:** no CRITICAL or HIGH finding remains open.
+
+## Stage 4 — Scan
+
+- **Owner:** `vuln-scanner`
+- Scan dependencies (including transitive) for known CVEs, and scan the working tree **and git
+  history** for secrets. A secret found in history is treated as exposed even if HEAD is clean.
+- **Exit criterion:** no unaddressed CVE at High/Critical severity; no secret in tree or history
+  (removal alone is insufficient for a real leak — see below).
+
+## Stage 5 — Ship
+
+- **Gate:** no open CRITICAL/HIGH audit finding, clean dependency scan, no committed secret.
+- If a secret was ever exposed, it is **rotated**, not merely deleted. If a CVE has no patch,
+  document the risk acceptance or apply a mitigating control before shipping.
+- **Exit criterion:** all gates green; any accepted risk is written down with an owner.
+
+## Why order matters
+
+The threat model is the shared dependency of every later stage — it sets what to build carefully in
+stage 2 and what to look for in stage 3. Building before modeling means you protect the wrong things.
+Auditing before scanning means you can pass human review while a vulnerable dependency or a leaked key
+sits in the tree. Skipping or reordering stages is the single biggest source of shipped
+vulnerabilities.

package/catalog/skills/api-pagination/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: api-pagination
+description: Implement correct, fast API pagination — cursor vs offset trade-offs, opaque cursor encoding, stable sort keys, page-size limits, total-count costs, and consumer-side iteration that survives inserts, deletes, and retries. With runnable cursor checks.
+type: skill
+version: 1.0.0
+updated: 2026-07-10
+---
+# API Pagination
+
+Pagination looks trivial until data changes underneath the reader. Offset pagination silently
+**skips or duplicates rows** when inserts land mid-iteration; cursor pagination survives churn but
+demands a stable sort key and an opaque token contract. This skill covers both sides: designing the
+API and consuming one correctly. Deep detail lives in `references/`; copy-paste material in
+`examples/`; a runnable cursor round-trip check in `scripts/`.
+
+## Decision: offset vs cursor
+
+| Situation | Use |
+|---|---|
+| Admin tables, small datasets, "jump to page 7" required | Offset (`LIMIT/OFFSET`) |
+| Feeds, sync endpoints, anything users scroll | Cursor (keyset) |
+| Data changes while clients iterate | Cursor — offset will skip/duplicate |
+| Deep pages (offset > ~10k rows) | Cursor — `OFFSET n` scans and discards n rows |
+
+Offset's failure mode is correctness, not just speed: a row inserted before your current position
+shifts everything, so page 3 re-shows an item from page 2 (duplicate) or swallows one (skip).
+
+## Keyset mechanics (the part people get wrong)
+
+The sort key must be **unique and immutable**. `created_at` alone is not unique — two rows with the
+same timestamp make the cursor ambiguous and rows vanish. Always add a tiebreaker:
+
+```sql
+-- WHERE clause for "next page after (2026-07-01T12:00:00Z, id 4711)" descending
+SELECT * FROM items
+WHERE (created_at, id) < ('2026-07-01T12:00:00Z', 4711)
+ORDER BY created_at DESC, id DESC
+LIMIT 51;  -- page_size + 1 to detect has_more without COUNT(*)
+```
+
+Fetch `page_size + 1` rows: if you get 51, there is a next page and the 51st row's key becomes the
+next cursor. This avoids `COUNT(*)`, which on large tables costs more than the page itself
+(see `references/counting-and-totals.md`).
+
+## Cursor token contract
+
+Cursors are **opaque to clients** — never let them parse or build one. Encode the keyset values plus
+the sort direction, base64url it, and (for public APIs) HMAC it so tampering is detectable. Include a
+version byte so you can change the encoding later. Full recipe: `references/cursor-encoding.md`;
+runnable round-trip: `scripts/check-cursor.mjs`.
+
+## Response envelope
+
+```json
+{
+  "data": [ ... ],
+  "page_info": { "has_more": true, "next_cursor": "djEuMj..." }
+}
+```
+
+Rules: `next_cursor` is absent (not empty-string) on the last page; page size is capped server-side
+(a `limit=10000` request gets the cap, documented, not an error); the default page size appears in
+the docs and never changes silently. Consumer-side iteration rules — retries, cursor expiry,
+resumption — live in `references/consuming-pages.md`.
+
+## Pitfalls
+
+- **Mutable sort keys** (`updated_at`) — rows teleport across pages as they update. Sort on immutable
+  columns or accept re-delivery and dedupe client-side.
+- **Cursor built from row position** instead of row values — it is offset with extra steps and
+  inherits every offset bug.
+- **`COUNT(*)` on every page** — the count is stale by the time the client renders it; provide totals
+  on a separate, cacheable endpoint if the product truly needs them.
+- **Breaking cursor encoding on deploy** — clients hold cursors across releases; version the token.
+- **Missing composite index** — keyset needs an index on exactly `(created_at, id)` in sort order, or
+  every page is a scan.
+
+## Verification
+
+Run `node scripts/check-cursor.mjs` — encodes, decodes, tampers, and versions a cursor and asserts
+every property above. For the SQL side, `examples/keyset-queries.sql` includes an `EXPLAIN` you can
+run to confirm the index is used. Pairs with `rest-api-design` (envelopes, limits) and
+`sql-index-tuning` (composite indexes).

package/catalog/skills/api-pagination/examples/keyset-queries.sql

@@ -0,0 +1,38 @@
+-- Keyset pagination: canonical queries (Postgres syntax).
+
+-- The supporting index. Column order and direction must match the ORDER BY exactly.
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_items_created_id
+  ON items (created_at DESC, id DESC);
+
+-- Page 1 (no cursor): newest first, page_size 50, +1 row to detect has_more.
+SELECT id, created_at, title
+FROM items
+WHERE tenant_id = $1
+ORDER BY created_at DESC, id DESC
+LIMIT 51;
+
+-- Page N (cursor decoded to ($2 = created_at, $3 = id) of the last row seen).
+-- Row-value comparison keeps the composite ordering correct in one clause.
+SELECT id, created_at, title
+FROM items
+WHERE tenant_id = $1
+  AND (created_at, id) < ($2, $3)
+ORDER BY created_at DESC, id DESC
+LIMIT 51;
+
+-- Verify the index is used (look for "Index Scan ... idx_items_created_id",
+-- no Sort node, and rows examined ≈ LIMIT):
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT id, created_at, title
+FROM items
+WHERE tenant_id = $1 AND (created_at, id) < (now(), 2147483647)
+ORDER BY created_at DESC, id DESC
+LIMIT 51;
+
+-- Ascending variant (jump-to-oldest without deep offsets): flip both the
+-- comparison and the sort, same index scanned backwards.
+SELECT id, created_at, title
+FROM items
+WHERE tenant_id = $1 AND (created_at, id) > ($2, $3)
+ORDER BY created_at ASC, id ASC
+LIMIT 51;

package/catalog/skills/api-pagination/examples/response-shapes.md

@@ -0,0 +1,51 @@
+# Response Shapes
+
+## Cursor-paginated list (recommended default)
+
+```json
+{
+  "data": [
+    { "id": "itm_9x2", "created_at": "2026-07-01T12:00:00.412Z", "title": "..." }
+  ],
+  "page_info": {
+    "has_more": true,
+    "next_cursor": "v1.eyJrIjpbIjIwMjYt...IsNDcxMV0sImQiOiJkZXNjIn0.3f9a1c22b0"
+  }
+}
+```
+
+Last page: `has_more: false` and **no** `next_cursor` key. Clients must treat absence — not
+empty string, not null — as the terminal signal (document exactly one convention and test it).
+
+## Offset-paginated list (admin/small data only)
+
+```json
+{
+  "data": [ ... ],
+  "page_info": { "page": 3, "per_page": 50, "total": 1204, "total_pages": 25 }
+}
+```
+
+Only ship `total`/`total_pages` when the dataset is small enough that COUNT is cheap and the
+product genuinely offers page jumping.
+
+## Request parameters
+
+```
+GET /v1/items?limit=50&cursor=v1.eyJr...          # cursor flow
+GET /v1/admin/items?page=3&per_page=50            # offset flow
+```
+
+- `limit` capped server-side (e.g., max 200); over-cap requests get the cap, not an error.
+- Filters/sort are request parameters, never encoded inside the cursor — but changing them
+  mid-iteration invalidates the cursor (return `CURSOR_INVALID`, client restarts).
+
+## Error shapes
+
+```json
+{ "error": { "code": "CURSOR_EXPIRED", "message": "Restart iteration from the beginning." } }
+{ "error": { "code": "CURSOR_INVALID", "message": "Cursor is malformed or filters changed." } }
+```
+
+Both are 400s. Clients restart from their last durable checkpoint; idempotent processing absorbs
+the overlap.

package/catalog/skills/api-pagination/references/consuming-pages.md

@@ -0,0 +1,39 @@
+# Consuming Paginated APIs Correctly
+
+The consumer side has its own failure modes: partial iteration on crash, duplicate processing on
+retry, and silent stalls when a provider changes page semantics.
+
+## The iteration loop
+
+```js
+let cursor = savedCheckpoint ?? null;
+do {
+  const page = await get('/items', { cursor, limit: 100 });
+  for (const item of page.data) await processIdempotently(item);
+  cursor = page.page_info.next_cursor ?? null;
+  await saveCheckpoint(cursor);          // AFTER processing the page
+} while (cursor);
+```
+
+Rules encoded above:
+
+- **Checkpoint the cursor, not the item index.** Persist `next_cursor` after each fully processed
+  page; on restart, resume from the checkpoint instead of page one.
+- **Process idempotently.** At-least-once is the reality: a crash between processing and
+  checkpointing replays the page. Dedupe on item ID exactly like a webhook consumer.
+- **Loop on `next_cursor` presence, not on `data.length > 0`.** Some providers return short or
+  empty pages mid-stream (filtered rows); an empty page with a cursor is NOT the end.
+- **Bound the loop.** A provider bug that returns the same cursor forever becomes your infinite
+  loop; track `pages_fetched` against a sane ceiling and alert past it.
+
+## Retry semantics
+
+Page fetches are GETs — safe to retry with backoff. But a `CURSOR_EXPIRED` or `CURSOR_INVALID`
+response is not retryable: restart the iteration from your last durable checkpoint (or from
+scratch) and rely on idempotent processing to absorb the overlap.
+
+## Rate limits and burst shape
+
+Full-table syncs hammer providers. Respect `Retry-After` on 429s, spread scheduled syncs with
+jitter, and prefer provider-side incremental endpoints (`updated_since=`) over re-walking
+everything — pagination is for the backfill, deltas are for steady state.