@cubis/foundry 0.3.10 → 0.3.12

package/Ai Agent Workflow/scripts/generate-powers.mjs

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+/**
+ * generate-powers.mjs
+ *
+ * Generates POWER.md files for Kiro from the canonical SKILL.md files in the
+ * skills/ directory. Powers are Kiro-specific wrappers around skills; the
+ * install source of truth for `cbx install` is ALWAYS `skills/<id>/SKILL.md`.
+ *
+ * Source priority (matching cubis.js installBundleArtifacts):
+ *   1. skills/<name>/SKILL.md  ← canonical (what `cbx install` uses)
+ *   2. powers/<name>/SKILL.md  ← fallback (local override only)
+ *
+ * Usage:
+ *   node "Ai Agent Workflow/scripts/generate-powers.mjs" [--dry-run] [--force] [--from-skills] [--sync-skills]
+ *
+ * Options:
+ *   --dry-run      Preview changes without writing files
+ *   --force        Overwrite existing POWER.md files
+ *   --from-skills  Also create missing power directories from skills/
+ *   --sync-skills  Sync canonical SKILL.md from skills/ → powers/ for every power
+ */
+
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { promises as fs } from "node:fs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..", "..");
+const ASSETS_ROOT = path.join(ROOT, "Ai Agent Workflow");
+const POWERS_ROOT = path.join(ASSETS_ROOT, "powers");
+const SKILLS_ROOT = path.join(ASSETS_ROOT, "skills");
+
+const ARGS = new Set(process.argv.slice(2));
+const DRY_RUN = ARGS.has("--dry-run");
+const FORCE = ARGS.has("--force");
+const FROM_SKILLS = ARGS.has("--from-skills");
+const SYNC_SKILLS = ARGS.has("--sync-skills");
+
+// ─── Kiro POWER.md frontmatter keys ────────────────────────────────────────
+// Keys added/ensured for Kiro power format
+const KIRO_REQUIRED_KEYS = {
+  inclusion: "manual",
+};
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+async function pathExists(p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readUtf8(p) {
+  return fs.readFile(p, "utf8");
+}
+
+async function writeUtf8(p, content) {
+  if (DRY_RUN) return;
+  await fs.mkdir(path.dirname(p), { recursive: true });
+  await fs.writeFile(p, content, "utf8");
+}
+
+async function copyDir(src, dest) {
+  if (DRY_RUN) return;
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Strip an outer code fence wrapper from file content.
+ * Handles both:
+ *   ```skill        (backtick × 3)
+ *   ````skill       (backtick × 4)
+ * Returns the raw inner content (the markdown string inside the fence),
+ * or the original content unchanged if no fence is found.
+ */
+function stripCodeFence(content) {
+  const trimmed = content.trim();
+  // Match opening fence: 3+ backticks followed by optional language identifier
+  const fenceMatch = trimmed.match(/^(`{3,})([a-zA-Z]*)\n([\s\S]*)\n\1\s*$/);
+  if (!fenceMatch) return trimmed;
+  return fenceMatch[3];
+}
+
+/**
+ * Parse YAML frontmatter block from raw markdown.
+ * Returns { frontmatterRaw, body } or null if no frontmatter found.
+ */
+function parseFrontmatter(markdown) {
+  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return null;
+  return {
+    frontmatterRaw: match[1],
+    body: match[2],
+  };
+}
+
+/**
+ * Inject Kiro-specific keys into a raw frontmatter string if they are absent.
+ * Returns updated frontmatter string.
+ */
+function injectKiroKeys(frontmatterRaw) {
+  let result = frontmatterRaw;
+  for (const [key, value] of Object.entries(KIRO_REQUIRED_KEYS)) {
+    const keyPresent = new RegExp(`^${key}\\s*:`, "m").test(result);
+    if (!keyPresent) {
+      // Prepend the key at the top of the frontmatter block
+      result = `${key}: ${value}\n${result}`;
+    }
+  }
+  return result;
+}
+
+/**
+ * Build POWER.md content from a SKILL.md source string.
+ * - Strips outer `skill` / ````skill fence if present
+ * - Parses frontmatter and injects Kiro keys
+ * - Re-wraps in a `markdown` code fence (matching the existing POWER.md convention)
+ */
+function buildPowerContent(skillMdContent) {
+  // 1. Strip outer code fence (the ````skill ... ```` wrapper)
+  const inner = stripCodeFence(skillMdContent);
+
+  // 2. Parse and update frontmatter
+  const parsed = parseFrontmatter(inner);
+  if (!parsed) {
+    // No frontmatter found – just re-wrap with markdown fence and return
+    return `\`\`\`\`markdown\n${inner}\n\`\`\`\`\n`;
+  }
+
+  const updatedFrontmatter = injectKiroKeys(parsed.frontmatterRaw);
+  const reconstructed = `---\n${updatedFrontmatter}\n---\n${parsed.body}`;
+
+  // 3. Wrap in markdown code fence for Kiro power format
+  return `\`\`\`\`markdown\n${reconstructed}\n\`\`\`\`\n`;
+}
+
+// ─── Core logic ─────────────────────────────────────────────────────────────
+
+async function getSubdirectories(dir) {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+async function processPowerDir(powerName) {
+  const powerDir = path.join(POWERS_ROOT, powerName);
+  const powerMdPath = path.join(powerDir, "POWER.md");
+
+  // Source priority mirrors cubis.js installBundleArtifacts (line ~2097):
+  //   skills/<name>/SKILL.md  ← canonical; what `cbx install` copies to the platform
+  //   powers/<name>/SKILL.md  ← local fallback only (may be a stale copy)
+  // Using skills/ as primary ensures POWER.md is generated from the same
+  // content that users receive when they run `cbx install`.
+  const canonicalSkill = path.join(SKILLS_ROOT, powerName, "SKILL.md");
+  const localSkill = path.join(powerDir, "SKILL.md");
+
+  let skillSource;
+  if (await pathExists(canonicalSkill)) {
+    skillSource = canonicalSkill;
+  } else if (await pathExists(localSkill)) {
+    skillSource = localSkill; // fallback: power-local override
+  } else {
+    return {
+      name: powerName,
+      result: "skip",
+      reason: "no SKILL.md found in skills/ or powers/",
+    };
+  }
+
+  const powerExists = await pathExists(powerMdPath);
+  if (powerExists && !FORCE) {
+    return {
+      name: powerName,
+      result: "skip",
+      reason: "POWER.md already exists (use --force to overwrite)",
+    };
+  }
+
+  const skillContent = await readUtf8(skillSource);
+  const powerContent = buildPowerContent(skillContent);
+
+  await writeUtf8(powerMdPath, powerContent);
+
+  return {
+    name: powerName,
+    result: powerExists ? "updated" : "created",
+    source: path.relative(ROOT, skillSource),
+  };
+}
+
+async function syncFromSkills() {
+  const skillDirs = await getSubdirectories(SKILLS_ROOT);
+  const created = [];
+
+  for (const name of skillDirs) {
+    // Skip non-skill entries
+    if (name.startsWith(".") || name.endsWith(".json") || name.endsWith(".md"))
+      continue;
+
+    const powerDir = path.join(POWERS_ROOT, name);
+    const skillDir = path.join(SKILLS_ROOT, name);
+    const skillMdSrc = path.join(skillDir, "SKILL.md");
+
+    if (!(await pathExists(skillMdSrc))) continue;
+    if (await pathExists(powerDir)) continue; // already exists
+
+    // Create power directory and copy SKILL.md
+    const skillMdDest = path.join(powerDir, "SKILL.md");
+    if (!DRY_RUN) {
+      await fs.mkdir(powerDir, { recursive: true });
+      await fs.copyFile(skillMdSrc, skillMdDest);
+    }
+
+    // Copy steering/, templates/, references/ if they exist
+    for (const subdir of ["steering", "templates", "references"]) {
+      const srcSub = path.join(skillDir, subdir);
+      const destSub = path.join(powerDir, subdir);
+      if (await pathExists(srcSub)) {
+        await copyDir(srcSub, destSub);
+      }
+    }
+
+    created.push(name);
+  }
+
+  return created;
+}
+
+/**
+ * Sync canonical SKILL.md from skills/ → powers/ for every power directory.
+ * This keeps powers/<name>/SKILL.md byte-identical to what `cbx install` will
+ * deliver to users, so Kiro and cbx users always see the same skill content.
+ */
+async function syncSkillsToPowers() {
+  const powerDirs = await getSubdirectories(POWERS_ROOT);
+  const synced = [];
+  const unchanged = [];
+  const missing = [];
+
+  for (const name of powerDirs) {
+    const canonicalSkill = path.join(SKILLS_ROOT, name, "SKILL.md");
+    const powerSkill = path.join(POWERS_ROOT, name, "SKILL.md");
+
+    if (!(await pathExists(canonicalSkill))) {
+      missing.push(name);
+      continue;
+    }
+
+    const canonical = await readUtf8(canonicalSkill);
+    const existing = (await pathExists(powerSkill))
+      ? await readUtf8(powerSkill)
+      : null;
+
+    if (existing === canonical) {
+      unchanged.push(name);
+      continue;
+    }
+
+    if (!DRY_RUN) {
+      await fs.mkdir(path.join(POWERS_ROOT, name), { recursive: true });
+      await fs.copyFile(canonicalSkill, powerSkill);
+    }
+
+    synced.push(name);
+  }
+
+  return { synced, unchanged, missing };
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log(`\nCubis Foundry — generate-powers.mjs`);
+  console.log(`Mode: ${DRY_RUN ? "DRY RUN (no files written)" : "LIVE"}`);
+  if (FORCE) console.log("Force: overwriting existing POWER.md files");
+  if (SYNC_SKILLS)
+    console.log(
+      "Sync-skills: syncing canonical SKILL.md from skills/ → powers/",
+    );
+  if (FROM_SKILLS)
+    console.log("From-skills: creating missing power dirs from skills/");
+  console.log();
+
+  // 1a. Sync canonical SKILL.md from skills/ → powers/ so powers/SKILL.md matches
+  //     what `cbx install` delivers (cubis.js always installs from skills/, not powers/).
+  if (SYNC_SKILLS) {
+    const { synced, missing } = await syncSkillsToPowers();
+    if (synced.length > 0) {
+      console.log(
+        `Synced SKILL.md for ${synced.length} power${synced.length === 1 ? "" : "s"} from skills/:`,
+      );
+      for (const name of synced) {
+        console.log(`  ↺ ${name}/SKILL.md`);
+      }
+      console.log();
+    } else {
+      console.log(
+        "All power SKILL.md files are already in sync with skills/.\n",
+      );
+    }
+    if (missing.length > 0) {
+      console.log(
+        `Note: ${missing.length} power${missing.length === 1 ? "" : "s"} have no matching skills/ entry (local-only):`,
+      );
+      for (const name of missing) console.log(`  ~ ${name}`);
+      console.log();
+    }
+  }
+
+  // 1b. Create missing power directories from skills/
+  if (FROM_SKILLS) {
+    const created = await syncFromSkills();
+    if (created.length > 0) {
+      console.log(
+        `Created ${created.length} new power director${created.length === 1 ? "y" : "ies"} from skills/:`,
+      );
+      for (const name of created) {
+        console.log(`  + ${name}/`);
+      }
+      console.log();
+    } else {
+      console.log("No new power directories needed from skills/.\n");
+    }
+  }
+
+  // 2. Process each power directory
+  const powerDirs = await getSubdirectories(POWERS_ROOT);
+  const results = { created: [], updated: [], skipped: [], errors: [] };
+
+  for (const name of powerDirs) {
+    try {
+      const result = await processPowerDir(name);
+      if (result.result === "created") results.created.push(result);
+      else if (result.result === "updated") results.updated.push(result);
+      else results.skipped.push(result);
+    } catch (err) {
+      results.errors.push({ name, error: err.message });
+    }
+  }
+
+  // 3. Report
+  if (results.created.length > 0) {
+    console.log(
+      `Created ${results.created.length} POWER.md file${results.created.length === 1 ? "" : "s"}:`,
+    );
+    for (const r of results.created) {
+      console.log(`  ✓ ${r.name}/POWER.md  (from ${r.source})`);
+    }
+    console.log();
+  }
+
+  if (results.updated.length > 0) {
+    console.log(
+      `Updated ${results.updated.length} POWER.md file${results.updated.length === 1 ? "" : "s"}:`,
+    );
+    for (const r of results.updated) {
+      console.log(`  ↺ ${r.name}/POWER.md  (from ${r.source})`);
+    }
+    console.log();
+  }
+
+  if (results.skipped.length > 0) {
+    console.log(
+      `Skipped ${results.skipped.length} director${results.skipped.length === 1 ? "y" : "ies"}:`,
+    );
+    for (const r of results.skipped) {
+      console.log(`  - ${r.name}: ${r.reason}`);
+    }
+    console.log();
+  }
+
+  if (results.errors.length > 0) {
+    console.error(`Errors (${results.errors.length}):`);
+    for (const r of results.errors) {
+      console.error(`  ✗ ${r.name}: ${r.error}`);
+    }
+    console.log();
+  }
+
+  const total = results.created.length + results.updated.length;
+  console.log(
+    `Done. ${total} POWER.md file${total === 1 ? "" : "s"} ${DRY_RUN ? "would be" : ""} generated.`,
+  );
+
+  if (results.errors.length > 0) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

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,16 @@ 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/`.
+- Use this package as the primary database hub in agents/workflows.
+- Keep `database-design`, `database-optimizer`, and `drift-flutter` active as companion skills for specialized or legacy-compatible flows.
+- 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 primary database hub. Keep `database-design`, `database-optimizer`, and `drift-flutter` available for specialized/legacy-compatible flows. 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.