@cubis/foundry 0.3.31 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/redis/references/operations.md

@@ -0,0 +1,144 @@
+# Redis — Operations, Memory, and Latency
+
+## Memory management
+
+Redis stores all data in memory. Running out of memory is the #1 operational failure mode.
+
+### Monitor memory
+
+```redis
+INFO memory
+# Key fields:
+# used_memory_human        — actual data memory
+# used_memory_rss_human    — RSS from OS (includes fragmentation)
+# mem_fragmentation_ratio  — rss / used. >1.5 = high fragmentation
+# maxmemory                — configured limit (0 = unlimited — dangerous)
+# maxmemory_human          — human readable limit
+```
+
+Always set `maxmemory`:
+```redis
+CONFIG SET maxmemory 2gb
+```
+
+### Eviction policies
+
+When `maxmemory` is reached, Redis uses the configured eviction policy:
+
+| Policy | Behavior |
+| --- | --- |
+| `noeviction` | Returns error on writes — safe for primary data stores |
+| `allkeys-lru` | Evicts least recently used keys — good for caches |
+| `volatile-lru` | Evicts LRU keys that have a TTL set |
+| `allkeys-lfu` | Evicts least frequently used — better than LRU for skewed access |
+| `volatile-ttl` | Evicts keys with shortest remaining TTL first |
+| `allkeys-random` | Random eviction — rarely useful |
+
+For pure caches: `allkeys-lru` or `allkeys-lfu`.
+For mixed primary + cache data: `volatile-lru` (only evicts keys with TTL).
+
+```redis
+CONFIG SET maxmemory-policy allkeys-lru
+```
+
+### Handle fragmentation
+
+When `mem_fragmentation_ratio > 1.5`, trigger active defragmentation (Redis 4.0+):
+```redis
+CONFIG SET activedefrag yes
+CONFIG SET active-defrag-ignore-bytes 100mb
+CONFIG SET active-defrag-threshold-lower 10
+```
+
+## Latency diagnostics
+
+Redis should respond in microseconds. If you're seeing millisecond latency, investigate:
+
+```redis
+# Check for slow commands (logged automatically)
+SLOWLOG GET 10
+SLOWLOG LEN
+SLOWLOG RESET
+
+# Default slow threshold is 10ms — lower for tighter monitoring:
+CONFIG SET slowlog-log-slower-than 1000   # microseconds = 1ms
+
+# Latency history (built-in latency monitoring)
+LATENCY LATEST
+LATENCY HISTORY event_name
+LATENCY RESET
+```
+
+### Common latency causes
+
+| Cause | Symptom | Fix |
+| --- | --- | --- |
+| `KEYS *` in production | Periodic spikes | Replace with `SCAN` |
+| Large key values (MB-range) | Slow reads/writes | Chunk data or use a different store |
+| AOF fsync on every write | Consistent high latency | Switch to `fsync everysec` |
+| Memory pressure / eviction | Increasing latency trend | Add memory or tune eviction |
+| Blocking commands (`BLPOP`, `BRPOP`) | Thread holds connection | Use timeouts |
+| Fork for RDB/AOF rewrite | Latency spike every N minutes | Schedule rewrites in off-peak windows |
+
+## Persistence configuration
+
+Choose based on durability requirements:
+
+| Config | Durability | Performance |
+| --- | --- | --- |
+| No persistence | None (cache only) | Fastest |
+| RDB snapshots only | Up to snapshot interval | Fast |
+| AOF `everysec` | Up to ~1s of data loss | Good |
+| AOF `always` | No data loss | Slowest — 1 fsync per write |
+| RDB + AOF | Best of both | Moderate |
+
+For caches where losing data on restart is acceptable, disable persistence:
+```redis
+CONFIG SET save ""         # disable RDB
+CONFIG SET appendonly no   # disable AOF
+```
+
+## Monitor key space
+
+```redis
+# Count keys per database
+INFO keyspace
+
+# Sample key patterns (does not block)
+redis-cli --scan --pattern 'user:*' | head -20
+
+# Key size distribution — pick a sample
+redis-cli --bigkeys       # finds largest keys by type
+```
+
+## Connection limits
+
+```redis
+INFO clients
+# connected_clients       — current connections
+# maxclients              — configured limit (default 10000)
+```
+
+Redis is single-threaded for command execution. High connection counts add overhead via:
+- Select/poll overhead on the socket set.
+- Memory per connection (~20KB).
+
+Use a connection pool in your application. Most Redis clients (ioredis, redis-py) pool by default. Check pool size matches your concurrency model.
+
+## Key expiry and eviction monitoring
+
+```redis
+INFO stats
+# expired_keys     — keys removed by TTL expiry since start
+# evicted_keys     — keys removed by maxmemory policy
+# keyspace_hits    — cache hit count
+# keyspace_misses  — cache miss count
+
+# Hit rate = hits / (hits + misses). Below 80% suggests key design issues.
+```
+
+## Sources
+- Memory optimization: https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/memory-optimization/
+- Latency optimization: https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/latency/
+- Persistence options: https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/
+- SLOWLOG: https://redis.io/docs/latest/commands/slowlog/

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/sqlite/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: sqlite
+description: SQLite local/edge data strategy, schema/index design, query planning, and WAL tuning.
+---
+
+# SQLite
+
+## Optimization workflow
+
+1. Inspect plan with `EXPLAIN QUERY PLAN`.
+2. Add multicolumn or covering indexes for hot read paths.
+3. Use keyset-style pagination for large datasets.
+4. Tune WAL/checkpoint behavior for write-heavy workloads.
+5. Re-check plans after schema/data-distribution changes.
+
+## Indexing techniques
+
+- Composite indexes for combined filter+sort paths.
+- Covering indexes when read latency is critical.
+- Keep indexes minimal on write-heavy local stores.
+
+## Pagination techniques
+
+- Offset is acceptable for small tables and shallow lists.
+- For large traversals, use deterministic keyset pagination.
+
+## Operational guardrails
+
+- Batch writes in explicit transactions.
+- Use WAL mode for mixed read/write concurrency.
+- Validate checkpoint strategy for mobile/edge IO limits.
+
+## References
+
+- `references/local-first.md`
+- `references/performance.md`

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/sqlite/references/local-first.md

@@ -0,0 +1,95 @@
+# SQLite — Local-First Design
+
+## When SQLite is the right fit
+
+SQLite is the right choice when:
+- Each user has their own private data (mobile app, desktop app, browser extension, edge function).
+- The application needs to work offline with local durability.
+- Data sync is done at the application layer, not the database layer.
+- Simplicity and zero-configuration matter.
+
+SQLite is **not** the right fit for:
+- High-concurrency write workloads with multiple simultaneous writers.
+- Data shared across multiple users in real-time (use Postgres or MySQL instead).
+- Analytics on large datasets (use ClickHouse or DuckDB instead).
+
+## Journal modes — choose WAL for mobile/desktop
+
+The default Rollback Journal blocks all reads during a write. Switch to WAL (Write-Ahead Log) for concurrent reads:
+
+```sql
+PRAGMA journal_mode = WAL;
+-- Persist across connections (set once after DB creation)
+```
+
+WAL mode allows:
+- Multiple simultaneous readers while a write is in progress.
+- Reads don't block writes; writes don't block reads.
+- Slightly better write performance for sequential inserts.
+
+Set `PRAGMA synchronous = NORMAL` with WAL (safe default, faster than `FULL`):
+```sql
+PRAGMA synchronous = NORMAL;
+```
+
+## Migration patterns
+
+Migrations must be deterministic and reversible. Use a migrations table to track applied versions:
+
+```sql
+CREATE TABLE IF NOT EXISTS _migrations (
+  id INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+```
+
+Migration rules:
+- **Never modify an applied migration** — create a new one instead.
+- **Always test on real device storage** — SD cards, old iPhones, and constrained flash behave differently than dev machines.
+- **Include a down migration** (rollback SQL) alongside every up migration.
+- Run migrations inside a transaction so partial failure is safe:
+  ```sql
+  BEGIN;
+  -- migration SQL here
+  INSERT INTO _migrations (id, name) VALUES (3, 'add_notes_column');
+  COMMIT;
+  ```
+
+## Multi-device sync and conflict handling
+
+SQLite has no built-in sync. Design conflict handling explicitly before writing any app code.
+
+Common strategies:
+- **Last-write-wins (LWW)**: each row has `updated_at`. On sync, higher timestamp wins. Simple but loses concurrent edits.
+- **CRDTs**: use conflict-free replicated data types for counters, sets, and ordered lists. Complex but correct.
+- **Event sourcing**: store immutable event log, derive state. Sync events instead of rows.
+- **Vector clocks**: each device has a logical clock; merge based on causal ordering.
+
+Always include a `sync_id` (UUID, globally unique) and `device_id` on every synced row. Never rely on local SQLite `ROWID` or autoincrement as a sync key.
+
+## Offline-first checklist
+
+- [ ] WAL mode enabled on database open.
+- [ ] All writes go through a local queue that syncs when connectivity is available.
+- [ ] Conflict resolution strategy defined before writing sync logic.
+- [ ] Migrations run before any app reads/writes.
+- [ ] Migration history table exists.
+- [ ] UI shows sync status (pending, syncing, error).
+- [ ] Sync tested under: airplane mode, partial connectivity, app killed mid-sync.
+
+## Appropriate use cases
+
+| Use | Verdict |
+| --- | --- |
+| Mobile app local data | ✅ Excellent |
+| Desktop app settings and cache | ✅ Excellent |
+| Embedded IoT / edge data | ✅ Excellent |
+| Read-heavy web server cache | ✅ Good (read-only or low-write) |
+| Multi-user web app backend | ❌ Use Postgres |
+| High-concurrency writes | ❌ Use Postgres or MySQL |
+
+## Sources
+- SQLite appropriate uses: https://sqlite.org/whentouse.html
+- Atomic commit behavior: https://sqlite.org/atomiccommit.html
+- WAL mode: https://sqlite.org/wal.html

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/sqlite/references/performance.md

@@ -0,0 +1,105 @@
+# SQLite — Performance Techniques
+
+## EXPLAIN QUERY PLAN
+
+Always check the planner before optimizing.
+
+```sql
+EXPLAIN QUERY PLAN
+SELECT * FROM orders WHERE user_id = 1 ORDER BY created_at DESC LIMIT 20;
+```
+
+Key output to read:
+- `SCAN orders` = full table scan — missing or unused index.
+- `SEARCH orders USING INDEX idx_orders_user (user_id=?)` = index seek — good.
+- `USE TEMP B-TREE FOR ORDER BY` = sort can't use the index — add a covering index with the sort column.
+
+## Index design
+
+SQLite uses B-tree indexes. Same leftmost-prefix rules as other SQL databases.
+
+```sql
+-- Equality first, sort last
+CREATE INDEX idx_orders_user_created ON orders (user_id, created_at DESC);
+
+-- Partial index for hot filtered subsets
+CREATE INDEX idx_orders_pending ON orders (user_id, created_at)
+WHERE status = 'pending';
+
+-- Covering index: include projected columns to avoid table fetch
+CREATE INDEX idx_orders_covering ON orders (user_id, status)
+-- SQLite doesn't have INCLUDE, so list all needed columns in the key
+```
+
+SQLite does not support `INCLUDE` columns — put all needed columns in the key if you want index-only reads.
+
+## Write performance — batch in transactions
+
+Every `INSERT`/`UPDATE`/`DELETE` outside a transaction is its own `fsync`. For bulk operations this is catastrophically slow.
+
+```sql
+-- BAD: 1000 individual fsyncs
+INSERT INTO logs VALUES (...);
+INSERT INTO logs VALUES (...);
+-- × 1000
+
+-- GOOD: one fsync
+BEGIN;
+INSERT INTO logs VALUES (...);
+INSERT INTO logs VALUES (...);
+-- × 1000
+COMMIT;
+```
+
+Rule of thumb: batch 100–10,000 rows per transaction. Benchmark for your hardware.
+
+## WAL and checkpoint tuning
+
+With WAL mode (see local-first.md), the WAL file grows until a checkpoint writes it back to the main DB file.
+
+```sql
+PRAGMA wal_autocheckpoint = 1000;   -- checkpoint after 1000 pages (default)
+-- Lower = more frequent checkpoints (less WAL growth, slightly more I/O)
+-- Higher = less frequent (better write throughput, larger WAL file)
+```
+
+Manual checkpoint before a backup:
+```sql
+PRAGMA wal_checkpoint(TRUNCATE);   -- flush WAL and truncate the file
+```
+
+## Memory and cache tuning
+
+```sql
+PRAGMA cache_size = -32000;    -- 32 MB page cache (negative = KB, default = 2MB)
+PRAGMA mmap_size = 268435456;  -- 256 MB memory-mapped I/O (faster reads on large DBs)
+PRAGMA temp_store = MEMORY;    -- keep temp tables in RAM instead of disk
+```
+
+Apply these after every `OPEN` — they are not persisted.
+
+## Seek pagination
+
+```sql
+-- BAD: OFFSET scans and discards N rows
+SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 10000;
+
+-- GOOD: seek on last seen id
+SELECT * FROM orders WHERE id > :last_seen_id ORDER BY id LIMIT 20;
+```
+
+## Connection management (multi-threaded apps)
+
+SQLite supports one writer at a time. For multi-threaded apps:
+- Use a single write connection with serialized writes.
+- Use a read connection pool (WAL mode allows concurrent readers).
+- Set `PRAGMA busy_timeout = 5000` to wait instead of failing immediately on a locked DB:
+  ```sql
+  PRAGMA busy_timeout = 5000;   -- wait up to 5s before returning SQLITE_BUSY
+  ```
+
+## Sources
+- EXPLAIN QUERY PLAN: https://sqlite.org/eqp.html
+- Query planner: https://sqlite.org/queryplanner.html
+- WAL mode: https://sqlite.org/wal.html
+- PRAGMA reference: https://sqlite.org/pragma.html

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/supabase/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: supabase
+description: Supabase/Postgres patterns for RLS, indexing, query optimization, pooling, and safe migrations.
+---
+
+# Supabase
+
+## Optimization workflow
+
+1. Confirm RLS policy shape and index policy predicates.
+2. Analyze query plans and use index advisor workflow.
+3. Choose proper connection mode (direct/session/transaction pooler).
+4. Use keyset pagination for heavy list endpoints.
+5. Include migration/rollback with version-awareness (managed vs self-hosted differences).
+
+## Indexing and RLS techniques
+
+- Index columns referenced by RLS policies.
+- Index join/filter columns used by API queries.
+- Remove redundant indexes that inflate write cost.
+
+## Pagination techniques
+
+- Prefer keyset pagination on stable, indexed sort columns.
+- Avoid blind offset scans on large tables.
+
+## Operational guardrails
+
+- Validate Supavisor mode based on runtime behavior.
+- Confirm compatibility when moving between managed and self-hosted environments.
+
+## References
+
+- `references/rls-auth.md`
+- `references/performance-operations.md`

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/supabase/references/performance-operations.md

@@ -0,0 +1,95 @@
+# Supabase — Query Performance and Connection Operations
+
+## Query optimization workflow
+
+1. Identify slow queries via Supabase Dashboard → Database → Query Performance (uses `pg_stat_statements`).
+2. Run `EXPLAIN (ANALYZE, BUFFERS)` on the slow query to read the actual plan.
+3. Check for: `Seq Scan` on large tables, `Sort` without index, high `Rows Removed by Filter` ratio.
+4. Add targeted index and re-test.
+
+```sql
+-- From the SQL editor in Supabase Dashboard
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
+SELECT * FROM orders WHERE user_id = 'abc' ORDER BY created_at DESC LIMIT 20;
+```
+
+## Database Advisors
+
+Supabase runs automated advisors that flag common issues. Check Dashboard → Database → Advisors for:
+- **Unused indexes**: indexes with zero scans — drop them.
+- **Unindexed foreign keys**: FKs without an index cause full scans on joins and cascades.
+- **Seq scans on large tables**: tables being full-scanned when an index would help.
+- **Bloated tables**: high dead tuple ratio — may need `VACUUM`.
+
+```sql
+-- Manual unused index check
+SELECT schemaname, relname, indexrelname, idx_scan
+FROM pg_stat_user_indexes
+WHERE idx_scan = 0 AND schemaname = 'public'
+ORDER BY relname;
+```
+
+## Connection modes and when to use each
+
+Supabase provides three connection methods:
+
+| Mode | How | Use for |
+| --- | --- | --- |
+| **Direct** | `postgresql://...` port 5432 | Long-lived connections (background jobs, migrations) |
+| **Transaction pooler** (PgBouncer) | Port 6543 | Serverless functions, edge functions, short-lived requests |
+| **Session pooler** | Port 5432 alt | When you need session-level features (prepared statements, `SET`) |
+
+**Serverless / Edge Functions**: always use the transaction pooler (6543). Direct connections from serverless cold starts exhaust Postgres connection limits fast.
+
+```ts
+// Supabase JS — uses transaction pooler automatically when using the client library
+const supabase = createClient(url, anonKey);
+
+// Direct connection for migrations / background jobs (Prisma, Drizzle, etc.)
+DATABASE_URL=postgresql://user:pass@db.xxx.supabase.co:5432/postgres
+// Transaction pooler for Prisma in serverless
+DATABASE_URL=postgresql://user:pass@db.xxx.supabase.co:6543/postgres?pgbouncer=true
+```
+
+## Prepared statements and pooling
+
+PgBouncer in transaction mode does **not** support prepared statements — they are per-session. If your ORM uses prepared statements (Prisma does by default):
+
+```
+# Prisma — disable prepared statements when using transaction pooler
+DATABASE_URL="...?pgbouncer=true&connection_limit=1"
+# Or in schema.prisma:
+datasource db {
+  url = env("DATABASE_URL")
+  directUrl = env("DIRECT_URL")  # direct connection for migrations
+}
+```
+
+## Realtime performance considerations
+
+Supabase Realtime uses Postgres logical replication. High-volume tables with Realtime enabled generate significant WAL traffic.
+
+- Enable Realtime only on tables that clients actually subscribe to.
+- Filter subscriptions as tightly as possible: `channel.on('postgres_changes', { filter: 'user_id=eq.123' }, ...)`.
+- Monitor replication slot lag in Dashboard → Database → Replication.
+
+## Extensions useful for performance
+
+```sql
+-- Query statistics (enabled by default in Supabase)
+SELECT * FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;
+
+-- Index usage stats
+SELECT * FROM pg_stat_user_indexes ORDER BY idx_scan ASC;
+
+-- Table bloat estimate
+SELECT relname, n_dead_tup, n_live_tup, last_autovacuum
+FROM pg_stat_user_tables
+ORDER BY n_dead_tup DESC;
+```
+
+## Sources
+- Query optimization guide: https://supabase.com/docs/guides/database/query-optimization
+- Database advisors: https://supabase.com/docs/guides/database/database-advisors
+- Connecting to Postgres (poolers): https://supabase.com/docs/guides/database/connecting-to-postgres
+- pg_stat_statements: https://www.postgresql.org/docs/current/pgstatstatements.html

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/supabase/references/rls-auth.md

@@ -0,0 +1,106 @@
+# Supabase — Row Level Security and Auth Performance
+
+## Enable RLS on every exposed table
+
+Any table exposed via the Supabase Data API (PostgREST) or Realtime must have RLS enabled. Without it, all authenticated users can access all rows.
+
+```sql
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+ALTER TABLE orders FORCE ROW LEVEL SECURITY;  -- applies to table owner too
+```
+
+## Policy fundamentals
+
+A policy is a `WHERE` predicate automatically appended to every query on the table.
+
+```sql
+-- Users can only see their own orders
+CREATE POLICY "users can read own orders"
+  ON orders FOR SELECT
+  USING (user_id = auth.uid());
+
+-- Users can only insert rows for themselves
+CREATE POLICY "users can insert own orders"
+  ON orders FOR INSERT
+  WITH CHECK (user_id = auth.uid());
+
+-- Separate policies for read vs write
+-- SELECT: use USING()
+-- INSERT: use WITH CHECK()
+-- UPDATE: use both USING() (which rows to target) + WITH CHECK() (what values are allowed)
+-- DELETE: use USING()
+```
+
+## auth.uid() and auth.jwt()
+
+Supabase injects the authenticated user context via:
+- `auth.uid()` — UUID of the current user (`auth.users.id`).
+- `auth.jwt()` — full JWT payload as JSONB. Access claims: `auth.jwt() ->> 'role'`, `(auth.jwt() -> 'user_metadata') ->> 'org_id'`.
+
+```sql
+-- Role-based policy using JWT claims
+CREATE POLICY "admins can read all orders"
+  ON orders FOR SELECT
+  USING (auth.jwt() ->> 'user_role' = 'admin');
+
+-- Multi-tenant: org_id from metadata
+CREATE POLICY "org members can read org orders"
+  ON orders FOR SELECT
+  USING (org_id = (auth.jwt() -> 'user_metadata' ->> 'org_id')::uuid);
+```
+
+## Index policy predicate columns
+
+**RLS policies are evaluated per row.** If the policy predicate isn't indexed, every query scans the full table before filtering.
+
+```sql
+-- Policy uses user_id — must have an index on it
+CREATE INDEX idx_orders_user_id ON orders (user_id);
+
+-- Policy uses org_id — same rule
+CREATE INDEX idx_orders_org_id ON orders (org_id);
+```
+
+For composite queries: `(user_id, status)`, `(org_id, created_at)`.
+
+## Bypassing RLS for service-role operations
+
+Backend code using the `service_role` key bypasses RLS — useful for admin operations, but dangerous if leaked. Never expose `service_role` to client code.
+
+```sql
+-- Explicitly bypass RLS in a function running as superuser
+CREATE FUNCTION admin_get_all_orders()
+RETURNS SETOF orders
+SECURITY DEFINER  -- runs as function owner (bypasses RLS)
+SET search_path = public
+LANGUAGE sql AS $$
+  SELECT * FROM orders;
+$$;
+```
+
+## Measuring policy overhead
+
+```sql
+-- Compare query time with and without RLS
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT * FROM orders WHERE status = 'pending' LIMIT 20;
+
+-- Check if planner inlines auth.uid() correctly (it should appear in the plan)
+```
+
+Benchmark list endpoints that have RLS policies after every policy change — policy complexity directly impacts query time.
+
+## Common RLS mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| No policy defined but RLS enabled | Default deny — no rows returned; add explicit policies |
+| Policy predicate column not indexed | Add index on policy column |
+| Using `auth.uid()` in `WITH CHECK` but not `USING` | UPDATE policy needs both |
+| Relying solely on app-layer filtering | Always enforce with RLS even if app also filters |
+| `service_role` key used in client | Switch to `anon` or `authenticated` key with RLS |
+
+## Sources
+- Row Level Security: https://supabase.com/docs/guides/database/postgres/row-level-security
+- Supabase auth helpers: https://supabase.com/docs/guides/auth
+- PostgreSQL RLS docs: https://www.postgresql.org/docs/current/ddl-rowsecurity.html

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/database-skills/skills/vitess/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: vitess
+description: Vitess sharding strategy, VSchema/vindex design, routing, and scale operations.
+---
+
+# Vitess
+
+## Primary focus
+
+- Choose a strong primary vindex.
+- Keep hot queries shard-local.
+- Minimize cross-shard joins and transactions.
+
+## Optimization workflow
+
+1. Identify dominant access patterns and routing keys.
+2. Design VSchema/vindex for locality and balanced distribution.
+3. Validate routing/fan-out behavior on critical queries.
+4. Use seek pagination anchored on routing key and tie-breaker.
+5. Stage topology/resharding changes with rollback checkpoints.
+
+## Pagination techniques
+
+- Prefer shard-aware keyset pagination.
+- Avoid broad fan-out + offset combinations.
+
+## Operational guardrails
+
+- Treat resharding as staged production operation.
+- Monitor fan-out, replica lag, and failover behavior during topology changes.
+
+## References
+
+- `references/sharding-routing.md`
+- `references/operational-safety.md`