ci(docker): reduce to sync-notice — native pipeline is .hanzo/workflows/deploy.yml

Image build+push+deploy now runs in-cluster (act_runner + BuildKit → operator). GitHub is a mirror; this workflow is retained only as a manual sync notice.
ci(deploy): add native Hanzo deploy pipeline (BuildKit → ghcr → operator patch)
2026-07-24 15:14:30 -07:00 · 2026-07-24 15:14:20 -07:00 · 2026-07-10 03:06:43 -07:00 · 2026-07-07 16:08:16 -07:00 · 2026-07-07 15:47:14 -07:00 · 2026-07-05 00:59:54 -07:00
819 changed files with 51416 additions and 14122 deletions
@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
@@ -0,0 +1,46 @@
+---
+name: postgres
+description: PostgreSQL best practices, query optimization, connection troubleshooting, and performance improvement. Load when working with Postgres databases.
+license: MIT
+metadata:
+  author: planetscale
+  version: "1.0.0"
+---
+
+# PlanetScale Postgres
+
+## Generic Postgres
+
+| Topic                  | Reference                                                        | Use for                                                   |
+| ---------------------- | ---------------------------------------------------------------- | --------------------------------------------------------- |
+| Schema Design          | [references/schema-design.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/schema-design.md)           | Tables, primary keys, data types, foreign keys            |
+| Indexing               | [references/indexing.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/indexing.md)                      | Index types, composite indexes, performance               |
+| Index Optimization     | [references/index-optimization.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/index-optimization.md) | Unused/duplicate index queries, index audit               |
+| Partitioning           | [references/partitioning.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/partitioning.md)             | Large tables, time-series, data retention                 |
+| Query Patterns         | [references/query-patterns.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/query-patterns.md)         | SQL anti-patterns, JOINs, pagination, batch queries       |
+| Optimization Checklist | [references/optimization-checklist.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/optimization-checklist.md) | Pre-optimization audit, cleanup, readiness checks  |
+| MVCC and VACUUM        | [references/mvcc-vacuum.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/mvcc-vacuum.md)               | Dead tuples, long transactions, xid wraparound prevention |
+
+## Operations and Architecture
+
+| Topic                  | Reference                                                                    | Use for                                                         |
+| ---------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Process Architecture   | [references/process-architecture.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/process-architecture.md)     | Multi-process model, connection pooling, auxiliary processes     |
+| Memory Architecture    | [references/memory-management-ops.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/memory-management-ops.md)   | Shared/private memory layout, OS page cache, OOM prevention     |
+| MVCC Transactions      | [references/mvcc-transactions.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/mvcc-transactions.md)           | Isolation levels, XID wraparound, serialization errors          |
+| WAL and Checkpoints    | [references/wal-operations.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/wal-operations.md)                 | WAL internals, checkpoint tuning, durability, crash recovery    |
+| Replication            | [references/replication.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/replication.md)                       | Streaming replication, slots, sync commit, failover             |
+| Storage Layout         | [references/storage-layout.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/storage-layout.md)                | PGDATA structure, TOAST, fillfactor, tablespaces, disk mgmt     |
+| Monitoring             | [references/monitoring.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/monitoring.md)                         | pg_stat views, logging, pg_stat_statements, host metrics        |
+| Backup and Recovery    | [references/backup-recovery.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/backup-recovery.md)              | pg_dump, pg_basebackup, PITR, WAL archiving, backup tools      |
+
+## PlanetScale-Specific
+
+| Topic              | Reference                                                                    | Use for                                               |
+| ------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Connection Pooling | [references/ps-connection-pooling.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/ps-connection-pooling.md)   | PgBouncer, pool sizing, pooled vs direct              |
+| Extensions         | [references/ps-extensions.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/ps-extensions.md)                   | Supported extensions, compatibility                   |
+| Connections        | [references/ps-connections.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/ps-connections.md)                 | Connection troubleshooting, drivers, SSL              |
+| Insights           | [references/ps-insights.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/ps-insights.md)                       | Slow queries, MCP server, pscale CLI                  |
+| CLI Commands       | [references/ps-cli-commands.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/ps-cli-commands.md)               | pscale CLI reference, branches, deploy requests, auth |
+| CLI API Insights   | [references/ps-cli-api-insights.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/ps-cli-api-insights.md)       | Query insights via `pscale api`, schema analysis      |
@@ -0,0 +1,41 @@
+---
+title: Backup and Recovery
+description: Logical/physical backups, PITR, WAL archiving, backup tools, and recovery strategies
+tags: postgres, backup, recovery, pitr, pg_dump, pg_basebackup, wal-archiving, operations
+---
+
+# Backup and Recovery
+
+**FUNDAMENTAL RULE: Backups are useless until you've successfully tested recovery.**
+
+## Logical Backups (pg_dump)
+Exports as SQL or custom format; portable across PG versions and architectures. Formats: `-Fp` (plain SQL), `-Fc` (custom compressed, selective restore), `-Fd` (directory, parallel with `-j`), `-Ft` (tar, avoid). Use `-Fd -j 4` for large DBs. Restore: `pg_restore -d dbname file.dump`; add `-j` for parallel restore. Selective table restore: `pg_restore -t tablename`. Slow for large DBs; RPO = backup frequency (typically 24h).
+
+## Physical Backups (pg_basebackup)
+Copies raw PGDATA; same major version and platform required; cross-architecture works if same endianness (e.g., x86_64 ↔ ARM64). Faster for large clusters; includes all databases. Flags: `-Ft -z -P` for compressed tar with progress. Manual alternative: `pg_backup_start()` → copy PGDATA → `pg_backup_stop()` (complex; must write returned `backup_label`).
+
+## PITR (Point-in-Time Recovery)
+Requires base backup + continuous WAL archiving. Restores to any timestamp, transaction, or named restore point. Without PITR: restore only to backup time (potentially lose hours). With PITR: RPO = minutes. `archive_command` must return 0 ONLY when file is safely stored—premature 0 = data loss risk. `wal_level` must be `replica` or `logical` (not `minimal`).
+
+## WAL Archiving
+`archive_mode=on`, `archive_command='test ! -f /archive/%f && cp %p /archive/%f'`. **Test archive command as postgres user** (not root) since permission issues are common. Monitor `pg_stat_archiver` for `failed_count`, `last_archived_time`. Archive failures prevent WAL recycling → disk fills.
+
+## Tool Comparison
+| Tool | Use case |
+|------|----------|
+| pg_dump | Small DBs, migrations, selective restore |
+| pg_basebackup | Basic PITR, built-in |
+| pgBackRest | Production—parallel, incremental, S3/GCS/Azure, retention |
+| Barman | Enterprise PITR, retention policies |
+| WAL-G | Cloud-native, S3/GCS/Azure |
+
+## RPO/RTO
+Logical only: RPO = backup interval (hours); RTO = hours. PITR: RPO = minutes; RTO = hours. Synchronous replication: RPO = 0; RTO = seconds to minutes (failover).
+
+## Operational Rules
+- Verify integrity with `pg_verifybackup` (PG 13+)
+- Test recovery / PITR regularly
+- Take backups from standby to avoid impacting primary
+- Retention: 7 daily, 4 weekly, 12 monthly
+- Monitor archive growth and backup age
+- **Never assume backups work without testing**
@@ -0,0 +1,69 @@
+---
+title: Index Optimization Queries
+description: Index audit queries
+tags: postgres, indexes, unused-indexes, duplicate-indexes, optimization
+---
+
+# Index Optimization
+
+## Identify Unused Indexes
+
+Query to find unused indexes:
+
+```sql
+-- indexes with 0 scans (check pg_stat_reset / pg_postmaster_start_time first)
+SELECT
+   s.schemaname,
+   s.relname AS table_name,
+   s.indexrelname AS index_name,
+   pg_size_pretty(pg_relation_size(s.indexrelid)) AS index_size
+ FROM pg_catalog.pg_stat_user_indexes s
+ JOIN pg_catalog.pg_index i ON s.indexrelid = i.indexrelid
+ WHERE s.idx_scan = 0
+   AND 0 <> ALL (i.indkey)       -- exclude expression indexes
+   AND NOT i.indisunique          -- exclude UNIQUE indexes
+   AND NOT EXISTS (               -- exclude constraint-backing indexes
+     SELECT 1 FROM pg_catalog.pg_constraint c
+     WHERE c.conindid = s.indexrelid
+   )
+ ORDER BY pg_relation_size(s.indexrelid) DESC;
+```
+
+## Indexes Per Table Guidelines
+
+- **< 5**: Normal
+- **5-10**: Monitor (Verify necessity)
+- **> 10**: Audit required (High write overhead)
+
+```sql
+SELECT relname AS table, count(*) as index_count
+FROM pg_stat_user_indexes
+GROUP BY relname
+ORDER BY count(*) DESC;
+```
+
+## Identify Unused Indexes
+
+Indexes with identical definitions (after normalizing names) on the same table are duplicates:
+
+```sql
+SELECT
+  schemaname || '.' || tablename AS table,
+  array_agg(indexname) AS duplicate_indexes,
+  pg_size_pretty(sum(pg_relation_size((schemaname || '.' || indexname)::regclass))) AS total_size
+FROM pg_indexes
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+GROUP BY schemaname, tablename,
+  regexp_replace(indexdef, 'INDEX \S+ ON ', 'INDEX ON ')
+HAVING count(*) > 1;
+```
+
+**Always confirm with a human before dropping or removing any indexes identified by the queries above.** Even indexes with 0 scans may be needed for infrequent but critical queries, and stats may have been reset recently.
+
+## Per-table Index Count Guidelines
+
+| Index Count | Recommendation                              |
+| ----------- | ------------------------------------------- |
+| <5          | Normal                                      |
+| 5-10        | Review for unused/duplicates                |
+| >10         | Audit required - significant write overhead |
@@ -0,0 +1,61 @@
+---
+title: Indexing Best Practices
+description: Index design guide
+tags: postgres, indexes, composite, partial, covering, gin, brin
+---
+
+# Indexing Best Practices
+
+## Core Rules
+
+1. **Always index foreign key columns** — PostgreSQL does not auto-create these
+2. **Index columns in WHERE, JOIN, and ORDER BY** clauses
+3. **Don't over-index** — each index slows writes and uses storage
+4. **Verify with EXPLAIN ANALYZE** — confirm indexes are actually used
+
+## Composite Indexes
+
+Put equality columns first, then range/sort columns:
+
+```sql
+-- WHERE status = 'active' AND created_at > '2026-01-01'
+CREATE INDEX order_status_created_idx ON order (status, created_at);
+```
+
+A composite index on `(a, b)` supports queries on `a` + `b` and `a` alone, but not `b` alone.
+
+## Partial Indexes
+
+Reduce index size by filtering to common query patterns.
+Only use if index size is problematic but the index is needed for performance.
+
+```sql
+CREATE INDEX order_active_idx ON order (customer_id)
+  WHERE status = 'active';
+```
+
+## Covering Indexes
+
+Consider creating covering indexes for commonly executed query patterns that return only 1 or a small number of columns.
+
+## Index Types
+
+| Type | Use Case | Example |
+| --- | --- | --- |
+| B-tree (default) | Equality, range, sorting | `WHERE id = 1`, `ORDER BY date` |
+| GIN | Arrays, JSONB, full-text | `WHERE tags @> ARRAY['x']` |
+| GiST | Geometric, range types, full-text | PostGIS, `tsrange`, `tsvector` |
+| BRIN | Large sequential/time-series | Append-only logs, events (requires physical row order correlation) |
+
+```sql
+CREATE INDEX metadata_idx ON order USING GIN (metadata);       -- JSONB
+CREATE INDEX event_created_idx ON event USING BRIN (created_at); -- time-series
+```
+
+## Guidelines
+
+- Name indexes consistently: `{table}_{column}_idx`
+- Review for unused indexes periodically
+- **Always confirm with a human before removing or dropping any indexes** — even unused ones may serve a purpose not reflected in recent stats
+- Use partial indexes for frequently filtered subsets
+- Use covering indexes on hot read paths
@@ -0,0 +1,39 @@
+---
+title: Memory Architecture and OOM Prevention
+description: PostgreSQL shared/private memory layout, OS page cache interaction, and OOM avoidance strategies
+tags: postgres, memory, shared_buffers, work_mem, oom, architecture, operations
+---
+
+# Memory Architecture and OOM Prevention
+
+## Memory Areas
+
+- **Shared memory**: `shared_buffers` — main data cache, all processes, requires restart to change.
+- **Private per backend**: `work_mem` (sorts/hashes/joins, per-operation); `maintenance_work_mem` (VACUUM, CREATE INDEX, ALTER TABLE ADD FOREIGN KEY); `temp_buffers` (8MB default).
+- **Planner hint only**: `effective_cache_size` is NOT allocated — set to ~50–75% of total RAM.
+- **Hash multiplier**: `hash_mem_multiplier` (default 2.0) means hash ops use up to 2× `work_mem`.
+
+## Memory Multiplication Danger
+
+Maximum potential: `work_mem × operations_per_query × (parallel_workers + 1) × connections` (leader participates by default via `parallel_leader_participation = on`; hash operations use up to `hash_mem_multiplier × work_mem`, default 2.0). Example: 128MB work_mem, 3 ops (2 sorts + 1 hash join), 2 parallel workers, 100 connections → 2 sorts at 128MB = 256MB, 1 hash join at 128MB × 2.0 = 256MB, per process = 512MB, × 3 processes (2 workers + leader) = 1536MB/query, × 100 connections = **~150GB** worst case. This case is rare.
+Not all queries hit limits at once, but high concurrency + large datasets approach it. This is a common cause of OOM in containerized/Kubernetes deployments. Plan capacity with a 1.5–2× safety margin.
+
+## OS Page Cache (Double Buffering)
+
+Data exists in both `shared_buffers` and OS page cache. A miss in shared_buffers can still hit OS cache (avoiding disk I/O). Extremely large shared_buffers can hurt performance: less OS cache, slower startup, heavier checkpoints. Optimal split depends on workload (OLTP vs OLAP).
+
+## OOM Prevention
+
+- Implement connection pooling to reduce total backend count.
+- Reduce `work_mem` globally; use per-session overrides for heavy queries only.
+- Lower `max_parallel_workers_per_gather` in high-concurrency systems.
+- Set `statement_timeout` to kill runaway queries.
+- Monitor: `dmesg -T | grep "killed process"` and `temp_blks_written` in pg_stat_statements.
+
+## Operational Rules
+
+- Tune per-session first, global last.
+- Suspect OOM when memory spikes during high concurrency, dashboards, or large batch jobs.
+- Increase memory only after confirming spill behavior (`temp_blks_written > 0`).
+- `maintenance_work_mem` can be set much higher (1–2GB) — fewer processes use it. Cap autovacuum with `autovacuum_work_mem` to avoid `autovacuum_max_workers × maintenance_work_mem` memory spikes.
+- `shared_buffers` change requires full restart; `work_mem` is per-session changeable.
@@ -0,0 +1,59 @@
+---
+title: Monitoring
+description: Essential PostgreSQL monitoring views, pg_stat_statements, logging, host metrics, and statistics management
+tags: postgres, monitoring, pg_stat_statements, logging, pgbadger, metrics, operations
+---
+
+# Monitoring
+
+## Essential Views
+
+- **pg_stat_activity**: First stop when something is wrong — running queries, states, wait events, locks.
+- **pg_stat_statements**: Execution stats for all SQL. Requires `shared_preload_libraries = 'pg_stat_statements'` and `CREATE EXTENSION pg_stat_statements`.
+- **pg_stat_database**: Cache hit ratio, temp files, deadlocks, connections per database.
+- **pg_stat_user_tables**: `seq_scan` vs `idx_scan`, dead tuples, last vacuum/analyze times.
+- **pg_stat_user_indexes**: Find unused indexes (`idx_scan = 0` with large size).
+- **pg_stat_bgwriter**: `buffers_clean`, `maxwritten_clean`, `buffers_alloc`. Pre-PG 17 also had `buffers_checkpoint`, `buffers_backend` (high = backends bypassing bgwriter). PG 17+ moved checkpoint stats to `pg_stat_checkpointer`.
+- **pg_stat_checkpointer** (PG 17+): Checkpoint frequency (`num_timed`, `num_requested`), write/sync time.
+
+## Key Queries
+
+```sql
+-- Slow queries (with cache hit ratio)
+SELECT query, calls, mean_exec_time,
+  100.0 * shared_blks_hit / nullif(shared_blks_hit + shared_blks_read, 0) AS cache_hit_pct
+FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;
+
+-- Connection counts / states
+SELECT state, count(*) FROM pg_stat_activity GROUP BY state;
+
+-- Dead tuples (vacuum candidates)
+SELECT relname, n_dead_tup, last_autovacuum FROM pg_stat_user_tables ORDER BY n_dead_tup DESC;
+-- last_autovacuum = <null> means autovacuum has not run on this table
+```
+
+Blocking: use `pg_blocking_pids(pid)` with `pg_stat_activity` to find blocked and blocking sessions.
+
+## Logging — First Line of Defense
+
+PostgreSQL is extremely vocal about problems. **Always check logs first**: `tail -f /var/log/postgresql/postgresql-*.log`.
+
+Key settings: `log_min_duration_statement` (OLTP: 1–3s, analytics: 30–60s, dev: 100–500ms). Enable `log_checkpoints=on`, `log_connections=on`, `log_disconnections=on`, `log_lock_waits=on`, `log_temp_files=0`. Use CSV log format for pgBadger analysis; pgBadger generates HTML reports with query stats and performance graphs.
+
+## pg_activity
+
+Interactive top-like tool (pip install pg_activity). Run on DB host for OS metrics alongside PG metrics. Combines `pg_stat_activity` with CPU/memory/I/O context.
+
+## Host Metrics — Critical
+
+PostgreSQL cannot report these. **Monitor them yourself:**
+
+- **CPU**: Steal time >10% in VMs bad; load average > core count; context switches >100k/sec.
+- **Memory**: Any swap = performance degradation. Check `dmesg` for OOM kills.
+- **Disk I/O**: `iostat -x` — `%util=100%` means saturated; `await` >10ms = high latency.
+- **Disk space**: >90% critical (VACUUM fails, writes fail). Check inode usage too.
+- **Network**: Packet loss >0% = problems; high retransmits = instability.
+
+## Statistics Management
+
+Stats accumulate since last reset or restart; check `stats_reset` timestamp. `pg_stat_statements_reset()` clears query stats; `pg_stat_reset()` clears database stats. Reset after major maintenance, config changes, or perf testing — not routinely. Prefer snapshotting stats to external monitoring (Prometheus, Datadog) over resetting. **Always confirm with a human before resetting statistics** — resetting destroys historical performance baselines and can make it harder to identify unused indexes or regressions.
@@ -0,0 +1,38 @@
+---
+title: MVCC Transactions and Concurrency
+description: Transaction isolation levels, XID wraparound prevention, serialization errors, and long-transaction impact
+tags: postgres, mvcc, transactions, isolation, xid-wraparound, concurrency, serialization
+---
+
+# MVCC Transactions and Concurrency
+
+## Transaction Isolation Levels
+
+- **READ UNCOMMITTED** — treated as READ COMMITTED in PostgreSQL; no dirty reads ever.
+- **READ COMMITTED** (default): new snapshot per statement; can see different data within same tx.
+- **REPEATABLE READ**: snapshot at first query; can cause serialization errors on write conflicts.
+- **SERIALIZABLE**: strongest; transactions appear serial; requires retry logic in app code.
+
+Readers never block writers; writers never block readers (only writer-writer conflicts on same row). No lock escalation — row locks never degrade to table locks.
+
+## XID Wraparound
+
+32-bit transaction IDs wrap at ~2 billion (2^31). `VACUUM FREEZE` replaces old XIDs with FrozenXID (value 2, always visible). Without freeze: after wraparound, old rows appear "in the future" and become **invisible**. Data physically exists but is invisible to all queries — looks like total data loss. PostgreSQL emergency shutdown at 2B XIDs to prevent this. XID wraparound should be avoided at all cost.
+
+Warning messages start at ~1.4B XIDs; shutdown at 2B. Recovery requires single-user mode VACUUM — can take hours to days on large DBs. **Never disable autovacuum** — it's your protection against wraparound.
+
+## XID Age Monitoring
+
+```sql
+SELECT datname, age(datfrozenxid),
+  ROUND(100.0 * age(datfrozenxid) / 2147483648, 2) AS pct
+FROM pg_database ORDER BY age(datfrozenxid) DESC;
+```
+
+## Long Transaction Impact
+
+A single long-running transaction blocks VACUUM from removing dead tuples across the **entire database**. Causes table bloat, increased disk, slower queries, cache pollution. `idle_in_transaction` connections are the #1 operational MVCC issue. Set `idle_in_transaction_session_timeout` (30s–5min). Dead tuples waste I/O on seq scans and cause useless heap lookups from indexes.
+
+## Serialization Errors
+
+Apps **must** handle "could not serialize access" with retry logic. More common in REPEATABLE READ and SERIALIZABLE. Smaller, faster transactions reduce conflict frequency.
@@ -0,0 +1,41 @@
+---
+title: MVCC and VACUUM
+description: MVCC internals, VACUUM/autovacuum tuning, and bloat prevention
+tags: postgres, mvcc, vacuum, autovacuum, xid, bloat, dead-tuples
+---
+
+# MVCC and VACUUM
+
+## MVCC
+
+Every `UPDATE` creates a new tuple and marks the old one dead; `DELETE` marks tuples dead. Dead tuples accumulate until `VACUUM` reclaims space. Each transaction gets a 32-bit XID (2^32 ≈ 4B values, but modular comparison means the effective danger zone is 2^31 ≈ 2B). VACUUM must freeze old XIDs to prevent wraparound.
+
+## VACUUM vs VACUUM FULL
+
+`VACUUM` is non-blocking (ShareUpdateExclusive lock) and marks dead space reusable. `VACUUM FULL` rewrites the table and requires an AccessExclusive lock — use only as a last resort. For online bloat reduction prefer `pg_squeeze` or `pg_repack`.
+
+## Autovacuum Tuning
+
+Triggers when dead tuples > `Min(autovacuum_vacuum_max_threshold, autovacuum_vacuum_threshold + autovacuum_vacuum_scale_factor * reltuples)`. `autovacuum_vacuum_max_threshold` defaults to 100M (PG 18+), capping the threshold for very large tables. Also triggers on inserts exceeding `autovacuum_vacuum_insert_threshold + autovacuum_vacuum_insert_scale_factor * reltuples * pct_not_frozen` (ensures insert-only tables get frozen; PG 13+). For large/hot tables, set per-table overrides:
+
+- `autovacuum_vacuum_scale_factor` — default 0.2; lower to 0.01–0.05 for large tables.
+- `autovacuum_vacuum_cost_delay` — default 2 ms; set to 0 on fast storage.
+- `autovacuum_vacuum_cost_limit` — default -1 (uses `vacuum_cost_limit`, effectively 200); raise to 1000–2000 on fast storage.
+- `autovacuum_freeze_max_age` — default 200M; triggers anti-wraparound vacuum.
+- `vacuum_failsafe_age` — default 1.6B; last-resort mode (PG 14+) that disables throttling and skips index vacuuming when wraparound is imminent.
+
+## Key Monitoring Queries
+
+Dead tuples: `SELECT relname, n_dead_tup, last_autovacuum FROM pg_stat_user_tables ORDER BY n_dead_tup DESC;`
+
+XID age: `SELECT datname, age(datfrozenxid) AS xid_age FROM pg_database ORDER BY xid_age DESC;`
+
+Long transactions: `SELECT pid, state, now() - xact_start AS tx_age FROM pg_stat_activity WHERE xact_start IS NOT NULL ORDER BY xact_start;`
+
+## Best Practices
+
+- Keep transactions short; set `idle_in_transaction_session_timeout` (30s–5min).
+- Alert when `age(datfrozenxid)` exceeds 40–50% of wraparound (~800M–1B).
+- Tune autovacuum per-table for write-heavy tables; don't change global defaults first.
+- Fix application transaction scope before adjusting vacuum parameters.
+- Never disable autovacuum globally.
@@ -0,0 +1,19 @@
+---
+title: Database Optimization Checklist
+description: Optimize checklist
+tags: postgres, optimization, indexes, partitioning, maintenance
+---
+
+# Optimization Checklist
+
+When optimizing performance, check the following:
+
+- Look for unused indexes (0 scans; exclude unique/primary indexes and verify stats age first)
+- Look for duplicate indexes
+- Archive audit/log tables >10GB
+- Review tables >500GB for partitioning (>100GB for time-series/logs)
+- Verify all extensions are supported
+- Check for circular foreign key dependencies
+- Consider alternatives to UUID primary keys for large tables
+- Configure connection pooling for OLTP workloads
+- **Always confirm with a human before removing any indexes, dropping partitions, archiving tables, or performing other destructive actions**
@@ -0,0 +1,79 @@
+---
+title: Table Partitioning Guide
+description: Partition guide
+tags: postgres, partitioning, range, list, pg_partman, data-retention
+---
+
+# Table Partitioning
+
+Plan partitioning upfront for tables expected to grow large. Retrofitting later requires a migration.
+
+## When to Partition
+
+Partitioning benefits maintenance (vacuum, index builds) and data retention more than pure query speed.
+
+| Table Type | Size Threshold | Row Threshold |
+| --- | --- | --- |
+| General tables | >100 GB (or >RAM) | >20M rows |
+| Time-series / logs | >50 GB | >10M rows |
+
+Use the lower thresholds for append-heavy, time-ordered data with retention needs (logs, events, audit trails, metrics).
+
+## Range Partitioning (Most Common)
+
+```sql
+-- EXAMPLE
+CREATE TABLE event (
+  id BIGINT GENERATED ALWAYS AS IDENTITY,
+  event_type TEXT NOT NULL,
+  payload JSONB,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (id, created_at) -- Partition key MUST be part of PK
+) PARTITION BY RANGE (created_at);
+
+CREATE TABLE event_2026_01 PARTITION OF event
+  FOR VALUES FROM ('2026-01-01') TO ('2026-02-01');
+
+CREATE TABLE event_2026_02 PARTITION OF event
+  FOR VALUES FROM ('2026-02-01') TO ('2026-03-01');
+```
+
+## List Partitioning
+
+Useful for partitioning by region, tenant, or category:
+
+```sql
+-- EXAMPLE
+CREATE TABLE order (
+  id BIGINT GENERATED ALWAYS AS IDENTITY,
+  region TEXT NOT NULL,
+  total NUMERIC(10,2),
+  PRIMARY KEY (id, region) -- Partition key MUST be part of PK
+) PARTITION BY LIST (region);
+
+CREATE TABLE order_us PARTITION OF order FOR VALUES IN ('us');
+CREATE TABLE order_eu PARTITION OF order FOR VALUES IN ('eu');
+CREATE TABLE order_default PARTITION OF order DEFAULT;  -- catches unmatched values
+```
+
+## Partition Management
+
+- Use `pg_partman` (extension) to automate partition creation and cleanup.
+- Use `DETACH PARTITION` to remove a partition while retaining it as a standalone table (e.g., for archiving).
+- Use `DETACH PARTITION ... CONCURRENTLY` (PG 14+) to avoid `ACCESS EXCLUSIVE` locks on the parent table.
+- Drop old partitions for data retention instead of `DELETE` to avoid vacuum overhead and bloat.
+- Create future partitions ahead of time to avoid insert failures.
+- **Always confirm with a human before detaching or dropping partitions.** These are destructive actions — detaching removes data from the partitioned table, and dropping permanently deletes the data.
+
+```sql
+-- DESTRUCTIVE: confirm with a human before executing
+ALTER TABLE event DETACH PARTITION event_2025_01 CONCURRENTLY;
+DROP TABLE event_2025_01;
+```
+
+## Guidelines & Limitations
+
+- **Primary Keys**: Partition key columns MUST be included in the `PRIMARY KEY` and any `UNIQUE` constraints.
+- **Global Uniqueness**: Global unique constraints on non-partition columns are NOT supported.
+- **Indexes**: Indexes defined on the parent are automatically created on all partitions (and future ones).
+- **Pruning**: Ensure queries filter by the partition key to enable "partition pruning" (skipping unrelated partitions).
@@ -0,0 +1,46 @@
+---
+title: Process Architecture
+description: PostgreSQL multi-process model, connection management, and auxiliary processes
+tags: postgres, processes, connections, pooling, memory, operations
+---
+
+# Process Architecture
+
+PostgreSQL uses a **multi-process** model, not multi-threaded: one OS process per client connection. The postmaster is the parent; it spawns backend processes per connection. Each backend has some private memory (`work_mem`, temp buffers). 1000 connections = 1000 processes (~5–10MB base + query memory each). There is also a large buffer shared amongst all.
+
+## Auxiliary Processes
+
+WAL Writer, Background Writer, Checkpointer, Autovacuum Launcher/Workers, Archiver, WAL Summarizer (PG 17+). These run alongside backends and are not spawned per connection.
+
+## Memory Risk
+
+`work_mem` is per-operation, not per-query. Estimate: `work_mem × operations_per_query × parallel_workers × connections` can grow very large at high concurrency. Scale connections and parallelism before raising `work_mem`.
+
+## Connection Pooling (Critical)
+
+Each connection = OS process (fork overhead, context switching, memory). PgBouncer can multiplex many app connections to fewer DB connections. Typical: 1000 app connections → pooler → 20–50 backends. Implement pooling before raising `max_connections`; `max_connections` requires a full restart to change (default 100). Note: `superuser_reserved_connections` (default 3) reserves slots for emergency superuser access, so non-superusers are rejected before `max_connections` is fully reached.
+
+## Monitoring
+
+```sql
+SELECT state, count(*) FROM pg_stat_activity WHERE backend_type = 'client backend' GROUP BY state;
+```
+
+```sql
+-- Show used and free connection slots
+SELECT count(*) AS used, max(max_conn) - count(*) AS free
+FROM pg_stat_activity, (SELECT setting::int AS max_conn FROM pg_settings WHERE name = 'max_connections') s
+WHERE backend_type = 'client backend';
+```
+
+Use `pg_activity` for interactive top-like monitoring. Alert at 80% connection usage, critical at 95%. Count by state to find idle-in-transaction leaks — these hold locks and **block VACUUM** from reclaiming dead tuples.
+
+## Common Problems
+
+| Problem | Fix |
+| ------- | --- |
+| `too many clients already` | Implement pooling; find idle connections; check for connection leaks |
+| High memory / OOM | Reduce `work_mem`; add pooling; set `statement_timeout` |
+| Stuck process | `SELECT pg_cancel_backend(pid);` then `SELECT pg_terminate_backend(pid);` — **always confirm with a human before terminating backends**, as this may abort in-flight transactions and cause data issues for the application |
+
+Prefer pooling + conservative `max_connections` over raising limits reactively.
@@ -0,0 +1,53 @@
+---
+title: CLI Query Insights API
+description: CLI insights usage
+tags: postgres, planetscale, cli, insights, query-patterns, api
+---
+
+# Query Insights via pscale CLI
+
+Analyze slow queries and missing indexes using `pscale api`. Endpoints may change—see https://planetscale.com/docs/api/reference/getting-started-with-planetscale-api for current API docs.
+
+## Using pscale api
+
+The `pscale api` command makes authenticated API calls using your current login or service token (see [ps-cli-commands.md](ps-cli-commands.md#service-token-cicd) for auth setup). No need to manage auth headers manually.
+
+```bash
+pscale api "<endpoint>" [--method POST] [--field key=value] [--org <org>]
+```
+
+## Query Patterns Reports
+
+```bash
+# Create a new report
+pscale api "organizations/{org}/databases/{db}/branches/{branch}/query-patterns-reports" \
+  --method POST --org my-org
+
+# Check status (poll until state=complete)
+pscale api "organizations/{org}/databases/{db}/branches/{branch}/query-patterns-reports/{id}/status"
+
+# Download completed report
+pscale api "organizations/{org}/databases/{db}/branches/{branch}/query-patterns-reports/{id}"
+
+# List all reports
+pscale api "organizations/{org}/databases/{db}/branches/{branch}/query-patterns-reports"
+```
+
+## Schema Analysis
+
+```bash
+# Get branch schema
+pscale api "organizations/{org}/databases/{db}/branches/{branch}/schema"
+
+# Lint schema for issues
+pscale api "organizations/{org}/databases/{db}/branches/{branch}/schema/lint"
+```
+
+## What to Look For
+
+| Metric                           | Indicates             | Action                          |
+| -------------------------------- | --------------------- | ------------------------------- |
+| High `rows_read / rows_returned` | Missing or poor index | Add index on WHERE/JOIN columns |
+| High `total_time_s`              | Heavy query           | Optimize or cache               |
+| High `count` with same pattern   | N+1 queries           | Batch or eager-load             |
+| `indexed: false`                 | Full table scan       | Add index                       |
@@ -0,0 +1,72 @@
+---
+title: PlanetScale CLI Reference
+description: CLI command guide
+tags: planetscale, cli, branches, deploy-requests, authentication
+---
+
+# pscale CLI Commands
+
+Full CLI reference: https://planetscale.com/docs/cli. Use `pscale <command> --help` for subcommands and flags.
+
+## Authentication
+
+```bash
+pscale auth login                    # Opens browser
+pscale auth logout
+pscale org list
+pscale org switch <name>
+```
+
+### Service Token (CI/CD)
+
+```bash
+# Create and configure
+pscale service-token create
+pscale service-token add-access <id> read_branch --database <db>
+# Use in CI/CD
+export PLANETSCALE_SERVICE_TOKEN_ID="<id>"
+export PLANETSCALE_SERVICE_TOKEN="<token>"
+```
+
+## Core Commands
+
+```bash
+# Databases
+pscale database list
+pscale database create <name>
+
+# Branches
+pscale branch list <db>
+pscale branch create <db> <branch> [--from <parent>]
+pscale branch delete <db> <branch>    # DESTRUCTIVE — always confirm with a human first
+pscale branch schema <db> <branch>
+
+# Deploy requests (schema changes) — Vitess only
+pscale deploy-request create <db> <branch>
+pscale deploy-request list <db>
+pscale deploy-request deploy <db> <number>
+
+# Connect
+pscale shell <db> <branch>           # Opens psql (Postgres) or mysql (Vitess)
+pscale connect <db> <branch>         # Proxy for GUI tools (secure tunnel) — Vitess only
+
+# Credentials
+pscale role create <db> <branch> <name>      # Postgres
+pscale password create <db> <branch> <name>  # Vitess
+
+# Other
+pscale ping              # Check latency to regions
+pscale region list       # Available regions
+pscale backup list <db> <branch>
+pscale backup create <db> <branch>
+```
+
+## Useful Flags
+
+```bash
+--format json    # Output as JSON (also: csv, human)
+--org <name>     # Specify organization
+--debug          # Debug output
+```
+
+For API calls via CLI, see [ps-cli-api-insights.md](ps-cli-api-insights.md).
@@ -0,0 +1,72 @@
+---
+title: PgBouncer Connection Pooling
+description: Pooling setup guide
+tags: postgres, pgbouncer, connection-pooling, performance, transactions
+---
+
+# Connection Pooling with PgBouncer
+
+PlanetScale provides PgBouncer for connection pooling. Connect on port `6432` instead of `5432`.
+
+## When to Use PgBouncer (Port 6432)
+
+All OLTP application workloads: web apps, APIs, high-concurrency read/write operations.
+
+## When to Use Direct Connections (Port 5432)
+
+- Schema changes (DDL)
+- Analytics, reporting, batch processing
+- Session-specific features (temp tables, session variables)
+- ETL, data streaming, `pg_dump`
+- Long-running admin transactions
+
+## PgBouncer Types
+
+PlanetScale offers three PgBouncer options. All use port `6432`.
+
+| Type | Runs On | Routes To | Key Trait |
+| ---- | ------- | --------- | --------- |
+| **Local** | Same node as primary | Primary only | Included with every database; no replica routing |
+| **Dedicated Primary** | Separate node | Primary | Connections persist through resizes, upgrades, and most failovers |
+| **Dedicated Replica** | Separate node | Replicas | Read-only traffic; supports AZ affinity for lower latency |
+
+- **Local PgBouncer** — use same credentials as direct, just change port to `6432`. Always routes to primary regardless of username.
+- **Dedicated Primary** — runs off-server for improved HA. Use for production OLTP write traffic.
+- **Dedicated Replica** — runs off-server for read-heavy workloads. Supports AZ affinity to prefer same-zone replicas. Multiple can be created for capacity or per-app isolation.
+
+To connect to a dedicated PgBouncer, append `|pgbouncer-name` to the username (e.g., `postgres.xxx|write-pool` or `postgres.xxx|read-bouncer`).
+
+## Transaction Pooling Limitations
+
+PlanetScale PgBouncer uses **transaction pooling mode**. These features are unavailable:
+
+- Prepared statements that persist across transactions
+- Temporary tables
+- `LISTEN`/`NOTIFY`
+- Session-level advisory locks
+- `SET` commands persisting beyond a transaction
+
+## Recommended Patterns
+
+- Size pools from observed concurrency, query memory behavior, and connection limits.
+- Keep pooled app traffic on `6432` and reserve direct connections for DDL/admin/long-running jobs.
+
+## Avoid Patterns
+
+- Avoid setting pool size with only `CPU_cores * N` while ignoring query-memory amplification.
+- Avoid running session-dependent workflows through transaction pooling.
+
+## Connecting
+
+```bash
+# Local PgBouncer (same credentials, port 6432)
+psql 'host=xxx.horizon.psdb.cloud port=6432 user=postgres.xxx password=pscale_pw_xxx dbname=mydb sslnegotiation=direct sslmode=verify-full sslrootcert=system'
+
+# Dedicated primary PgBouncer (append |pgbouncer-name to user)
+psql 'host=xxx.horizon.psdb.cloud port=6432 user=postgres.xxx|write-pool password=pscale_pw_xxx dbname=mydb sslnegotiation=direct sslmode=verify-full sslrootcert=system'
+
+# Dedicated replica PgBouncer (append |pgbouncer-name to user)
+psql 'host=xxx.horizon.psdb.cloud port=6432 user=postgres.xxx|read-bouncer password=pscale_pw_xxx dbname=mydb sslnegotiation=direct sslmode=verify-full sslrootcert=system'
+```
+
+Docs: https://planetscale.com/docs/postgres/connecting/pgbouncer
@@ -0,0 +1,37 @@
+---
+title: PlanetScale Postgres Connections
+description: Connection guide for PlanetScale Postgres
+tags: planetscale, postgres, connections, ssl, troubleshooting
+---
+
+# PlanetScale Postgres Connections
+
+Postgres docs: https://planetscale.com/docs/postgres/connecting
+
+| Protocol | Standard Port | Pooled Port | SSL      |
+| -------- | ------------- | ----------------------- | -------- |
+| Postgres | 5432          | 6432 (PgBouncer)        | Required |
+
+Credentials (roles) are branch-specific and cannot be recovered after creation.
+
+## Connection String
+
+```
+postgresql://<user>:<password>@<host>.horizon.psdb.cloud:5432/<database>?sslmode=verify-full&sslrootcert=system&sslnegotiation=direct
+```
+
+Use port **6432** for PgBouncer (applications/OLTP).
+Use port **5432** for DDL, admin tasks, and migrations.
+
+## Troubleshooting
+
+| Error | Fix |
+| -------------------------------- | --------------------------------------- |
+| `password authentication failed` | Check role format: `<role>.<branch_id>` |
+| `too many clients already`       | Use PgBouncer (port 6432)               |
+| `SSL connection is required`     | Add `sslmode=verify-full&sslrootcert=system` |
+
+**Best practices:**
+- Use the PlanetScale Postgres metrics page to monitor direct and PgBouncer connections
+- Route OLTP traffic to port 6432 and reserve 5432 for admin/migrations.
+- Avoid raising `max_connections` reactively instead of pooling.
@@ -0,0 +1,27 @@
+---
+title: PlanetScale PostgreSQL Extensions
+description: Extension reference
+tags: postgres, extensions
+---
+
+# PostgreSQL Extensions on PlanetScale
+
+Only use PlanetScale-supported extensions. For the complete and up-to-date list of available extensions, see: https://planetscale.com/docs/postgres/extensions
+
+Do not rely on hard-coded extension lists — always check the documentation above for current availability.
+
+## Enabling Extensions
+
+Some extensions must first be **enabled in the PlanetScale Dashboard** (Clusters > Extensions) before they can be created in SQL. This often requires a database restart.
+
+Once enabled in the dashboard, create the extension in SQL:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS <extension_name>;
+```
+
+## Recommended Patterns
+
+- Always check the [PlanetScale extensions docs](https://planetscale.com/docs/postgres/extensions) before assuming an extension is available.
+- Verify extension availability in PlanetScale configuration and docs before schema design depends on it.
+- Enable `pg_stat_statements` early for baseline query telemetry.
@@ -0,0 +1,62 @@
+---
+title: PlanetScale Query Insights
+description: Query insights guide
+tags: postgres, planetscale, insights, monitoring, optimization
+---
+
+# PlanetScale Insights
+
+## Fetch current documentation first
+
+Prefer retrieval over pre-training knowledge. Docs: https://planetscale.com/docs
+
+## MCP Server (Preferred)
+
+When the PlanetScale MCP server is configured in your environment, prefer it over CLI. Key tools:
+
+- `planetscale_get_branch_schema` — Get schema for a branch
+- `planetscale_execute_read_query` — Run SELECT, SHOW, DESCRIBE, EXPLAIN
+- `planetscale_get_insights` — Query performance insights
+- `planetscale_list_schema_recommendations` — Index and schema suggestions
+- `planetscale_search_documentation` — Search PlanetScale docs
+
+MCP setup: https://planetscale.com/docs/connect/mcp
+
+The MCP server is the ideal way to interact with insights from an AI agent.
+If not installed, prompt the user to install it to make the agent more effective.
+
+## Query Insights (CLI)
+
+Generating reports via CLI is a multi-step process (create → wait → download).
+
+See [ps-cli-api-insights.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/ps-cli-api-insights.md) for how to use.
+
+What to look for:
+
+- High `rows_read / rows_returned` ratio → missing index
+- High `total_time_s` → optimization target
+
+## Insights UI (Dashboard)
+
+In the [PlanetScale dashboard](https://app.planetscale.com/), select your database and click **Insights**.
+
+- **Filtering** — Pick a branch, choose primary or replica, and scroll through the last 7 days. Click-and-drag on graphs to zoom into a time window.
+- **Graphs** — Four tabs: Query latency (p50/p95/p99/p99.9), Queries per second, Rows read/s, and Rows written/s.
+- **Queries table** — All queries in the selected timeframe, normalized into patterns. Sortable and filterable by SQL, schema, table, latency, index usage, and more. Customizable columns (count, total time, latency percentiles, rows read/returned/affected, CPU/IO time, cache hit ratio, etc.). Enable sparklines for inline trend graphs. Orange icons flag full table scans.
+- **Query deep dive** — Click any query to see per-pattern graphs, summary stats, index usage breakdown, and a table of notable executions (>1 s, >10k rows read, or errors). Use "Summarize query" for an LLM-generated plain-English description.
+- **Anomalies tab** — Flags periods with elevated slow-running queries and surfaces the responsible patterns.
+- **Errors tab** — Surfaces queries that produced errors.
+- **pginsights settings** — `pginsights.raw_queries` enables full query text collection for notable queries; `pginsights.normalize_schema_names` groups identical patterns across schemas (useful for schema-per-tenant designs). Both configurable in the Extensions tab on the Clusters page.
+
+More: [PlanetScale Insights docs](https://planetscale.com/docs/postgres/monitoring/query-insights)
+
+## Optimization Checklist
+
+- Remove unused indexes (0 scans)
+- Remove duplicate indexes
+- Archive audit/log tables >10 GB
+- Review tables >100 GB for partitioning
+
+**Always confirm with a human before removing indexes, dropping tables/partitions, or archiving data.** These are destructive actions that cannot be easily undone.
+
+More: [optimization-checklist.md](https://raw.githubusercontent.com/planetscale/database-skills/main/skills/postgres/references/optimization-checklist.md)
@@ -0,0 +1,80 @@
+---
+title: SQL Query Patterns
+description: Common SQL anti-patterns and optimized alternatives
+tags: postgres, sql, query-optimization, n-plus-one, pagination
+---
+
+# SQL Query Patterns
+
+## Query Structure
+
+**SELECT specific columns** — avoids fetching unnecessary data and enables covering indexes:
+```sql
+-- Bad:
+SELECT * FROM user WHERE status = 'active';
+-- Good:
+SELECT id, name, email FROM user WHERE status = 'active';
+```
+
+**Subqueries → JOINs** — correlated subqueries re-execute per row:
+```sql
+-- Bad
+SELECT id, (SELECT COUNT(*) FROM order WHERE order.user_id = user.id) FROM user;
+-- Good
+SELECT u.id, COUNT(o.id) FROM user u LEFT JOIN order o ON o.user_id = u.id GROUP BY u.id;
+```
+
+**Always LIMIT unbounded queries** — prevent runaway result sets:
+```sql
+SELECT id, message FROM log WHERE level = 'error' ORDER BY created_at DESC LIMIT 100;
+```
+
+**Avoid functions on indexed columns (SARGable)** — functions prevent index usage unless a functional index exists:
+```sql
+-- Bad: Full table scan
+SELECT * FROM user WHERE date_trunc('day', created_at) = '2023-01-01';
+-- Good: Index scan
+SELECT * FROM user WHERE created_at >= '2023-01-01' AND created_at < '2023-01-02';
+```
+
+## N+1 Detection
+
+**Queries inside loops → batch with ANY/IN:**
+```python
+# Bad
+for uid in user_ids:
+    cursor.execute("SELECT name FROM user WHERE id = %s", (uid,))
+# Good (Postgres specific)
+cursor.execute("SELECT id, name FROM user WHERE id = ANY(%s)", (list(user_ids),))
+# Good (Standard SQL)
+# cursor.execute("SELECT id, name FROM user WHERE id IN %s", (tuple(user_ids),))
+```
+
+**ORM lazy loading → eager loading:**
+```python
+# Bad: N+1 — each iteration fires a query
+for user in User.query.all():
+    print(user.posts)
+# Good
+users = User.query.options(joinedload(User.posts)).all()
+```
+
+## Query Rewrites
+
+**UNION → UNION ALL** — skip deduplication when duplicates are impossible or acceptable.
+
+**IN subquery → EXISTS** — EXISTS short-circuits on first match:
+```sql
+SELECT id, name FROM user u
+WHERE EXISTS (SELECT 1 FROM order o WHERE o.user_id = u.id AND o.total > 100);
+```
+
+**OFFSET → cursor pagination** — OFFSET scans and discards rows, degrading at depth:
+```sql
+-- Bad: OFFSET 10000 scans 10020 rows
+SELECT id, title FROM article ORDER BY created_at DESC LIMIT 20 OFFSET 10000;
+-- Good: cursor-based (requires index on (created_at DESC, id DESC))
+SELECT id, title FROM article
+WHERE (created_at, id) < ('2025-06-15T12:00:00Z', 987654)
+ORDER BY created_at DESC, id DESC LIMIT 20;
+```
@@ -0,0 +1,49 @@
+---
+title: Replication
+description: Streaming replication, replication slots, synchronous commit levels, failover, and standby management
+tags: postgres, replication, streaming, slots, synchronous, failover, standby, operations
+---
+
+# Replication
+
+## Streaming Replication for followers
+
+Use physical (byte-for-byte) replication via WAL stream from primary to standbys. Standbys are read-only (hot standby); same major PG version and architecture required (same minor recommended). Without replication slots, the primary may recycle WAL before the standby receives it → standby needs full resync via `pg_basebackup`. Use replication slots to guarantee WAL retention for specific standbys.
+
+## Replication Slots
+
+Postgres supports Physical slots (streaming) and logical slots (logical replication). Slots prevent WAL deletion even if standby is offline — can exhaust `pg_wal/` disk. Use `max_slot_wal_keep_size` to cap retained WAL per slot. Use `idle_replication_slot_timeout` (PG 17+) to auto-invalidate idle slots. `wal_keep_size` is a simpler alternative to slots for WAL retention. Drop inactive slots immediately to prevent disk exhaustion.
+
+Slot lag (MB behind): `SELECT slot_name, pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)/1024/1024 AS mb_behind FROM pg_replication_slots;`
+
+Drop inactive slot: `SELECT pg_drop_replication_slot('slot_name');`
+
+**Always confirm with a human before dropping replication slots.** Dropping an active or needed slot can cause downstream issues.
+
+## Synchronous Commit Levels
+
+| Level | Behavior | Use Case |
+|-------|----------|----------|
+| `off` | Returns immediately, no wait | Non-critical writes; risks losing ~600ms of commits on crash (no inconsistency) |
+| `local` | Waits for local WAL fsync only | Local durability only; no standby wait |
+| `remote_write` | Waits for standby OS buffer | Data loss on standby OS crash |
+| `on` | Waits for standby WAL to disk when `synchronous_standby_names` is set; otherwise same as `local` | **Default. This level or higher recommended for HA** |
+| `remote_apply` | Waits for standby to apply WAL | Strongest; read-your-writes |
+
+Configure with `synchronous_standby_names`. Use `ANY N` for quorum or `FIRST N` for priority-based sync.
+
+## Quorum and Failure
+
+`FIRST 2 (s1, s2, s3)` is priority-based: waits for the 2 highest-priority connected standbys (s1+s2; s3 takes over only if one disconnects). `ANY 2 (s1, s2, s3)` is quorum-based: waits for any 2. With either, if only 1 is healthy, commits hang. Provision at least N+1 standbys: need 2 confirmations → provision 3. PostgreSQL never commits unless required standbys confirm — no inconsistency, but clients may timeout.
+
+## Failover
+
+`pg_ctl promote` or `SELECT pg_promote()` (SQL function, PG 12+) converts standby to primary. One-way: promoted standby cannot rejoin as standby without rebuild. `pg_rewind` can resync old primary to new primary (requires `wal_log_hints=on` or data checksums) — faster than full rebuild. After promotion: update connection strings, rebuild old primary as standby, reconfigure other standbys.
+
+## Monitoring
+
+On the primary, query `pg_stat_replication` for each connected standby's `state` (`streaming` = healthy, `catchup` = behind), `sync_state` (`sync`/`async`), and LSN positions (`sent_lsn`, `write_lsn`, `flush_lsn`, `replay_lsn`) to compute lag. On standbys, `pg_stat_wal_receiver` shows the receiver process status and `flushed_lsn`; compare `pg_last_wal_receive_lsn()` vs `pg_last_wal_replay_lsn()` for local replay lag.
+
+Replication lag (MB): `SELECT application_name, pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn)/1024/1024 AS lag_mb FROM pg_stat_replication;`
+
+Enable `wal_compression` (`pglz`, `lz4`, or `zstd`) to compress full page images in WAL (not all WAL data) — reduces WAL size for bandwidth-limited replication.
@@ -0,0 +1,66 @@
+---
+title: PostgreSQL Schema Design
+description: Schema design guide
+tags: postgres, schema, primary-keys, data-types, foreign-keys, naming
+---
+
+# Schema Design
+
+## Primary Keys
+
+Prefer `BIGINT GENERATED ALWAYS AS IDENTITY`. Avoid random UUIDs (UUIDv4) as primary keys; use `uuidv7()` when you need UUIDs.
+
+```sql
+CREATE TABLE user (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE
+);
+```
+
+Random UUID PKs (v4) can cause index fragmentation; UUIDs are also larger (16 vs 8 bytes for BIGINT) and can slow joins.
+
+## Data Types
+
+| Use | Avoid |
+| --- | --- |
+| `TEXT`, `VARCHAR` | Extension-specific types |
+| `JSONB` | Custom ENUMs (use CHECK instead) |
+| `TIMESTAMPTZ` | `TIMESTAMP` without time zone |
+| `BIGINT`, `INTEGER` | Platform-specific types |
+
+Prefer CHECK constraints over ENUM types — they're easier to modify:
+
+```sql
+CREATE TABLE order (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  status TEXT NOT NULL CHECK (status IN ('pending', 'shipped', 'delivered'))
+);
+```
+
+## Foreign Keys
+
+- Always index FK columns (PostgreSQL does not auto-create these)
+- Avoid circular FK dependencies
+- Suggestion: use `ON DELETE CASCADE` or `ON DELETE SET NULL` explicitly
+
+```sql
+CREATE TABLE order (
+  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  customer_id BIGINT NOT NULL REFERENCES customer(id) ON DELETE CASCADE
+);
+CREATE INDEX order_customer_id_idx ON order (customer_id);
+```
+
+## Naming Conventions
+
+- Tables: singular snake_case (`user_account`, `order_item`)
+- Columns: singular snake_case (`created_at`, `user_id`)
+- Indexes: `{table}_{column}_idx`
+- Constraints: `{table}_{column}_{type}` (e.g., `order_status_check`)
+
+## General Guidelines
+
+- Add `NOT NULL` to as many columns as possible
+- Add `created_at TIMESTAMPTZ DEFAULT NOW()` to all tables
+- Use `BIGINT` for all IDs and foreign keys, even on small tables
+- Keep tables normalized; denormalize only for proven hot read paths
@@ -0,0 +1,41 @@
+---
+title: Storage Layout and Tablespaces
+description: PGDATA directory structure, TOAST, fillfactor, tablespaces, and disk management
+tags: postgres, storage, pgdata, toast, fillfactor, tablespaces, disk, operations
+---
+
+# Storage Layout and Tablespaces
+
+## PGDATA Structure
+
+- **base/** — database files (one subdirectory per database, named by OID)
+- **global/** — cluster-wide shared catalogs (pg_database, pg_authid, pg_tablespace)
+- **pg_wal/** — WAL files
+- **pg_xact/** — transaction commit status
+
+"Cluster" in PostgreSQL = single instance with one PGDATA, not an HA cluster. Each table/index = one or more files, split into 1GB segments. Tables have companion **_fsm** (free space map) and **_vm** (visibility map); indexes have **_fsm** only (no _vm), except hash indexes.
+
+## Visibility Map and Free Space Map
+
+- **_vm** tracks all-visible pages — VACUUM skips these
+- **_fsm** tracks free space per page — INSERT uses this to find pages with room
+- Both are small files but critical for performance
+
+## TOAST
+
+TOAST triggers when a **row** exceeds ~2KB. Large values are compressed and/or moved out-of-line to `pg_toast.pg_toast_<oid>` tables. **Strategies:** PLAIN (no TOAST), EXTENDED (compress+out-of-line, default for text/bytea), EXTERNAL (out-of-line, no compression — use for pre-compressed data), MAIN (compress, avoid out-of-line). TOAST tables bloat like regular tables — they need VACUUM. `SELECT *` fetches all TOAST columns; always SELECT only needed columns. Move large rarely-accessed columns to separate tables.
+
+## Fillfactor
+
+Controls how full pages are packed (default 100%). Lower fillfactor (70–80%) leaves room for HOT (Heap-Only Tuple) updates, which avoid index entries and reduce bloat on UPDATE-heavy tables. Keep 100% for insert-only or read-mostly tables. `ALTER TABLE t SET (fillfactor = 70);`
+
+## Tablespaces
+
+`pg_default` (base/), `pg_global` (global/) are built-in. Custom tablespaces: symbolic links in **pg_tblspc/** to other filesystem locations. Use for separating hot data (SSD) from archives (HDD). Moving tablespaces requires exclusive lock on affected tables.
+
+## Disk Monitoring
+
+- `pg_database_size('dbname')`, `pg_total_relation_size('tablename')`, `pg_relation_size('tablename')`
+- Monitor disk usage: >80% = at risk; >90% = critical (VACUUM may fail if disk capacity is insufficient)
+- Check inode usage (`df -i`) — can run out even with free space
+- `pg_wal/` suddenly large = check replication slots and archiving
@@ -0,0 +1,42 @@
+---
+title: WAL and Checkpoint Operations
+description: Write-ahead log internals, checkpoint tuning, durability guarantees, and WAL disk management
+tags: postgres, wal, checkpoints, durability, crash-recovery, fsync, operations
+---
+
+# WAL and Checkpoint Operations
+
+## WAL Fundamentals
+
+Write-Ahead Logging: logs changes to `pg_wal/` **before** modifying data files. WAL segments are 16MB (fixed at initdb). On COMMIT, PostgreSQL fsyncs WAL to disk and returns SUCCESS — data files are updated lazily. WAL records are written for all changes (including uncommitted transactions and rollbacks). **Never disable `fsync` in production** — power loss without fsync risks unrecoverable data loss.
+
+`wal_level`: `minimal` (crash recovery only), `replica` (default; replication + archiving), `logical` (logical replication).
+
+## Dirty Pages and Checkpoints
+
+A dirty page is modified in shared_buffers but not yet written to data files. A checkpoint flushes all dirty pages to disk and writes a checkpoint record to WAL; recovery only replays WAL since the last checkpoint.
+
+- `checkpoint_timeout` (default 5 min) and `max_wal_size` (default 1GB) — checkpoint on whichever triggers first.
+- `checkpoint_completion_target=0.9` spreads I/O over 90% of the interval; avoid spikes.
+- "Checkpoints are occurring too frequently" in logs → increase `max_wal_size`.
+- **Target: >90% of checkpoints should be time-based** (`num_timed` in `pg_stat_checkpointer`), not size-based (`num_requested`). If num_requested/(num_timed+num_requested) > 10%, tune `max_wal_size` up.
+
+## WAL Disk Management
+
+Replication slots prevent WAL deletion even when standbys are offline — they can fill disk. WAL archiving failures also block recycling. `max_wal_size` is a *soft* limit; WAL can grow beyond it under heavy load.
+
+WAL size: `SELECT count(*) AS files, pg_size_pretty(sum(size)) AS total FROM pg_ls_waldir();`
+
+Slot lag: `SELECT slot_name, pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) AS lag_bytes FROM pg_replication_slots;`
+
+## Checkpoint Monitoring
+
+PG17+ moved checkpoint stats from `pg_stat_bgwriter` to `pg_stat_checkpointer` and renamed columns.
+
+`SELECT num_timed, num_requested, write_time, sync_time, buffers_written FROM pg_stat_checkpointer;`
+
+Backend-direct writes (formerly `buffers_backend` in `pg_stat_bgwriter`) are now tracked in `pg_stat_io`: `SELECT writes FROM pg_stat_io WHERE backend_type = 'client backend' AND object = 'relation';`
+
+## Crash Recovery
+
+On crash, PostgreSQL replays WAL from the last checkpoint. Longer checkpoint intervals → more WAL to replay → longer recovery. Trade-off: frequent checkpoints (faster recovery, more I/O) vs infrequent (less I/O, slower recovery). For most workloads, `checkpoint_timeout=5min` and `max_wal_size` tuned to keep checkpoints time-based is the right balance.
@@ -0,0 +1,136 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
@@ -0,0 +1,80 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
@@ -0,0 +1,51 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
@@ -0,0 +1,59 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct (imports only what you need):**
+
+```tsx
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+// Loads only 3 modules (~2KB vs ~1MB)
+
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+**Alternative (Next.js 13.5+):**
+
+```js
+// next.config.js - use optimizePackageImports
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+
+// Then you can keep the ergonomic barrel imports:
+import { Check, X, Menu } from 'lucide-react'
+// Automatically transformed to direct imports at build time
+```
+
+Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
@@ -0,0 +1,35 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, next-dynamic
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
@@ -0,0 +1,50 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example (preload on hover/focus):**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
@@ -0,0 +1,71 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
@@ -0,0 +1,107 @@
+---
+title: Avoid Layout Thrashing
+impact: MEDIUM
+impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
+tags: javascript, dom, css, performance, reflow, layout-thrashing
+---
+
+## Avoid Layout Thrashing
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK (browser batches style changes):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect (interleaved reads and writes force reflows):**
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct (batch reads, then writes):**
+```typescript
+function avoidThrashing(element: HTMLElement) {
+  // Read phase - all layout queries first
+  const rect1 = element.getBoundingClientRect()
+  const offsetWidth = element.offsetWidth
+  const offsetHeight = element.offsetHeight
+  
+  // Write phase - all style changes after
+  element.style.width = '100px'
+  element.style.height = '200px'
+}
+```
+
+**Better: use CSS classes**
+```css
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+```
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**React example:**
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
@@ -0,0 +1,37 @@
+---
+title: Build Index Maps for Repeated Lookups
+impact: LOW-MEDIUM
+impactDescription: 1M ops to 2K ops
+tags: javascript, map, indexing, optimization, performance
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+For 1000 orders × 1000 users: 1M ops → 2K ops.
@@ -0,0 +1,49 @@
+---
+title: Early Length Check for Array Comparisons
+impact: MEDIUM-HIGH
+impactDescription: avoids expensive operations when lengths differ
+tags: javascript, arrays, performance, optimization, comparison
+---
+
+## Early Length Check for Array Comparisons
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect (always runs expensive comparison):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+- It avoids mutating the original arrays
+- It returns early when a difference is found
@@ -0,0 +1,82 @@
+---
+title: Use Loop for Min/Max Instead of Sort
+impact: LOW
+impactDescription: O(n) instead of O(n log n)
+tags: javascript, arrays, performance, sorting, algorithms
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative (Math.min/Math.max for small arrays):**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
@@ -0,0 +1,24 @@
+---
+title: Use Set/Map for O(1) Lookups
+impact: LOW-MEDIUM
+impactDescription: O(n) to O(1)
+tags: javascript, set, map, data-structures, performance
+---
+
+## Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
@@ -0,0 +1,57 @@
+---
+title: Use toSorted() Instead of sort() for Immutability
+impact: MEDIUM-HIGH
+impactDescription: prevents mutation bugs in React state
+tags: javascript, arrays, immutability, react, state, mutation
+---
+
+## Use toSorted() Instead of sort() for Immutability
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect (mutates original array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct (creates new array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support (fallback for older browsers):**
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement
@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
@@ -0,0 +1,47 @@
+---
+title: Animate SVG Wrapper Instead of SVG Element
+impact: LOW
+impactDescription: enables hardware acceleration
+tags: rendering, svg, css, animation, performance
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
@@ -0,0 +1,30 @@
+---
+title: Suppress Expected Hydration Mismatches
+impact: LOW-MEDIUM
+impactDescription: avoids noisy hydration warnings for known differences
+tags: rendering, hydration, ssr, nextjs
+---
+
+## Suppress Expected Hydration Mismatches
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect (known mismatch warnings):**
+
+```tsx
+function Timestamp() {
+  return <span>{new Date().toLocaleString()}</span>
+}
+```
+
+**Correct (suppress expected mismatch only):**
+
+```tsx
+function Timestamp() {
+  return (
+    <span suppressHydrationWarning>
+      {new Date().toLocaleString()}
+    </span>
+  )
+}
+```
@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct (1 decimal place):**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
@@ -0,0 +1,75 @@
+---
+title: Use useTransition Over Manual Loading States
+impact: LOW
+impactDescription: reduces re-renders and improves code clarity
+tags: rendering, transitions, useTransition, loading, state
+---
+
+## Use useTransition Over Manual Loading States
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect (manual loading state):**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct (useTransition with built-in pending state):**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+- **Error resilience**: Pending state correctly resets even if the transition throws
+- **Better responsiveness**: Keeps the UI responsive during updates
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [useTransition](https://react.dev/reference/react/useTransition)
@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
@@ -0,0 +1,40 @@
+---
+title: Calculate Derived State During Rendering
+impact: MEDIUM
+impactDescription: avoids redundant renders and state drift
+tags: rerender, derived-state, useEffect, state
+---
+
+## Calculate Derived State During Rendering
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect (redundant state and effect):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const [fullName, setFullName] = useState('')
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName)
+  }, [firstName, lastName])
+
+  return <p>{fullName}</p>
+}
+```
+
+**Correct (derive during render):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const fullName = firstName + ' ' + lastName
+
+  return <p>{fullName}</p>
+}
+```
+
+References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
@@ -0,0 +1,38 @@
+---
+
+title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+impact: MEDIUM
+impactDescription: restores memoization by using a constant for default value
+tags: rerender, memo, optimization
+
+---
+
+## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect (`onClick` has different values on every rerender):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct (stable default value):**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
@@ -0,0 +1,45 @@
+---
+title: Put Interaction Logic in Event Handlers
+impact: MEDIUM
+impactDescription: avoids effect re-runs and duplicate side effects
+tags: rerender, useEffect, events, side-effects, dependencies
+---
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false)
+  const theme = useContext(ThemeContext)
+
+  useEffect(() => {
+    if (submitted) {
+      post('/api/register')
+      showToast('Registered', theme)
+    }
+  }, [submitted, theme])
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext)
+
+  function handleSubmit() {
+    post('/api/register')
+    showToast('Registered', theme)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
@@ -0,0 +1,35 @@
+---
+title: Do not wrap a simple expression with a primitive result type in useMemo
+impact: LOW-MEDIUM
+impactDescription: wasted computation on every render
+tags: rerender, useMemo, optimization
+---
+
+## Do not wrap a simple expression with a primitive result type in useMemo
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
@@ -0,0 +1,73 @@
+---
+title: Use useRef for Transient Values
+impact: MEDIUM
+impactDescription: avoids unnecessary re-renders on frequent updates
+tags: rerender, useref, state, performance
+---
+
+## Use useRef for Transient Values
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect (renders every update):**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX)
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: 'black',
+      }}
+    />
+  )
+}
+```
+
+**Correct (no re-render for tracking):**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0)
+  const dotRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX
+      const node = dotRef.current
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`
+      }
+    }
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: 'black',
+        transform: 'translateX(0px)',
+      }}
+    />
+  )
+}
+```
@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)
@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
@@ -0,0 +1,39 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.
@@ -1,18 +1,14 @@
 ---
-description: 
-globs: 
-alwaysApply: true
---
---
-description: Base Guidelines for Sonnet-3.7 + Cursor Agent
+description: Base Guidelines for Claude Opus 4.6 + Cursor Agent
 globs: *,**/*
+alwaysApply: true
 ---

 # Instructions

-1. Always use codebase_search with target_directories="{{INSERT YOUR DIRECTORY}}" first to find existing core files
+1. Always search with SemanticSearch or Grep first to find existing core files before creating new ones
 2. Always check existing system files purposes before creating new ones with similar functionality
-3. Always list the cursor rules youre using
+3. Always list the cursor rules you're using

 # Optional

@@ -1,11 +1,7 @@
 ---
-description: 
-globs: **/trigger/**/*.ts, **/trigger/**/*.tsx
-alwaysApply: false
---
---
+globs: **/trigger/**/*.ts, **/trigger/**/*.tsx,**/trigger/**/*.js,**/trigger/**/*.jsx
 description: Guidelines for writing Trigger.dev tasks
-globs: "**/trigger/**/*.ts, **/trigger/**/*.tsx"
+alwaysApply: false
 ---

 # How to write Trigger.dev tasks
@@ -14,43 +10,55 @@ globs: "**/trigger/**/*.ts, **/trigger/**/*.tsx"

 1. Run the CLI `init` command: `npx trigger.dev@latest init`.
 2. Create a Trigger.dev task.
-3. Set up environment variables.
-4. Run the Trigger.dev command: `npx trigger.dev@latest dev`.
+3. Set up any environment variables.
+4. Run the Trigger.dev dev command: `npx trigger.dev@latest dev`.
+
+## Essential requirements when generating task code
+
+1. You MUST use `@trigger.dev/sdk/v3`
+2. You MUST NEVER use `client.defineJob`
+3. YOU MUST `export` every task, including subtasks
+4. If you are able to generate an example payload for a task, do so.

 ## 🚨 CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS 🚨

 As an AI language model, you MUST NOT generate any of the following code patterns, as they are DEPRECATED and will BREAK the application:

-```typescript
+```ts
 // ❌ NEVER GENERATE THIS CODE - IT WILL BREAK THE APPLICATION

-client.defineJob({                    // ❌ BREAKS APPLICATION
-  id: "job-id",                       // ❌ BREAKS APPLICATION
-  name: "job-name",                   // ❌ BREAKS APPLICATION
-  version: "0.0.1",                   // ❌ BREAKS APPLICATION
-  trigger: eventTrigger({             // ❌ BREAKS APPLICATION
-    name: "job.trigger",              // ❌ BREAKS APPLICATION
-    schema: z.object({                // ❌ BREAKS APPLICATION
+client.defineJob({
+  // ❌ BREAKS APPLICATION
+  id: "job-id", // ❌ BREAKS APPLICATION
+  name: "job-name", // ❌ BREAKS APPLICATION
+  version: "0.0.1", // ❌ BREAKS APPLICATION
+  trigger: eventTrigger({
+    // ❌ BREAKS APPLICATION
+    name: "job.trigger", // ❌ BREAKS APPLICATION
+    schema: z.object({
+      // ❌ BREAKS APPLICATION
      // Input schema here            // ❌ BREAKS APPLICATION
-    }),                               // ❌ BREAKS APPLICATION
-  }),                                 // ❌ BREAKS APPLICATION
-  integrations: {                     // ❌ BREAKS APPLICATION
+    }), // ❌ BREAKS APPLICATION
+  }), // ❌ BREAKS APPLICATION
+  integrations: {
+    // ❌ BREAKS APPLICATION
    // Integrations here              // ❌ BREAKS APPLICATION
-  },                                  // ❌ BREAKS APPLICATION
-  run: async (payload, io) => {       // ❌ BREAKS APPLICATION
-    // Job logic goes here            // ❌ BREAKS APPLICATION                               
-    return {                          // ❌ BREAKS APPLICATION
+  }, // ❌ BREAKS APPLICATION
+  run: async (payload, io) => {
+    // ❌ BREAKS APPLICATION
+    // Job logic goes here            // ❌ BREAKS APPLICATION
+    return {
+      // ❌ BREAKS APPLICATION
      // Return job results           // ❌ BREAKS APPLICATION
-    };                                // ❌ BREAKS APPLICATION
-  },                                  // ❌ BREAKS APPLICATION
+    }; // ❌ BREAKS APPLICATION
+  }, // ❌ BREAKS APPLICATION
 });
 ```

 Instead, you MUST ALWAYS generate ONLY this pattern:

-```typescript
+```ts
 // ✅ ALWAYS GENERATE THIS EXACT PATTERN
-
 import { task } from "@trigger.dev/sdk/v3";

 //1. You need to export each task, even if it's a subtask
@@ -64,18 +72,11 @@ export const helloWorld = task({
 });
 ```

-## ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
-
-1. You MUST use `@trigger.dev/sdk/v3`
-2. You MUST NEVER use `client.defineJob`
-3. YOU MUST `export` every task, including subtasks
-4. If you are able to generate an example payload for a task, do so.
-
 ## Correct Task implementations

 A task is a function that can run for a long time with resilience to failure:

-```typescript
+```ts
 import { task } from "@trigger.dev/sdk/v3";

 export const helloWorld = task({
@@ -87,6 +88,7 @@ export const helloWorld = task({
 ```

 Key points:
+
 - Tasks must be exported, even subtasks in the same file
 - Each task needs a unique ID within your project
 - The `run` function contains your task logic
@@ -97,7 +99,7 @@ Key points:

 Control retry behavior when errors occur:

-```typescript
+```ts
 export const taskWithRetries = task({
  id: "task-with-retries",
  retry: {
@@ -117,7 +119,7 @@ export const taskWithRetries = task({

 Control concurrency:

-```typescript
+```ts
 export const oneAtATime = task({
  id: "one-at-a-time",
  queue: {
@@ -133,7 +135,7 @@ export const oneAtATime = task({

 Specify CPU/RAM requirements:

-```typescript
+```ts
 export const heavyTask = task({
  id: "heavy-task",
  machine: {
@@ -147,21 +149,21 @@ export const heavyTask = task({

 Machine configuration options:

-| Machine name        | vCPU | Memory | Disk space |
-| ------------------- | ---- | ------ | ---------- |
-| micro               | 0.25 | 0.25   | 10GB       |
-| small-1x (default)  | 0.5  | 0.5    | 10GB       |
-| small-2x            | 1    | 1      | 10GB       |
-| medium-1x           | 1    | 2      | 10GB       |
-| medium-2x           | 2    | 4      | 10GB       |
-| large-1x            | 4    | 8      | 10GB       |
-| large-2x            | 8    | 16     | 10GB       |
+| Machine name       | vCPU | Memory | Disk space |
+| ------------------ | ---- | ------ | ---------- |
+| micro              | 0.25 | 0.25   | 10GB       |
+| small-1x (default) | 0.5  | 0.5    | 10GB       |
+| small-2x           | 1    | 1      | 10GB       |
+| medium-1x          | 1    | 2      | 10GB       |
+| medium-2x          | 2    | 4      | 10GB       |
+| large-1x           | 4    | 8      | 10GB       |
+| large-2x           | 8    | 16     | 10GB       |

 #### Max Duration

 Limit how long a task can run:

-```typescript
+```ts
 export const longTask = task({
  id: "long-task",
  maxDuration: 300, // 5 minutes
@@ -179,7 +181,7 @@ Tasks support several lifecycle hooks:

 Runs before each attempt, can return data for other functions:

-```typescript
+```ts
 export const taskWithInit = task({
  id: "task-with-init",
  init: async (payload, { ctx }) => {
@@ -195,7 +197,7 @@ export const taskWithInit = task({

 Runs after each attempt, regardless of success/failure:

-```typescript
+```ts
 export const taskWithCleanup = task({
  id: "task-with-cleanup",
  cleanup: async (payload, { ctx }) => {
@@ -211,7 +213,7 @@ export const taskWithCleanup = task({

 Runs once when a task starts (not on retries):

-```typescript
+```ts
 export const taskWithOnStart = task({
  id: "task-with-on-start",
  onStart: async (payload, { ctx }) => {
@@ -227,7 +229,7 @@ export const taskWithOnStart = task({

 Runs when a task succeeds:

-```typescript
+```ts
 export const taskWithOnSuccess = task({
  id: "task-with-on-success",
  onSuccess: async (payload, output, { ctx }) => {
@@ -243,7 +245,7 @@ export const taskWithOnSuccess = task({

 Runs when a task fails after all retries:

-```typescript
+```ts
 export const taskWithOnFailure = task({
  id: "task-with-on-failure",
  onFailure: async (payload, error, { ctx }) => {
@@ -259,7 +261,7 @@ export const taskWithOnFailure = task({

 Controls error handling and retry behavior:

-```typescript
+```ts
 export const taskWithErrorHandling = task({
  id: "task-with-error-handling",
  handleError: async (error, { ctx }) => {
@@ -275,7 +277,7 @@ Global lifecycle hooks can also be defined in `trigger.config.ts` to apply to al

 ## Correct Schedules task (cron) implementations

-```typescript
+```ts
 import { schedules } from "@trigger.dev/sdk/v3";

 export const firstScheduledTask = schedules.task({
@@ -316,7 +318,7 @@ export const firstScheduledTask = schedules.task({

 ### Attach a Declarative schedule

-```typescript
+```ts
 import { schedules } from "@trigger.dev/sdk/v3";

 // Sepcify a cron pattern (UTC)
@@ -330,7 +332,7 @@ export const firstScheduledTask = schedules.task({
 });
 ```

-```typescript
+```ts
 import { schedules } from "@trigger.dev/sdk/v3";

 // Specify a specific timezone like this:
@@ -350,6 +352,7 @@ export const secondScheduledTask = schedules.task({
 Create schedules explicitly for tasks using the dashboard's "New schedule" button or the SDK.

 #### Benefits
+
 - Dynamic creation (e.g., one schedule per user)
 - Manage without code deployment:
  - Activate/disable
@@ -357,14 +360,16 @@ Create schedules explicitly for tasks using the dashboard's "New schedule" butto
  - Delete

 #### Implementation
-1.	Define a task using `⁠schedules.task()`
-2.	Attach one or more schedules via:
-  - Dashboard
-	- SDK
+
+1. Define a task using `⁠schedules.task()`
+2. Attach one or more schedules via:
+
+- Dashboard
+  - SDK

 #### Attach schedules with the SDK like this

-```typescript
+```ts
 const createdSchedule = await schedules.create({
  //The id of the scheduled task you want to attach to.
  task: firstScheduledTask.id,
@@ -379,7 +384,7 @@ const createdSchedule = await schedules.create({

 Schema tasks validate payloads against a schema before execution:

-```typescript
+```ts
 import { schemaTask } from "@trigger.dev/sdk/v3";
 import { z } from "zod";

@@ -404,7 +409,7 @@ When you trigger a task from your backend code, you need to set the `TRIGGER_SEC

 Triggers a single run of a task with specified payload and options without importing the task. Use type-only imports for full type checking.

-```typescript
+```ts
 import { tasks } from "@trigger.dev/sdk/v3";
 import type { emailSequence } from "~/trigger/emails";

@@ -422,7 +427,7 @@ export async function POST(request: Request) {

 Triggers multiple runs of a single task with different payloads without importing the task.

-```typescript
+```ts
 import { tasks } from "@trigger.dev/sdk/v3";
 import type { emailSequence } from "~/trigger/emails";

@@ -430,39 +435,17 @@ export async function POST(request: Request) {
  const data = await request.json();
  const batchHandle = await tasks.batchTrigger<typeof emailSequence>(
    "email-sequence",
-    data.users.map((u) => ({ payload: { to: u.email, name: u.name } }))
+    data.users.map((u) => ({ payload: { to: u.email, name: u.name } })),
  );
  return Response.json(batchHandle);
 }
 ```

-### tasks.triggerAndPoll()
-
-Triggers a task and polls until completion. Not recommended for web requests as it blocks until the run completes. Consider using Realtime docs for better alternatives.
-
-```typescript
-import { tasks } from "@trigger.dev/sdk/v3";
-import type { emailSequence } from "~/trigger/emails";
-
-export async function POST(request: Request) {
-  const data = await request.json();
-  const result = await tasks.triggerAndPoll<typeof emailSequence>(
-    "email-sequence",
-    {
-      to: data.email,
-      name: data.name,
-    },
-    { pollIntervalMs: 5000 }
-  );
-  return Response.json(result);
-}
-```
-
 ### batch.trigger()

 Triggers multiple runs of different tasks at once, useful when you need to execute multiple tasks simultaneously.

-```typescript
+```ts
 import { batch } from "@trigger.dev/sdk/v3";
 import type { myTask1, myTask2 } from "~/trigger/myTasks";

@@ -482,7 +465,7 @@ export async function POST(request: Request) {

 Triggers a single run of a task with specified payload and options.

-```typescript
+```ts
 import { myOtherTask, runs } from "~/trigger/my-other-task";

 export const myTask = task({
@@ -502,13 +485,15 @@ If you need to call `trigger()` on a task in a loop, use `batchTrigger()` instea

 Triggers multiple runs of a single task with different payloads.

-```typescript
-import { myOtherTask, batch } from "~/trigger/my-other-task";
+```ts
+import { batch, myOtherTask } from "~/trigger/my-other-task";

 export const myTask = task({
  id: "my-task",
  run: async (payload: string) => {
-    const batchHandle = await myOtherTask.batchTrigger([{ payload: "some data" }]);
+    const batchHandle = await myOtherTask.batchTrigger([
+      { payload: "some data" },
+    ]);

    //...do other stuff
    const batch = await batch.retrieve(batchHandle.id);
@@ -520,7 +505,7 @@ export const myTask = task({

 Triggers a task and waits for the result, useful when you need to call a different task and use its result.

-```typescript
+```ts
 export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
@@ -538,7 +523,7 @@ The result object needs to be checked to see if the child task run was successfu

 Batch triggers a task and waits for all results, useful for fan-out patterns.

-```typescript
+```ts
 export const batchParentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
@@ -560,11 +545,13 @@ You can handle run failures by inspecting individual run results and implementin

 Batch triggers multiple different tasks and waits for all results.

-```typescript
+```ts
 export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
-    const results = await batch.triggerAndWait<typeof childTask1 | typeof childTask2>([
+    const results = await batch.triggerAndWait<
+      typeof childTask1 | typeof childTask2
+    >([
      { id: "child-task-1", payload: { foo: "World" } },
      { id: "child-task-2", payload: { bar: 42 } },
    ]);
@@ -589,7 +576,7 @@ export const parentTask = task({

 Batch triggers multiple tasks by passing task instances, useful for static task sets.

-```typescript
+```ts
 export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
@@ -608,7 +595,7 @@ export const parentTask = task({

 Batch triggers multiple tasks by passing task instances and waits for all results.

-```typescript
+```ts
 export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
@@ -638,24 +625,24 @@ Metadata allows attaching up to 256KB of structured data to a run, which can be

 Add metadata when triggering a task:

-```typescript
+```ts
 const handle = await myTask.trigger(
  { message: "hello world" },
-  { metadata: { user: { name: "Eric", id: "user_1234" } } }
+  { metadata: { user: { name: "Eric", id: "user_1234" } } },
 );
 ```

 Access metadata inside a run:

-```typescript
-import { task, metadata } from "@trigger.dev/sdk/v3";
+```ts
+import { metadata, task } from "@trigger.dev/sdk/v3";

 export const myTask = task({
  id: "my-task",
  run: async (payload: { message: string }) => {
    // Get the whole metadata object
    const currentMetadata = metadata.current();
-    
+
    // Get a specific key
    const user = metadata.get("user");
    console.log(user.name); // "Eric"
@@ -679,8 +666,9 @@ Metadata can be updated as the run progresses:

 Updates can be chained with a fluent API:

-```typescript
-metadata.set("progress", 0.1)
+```ts
+metadata
+  .set("progress", 0.1)
  .append("logs", "Step 1 complete")
  .increment("progress", 0.4);
 ```
@@ -689,13 +677,13 @@ metadata.set("progress", 0.1)

 Child tasks can update parent task metadata:

-```typescript
+```ts
 export const childTask = task({
  id: "child-task",
  run: async (payload: { message: string }) => {
    // Update parent task's metadata
    metadata.parent.set("progress", 0.5);
-    
+
    // Update root task's metadata
    metadata.root.set("status", "processing");
  },
@@ -706,7 +694,7 @@ export const childTask = task({

 Metadata accepts any JSON-serializable object. For type safety, consider wrapping with Zod:

-```typescript
+```ts
 import { z } from "zod";

 const Metadata = z.object({
@@ -739,7 +727,7 @@ Trigger.dev Realtime enables subscribing to runs for real-time updates on run st

 Subscribe to a run after triggering a task:

-```typescript
+```ts
 import { runs, tasks } from "@trigger.dev/sdk/v3";

 async function myBackend() {
@@ -761,13 +749,14 @@ async function myBackend() {

 You can infer types of run's payload and output by passing the task type:

-```typescript
+```ts
 import { runs } from "@trigger.dev/sdk/v3";
+
 import type { myTask } from "./trigger/my-task";

 for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {
  console.log(run.payload.some); // Type-safe access to payload
-  
+
  if (run.output) {
    console.log(run.output.result); // Type-safe access to output
  }
@@ -778,8 +767,8 @@ for await (const run of runs.subscribeToRun<typeof myTask>(handle.id)) {

 Stream data in realtime from inside your tasks using the metadata system:

-```typescript
-import { task, metadata } from "@trigger.dev/sdk/v3";
+```ts
+import { metadata, task } from "@trigger.dev/sdk/v3";
 import OpenAI from "openai";

 export type STREAMS = {
@@ -810,8 +799,10 @@ export const myTask = task({

 Subscribe to streams using `withStreams`:

-```typescript
-for await (const part of runs.subscribeToRun<typeof myTask>(runId).withStreams<STREAMS>()) {
+```ts
+for await (const part of runs
+  .subscribeToRun<typeof myTask>(runId)
+  .withStreams<STREAMS>()) {
  switch (part.type) {
    case "run": {
      console.log("Received run", part.run);
@@ -837,7 +828,7 @@ npm add @trigger.dev/react-hooks

 All hooks require a Public Access Token. You can provide it directly to each hook:

-```typescriptx
+```ts
 import { useRealtimeRun } from "@trigger.dev/react-hooks";

 function MyComponent({ runId, publicAccessToken }) {
@@ -850,7 +841,7 @@ function MyComponent({ runId, publicAccessToken }) {

 Or use the `TriggerAuthContext` provider:

-```typescriptx
+```ts
 import { TriggerAuthContext } from "@trigger.dev/react-hooks";

 function SetupTrigger({ publicAccessToken }) {
@@ -864,7 +855,7 @@ function SetupTrigger({ publicAccessToken }) {

 For Next.js App Router, wrap the provider in a client component:

-```typescriptx
+```ts
 // components/TriggerProvider.tsx
 "use client";

@@ -884,7 +875,8 @@ export function TriggerProvider({ accessToken, children }) {
 Several approaches for Next.js App Router:

 1. **Using cookies**:
-```typescriptx
+
+```ts
 // Server action
 export async function startRun() {
  const handle = await tasks.trigger<typeof exampleTask>("example", { foo: "bar" });
@@ -904,16 +896,20 @@ export default function RunPage({ params }) {
 ```

 2. **Using query parameters**:
-```typescriptx
+
+```ts
 // Server action
 export async function startRun() {
-  const handle = await tasks.trigger<typeof exampleTask>("example", { foo: "bar" });
+  const handle = await tasks.trigger<typeof exampleTask>("example", {
+    foo: "bar",
+  });
  redirect(`/runs/${handle.id}?publicAccessToken=${handle.publicAccessToken}`);
 }
 ```

 3. **Server-side token generation**:
-```typescriptx
+
+```ts
 // Page component
 export default async function RunPage({ params }) {
  const publicAccessToken = await generatePublicAccessToken(params.id);
@@ -943,7 +939,7 @@ export async function generatePublicAccessToken(runId: string) {

 Data fetching hooks that use SWR for caching:

-```typescriptx
+```ts
 "use client";
 import { useRun } from "@trigger.dev/react-hooks";
 import type { myTask } from "@/trigger/myTask";
@@ -959,6 +955,7 @@ function MyComponent({ runId }) {
 ```

 Common options:
+
 - `revalidateOnFocus`: Revalidate when window regains focus
 - `revalidateOnReconnect`: Revalidate when network reconnects
 - `refreshInterval`: Polling interval in milliseconds
@@ -973,7 +970,7 @@ For most use cases, Realtime hooks are preferred over SWR hooks with polling due

 For client-side usage, generate a public access token with appropriate scopes:

-```typescript
+```ts
 import { auth } from "@trigger.dev/sdk/v3";

 const publicToken = await auth.createPublicToken({
@@ -993,7 +990,7 @@ Idempotency ensures that an operation produces the same result when called multi

 Provide an `idempotencyKey` when triggering a task to ensure it runs only once with that key:

-```typescript
+```ts
 import { idempotencyKeys, task } from "@trigger.dev/sdk/v3";

 export const myTask = task({
@@ -1018,20 +1015,22 @@ export const myTask = task({

 By default, keys are scoped to the current run. You can create globally unique keys:

-```typescript
-const idempotencyKey = await idempotencyKeys.create("my-task-key", { scope: "global" });
+```ts
+const idempotencyKey = await idempotencyKeys.create("my-task-key", {
+  scope: "global",
+});
 ```

 When triggering from backend code:

-```typescript
+```ts
 const idempotencyKey = await idempotencyKeys.create([myUser.id, "my-task"]);
 await tasks.trigger("my-task", { some: "data" }, { idempotencyKey });
 ```

 You can also pass a string directly:

-```typescript
+```ts
 await myTask.trigger({ some: "data" }, { idempotencyKey: myUser.id });
 ```

@@ -1039,10 +1038,10 @@ await myTask.trigger({ some: "data" }, { idempotencyKey: myUser.id });

 The `idempotencyKeyTTL` option defines a time window during which duplicate triggers return the original run:

-```typescript
+```ts
 await childTask.trigger(
-  { foo: "bar" }, 
-  { idempotencyKey, idempotencyKeyTTL: "60s" }
+  { foo: "bar" },
+  { idempotencyKey, idempotencyKeyTTL: "60s" },
 );

 await wait.for({ seconds: 61 });
@@ -1052,6 +1051,7 @@ await childTask.trigger({ foo: "bar" }, { idempotencyKey });
 ```

 Supported time units:
+
 - `s` for seconds (e.g., `60s`)
 - `m` for minutes (e.g., `5m`)
 - `h` for hours (e.g., `2h`)
@@ -1061,7 +1061,7 @@ Supported time units:

 While not directly supported, you can implement payload-based idempotency by hashing the payload:

-```typescript
+```ts
 import { createHash } from "node:crypto";

 const idempotencyKey = await idempotencyKeys.create(hash(payload));
@@ -1083,9 +1083,9 @@ function hash(payload: any): string {

 ## Correct Logs implementation

-```typescript
+```ts
 // onFailure executes after all retries are exhausted; use for notifications, logging, or side effects on final failure:
-import { task, logger } from "@trigger.dev/sdk/v3";
+import { logger, task } from "@trigger.dev/sdk/v3";

 export const loggingExample = task({
  id: "logging-example",
@@ -1100,11 +1100,11 @@ export const loggingExample = task({
 });
 ```

-## Correct `trigger.config.ts` implementation 
+## Correct `trigger.config.ts` implementation

 The `trigger.config.ts` file configures your Trigger.dev project, specifying task locations, retry settings, telemetry, and build options.

-```typescript
+```ts
 import { defineConfig } from "@trigger.dev/sdk/v3";

 export default defineConfig({
@@ -1129,7 +1129,7 @@ export default defineConfig({

 Specify where your tasks are located:

-```typescript
+```ts
 dirs: ["./trigger"],
 ```

@@ -1139,7 +1139,7 @@ Files with `.test` or `.spec` are automatically excluded, but you can customize

 Add global hooks for all tasks:

-```typescript
+```ts
 onStart: async (payload, { ctx }) => {
  console.log("Task started", ctx.task.id);
 },
@@ -1155,7 +1155,7 @@ onFailure: async (payload, error, { ctx }) => {

 Add OpenTelemetry instrumentations for enhanced logging:

-```typescript
+```ts
 telemetry: {
  instrumentations: [
    new PrismaInstrumentation(),
@@ -1169,7 +1169,7 @@ telemetry: {

 Specify the runtime environment:

-```typescript
+```ts
 runtime: "node", // or "bun" (experimental)
 ```

@@ -1177,7 +1177,7 @@ runtime: "node", // or "bun" (experimental)

 Set default machine for all tasks:

-```typescript
+```ts
 defaultMachine: "large-1x",
 ```

@@ -1185,7 +1185,7 @@ defaultMachine: "large-1x",

 Configure logging verbosity:

-```typescript
+```ts
 logLevel: "debug", // Controls logger API logs
 ```

@@ -1193,7 +1193,7 @@ logLevel: "debug", // Controls logger API logs

 Set default maximum runtime for all tasks:

-```typescript
+```ts
 maxDuration: 60, // 60 seconds
 ```

@@ -1201,7 +1201,7 @@ maxDuration: 60, // 60 seconds

 Customize the build process:

-```typescript
+```ts
 build: {
  external: ["header-generator"], // Don't bundle these packages
  jsx: {
@@ -1245,11 +1245,11 @@ You can also create custom build extensions with hooks like `onBuildStart`, `onB

 #### Trigger with:

-```typescript
+```ts
 await myTask.trigger({ name: "Alice", age: 30 });
 ```

-## AI MODEL VERIFICATION STEPS
+## AI model verification steps

 Before generating any code, you MUST verify:

@@ -1257,7 +1257,7 @@ Before generating any code, you MUST verify:
 2. Have you exported every task? If not, STOP and FIX.
 3. Have you generated any DEPRECATED code patterns? If yes, STOP and FIX.

-## CONSEQUENCES OF INCORRECT IMPLEMENTATION
+## Consequences of incorrect implementations

 If you generate code that fails the verification steps above, your implementation will:

@@ -1265,10 +1265,10 @@ If you generate code that fails the verification steps above, your implementatio
 2. Fail to deploy to the Trigger.dev servers
 3. Fail to run in a local Dev environment

-## AI MODEL RESPONSE TEMPLATE
+## AI model response template

 When asked about Trigger.dev task implementation, you MUST:
+
 1. FIRST use code patterns from this guide
 2. NEVER suggest deprecated approaches
 3. VERIFY your response against the patterns shown here
-4. If an answer cannot be found using this guide, look up further information ONLY from the official LLM-friendly version of the [Trigger.dev docs site](mdc:https:/trigger.dev/docs/llms.txt).
@@ -0,0 +1 @@
+../../.agents/skills/frontend-design
@@ -0,0 +1 @@
+../../.agents/skills/gh-cli
@@ -0,0 +1 @@
+../../.agents/skills/postgres
@@ -0,0 +1 @@
+../../.agents/skills/vercel-react-best-practices
@@ -0,0 +1 @@
+../../.agents/skills/web-design-guidelines
@@ -0,0 +1,13 @@
+node_modules
+**/node_modules
+**/.next
+.git
+.env*
+.vscode/
+.idea/
+coverage/
+*.test.ts
+*.spec.ts
+.DS_Store
+*.md
+docs/
@@ -12,9 +12,15 @@ POSTGRES_PRISMA_URL_NON_POOLING=
 # This variable is from Vercel Storage Blob
 BLOB_READ_WRITE_TOKEN=

-# Google client id and secret for authentication
-GOOGLE_CLIENT_ID=
-GOOGLE_CLIENT_SECRET=
+# Hanzo IAM OAuth (required for production)
+IAM_URL="https://hanzo.id"
+IAM_CLIENT_ID=""
+IAM_CLIENT_SECRET=""
+# IAM_PROVIDER_NAME="Hanzo"
+
+# Google client id and secret (deprecated — use Hanzo IAM above)
+# GOOGLE_CLIENT_ID=
+# GOOGLE_CLIENT_SECRET=

 # This variable is from Resend to send emails
 RESEND_API_KEY=
@@ -67,8 +73,25 @@ NEXT_PRIVATE_UPLOAD_DISTRIBUTION_KEY_CONTENTS=
 # Encryption key for document passwords. 
 NEXT_PRIVATE_DOCUMENT_PASSWORD_KEY=my-superstrong-document-secret

-# [[REDIS LOCKER CONFIGURATION]]
-# For bulk upload using tus.io, we use a Redis-based locker to prevent corruption of the data.
+# [[HANZO KV]] — OPTIONAL. Leave UNSET to run on the in-process backend
+# (single-replica correct: cache, rate-limit, tus upload locks, export/download
+# job stores and digest queues all work with no external datastore). SET it to
+# an external Hanzo KV instance for multi-replica HA (shared state across pods).
+# Accepts the Hanzo KV brand scheme kv:// (kvs:// for TLS) or a redis:// DSN.
+# A malformed value fails CLOSED (the app throws rather than silently degrade).
+#
+# Re-enabling multi-replica (replicas > 1) REQUIRES KV_URL. dataroom is
+# single-replica-by-construction otherwise: SQLite on a ReadWriteOnce volume plus
+# the in-process KV. Without KV_URL each pod owns its OWN map, so sessions,
+# rate-limit windows and tus upload locks split-brain across replicas — scaling
+# out needs a shared DB AND KV_URL set.
+#   KV_URL=kv://:password@hanzo-kv:6379
+KV_URL=
+
+# [[TUS UPLOAD LOCKER]] — for bulk upload via tus.io, an exclusive locker
+# prevents data corruption. It uses the Hanzo KV client above (KV_URL); with
+# KV_URL unset the lock is in-process (correct for a single replica). The legacy
+# Upstash REST locker below is unused and kept only for reference.
 UPSTASH_REDIS_REST_LOCKER_URL=
 UPSTASH_REDIS_REST_LOCKER_TOKEN=

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="640" viewBox="0 0 1280 640" role="img" aria-label="dataroom">
+<rect width="1280" height="640" fill="#0A0A0A"/>
+<svg x="96" y="215" width="210" height="210" viewBox="0 0 67 67"><path d="M22.21 67V44.6369H0V67H22.21Z" fill="#fff"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z" fill="#fff"/><path d="M22.21 0H0V22.3184H22.21V0Z" fill="#fff"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z" fill="#fff"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z" fill="#fff"/></svg>
+<text x="378" y="276" font-family="Inter,system-ui,-apple-system,sans-serif" font-size="78" font-weight="800" letter-spacing="-2" fill="#ffffff">dataroom</text>
+<text x="378" y="322" font-family="Inter,system-ui,sans-serif" font-size="30" fill="#ffffff" opacity=".66">Papermark is the open-source DocSend alternative with built-in…</text>
+<rect x="378" y="338" width="806" height="3" rx="1.5" fill="#ffffff" opacity=".9"/>
+<text x="378" y="390" font-family="Inter,system-ui,sans-serif" font-size="24" font-weight="600" fill="#ffffff" opacity=".5">github.com/hanzoai</text>
+<text x="1184" y="390" text-anchor="end" font-family="Inter,system-ui,sans-serif" font-size="24" font-weight="600" fill="#ffffff" opacity=".5">hanzo.ai</text>
+</svg>
@@ -13,7 +13,7 @@ permissions:

 jobs:
  CLAAssistant:
-    runs-on: ubuntu-latest
+    runs-on: hanzo-build-linux-amd64
    steps:
      - name: "CLA Assistant"
        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
@@ -25,10 +25,10 @@ jobs:
          # This token is required only if you have configured to store the signatures in a remote repository/organization
          PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
        with:
-          remote-organization-name: 'papermark'
+          remote-organization-name: 'hanzo-dataroom'
          remote-repository-name: 'cla-signatures'
          path-to-signatures: 'signatures/version1/cla.json'
-          path-to-document: 'https://github.com/mfts/papermark/blob/main/CLA.md'
+          path-to-document: 'https://github.com/hanzoai/dataroom/blob/main/CLA.md'
          # branch should not be protected
          branch: 'main'
          allowlist: cursoragent
@@ -0,0 +1,11 @@
+name: Docker
+# Native deploy pipeline is .hanzo/workflows/deploy.yml (Hanzo Git → act_runner →
+# BuildKit → ghcr.io/hanzoai/dataroom:<sha> → operator reconcile → hanzocd).
+# GitHub is a mirror; this workflow is retained only as a manual sync notice.
+on:
+  workflow_dispatch:
+jobs:
+  notice:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "native pipeline is .hanzo/workflows/deploy.yml; GitHub is a mirror"
@@ -0,0 +1,7 @@
+name: Workflow Sanity
+on:
+  pull_request:
+    paths: ['.github/workflows/**']
+jobs:
+  sanity:
+    uses: hanzoai/.github/.github/workflows/workflow-sanity.yml@main
@@ -60,5 +60,6 @@ lib/emails/marketing
 # trigger.dev
 .trigger

-# changelog
-changelog
+# changelog and docs
+changelog
+.docsvendor/
@@ -0,0 +1,24 @@
+name: deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: hanzo-linux-amd64
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build + push image
+        run: |
+          SHA="${GITHUB_SHA::8}"
+          buildctl-daemonless.sh build --frontend=dockerfile.v0 \
+            --opt context="${{ github.server_url }}/${{ github.repository }}.git#${GITHUB_SHA}" \
+            --opt filename=Dockerfile --opt platform=linux/amd64 \
+            --secret id=GIT_AUTH_TOKEN,env=GIT_AUTH_TOKEN \
+            --output "type=image,name=ghcr.io/hanzoai/dataroom:${SHA},push=true" --progress=plain
+        env:
+          GIT_AUTH_TOKEN: ${{ secrets.GIT_CLONE_TOKEN }}
+      - name: Deploy — declare tag to operator
+        run: |
+          for app in dataroom; do
+            kubectl -n hanzo patch app "$app" --type=merge -p "{\"spec\":{\"image\":{\"repository\":\"ghcr.io/hanzoai/dataroom\",\"tag\":\"${GITHUB_SHA::8}\"}}}"
+          done
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`../../.agents/skills/vercel-react-best-practices`