rsc-universal 0.1.1

package/skills/duckdb/scripts/verify.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — duckdb skill smoke test. Run from anywhere.
+#
+# Proves the documented DuckDB commands actually execute on the installed version:
+#   1. Prefer the `duckdb` CLI if on PATH; else `python3 -c "import duckdb"`.
+#   2. If NEITHER is available -> print SKIP and exit 0 (never a false failure).
+#   3. Otherwise: generate a tiny CSV in a temp dir, run an aggregate over a VALUES
+#      table AND over read_csv_auto on that file, and assert both equal a known scalar.
+#
+# Read-only with respect to your project: it only writes inside a private mktemp dir,
+# which it removes on exit. No network, no large downloads, deterministic.
+#
+# Exit code: 0 on pass or skip; non-zero ONLY when DuckDB is present but a documented
+# command returns the wrong scalar (a real regression).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+
+TMP="$(mktemp -d 2>/dev/null || mktemp -d -t duckdb_verify)"
+cleanup() { rm -rf "$TMP"; }
+trap cleanup EXIT
+
+CSV="$TMP/sales.csv"
+printf 'region,amount\nEU,10\nEU,20\nUS,30\n' > "$CSV"
+# Known answers: total sum = 60; EU sum = 30.
+
+run_cli() {
+  # Aggregate over an inline VALUES table (no file): expect 60.
+  local a b
+  a="$(duckdb -noheader -list -c \
+        "SELECT sum(amount) FROM (VALUES (10),(20),(30)) AS t(amount)" 2>/dev/null)"
+  # Aggregate over the generated CSV via read_csv_auto, filtered to EU: expect 30.
+  b="$(duckdb -noheader -list -c \
+        "SELECT sum(amount) FROM read_csv_auto('$CSV') WHERE region = 'EU'" 2>/dev/null)"
+  [ "$a" = "60" ] && [ "$b" = "30" ]
+}
+
+run_py() {
+  python3 - "$CSV" <<'PY'
+import sys, duckdb
+csv = sys.argv[1]
+a = duckdb.sql("SELECT sum(amount) FROM (VALUES (10),(20),(30)) AS t(amount)").fetchone()[0]
+b = duckdb.sql(f"SELECT sum(amount) FROM read_csv_auto('{csv}') WHERE region = 'EU'").fetchone()[0]
+sys.exit(0 if (a == 60 and b == 30) else 1)
+PY
+}
+
+if command -v duckdb >/dev/null 2>&1; then
+  if run_cli; then
+    ok "duckdb CLI: VALUES aggregate = 60 and read_csv_auto(EU) = 30"
+    exit 0
+  else
+    err "duckdb CLI ran but returned an unexpected scalar"
+    exit 1
+  fi
+elif command -v python3 >/dev/null 2>&1 && python3 -c "import duckdb" >/dev/null 2>&1; then
+  if run_py; then
+    ok "python duckdb: VALUES aggregate = 60 and read_csv_auto(EU) = 30"
+    exit 0
+  else
+    err "python duckdb ran but returned an unexpected scalar"
+    exit 1
+  fi
+else
+  skip "neither the duckdb CLI nor the python duckdb module is installed — nothing to verify"
+  exit 0
+fi

package/skills/dynamodb/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: dynamodb
+description: "Use when designing or operating an Amazon DynamoDB table - modeling entities and relationships without joins, choosing partition/sort keys, deciding single-table vs table-per-entity, adding a GSI/LSI, picking on-demand vs provisioned capacity, or diagnosing throttling. Triggers: 'design a DynamoDB table', 'model one-to-many / many-to-many without joins', 'single-table design worth it?', 'query the same data by two different keys' (inverted GSI), 'writes throttled even though I'm under my provisioned capacity' (hot partition), 'on-demand or provisioned?', 'why does my Query only return some rows?' (1 MB page), 'diseña la tabla DynamoDB para estos patrones de acceso', 'modela aquesta relació amb clau composta a DynamoDB'. NOT relational schema / SQL / EXPLAIN / B-tree indexing (that is postgresdb), and NOT document modeling with aggregation pipelines (that is mongodb)."
+tags: [dynamodb, nosql, single-table-design, aws, data-modeling]
+recommends: [postgresdb, mongodb, redis, vector-db, aws-essentials, deployment, secure-coding]
+origin: risco
+---
+
+# DynamoDB — access-pattern-first modeling and capacity
+
+DynamoDB is not a relational database with a different syntax. It has no joins, no ad-hoc queries, no
+server-side aggregation, and it punishes schema changes after launch. So the modeling discipline IS the
+work: enumerate every read and write the app must perform, THEN design keys so each one is a single
+`GetItem` or `Query`. Add an index only when the base table physically cannot serve a pattern. Decide
+capacity last.
+
+Your job here is to stop the user from treating DynamoDB like SQL.
+
+## What you produce / what you refuse
+
+You deliver three artifacts, in this order:
+
+1. **An access-pattern list** — a table of every query and write, with key condition, read/write,
+   frequency, and what serves it. This is the contract the keys must satisfy.
+2. **A key-design document** — entity → PK/SK encoding → which table or named GSI serves each pattern.
+3. **A capacity + cost recommendation** — on-demand vs provisioned vs reserved, and the hot-partition risk.
+
+You **refuse** to: click through the AWS console, wire the IaC/CI provisioning pipeline (that is
+`../deployment/SKILL.md`), or model the data as normalized tables you then "join" in application code.
+You emit DDL, IaC snippets, and example SDK calls — you do not provision the infrastructure.
+
+## The non-negotiable order
+
+Do these in sequence. Reordering them is the single most common DynamoDB mistake.
+
+1. **Access patterns first.** You cannot query what your keys do not express, and there is no `WHERE`
+   over arbitrary columns. List the patterns before you name a single attribute.
+2. **Keys second.** Co-locate items that are read together so one `Query` returns them.
+3. **Indexes last.** A GSI is a cost and a consistency compromise; reach for it only when the base
+   table cannot answer a pattern.
+4. **Capacity last.** Capacity mode is a billing decision, not a modeling one — it changes nothing about
+   the keys. Pick it after the model is stable.
+
+Why the order matters: changing a table's key schema after launch means a full migration (new table +
+backfill + dual-write). Get the keys wrong and you pay for it forever.
+
+## Step 1 — Enumerate access patterns
+
+Produce this table before touching keys. It is also exactly what `scripts/verify.sh` checks.
+
+| pattern | entity | key condition | read/write | est. freq | served by |
+|---|---|---|---|---|---|
+| Get a user by id | User | `PK=USER#<id>` | read | high | base table `GetItem` |
+| Get a user's orders, newest first | Order | `PK=USER#<id>`, `SK begins_with ORDER#` | read | high | base table `Query` |
+| Look up a user by email | User | `GSI1PK=EMAIL#<email>` | read | medium | GSI1 `Query` |
+| List open orders across all users | Order | sparse `GSI2PK=OPEN` | read | low | GSI2 (sparse) `Query` |
+
+Bad → Good. The whole game is moving from vague to executable:
+
+- Bad: "store users and orders." (No key condition is derivable from this.)
+- Good: "get all orders for a user, newest first, page size 25." (PK + SK range + sort direction fall out.)
+
+Rule: if a pattern needs a `FilterExpression` over more than ~10% of the items it scans, that is a
+modeling smell — redesign the key, do not patch it with a filter.
+
+## Step 2 — Key design + single-table decision
+
+**Composite-key encoding.** Use prefixed, sortable strings so one partition holds an entity and its
+children, and so a sort-key range query slices them:
+
+```text
+PK = USER#123
+SK = USER#123                      <- the user item itself
+SK = ORDER#2026-06-02T10:15#A91    <- an order, ISO-8601 timestamp sorts lexically = chronologically
+SK = ORDER#2026-06-02T11:40#B07
+```
+
+```json
+{ "PK": "USER#123", "SK": "ORDER#2026-06-02T10:15#A91",
+  "Type": "Order", "Total": 4200, "Status": "OPEN" }
+```
+
+One `Query` with `PK = USER#123 AND SK begins_with("ORDER#")` returns all of that user's orders,
+already sorted. That is a **one-to-many** relationship with no join.
+
+**Many-to-many** uses an adjacency list: store the edge twice (or use an inverted GSI, see Step 3) so
+you can traverse it from either side. Full worked example in
+[references/access-patterns.md](references/access-patterns.md).
+
+**Single-table vs table-per-entity** — decide honestly, do not cargo-cult:
+
+| signal | single-table | table-per-entity |
+|---|---|---|
+| Many entities read together in one request | yes | no |
+| Many access patterns over related entities | yes | no |
+| Entities are independent, patterns are few/simple | no | yes (simpler, fine) |
+| Team unfamiliar with overloaded keys | weigh the cost | yes |
+| Need clean per-entity IAM / TTL / capacity isolation | no | yes |
+
+Single-table design earns its complexity when many related entities share access patterns. When entities
+are independent and the queries are few, separate tables are simpler and perfectly correct — say so.
+
+## Step 3 — GSIs (only when the base table can't serve it)
+
+Three named patterns, each with a one-line why:
+
+- **Inverted index** — swap PK and SK on the GSI so you can read the relationship from the other side
+  (`GSI1PK = SK_value`, `GSI1SK = PK_value`). Serves "given an order, who owns it" / many-to-many reverse.
+- **Sparse index** — only items that carry the GSI's key attribute are indexed. Write the attribute
+  only on the few items you want to find ("OPEN" orders, flagged accounts) so the index is tiny and the
+  query is "find the few" instead of "scan the many."
+- **Overloaded GSI** — reuse generic `GSI1PK`/`GSI1SK` attributes across multiple entity types so one
+  index serves several patterns. Keeps you under the index quota.
+
+**Rule: add a GSI only when the base table physically cannot answer the pattern.** Every GSI is a
+standing cost.
+
+Warnings that bite people:
+
+- GSIs are **always eventually consistent** — you cannot read-your-own-write through a GSI. If a pattern
+  needs strong consistency, it must hit the base table.
+- Each write to the base table replicates to **every GSI whose keys changed**, each consuming its own
+  write capacity. More indexes = multiplied write cost.
+- **Project only the attributes each pattern needs.** Blanket `ProjectionType: ALL` doubles storage and
+  write cost; use `KEYS_ONLY` or `INCLUDE` when you can.
+
+Quotas (default, adjustable for GSIs): up to **20 GSIs** and **5 LSIs** per table. LSIs must be defined
+at table creation, share the base partition key, and impose a **10 GB item-collection cap** (all items
+under one partition key). GSI-only tables have no such cap — a real reason to prefer GSIs over LSIs.
+
+## Step 4 — Capacity & cost
+
+Pick the mode after the model is stable. Decision table:
+
+| traffic shape | recommendation | why |
+|---|---|---|
+| Spiky / unpredictable, or < ~10M req/month | **On-demand** (the AWS default) | Nov-2024 ~50% price cut made it cheapest for most workloads; no capacity planning |
+| Sustained utilization > ~40% | Provisioned + auto-scaling | provisioned writes (~$0.047/M) are far cheaper than on-demand at high utilization |
+| Predictable, long-running, > ~70% util | Provisioned + reserved capacity | 3-year reserved (~$0.013/M write) is dramatically cheaper still |
+
+On-demand request unit pricing (us-east-1, standard table class): **RRU $0.125 / million**,
+**WRU $0.625 / million**. **Warm throughput** (the instantaneous read/write a table can serve) is shown
+by default at no cost and rises automatically as you scale; you pay only if you **proactively pre-warm**
+ahead of a known spike.
+
+**Hot partitions.** Each physical partition has a hard ceiling of **3,000 RCU and 1,000 WCU per second**,
+regardless of the table's total capacity. Drive one partition key past that and you are throttled even
+while well under your table limit — this is why "writes throttled but I'm under capacity" means a hot key.
+Fix with high-cardinality keys or **write-sharding**: append a suffix bucket to the PK.
+
+```text
+# Hot: every write lands on one partition
+PK = METRIC#daily_total
+
+# Sharded: spread writes across N buckets, scatter-gather on read
+PK = METRIC#daily_total#<0..9>
+```
+
+Capacity math, full pricing detail, and the sharding recipe live in
+[references/capacity-and-limits.md](references/capacity-and-limits.md).
+
+## Step 5 — Operational guardrails
+
+- **Item size is hard-capped at 400 KB** (attribute names + values). Offload large blobs to S3 and store
+  the S3 key in the item.
+- **Query/Scan return at most 1 MB per request.** That is why a `Query` "only returns some rows" — loop on
+  `LastEvaluatedKey` until it is absent.
+
+```bash
+aws dynamodb query --table-name App \
+  --key-condition-expression 'PK = :pk' \
+  --expression-attribute-values '{":pk":{"S":"USER#123"}}' \
+  --starting-token "$LAST_EVALUATED_KEY"   # paginate; absent => done
+```
+
+- **TransactWriteItems / TransactGetItems** group up to **100 unique items**; a transactional write
+  consumes **2× WCU**.
+- **BatchWriteItem** takes up to **25 put/delete requests** per call.
+- **FilterExpression runs AFTER the read consumes capacity** — it saves bandwidth, not RCU. Never use a
+  filter as a substitute for a key condition.
+- **TTL** for automatic expiry (set an epoch-seconds attribute); deletion is best-effort, not instant.
+- **DynamoDB Streams** for change capture / building derived & denormalized views.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| Designing keys before listing access patterns | The keys won't express the queries; post-launch fix is a full migration | List every read/write first; derive keys from them |
+| `Scan` + `FilterExpression` as your "query" | Scan reads (and bills) the whole table; the filter only trims the response | Make the pattern a `Query` on a key or GSI |
+| One GSI per attribute "just in case" | Each GSI multiplies write cost and counts against the 20-GSI quota | Add a GSI only when the base table can't serve a real pattern |
+| Normalizing into separate tables joined in app code | DynamoDB has no joins; app-side joins are N round-trips and races | Co-locate related items under one PK; query once |
+| Low-cardinality PK (e.g. `status`, `tenant`) | All traffic funnels to one partition → throttling at 3000 RCU / 1000 WCU | High-cardinality PK; write-shard hot keys |
+| Expecting strong consistency from a GSI | GSIs are always eventually consistent — stale reads | Read consistency-critical patterns from the base table |
+| `ProjectionType: ALL` on every GSI | Doubles storage and write cost on each indexed write | Project `KEYS_ONLY` / `INCLUDE` only what the pattern needs |
+| Storing > 400 KB inline (images, docs, logs) | Hits the 400 KB item cap; bloats every read | Put the blob in S3, store the pointer in the item |
+| Picking capacity mode before the model is done | Mode is billing, not modeling — premature and often wrong | Stabilize keys/GSIs first, then choose on-demand vs provisioned |
+
+## References & siblings
+
+- [references/access-patterns.md](references/access-patterns.md) — full multi-tenant SaaS / e-commerce
+  model end-to-end: pattern table → PK/SK map → GSI map → example AWS SDK v3 (`@aws-sdk/lib-dynamodb`)
+  calls; adjacency-list many-to-many; time-series and leaderboard patterns.
+- [references/capacity-and-limits.md](references/capacity-and-limits.md) — capacity-mode detail, current
+  pricing + the Nov-2024 cut, warm throughput, the full quota table, hot-partition diagnosis + sharding.
+
+Route elsewhere when the engine is different: relational schema / SQL / EXPLAIN / indexing →
+`../postgresdb/SKILL.md`; MySQL-engine schema → `mysql`; document modeling + aggregation pipeline →
+`mongodb`; cache / queue / rate-limiter → `redis`; vector store / semantic search → `vector-db`; AWS
+account / IAM / VPC setup → `aws-essentials`; provisioning the table in CI/CD → `../deployment/SKILL.md`;
+API-layer auth/secrets in front of the table → `../secure-coding/SKILL.md`.
+
+## verify.sh
+
+`scripts/verify.sh <path-to-key-design.{md,json}>` checks the access-pattern artifact: every row has a
+key target (`pk`/`sk` or a named `gsi`) and a `query_type`; it FAILS on any pattern served by `Scan`,
+WARNS on `FilterExpression`, and asserts ≤20 GSIs / ≤5 LSIs. Read-only; exits 0 on an empty or clean
+target.

package/skills/dynamodb/evals/README.md

@@ -0,0 +1,8 @@
+# Evals — dynamodb
+
+These cases are graded by judgment, not an automated harness. Feed each `should_trigger` and
+`should_not_trigger` prompt to the skill router and confirm it routes to `dynamodb` (or, for the negatives,
+to the named `route_to` sibling). For the `capability` case, give the scenario to the skill and check the
+answer hits every item in `must_include` — most importantly that it enumerates access patterns before keys,
+serves every lookup with a key or GSI (never a Scan), and never falls back to relational joins. The
+separate `scripts/verify.sh` mechanically checks a key-design artifact; this YAML checks reasoning.

package/skills/dynamodb/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: dynamodb
+
+should_trigger:
+  - prompt: "Design a DynamoDB table for an e-commerce app — users, orders, and order items."
+    why: "Core access-pattern-first NoSQL modeling for the DynamoDB engine."
+  - prompt: "I need to look up a user by id AND by email in DynamoDB. How do I support both lookups?"
+    why: "Non-obvious — the answer is an inverted/sparse GSI, but the user never says 'GSI' or 'index'."
+  - prompt: "My DynamoDB writes are getting throttled even though I'm way under my provisioned capacity. Why?"
+    why: "Non-obvious — this is the per-partition 1000 WCU hot-partition ceiling, with no modeling vocabulary in the prompt."
+  - prompt: "Should I use on-demand or provisioned capacity for a workload that spikes hard at 9am and is quiet otherwise?"
+    why: "Capacity-mode decision the skill owns (on-demand is the post-Nov-2024 default for spiky traffic)."
+  - prompt: "Is single-table design actually worth it for my app, or should I use a table per entity?"
+    why: "The single-table-vs-table-per-entity call is squarely this skill's territory."
+  - prompt: "Diseña el modelo de DynamoDB para un chat: conversaciones y mensajes, con paginación."
+    why: "Spanish + access-pattern modeling (one-to-many) + the 1 MB page / LastEvaluatedKey pagination concern."
+
+should_not_trigger:
+  - prompt: "Design a normalized Postgres schema with foreign keys for orders and customers, and add the right indexes."
+    route_to: postgresdb
+    why: "Relational engine — normalization, foreign keys, B-tree indexes are postgresdb's domain."
+  - prompt: "Model embedding-vs-referencing for my MongoDB documents and write the aggregation pipeline."
+    route_to: mongodb
+    why: "Document engine with an aggregation pipeline; not DynamoDB key/GSI modeling."
+  - prompt: "I want to store and query vector embeddings for semantic search."
+    route_to: vector-db
+    why: "Vector / semantic search, not key-value access-pattern modeling."
+  - prompt: "Set up my AWS account, IAM roles, and a VPC so I can start using AWS."
+    route_to: aws-essentials
+    why: "Account and infrastructure setup, not data modeling."
+  - prompt: "Cache these hot read results to take load off my database."
+    route_to: redis
+    why: "Caching layer is out of scope; DynamoDB owns the modeling, not the cache in front of it."
+
+capability:
+  - scenario: >
+      A multi-tenant SaaS has entities Org, User, Project, and Task. It needs to: get all users in an org;
+      get a user's tasks newest-first; look up a user by email; and list all overdue tasks across an org.
+      Design the DynamoDB model and recommend a capacity mode.
+    must_include:
+      - "Enumerates the four access patterns BEFORE designing any keys"
+      - "Designs composite PK/SK with entity co-location under a single table and shows the encoding (e.g. PK=USER#id, SK=TASK#<iso>#id)"
+      - "Serves the email lookup via an inverted/sparse GSI and notes GSIs are eventually consistent (no read-your-own-write)"
+      - "Serves 'overdue tasks' via a sparse GSI (attribute written only on overdue items), not a Scan + FilterExpression"
+      - "Recommends on-demand as the default capacity mode while naming the ~40%-utilization threshold for switching to provisioned"
+      - "Flags the 400 KB item cap and the 1 MB Query page with LastEvaluatedKey pagination"
+      - "Does NOT propose normalized separate tables joined in application code"

package/skills/dynamodb/references/access-patterns.md

@@ -0,0 +1,127 @@
+# Worked model: multi-tenant SaaS / e-commerce
+
+A single end-to-end example. The domain has four entities — **Org**, **User**, **Project**, **Task** —
+plus orders to show one-to-many and many-to-many. Follow the order: patterns → keys → GSIs → calls.
+
+## 1. Access patterns
+
+| # | pattern | key condition | type | served by |
+|---|---|---|---|---|
+| 1 | Get an org by id | `PK=ORG#<id>`, `SK=ORG#<id>` | GetItem | base |
+| 2 | Get all users in an org | `PK=ORG#<id>`, `SK begins_with USER#` | Query | base |
+| 3 | Get a user by id | `PK=USER#<id>`, `SK=USER#<id>` | GetItem | base |
+| 4 | Look up a user by email | `GSI1PK=EMAIL#<email>` | Query | GSI1 (inverted) |
+| 5 | Get a user's tasks, newest first | `PK=USER#<id>`, `SK begins_with TASK#`, ScanIndexForward=false | Query | base |
+| 6 | List all overdue tasks in an org | `GSI2PK=ORG#<id>#OVERDUE` | Query | GSI2 (sparse) |
+| 7 | Get all users on a project (M:N) | `GSI1PK=PROJECT#<id>` | Query | GSI1 (inverted) |
+
+Patterns 1–5 are served by the base table. Only 4, 6, 7 force an index — note how few do.
+
+## 2. Key design (single table `App`)
+
+```text
+# Base table key schema
+PK (partition)   SK (sort)
+-------------------------------------------------------------
+ORG#o1           ORG#o1                       Org item
+ORG#o1           USER#u1                      User (co-located under org)  -> pattern 2
+USER#u1          USER#u1                      User canonical item          -> pattern 3
+USER#u1          TASK#2026-06-02T09:00#t1     Task (sorts chronologically) -> pattern 5
+USER#u1          TASK#2026-06-01T14:00#t2
+```
+
+User items carry GSI attributes for the inverted/sparse lookups; tasks carry the sparse key only when overdue:
+
+```json
+{ "PK": "USER#u1", "SK": "USER#u1", "Type": "User",
+  "Email": "ana@acme.com", "OrgId": "o1",
+  "GSI1PK": "EMAIL#ana@acme.com", "GSI1SK": "USER#u1" }
+```
+
+```json
+{ "PK": "USER#u1", "SK": "TASK#2026-06-02T09:00#t1", "Type": "Task",
+  "DueDate": "2026-05-30", "Status": "OPEN",
+  "GSI2PK": "ORG#o1#OVERDUE", "GSI2SK": "2026-05-30#t1" }
+```
+
+When a task is completed or not yet overdue, **omit `GSI2PK`** — the sparse index then contains only
+overdue tasks, so pattern 6 is a cheap `Query`, never a `Scan`.
+
+## 3. GSI map
+
+| GSI | partition key | sort key | projection | serves |
+|---|---|---|---|---|
+| GSI1 (inverted/overloaded) | `GSI1PK` | `GSI1SK` | `KEYS_ONLY` + email | patterns 4, 7 |
+| GSI2 (sparse) | `GSI2PK` | `GSI2SK` | `INCLUDE` DueDate,Title | pattern 6 |
+
+GSI1 is **overloaded**: an `EMAIL#...` value serves user-by-email; a `PROJECT#...` value (written on a
+membership edge item) serves project members. One index, two patterns, under quota.
+
+## 4. Example calls (AWS SDK v3, `@aws-sdk/lib-dynamodb`)
+
+```typescript
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, QueryCommand, GetCommand } from "@aws-sdk/lib-dynamodb";
+
+const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+
+// Pattern 5: a user's tasks, newest first, page of 25
+const tasks = await ddb.send(new QueryCommand({
+  TableName: "App",
+  KeyConditionExpression: "PK = :pk AND begins_with(SK, :p)",
+  ExpressionAttributeValues: { ":pk": "USER#u1", ":p": "TASK#" },
+  ScanIndexForward: false,            // descending = newest first
+  Limit: 25,
+}));
+
+// Pattern 4: user by email (inverted GSI — eventually consistent)
+const byEmail = await ddb.send(new QueryCommand({
+  TableName: "App",
+  IndexName: "GSI1",
+  KeyConditionExpression: "GSI1PK = :e",
+  ExpressionAttributeValues: { ":e": "EMAIL#ana@acme.com" },
+}));
+
+// Pattern 6: overdue tasks across the org (sparse GSI — only overdue items are present)
+const overdue = await ddb.send(new QueryCommand({
+  TableName: "App",
+  IndexName: "GSI2",
+  KeyConditionExpression: "GSI2PK = :o",
+  ExpressionAttributeValues: { ":o": "ORG#o1#OVERDUE" },
+}));
+```
+
+## 5. Pagination loop (1 MB page limit)
+
+```typescript
+let cursor: Record<string, unknown> | undefined;
+const all = [];
+do {
+  const page = await ddb.send(new QueryCommand({
+    TableName: "App",
+    KeyConditionExpression: "PK = :pk AND begins_with(SK, :p)",
+    ExpressionAttributeValues: { ":pk": "USER#u1", ":p": "ORDER#" },
+    ExclusiveStartKey: cursor,
+  }));
+  all.push(...(page.Items ?? []));
+  cursor = page.LastEvaluatedKey;     // absent => done
+} while (cursor);
+```
+
+## 6. Many-to-many via adjacency list
+
+A user belongs to many projects; a project has many users. Store the edge so both directions Query:
+
+```text
+PK = USER#u1      SK = PROJECT#p9     (GSI1PK = PROJECT#p9, GSI1SK = USER#u1)
+```
+
+- "projects for a user" → base `Query PK=USER#u1, SK begins_with PROJECT#`.
+- "users on a project" → GSI1 `Query GSI1PK=PROJECT#p9` (pattern 7).
+
+## 7. Time-series & leaderboard
+
+- **Time-series**: PK = `SENSOR#<id>#<yyyy-mm>` (bucket by month to bound partition size), SK = ISO
+  timestamp. Range queries slice by time; monthly buckets keep any single partition under the heat ceiling.
+- **Leaderboard**: a sparse/overloaded GSI with PK = `BOARD#<id>`, SK = zero-padded score
+  (`0000420#user`). `Query` descending = top-N. Pad numerically so lexical sort matches numeric sort.

package/skills/dynamodb/references/capacity-and-limits.md

@@ -0,0 +1,78 @@
+# Capacity, pricing, limits
+
+All numbers are us-east-1, standard table class, as of mid-2026. Prices change; treat ratios as durable,
+absolute cents as a snapshot.
+
+## Capacity modes
+
+| mode | when | mechanics |
+|---|---|---|
+| On-demand | Spiky / unpredictable, new tables, < ~10M req/month | Pay per request; no capacity planning. **AWS's recommended default** since the Nov-2024 cut. |
+| Provisioned + auto-scaling | Sustained utilization > ~40% | Reserve RCU/WCU; auto-scaling adjusts within bounds. |
+| Provisioned + reserved capacity | Predictable, long-running, > ~70% util | Commit 1- or 3-year for the steep discount. |
+
+**The Nov-2024 change.** AWS cut on-demand throughput price by **~50%**, which made on-demand cheaper than
+provisioned for most workloads and shifted the default recommendation to on-demand. Only commit to
+provisioned/reserved once you can show steady high utilization.
+
+## Pricing snapshot (on-demand, us-east-1, standard class)
+
+- Read request units (RRU): **$0.125 / million**
+- Write request units (WRU): **$0.625 / million** (writes are 5× reads — write-heavy designs cost more)
+
+At **full** utilization, provisioned beats on-demand hard:
+
+- Provisioned write ~ **$0.047 / million** WCU → roughly **26×** cheaper than on-demand WRU.
+- 3-year reserved write ~ **$0.013 / million** → roughly **96×** cheaper than on-demand.
+
+These ratios only apply if utilization is genuinely high and steady; idle provisioned capacity is pure
+waste. That is the whole point of the >40% / >70% thresholds.
+
+## Warm throughput
+
+Warm throughput is the **instantaneous** read/write a table or index can already serve. It is exposed by
+default at **no cost** and rises automatically as the table scales. You are charged a one-time fee only if
+you **proactively pre-warm** ahead of a known spike (e.g. a launch or a sale), priced at the per-unit
+RCU/WCU regional rate for the increase you request. Default behavior costs nothing.
+
+## Hot partitions and write-sharding
+
+Every physical partition has a hard ceiling, independent of table capacity:
+
+- **3,000 RCU/sec** and **1,000 WCU/sec** per partition.
+
+Concentrate traffic on one partition key and you throttle even while well under the table's provisioned
+or on-demand limit. Symptom: `ProvisionedThroughputExceededException` / throttles "but I'm under capacity."
+
+Fix — **write-sharding** spreads a hot key across N buckets:
+
+```text
+# Hot: a single counter, one partition
+PK = COUNTER#global
+
+# Sharded across 10 buckets
+PK = COUNTER#global#<0..9>     # write: random bucket; read: query all 10 and sum (scatter-gather)
+```
+
+Choose N from peak WCU / 1,000 (round up). Higher N spreads heat but multiplies read fan-out — size it to
+the real peak, not a guess.
+
+## Quotas and operation limits
+
+| limit | value | note |
+|---|---|---|
+| Item size | **400 KB** | attribute names + values, binary length; offload big blobs to S3 |
+| GSIs per table | **20** (default, adjustable) | each adds standing write cost |
+| LSIs per table | **5** | must be defined at table creation; share base PK |
+| Item-collection size (with any LSI) | **10 GB** | all items under one PK; GSI-only tables have no cap |
+| Query / Scan response | **1 MB / request** | paginate via `LastEvaluatedKey` |
+| TransactWriteItems / TransactGetItems | **100 unique items** | transactional write = **2× WCU** |
+| BatchWriteItem | **25 put/delete requests** | per call |
+| Table / item count | no practical limit | only the per-item and per-partition caps bind |
+
+## FilterExpression vs key condition
+
+`FilterExpression` is applied **after** the read has already consumed capacity. It reduces the bytes sent
+over the wire, never the RCU billed. A pattern that filters away most of what it scanned is a key-design
+failure — fix the key or add the right (often sparse) GSI. Filtering ≤10% of a small, key-bounded result
+is fine; filtering a Scan is not.

package/skills/dynamodb/scripts/verify.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — dynamodb skill gate. Checks a key-design / access-pattern artifact.
+#
+# Usage:   scripts/verify.sh [path-to-key-design.{md,json}]
+#   With no argument it auto-discovers candidate files under the current directory
+#   (*key-design*, *access-pattern*, *.md/*.json containing a DynamoDB pattern table).
+#
+# What it enforces (the skill's core discipline — every access pattern is served by a
+# key or index, never a table scan):
+#   - every pattern row names a key target (pk/sk or a gsi) AND a query_type   -> [fail] if missing
+#   - any pattern whose query_type is Scan                                     -> [fail]
+#   - any pattern relying on FilterExpression                                  -> [warn]
+#   - declared index counts within quota: <=20 GSIs, <=5 LSIs                  -> [fail] if exceeded
+#
+# Read-only: never writes, never connects to AWS. Exit 0 on an empty or clean target
+# (no artifact found is a [skip], not a failure). Non-zero ONLY on a real violation.
+# Runs on stock macOS bash 3.2 (no mapfile/associative arrays).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# --- locate the artifact(s) -------------------------------------------------
+FILES=()
+if [ "$#" -ge 1 ]; then
+  if [ -f "$1" ]; then
+    FILES+=("$1")
+  else
+    err "no such file: $1"
+    exit 1
+  fi
+else
+  ROOT="$(pwd)"
+  while IFS= read -r -d '' f; do
+    # keep files that look like a key-design artifact
+    if grep -liE 'key.?design|access.?pattern|query_type|GSI[0-9]?PK|begins_with' "$f" >/dev/null 2>&1; then
+      FILES+=("$f")
+    fi
+  done < <(
+    find "$ROOT" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+      -type f \( -name '*.md' -o -name '*.json' \) -print0 2>/dev/null
+  )
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  skip "no key-design / access-pattern artifact found — nothing to verify"
+  exit 0
+fi
+
+PATTERNS=0 SCANS=0 FILTERS=0
+
+for f in "${FILES[@]}"; do
+  [ -s "$f" ] || { skip "empty file: $f"; continue; }
+
+  # Pattern rows only — not prose. A pattern row is either a Markdown TABLE row (starts with `|`)
+  # or a JSON "query_type": "..." field. This deliberately ignores narrative sentences that merely
+  # mention Scan/Query, so pointing the tool at documentation does not raise false failures.
+  ROW_RE='(^[[:space:]]*\|.*\b(GetItem|Query|Scan|BatchGetItem|TransactGetItems)\b)|("query_type"[[:space:]]*:[[:space:]]*"(GetItem|Query|Scan|BatchGetItem|TransactGetItems)")'
+  while IFS= read -r line; do
+    PATTERNS=$((PATTERNS + 1))
+    # A row is a Scan only when the query_type cell/field is Scan — not when "Scan" appears elsewhere
+    # in the row (e.g. a "Query / Scan response" doc note). Check the query_type position.
+    if printf '%s' "$line" | grep -qiE '("query_type"[[:space:]]*:[[:space:]]*"Scan")|(\|[[:space:]]*Scan[[:space:]]*\|)|(\|[[:space:]]*Scan[[:space:]]*$)'; then
+      SCANS=$((SCANS + 1))
+      err "pattern resolved by Scan in $f: $(printf '%s' "$line" | sed 's/^[[:space:]]*//' | cut -c1-80)"
+    fi
+  done < <(grep -iE "$ROW_RE" "$f" 2>/dev/null || true)
+
+  # FilterExpression usage anywhere is a smell (warn, not fail).
+  fc=$(grep -ciE 'FilterExpression' "$f" 2>/dev/null || true)
+  if [ "${fc:-0}" -gt 0 ]; then
+    FILTERS=$((FILTERS + fc))
+  fi
+
+done
+
+# Distinct index identifiers, not raw mentions, is what the quota bounds. Count distinctly,
+# taking the max across files (a single table's design is normally one file).
+GSI_COUNT=0; LSI_COUNT=0
+for f in "${FILES[@]}"; do
+  [ -s "$f" ] || continue
+  g=$( (grep -oiE 'GSI[0-9]+' "$f" 2>/dev/null || true) | tr 'A-Z' 'a-z' | sort -u | grep -c . || true)
+  l=$( (grep -oiE 'LSI[0-9]+' "$f" 2>/dev/null || true) | tr 'A-Z' 'a-z' | sort -u | grep -c . || true)
+  if [ "${g:-0}" -gt "$GSI_COUNT" ]; then GSI_COUNT="${g:-0}"; fi
+  if [ "${l:-0}" -gt "$LSI_COUNT" ]; then LSI_COUNT="${l:-0}"; fi
+done
+
+if [ "$PATTERNS" -eq 0 ]; then
+  skip "artifact found but no access-pattern rows detected (no GetItem/Query/Scan) — nothing to verify"
+  exit 0
+fi
+
+if [ "$FILTERS" -gt 0 ]; then warn "FilterExpression used $FILTERS time(s) — confirm each filters <=10% of a key-bounded result, not a Scan"; fi
+if [ "$GSI_COUNT" -gt 20 ]; then err "declared GSIs ($GSI_COUNT) exceed the 20-per-table quota"; fi
+if [ "$LSI_COUNT" -gt 5 ];  then err "declared LSIs ($LSI_COUNT) exceed the 5-per-table quota"; fi
+
+if [ "$SCANS" -eq 0 ]; then ok "no access pattern resolved by Scan"; fi
+
+printf 'summary: %d pattern row(s), %d scan(s), %d filter mention(s), GSIs declared=%d, LSIs declared=%d\n' \
+  "$PATTERNS" "$SCANS" "$FILTERS" "$GSI_COUNT" "$LSI_COUNT"
+
+exit "$EXIT"