rsc-universal 0.1.1

package/skills/mongodb/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: mongodb
+
+should_trigger:
+  - prompt: "This find() takes forever and the logs say it's scanning the whole collection — 4 million docs. How do I make it fast?"
+    why: "A full collection scan (COLLSCAN) on a large collection is core scope; the skill owns reading explain and choosing the index, even though the user never says 'index' or 'COLLSCAN'."
+  - prompt: "Should I put the comments inside the post document or keep them in their own collection?"
+    why: "Embed vs reference is a named modeling decision with an explicit rule and the 16 MB rationale."
+  - prompt: "My aggregation with a $lookup and a $group is slow and sometimes errors out on memory. What's wrong?"
+    why: "Pipeline stage order, $lookup cost, and the 100 MB blocking-stage limit / allowDiskUse are all in scope."
+  - prompt: "My multi-document transaction keeps throwing TransientTransactionError and I don't know how to handle it."
+    why: "Non-obvious: the fix is the mandatory retry-on-the-transient-label (withTransaction), a core transactions topic the user wouldn't phrase as 'retry'."
+  - prompt: "Necesito modelar una colección de pedidos con muchísimos items que crece sin límite, cómo lo hago?"
+    why: "Spanish; unbounded array growth → reference or bucket pattern, a named modeling case."
+  - prompt: "Which Atlas tier do I actually need to run Vector Search — is the free M0 enough?"
+    why: "Non-obvious tier boundary: M0 won't run Vector Search for real workloads; Atlas tier choice + Vector Search are explicitly in scope."
+
+should_not_trigger:
+  - prompt: "Design a normalized Postgres schema with foreign keys and help me read this EXPLAIN ANALYZE output."
+    route_to: "postgresdb"
+    why: "Relational engine, SQL, and EXPLAIN ANALYZE — a different planner and concurrency model; the named boundary sibling."
+  - prompt: "My Mongoose pre-save hook isn't firing and I don't understand what updateMany returns."
+    route_to: "nodejs"
+    why: "ODM/driver API ergonomics, not engine behavior; nearest catalog skill is the JS runtime, the ODM's own docs own this."
+  - prompt: "Audit my repo for hardcoded credentials and unsafe authentication patterns."
+    route_to: "secure-coding"
+    why: "A security audit of the codebase, not MongoDB modeling/indexing; secure-coding owns app-layer security review."
+  - prompt: "Set up a Redis cache in front of my read queries to cut database load."
+    route_to: "redis"
+    why: "App-layer caching with a different store; explicitly out of scope for this engine skill."
+  - prompt: "Help me choose between Pinecone and Weaviate for our vector store."
+    route_to: "vector-db"
+    why: "Cross-engine vector-DB selection is out of scope; Atlas Vector Search inside Mongo would be in scope, but choosing between external products is not."
+
+capability:
+  - scenario: "A posts/comments app where the number of comments per post is unbounded, and a feed query filters by author and sorts by date. The user asks how to model the collections and which index to add."
+    must_include:
+      - "Chooses to reference comments in a separate collection (not an unbounded embedded array), citing the 16 MB document cap — or proposes a bucket pattern for the comment stream"
+      - "Designs a compound index ordered by ESR: author equality first, then createdAt as the sort key (e.g. { 'author._id': 1, createdAt: -1 })"
+      - "Shows explain('executionStats') and reads it: confirms IXSCAN (not COLLSCAN) and totalKeysExamined close to nReturned, with no in-memory SORT stage"
+      - "States that inserting a single comment or post is already atomic, so no multi-document transaction is needed for it"
+      - "Uses mongosh syntax (createIndex/find/explain), money as Decimal128 if money appears, not relational/SQL framing"

package/skills/mongodb/references/aggregation.md

@@ -0,0 +1,115 @@
+# Aggregation pipelines (MongoDB 8.2)
+
+A pipeline is stages run in order; the order decides whether an index is used and whether a stage
+blows the memory limit. The single most important rule: **put `$match` and `$sort` as early as
+possible**, because once a `$group`, `$project`, `$unwind`, or `$lookup` has reshaped the stream, the
+original index no longer applies.
+
+## Per-stage index eligibility
+
+| Stage | Uses an index? | Notes |
+| --- | --- | --- |
+| `$match` (first stage) | yes | behaves like a `find` filter; ESR rules apply |
+| `$sort` (before any reshape) | yes, if a compound index covers filter+sort | after `$group`/`$project` it is an in-memory SORT |
+| `$match` after `$group`/`$project` | no | runs on computed/in-memory docs |
+| `$lookup` | uses the *foreign* collection's index on `foreignField` | index the join target |
+| `$group` | no (blocking) | 100 MB/stage; `allowDiskUse` to spill |
+| `$unwind` | no | can multiply document count — `$match` before it |
+| `$limit` / `$skip` | benefits from a preceding indexed `$sort` | push `$limit` up where correctness allows |
+
+## `$lookup` variants
+
+```javascript
+// Simple equality join — index customers._id (it is the _id, already indexed).
+{ $lookup: { from: "customers", localField: "customerId", foreignField: "_id", as: "customer" } }
+
+// Subpipeline join — project/filter the foreign side so you pull only what you display.
+{ $lookup: {
+    from: "customers",
+    let: { cid: "$customerId" },
+    pipeline: [
+      { $match: { $expr: { $eq: ["$_id", "$$cid"] } } },
+      { $project: { name: 1, tier: 1 } }
+    ],
+    as: "customer"
+}}
+```
+
+`$lookup` runs the foreign lookup per input document — it is not a hash join. If you do it on every
+read, model it away with the **extended reference** pattern (see data-modeling) instead.
+
+## `$facet` — multiple aggregations in one pass
+
+```javascript
+db.products.aggregate([
+  { $match: { active: true } },
+  { $facet: {
+      byCategory: [ { $group: { _id: "$category", n: { $sum: 1 } } } ],
+      priceStats: [ { $group: { _id: null, avg: { $avg: "$price" }, max: { $max: "$price" } } } ],
+      page:       [ { $sort: { createdAt: -1 } }, { $limit: 20 } ]
+  }}
+])
+// Note: the input to a $facet is materialized; the per-facet sub-pipelines do NOT use indexes.
+// Keep the upstream $match selective so the materialized set is small.
+```
+
+## Window functions (`$setWindowFields`)
+
+```javascript
+// Running total of amount per customer, ordered by date — no self-join.
+db.orders.aggregate([
+  { $setWindowFields: {
+      partitionBy: "$customerId",
+      sortBy: { createdAt: 1 },
+      output: { runningTotal: { $sum: "$amount", window: { documents: ["unbounded", "current"] } } }
+  }}
+])
+```
+
+## `$merge` / `$out` — materialized output
+
+```javascript
+// $merge: upsert results into a target collection (incremental rollups, materialized views).
+{ $merge: { into: "daily_rollup", on: "_id", whenMatched: "merge", whenNotMatched: "insert" } }
+
+// $out: replace the target collection wholesale. Destructive — overwrites. Prefer $merge for
+// incremental jobs; reach for $out only for a full rebuild.
+{ $out: "report_snapshot" }
+```
+
+## Hybrid search (8.2)
+
+MongoDB 8.2 adds the `$scoreFusion` stage, which combines the ranked results of multiple subqueries
+(for example an Atlas Search full-text query and a Vector Search semantic query) into one fused
+ranking — the building block for hybrid search without doing the score blending in application code.
+Pair it with a `$vectorSearch`/`$search` stage per input ranking. (Atlas/Search-index setup lives in
+transactions-and-ops.)
+
+## Memory limit and `allowDiskUse`
+
+Each blocking stage (`$group`, `$sort` without a supporting index, `$bucket`,
+`$setWindowFields`) is capped at **100 MB**. Past it the stage errors unless you pass
+`allowDiskUse: true`, which lets it spill to temporary files on disk.
+
+Spilling is the right tool for a genuinely large aggregation (an analytics rollup over the whole
+collection). It is the **wrong** tool to "fix" a slow pipeline whose real problem is a `$match` that
+isn't using an index — that just makes the unindexed scan spill instead of fixing it. Always check
+the explain first.
+
+## Reading a pipeline's explain
+
+```javascript
+db.orders.explain("executionStats").aggregate([
+  { $match: { status: "paid", createdAt: { $gte: since } } },
+  { $sort:  { createdAt: -1 } },
+  { $group: { _id: "$customerId", total: { $sum: "$amount" } } }
+])
+```
+
+Look for:
+
+- The first stage shows `IXSCAN`, not `COLLSCAN` — the leading `$match` used an index.
+- No surprise in-memory `SORT` stage where a compound index (ESR) should have served the order.
+- `totalDocsExamined` close to the count the `$match` should return — a big gap means the index
+  isn't selective enough or the wrong one was chosen.
+- For `$lookup`, the sub-explain shows an `IXSCAN` on the foreign `foreignField`.

package/skills/mongodb/references/data-modeling.md

@@ -0,0 +1,135 @@
+# Data modeling (MongoDB 8.2)
+
+The rule that overrides every other: **model for the queries you run, not the shape of your data.**
+A document should make your common read a single, index-eligible fetch. Everything below is a tool
+for getting there.
+
+## The embed-vs-reference decision tree
+
+Walk it top to bottom; the first match wins.
+
+1. **Is the child read together with the parent, almost always?** No → reference.
+2. **Is the child set bounded and small (will it stay under a few dozen, forever)?** No → reference.
+3. **Is the child shared across multiple parents, or independently/frequently mutated?** Yes →
+   reference (embedding would duplicate and drift, or rewrite a big parent per child edit).
+4. **Could the embedded array ever push the document toward 16 MB?** Yes → reference or bucket.
+5. **Otherwise → embed.** One read, atomic update, no `$lookup`.
+
+The 16 MB cap is the hard backstop. There is no overflow storage; a write that would exceed it
+fails. So any one-to-many whose "many" is unbounded (comments, events, line items on a long-lived
+cart) is referenced or bucketed, never embedded as a growing array.
+
+### 16 MB math (sanity-check before you embed)
+
+Estimate average child size × expected count, with headroom. A 300-byte comment subdocument hits
+16 MB at roughly 52,000 comments — but you are in trouble long before that, because every read of the
+parent deserializes the whole array. Treat a few hundred unbounded children as the practical ceiling
+for embedding, and reference past it.
+
+## The six patterns, with worked Bad → Good
+
+### 1. Subset
+
+Embed only the hot fields the common view needs; reference the cold rest.
+
+```javascript
+// BAD: product carries its full 200-review history; the catalog card read drags all of it.
+db.products.insertOne({ _id: ObjectId(), name: "Lamp", reviews: [ /* 200 full reviews */ ] })
+
+// GOOD: embed the 3 most-recent reviews for the card; full set lives in its own collection.
+db.products.insertOne({
+  _id: ObjectId(), name: "Lamp",
+  recentReviews: [ { author: "Ada", stars: 5, text: "…" } /* top 3 only */ ],
+  reviewCount: 200
+})
+db.reviews.insertOne({ _id: ObjectId(), productId: ObjectId(), author: "Ada", stars: 5, text: "…" })
+```
+
+### 2. Extended reference
+
+Copy the few joined fields you display so the read needs no `$lookup`.
+
+```javascript
+// BAD: every order render does a $lookup into customers just to show a name.
+db.orders.insertOne({ _id: ObjectId(), customerId: ObjectId(), amount: NumberDecimal("9.99") })
+
+// GOOD: duplicate the small, slow-changing fields you actually display.
+db.orders.insertOne({
+  _id: ObjectId(),
+  customer: { _id: ObjectId(), name: "Ada", tier: "gold" }, // the display fields, copied
+  amount: NumberDecimal("9.99")
+})
+// Trade-off: when the source name changes, refresh the copies (a background job or change stream).
+```
+
+### 3. Bucket
+
+Group N time-ordered events per document instead of one document per event — fewer documents,
+smaller indexes, and the array stays bounded by the bucket size.
+
+```javascript
+// BAD: one document per sensor reading — millions of tiny docs, huge index.
+db.readings.insertOne({ sensorId: ObjectId(), ts: new Date(), value: 21.4 })
+
+// GOOD: one bucket per sensor per hour, capped at N readings; roll to a new bucket past the cap.
+db.readings.updateOne(
+  { sensorId: ObjectId(), hour: ISODate("2026-06-02T10:00:00Z"), count: { $lt: 200 } },
+  { $push: { samples: { ts: new Date(), value: 21.4 } }, $inc: { count: 1 } },
+  { upsert: true }
+)
+// For pure metrics, also consider a native time-series collection (timeField/metaField).
+```
+
+### 4. Computed
+
+Store the rollup; update it on write rather than recomputing on every read.
+
+```javascript
+// GOOD: keep commentCount on the post; bump it when a comment is inserted.
+db.posts.updateOne({ _id: postId }, { $inc: { commentCount: 1 } })
+// Read is O(1); you trade a tiny write cost for avoiding a count aggregation per page load.
+```
+
+### 5. Outlier
+
+When ~1% of documents break the shape (a celebrity with millions of followers), flag them and
+overflow into linked documents so the common case stays small.
+
+```javascript
+db.users.insertOne({
+  _id: ObjectId(), name: "Ada",
+  followerIds: [ /* up to N */ ],
+  hasExtras: false            // flip to true and spill into a followers_overflow collection past N
+})
+```
+
+### 6. Polymorphic
+
+One collection holding several entity shapes, distinguished by a `type` field, sharing an `_id`
+space and the indexes they have in common.
+
+```javascript
+db.assets.insertMany([
+  { _id: ObjectId(), type: "image", url: "…", width: 800, height: 600 },
+  { _id: ObjectId(), type: "video", url: "…", durationSec: 42 }
+])
+// Index the shared fields (type, createdAt); query with the discriminator in the filter.
+```
+
+## Schema versioning
+
+Documents in one collection can have different shapes over time. Stamp a `schemaVersion` and migrate
+lazily on read/write — no big-bang migration, no downtime.
+
+```javascript
+db.users.insertOne({ _id: ObjectId(), schemaVersion: 2, name: "Ada", emails: ["ada@x.io"] })
+// App reads: if doc.schemaVersion < 2, upconvert in code (and optionally write the upgraded shape back).
+```
+
+## `_id` discipline
+
+- Default `ObjectId` is fine: 12 bytes, roughly time-ordered, generated client- or server-side.
+- A natural unique key (a slug, an external id) is a valid `_id` — but it is immutable, so only use
+  one that never changes.
+- Don't add a second unique field as your "real" key and ignore `_id`; make the meaningful key the
+  `_id` or give it its own unique index.

package/skills/mongodb/references/transactions-and-ops.md

@@ -0,0 +1,128 @@
+# Transactions & operations (MongoDB 8.2)
+
+## When a transaction is the wrong tool
+
+A single-document write — including an update that touches many fields, arrays, and subdocuments —
+is **already atomic**. You only need a multi-document transaction when two or more documents must
+commit or roll back together (move money between two accounts, flip an order and append a ledger
+entry). If you can restructure so the atomic unit is one document, do that instead: it is faster and
+needs no replica set.
+
+Transactions require a **replica set or sharded cluster**; they do not run on a standalone `mongod`.
+The default has a **60-second** time limit — keep the body short; a long-running transaction holds
+locks and is more likely to abort.
+
+## Retry wrappers
+
+Two distinct retries are mandatory:
+
+- Retry the whole transaction body when the error carries the **`TransientTransactionError`** label.
+- Retry the **commit** when it carries **`UnknownTransactionCommitResult`** (the commit's outcome is
+  unknown; retrying is safe because commit is idempotent).
+
+`withTransaction` does both for you — prefer it.
+
+```javascript
+const session = db.getMongo().startSession();
+try {
+  session.withTransaction(() => {
+    const accts = session.getDatabase("bank").accounts;
+    accts.updateOne({ _id: "A" }, { $inc: { balance: NumberDecimal("-100") } }, { session });
+    accts.updateOne({ _id: "B" }, { $inc: { balance: NumberDecimal("100")  } }, { session });
+  }, { readConcern: { level: "snapshot" }, writeConcern: { w: "majority" } });
+} finally {
+  session.endSession();
+}
+```
+
+If you must hand-roll (no `withTransaction`), the loop is: start → run body → commit; on a
+`TransientTransactionError` label, restart the whole thing; on `UnknownTransactionCommitResult`,
+retry only `commitTransaction()`. Cap retries with a deadline so a persistent error can't spin
+forever.
+
+## Read & write concern semantics
+
+- **`w:"majority"`** — acknowledged once a majority of replica-set members have the write; it cannot
+  be rolled back by a failover. Use it for money and state transitions.
+- **`w:1`** — acknowledged by the primary only; a failover before replication can roll it back. Fine
+  for logs and fire-and-forget.
+- **read concern `"majority"`** — returns data acknowledged by a majority (no dirty reads).
+- **read concern `"snapshot"`** — a consistent point-in-time view; the transaction default.
+- **read concern `"local"`** — the node's latest, possibly un-replicated; fastest, weakest.
+- A **causally consistent session** lets a client read its own writes across operations.
+
+## Atlas tiers
+
+| Tier | For | Limits / features |
+| --- | --- | --- |
+| **M0** | learning, tiny prototypes | free forever, ≤ 5 GB, shared, no SLA; not for real Vector Search |
+| **Flex** (GA Feb 2025) | small prod / spiky load | $8 base, capped at $30/mo, 100 ops/sec (burst 500), 5 GB; supports Atlas Search, Vector Search, Change Streams, Triggers |
+| **M10+** dedicated | production, scale, isolation | from ~$0.08/hr (~$57/mo); dedicated compute, full feature set |
+
+Legacy Serverless / M2 / M5 instances were auto-migrated to Flex. Move off M0 before you depend on
+Search or Vector Search at any real volume.
+
+## Atlas Search & Vector Search
+
+As of MongoDB 8.2, Search and Vector Search ship with Community and Enterprise Server, not just
+Atlas. They are built on a separate search index you define on a collection; queries run through the
+`$search` / `$vectorSearch` aggregation stages. For hybrid (keyword + semantic) ranking, fuse the two
+rankings with `$scoreFusion` (8.2) rather than blending scores in application code.
+
+```javascript
+// Vector similarity search (index defined out of band on the embedding field).
+db.docs.aggregate([
+  { $vectorSearch: {
+      index: "embedding_idx",
+      path: "embedding",
+      queryVector: queryEmbedding,
+      numCandidates: 200,
+      limit: 10
+  }}
+])
+```
+
+## Queryable Encryption
+
+Encrypts fields client-side; the server stores and queries ciphertext without ever seeing
+plaintext. The supported query types have grown:
+
+- **8.0** added **range** queries (`$lt/$lte/$gt/$gte`) on encrypted fields — previously only `$eq`.
+- **8.2** added **prefix, suffix, and substring** query types on encrypted fields.
+
+Use it for regulated/sensitive fields (SSNs, card data). Never store such a value, or any database
+credential, as plaintext.
+
+## Role-based access control
+
+Grant least privilege: a per-application user scoped with the built-in roles (`readWrite` on one
+database, `read` for reporting users) or a custom role, never the cluster-admin user for app
+traffic. The connection string carries the credential — keep it in a secret store, not in the repo.
+
+## Connection-pool knobs
+
+The driver maintains a pool per `MongoClient`; create one client and reuse it for the process
+lifetime (a new client per request exhausts connections — the classic serverless foot-gun).
+
+| Option | What it controls |
+| --- | --- |
+| `maxPoolSize` (default 100) | upper bound on concurrent connections per client |
+| `minPoolSize` | warm connections kept open to avoid cold-start latency |
+| `maxIdleTimeMS` | close a connection idle this long (useful behind a proxy/firewall) |
+| `waitQueueTimeoutMS` | how long an operation waits for a free connection before erroring |
+
+In a serverless/Lambda runtime, cache the client across invocations and keep `maxPoolSize` small —
+many short-lived containers each opening a large pool overruns the server's connection limit.
+
+## Change streams
+
+A resumable feed of collection/database/cluster events, built on the oplog (needs a replica set).
+Filter with a pipeline and persist the `resumeToken` so a restart picks up without gaps.
+
+```javascript
+const cs = db.orders.watch(
+  [{ $match: { operationType: { $in: ["insert", "update"] } } }],
+  { fullDocument: "updateLookup" }   // include the full post-update document
+);
+while (cs.hasNext()) { const change = cs.next(); /* process; save change._id as resume token */ }
+```

package/skills/mongodb/scripts/verify.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — mongodb skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, never writes, never connects to a database):
+#   1. Discovers .js / .mongodb.js files (excluding vendor dirs).
+#   2. Foot-gun scan (advisory [warn] unless noted):
+#        - committed plaintext credential: mongodb://user:pass@ ...      <- the ONLY hard fail
+#        - createIndex(...) with no options object                       <- [warn]
+#        - redundant compound-index prefix (one index is a left prefix of another in the same file)
+#        - $where JS predicate                                           <- [warn]
+#        - unbounded $lookup (a $lookup with no sub-pipeline)            <- [warn]
+#        - allowDiskUse: true (may be masking a missing $match index)    <- [warn]
+#        - money as a JS number in a seed/insert (heuristic)             <- [warn]
+#   3. If `node` is present, runs `node --check` on each file for a syntax pass; else [skip].
+#
+# Exit code: non-zero ONLY when a committed plaintext credential is found. Everything else —
+# missing tools, every heuristic warning, an empty target — is advisory and exits 0.
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays). Arrays are initialised
+# so they expand safely under `set -u`.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+note() { 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; }
+
+ROOT="$(pwd)"
+
+# Discover JS / mongosh files. bash 3.2 has no mapfile; read NUL-delimited names into an
+# explicitly-initialised array so expansion is safe under `set -u`.
+JS_FILES=()
+while IFS= read -r -d '' f; do
+  JS_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/dist/*' -o -path '*/build/*' \) -prune -o \
+    \( -type f \( -name '*.mongodb.js' -o -name '*.js' \) \) -print0 2>/dev/null
+)
+
+if [ "${#JS_FILES[@]}" -eq 0 ]; then
+  skip "no .js / .mongodb.js files found — nothing to scan"
+  ok "verify.sh passed"
+  exit 0
+fi
+
+# ---- 1. Hard fail: committed plaintext credential in a connection string ----
+# Matches mongodb://user:password@ or mongodb+srv://user:password@ with a literal (non-empty,
+# non-placeholder) password. We treat ${...}, <...>, and process.env as NOT a literal.
+for f in "${JS_FILES[@]}"; do
+  while IFS= read -r line; do
+    case "$line" in
+      *mongodb://*:*@*|*mongodb+srv://*:*@*)
+        # Ignore obvious placeholders / env interpolation.
+        case "$line" in
+          *'${'*|*'<'*'>'*|*process.env*|*':@'*|*'://user:pass@localhost'*) continue ;;
+        esac
+        # Re-confirm there is a colon-delimited secret between scheme and @ that isn't empty.
+        if printf '%s' "$line" | grep -Eq 'mongodb(\+srv)?://[^:/@[:space:]]+:[^@/[:space:]]+@'; then
+          err "$f: plaintext credential in a mongodb connection string — move it to a secret/env var"
+        fi
+        ;;
+    esac
+  done < "$f"
+done
+
+# ---- 2. Advisory foot-gun scan ----
+for f in "${JS_FILES[@]}"; do
+  # createIndex with no options object: createIndex({...})  with no trailing ", { ... }"
+  if grep -Eq 'createIndex\(' "$f" \
+     && ! grep -Eq 'createIndex\([^)]*\},[[:space:]]*\{' "$f"; then
+    note "$f: createIndex(...) with no options object — consider name/partialFilterExpression/unique/expireAfterSeconds"
+  fi
+
+  # $where JS predicate — no index, server-side injection surface.
+  if grep -Eq '\$where' "$f"; then
+    note "$f: \$where runs JS per document (no index, injection surface) — use query operators / \$expr"
+  fi
+
+  # Unbounded $lookup: a $lookup that has no sub-pipeline to project/filter the foreign side.
+  if grep -Eq '\$lookup' "$f" \
+     && ! grep -Eq '\$lookup[^}]*pipeline' "$f"; then
+    note "$f: \$lookup with no sub-pipeline — project/filter the foreign side, or model it away (extended reference)"
+  fi
+
+  # allowDiskUse: true — may be masking a missing $match index.
+  if grep -Eq 'allowDiskUse[[:space:]]*:[[:space:]]*true' "$f"; then
+    note "$f: allowDiskUse:true — confirm via explain it isn't masking a missing \$match index"
+  fi
+
+  # Money as a JS number heuristic: a price/amount/balance/total field assigned a bare number
+  # literal (not NumberDecimal). Catches "amount: 9.99" / "price: 100".
+  if grep -Eiq '(amount|price|balance|total|cost)[[:space:]]*:[[:space:]]*-?[0-9]+(\.[0-9]+)?[[:space:]]*[,}]' "$f" \
+     && ! grep -q 'NumberDecimal' "$f"; then
+    note "$f: money-like field stored as a JS number — use NumberDecimal(\"...\") (Decimal128), floats drift"
+  fi
+done
+
+# Redundant compound-index prefix: within one file, if index keys A are a left prefix of keys B,
+# A is likely redundant. Heuristic on the key-list text between the first {...} of createIndex.
+for f in "${JS_FILES[@]}"; do
+  KEYS=()
+  while IFS= read -r kl; do
+    [ -n "$kl" ] && KEYS+=("$kl")
+  done < <(grep -Eo 'createIndex\([[:space:]]*\{[^}]*\}' "$f" 2>/dev/null \
+            | sed -E 's/.*\{([^}]*)\}.*/\1/' \
+            | tr -d ' ' )
+  n="${#KEYS[@]}"
+  if [ "$n" -ge 2 ]; then
+    i=0
+    while [ "$i" -lt "$n" ]; do
+      j=$((i + 1))
+      while [ "$j" -lt "$n" ]; do
+        a="${KEYS[$i]}"; b="${KEYS[$j]}"
+        # Report once per pair: whichever is the strict left-prefix of the other is redundant.
+        short=""; long=""
+        case "$b" in "$a"*) short="$a"; long="$b" ;; esac
+        case "$a" in "$b"*) short="$b"; long="$a" ;; esac
+        if [ -n "$short" ] && [ "${#short}" -lt "${#long}" ]; then
+          note "$f: index {$short} is a left prefix of {$long} — the longer one likely covers it"
+        fi
+        j=$((j + 1))
+      done
+      i=$((i + 1))
+    done
+  fi
+done
+
+ok "foot-gun scan complete (${#JS_FILES[@]} files)"
+
+# ---- 3. node --check syntax pass ----
+if command -v node >/dev/null 2>&1; then
+  bad=0
+  for f in "${JS_FILES[@]}"; do
+    # mongosh files use shell-only globals (db, ObjectId); node --check only parses syntax, which is fine.
+    if ! node --check "$f" >/dev/null 2>&1; then
+      note "$f: node --check reported a syntax issue (mongosh globals are expected; check real syntax)"
+      bad=$((bad + 1))
+    fi
+  done
+  if [ "$bad" -eq 0 ]; then ok "node --check: all files parse"; fi
+else
+  skip "node not installed — skipping syntax check"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found a committed credential"; fi
+exit "$EXIT"