@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/_general/database-solutions/mysql-to-pg-migration.md

@@ -0,0 +1,195 @@
+---
+name: mysql-to-pg-migration
+category: database-solutions
+version: 1.0.0
+contributed: 2026-03-10
+contributor: research
+last_updated: 2026-03-10
+tags: [mysql, postgresql, migration, pgloader, schema-conversion]
+difficulty: hard
+---
+
+# MySQL to PostgreSQL Migration
+
+## Problem
+
+Migrating from MySQL to PostgreSQL is the most common enterprise database migration direction (validated by the $480K/year savings case study, 2026). Despite tooling like pgloader, 20% of translations require manual intervention — type mappings, stored procedure rewrites, and application code changes that tools miss.
+## Solution Pattern
+
+### Phase 1: Assessment
+
+Before any migration, audit the source MySQL database:
+
+```sql
+-- Count tables, views, procedures, triggers
+SELECT 'tables' AS type, COUNT(*) FROM information_schema.tables WHERE table_schema = 'mydb'
+UNION ALL
+SELECT 'views', COUNT(*) FROM information_schema.views WHERE table_schema = 'mydb'
+UNION ALL
+SELECT 'procedures', COUNT(*) FROM information_schema.routines WHERE routine_schema = 'mydb'
+UNION ALL
+SELECT 'triggers', COUNT(*) FROM information_schema.triggers WHERE trigger_schema = 'mydb';
+
+-- Find unsigned columns (require upsizing)
+SELECT table_name, column_name, column_type
+FROM information_schema.columns
+WHERE table_schema = 'mydb' AND column_type LIKE '%unsigned%';
+
+-- Find ENUM columns (require CREATE TYPE)
+SELECT table_name, column_name, column_type
+FROM information_schema.columns
+WHERE table_schema = 'mydb' AND data_type = 'enum';
+
+-- Find zero-date values (will become NULL)
+SELECT table_name, column_name
+FROM information_schema.columns
+WHERE table_schema = 'mydb' AND (data_type = 'datetime' OR data_type = 'timestamp');
+```
+
+### Phase 2: Schema Conversion
+
+#### Core Type Translations
+
+| MySQL | PostgreSQL | Notes |
+|---|---|---|
+| `INT AUTO_INCREMENT` | `SERIAL` or `GENERATED ALWAYS AS IDENTITY` | IDENTITY is SQL standard |
+| `BIGINT AUTO_INCREMENT` | `BIGSERIAL` | |
+| `TINYINT(1)` / `BOOL` | `BOOLEAN` | Validate no values > 1 |
+| `TINYINT` (other) | `SMALLINT` | |
+| `INT UNSIGNED` | `BIGINT` | Upsize for unsigned range |
+| `DOUBLE` | `DOUBLE PRECISION` | |
+| `DATETIME` | `TIMESTAMP` or `TIMESTAMPTZ` | Choose based on timezone needs |
+| `ENUM('a','b','c')` | `CREATE TYPE myenum AS ENUM('a','b','c')` | One type per unique enum set |
+| `` `backtick_quoted` `` | `"double_quoted"` | PG preserves case in quotes |
+| `JSON` | `JSONB` | Upgrade to binary for indexing |
+
+#### Syntax Translations (Application Code)
+
+| MySQL | PostgreSQL | Notes |
+|---|---|---|
+| `IFNULL(a, b)` | `COALESCE(a, b)` | COALESCE is SQL standard |
+| `IF(cond, a, b)` | `CASE WHEN cond THEN a ELSE b END` | |
+| `LIMIT k, n` | `LIMIT n OFFSET k` | Argument order reverses! |
+| `DATE_FORMAT(d, '%Y-%m')` | `TO_CHAR(d, 'YYYY-MM')` | Different format tokens |
+| `GROUP_CONCAT(col)` | `STRING_AGG(col, ',')` | PG requires explicit separator |
+| `CONCAT(a, b)` | `a \|\| b` | PG also supports CONCAT() |
+| `NOW()` | `NOW()` | Same |
+| `LOCATE(sub, str)` | `POSITION(sub IN str)` | |
+| `json_extract(col, '$.key')` | `col->>'key'` | Simpler syntax in PG |
+| `ON DUPLICATE KEY UPDATE` | `ON CONFLICT (col) DO UPDATE SET` | Different upsert syntax |
+| `VALUES(col)` (in upsert) | `EXCLUDED.col` | Reference to proposed row |
+| `INSERT IGNORE INTO` | `ON CONFLICT DO NOTHING` | |
+
+### Phase 3: Automated Migration with pgloader
+
+```lisp
+-- pgloader.conf
+LOAD DATABASE
+  FROM mysql://user:pass@localhost/mydb
+  INTO postgresql://user:pass@localhost/mydb_pg
+
+WITH
+  include drop,
+  create tables,
+  create indexes,
+  reset sequences,
+  workers = 4,
+  concurrency = 2
+
+-- Custom type overrides
+CAST
+  type tinyint when (= 1 precision) to boolean using tinyint-to-boolean,
+  type int when unsigned to bigint,
+  type year to integer,
+  type datetime to timestamptz
+
+-- Handle zero-dates
+BEFORE LOAD DO
+  $$ ALTER DATABASE mydb_pg SET datestyle TO 'ISO, MDY'; $$
+
+AFTER LOAD DO
+  $$ VACUUM ANALYZE; $$
+;
+```
+
+```bash
+# Run pgloader
+pgloader pgloader.conf
+
+# Verify
+psql -d mydb_pg -c "SELECT schemaname, tablename FROM pg_tables WHERE schemaname = 'public';"
+```
+
+### Phase 4: Application Code Changes
+
+1. **Connection driver:** `mysql2` → `pg` (or `postgres.js`)
+2. **Parameter placeholders:** `?` → `$1, $2, $3` (numbered)
+3. **Identifier quoting:** Backticks → double quotes (or remove)
+4. **Boolean values:** `1/0` → `true/false`
+5. **JSON access:** `JSON_EXTRACT(col, '$.key')` → `col->>'key'`
+6. **Date formatting:** `DATE_FORMAT(d, '%Y-%m-%d')` → `TO_CHAR(d, 'YYYY-MM-DD')`
+7. **String aggregation:** `GROUP_CONCAT(col SEPARATOR ',')` → `STRING_AGG(col::text, ',')`
+8. **UPSERT:** `ON DUPLICATE KEY UPDATE` → `ON CONFLICT ... DO UPDATE SET`
+9. **LIMIT syntax:** `LIMIT offset, count` → `LIMIT count OFFSET offset`
+10. **RETURNING:** Can now use `INSERT ... RETURNING *` natively (was emulated)
+
+### Phase 5: Post-Migration Validation
+
+```bash
+# Compare table counts
+mysql -u user -p mydb -e "SELECT COUNT(*) FROM users;"
+psql -d mydb_pg -c "SELECT COUNT(*) FROM users;"
+
+# Compare row counts for all tables
+psql -d mydb_pg -c "
+  SELECT schemaname, relname, n_live_tup
+  FROM pg_stat_user_tables
+  ORDER BY n_live_tup DESC;
+"
+
+# Run VACUUM ANALYZE on all tables
+psql -d mydb_pg -c "VACUUM ANALYZE;"
+
+# Verify sequences are correct
+psql -d mydb_pg -c "
+  SELECT sequencename, last_value
+  FROM pg_sequences
+  WHERE schemaname = 'public';
+"
+```
+
+## Common Breakage Points
+
+1. **Timezone drift:** MySQL DATETIME has no timezone; PG TIMESTAMPTZ is UTC-aware. Audit trail timestamps may shift.
+2. **Zero-dates:** MySQL `0000-00-00` → NULL in PG. Application code expecting these dates will break.
+3. **Case sensitivity:** MySQL table names are case-insensitive on Windows; PG is always case-sensitive. Verify all table references.
+4. **ENUM ordering:** MySQL ENUMs have implicit ordering; PG ENUMs have explicit ordering. Sorts may change.
+5. **Implicit type casts:** MySQL silently casts strings to numbers in comparisons; PG raises errors.
+6. **GROUP BY strictness:** PG requires all non-aggregated columns in GROUP BY; MySQL's `ONLY_FULL_GROUP_BY` is optional.
+
+## When to Use
+
+- Migrating from MySQL to PostgreSQL (any direction)
+- Planning a database migration for `/fire-resurrect --migrate`
+- Evaluating migration complexity before committing
+
+## When NOT to Use
+
+- MySQL-to-MySQL upgrades (different problem)
+- Migrating to/from NoSQL
+- Small SQLite databases (use sqlite-to-pg-migration instead)
+
+## Related Skills
+
+- [sql-dialect-compatibility-matrix](sql-dialect-compatibility-matrix.md)
+- [data-type-mapping-reference](data-type-mapping-reference.md)
+- [pg-to-mysql-schema-migration-methodology](pg-to-mysql-schema-migration-methodology.md) — reverse direction
+- [sqlite-to-pg-migration](sqlite-to-pg-migration.md)
+
+## References
+
+- "The MySQL-to-Postgres Migration That Saved $480K/Year" (Medium, 2026)
+- "I Migrated 400M Rows — Here's What Actually Broke" (Medium, 2026)
+- pgloader documentation (pgloader.readthedocs.io)
+- AI2sql MySQL-to-PostgreSQL conversion guide (2026)
+- Percona pgloader guide (percona.com/blog)

package/skills-library/_general/database-solutions/orm-schema-portability.md

@@ -0,0 +1,193 @@
+---
+name: orm-schema-portability
+category: database-solutions
+version: 1.0.0
+contributed: 2026-03-10
+contributor: research
+last_updated: 2026-03-10
+tags: [orm, prisma, knex, drizzle, typeorm, sequelize, django, portability, migration]
+difficulty: medium
+---
+
+# ORM Schema Portability
+
+## Problem
+
+Developers assume ORMs abstract away database differences. They don't. Every ORM leaks dialect-specific behavior for arrays, enums, JSON querying, full-text search, and migrations. Switching databases after building on ORM-specific features requires significant rework that isn't obvious until migration day.
+## ORM Portability Comparison
+
+| Dimension | Prisma | Knex.js | Drizzle | TypeORM | Sequelize | Django |
+|---|---|---|---|---|---|---|
+| **Schema portability** | Single provider | N/A (query builder) | Separate per dialect | Mostly portable | Mostly portable | Fully portable |
+| **Migration portability** | None (SQL files) | Partial (schema builder) | None (dialect SQL) | Partial (auto-gen) | Low | High (Python) |
+| **Array support** | PG only | N/A | Dialect-specific | PG only | PG only | PG only |
+| **JSON support** | PG, MySQL (recent SQLite) | N/A | Dialect-specific | All (simple-json) | PG, MySQL, SQLite | All (since 3.1) |
+| **Enum support** | PG, MySQL | N/A | Dialect-specific | PG, MySQL | PG, MySQL, SQLite | All (CharField) |
+| **Raw SQL portability** | None | None | Param only | None | None | Partial |
+| **Switching effort** | **High** | **Medium** | **Very High** | **Medium** | **Medium** | **Low** |
+| **Best for multi-DB** | No | Yes | No | Moderate | Moderate | **Yes** |
+
+## Per-ORM Details
+
+### Prisma — Single Provider, No Switching
+
+**What it abstracts:** CRUD, relations, connection pooling, type generation.
+
+**What breaks when switching:**
+- Schema is inherently single-provider (`provider = "postgresql"` in schema.prisma)
+- No `provider = "universal"` — community request since 2020, still unresolved
+- Enum, JSON, scalar list support varies by provider
+- Migrations generate provider-specific SQL — not reusable across databases
+- `$queryRaw` uses `$1` for PG, `?` for MySQL — dialect-dependent
+
+**Portable pattern:** Maintain separate schema files per provider. Share application code.
+
+### Knex.js — Best JS/TS Option for Portability
+
+**What it abstracts:** Query building, schema builder DDL, connection pooling, parameter binding.
+
+**What breaks when switching:**
+- SQLite's limited ALTER TABLE (Knex emulates with temp table + copy)
+- `RETURNING` is PG/SQLite only
+- `knex.raw()` completely kills portability
+- Result shape differs by dialect (`{ rows: [...] }` vs `[[...], fields]`)
+- LIMIT/OFFSET string values accepted by PG, rejected by MySQL
+
+**Portable pattern:** Use schema builder API exclusively. Avoid `knex.raw()`. Coerce LIMIT/OFFSET to integers.
+
+**MINISTRY-LMS approach:** Knex migrations with conditional DDL:
+```javascript
+const isPostgres = knex.client.config.client === 'pg';
+if (isPostgres) {
+  table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'));
+  table.jsonb('settings');
+} else {
+  table.uuid('id').primary();
+  table.json('settings');
+}
+```
+
+### Drizzle — Intentionally Non-Portable
+
+**What it abstracts:** Type-safe query building, relational queries, driver adapters.
+
+**What breaks when switching:**
+- **Schema definitions are NOT portable.** Separate imports: `pgTable`, `mysqlTable`, `sqliteTable`
+- Column types differ per dialect (e.g., `serial` in PG vs `int` + `autoIncrement` in MySQL)
+- Migrations generate dialect-specific SQL
+
+**Why it's designed this way:** Drizzle is "SQL with types" — it deliberately exposes dialect differences for maximum control and type safety. The trade-off is zero cross-dialect portability.
+
+**Portable pattern:** Share column definitions via spread syntax; rewrite table definitions per dialect.
+
+### TypeORM — Moderate Portability
+
+**What it abstracts:** Entity decorators map to appropriate types, repository pattern, QueryBuilder.
+
+**What breaks when switching:**
+- `array: true` is PG/CockroachDB only
+- `jsonb` is PG only; MySQL uses `json`; SQLite stores as text
+- `unsigned` modifier is MySQL only
+- Enum+Array combination is problematic on PG
+- `@CreateDateColumn` precision differs
+
+**Portable pattern:** Use `simple-array`, `simple-json`, `simple-enum` types (stored as strings). Avoid native types.
+
+### Sequelize — Moderate Portability
+
+**What it abstracts:** Model definition, query interface, associations, transactions.
+
+**What breaks when switching:**
+- `DataTypes.ARRAY` is PG only
+- `DataTypes.JSONB` is PG only
+- `CITEXT` is PG/SQLite only
+- ENUM storage differs (PG: CREATE TYPE, MySQL: inline, SQLite: CHECK)
+- v7 moved dialects to separate packages (breaking change from v6)
+
+**Portable pattern:** Stick to `DataTypes.STRING`, `INTEGER`, `BOOLEAN`, `DATE`, `JSON` (not JSONB), `TEXT`.
+
+### Django — Most Portable
+
+**What it abstracts:** Model definitions, QuerySet API, migration framework, admin interface.
+
+**What breaks when switching:**
+- `ArrayField` is PG only (`django.contrib.postgres`)
+- `HStoreField` is PG only
+- Full-text search (`SearchVector`, `SearchRank`) is PG only
+- Range fields are PG only
+
+**Portable pattern:** Avoid `django.contrib.postgres`. Use `JSONField` (cross-DB since 3.1). Use `CharField(choices=...)` instead of custom ENUM types.
+
+**Why Django wins:** Python-based migrations (not raw SQL) are inherently backend-agnostic. `%s` parameter placeholders are translated internally by Django.
+
+## The Safest Portable Subset
+
+These ORM types work identically across PG, MySQL, SQLite with zero translation in ANY ORM:
+
+```
+string / VARCHAR(n)     — where n ≤ 255
+integer / INT           — signed 32-bit
+float / DOUBLE          — 8-byte floating point
+boolean / BOOLEAN       — true/false (ORM handles TINYINT mapping)
+text / TEXT             — unlimited string
+timestamp / DATETIME    — ORM handles dialect differences
+uuid-as-string / CHAR(36) — generate in app code
+json-as-text / JSON     — basic JSON (no JSONB indexing)
+```
+
+**Avoid for portability:** Arrays, JSONB, native ENUM, range types, full-text search, geometric types, HSTORE.
+
+## Decision Matrix: Choosing an ORM for Multi-DB
+
+| If you need... | Use... | Why |
+|---|---|---|
+| Maximum portability (Python) | **Django** | Python migrations, internal param translation |
+| Maximum portability (JS/TS) | **Knex.js** | Query builder, not ORM — minimal abstraction leak |
+| Type safety over portability | **Drizzle** | Explicit dialect awareness, best TypeScript DX |
+| Quick prototyping | **Prisma** | Best DX, but locked to one provider |
+| Legacy enterprise | **TypeORM** or **Sequelize** | Broad dialect support, mature ecosystem |
+
+## Migration State Continuity
+
+When rebuilding an app (e.g., `/fire-resurrect`), the ORM's migration tracking table lives IN the database:
+
+| ORM | Migration Table | What It Tracks |
+|---|---|---|
+| Prisma | `_prisma_migrations` | Applied migration names + timestamps |
+| Knex | `knex_migrations` | Batch number + migration name |
+| Sequelize | `SequelizeMeta` | Migration filenames |
+| TypeORM | `migrations` | Timestamp + name |
+| Django | `django_migrations` | App + name + applied timestamp |
+
+**Key insight:** If you point a new project at an existing database with the same migration files, the ORM knows which migrations have already run. No re-creation, no data loss.
+
+**For "reuse" strategy in fire-resurrect:** Copy migration files to new project → point at existing DB → `migrate:latest` runs only NEW migrations.
+
+## When to Use
+
+- Choosing an ORM for a new multi-database project
+- Auditing existing ORM schema for portability issues before migration
+- Planning the VISION phase of `/fire-resurrect` with `--migrate`
+- Understanding why a database switch broke application code
+
+## When NOT to Use
+
+- Single-database projects with no migration plans
+- Raw SQL projects (use sql-dialect-compatibility-matrix instead)
+- NoSQL ORMs (Mongoose, etc.)
+
+## Related Skills
+
+- [sql-dialect-compatibility-matrix](sql-dialect-compatibility-matrix.md)
+- [data-type-mapping-reference](data-type-mapping-reference.md)
+- [pg-to-mysql-schema-migration-methodology](pg-to-mysql-schema-migration-methodology.md)
+
+## References
+
+- Prisma multiple database support limitations (issue #1487)
+- Bytebase — "Drizzle vs Prisma" (2026)
+- TheDataGuy — "Node.js ORMs in 2025" (Dec 2025)
+- MINISTRY-LMS Knex migration patterns (production-proven, 2026)
+- Django ORM comparison (Paolo Melchiorre, 2025)
+- Drizzle ORM schema declaration docs
+- Sequelize v7 dialect-specific documentation

package/skills-library/_general/database-solutions/persistent-analysis-storage.md

@@ -0,0 +1,207 @@
+---
+name: persistent-analysis-storage
+category: database-solutions
+version: 1.0.0
+contributed: 2026-03-01
+contributor: scribe-bible
+last_updated: 2026-03-01
+contributors:
+  - scribe-bible
+tags: [prisma, postgresql, persistence, favorites, sharing, nanoid, cursor-pagination, dual-storage]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Persistent Analysis Storage
+
+## Problem
+
+AI-powered analysis features (deep research, recursive reasoning, multi-step pipelines) produce expensive results that take 30-120+ seconds and significant API cost. Users need to:
+
+1. **Save results permanently** to their account (not just browser localStorage)
+2. **Favorite** important analyses for quick access
+3. **Share publicly** via short links (without requiring recipient login)
+4. **Browse history** with filtering and pagination
+5. **Maintain anonymous fallback** — localStorage history works without login
+
+Without DB persistence, results vanish on browser clear. Without dual-storage, unauthenticated users get no history at all.
+
+## Solution Pattern
+
+Implement a **dual-storage architecture** with localStorage as the anonymous/immediate layer and PostgreSQL (via Prisma) as the authenticated persistent layer. Each layer serves a different purpose:
+
+- **localStorage**: Instant, no-auth, limited to ~50 items, browser-scoped
+- **Database**: Permanent, auth-required, unlimited, supports sharing/favorites
+
+The key insight is these layers are **complementary, not competing** — localStorage provides instant gratification while DB provides permanence. The UI presents both via a tabbed sidebar.
+
+## Code Example
+
+### Prisma Model
+
+```prisma
+model RlmAnalysis {
+  id              String   @id @default(uuid())
+  userId          String
+  query           String
+  analysisType    String
+  result          String   @db.Text
+  trajectoryId    String
+  trajectory      String?  @db.Text    // JSON stringified steps
+  tokenUsage      String?              // JSON stringified usage
+  durationSeconds Float
+  translation     String   @default("kjv")
+  isFavorite      Boolean  @default(false)
+  isPublic        Boolean  @default(false)
+  shareSlug       String?  @unique     // nanoid(8) generated on first share
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+  user            User     @relation(fields: [userId], references: [id])
+
+  @@index([userId, createdAt])
+  @@index([userId, isFavorite])
+  @@index([analysisType])
+}
+```
+
+### Storage Service (CRUD + Sharing)
+
+```typescript
+// Toggle public sharing — generates a short slug on first share
+export async function toggleShare(id: string, userId: string) {
+  const analysis = await prisma.analysis.findUnique({ where: { id } });
+  if (!analysis || analysis.userId !== userId) return null;
+
+  const isPublic = !analysis.isPublic;
+  const shareSlug = isPublic && !analysis.shareSlug ? nanoid(8) : analysis.shareSlug;
+
+  return prisma.analysis.update({
+    where: { id },
+    data: { isPublic, shareSlug },
+  });
+}
+
+// Cursor-based pagination (better than offset for large sets)
+export async function listAnalyses(options: ListOptions) {
+  const { userId, type, favoritesOnly, limit = 20, cursor } = options;
+  const where: any = { userId };
+  if (type) where.analysisType = type;
+  if (favoritesOnly) where.isFavorite = true;
+
+  const analyses = await prisma.analysis.findMany({
+    where,
+    orderBy: { createdAt: 'desc' },
+    take: limit + 1,  // Fetch one extra to detect hasMore
+    ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+    select: { id: true, query: true, analysisType: true, /* ... */ },
+  });
+
+  const hasMore = analyses.length > limit;
+  const items = hasMore ? analyses.slice(0, limit) : analyses;
+  return { items, nextCursor: hasMore ? items[items.length - 1].id : null, hasMore };
+}
+```
+
+### API Endpoints (7 routes)
+
+```typescript
+// Auth-required endpoints
+router.post('/saved', authenticateToken, saveHandler);        // Save analysis
+router.get('/saved', authenticateToken, listHandler);         // List with filters
+router.get('/saved/:id', authenticateToken, getHandler);      // Get single
+router.delete('/saved/:id', authenticateToken, deleteHandler);// Delete
+router.post('/saved/:id/favorite', authenticateToken, favHandler);  // Toggle favorite
+router.post('/saved/:id/share', authenticateToken, shareHandler);   // Toggle share
+
+// Public endpoint (no auth)
+router.get('/shared/:slug', sharedHandler);  // View shared analysis
+```
+
+### Frontend Hook (Dual Storage)
+
+```typescript
+// localStorage for anonymous history
+const [history, setHistory] = useState<HistoryItem[]>(loadHistory);
+
+// DB-backed for authenticated persistence
+const saveToDb = useCallback(async (result: AnalysisResult) => {
+  const res = await fetch(`${API_BASE}/api/saved`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...getAuthHeaders() },
+    body: JSON.stringify(result),
+  });
+  if (!res.ok) return null;
+  // Mark in local history as saved (cross-reference)
+  setHistory(prev => prev.map(h =>
+    h.trajectoryId === result.trajectoryId ? { ...h, savedToDb: true } : h
+  ));
+  return (await res.json()).data;
+}, []);
+```
+
+### Tabbed Sidebar UI
+
+```tsx
+{/* Tab buttons */}
+<button onClick={() => setSidebarTab('recent')}
+  className={sidebarTab === 'recent' ? 'active' : ''}>
+  Recent ({history.length})
+</button>
+<button onClick={() => { setSidebarTab('saved'); loadSavedAnalyses(); }}
+  className={sidebarTab === 'saved' ? 'active' : ''}>
+  Saved ({savedAnalyses.length})
+</button>
+
+{/* Tab content */}
+{sidebarTab === 'recent' ? (
+  // localStorage items with "saved" badge
+  history.map(item => <HistoryItem key={item.id} item={item} />)
+) : (
+  // DB-backed items with favorite/share/delete actions
+  savedAnalyses.map(item => <SavedItem key={item.id} item={item} />)
+)}
+```
+
+## Implementation Steps
+
+1. Add Prisma model with indexes on userId+createdAt, userId+isFavorite, and unique shareSlug
+2. Create storage service with CRUD + toggleFavorite + toggleShare (nanoid for slugs)
+3. Add 7 API routes (6 auth-required + 1 public shared endpoint)
+4. Extend frontend hook with DB persistence methods alongside existing localStorage
+5. Add tabbed sidebar UI (Recent/Saved) with action buttons on saved items
+6. Cross-reference: mark localStorage items as "savedToDb" when saved to DB
+
+## When to Use
+
+- AI analysis features that produce expensive, non-reproducible results
+- Any feature where users want to bookmark/favorite results for later
+- When public sharing via short links is needed (portfolios, collaboration)
+- Dual anonymous + authenticated experience (localStorage fallback)
+- Large result sets needing cursor-based pagination
+
+## When NOT to Use
+
+- Simple caching (use AI_RESPONSE_DATABASE_CACHING skill instead)
+- Ephemeral data that doesn't need user ownership (use Redis/in-memory)
+- When results are cheap to recompute (no persistence needed)
+- Single-user apps with no sharing requirement (localStorage may suffice)
+
+## Common Mistakes
+
+- Using offset pagination instead of cursor-based (degrades at scale)
+- Generating share slugs eagerly instead of on first share toggle (wasted IDs)
+- Forgetting to handle the "not found OR not authorized" case (leaks existence info)
+- Not providing localStorage fallback for unauthenticated users
+- Storing large JSON blobs (trajectory, tokenUsage) as regular String instead of @db.Text
+
+## Related Skills
+
+- [AI_RESPONSE_DATABASE_CACHING](AI_RESPONSE_DATABASE_CACHING.md) - Cache-first pattern for avoiding recomputation
+- cursor-pagination - Efficient large dataset browsing pattern
+
+## References
+
+- nanoid: https://github.com/ai/nanoid — short unique ID generation
+- Prisma cursor pagination: https://www.prisma.io/docs/concepts/components/prisma-client/pagination#cursor-based-pagination
+- Contributed from: scribe-bible (Phase 2 — Persistent Analysis Storage)