@cubis/foundry 0.3.10 → 0.3.11

package/Ai Agent Workflow/powers/database-skills/POWER.md

@@ -1,8 +1,21 @@
 ---
 name: database-skills
-description: Compatibility power wrapper for the database-skills package.
+description: Power-oriented database execution pack for PostgreSQL, MySQL, Vitess, Neki, MongoDB, SQLite, Supabase, and Redis.
 ---
 
 # database-skills
 
-Use this wrapper when power-oriented flows need the consolidated database package.
+This is the power-mode entrypoint for database tasks.
+
+Primary source files:
+- `Ai Agent Workflow/skills/database-skills/SKILL.md`
+- `Ai Agent Workflow/skills/database-skills/LATEST_VERSIONS.md`
+
+Execution policy:
+1. Pick engine wrapper first.
+2. Use measurable optimization methods only.
+3. No schema/data destructive action without explicit confirmation.
+4. Always include rollback.
+
+Engine wrappers live in:
+- `Ai Agent Workflow/powers/database-skills/engines/`

package/Ai Agent Workflow/powers/database-skills/SKILL.md

@@ -1,9 +1,33 @@
 ---
 name: database-skills
-description: Compatibility power wrapper for the database-skills package.
+description: Power bridge for the unified database-skills package with engine-specific wrappers.
 ---
 
 # database-skills
 
-This power mirrors:
+Use this power as the routing layer over the database skill pack.
+
+Primary source of truth:
 - `Ai Agent Workflow/skills/database-skills/SKILL.md`
+- `Ai Agent Workflow/skills/database-skills/LATEST_VERSIONS.md`
+
+## Required flow
+
+1. Read the version baseline first.
+2. Choose the engine wrapper in `engines/<engine>/POWER.md`.
+3. Produce decisions with:
+   - indexing strategy,
+   - pagination strategy,
+   - query-plan evidence (`EXPLAIN` or equivalent),
+   - rollback path.
+
+## Engine wrappers
+
+- `engines/postgres/POWER.md`
+- `engines/mysql/POWER.md`
+- `engines/vitess/POWER.md`
+- `engines/neki/POWER.md`
+- `engines/mongodb/POWER.md`
+- `engines/sqlite/POWER.md`
+- `engines/supabase/POWER.md`
+- `engines/redis/POWER.md`

package/Ai Agent Workflow/powers/database-skills/engines/mongodb/POWER.md

@@ -0,0 +1,10 @@
+# mongodb
+
+Source skill:
+- `Ai Agent Workflow/skills/database-skills/skills/mongodb/SKILL.md`
+
+Focus:
+- Access-pattern-first schema design
+- Compound index strategy
+- Cursor/range pagination over deep `skip`
+- `explain("executionStats")` evidence

package/Ai Agent Workflow/powers/database-skills/engines/mysql/POWER.md

@@ -0,0 +1,10 @@
+# mysql
+
+Source skill:
+- `Ai Agent Workflow/skills/database-skills/skills/mysql/SKILL.md`
+
+Focus:
+- Composite/covering index design
+- Keyset pagination with stable ordering
+- `EXPLAIN` / `EXPLAIN ANALYZE` evidence
+- Online DDL lock and replication risk checks

package/Ai Agent Workflow/powers/database-skills/engines/neki/POWER.md

@@ -0,0 +1,10 @@
+# neki
+
+Source skill:
+- `Ai Agent Workflow/skills/database-skills/skills/neki/SKILL.md`
+
+Focus:
+- Shard key and locality planning
+- Cross-shard boundary minimization
+- Reversible migration milestones
+- Explicit assumption tracking (pre-GA)

package/Ai Agent Workflow/powers/database-skills/engines/postgres/POWER.md

@@ -0,0 +1,10 @@
+# postgres
+
+Source skill:
+- `Ai Agent Workflow/skills/database-skills/skills/postgres/SKILL.md`
+
+Focus:
+- Multicolumn/partial/INCLUDE indexes
+- Keyset pagination for deep lists
+- `EXPLAIN (ANALYZE, BUFFERS)` evidence
+- Vacuum/autovacuum and stats health

package/Ai Agent Workflow/powers/database-skills/engines/redis/POWER.md

@@ -0,0 +1,10 @@
+# redis
+
+Source skill:
+- `Ai Agent Workflow/skills/database-skills/skills/redis/SKILL.md`
+
+Focus:
+- Key schema as access index
+- Sorted set and SCAN-based pagination patterns
+- Pipeline/batching throughput optimization
+- Memory/latency diagnostics and eviction safety

package/Ai Agent Workflow/powers/database-skills/engines/sqlite/POWER.md

@@ -0,0 +1,10 @@
+# sqlite
+
+Source skill:
+- `Ai Agent Workflow/skills/database-skills/skills/sqlite/SKILL.md`
+
+Focus:
+- `EXPLAIN QUERY PLAN` verification
+- Multicolumn/covering index design
+- Keyset pagination for large local datasets
+- WAL/checkpoint tuning and transaction batching

package/Ai Agent Workflow/powers/database-skills/engines/supabase/POWER.md

@@ -0,0 +1,10 @@
+# supabase
+
+Source skill:
+- `Ai Agent Workflow/skills/database-skills/skills/supabase/SKILL.md`
+
+Focus:
+- RLS policy correctness and predicate indexing
+- Keyset pagination for heavy endpoints
+- Query optimization + advisor workflow
+- Pooler mode and managed/self-host compatibility checks

package/Ai Agent Workflow/powers/database-skills/engines/vitess/POWER.md

@@ -0,0 +1,10 @@
+# vitess
+
+Source skill:
+- `Ai Agent Workflow/skills/database-skills/skills/vitess/SKILL.md`
+
+Focus:
+- Vindex and VSchema routing quality
+- Shard-local query design
+- Shard-aware seek pagination
+- Resharding rollout + rollback safety

package/Ai Agent Workflow/powers/database-skills/steering/readme.md

@@ -1,9 +1,21 @@
 # database-skills steering
 
-Primary source:
-- `Ai Agent Workflow/skills/database-skills/`
+Use this steering map for power-mode database tasks.
 
-Suggested flow:
-1. Read hub SKILL
-2. Read engine SKILL
-3. Read engine references needed for current task
+## Routing map
+
+- Postgres: `engines/postgres/POWER.md`
+- MySQL: `engines/mysql/POWER.md`
+- Vitess: `engines/vitess/POWER.md`
+- Neki: `engines/neki/POWER.md`
+- MongoDB: `engines/mongodb/POWER.md`
+- SQLite: `engines/sqlite/POWER.md`
+- Supabase: `engines/supabase/POWER.md`
+- Redis: `engines/redis/POWER.md`
+
+## Required output for DB work
+
+- Indexing plan
+- Pagination plan
+- Query-plan evidence
+- Rollback plan

package/Ai Agent Workflow/skills/database-skills/LATEST_VERSIONS.md

@@ -0,0 +1,36 @@
+# Database Versions Baseline
+
+Last verified: 2026-02-20 (US)
+
+## Relational / SQL
+
+- PostgreSQL: **18.2** current minor for supported major 18.
+- MySQL:
+  - **8.4.8** current LTS patch.
+  - **9.6.0** latest Innovation release.
+- SQLite: **3.51.2** current stable release.
+- Vitess: **v23.0.2** current stable patch in v23.0 line.
+
+## Document / KV / Managed
+
+- MongoDB: **8.2.5** latest patch in current 8.2 minor line.
+- Redis Open Source: **8.4.0** latest GA major (8.2 remains an actively documented line).
+- Supabase Postgres:
+  - Managed projects may run **Postgres 17**.
+  - Self-hosted Docker docs currently call out **Postgres 15** compatibility constraints.
+- Neki: announced and in active development/waitlist stage (no GA semantic version yet).
+
+## Source links (official)
+
+- PostgreSQL versioning: https://www.postgresql.org/support/versioning/
+- MySQL release model: https://dev.mysql.com/doc/refman/8.4/en/mysql-releases.html
+- MySQL 8.4.8 LTS notes: https://dev.mysql.com/doc/relnotes/mysql/8.4/en/news-8-4-8.html
+- MySQL 9.6.0 Innovation notes: https://dev.mysql.com/doc/relnotes/mysql/9.6/en/news-9-6-0.html
+- SQLite current release: https://sqlite.org/releaselog/current.html
+- Vitess releases: https://vitess.io/docs/releases/
+- MongoDB 8.2 release notes: https://www.mongodb.com/docs/manual/release-notes/8.2/
+- Redis 8.4 updates: https://redis.io/docs/latest/develop/whats-new/8-4/
+- Redis OSS releases: https://github.com/redis/redis/releases
+- Supabase restore compatibility note: https://supabase.com/docs/guides/self-hosting/restore-from-platform
+- Neki announcement: https://planetscale.com/blog/announcing-neki
+- Neki product page: https://planetscale.com/neki

package/Ai Agent Workflow/skills/database-skills/README.md

@@ -1,12 +1,13 @@
 # database-skills
 
-Engine-specific database skill pack inspired by `planetscale/database-skills`, expanded for common stacks.
+Engine-specific database skill pack inspired by `planetscale/database-skills`, expanded for modern production stacks.
 
 ## Layout
 
 ```text
 database-skills/
 ├── README.md
+├── LATEST_VERSIONS.md
 ├── SKILL.md
 └── skills/
     ├── postgres/
@@ -35,7 +36,15 @@ database-skills/
         └── references/
 ```
 
+## What each engine pack must cover
+
+- Index strategy for real query patterns.
+- Pagination strategy (keyset/seek first, offset only when justified).
+- Query plan workflow (`EXPLAIN` or engine equivalent).
+- Write/read tradeoff notes.
+- Safe rollout + rollback notes for schema and operational changes.
+
 ## Notes
 
 - Use this package as the single database skill dependency in agents/workflows.
-- Keep engine-specific guidance in `skills/<engine>/references/`.
+- Keep version-sensitive guidance synced with `LATEST_VERSIONS.md`.

package/Ai Agent Workflow/skills/database-skills/SKILL.md

@@ -3,35 +3,100 @@ name: database-skills
 description: Unified database skill hub with engine-specific packs for PostgreSQL, MySQL, Vitess, Neki, MongoDB (Mongoose), SQLite, Supabase, and Redis.
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 metadata:
-  version: "1.0.0"
+  version: "2.0.0"
   domain: data
-  triggers: database, sql, postgres, mysql, vitess, neki, mongodb, mongoose, sqlite, supabase, redis, schema, migration, index, query, performance
+  triggers: database, sql, postgres, mysql, vitess, neki, mongodb, mongoose, sqlite, supabase, redis, schema, migration, index, query, performance, pagination, replication, pooling, sharding, cache
 ---
 
 # Database Skills Hub
 
-Use this as the single database package.
+Use this as the single database package. Load the target engine's `SKILL.md` from `skills/<engine>/`, then load relevant `references/*` files.
+
+## Engine selection
+
+| Situation | Engine |
+| --- | --- |
+| Relational OLTP, self-hosted or cloud | Postgres |
+| Relational OLTP, MySQL-compatible managed service | MySQL + Vitess (PlanetScale) |
+| Multi-tenant SaaS needing horizontal Postgres scale | Neki |
+| Document model, flexible schema | MongoDB |
+| Mobile / desktop / edge local storage | SQLite |
+| BaaS with built-in auth, storage & realtime | Supabase |
+| Caching, queues, leaderboards, pub/sub | Redis |
 
 ## Structure
 
-- `skills/postgres/`
-- `skills/mysql/`
-- `skills/vitess/`
-- `skills/neki/`
-- `skills/mongodb/`
-- `skills/sqlite/`
-- `skills/supabase/`
-- `skills/redis/`
+```
+skills/
+  postgres/
+    SKILL.md
+    references/
+      schema-indexing.md       ← index types, composite, partial, INCLUDE
+      performance-ops.md       ← EXPLAIN, pg_stat_statements, VACUUM, autovacuum
+      migrations.md            ← zero-downtime DDL, expand/contract, tools
+      connection-pooling.md    ← PgBouncer, pool sizing, serverless patterns
+
+  mysql/
+    SKILL.md
+    references/
+      query-indexing.md        ← EXPLAIN, composite indexes, covering, seek pagination
+      locking-ddl.md           ← INSTANT/INPLACE/COPY, MDL, gh-ost, deadlocks
+      replication.md           ← binlog formats, GTID, lag monitoring, read routing
+
+  vitess/
+    SKILL.md
+    references/
+      sharding-routing.md      ← VSchema, vindexes, sequences, scatter queries
+      operational-safety.md    ← Online DDL strategies, migration lifecycle, VReplication
+
+  neki/
+    SKILL.md
+    references/
+      architecture.md          ← sharded Postgres architecture, pre-sharding checklist
+      operations.md            ← migration planning, validation, provisional pre-GA guidance
+
+  mongodb/
+    SKILL.md
+    references/
+      modeling.md              ← embed vs reference, compound indexes, explain(), pagination
+      mongoose-nestjs.md       ← repository pattern, lean reads, transactions, NestJS setup
+      aggregation.md           ← pipeline stages, $group, $lookup, $facet, performance
+
+  sqlite/
+    SKILL.md
+    references/
+      local-first.md           ← WAL mode, migration patterns, sync/conflict strategies
+      performance.md           ← EXPLAIN QUERY PLAN, indexes, batch writes, checkpoint tuning
+
+  supabase/
+    SKILL.md
+    references/
+      rls-auth.md              ← RLS policies, auth.uid(), index predicates, service_role
+      performance-operations.md ← query optimization, connection modes, pooler selection
+
+  redis/
+    SKILL.md
+    references/
+      data-modeling.md         ← data structure selection, key naming, TTL strategy
+      cache-patterns.md        ← pipelining, SCAN, rate limiting, leaderboards, invalidation
+      operations.md            ← memory management, eviction policies, latency diagnostics
+```
 
-## Routing
+## Required flow
 
-1. Identify the target engine from the user request.
-2. Load that engine's `SKILL.md` first.
-3. Load only the referenced files needed for the current task.
-4. If engine is unclear, ask before implementation.
+1. Read `LATEST_VERSIONS.md` before proposing version-specific behavior.
+2. Use engine selection table above to pick the target engine.
+3. Load the target engine `SKILL.md` and relevant `references/*` files — read the ones that match the task (indexing, migrations, replication, etc.).
+4. Provide an optimization or implementation plan that includes:
+   - specific change with rationale,
+   - indexing or schema decisions,
+   - migration safety (online vs offline),
+   - rollback path.
+5. For production-impacting changes, include blast-radius assessment and rollout stages.
 
-## Global Guardrails
+## Cross-engine performance checklist
 
-- No destructive operations without explicit confirmation.
-- Include migration and rollback steps for production changes.
-- Use evidence-first tuning (`EXPLAIN`, plans, slow logs, lock metrics).
+- **Indexing**: add indexes only for real predicates and sort patterns. Drop unused indexes — they penalize writes.
+- **Pagination**: prefer keyset/seek for deep or high-throughput pagination. Reserve offset for shallow interactive pages only.
+- **Measurement**: compare before/after plans with engine-native explain tooling (`EXPLAIN ANALYZE`, `VEXPLAIN`, `explain()`). Validate with realistic cardinality.
+- **Safety**: no destructive data/schema operations without explicit user confirmation. Always include rollback/recovery steps.

package/Ai Agent Workflow/skills/database-skills/skills/mongodb/SKILL.md

@@ -1,15 +1,37 @@
 ---
 name: mongodb
-description: MongoDB and Mongoose modeling, indexing, query tuning, and transaction guidance.
+description: MongoDB and Mongoose modeling, indexing, pagination, query tuning, and transaction guidance.
 ---
 
 # MongoDB and Mongoose
 
-Load references as needed:
+## Optimization workflow
+
+1. Model around dominant read/write paths (embed vs reference).
+2. Add compound indexes for real filter + sort patterns.
+3. Validate with `explain("executionStats")`.
+4. Prefer range/keyset pagination over deep `skip`.
+5. Re-check index selectivity and write overhead as data grows.
+
+## Indexing techniques
+
+- Compound indexes over isolated single-field indexes when query shape demands it.
+- Keep index count controlled on write-heavy collections.
+- Use partial/sparse strategies only when semantics are correct.
+
+## Pagination techniques
+
+- Avoid large-offset `skip` on large collections.
+- Use boundary-based pagination with indexed monotonic key (`_id` or timestamp+id).
+- Keep deterministic sort and cursor boundary state.
+
+## Mongoose/NestJS guardrails
+
+- Keep schema indexes explicit in model definitions/migrations.
+- Use projections to avoid over-fetching large documents.
+- Use transactions only when cross-document invariants require them.
+
+## References
+
 - `references/modeling.md`
 - `references/mongoose-nestjs.md`
-
-Key rules:
-- Model by access pattern (embed vs reference).
-- Use compound indexes for dominant filters/sorts.
-- Use transactions only where multi-document invariants require them.

package/Ai Agent Workflow/skills/database-skills/skills/mongodb/references/aggregation.md

@@ -0,0 +1,153 @@
+# MongoDB — Aggregation Pipeline
+
+## Pipeline basics
+
+The aggregation pipeline is a sequence of stages, each transforming the document stream. Stages execute in order.
+
+```js
+db.orders.aggregate([
+  { $match: { status: 'complete', userId: 'u42' } },  // filter early
+  { $group: { _id: '$category', total: { $sum: '$amount' }, count: { $sum: 1 } } },
+  { $sort: { total: -1 } },
+  { $limit: 10 },
+  { $project: { category: '$_id', total: 1, count: 1, _id: 0 } }
+])
+```
+
+**Critical rule**: Put `$match` as early as possible to reduce documents flowing through subsequent stages. MongoDB can use indexes for `$match` at the start of a pipeline.
+
+## Common stages
+
+| Stage | Purpose |
+| --- | --- |
+| `$match` | Filter documents (use early, supports indexes) |
+| `$group` | Group by key, apply accumulators (`$sum`, `$avg`, `$min`, `$max`, `$push`, `$addToSet`) |
+| `$project` | Reshape documents (include/exclude/rename/compute fields) |
+| `$sort` | Sort (can use index when at start, before `$group`) |
+| `$limit` / `$skip` | Pagination (prefer range-based — see below) |
+| `$lookup` | Left outer join to another collection |
+| `$unwind` | Flatten an array field into individual documents |
+| `$addFields` | Add computed fields without removing existing |
+| `$facet` | Run multiple sub-pipelines in parallel (for multi-category aggregation) |
+| `$bucket` | Group into ranges (histogram) |
+| `$count` | Count documents |
+| `$out` / `$merge` | Write results to a collection |
+
+## $group accumulators
+
+```js
+{ $group: {
+  _id: '$category',
+  total:    { $sum: '$amount' },           // sum
+  average:  { $avg: '$amount' },           // average
+  max:      { $max: '$amount' },           // max
+  min:      { $min: '$amount' },           // min
+  count:    { $sum: 1 },                   // count rows
+  products: { $push: '$productId' },       // array of all values (duplicates kept)
+  unique:   { $addToSet: '$productId' },   // array of unique values
+  first:    { $first: '$createdAt' },      // first value in group
+}}
+```
+
+## $lookup — joins
+
+```js
+// Left join orders with users
+db.orders.aggregate([
+  { $match: { status: 'complete' } },
+  { $lookup: {
+    from: 'users',
+    localField: 'userId',
+    foreignField: '_id',
+    as: 'user'
+  }},
+  { $unwind: { path: '$user', preserveNullAndEmptyArrays: true } },
+  { $project: { total: 1, 'user.name': 1, 'user.email': 1 } }
+])
+```
+
+`$lookup` is expensive on large collections — **prefer embedding** if data is always accessed together. Always filter with `$match` before `$lookup` to minimize joined documents.
+
+Pipeline-style `$lookup` (MongoDB 3.6+) for filtered joins:
+```js
+{ $lookup: {
+  from: 'orderItems',
+  let: { orderId: '$_id' },
+  pipeline: [
+    { $match: { $expr: { $eq: ['$orderId', '$$orderId'] } } },
+    { $project: { sku: 1, qty: 1, _id: 0 } }
+  ],
+  as: 'items'
+}}
+```
+
+## $unwind
+
+Flattens array fields — generates one output document per array element:
+
+```js
+// Input: { _id: 1, tags: ['a', 'b', 'c'] }
+{ $unwind: '$tags' }
+// Output: { _id: 1, tags: 'a' }, { _id: 1, tags: 'b' }, { _id: 1, tags: 'c' }
+```
+
+Watch out: `$unwind` on an array of 1000 elements turns 1 doc into 1000. Use `preserveNullAndEmptyArrays: true` to keep docs with missing/empty arrays.
+
+## Pagination in aggregation
+
+Avoid `$skip` for deep pagination — it scans all skipped docs.
+
+```js
+// BAD: $skip is O(N)
+db.orders.aggregate([
+  { $sort: { createdAt: -1 } },
+  { $skip: 10000 },
+  { $limit: 20 }
+])
+
+// GOOD: range-based pagination
+db.orders.aggregate([
+  { $match: { createdAt: { $lt: lastSeenDate }, _id: { $lt: lastSeenId } } },
+  { $sort: { createdAt: -1, _id: -1 } },
+  { $limit: 20 }
+])
+```
+
+## $facet — parallel aggregations
+
+Run multiple sub-pipelines against the same input in one pass:
+
+```js
+db.products.aggregate([
+  { $match: { active: true } },
+  { $facet: {
+    byCategory: [
+      { $group: { _id: '$category', count: { $sum: 1 } } }
+    ],
+    priceRange: [
+      { $bucket: { groupBy: '$price', boundaries: [0, 50, 100, 200, 500], default: '500+' } }
+    ],
+    total: [
+      { $count: 'count' }
+    ]
+  }}
+])
+```
+
+## Performance tips
+
+- **Index for `$match` and `$sort`**: the pipeline can use an index only for `$match` and `$sort` stages that appear before any `$group`/`$project`/`$unwind`.
+- **Use `allowDiskUse: true`** for large aggregations that exceed the 100MB in-memory sort limit.
+- **`$project` early** to reduce document size flowing through the pipeline.
+- **Avoid `$lookup` on hot paths** — cache results or redesign schema to embed.
+- **Use `$merge` to pre-compute** expensive aggregations into a results collection, then query that.
+
+```js
+// Run explain on aggregation
+db.orders.explain('executionStats').aggregate([...])
+```
+
+## Sources
+- Aggregation pipeline: https://www.mongodb.com/docs/manual/aggregation/
+- Pipeline stages reference: https://www.mongodb.com/docs/manual/reference/operator/aggregation-pipeline/
+- Aggregation performance: https://www.mongodb.com/docs/manual/core/aggregation-pipeline-optimization/

package/Ai Agent Workflow/skills/database-skills/skills/mongodb/references/modeling.md

@@ -1,5 +1,96 @@
-# MongoDB Modeling
+# MongoDB — Modeling, Indexing, and Pagination
 
-- Embed for bounded one-to-few relationships.
-- Reference for large or shared entities.
-- Avoid unbounded arrays in hot collections.
+## Data modeling philosophy
+
+MongoDB is schema-flexible at the storage layer, but **your schema is defined by your queries, not by your data shape**. Model documents for the queries you actually run.
+
+### Embed vs reference
+
+| Embed | Reference (DBRef / manual) |
+| --- | --- |
+| Data is always accessed together | Data is accessed independently |
+| 1-to-1 or bounded 1-to-few | 1-to-many with unbounded growth |
+| Child data has no standalone identity | Child data is queried on its own |
+| Written/updated together | Updated at different rates |
+
+```js
+// Embed: order with line items (always fetched together, bounded count)
+{ _id: ..., userId: ..., lineItems: [ { sku, qty, price }, ... ] }
+
+// Reference: user with orders (orders accessed independently, unbounded)
+{ _id: ..., name: "Alice" }   // users collection
+{ _id: ..., userId: <ref>, total: 99 }  // orders collection
+```
+
+Avoid embedding unbounded arrays — document size limit is 16MB and large docs slow query/update performance.
+
+## Index types and when to use them
+
+| Type | Use for |
+| --- | --- |
+| **Single field** | Equality, range, sort on one field |
+| **Compound** | Combined equality + range + sort — column order matters |
+| **Multikey** | Fields that are arrays (auto-detected by MongoDB) |
+| **Text** | Full-text search on string fields |
+| **Wildcard** | Arbitrary field access patterns |
+| **2dsphere** | Geospatial queries |
+| **TTL** | Auto-delete documents after expiry |
+
+## Compound index design
+
+Same leftmost-prefix rule as SQL — **equality fields first, then range, then sort**:
+
+```js
+// Query: find open orders for a user, sorted by date
+db.orders.find({ userId: X, status: "open" }).sort({ createdAt: -1 })
+
+// Correct index: equality fields lead, sort field last
+db.orders.createIndex({ userId: 1, status: 1, createdAt: -1 })
+
+// Wrong: sort field before filter — doesn't eliminate docs efficiently
+db.orders.createIndex({ createdAt: -1, userId: 1, status: 1 })
+```
+
+## Reading query plans with explain()
+
+```js
+db.orders.find({ userId: 1 }).explain("executionStats")
+```
+
+Key things to check:
+- `winningPlan.stage`: `COLLSCAN` = full scan (bad on large collections), `IXSCAN` = index scan (good).
+- `executionStats.totalDocsExamined` vs `nReturned`: should be close. Large ratio = poor index coverage.
+- `executionStats.executionTimeMillis`: baseline to compare before/after index changes.
+
+## Avoid deep skip() pagination
+
+`skip(N)` makes MongoDB scan and discard N documents. On large collections this is O(N).
+
+```js
+// BAD: skip-based pagination
+db.orders.find().sort({ _id: 1 }).skip(10000).limit(20)
+
+// GOOD: range-based pagination using last seen _id (or cursor field)
+db.orders.find({ _id: { $gt: lastSeenId } }).sort({ _id: 1 }).limit(20)
+
+// For composite sort keys
+db.orders.find({
+  $or: [
+    { createdAt: { $lt: lastDate } },
+    { createdAt: lastDate, _id: { $lt: lastId } }
+  ]
+}).sort({ createdAt: -1, _id: -1 }).limit(20)
+```
+
+## Common modeling mistakes
+
+- **Storing growing arrays in a document**: the document grows without bound → move to a child collection.
+- **Using `$lookup` as a substitute for embedding**: `$lookup` is expensive; redesign the schema if you always join.
+- **Not projecting fields**: always project only needed fields to reduce document transfer size.
+- **Missing index on high-cardinality filter fields**: every `find()` cold path should have an index.
+
+## Sources
+- Explain plans: https://www.mongodb.com/docs/manual/reference/method/db.collection.explain/
+- `skip()` caveats: https://www.mongodb.com/docs/manual/reference/method/cursor.skip/
+- Query plans: https://www.mongodb.com/docs/manual/core/query-plans/
+- Data modeling guide: https://www.mongodb.com/docs/manual/data-modeling/