@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/duckdb/references/remote-and-lakehouse.md

@@ -0,0 +1,101 @@
+# DuckDB — remote data & lakehouse
+
+Offloaded from the SKILL body. DuckDB v1.5.2 / LTS 1.4.x.
+
+## httpfs: read from S3 / GCS / Azure / HTTP in place
+
+```sql
+INSTALL httpfs;        -- one-time per database/install
+LOAD httpfs;           -- per session
+SELECT count(*) FROM read_parquet('https://host/path/data.parquet');  -- plain HTTP works immediately
+```
+
+`httpfs` streams remote files with HTTP range requests, so Parquet row-group and column pushdown still
+apply — you fetch only the bytes you read, not the whole object.
+
+## CREATE SECRET — credentials done right
+
+Never inline keys into SQL. Use a secret; prefer the credential chain so creds come from the environment
+or an instance/role rather than being typed.
+
+```sql
+-- Pick up env vars / instance role / SSO automatically (recommended):
+CREATE SECRET s3 (TYPE s3, PROVIDER credential_chain);
+
+-- Explicit, when you must (e.g. a non-default region / endpoint):
+CREATE SECRET s3 (
+    TYPE s3,
+    KEY_ID '...', SECRET '...',
+    REGION 'eu-west-1'
+);
+
+-- GCS (S3-compatible) and Azure have their own TYPEs:
+CREATE SECRET gcs (TYPE gcs, KEY_ID '...', SECRET '...');
+CREATE SECRET az  (TYPE azure, CONNECTION_STRING '...');
+```
+
+```sql
+SELECT region, sum(amount) AS rev
+FROM read_parquet('s3://bkt/sales/year=*/month=*/*.parquet', filename = true)
+GROUP BY ALL;
+```
+
+## Hive-partitioned globs
+
+A glob over `key=value/` directories auto-derives partition columns; filter on them and DuckDB prunes
+whole directories before reading any data.
+
+```sql
+SELECT *
+FROM read_parquet('s3://bkt/events/year=*/month=*/*.parquet', hive_partitioning = true)
+WHERE year = 2025 AND month = 4;     -- only the matching partition dirs are scanned
+```
+
+## Iceberg
+
+```sql
+INSTALL iceberg; LOAD iceberg;
+SELECT * FROM iceberg_scan('s3://bkt/warehouse/db/table');   -- read a table snapshot
+```
+
+## Delta Lake
+
+```sql
+INSTALL delta; LOAD delta;
+SELECT * FROM delta_scan('s3://bkt/delta/events');
+```
+
+## DuckLake — DuckDB's own lakehouse catalog
+
+DuckLake (ducklake.select) stores table metadata in a SQL catalog with Parquet data files — DuckDB's
+native lakehouse format. Attach it and query like a normal schema.
+
+```sql
+INSTALL ducklake; LOAD ducklake;
+ATTACH 'ducklake:metadata.ducklake' AS lake (DATA_PATH 's3://bkt/lake/');
+USE lake;
+CREATE TABLE sales AS FROM read_parquet('s3://bkt/raw/*.parquet');
+```
+
+## Partitioned write (handoff)
+
+```sql
+COPY (SELECT * FROM 'raw/*.parquet')
+  TO 's3://bkt/curated/' (FORMAT parquet, PARTITION_BY (year, month), OVERWRITE_OR_IGNORE);
+```
+
+Writes a hive-partitioned dataset so any reader (DuckDB, Spark, ClickHouse, pandas) can prune partitions.
+
+## MotherDuck — scale-out / share escape hatch
+
+MotherDuck is managed DuckDB-as-a-service with hybrid local+cloud execution. Reach for it to share a
+database or push heavy work to the cloud without running a server yourself — not the default.
+
+```sql
+ATTACH 'md:';                       -- connect to your MotherDuck account (auth via token)
+USE my_cloud_db;
+SELECT * FROM cloud_table LIMIT 10; -- query can run partly local, partly in the cloud
+```
+
+When the real need is many concurrent users or always-on production serving, that is
+`clickhouse-analytics`, not MotherDuck.

package/skills/shared/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/shared/dynamodb/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: dynamodb
+description: "Use when modeling or operating a DynamoDB table: deriving partition/sort keys from access patterns, single-table vs table-per-entity, adding a GSI/LSI, on-demand vs provisioned capacity, or diagnosing hot-partition throttling. NOT relational schema/SQL/EXPLAIN (that is `postgresdb`), NOT aggregation-pipeline document modeling (that is `mongodb`)."
+tags: [dynamodb, nosql, single-table-design, aws, data-modeling]
+recommends: [postgresdb, mongodb, redis, vector-db, aws-essentials, deployment, secure-coding]
+origin: ai-hub
+---
+
+# 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 steps below run in sequence — access patterns, then keys, then indexes, then capacity. Reordering
+them is the single most common DynamoDB mistake.
+
+## Step 1 — Enumerate access patterns
+
+You cannot query what your keys do not express, and there is no `WHERE` over arbitrary columns, so
+produce this table before you name a single attribute. It is also exactly what `scripts/verify.sh`
+checks: run `scripts/verify.sh <path-to-key-design.{md,json}>` and every row must carry 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.
+
+| 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
+
+Get this wrong and you pay for it forever: changing a table's key schema after launch means a full
+migration (new table + backfill + dual-write).
+
+**Composite-key encoding.** Use prefixed, sortable strings so one partition holds an entity and its
+children — items read together are co-located, so one `Query` returns them — 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. Worked end-to-end in
+[references/access-patterns.md](references/access-patterns.md) — a multi-tenant SaaS / e-commerce model
+(pattern table → PK/SK map → GSI map → AWS SDK v3 `@aws-sdk/lib-dynamodb` calls), adjacency-list
+many-to-many, time-series and leaderboard patterns.
+
+**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
+
+Capacity mode is a billing decision, not a modeling one — it changes nothing about the keys, so pick it
+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 (including the Nov-2024 cut), warm throughput, the full quota table,
+and hot-partition diagnosis + 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 |
+
+## 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`.

package/skills/shared/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/shared/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/shared/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/shared/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.