dreamcontext 0.5.0

package/dist/skill-packs/engineering/firebase-cloud-functions/references/triggers_and_deployment.md

@@ -0,0 +1,139 @@
+# Triggers, Deployment & Runtime
+
+## All Trigger Types (2nd Gen)
+
+```js
+// HTTP
+const { onRequest, onCall } = require("firebase-functions/v2/https");
+
+// Firestore
+const { onDocumentCreated, onDocumentUpdated, onDocumentDeleted, onDocumentWritten } = require("firebase-functions/v2/firestore");
+
+// Auth
+const { onAuthUserCreated, onAuthUserDeleted } = require("firebase-functions/v2/identity");
+
+// Storage
+const { onObjectFinalized, onObjectDeleted } = require("firebase-functions/v2/storage");
+
+// Pub/Sub
+const { onMessagePublished } = require("firebase-functions/v2/pubsub");
+
+// Scheduler (cron)
+const { onSchedule } = require("firebase-functions/v2/scheduler");
+
+// Task Queue
+const { onTaskDispatched } = require("firebase-functions/v2/tasks");
+
+// Eventarc (custom events — 90+ sources)
+const { onCustomEventPublished } = require("firebase-functions/v2/eventarc");
+```
+
+## Trigger Examples
+
+### HTTP (onRequest)
+```js
+exports.api = onRequest({
+  timeoutSeconds: 60,
+  memory: "512MiB",
+  concurrency: 500,
+}, async (req, res) => {
+  res.json({ status: "ok" });
+});
+```
+
+### HTTP Callable (onCall)
+```js
+exports.addMessage = onCall({
+  enforceAppCheck: true,
+}, async (request) => {
+  const text = request.data.text;
+  const uid = request.auth?.uid;
+  // ...
+  return { result: "ok" };
+});
+```
+
+### Firestore Trigger
+```js
+exports.userUpdated = onDocumentUpdated(
+  { document: "users/{userId}", retry: true, concurrency: 200 },
+  async (event) => {
+    const before = event.data.before.data();
+    const after = event.data.after.data();
+    // Always compare before/after — see idempotency.md
+  }
+);
+```
+
+### Scheduled (Cron)
+```js
+exports.dailyCleanup = onSchedule("every day 02:00", async (event) => {
+  // Runs daily at 2 AM
+});
+```
+
+### Storage Trigger
+```js
+exports.onUpload = onObjectFinalized(
+  { bucket: "my-bucket" },
+  async (event) => {
+    const filePath = event.data.name;
+    const contentType = event.data.contentType;
+  }
+);
+```
+
+## Deployment
+
+```bash
+# Deploy all functions
+firebase deploy --only functions
+
+# Deploy specific function
+firebase deploy --only functions:myFunc
+
+# Deploy multiple
+firebase deploy --only functions:funcA,functions:funcB
+
+# Delete a function
+firebase functions:delete myFunc --force
+
+# List deployed functions
+firebase functions:list
+```
+
+## Renaming / Changing Trigger or Region
+
+Changing a function's name, trigger type, or region requires the **rename + deploy + delete** pattern to avoid downtime:
+
+1. Rename the function in code (new name)
+2. Deploy → both old and new functions run
+3. Delete old function: `firebase functions:delete oldName --force`
+
+**NEVER** change trigger/region in-place — it causes downtime.
+
+## Testing with Emulator
+
+```bash
+firebase emulators:start --only functions
+
+# With Firestore emulator (for trigger testing)
+firebase emulators:start --only functions,firestore
+```
+
+Test idempotency: trigger the same event 3–5 times and verify no duplicates or loops.
+
+## Project Structure (Recommended)
+
+```
+functions/
+├── package.json
+├── index.js          # or index.ts
+├── .env              # non-sensitive defaults
+├── .env.local        # emulator secrets (gitignored)
+└── src/
+    ├── http/         # HTTP + Callable functions
+    ├── triggers/     # Firestore, Auth, Storage triggers
+    ├── scheduled/    # Cron jobs
+    └── shared/       # Shared utilities, clients
+```

package/dist/skill-packs/engineering/firebase-firestore/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: firebase-firestore-basics
+description: Comprehensive Firestore skill covering provisioning, security rules, SDK usage, query mechanics, aggregation, and indexing. Use when writing Firestore queries, security rules, or setting up Firestore.
+compatibility: Best used with Firebase CLI (`npm install -g firebase-tools`). Supports Standard and Enterprise editions.
+---
+
+# Firestore Basics
+
+Complete guide for Cloud Firestore — provisioning, securing, querying, and optimizing.
+
+## Edition Awareness (Check First)
+
+Before writing ANY Firestore code, determine the edition:
+- **Standard**: Classic rules + limits. Most projects use this.
+- **Enterprise (Pipeline)**: 100+ features — groupBy, min/max, countDistinct, optional indexes, `query.explain()`. Available since Jan 2026.
+
+Agent MUST NOT suggest Pipeline syntax for Standard projects — it will error.
+
+## Provisioning
+
+Set up Cloud Firestore in your Firebase project and local environment: [provisioning.md](references/provisioning.md)
+
+## Security Rules
+
+Write and deploy Firestore Security Rules to protect your data: [security_rules.md](references/security_rules.md)
+
+## SDK Usage
+
+CRUD operations, real-time listeners, queries, aggregation, pagination: [web_sdk_usage.md](references/web_sdk_usage.md)
+
+## Query Mechanics (Deep Dive)
+
+**How Firestore processes queries internally** — execution model, index selection, cost model, aggregation mechanics, and the agent pre-query checklist: [query_mechanics.md](references/query_mechanics.md)
+
+## Indexes
+
+Index types, composite index ordering rules, Enterprise differences, and management: [indexes.md](references/indexes.md)
+
+## Agent Pre-Query Checklist
+
+Before generating ANY Firestore query:
+
+1. **Edition?** → Standard or Enterprise? Determines available syntax.
+2. **Aggregation?** → `getAggregateFromServer` (Standard) or `db.pipeline().aggregate()` (Enterprise). **NEVER** client-side reduce/sum/count.
+3. **Compound query?** → Composite index needed? Field order: equality → inequality → orderBy.
+4. **OR / in?** → Disjunction count ≤ 30.
+5. **Index exists?** → Standard: error + create link. Enterprise: warn about scan cost.
+6. **Pagination?** → Cursor-based only (`startAfter`). No offset.
+7. **Real-time?** → Cannot use Pipeline syntax. Use Core query.
+8. **Explain?** → Use `query.explain()` on Enterprise to verify planner decisions.

package/dist/skill-packs/engineering/firebase-firestore/references/indexes.md

@@ -0,0 +1,96 @@
+# Firestore Indexes Reference
+
+Indexes allow Firestore to ensure that query performance depends on the size of the result set, not the size of the database.
+
+## Index Types
+
+### Single-Field Indexes
+Firestore **automatically creates** a single-field index for every field in a document (and subfields in maps).
+*   **Support**: Simple equality queries (`==`) and single-field range/sort queries (`<`, `<=`, `orderBy`).
+*   **Behavior**: You generally don't need to manage these unless you want to *exempt* a field.
+
+### Composite Indexes
+A composite index stores a sorted mapping of all documents based on an ordered list of fields.
+*   **Support**: Complex queries that filter or sort by **multiple fields**.
+*   **Creation**: These are **NOT** automatically created. You must define them manually or via the console/CLI.
+
+**Field ordering is critical** — composite index fields MUST follow this order:
+1. All **equality** filter fields (any order among themselves)
+2. **Inequality/range** field (only 1 in Standard)
+3. **orderBy** fields (direction must match query)
+
+Example: `where("state","==","CA").where("pop",">=",1M).orderBy("pop","desc")` → index: `(state ASC, pop DESC)`
+
+## Automatic vs. Manual Management
+
+### What is Automatic?
+*   Indexes for simple queries.
+*   Merging of single-field indexes for multiple equality filters (e.g., `where("state", "==", "CA").where("country", "==", "USA")`).
+
+### When Do I Need to Act?
+If you attempt a query that requires a composite index, the SDK will throw an error containing a **direct link** to the Firebase Console to create that specific index.
+
+**Example Error:**
+> "The query requires an index. You can create it here: https://console.firebase.google.com/project/..."
+
+## Query Support Examples
+
+| Query Type | Index Required |
+| :--- | :--- |
+| **Simple Equality**<br>`where("a", "==", 1)` | Automatic (Single-Field) |
+| **Simple Range/Sort**<br>`where("a", ">", 1).orderBy("a")` | Automatic (Single-Field) |
+| **Multiple Equality**<br>`where("a", "==", 1).where("b", "==", 2)` | Automatic (Merged Single-Field) |
+| **Equality + Range/Sort**<br>`where("a", "==", 1).where("b", ">", 2)` | **Composite Index** |
+| **Multiple Ranges**<br>`where("a", ">", 1).where("b", ">", 2)` | **Composite Index** (and technically limited query support) |
+| **Array Contains + Equality**<br>`where("tags", "array-contains", "news").where("active", "==", true)` | **Composite Index** |
+
+## Best Practices & Exemptions
+
+You can **exempt** fields from automatic indexing to save storage or strictly enforce write limits.
+
+### 1. High Write Rates (Sequential Values)
+*   **Problem**: Indexing fields that increase sequentially (like `timestamp`) limits the write rate to ~500 writes/second per collection.
+*   **Solution**: If you don't query on this field, **exempt** it from simple indexing.
+
+### 2. Large String/Map/Array Fields
+*   **Problem**: Indexing limits (40k entries per doc). Indexing large blobs wastes storage.
+*   **Solution**: Exempt large text blobs or huge arrays if they aren't used for filtering.
+
+### 3. TTL Fields
+*   **Problem**: TTL (Time-To-Live) deletion can cause index churn.
+*   **Solution**: Exempt the TTL timestamp field from indexing if you don't query it.
+
+### Enterprise Edition Index Differences
+*   Single-field indexes are **NOT** auto-created.
+*   Supports sparse, unique, and non-sparse index types.
+*   Indexes are **optional** — Pipeline queries work without them (but slower).
+*   `query.explain()` available to inspect which index the planner selected and how many entries were scanned.
+*   Write fanout is reduced compared to Standard.
+
+## Management
+
+### Config files
+Your indexes should be defined in `firestore.indexes.json` (pointed to by `firebase.json`).
+
+```json
+{
+  "indexes": [
+    {
+      "collectionGroup": "cities",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "country", "order": "ASCENDING" },
+        { "fieldPath": "population", "order": "DESCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}
+```
+
+### CLI Commands
+
+Deploy indexes only:
+```bash
+firebase deploy --only firestore:indexes
+```

package/dist/skill-packs/engineering/firebase-firestore/references/provisioning.md

@@ -0,0 +1,101 @@
+# Provisioning Cloud Firestore
+
+## Manual Initialization
+
+Initialize the following firebase configuration files manually. Do not use `firebase init`, as it expects interactive inputs.
+
+1.  **Create `firebase.json`**: This file configures the Firebase CLI.
+2.  **Create `firestore.rules`**: This file contains your security rules.
+3.  **Create `firestore.indexes.json`**: This file contains your index definitions.
+
+### 1. Create `firebase.json`
+
+Create a file named `firebase.json` in your project root with the following content. If this file already exists, instead append to the existing JSON:
+
+```json
+{
+  "firestore": {
+    "rules": "firestore.rules",
+    "indexes": "firestore.indexes.json"
+  }
+}
+```
+
+This will use the default database. To use a different database, specify the database ID and location. You can check the list of available databases using `firebase firestore:databases:list`. If the database does not exist, it will be created when you deploy:
+
+```json
+{
+  "firestore": {
+    "rules": "firestore.rules",
+    "indexes": "firestore.indexes.json",
+    "database": "my-database-id",
+    "location": "us-central1"
+  }
+}
+```
+ 
+ To use Enterprise edition, specify the `enterprise` field.
+
+```json
+{
+  "firestore": {
+    "rules": "firestore.rules",
+    "indexes": "firestore.indexes.json",
+    "edition": "enterprise",
+    "database": "my-database-id",
+    "location": "us-central1"
+  }
+}
+```
+
+### 2. Create `firestore.rules`
+
+Create a file named `firestore.rules`. A good starting point (locking down the database) is:
+
+```
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /{document=**} {
+      allow read, write: if false;
+    }
+  }
+}
+```
+*See [security_rules.md](security_rules.md) for how to write actual rules.*
+
+### 3. Create `firestore.indexes.json`
+
+Create a file named `firestore.indexes.json` with an empty configuration to start:
+
+```json
+{
+  "indexes": [],
+  "fieldOverrides": []
+}
+```
+
+*See [indexes.md](indexes.md) for how to configure indexes.*
+
+
+## Deploy rules and indexes
+```bash
+# To deploy all rules and indexes
+firebase deploy --only firestore
+
+# To deploy just rules
+firebase deploy --only firestore:rules
+
+# To deploy just indexes
+firebase deploy --only firestore:indexes
+```
+
+## Local Emulation
+
+To run Firestore locally for development and testing:
+
+```bash
+firebase emulators:start --only firestore
+```
+
+This starts the Firestore emulator, typically on port 8080. You can interact with it using the Emulator UI (usually at http://localhost:4000/firestore).

package/dist/skill-packs/engineering/firebase-firestore/references/query_mechanics.md

@@ -0,0 +1,182 @@
+# Firestore Query Mechanics – Deep Dive
+
+How Firestore processes queries under the hood. Agent MUST internalize these rules before generating any query.
+
+## 1. Edition Check (FIRST STEP — Always)
+
+```js
+// Agent must determine edition before writing any query
+// Check firebase.json → "edition": "enterprise" or absence = Standard
+```
+
+| Capability | Standard | Enterprise (Pipeline) |
+|---|---|---|
+| Aggregation | count/sum/avg only | + min/max/countDistinct/groupBy |
+| Index requirement | Mandatory | Optional (but recommended) |
+| Pipeline syntax (`db.pipeline()`) | NOT available | Available |
+| `query.explain()` | Not available | Available |
+| Real-time listeners | Full support | Pipeline queries: NO real-time |
+| Disjunction limit | 30 | Higher |
+
+**Rule**: If project is Standard, NEVER suggest Pipeline syntax — it will throw an error.
+
+## 2. Query Execution Model (Full Flow)
+
+Firestore queries are **entirely index-driven**. No query does a full collection scan (Enterprise without indexes will scan but at extreme cost).
+
+### Step 1: Query Parsing & Planning
+Client SDK → protobuf → Firestore Frontend.
+Query planner evaluates:
+- Which collection / collection group?
+- Which fields have equality filters? (these become index prefix)
+- Inequality/range filters?
+- Aggregation or document fetch?
+
+### Step 2: Index Selection
+- Planner picks the **narrowest matching index**.
+- No match:
+  - **Standard**: Error + "Create index" console link.
+  - **Enterprise**: Falls back to full scan (slow, expensive).
+
+### Step 3: Index Scan (Most Critical)
+Internal structure (on Bigtable):
+- **Documents table** + **Indexes table**
+- Index row key: `[collection] + [field1 value] + [field2 value] + … + __name__ (doc ID)`
+- **Start position**: All equality filters become prefix. First inequality/orderBy field starts the range.
+- Executes a **single range scan** across the index.
+- Each matching row → document fetch (batched, 1 read = 1000 index entries).
+- Scan continues until: limit reached, filter breaks, or collection ends.
+
+### Step 4: Post-processing
+- OR/in/array-contains-any → split into multiple index scans (max 30 disjunctions, DNF conversion).
+- Results streamed to client, or aggregated server-side into single result.
+
+**Cost rule**: Query cost = number of scanned index entries. This is why aggregation MUST be server-side.
+
+## 3. Composite Index Field Ordering (Critical for Agents)
+
+When creating composite indexes, field order matters:
+
+1. **All equality filters** (any order among themselves)
+2. **Inequality/range filter** (only 1 allowed in Standard)
+3. **orderBy fields** (must match query direction)
+
+Example:
+```js
+where("state", "==", "CA")
+.where("population", ">=", 1000000)
+.orderBy("population", "desc")
+```
+Required composite index: `(state ASC, population DESC)`
+
+**Why only 1 inequality?**
+Index scan is a single range scan. Multiple inequalities would require separate ranges → performance guarantee breaks.
+
+## 4. OR / Disjunction Mechanics
+
+```js
+import { or } from "firebase/firestore";
+query(coll, or(where("a", "==", 1), where("b", ">", 10)));
+```
+
+Internally: 2 separate index scans + merge. Max 30 disjunctions (DNF form).
+
+**Restrictions**:
+- `not-in` cannot combine with `in`, `array-contains-any`, or `or`.
+- `array-contains` → only 1 per query.
+- `!=` and `not-in` exclude documents where the field doesn't exist.
+
+## 5. Aggregation Mechanics
+
+### Standard Edition
+```js
+import { count, sum, average, getAggregateFromServer } from "firebase/firestore";
+
+const snapshot = await getAggregateFromServer(q, {
+  totalCount: count(),
+  totalPop: sum("population"),
+  avgPop: average("population")
+});
+console.log(snapshot.data()); // { totalCount: 42, totalPop: 12345678, avgPop: 294420 }
+```
+- Supported: `count()`, `sum(field)`, `average(field)`
+- NOT supported: min, max, groupBy (Enterprise only)
+- Reads index only — 1 read per 1000 index entries
+- 60-second timeout
+- Security rules apply to aggregation queries
+
+### Enterprise Edition (Pipeline)
+```js
+const result = await db.pipeline()
+  .collection("orders")
+  .where("status", "==", "shipped")
+  .aggregate({
+    accumulators: [
+      sum("totalAmount").as("revenue"),
+      count().as("orderCount"),
+      min("totalAmount").as("minOrder"),
+      countDistinct("customerId").as("uniqueCustomers")
+    ],
+    groups: ["productId"]  // GROUP BY
+  })
+  .sort("totalPop", "desc")
+  .limit(10)
+  .execute();
+```
+Pipeline is a true stage-by-stage engine: regex, map, filter-after-aggregate supported.
+
+**CRITICAL RULE**: NEVER fetch all documents and reduce/sum client-side. Cost is 10-1000x higher. Always use server-side aggregation.
+
+## 6. Pagination
+
+**Cursor pagination** (only correct approach):
+```js
+import { startAfter, limit, orderBy } from "firebase/firestore";
+
+// Page 1
+const first = query(citiesRef, orderBy("name"), limit(25));
+const snapshot = await getDocs(first);
+const lastDoc = snapshot.docs[snapshot.docs.length - 1];
+
+// Page 2
+const next = query(citiesRef, orderBy("name"), startAfter(lastDoc), limit(25));
+```
+
+- `startAfter(lastDoc)` → resumes from the same index position (most efficient).
+- Firestore has NO offset-based pagination. Do not simulate it.
+- `startAt` / `startAfter` / `endAt` / `endBefore` — all require matching `orderBy`.
+
+## 7. Real-time Listener Internals
+
+- Listener sets up an **index watcher**.
+- On index change → incremental update pushed (no full rescan).
+- Pipeline queries (Enterprise) do NOT support real-time listeners — use Core query syntax for real-time.
+
+## 8. Collection Group Queries
+
+```js
+import { collectionGroup } from "firebase/firestore";
+const q = query(collectionGroup(db, "landmarks"), where("type", "==", "museum"));
+```
+Queries across ALL subcollections with the same name, regardless of parent document.
+
+## 9. query.explain() (Enterprise Only)
+
+```js
+const explained = await query.explain();
+// Shows: which index selected, entries scanned, execution plan
+```
+Use to debug slow queries and verify index selection.
+
+## 10. Agent Pre-Query Checklist
+
+Before generating ANY Firestore query, the agent MUST check:
+
+1. **Edition?** → Standard or Enterprise? Determines available syntax.
+2. **Aggregation needed?** → Pipeline (Enterprise) or `getAggregateFromServer` (Standard). NEVER client-side reduce.
+3. **Compound query?** → Will it need a composite index? (equality fields → inequality → orderBy)
+4. **OR / in present?** → Disjunction count ≤ 30.
+5. **Index exists?** → Enterprise: warn about cost without index. Standard: suggest index creation link.
+6. **Pagination?** → Cursor-based only (`startAfter`). No offset.
+7. **Real-time needed?** → Cannot use Pipeline syntax. Use Core query.
+8. **`query.explain()`** → Recommend for Enterprise to verify planner decisions.