@intentsolutionsio/jeremy-firestore 2.0.0

package/skills/firestore-operations-manager/ARD.md

@@ -0,0 +1,215 @@
+# ARD: Firestore Operations Manager Skill
+
+> Part of [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)
+
+## System Context
+
+This skill operates within the Firestore ecosystem on Google Cloud Platform. The primary components are:
+
+```
+┌──────────────┐     ┌───────────────────┐     ┌──────────────────┐
+│ Admin SDK     │────▶│ Cloud Firestore    │────▶│ Composite Indexes│
+│ (Node.js)     │     │ (Document DB)      │     │ (auto + manual)  │
+└──────────────┘     └───────┬───────────┘     └──────────────────┘
+                              │
+                    ┌─────────┴──────────┐
+                    │                     │
+              ┌─────▼──────┐     ┌───────▼────────┐
+              │ Security    │     │ Firestore       │
+              │ Rules       │     │ Emulator        │
+              │ (deploy)    │     │ (localhost:8080) │
+              └────────────┘     └────────────────┘
+```
+
+### External Systems
+
+| System | Role | Interface |
+|--------|------|-----------|
+| Cloud Firestore | Document database, query engine | Admin SDK `firestore()`, REST API |
+| Security Rules | Access control layer evaluated on every read/write | `firestore.rules` file deployed via CLI |
+| Composite Indexes | Required for multi-field queries | `firestore.indexes.json` deployed via CLI |
+| Firestore Emulator | Local Firestore replica for testing | `localhost:8080`, reset between test runs |
+| Firebase Auth | Identity provider (rules reference `request.auth`) | Auth emulator at `localhost:9099` for testing |
+
+## Data Flow
+
+### Standard CRUD Flow
+
+```
+1. Identify operation type (create/read/update/delete)
+2. Validate schema: read sample doc to understand existing fields
+3. Check security rules: will the operation be allowed?
+4. Check indexes: does the query need a composite index?
+5. Execute operation (single doc or batch)
+6. Verify result (read-after-write or emulator assertion)
+```
+
+### Batch Migration Flow
+
+```
+1. Read migration spec: source collection, target field(s), transform function
+2. Check for existing checkpoint in _migrations/{migrationId}
+3. Query next batch of documents (500, starting after checkpoint cursor)
+4. Apply transform to each document
+5. Commit batch (500 writes max per commit)
+6. Write checkpoint: { lastDocId, processedCount, status: "in_progress" }
+7. Repeat steps 3-6 until no more documents
+8. Write final checkpoint: { processedCount, skippedCount, status: "completed" }
+```
+
+### Security Rules Testing Flow
+
+```
+1. Write firestore.rules with helper functions
+2. Start Firestore + Auth emulators
+3. Create test contexts (authenticated, unauthenticated, admin)
+4. Assert each access pattern (read/write per collection per role)
+5. Fix failing assertions by adjusting rules
+6. Deploy: firebase deploy --only firestore:rules
+```
+
+## Design Decisions
+
+### DD-1: Batch Over Individual Writes
+
+**Decision**: All multi-document operations use `WriteBatch` (up to 500 operations) rather than individual `doc.set()` or `doc.update()` calls.
+
+**Rationale**: Individual writes incur one round trip each. A batch of 500 writes completes in a single round trip, reducing latency by ~500x and cost by reducing billable operations. Firestore enforces a hard limit of 500 operations per batch commit.
+
+**Implementation**: Chunk document arrays into groups of 500, commit each chunk, and log progress:
+
+```typescript
+const BATCH_SIZE = 500;
+for (let i = 0; i < docs.length; i += BATCH_SIZE) {
+  const batch = db.batch();
+  const chunk = docs.slice(i, i + BATCH_SIZE);
+  chunk.forEach(doc => batch.update(doc.ref, transform(doc.data())));
+  await batch.commit();
+  console.log(`Committed ${Math.min(i + BATCH_SIZE, docs.length)} / ${docs.length}`);
+}
+```
+
+### DD-2: Cursor-Based Pagination for Large Reads
+
+**Decision**: Queries that may return more than 100 documents use `startAfter(lastDoc)` cursor pagination, never `offset()`.
+
+**Rationale**: Firestore's `offset(N)` still reads and bills for the skipped N documents. Cursor-based pagination with `startAfter()` reads only the next page, making it O(pageSize) per page instead of O(offset + pageSize).
+
+**Trade-off**: Requires storing the last document snapshot or a deterministic sort field. All paginated queries must include an `orderBy()` clause.
+
+### DD-3: Emulator-First Testing
+
+**Decision**: All security rules and query patterns are tested against the Firestore emulator before any production deployment.
+
+**Rationale**: Security rules errors in production silently block operations with `PERMISSION_DENIED`. The emulator provides instant feedback and supports `@firebase/rules-unit-testing` for programmatic assertions. Emulator tests run in < 5 seconds versus deploying rules to production (30-60 seconds).
+
+**Constraint**: The emulator does not enforce billing or quotas, so cost estimation must be done separately.
+
+### DD-4: Checkpoint-Based Migration Resumption
+
+**Decision**: Long-running migrations write a checkpoint document after each batch to `_migrations/{migrationId}`.
+
+**Rationale**: A migration processing 100,000 documents takes 200 batch commits. If the script crashes at batch 150, without checkpoints it must restart from document 0 (re-reading 75,000 already-processed documents). With checkpoints, it reads the last checkpoint and resumes from document 75,001.
+
+**Checkpoint document schema**:
+```typescript
+interface MigrationCheckpoint {
+  migrationId: string;
+  collection: string;
+  lastDocumentId: string;        // cursor for startAfter()
+  processedCount: number;
+  skippedCount: number;
+  failedCount: number;
+  status: "in_progress" | "completed" | "failed";
+  startedAt: Timestamp;
+  updatedAt: Timestamp;
+}
+```
+
+### DD-5: Distributed Counters for Hot Documents
+
+**Decision**: Documents expected to receive > 1 write per second use a sharded counter pattern instead of `FieldValue.increment()` on a single document.
+
+**Rationale**: Firestore supports a sustained write rate of 1 write per second per document. Higher rates cause `ABORTED` errors due to contention. Distributing writes across N shard documents and summing on read provides Nx throughput.
+
+**When to use**: Page view counters, like counts, real-time vote tallies. Not needed for user profile updates or low-frequency writes.
+
+### DD-6: Index-Aware Query Generation
+
+**Decision**: When generating a query with multiple `where()` filters or `where()` + `orderBy()` on different fields, the skill must also produce the composite index definition.
+
+**Rationale**: Firestore requires composite indexes for these queries. Without the index, the query fails at runtime with `FAILED_PRECONDITION`. Generating the index alongside the query prevents this failure mode entirely.
+
+## Component Design
+
+### Migration Engine
+
+```
+MigrationRunner
+├── readCheckpoint(migrationId)     → MigrationCheckpoint | null
+├── runBatch(query, transform)      → { processed, skipped, failed }
+├── writeCheckpoint(checkpoint)     → void
+├── run(config)                     → MigrationResult
+│   ├── Resume from checkpoint if exists
+│   ├── Loop: query batch → transform → commit → checkpoint
+│   └── Write final status
+└── dryRun(config)                  → MigrationResult (reads only, no writes)
+```
+
+### Rules Generator
+
+```
+RulesGenerator
+├── addCollection(name, accessPatterns)
+├── addHelper(name, body)
+├── addFieldValidation(collection, fieldRules)
+├── generate()                       → string (firestore.rules content)
+└── generateTests()                  → string (rules-unit-testing code)
+```
+
+### Index Manager
+
+```
+IndexManager
+├── analyzeQuery(query)              → IndexDefinition | null
+├── readExistingIndexes(path)        → IndexDefinition[]
+├── mergeIndexes(existing, new)      → IndexDefinition[]
+└── writeIndexFile(path, indexes)    → void
+```
+
+## Failure Modes and Recovery
+
+| Failure | Detection | Recovery |
+|---------|-----------|----------|
+| PERMISSION_DENIED on write | Error code from Admin SDK | Check security rules; test with emulator; verify auth context |
+| FAILED_PRECONDITION (missing index) | Error message contains index creation URL | Add index to `firestore.indexes.json`; deploy with `firebase deploy --only firestore:indexes` |
+| ABORTED (write contention) | Transaction retry count > 0 | Admin SDK auto-retries 5 times; if persists, redesign to reduce writes to that document |
+| Batch commit partially fails | Exception mid-batch (network, timeout) | Resume from last checkpoint; the failed batch is atomic (all or nothing) |
+| DEADLINE_EXCEEDED on read | Query took > 60 seconds | Add indexes; reduce query scope with tighter filters; paginate |
+| RESOURCE_EXHAUSTED | 429 from Firestore API | Back off; check if sustained write rate > 10k/sec database limit |
+
+## Observability
+
+### Migration Logging
+
+Every batch commit logs:
+```
+[migration:backfill-status-field] Batch 150/200 committed. Processed: 75000, Skipped: 12, Failed: 0. Elapsed: 4m32s.
+```
+
+### Cost Estimation
+
+Before executing large operations, estimate cost:
+```
+Operation: backfill 100,000 documents
+  Reads:   100,000 × $0.06/100k = $0.06
+  Writes:  100,000 × $0.18/100k = $0.18
+  Total estimated cost: $0.24
+```
+
+### Key Metrics
+
+- Batch commit latency (p50/p95 per commit)
+- Documents processed per minute
+- Contention retry count (should be near zero)
+- Security rules evaluation latency (visible in Firebase Console > Firestore > Rules)

package/skills/firestore-operations-manager/PRD.md

@@ -0,0 +1,106 @@
+# PRD: Firestore Operations Manager Skill
+
+## Problem Statement
+
+Firestore operations at scale require deep knowledge of batch write mechanics, composite index design, security rules authoring, and migration strategies. Developers routinely hit production issues -- missing composite indexes that crash queries, write contention on hot documents, security rules that silently block legitimate operations, and data migrations that lose documents or corrupt fields.
+
+These problems share a root cause: Firestore's document model and operational constraints (500-write batch limit, 1-write-per-second-per-document sustained, mandatory composite indexes for multi-field queries) are well documented but poorly surfaced at development time. Errors appear only at runtime, often in production.
+
+## Target Users
+
+| Persona | Description | Key Need |
+|---------|-------------|----------|
+| Firebase developer | Building apps on Firestore, intermediate skill | Correct CRUD patterns, query optimization, index guidance |
+| Backend engineer | Migrating data or building ingestion pipelines | Safe batch operations with checkpoints and rollback |
+| Data team | Managing production Firestore data at scale | Migration strategies, schema evolution, cost control |
+| Security-conscious developer | Writing or auditing Firestore security rules | Rules that pass emulator tests and enforce least privilege |
+
+## Success Criteria
+
+1. **Zero data loss on migrations**: Batch operations include checkpointing so that a failure at document 50,000 of 100,000 resumes from 50,000, not from 0.
+2. **Correct indexes on first deploy**: Composite indexes are identified before deployment, not discovered via runtime FAILED_PRECONDITION errors.
+3. **Rules pass emulator tests**: Security rules generated by this skill pass `@firebase/rules-unit-testing` validation against expected access patterns.
+4. **Batch operations under limits**: All batch writes stay within the 500-operation limit per commit; all transactions complete within the 270-second server-side deadline.
+5. **Paginated reads by default**: Queries returning potentially large result sets use cursor-based pagination, not unbounded `.get()`.
+
+## Scope
+
+### In Scope
+
+- Document CRUD (create, read, update, delete) with proper error handling
+- Batch writes (up to 500 operations per commit) with retry logic
+- Transactions for multi-document atomic operations
+- Composite index detection and `firestore.indexes.json` generation
+- Security rules authoring with helper functions and field-level validation
+- Emulator-first testing workflow for rules and queries
+- Data migrations: backfill new fields, transform existing fields, move between collections
+- Cursor-based pagination for large result sets
+- Write contention mitigation (distributed counters, sharding)
+- Cost estimation for read/write patterns
+
+### Out of Scope
+
+- Firestore-to-BigQuery export streaming (use Firestore Extensions)
+- Real-time listener architecture design
+- Firestore in Datastore mode
+- Cross-database replication or multi-region configuration
+- Vertex AI vector search in Firestore (covered by firebase-vertex-ai skill)
+
+## Functional Requirements
+
+### FR-1: Schema-Aware CRUD
+The skill must detect the existing collection schema (by reading sample documents) before proposing writes. New fields added via `update()` must not overwrite existing data unless explicitly requested.
+
+### FR-2: Batch Write Management
+Batch writes must:
+- Chunk operations into groups of 500 (Firestore limit per `batch.commit()`)
+- Log progress every N documents (configurable, default 1,000)
+- Write a checkpoint document after each successful batch so the operation can resume
+- Retry failed batches with exponential backoff (3 attempts, 1s/2s/4s delays)
+
+### FR-3: Composite Index Generation
+When the skill generates a query with multiple `where()` clauses or a `where()` + `orderBy()` combination, it must also produce the corresponding composite index entry for `firestore.indexes.json`.
+
+### FR-4: Security Rules
+Generated rules must:
+- Deny all access by default (no `match /{document=**} { allow read, write: if true }`)
+- Use helper functions for authentication and ownership checks
+- Include field-level validation for create and update operations
+- Be testable with `@firebase/rules-unit-testing`
+
+### FR-5: Migration Operations
+Migrations must:
+- Support backfill (add field to existing documents) and transform (modify field values)
+- Write a checkpoint after each batch to a `_migrations/{migrationId}` document
+- Support dry-run mode that reads but does not write
+- Produce a summary (documents processed, skipped, failed)
+
+### FR-6: Pagination
+Queries that may return more than 100 documents must use `startAfter()` cursor-based pagination. The skill must produce both the query code and the pagination cursor management logic.
+
+## Non-Functional Requirements
+
+- **Throughput**: Batch operations must sustain 500 writes per second against Firestore without triggering rate limits (using staggered batch commits).
+- **Idempotency**: Migrations must be idempotent -- running the same migration twice produces the same result without duplicating data.
+- **Cost transparency**: For operations affecting > 1,000 documents, the skill must estimate Firestore read/write costs using current pricing ($0.06/100k reads, $0.18/100k writes).
+- **Emulator compatibility**: All generated code must work against the Firestore emulator (`localhost:8080`) with no modification.
+
+## Dependencies
+
+| Dependency | Version | Purpose |
+|------------|---------|---------|
+| firebase-admin | >= 12.0 | Server-side Firestore access |
+| @firebase/rules-unit-testing | >= 3.0 | Security rules testing |
+| Firebase CLI | >= 13.0 | Emulator, rules deploy, index deploy |
+| Node.js | >= 18 LTS | Runtime for Admin SDK scripts |
+
+## Risks and Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Hot document write contention | Writes to same doc > 1/sec cause ABORTED errors | Use distributed counters or sharded writes for high-throughput paths |
+| Composite index build time | New indexes take minutes to hours for large collections | Deploy indexes before code that depends on them; use `firebase firestore:indexes` to check status |
+| Security rules too restrictive | Legitimate operations blocked in production | Test all access patterns against emulator before deploy |
+| Migration halfway failure | Partial data state if script crashes mid-batch | Checkpoint after each batch; resume from last checkpoint |
+| Unbounded reads | Forgetting `.limit()` on a million-doc collection | Enforce pagination for any query without a known small result set |
+| Stale reads in transactions | Reading outside transaction sees older data | Always read within `runTransaction()` when consistency matters |

package/skills/firestore-operations-manager/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: firestore-operations-manager
+description: |
+  Manage Firebase/Firestore operations including CRUD, queries, batch processing, and index/rule guidance.
+  Use when you need to create/update/query Firestore documents, run batch writes, troubleshoot missing indexes, or plan migrations.
+  Trigger with phrases like "firestore operations", "create firestore document", "batch write", "missing index", or "fix firestore query".
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(cmd:*)
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatible-with: claude-code, codex, openclaw
+tags: [community, migration, firestore-operations]
+---
+# Firestore Operations Manager
+
+Operate Firestore safely in production: schema-aware CRUD, query/index tuning, batch processing, and guardrails for permissions and cost.
+
+## Overview
+
+Use this skill to design Firestore data access patterns and implement changes with the right indexes, security rules, and operational checks (emulator tests, monitoring, and rollback plans).
+
+## Prerequisites
+
+- A Firebase project with Firestore enabled (or a local emulator setup)
+- A clear collection/document schema (or permission to propose one)
+- Credentials for the target environment (service account / ADC) and a plan for secrets
+
+## Instructions
+
+1. Identify the operation: create/update/delete/query/batch/migration.
+2. Confirm schema expectations and security rules constraints.
+3. Implement the change (or propose a patch) using safe patterns:
+   - prefer batched writes/transactions where consistency matters
+   - add pagination for large queries
+4. Check indexes:
+   - detect required composite indexes and provide `firestore.indexes.json` updates
+5. Validate:
+   - run emulator tests or a minimal smoke query
+   - confirm cost/perf implications for the query pattern
+
+## Output
+
+- Code changes or snippets for the requested Firestore operation
+- Index recommendations (and config updates when needed)
+- A validation checklist (emulator commands and production smoke tests)
+
+## Error Handling
+
+- Permission denied: identify the rule/role blocking the operation and propose least-privilege changes.
+- Missing index: provide the exact composite index needed for the query.
+- Hotspot/latency issues: propose sharding, pagination, or query redesign.
+
+## Examples
+
+**Example: Fix a failing query**
+- Request: “This query needs a composite index—what do I add?”
+- Result: the exact index definition and a safer query pattern if needed.
+
+**Example: Batch migration**
+- Request: “Backfill a new field across 100k docs.”
+- Result: batched write strategy, checkpoints, and rollback guidance.
+
+## Resources
+
+- Full detailed guide (kept for reference): `${CLAUDE_SKILL_DIR}/references/SKILL.full.md`
+- Firestore docs: https://firebase.google.com/docs/firestore
+- Firestore indexes: https://firebase.google.com/docs/firestore/query-data/indexing

package/skills/firestore-operations-manager/references/errors.md

@@ -0,0 +1,85 @@
+# Firestore Operations Manager: Error Reference
+
+## Security Rules Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `PERMISSION_DENIED: Missing or insufficient permissions` | Security rules block the read or write | Check `firestore.rules` for the matching collection path; verify `request.auth` is not null and meets rule conditions |
+| `PERMISSION_DENIED` on admin SDK writes | Admin SDK bypasses rules by default; this error means the service account lacks IAM roles | Grant `roles/datastore.user` to the service account in IAM |
+| Rules pass in emulator but fail in production | Rules reference a document that does not exist in production (e.g., `get()` on missing user profile) | Ensure referenced documents exist before deploying; add null checks in rules |
+| `request.resource.data.X` undefined | Write operation does not include field `X` that rules validate | Add the required field to the write payload, or adjust rules to use `request.resource.data.get('X', default)` |
+
+## Composite Index Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `FAILED_PRECONDITION: The query requires an index` | Query uses multiple `where()` clauses or `where()` + `orderBy()` on different fields without a composite index | Click the URL in the error message to auto-create, or add to `firestore.indexes.json` and deploy |
+| Index build stuck at "Building" | Large collection, or conflicting index on same fields | Wait (can take hours for millions of docs); check Firebase Console > Firestore > Indexes for status |
+| `INVALID_ARGUMENT: Too many composite indexes` | Exceeded 200 composite index limit per database | Remove unused indexes; consolidate queries to share indexes |
+| Query works locally but fails in production | Emulator does not enforce index requirements | Always deploy indexes before deploying code that uses new queries |
+
+## Write Contention Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `ABORTED: Too much contention on these documents` | Multiple clients writing to the same document simultaneously (> 1 write/sec sustained) | Use distributed counters or sharded writes for high-frequency update paths |
+| `ABORTED` inside `runTransaction()` | Transaction read-set modified by another write before commit | Admin SDK auto-retries up to 5 times; if still failing, reduce transaction scope or redesign data model |
+| Transaction succeeds on retry but data looks wrong | Read outside transaction sees stale data; write based on stale read | Move all reads that inform writes inside `runTransaction()` |
+
+## Batch Operation Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `INVALID_ARGUMENT: maximum 500 writes allowed per request` | Batch contains > 500 operations | Chunk operations into groups of 500; commit each chunk separately |
+| `DEADLINE_EXCEEDED` on `batch.commit()` | Batch took > 270 seconds server-side | Reduce batch size; check if individual document writes trigger expensive Cloud Functions |
+| Partial failure on batch | Network error after server received but before client got response | Batch commits are atomic: either all 500 succeed or none do; safe to retry the entire batch |
+| `NOT_FOUND: No document to update` inside batch | `batch.update()` called on a document that does not exist | Use `batch.set(ref, data, { merge: true })` instead, or verify document existence before batching |
+
+## Transaction Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `ABORTED: Transaction was aborted due to contention` | Concurrent writes to documents in the transaction's read set | Reduce documents read in transaction; Admin SDK retries automatically |
+| `DEADLINE_EXCEEDED: Transaction has expired` | Transaction exceeded 270-second server-side limit | Break large transactions into smaller ones; avoid long-running async work inside transaction |
+| `INVALID_ARGUMENT: Transaction has already been committed/rolled back` | Calling operations on a transaction object after it resolved | Ensure all operations happen before the transaction callback returns |
+| Writes outside transaction not seeing transaction results | Reads after `runTransaction()` returns may hit cache | Use `{ source: 'server' }` for critical post-transaction reads on client SDK |
+
+## Query Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `INVALID_ARGUMENT: Cannot have inequality filters on multiple properties` | Query has `where('a', '>', x)` and `where('b', '<', y)` | Restructure query: inequality filter on one field only; use composite index for second field with `==` |
+| `INVALID_ARGUMENT: Order by must match the first inequality field` | `orderBy('name')` when inequality filter is on `createdAt` | Add `orderBy('createdAt')` before any other `orderBy()` |
+| Empty results when documents exist | Query field name has typo, or field stored as different type (string vs number) | Verify field name casing; check document in Firebase Console; Firestore is case-sensitive |
+| `RESOURCE_EXHAUSTED: Quota exceeded` | Exceeded read quota (50k reads/minute on free tier) | Upgrade to Blaze plan; optimize queries with tighter filters and limits |
+
+## Emulator Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `EADDRINUSE: address already in use :::8080` | Another process (or previous emulator) using port 8080 | Kill the process: `lsof -ti:8080 \| xargs kill`; or change port in `firebase.json` |
+| `Error: Could not start Firestore Emulator, port taken` | Same as above but reported by Firebase CLI | Stop other emulator instances; check for zombie Java processes |
+| Emulator data disappears between restarts | Emulator does not persist by default | Use `--export-on-exit=./emulator-data` and `--import=./emulator-data` flags |
+| Rules changes not reflected in emulator | Emulator loaded rules at startup | Restart emulator after rules changes; or use hot-reload (CLI v13+) |
+| `connect ECONNREFUSED 127.0.0.1:8080` | Emulator not running or wrong port | Start emulator: `firebase emulators:start --only firestore`; verify port matches code |
+
+## Data Migration Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Migration script re-processes already-migrated documents | No checkpoint mechanism; script restarted from beginning | Implement checkpoint pattern: write `_migrations/{id}` doc after each batch with `lastDocumentId` |
+| Documents have mixed old/new schema | Migration interrupted midway | Resume from checkpoint; run validation query to find documents missing the new field |
+| `INVALID_ARGUMENT: Value for argument "data" is not a valid Firestore document` | Transform function returned undefined or invalid type | Validate transform output before writing; skip documents that produce invalid results |
+| Migration too slow (hours for 100k docs) | Processing documents one at a time instead of in batches | Use batch writes (500 per commit); parallelize with multiple query cursors on sharded key |
+
+## Cost and Billing Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Unexpected high Firestore bill | Runaway query without `.limit()`; or real-time listener on large collection | Add `.limit()` to all queries; audit listeners; check Firebase Console > Usage |
+| `RESOURCE_EXHAUSTED` on free tier | Exceeded 50k reads/day or 20k writes/day (Spark plan) | Upgrade to Blaze plan; optimize query patterns; cache frequently read documents |
+| Reads cost more than expected | `get()` on a collection with 10,000 docs counts as 10,000 reads | Always use `.where()` and `.limit()` to narrow results; paginate large reads |
+| Deletes cost more than expected | Deleting a document with subcollections does not delete subcollections | Recursively delete subcollections first; use `firebase firestore:delete --recursive` for CLI deletion |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*