@tamsensedev/runner 0.0.0-stage → 0.2.1

package/library/skills/motion-design/references/recipes.md

@@ -0,0 +1,243 @@
+# Motion recipes
+
+Read this when implementing a specific transition. Use the project's existing motion tokens and library if it has them; these recipes are CSS first, then examples in common libraries. Do not add a library to use a recipe.
+
+## Tokens
+
+```css
+:root {
+  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
+  --duration-press: 150ms;
+  --duration-popover: 180ms;
+  --duration-dialog: 240ms;
+}
+```
+
+## Reduced motion pattern
+
+Define movement only for people who have not asked to reduce it; keep the opacity change for everyone.
+
+```css
+.toast { transition: opacity 200ms ease; }
+
+@media (prefers-reduced-motion: no-preference) {
+  .toast {
+    transition:
+      opacity 200ms var(--ease-out),
+      transform 200ms var(--ease-out);
+  }
+}
+```
+
+## Press feedback
+
+```css
+.button {
+  transition: transform var(--duration-press) var(--ease-out);
+}
+.button:active:not(:disabled) { transform: scale(0.97); }
+```
+
+## Popover or menu (native popover, no JavaScript)
+
+```css
+.menu[popover] {
+  transform-origin: top left;
+  opacity: 0;
+  transform: scale(0.97);
+  transition:
+    opacity var(--duration-popover) var(--ease-out),
+    transform var(--duration-popover) var(--ease-out),
+    overlay var(--duration-popover) allow-discrete,
+    display var(--duration-popover) allow-discrete;
+}
+.menu[popover]:popover-open { opacity: 1; transform: scale(1); }
+
+@starting-style {
+  .menu[popover]:popover-open { opacity: 0; transform: scale(0.97); }
+}
+```
+
+Browsers without `@starting-style` simply show the menu without animation. Set `transform-origin` to the side of the trigger. With a headless library, use the origin variable it exposes (for example `var(--radix-popover-content-transform-origin)` or `var(--transform-origin)`).
+
+## Dialog
+
+Same pattern on `dialog[open]`, centred origin, `--duration-dialog`, plus a backdrop fade:
+
+```css
+dialog::backdrop { background: rgb(0 0 0 / 0.4); transition: opacity var(--duration-dialog) ease; }
+```
+
+Exit about 75% of the enter duration.
+
+## Drawer or bottom sheet
+
+```css
+.sheet {
+  transform: translateY(100%);
+  transition: transform 300ms var(--ease-drawer);
+}
+.sheet[data-open="true"] { transform: translateY(0); }
+```
+
+Percent translations move by the element's own size, so they work at any height. Add `overscroll-behavior: contain` on the sheet's scroll area.
+
+## Expand and collapse without animating height
+
+```css
+.collapsible {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 250ms var(--ease-out);
+}
+.collapsible[data-open="true"] { grid-template-rows: 1fr; }
+.collapsible > .inner { overflow: hidden; }
+```
+
+## Toast
+
+Enter from the edge it lives on, leave the same way, a little faster:
+
+```css
+.toast { transform: translateY(0); opacity: 1; }
+.toast[data-state="entering"], .toast[data-state="leaving"] { transform: translateY(100%); opacity: 0; }
+.toast[data-state="leaving"] { transition-duration: 150ms; }
+```
+
+Pause auto-dismiss timers while the toast is hovered or the tab is hidden.
+
+## Icon swap (copy to copied, play to pause)
+
+Keep both icons in the DOM, one positioned over the other, and cross-fade:
+
+```css
+.icon-swap { position: relative; display: inline-grid; }
+.icon-swap > * {
+  grid-area: 1 / 1;
+  transition:
+    opacity 250ms cubic-bezier(0.2, 0, 0, 1),
+    transform 250ms cubic-bezier(0.2, 0, 0, 1),
+    filter 250ms cubic-bezier(0.2, 0, 0, 1);
+}
+.icon-swap > [data-hidden="true"] { opacity: 0; transform: scale(0.25); filter: blur(4px); }
+```
+
+## Skeleton
+
+A flat muted block at the final size. If the project pulses skeletons, use a slow opacity pulse (1.5 to 2s) and stop it under reduced motion. No shimmer gradient sweeping across the screen.
+
+## Web Animations API
+
+```js
+const reduce = matchMedia('(prefers-reduced-motion: reduce)').matches
+element.animate(
+  reduce
+    ? [{ opacity: 0 }, { opacity: 1 }]
+    : [{ opacity: 0, transform: 'translateY(8px)' }, { opacity: 1, transform: 'none' }],
+  { duration: 200, easing: 'cubic-bezier(0.23, 1, 0.32, 1)', fill: 'backwards' },
+)
+```
+
+## View Transitions
+
+```js
+function update(change) {
+  if (!document.startViewTransition) return change()
+  document.startViewTransition(change)
+}
+```
+
+```css
+::view-transition-old(root),
+::view-transition-new(root) { animation-duration: 200ms; }
+
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) { animation: none; }
+}
+```
+
+Use them when continuity between two states is the point (a card expanding into its detail), not on every route change. Many routers (Astro, Nuxt, SvelteKit, Next.js) have their own switch for this; use it.
+
+## Vue
+
+```vue
+<template>
+  <Transition name="pop">
+    <div v-if="open" class="menu">...</div>
+  </Transition>
+</template>
+
+<style>
+.pop-enter-active { transition: opacity 180ms var(--ease-out), transform 180ms var(--ease-out); }
+.pop-leave-active { transition: opacity 120ms var(--ease-out), transform 120ms var(--ease-out); }
+.pop-enter-from,
+.pop-leave-to { opacity: 0; transform: scale(0.97); }
+</style>
+```
+
+For lists, `<TransitionGroup>` with a `.list-move { transition: transform 200ms var(--ease-out); }` class animates reordering.
+
+## Svelte
+
+```svelte
+<script>
+  import { fly } from 'svelte/transition'
+  import { cubicOut } from 'svelte/easing'
+</script>
+
+{#if open}
+  <div class="menu" transition:fly={{ y: -4, duration: 180, easing: cubicOut }}>...</div>
+{/if}
+```
+
+## Motion for React
+
+Only if `motion` or `framer-motion` is already installed; import from whichever the project uses.
+
+```jsx
+import { AnimatePresence, motion } from 'motion/react'
+
+<AnimatePresence initial={false}>
+  {open && (
+    <motion.div
+      key="panel"
+      initial={{ opacity: 0, transform: 'scale(0.97)' }}
+      animate={{ opacity: 1, transform: 'scale(1)' }}
+      exit={{ opacity: 0, transform: 'scale(0.97)', transition: { duration: 0.12 } }}
+      transition={{ duration: 0.18, ease: [0.23, 1, 0.32, 1] }}
+    />
+  )}
+</AnimatePresence>
+```
+
+`initial={false}` stops elements already present on first render from animating in. Full `transform` strings stay on the compositor when the main thread is busy; the `x` and `y` shorthands do not. For gestures and drags, springs (`{ type: 'spring', duration: 0.3, bounce: 0 }`) keep their velocity when interrupted; keep bounce at 0 in product UI. `useReducedMotion()` returns the user's preference.
+
+## GSAP
+
+Only if GSAP is already installed.
+
+```js
+import { gsap } from 'gsap'
+
+const mm = gsap.matchMedia()
+mm.add('(prefers-reduced-motion: no-preference)', () => {
+  gsap.from('.step', { opacity: 0, y: 12, duration: 0.4, ease: 'power3.out', stagger: 0.06 })
+})
+```
+
+`gsap.matchMedia()` reverts the animation when the media query stops matching. Keep scroll-triggered work for marketing pages, and give it a version that leaves content visible.
+
+## Drag and gestures
+
+- Capture the pointer once dragging starts (`setPointerCapture`) so the drag continues outside the element.
+- Ignore extra touch points after the drag begins.
+- Dismiss on velocity as well as distance (a quick flick is enough).
+- Past a boundary, apply friction instead of a hard stop.
+- On `pointercancel`, `lostpointercapture` and window `blur`, clear the dragging state so the next drag works.
+- Offer a click or keyboard alternative for every gesture.
+
+Sources: adapted from emilkowalski/skills emil-design-eng (MIT, changed: examples made framework-neutral, Vue, Svelte and GSAP examples added), jakubkrehel/make-interfaces-feel-better animations reference (MIT, changed: icon swap duration aligned to 250ms, CSS grid variant) and pbakaus/impeccable animate and harden references (Apache-2.0, changed: rewritten).

package/library/skills/postgres-performance/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: postgres-performance
+description: Use when writing or reviewing PostgreSQL queries, ORM data access, indexes, pagination, row-level security policies or connection handling, or when an endpoint or page is slow. Checks missing indexes, N+1 queries, OFFSET pagination, long transactions, racy upserts and pool misuse, and verifies fixes with EXPLAIN on a local database.
+---
+
+# PostgreSQL performance
+
+Most slow Postgres code comes from a short list of mistakes: a query without a usable index, a query inside a loop, deep OFFSET pages, transactions held open across network calls, and connections opened per request. This skill finds them in a diff or in slow code and proves the fix with a query plan.
+
+The project's conventions win (naming, ORM style, how indexes are declared, which database version it targets). Schema changes that come out of this work, such as new indexes, must follow the `safe-database-changes` skill (build indexes without blocking writes, separate migration).
+
+## Safety
+
+- Never connect to a real, shared or production database to "check" a plan. Work on a throwaway local database (see `safe-database-changes` for how to get one) or reason from the code.
+- `EXPLAIN ANALYZE` executes the statement. For INSERT, UPDATE or DELETE, run it only on the throwaway database, inside `BEGIN; ... ROLLBACK;`.
+- Do not change server settings (`ALTER SYSTEM`, `max_connections`, pooler config) from a task run. Put recommended settings in the report.
+
+## Process
+
+### 1. Find the SQL that actually runs
+
+ORMs hide the real queries. Read the data-access code and, when you can run it locally, turn on query logging for one request or test: Prisma `log: ['query']`, Django `connection.queries` or `DEBUG` SQL logging, Rails log output, SQLAlchemy `echo=True`, Sequelize `logging`, TypeORM `logging: true`, Drizzle `logger: true`, or `log_statement = 'all'` on the throwaway database. Count queries per request, not just their speed.
+
+### 2. Check against the list, highest impact first
+
+| Priority | Look for | Rule |
+|---|---|---|
+| 1 | Filters, joins and sorts on columns with no matching index | [Indexes](references/rules.md#indexes) |
+| 1 | A query per item inside a loop, or lazy-loaded relations in a list | [N+1](references/rules.md#n1-queries) |
+| 1 | A new connection or client per request; a pool per module | [Connections](references/rules.md#connections) |
+| 1 | RLS policies calling a function per row, unindexed policy columns | [Row-level security](references/rules.md#row-level-security) |
+| 2 | Composite index in the wrong column order; foreign key without an index | [Indexes](references/rules.md#indexes) |
+| 2 | Deep `OFFSET` pagination | [Pagination](references/rules.md#pagination) |
+| 2 | Unbounded `SELECT` (no `LIMIT`) on growing tables; `SELECT *` on wide rows | [Query shape](references/rules.md#query-shape) |
+| 2 | Transactions held across HTTP calls or user input; check-then-insert | [Transactions and locks](references/rules.md#transactions-and-locks) |
+| 3 | Row-by-row inserts; `COUNT(*)` to test existence | [Query shape](references/rules.md#query-shape) |
+| 3 | Functions or casts on indexed columns (`lower(email) = ...`), leading-wildcard `LIKE` | [Indexes](references/rules.md#indexes), [Search](references/rules.md#search-and-jsonb) |
+| 3 | Worker queues that block each other | [Transactions and locks](references/rules.md#transactions-and-locks) |
+| 4 | Column types (int ids that will overflow, `timestamp` without zone, float money) | [Types](references/rules.md#types-and-keys) |
+
+Table size matters. An index on a 200-row lookup table is noise; a missing one on an events table is an outage. When you do not know the size, say what you assumed.
+
+### 3. Fix with the smallest change
+
+- Prefer fixing the query (batch the loop, keyset pagination, select fewer columns) over adding an index; prefer one composite index that serves several queries over several single-column ones.
+- Every index slows writes and takes space. Add one only for a query that runs often or on a large table, and check that an existing index does not already cover it (a composite index on `(a, b)` serves queries on `a` alone).
+- In ORMs, use the ORM's own tools first: eager loading (`include`, `select_related` / `prefetch_related`, `includes`, `joinedload` / `selectinload`), batch `findMany` with `in`, `createMany`, `bulk_create`, `insert_all`, upsert helpers.
+
+### 4. Verify
+
+On the throwaway database, with enough rows for the planner to behave like production (generate them with `generate_series`; a few hundred rows often get a sequential scan no matter what):
+
+```sql
+INSERT INTO orders (customer_id, status, created_at)
+SELECT (random() * 10000)::int, (ARRAY['pending','paid','shipped'])[1 + (random() * 2)::int],
+       now() - random() * interval '365 days'
+FROM generate_series(1, 200000);
+ANALYZE orders;
+
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT id, total FROM orders WHERE customer_id = 42 ORDER BY created_at DESC LIMIT 20;
+```
+
+Read the plan:
+
+- `Seq Scan` on a big table with a selective filter, and a large `Rows Removed by Filter`: missing or unusable index.
+- Estimated rows far from actual rows: stale statistics (run `ANALYZE`) or a correlated filter.
+- `Sort` with `external merge`: sorting on disk; an index matching `ORDER BY` can remove the sort.
+- `Nested Loop` with a huge `loops` count on the inner side: missing index on the join column.
+- `Index Scan` followed by many heap fetches where a covering index would allow an `Index Only Scan`.
+
+Compare the plan before and after the fix. For N+1 fixes, count the queries for one request before and after, or assert the count in a test if the project has a helper for it.
+
+If you cannot run a database, say so and explain from the code why the fix helps.
+
+## Report
+
+For each finding: file and line, the query or ORM call, why it is slow (with the plan or the query count if you measured), the fix, and its cost (new index, extra memory). Separate what you changed from recommendations for operators (pool size, timeouts, server settings).
+
+## Common mistakes
+
+- Adding an index for every column in a WHERE clause, or duplicating an existing index's leading columns.
+- Indexing a low-selectivity column alone (a boolean, a status with three values) when a partial or composite index is what the query needs.
+- Wrapping the indexed column in a function or cast, so the index cannot be used.
+- Measuring on an empty table and concluding the plan is fine.
+- "Fixing" N+1 by caching instead of batching.
+- Raising pool size or `max_connections` to hide connection leaks.
+- Running `EXPLAIN ANALYZE` on a write statement against a real database.
+
+## Done when
+
+- Each slow pattern found is fixed or listed with a reason it was left.
+- New indexes go through a migration that follows `safe-database-changes`.
+- The fix is backed by a plan or query count from a throwaway database, or the report says it could not be measured.
+- Operator-level recommendations are in the report, not applied.
+
+Sources: supabase/agent-skills supabase-postgres-best-practices (MIT, commit c9be0e9). Changed: made Postgres-generic and condensed.

package/library/skills/postgres-performance/references/rules.md

@@ -0,0 +1,265 @@
+# PostgreSQL rules: wrong and right
+
+Read the section that matches what you found in step 2 of the skill. Each rule shows the slow form and the fix. Table and column names are examples.
+
+## Indexes
+
+**Index the columns you filter and join on.** Without one, every lookup scans the whole table.
+
+```sql
+-- wrong: no index on customer_id, so Seq Scan on a large table
+SELECT * FROM orders WHERE customer_id = 123;
+-- right
+CREATE INDEX orders_customer_id_idx ON orders (customer_id);
+```
+
+**Composite indexes: equality columns first, range or sort columns last.** An index on `(a, b)` serves `a = ?` and `a = ? AND b > ?`, but not `b > ?` alone.
+
+```sql
+-- wrong: two single-column indexes, combined with a slower bitmap scan
+CREATE INDEX ON orders (status);
+CREATE INDEX ON orders (created_at);
+-- right, for WHERE status = 'pending' AND created_at > ... ORDER BY created_at
+CREATE INDEX orders_status_created_idx ON orders (status, created_at);
+```
+
+**Index foreign key columns.** Postgres indexes the referenced primary key, not the referencing column. Without it, joins and `ON DELETE CASCADE` scan the child table.
+
+```sql
+-- find foreign keys whose columns lead no index
+SELECT c.conrelid::regclass AS table_name, a.attname AS column_name
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY (c.conkey)
+WHERE c.contype = 'f'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_index i
+    WHERE i.indrelid = c.conrelid AND i.indkey[0] = a.attnum
+  );
+```
+
+**Partial indexes for queries that always filter the same way.** Smaller and faster than a full index.
+
+```sql
+-- queries always add deleted_at IS NULL
+CREATE INDEX users_active_email_idx ON users (email) WHERE deleted_at IS NULL;
+```
+
+**Covering indexes to skip the table.** `INCLUDE` columns you select but do not filter on, so the plan can use an Index Only Scan.
+
+```sql
+CREATE INDEX orders_status_idx ON orders (status) INCLUDE (customer_id, total);
+SELECT status, customer_id, total FROM orders WHERE status = 'shipped';
+```
+
+**Match the index to the expression.** A function or cast on the column hides it from a plain index.
+
+```sql
+-- wrong: index on email is not used
+SELECT * FROM users WHERE lower(email) = lower($1);
+-- right: expression index (or store a normalized column)
+CREATE INDEX users_email_lower_idx ON users (lower(email));
+```
+
+Also watch implicit casts: comparing a `bigint` column with a `text` parameter, or a `timestamptz` column with a date string in another type, can prevent index use.
+
+**Pick the index type for the operator.**
+
+| Data and operator | Index |
+|---|---|
+| `=`, `<`, `>`, `BETWEEN`, `IN`, `ORDER BY` | B-tree (default) |
+| JSONB containment `@>`, `?`, arrays, full-text `@@` | GIN |
+| Ranges, geometry, nearest neighbour | GiST |
+| Huge append-only tables queried by time ranges | BRIN |
+
+**Do not over-index.** Each index costs write time, disk and vacuum work. Before adding one, list existing indexes (`\d table` or `pg_indexes`) and check whether one already has the needed leading columns. In reviews, flag new indexes that duplicate an existing prefix.
+
+## N+1 queries
+
+One query for the list, then one per item:
+
+```sql
+-- wrong: 1 + N round trips
+SELECT id FROM users WHERE active;
+SELECT * FROM orders WHERE user_id = 1;
+SELECT * FROM orders WHERE user_id = 2;
+-- ...
+-- right: one query with an array parameter, or a join
+SELECT * FROM orders WHERE user_id = ANY ($1::bigint[]);
+```
+
+In ORMs this hides behind lazy relations in a loop or a template. Use eager loading (`include`, `with`, `select_related` / `prefetch_related`, `includes` / `preload`, `joinedload` / `selectinload`) or collect ids and fetch once. GraphQL resolvers need a batching loader. Count queries per request to confirm.
+
+## Pagination
+
+OFFSET reads and discards every skipped row, so deep pages get slower and rows shift between pages when data changes.
+
+```sql
+-- wrong
+SELECT * FROM products ORDER BY id LIMIT 20 OFFSET 19980;
+-- right: keyset (cursor) pagination
+SELECT * FROM products WHERE id > $last_id ORDER BY id LIMIT 20;
+-- sorting by several columns: the cursor holds all of them, the index matches
+SELECT * FROM products
+WHERE (created_at, id) > ($last_created_at, $last_id)
+ORDER BY created_at, id LIMIT 20;
+```
+
+OFFSET is acceptable for small, bounded lists (admin tables with a few pages). Exact total counts on large tables are expensive too; consider "has more" instead of a full `COUNT(*)`.
+
+## Query shape
+
+**Bound every list query.** A `SELECT` without `LIMIT` on a table that grows will eventually return too much. Select only the columns you need, especially with wide text or JSON columns.
+
+**Test existence with EXISTS, not COUNT.**
+
+```sql
+-- wrong
+SELECT count(*) FROM orders WHERE user_id = $1;   -- then check > 0
+-- right
+SELECT EXISTS (SELECT 1 FROM orders WHERE user_id = $1);
+```
+
+**Batch inserts.** One statement per row means one round trip per row.
+
+```sql
+-- wrong: a loop of single-row INSERTs
+-- right: multi-row VALUES (hundreds to a few thousand rows per statement)
+INSERT INTO events (user_id, action) VALUES ($1, $2), ($3, $4), ($5, $6);
+-- bulk loads: COPY, or the driver's copy or bulk helper
+```
+
+**Upsert atomically.** Select-then-insert races under concurrency.
+
+```sql
+-- wrong: two requests both see "not found", both insert, one fails
+SELECT 1 FROM settings WHERE user_id = $1 AND key = $2;
+INSERT INTO settings (user_id, key, value) VALUES ($1, $2, $3);
+-- right (needs a unique constraint on user_id, key)
+INSERT INTO settings (user_id, key, value) VALUES ($1, $2, $3)
+ON CONFLICT (user_id, key) DO UPDATE SET value = excluded.value, updated_at = now();
+```
+
+**Beware `NOT IN (subquery)`** when the subquery can return NULL: it returns no rows. Use `NOT EXISTS`.
+
+## Transactions and locks
+
+**Keep transactions short.** Never hold a transaction (and its row locks) open across an HTTP call, a queue publish or user input.
+
+```sql
+-- wrong
+BEGIN;
+SELECT * FROM orders WHERE id = 1 FOR UPDATE;
+-- app calls the payment API for 3 seconds while the row stays locked
+UPDATE orders SET status = 'paid' WHERE id = 1;
+COMMIT;
+-- right: call the API first, then a short conditional update
+UPDATE orders SET status = 'paid', payment_id = $1
+WHERE id = $2 AND status = 'pending'
+RETURNING id;
+```
+
+**Lock rows in a consistent order** to avoid deadlocks, for example `SELECT ... WHERE id IN (...) ORDER BY id FOR UPDATE` before updating several rows, or do it in one UPDATE statement.
+
+**Job queues: `FOR UPDATE SKIP LOCKED`.** Workers then take different rows instead of waiting on each other.
+
+```sql
+UPDATE jobs SET status = 'running', started_at = now(), worker_id = $1
+WHERE id = (
+  SELECT id FROM jobs WHERE status = 'pending'
+  ORDER BY created_at LIMIT 1
+  FOR UPDATE SKIP LOCKED
+)
+RETURNING *;
+```
+
+**Advisory locks** coordinate app-level work (one cron runner at a time) without dummy lock rows: `pg_try_advisory_xact_lock(key)` inside a transaction releases automatically on commit. Session-level advisory locks behave badly with transaction-mode poolers; prefer the transaction-level form.
+
+**Statement timeouts.** A `statement_timeout` (per role, per session or `SET LOCAL` per transaction) stops runaway queries. Recommend values in the report; do not change server settings.
+
+## Connections
+
+**Use one pool per process, created once.** A new client per request exhausts the server's connections under load, and each Postgres connection costs memory.
+
+```js
+// wrong: a client per request
+app.get('/orders', async () => { const c = new Client(url); await c.connect(); /* ... */ });
+// right: module-level pool (or the ORM's single client), reused
+const pool = new Pool({ connectionString: url, max: 10 });
+```
+
+In serverless and edge runtimes, keep the client outside the handler and use the platform's pooler or a transaction-mode pooler such as PgBouncer.
+
+**Transaction-mode poolers do not keep session state.** Named prepared statements, `SET` without `LOCAL`, temp tables, `LISTEN` and session advisory locks can break, because the next transaction may run on another server connection. Use the driver's or ORM's setting for pooled connections (many have a flag to disable named prepared statements) or a session-mode connection for those features.
+
+**Always release connections**, including on errors (`try/finally`, the pool's helper that releases for you). A leak looks like "too many connections" after a while; raising limits only delays it.
+
+Server-side settings (`max_connections`, `idle_in_transaction_session_timeout`, pool sizes) belong in the report as recommendations.
+
+## Row-level security
+
+**Call per-request functions once, not per row.** Wrap them in a scalar subquery so the planner evaluates them once.
+
+```sql
+-- wrong: current_setting() evaluated for every row
+CREATE POLICY orders_owner ON orders
+  USING (user_id = current_setting('app.user_id')::bigint);
+-- right
+CREATE POLICY orders_owner ON orders
+  USING (user_id = (SELECT current_setting('app.user_id')::bigint));
+```
+
+The same applies to platform helpers that return the current user (for example `auth.uid()` on Supabase).
+
+**Index every column the policy filters on** (`user_id`, `tenant_id`, `team_id`). The policy is an extra WHERE clause on every query.
+
+**Complex membership checks:** a `SECURITY DEFINER` function can do an indexed lookup without nested policy evaluation, but it bypasses RLS on the tables it reads. Keep it in a schema the API does not expose, set `search_path = ''` and schema-qualify names, check the caller's identity inside it, and keep `EXECUTE` limited to the roles whose policies call it. Flag any new SECURITY DEFINER function for the `security-review` skill.
+
+Remember that RLS does not apply to table owners unless `FORCE ROW LEVEL SECURITY` is set, and that the application role should not be a superuser.
+
+## Types and keys
+
+| Use | Instead of | Why |
+|---|---|---|
+| `bigint` identity (`GENERATED ALWAYS AS IDENTITY`) | `int`, `serial` | `int` ids overflow at about 2.1 billion |
+| Time-ordered UUIDs (v7) when ids must be distributed or public | Random UUID v4 as the primary key of a big table | Random keys scatter inserts across the index |
+| `timestamptz` | `timestamp` | Stores an absolute moment |
+| `numeric(p, s)` or integer minor units for money | `float`, `real` | Exact arithmetic |
+| `text` (plus a CHECK if a limit matters) | `varchar(n)` chosen arbitrarily | Same performance, fewer migrations |
+| `boolean`, enums or CHECK constraints | Strings for flags and states | Smaller, validated |
+
+UUID v7 is built in from PostgreSQL 18 (`uuidv7()`); older versions need an extension or ids generated by the application. Follow the project's existing key strategy unless the task is about changing it.
+
+Very large time-series tables (hundreds of millions of rows) where old data is dropped in bulk are candidates for range partitioning; this is a design change, so recommend it rather than doing it inside an unrelated task.
+
+## Search and JSONB
+
+**Leading-wildcard LIKE cannot use a B-tree index.**
+
+```sql
+-- wrong on large tables
+SELECT * FROM articles WHERE body ILIKE '%postgres%';
+-- right for word search: full-text search with a GIN index
+ALTER TABLE articles ADD COLUMN search tsvector
+  GENERATED ALWAYS AS (to_tsvector('english', coalesce(title, '') || ' ' || coalesce(body, ''))) STORED;
+CREATE INDEX articles_search_idx ON articles USING gin (search);
+SELECT * FROM articles WHERE search @@ websearch_to_tsquery('english', 'postgres performance');
+```
+
+For substring matching, a trigram index (`pg_trgm` extension, `gin (col gin_trgm_ops)`) supports `ILIKE '%...%'`. Adding an extension is an operator decision: mention it if the project does not already use it. Adding a stored generated column rewrites the table: follow `safe-database-changes`.
+
+**JSONB:** a GIN index serves containment (`@>`); `jsonb_path_ops` is smaller if you only use `@>`. For lookups on one key, an expression index is better:
+
+```sql
+CREATE INDEX products_brand_idx ON products ((attributes ->> 'brand'));
+SELECT * FROM products WHERE attributes ->> 'brand' = 'Acme';
+```
+
+If the same JSON keys are queried everywhere, they probably deserve real columns.
+
+## Diagnostics
+
+- `EXPLAIN (ANALYZE, BUFFERS)` on the throwaway database: see the skill for how to read it.
+- `pg_stat_statements`, if the project or its operators use it, ranks queries by total and mean time; ask for its output in the report rather than querying a production database yourself.
+- After large data changes, `ANALYZE table` refreshes planner statistics; bad estimates (estimated rows far from actual) often mean stale statistics.
+
+Adapted from supabase/agent-skills `skills/supabase-postgres-best-practices` (MIT, commit c9be0e931b7930f7d02126d04774d904c381e7d7, Copyright (c) 2026 Supabase). Changed: made Postgres-generic (Supabase ports, roles and dashboards removed), condensed about 34 rule files into one page, fixed the SECURITY DEFINER example that revoked EXECUTE from the roles its policy needs, replaced server-setting changes with report recommendations, added expression indexes, EXISTS, NOT IN, trigram and ORM notes.