@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/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/claude/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`

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/vitess/references/operational-safety.md

@@ -0,0 +1,105 @@
+# Vitess — Online DDL and Operational Safety
+
+## Online DDL strategies
+
+Vitess manages schema changes as tracked, non-blocking, revertible migrations. This is the **only recommended approach** for production schema changes.
+
+Set DDL strategy per session or globally:
+```sql
+SET @@ddl_strategy = 'vitess';
+```
+
+| Strategy | Description |
+| --- | --- |
+| `vitess` (**recommended**) | VReplication-based. Non-blocking, revertible, failover-safe. |
+| `online` | Alias for `vitess`. |
+| `mysql` | Native MySQL DDL managed by Vitess scheduler. Blocking depends on the DDL. |
+| `direct` | Unmanaged — direct DDL to MySQL. Not trackable. Avoid in production. |
+
+## Running a migration
+
+```sql
+SET @@ddl_strategy = 'vitess';
+ALTER TABLE orders ADD COLUMN notes TEXT;   -- returns migration UUID immediately
+```
+
+```bash
+vtctldclient ApplySchema --ddl-strategy "vitess" \
+  --sql "ALTER TABLE orders ADD COLUMN notes TEXT" commerce
+```
+
+## Migration lifecycle
+
+```
+queued → ready → running → complete
+                         ↘ failed
+         ↘ cancelled
+```
+
+## Monitor and control migrations
+
+```sql
+SHOW VITESS_MIGRATIONS;                                         -- all migrations
+SHOW VITESS_MIGRATIONS LIKE '<uuid>';                           -- specific migration
+```
+
+Key columns to watch: `migration_status`, `progress`, `started_timestamp`, `completed_timestamp`, `message`.
+
+```sql
+ALTER VITESS_MIGRATION '<uuid>' CANCEL;    -- cancel pending
+ALTER VITESS_MIGRATION '<uuid>' RETRY;     -- retry failed
+ALTER VITESS_MIGRATION '<uuid>' COMPLETE;  -- complete a postponed migration
+ALTER VITESS_MIGRATION '<uuid>' LAUNCH;    -- launch a postponed migration
+REVERT VITESS_MIGRATION '<uuid>';          -- revert a completed migration (non-destructive)
+```
+
+## Key DDL strategy flags
+
+Append flags to strategy string:
+```sql
+SET @@ddl_strategy = 'vitess --postpone-completion --allow-concurrent';
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--postpone-launch` | Queue migration but don't start automatically |
+| `--postpone-completion` | Run migration but don't cut over — you control timing |
+| `--allow-concurrent` | Allow multiple migrations to run simultaneously |
+| `--declarative` | Provide desired `CREATE TABLE`; Vitess computes the ALTER |
+| `--prefer-instant-ddl` | Use MySQL INSTANT DDL when possible |
+| `--singleton` | Only one migration on this table at a time |
+
+## Declarative migrations
+
+Supply the desired schema; Vitess computes the diff and runs the minimal ALTER:
+```sql
+SET @@ddl_strategy = 'vitess --declarative';
+CREATE TABLE demo (id BIGINT UNSIGNED NOT NULL, status VARCHAR(32), PRIMARY KEY (id));
+```
+
+## Throttling and failover safety
+
+- The **tablet throttler** automatically slows migrations when replication lag is high.
+  Enable: `vtctldclient UpdateThrottlerConfig --enable <keyspace>`
+- VReplication-based migrations **auto-resume** after primary reparenting (new primary must come up within 10 min).
+
+## Operational guardrails
+
+- **Stage topology and resharding changes** in maintenance windows; keep blast radius small per operation.
+- **Watch fan-out and replication lag** as release gates — do not proceed if lag is elevated.
+- **Prepare explicit rollback procedures per shard move**: `MoveTables SwitchTraffic --reverse`, then `MoveTables Complete` on the old keyspace.
+- Validate with `VDiff` before completing table moves: `vtctldclient VDiff <keyspace> <workflow>`.
+- Test resharding end-to-end on staging with production-like data volume before production.
+
+## Best practices
+
+1. Always use `vitess` strategy in production — never `direct`.
+2. Use `--postpone-completion` for critical tables to control cut-over timing precisely.
+3. Enable the tablet throttler to prevent replication lag buildup.
+4. Use declarative migrations for desired-state schema management.
+5. Monitor all running migrations with `SHOW VITESS_MIGRATIONS` before and after deployments.
+
+## Sources
+- Online DDL guide: https://vitess.io/docs/user-guides/schema-changes/
+- VReplication reference: https://vitess.io/docs/reference/vreplication/
+- Release notes / lifecycle: https://vitess.io/docs/releases/

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/database-skills/skills/vitess/references/sharding-routing.md

@@ -0,0 +1,125 @@
+# Vitess — Sharding and VSchema Design
+
+## Core concept
+
+The **VSchema** tells VTGate how to route queries. It defines which tables belong to which keyspace, which column determines shard placement (the **primary vindex**), and how tables relate across shards.
+
+## Shard routing types
+
+| Routing | Condition | Performance |
+| --- | --- | --- |
+| **Single-shard** | `WHERE` on primary vindex with `=` | Best |
+| **Multi-shard (targeted)** | `WHERE` with `IN` on primary vindex | Good |
+| **Scatter** | No primary vindex filter | Expensive — hits all shards |
+
+Always include the primary vindex column in `WHERE` clauses to avoid scatter queries.
+
+## Choosing a primary vindex column
+
+Pick the column that:
+1. Appears in your highest-QPS `WHERE` clauses.
+2. Enables join co-location — tables frequently joined should shard on the same column.
+3. Keeps transactions within a single shard.
+4. Has high cardinality for even distribution.
+5. Is immutable — changing it after insert requires a data migration.
+
+Common choices: `user_id`, `tenant_id`, `org_id`, `account_id`.
+
+## Vindex types
+
+| Type | When to use |
+| --- | --- |
+| `xxhash` | Any column type — most common |
+| `unicode_loose_xxhash` | Text columns needing case-insensitive hashing |
+| `binary_md5` | MD5-based alternative for any column type |
+
+## VSchema structure (sharded keyspace)
+
+```json
+{
+  "sharded": true,
+  "vindexes": {
+    "xxhash": { "type": "xxhash" }
+  },
+  "tables": {
+    "orders": {
+      "column_vindexes": [
+        { "column": "customer_id", "name": "xxhash" }
+      ],
+      "auto_increment": {
+        "column": "id",
+        "sequence": "unsharded_keyspace.orders_seq"
+      }
+    }
+  }
+}
+```
+
+## Sequences — replacing AUTO_INCREMENT
+
+Per-shard `AUTO_INCREMENT` produces duplicate IDs across shards. Use Vitess Sequences instead.
+
+1. Create in an **unsharded** keyspace:
+   ```sql
+   CREATE TABLE orders_seq (id BIGINT, next_id BIGINT, cache BIGINT, PRIMARY KEY(id))
+     COMMENT 'vitess_sequence';
+   INSERT INTO orders_seq (id, next_id, cache) VALUES (0, 1, 1000);
+   ```
+2. Register in unsharded VSchema: `{ "orders_seq": { "type": "sequence" } }`
+3. Link to sharded table via `auto_increment` in sharded VSchema (see above).
+
+Sequence gaps from caching/restarts are expected and harmless.
+
+## Lookup vindexes (secondary routing)
+
+Lookup vindexes let you route by non-primary-vindex columns without scatter. They are backed by a separate mapping table. **They are expensive** — avoid unless scatter on the column is genuinely a problem.
+
+```json
+"customer_email_lookup": {
+  "type": "consistent_lookup",
+  "params": {
+    "table": "product.customer_email_lookup",
+    "from": "email",
+    "to": "keyspace_id"
+  },
+  "owner": "customer"
+}
+```
+
+Use `consistent_lookup_unique` only when uniqueness across shards must be enforced at the DB level (this is a scalability anti-pattern — prefer app-level enforcement).
+
+## Discover existing VSchema
+
+```bash
+vtctldclient GetVSchema <keyspace>                     # full JSON
+vtctldclient GetVSchema <keyspace> | jq '.vindexes'   # just vindexes
+```
+
+```sql
+SHOW VSCHEMA TABLES;        -- tables known to VTGate
+SHOW VSCHEMA VINDEXES;      -- vindexes and types
+```
+
+## Troubleshoot scatter queries
+
+```sql
+VEXPLAIN PLAN SELECT * FROM orders WHERE customer_id = 42;
+-- Look for Route variant: EqualUnique (single-shard) vs Scatter (all shards)
+
+VEXPLAIN ALL SELECT ...;    -- includes MySQL plans from each tablet
+VEXPLAIN TRACE SELECT ...;  -- shows row counts passed between query parts
+```
+
+If a query scatters:
+1. Is `WHERE` filtering on the primary vindex column? If not, add it.
+2. Is a lookup vindex configured for that column? If needed, add one.
+3. Primary vindex column updates are blocked — use `MoveTables` to re-shard if needed.
+
+## Reference tables
+
+Small, rarely-changing lookup data (countries, currencies, enums) can use `"type": "reference"` — they are replicated to all shards and never scatter.
+
+## Sources
+- VSchema guide: https://vitess.io/docs/user-guides/vschema-guide/
+- Vindexes reference: https://vitess.io/docs/reference/features/vschema/
+- Sharding key selection: https://vitess.io/docs/faq/advanced-configuration/vschema/how-do-you-select-your-sharding-key-for-vitess/

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/debugging-wizard/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: debugging-wizard
+description: "Compatibility alias skill. Deprecated: use systematic-debugging."
+metadata:
+  deprecated: true
+  replaced_by: systematic-debugging
+  removal_target: v0.6.0
+---
+
+# Debugging Wizard
+
+## Compatibility Alias
+
+This skill is deprecated and kept for backward compatibility.
+
+Use `systematic-debugging` as the canonical skill.
+
+## Migration
+
+1. Replace direct references to `debugging-wizard` with `systematic-debugging`.
+2. Apply the full workflow from `systematic-debugging` for new work.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/debugging-wizard/references/common-patterns.md

@@ -0,0 +1,135 @@
+# Common Bug Patterns
+
+> Reference for: Debugging Wizard
+> Load when: Identifying bug type
+
+## Pattern Recognition
+
+| Pattern | Symptom | Likely Cause |
+|---------|---------|--------------|
+| Race condition | Intermittent failures | Missing await, async timing |
+| Off-by-one | Missing first/last item | `<` vs `<=`, array bounds |
+| Null reference | "undefined is not..." | Missing null check |
+| Memory leak | Growing memory | Uncleaned listeners/intervals |
+| N+1 queries | Slow with more data | Fetching in loop |
+| Type coercion | Unexpected behavior | `==` instead of `===` |
+| Closure issue | Wrong variable value | Loop variable capture |
+| Stale state | Old value used | React state closure |
+
+## Race Condition
+
+```typescript
+// BUG: Race condition
+let data;
+fetchData().then(result => { data = result; });
+console.log(data); // undefined!
+
+// FIX: Await the result
+const data = await fetchData();
+console.log(data);
+```
+
+## Off-by-One
+
+```typescript
+// BUG: Skips last element
+for (let i = 0; i < array.length - 1; i++) { }
+
+// FIX: Include last element
+for (let i = 0; i < array.length; i++) { }
+
+// BUG: Array index out of bounds
+const last = array[array.length]; // undefined
+
+// FIX: Correct index
+const last = array[array.length - 1];
+```
+
+## Null Reference
+
+```typescript
+// BUG: Crashes if user is null
+const name = user.profile.name;
+
+// FIX: Optional chaining
+const name = user?.profile?.name ?? 'Unknown';
+
+// FIX: Guard clause
+if (!user?.profile) {
+  return 'Unknown';
+}
+return user.profile.name;
+```
+
+## Memory Leak
+
+```typescript
+// BUG: Listener never removed
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+}, []);
+
+// FIX: Cleanup function
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  return () => window.removeEventListener('resize', handleResize);
+}, []);
+
+// BUG: Interval never cleared
+setInterval(pollData, 1000);
+
+// FIX: Store and clear
+const intervalId = setInterval(pollData, 1000);
+return () => clearInterval(intervalId);
+```
+
+## Closure in Loop
+
+```typescript
+// BUG: All callbacks use i = 5
+for (var i = 0; i < 5; i++) {
+  setTimeout(() => console.log(i), 100);
+}
+
+// FIX: Use let (block scoped)
+for (let i = 0; i < 5; i++) {
+  setTimeout(() => console.log(i), 100);
+}
+
+// FIX: Capture in closure
+for (var i = 0; i < 5; i++) {
+  ((j) => setTimeout(() => console.log(j), 100))(i);
+}
+```
+
+## React Stale State
+
+```typescript
+// BUG: count is stale in closure
+const [count, setCount] = useState(0);
+useEffect(() => {
+  setInterval(() => {
+    setCount(count + 1); // Always uses initial count
+  }, 1000);
+}, []);
+
+// FIX: Use functional update
+setCount(prev => prev + 1);
+
+// FIX: Include in dependency array with cleanup
+useEffect(() => {
+  const id = setInterval(() => setCount(c => c + 1), 1000);
+  return () => clearInterval(id);
+}, []);
+```
+
+## Quick Reference
+
+| Symptom | First Check |
+|---------|-------------|
+| "undefined is not..." | Null check missing |
+| Works sometimes | Race condition |
+| Wrong value in callback | Closure/stale state |
+| Gets slower over time | Memory leak, N+1 |
+| Off by one item | Loop bounds, array index |
+| Type mismatch | `==` vs `===`, coercion |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/debugging-wizard/references/debugging-tools.md

@@ -0,0 +1,143 @@
+# Debugging Tools
+
+> Reference for: Debugging Wizard
+> Load when: Setting up debugging environment
+
+## Debuggers by Language
+
+| Language | Debugger | Start Command |
+|----------|----------|---------------|
+| TypeScript/JS | Node Inspector | `node --inspect` |
+| Python | pdb/ipdb | `python -m pdb` |
+| Go | Delve | `dlv debug` |
+| Rust | rust-gdb/lldb | `rust-gdb ./target/debug/app` |
+| Java | JDB/IDE | IDE debugger |
+
+## Node.js / TypeScript
+
+```bash
+# Start with inspector
+node --inspect dist/main.js
+
+# Break on first line
+node --inspect-brk dist/main.js
+
+# With ts-node
+node --inspect -r ts-node/register src/main.ts
+```
+
+```typescript
+// In code
+debugger; // Breakpoint
+
+// Quick print
+console.log({ variable }); // Shows name and value
+console.table(arrayOfObjects); // Table format
+console.trace('Called from'); // Stack trace
+```
+
+## Python
+
+```bash
+# Start debugger
+python -m pdb script.py
+
+# Post-mortem on exception
+python -m pdb -c continue script.py
+```
+
+```python
+# In code
+breakpoint()  # Python 3.7+
+import pdb; pdb.set_trace()  # Older Python
+
+# Quick print
+print(f"{variable=}")  # Python 3.8+ shows name and value
+
+# Rich debugging
+from rich import inspect
+inspect(object, methods=True)
+```
+
+### pdb Commands
+
+| Command | Action |
+|---------|--------|
+| `n` | Next line |
+| `s` | Step into |
+| `c` | Continue |
+| `l` | List code |
+| `p expr` | Print expression |
+| `pp expr` | Pretty print |
+| `w` | Where (stack) |
+| `q` | Quit |
+
+## Go
+
+```bash
+# Start delve
+dlv debug ./cmd/app
+
+# Attach to running process
+dlv attach <pid>
+
+# Debug test
+dlv test ./pkg/...
+```
+
+```go
+// Quick print
+log.Printf("%+v", variable) // With field names
+fmt.Printf("%#v\n", variable) // Go syntax representation
+
+// Spew for complex structures
+import "github.com/davecgh/go-spew/spew"
+spew.Dump(variable)
+```
+
+### Delve Commands
+
+| Command | Action |
+|---------|--------|
+| `break main.go:42` | Set breakpoint |
+| `continue` | Continue |
+| `next` | Next line |
+| `step` | Step into |
+| `print var` | Print variable |
+| `goroutines` | List goroutines |
+
+## VS Code Debug Config
+
+```json
+// .vscode/launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug TypeScript",
+      "program": "${workspaceFolder}/src/main.ts",
+      "preLaunchTask": "tsc: build",
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+    },
+    {
+      "type": "python",
+      "request": "launch",
+      "name": "Debug Python",
+      "program": "${workspaceFolder}/main.py",
+      "console": "integratedTerminal"
+    }
+  ]
+}
+```
+
+## Quick Reference
+
+| Need | Tool |
+|------|------|
+| Breakpoint in code | `debugger;` / `breakpoint()` |
+| Print with name | `console.log({x})` / `print(f"{x=}")` |
+| Stack trace | `console.trace()` / `traceback.print_stack()` |
+| Inspect object | `console.dir(obj)` / `dir(obj)` |
+| Step through | IDE debugger or CLI debugger |