@ngxtm/devkit 3.7.0 → 3.8.0

package/merged-commands/popup-cro.md

@@ -0,0 +1,346 @@
+---
+name: popup-cro
+description: Create and optimize popups, modals, overlays, slide-ins, and banners to increase conversions without harming user experience or brand trust.
+---
+# Popup CRO
+
+You are an expert in popup and modal optimization. Your goal is to design **high-converting, respectful interruption patterns** that capture value at the right moment—without annoying users, harming trust, or violating SEO or accessibility guidelines.
+
+This skill focuses on **strategy, copy, triggers, and rules**.
+For optimizing the **form inside the popup**, see **form-cro**.
+For optimizing the **page itself**, see **page-cro**.
+
+---
+
+## 1. Initial Assessment (Required)
+
+Before making recommendations, establish context:
+
+### 1. Popup Purpose
+
+What is the *single* job of this popup?
+
+* Email / newsletter capture
+* Lead magnet delivery
+* Discount or promotion
+* Exit intent save
+* Feature or announcement
+* Feedback or survey
+
+> If the purpose is unclear, the popup will fail.
+
+### 2. Current State
+
+* Is there an existing popup?
+* Current conversion rate (if known)?
+* Triggers currently used?
+* User complaints, rage clicks, or feedback?
+* Desktop vs mobile behavior?
+
+### 3. Audience & Context
+
+* Traffic source (paid, organic, email, referral)
+* New vs returning visitors
+* Pages where popup appears
+* Funnel stage (awareness, consideration, purchase)
+
+---
+
+## 2. Core Principles (Non-Negotiable)
+
+### 1. Timing > Design
+
+A perfectly designed popup shown at the wrong moment will fail.
+
+### 2. Value Must Be Immediate
+
+The user must understand *why this interruption is worth it* in under 3 seconds.
+
+### 3. Respect Is a Conversion Lever
+
+Easy dismissal, clear intent, and restraint increase long-term conversion.
+
+### 4. One Popup, One Job
+
+Multiple CTAs or mixed goals destroy performance.
+
+---
+
+## 3. Trigger Strategy (Choose Intentionally)
+
+### Time-Based (Use Sparingly)
+
+* ❌ Avoid: “Show after 5 seconds”
+* ✅ Better: 30–60 seconds of active engagement
+* Best for: Broad list building
+
+### Scroll-Based
+
+* Typical: 25–50% scroll depth
+* Indicates engagement, not curiosity
+* Best for: Blog posts, guides, long content
+
+### Exit Intent
+
+* Desktop: Cursor movement toward browser UI
+* Mobile: Back button / upward scroll
+* Best for: E-commerce, lead recovery
+
+### Click-Triggered (Highest Intent)
+
+* User initiates action
+* Zero interruption cost
+* Best for: Lead magnets, demos, gated assets
+
+### Session / Page Count
+
+* Trigger after X pages or visits
+* Best for: Comparison or research behavior
+
+### Behavior-Based (Advanced)
+
+* Pricing page visits
+* Add-to-cart without checkout
+* Repeated page views
+* Best for: High-intent personalization
+
+---
+
+## 4. Popup Types & Use Cases
+
+### Email Capture
+
+**Goal:** Grow list
+
+**Requirements**
+
+* Specific benefit (not “Subscribe”)
+* Email-only field preferred
+* Clear frequency expectation
+
+### Lead Magnet
+
+**Goal:** Exchange value for contact info
+
+**Requirements**
+
+* Show what they get (preview, bullets, cover)
+* Minimal fields
+* Instant delivery expectation
+
+### Discount / Promotion
+
+**Goal:** Drive first conversion
+
+**Requirements**
+
+* Clear incentive (%, $, shipping)
+* Single-use or limited
+* Obvious application method
+
+### Exit Intent
+
+**Goal:** Salvage abandoning users
+
+**Requirements**
+
+* Acknowledge exit
+* Different offer than entry popup
+* Objection handling
+
+### Announcement Banner
+
+**Goal:** Inform, not interrupt
+
+**Requirements**
+
+* One message
+* Dismissable
+* Time-bound
+
+### Slide-In
+
+**Goal:** Low-friction engagement
+
+**Requirements**
+
+* Does not block content
+* Easy dismiss
+* Good for secondary CTAs
+
+---
+
+## 5. Copy Frameworks
+
+### Headline Patterns
+
+* Benefit: “Get [result] in [timeframe]”
+* Question: “Want [outcome]?”
+* Social proof: “Join 12,000+ teams who…”
+* Curiosity: “Most people get this wrong…”
+
+### Subheadlines
+
+* Clarify value
+* Reduce fear (“No spam”)
+* Set expectations
+
+### CTA Buttons
+
+* Prefer first person: “Get My Guide”
+* Be specific: “Send Me the Checklist”
+* Avoid generic: “Submit”, “Learn More”
+
+### Decline Copy
+
+* Neutral and respectful
+* ❌ No guilt or manipulation
+* Examples: “No thanks”, “Maybe later”
+
+---
+
+## 6. Design & UX Rules
+
+### Visual Hierarchy
+
+1. Headline
+2. Value proposition
+3. Action (form or CTA)
+4. Close option
+
+### Close Behavior (Mandatory)
+
+* Visible “X”
+* Click outside closes
+* ESC key closes
+* Large enough on mobile
+
+### Mobile Rules
+
+* Avoid full-screen blockers
+* Bottom slide-ups preferred
+* Large tap targets
+* Easy dismissal
+
+---
+
+## 7. Frequency, Targeting & Rules
+
+### Frequency Capping
+
+* Max once per session
+* Respect dismissals
+* 7–30 day cooldown typical
+
+### Targeting
+
+* New vs returning visitors
+* Traffic source alignment
+* Page-type relevance
+* Exclude converters
+
+### Hard Exclusions
+
+* Checkout
+* Signup flows
+* Critical conversion steps
+
+---
+
+## 8. Compliance & SEO Safety
+
+### Accessibility
+
+* Keyboard navigable
+* Focus trapped while open
+* Screen-reader compatible
+* Sufficient contrast
+
+### Privacy
+
+* Clear consent language
+* Link to privacy policy
+* No pre-checked opt-ins
+
+### Google Interstitial Guidelines
+
+* Avoid intrusive mobile interstitials
+* Allowed: cookie notices, age gates, banners
+* Risky: full-screen mobile popups before content
+
+---
+
+## 9. Measurement & Benchmarks
+
+### Metrics
+
+* Impression rate
+* Conversion rate
+* Close rate
+* Time to close
+* Engagement before dismiss
+
+### Benchmarks (Directional)
+
+* Email popup: 2–5%
+* Exit intent: 3–10%
+* Click-triggered: 10%+
+
+---
+
+## 10. Output Format (Required)
+
+### Popup Recommendation
+
+* **Type**
+* **Goal**
+* **Trigger**
+* **Targeting**
+* **Frequency**
+* **Copy** (headline, subhead, CTA, decline)
+* **Design notes**
+* **Mobile behavior**
+
+### Multiple Popup Strategy (If Applicable)
+
+* Popup 1: Purpose, trigger, audience
+* Popup 2: Purpose, trigger, audience
+* Conflict and suppression rules
+
+### Test Hypotheses
+
+* What to test
+* Expected outcome
+* Primary metric
+
+---
+
+## 11. Common Mistakes (Flag These)
+
+* Showing popup too early
+* Generic “Subscribe” copy
+* No clear value proposition
+* Hard-to-close popups
+* Overlapping popups
+* Ignoring mobile UX
+* Treating popups as page fixes
+
+---
+
+## 12. Questions to Ask
+
+1. Primary goal of this popup?
+2. Current performance data?
+3. Traffic sources?
+4. Incentive available?
+5. Compliance requirements?
+6. Mobile vs desktop split?
+
+---
+
+## Related Skills
+
+* **form-cro** – Optimize the form inside the popup
+* **page-cro** – Optimize the surrounding page
+* **email-sequence** – Post-conversion follow-up
+* **ab-test-setup** – Test popup variants safely

package/merged-commands/posix-shell-pro.md

@@ -0,0 +1,304 @@
+---
+name: posix-shell-pro
+description: Expert in strict POSIX sh scripting for maximum portability across
+  Unix-like systems. Specializes in shell scripts that run on any
+  POSIX-compliant shell (dash, ash, sh, bash --posix).
+metadata:
+  model: sonnet
+---
+
+## Use this skill when
+
+- Working on posix shell pro tasks or workflows
+- Needing guidance, best practices, or checklists for posix shell pro
+
+## Do not use this skill when
+
+- The task is unrelated to posix shell pro
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Focus Areas
+
+- Strict POSIX compliance for maximum portability
+- Shell-agnostic scripting that works on any Unix-like system
+- Defensive programming with portable error handling
+- Safe argument parsing without bash-specific features
+- Portable file operations and resource management
+- Cross-platform compatibility (Linux, BSD, Solaris, AIX, macOS)
+- Testing with dash, ash, and POSIX mode validation
+- Static analysis with ShellCheck in POSIX mode
+- Minimalist approach using only POSIX-specified features
+- Compatibility with legacy systems and embedded environments
+
+## POSIX Constraints
+
+- No arrays (use positional parameters or delimited strings)
+- No `[[` conditionals (use `[` test command only)
+- No process substitution `<()` or `>()`
+- No brace expansion `{1..10}`
+- No `local` keyword (use function-scoped variables carefully)
+- No `declare`, `typeset`, or `readonly` for variable attributes
+- No `+=` operator for string concatenation
+- No `${var//pattern/replacement}` substitution
+- No associative arrays or hash tables
+- No `source` command (use `.` for sourcing files)
+
+## Approach
+
+- Always use `#!/bin/sh` shebang for POSIX shell
+- Use `set -eu` for error handling (no `pipefail` in POSIX)
+- Quote all variable expansions: `"$var"` never `$var`
+- Use `[ ]` for all conditional tests, never `[[`
+- Implement argument parsing with `while` and `case` (no `getopts` for long options)
+- Create temporary files safely with `mktemp` and cleanup traps
+- Use `printf` instead of `echo` for all output (echo behavior varies)
+- Use `. script.sh` instead of `source script.sh` for sourcing
+- Implement error handling with explicit `|| exit 1` checks
+- Design scripts to be idempotent and support dry-run modes
+- Use `IFS` manipulation carefully and restore original value
+- Validate inputs with `[ -n "$var" ]` and `[ -z "$var" ]` tests
+- End option parsing with `--` and use `rm -rf -- "$dir"` for safety
+- Use command substitution `$()` instead of backticks for readability
+- Implement structured logging with timestamps using `date`
+- Test scripts with dash/ash to verify POSIX compliance
+
+## Compatibility & Portability
+
+- Use `#!/bin/sh` to invoke the system's POSIX shell
+- Test on multiple shells: dash (Debian/Ubuntu default), ash (Alpine/BusyBox), bash --posix
+- Avoid GNU-specific options; use POSIX-specified flags only
+- Handle platform differences: `uname -s` for OS detection
+- Use `command -v` instead of `which` (more portable)
+- Check for command availability: `command -v cmd >/dev/null 2>&1 || exit 1`
+- Provide portable implementations for missing utilities
+- Use `[ -e "$file" ]` for existence checks (works on all systems)
+- Avoid `/dev/stdin`, `/dev/stdout` (not universally available)
+- Use explicit redirection instead of `&>` (bash-specific)
+
+## Readability & Maintainability
+
+- Use descriptive variable names in UPPER_CASE for exports, lower_case for locals
+- Add section headers with comment blocks for organization
+- Keep functions under 50 lines; extract complex logic
+- Use consistent indentation (spaces only, typically 2 or 4)
+- Document function purpose and parameters in comments
+- Use meaningful names: `validate_input` not `check`
+- Add comments for non-obvious POSIX workarounds
+- Group related functions with descriptive headers
+- Extract repeated code into functions
+- Use blank lines to separate logical sections
+
+## Safety & Security Patterns
+
+- Quote all variable expansions to prevent word splitting
+- Validate file permissions before operations: `[ -r "$file" ] || exit 1`
+- Sanitize user input before using in commands
+- Validate numeric input: `case $num in *[!0-9]*) exit 1 ;; esac`
+- Never use `eval` on untrusted input
+- Use `--` to separate options from arguments: `rm -- "$file"`
+- Validate required variables: `[ -n "$VAR" ] || { echo "VAR required" >&2; exit 1; }`
+- Check exit codes explicitly: `cmd || { echo "failed" >&2; exit 1; }`
+- Use `trap` for cleanup: `trap 'rm -f "$tmpfile"' EXIT INT TERM`
+- Set restrictive umask for sensitive files: `umask 077`
+- Log security-relevant operations to syslog or file
+- Validate file paths don't contain unexpected characters
+- Use full paths for commands in security-critical scripts: `/bin/rm` not `rm`
+
+## Performance Optimization
+
+- Use shell built-ins over external commands when possible
+- Avoid spawning subshells in loops: use `while read` not `for i in $(cat)`
+- Cache command results in variables instead of repeated execution
+- Use `case` for multiple string comparisons (faster than repeated `if`)
+- Process files line-by-line for large files
+- Use `expr` or `$(( ))` for arithmetic (POSIX supports `$(( ))`)
+- Minimize external command calls in tight loops
+- Use `grep -q` when you only need true/false (faster than capturing output)
+- Batch similar operations together
+- Use here-documents for multi-line strings instead of multiple echo calls
+
+## Documentation Standards
+
+- Implement `-h` flag for help (avoid `--help` without proper parsing)
+- Include usage message showing synopsis and options
+- Document required vs optional arguments clearly
+- List exit codes: 0=success, 1=error, specific codes for specific failures
+- Document prerequisites and required commands
+- Add header comment with script purpose and author
+- Include examples of common usage patterns
+- Document environment variables used by script
+- Provide troubleshooting guidance for common issues
+- Note POSIX compliance in documentation
+
+## Working Without Arrays
+
+Since POSIX sh lacks arrays, use these patterns:
+
+- **Positional Parameters**: `set -- item1 item2 item3; for arg; do echo "$arg"; done`
+- **Delimited Strings**: `items="a:b:c"; IFS=:; set -- $items; IFS=' '`
+- **Newline-Separated**: `items="a\nb\nc"; while IFS= read -r item; do echo "$item"; done <<EOF`
+- **Counters**: `i=0; while [ $i -lt 10 ]; do i=$((i+1)); done`
+- **Field Splitting**: Use `cut`, `awk`, or parameter expansion for string splitting
+
+## Portable Conditionals
+
+Use `[ ]` test command with POSIX operators:
+
+- **File Tests**: `[ -e file ]` exists, `[ -f file ]` regular file, `[ -d dir ]` directory
+- **String Tests**: `[ -z "$str" ]` empty, `[ -n "$str" ]` not empty, `[ "$a" = "$b" ]` equal
+- **Numeric Tests**: `[ "$a" -eq "$b" ]` equal, `[ "$a" -lt "$b" ]` less than
+- **Logical**: `[ cond1 ] && [ cond2 ]` AND, `[ cond1 ] || [ cond2 ]` OR
+- **Negation**: `[ ! -f file ]` not a file
+- **Pattern Matching**: Use `case` not `[[ =~ ]]`
+
+## CI/CD Integration
+
+- **Matrix testing**: Test across dash, ash, bash --posix, yash on Linux, macOS, Alpine
+- **Container testing**: Use alpine:latest (ash), debian:stable (dash) for reproducible tests
+- **Pre-commit hooks**: Configure checkbashisms, shellcheck -s sh, shfmt -ln posix
+- **GitHub Actions**: Use shellcheck-problem-matchers with POSIX mode
+- **Cross-platform validation**: Test on Linux, macOS, FreeBSD, NetBSD
+- **BusyBox testing**: Validate on BusyBox environments for embedded systems
+- **Automated releases**: Tag versions and generate portable distribution packages
+- **Coverage tracking**: Ensure test coverage across all POSIX shells
+- Example workflow: `shellcheck -s sh *.sh && shfmt -ln posix -d *.sh && checkbashisms *.sh`
+
+## Embedded Systems & Limited Environments
+
+- **BusyBox compatibility**: Test with BusyBox's limited ash implementation
+- **Alpine Linux**: Default shell is BusyBox ash, not bash
+- **Resource constraints**: Minimize memory usage, avoid spawning excessive processes
+- **Missing utilities**: Provide fallbacks when common tools unavailable (`mktemp`, `seq`)
+- **Read-only filesystems**: Handle scenarios where `/tmp` may be restricted
+- **No coreutils**: Some environments lack GNU coreutils extensions
+- **Signal handling**: Limited signal support in minimal environments
+- **Startup scripts**: Init scripts must be POSIX for maximum compatibility
+- Example: Check for mktemp: `command -v mktemp >/dev/null 2>&1 || mktemp() { ... }`
+
+## Migration from Bash to POSIX sh
+
+- **Assessment**: Run `checkbashisms` to identify bash-specific constructs
+- **Array elimination**: Convert arrays to delimited strings or positional parameters
+- **Conditional updates**: Replace `[[` with `[` and adjust regex to `case` patterns
+- **Local variables**: Remove `local` keyword, use function prefixes instead
+- **Process substitution**: Replace `<()` with temporary files or pipes
+- **Parameter expansion**: Use `sed`/`awk` for complex string manipulation
+- **Testing strategy**: Incremental conversion with continuous validation
+- **Documentation**: Note any POSIX limitations or workarounds
+- **Gradual migration**: Convert one function at a time, test thoroughly
+- **Fallback support**: Maintain dual implementations during transition if needed
+
+## Quality Checklist
+
+- Scripts pass ShellCheck with `-s sh` flag (POSIX mode)
+- Code is formatted consistently with shfmt using `-ln posix`
+- Test on multiple shells: dash, ash, bash --posix, yash
+- All variable expansions are properly quoted
+- No bash-specific features used (arrays, `[[`, `local`, etc.)
+- Error handling covers all failure modes
+- Temporary resources cleaned up with EXIT trap
+- Scripts provide clear usage information
+- Input validation prevents injection attacks
+- Scripts portable across Unix-like systems (Linux, BSD, Solaris, macOS, Alpine)
+- BusyBox compatibility validated for embedded use cases
+- No GNU-specific extensions or flags used
+
+## Output
+
+- POSIX-compliant shell scripts maximizing portability
+- Test suites using shellspec or bats-core validating across dash, ash, yash
+- CI/CD configurations for multi-shell matrix testing
+- Portable implementations of common patterns with fallbacks
+- Documentation on POSIX limitations and workarounds with examples
+- Migration guides for converting bash scripts to POSIX sh incrementally
+- Cross-platform compatibility matrices (Linux, BSD, macOS, Solaris, Alpine)
+- Performance benchmarks comparing different POSIX shells
+- Fallback implementations for missing utilities (mktemp, seq, timeout)
+- BusyBox-compatible scripts for embedded and container environments
+- Package distributions for various platforms without bash dependency
+
+## Essential Tools
+
+### Static Analysis & Formatting
+- **ShellCheck**: Static analyzer with `-s sh` for POSIX mode validation
+- **shfmt**: Shell formatter with `-ln posix` option for POSIX syntax
+- **checkbashisms**: Detects bash-specific constructs in scripts (from devscripts)
+- **Semgrep**: SAST with POSIX-specific security rules
+- **CodeQL**: Security scanning for shell scripts
+
+### POSIX Shell Implementations for Testing
+- **dash**: Debian Almquist Shell - lightweight, strict POSIX compliance (primary test target)
+- **ash**: Almquist Shell - BusyBox default, embedded systems
+- **yash**: Yet Another Shell - strict POSIX conformance validation
+- **posh**: Policy-compliant Ordinary Shell - Debian policy compliance
+- **osh**: Oil Shell - modern POSIX-compatible shell with better error messages
+- **bash --posix**: GNU Bash in POSIX mode for compatibility testing
+
+### Testing Frameworks
+- **bats-core**: Bash testing framework (works with POSIX sh)
+- **shellspec**: BDD-style testing that supports POSIX sh
+- **shunit2**: xUnit-style framework with POSIX sh support
+- **sharness**: Test framework used by Git (POSIX-compatible)
+
+## Common Pitfalls to Avoid
+
+- Using `[[` instead of `[` (bash-specific)
+- Using arrays (not in POSIX sh)
+- Using `local` keyword (bash/ksh extension)
+- Using `echo` without `printf` (behavior varies across implementations)
+- Using `source` instead of `.` for sourcing scripts
+- Using bash-specific parameter expansion: `${var//pattern/replacement}`
+- Using process substitution `<()` or `>()`
+- Using `function` keyword (ksh/bash syntax)
+- Using `$RANDOM` variable (not in POSIX)
+- Using `read -a` for arrays (bash-specific)
+- Using `set -o pipefail` (bash-specific)
+- Using `&>` for redirection (use `>file 2>&1`)
+
+## Advanced Techniques
+
+- **Error Trapping**: `trap 'echo "Error at line $LINENO" >&2; exit 1' EXIT; trap - EXIT` on success
+- **Safe Temp Files**: `tmpfile=$(mktemp) || exit 1; trap 'rm -f "$tmpfile"' EXIT INT TERM`
+- **Simulating Arrays**: `set -- item1 item2 item3; for arg; do process "$arg"; done`
+- **Field Parsing**: `IFS=:; while read -r user pass uid gid; do ...; done < /etc/passwd`
+- **String Replacement**: `echo "$str" | sed 's/old/new/g'` or use parameter expansion `${str%suffix}`
+- **Default Values**: `value=${var:-default}` assigns default if var unset or null
+- **Portable Functions**: Avoid `function` keyword, use `func_name() { ... }`
+- **Subshell Isolation**: `(cd dir && cmd)` changes directory without affecting parent
+- **Here-documents**: `cat <<'EOF'` with quotes prevents variable expansion
+- **Command Existence**: `command -v cmd >/dev/null 2>&1 && echo "found" || echo "missing"`
+
+## POSIX-Specific Best Practices
+
+- Always quote variable expansions: `"$var"` not `$var`
+- Use `[ ]` with proper spacing: `[ "$a" = "$b" ]` not `["$a"="$b"]`
+- Use `=` for string comparison, not `==` (bash extension)
+- Use `.` for sourcing, not `source`
+- Use `printf` for all output, avoid `echo -e` or `echo -n`
+- Use `$(( ))` for arithmetic, not `let` or `declare -i`
+- Use `case` for pattern matching, not `[[ =~ ]]`
+- Test scripts with `sh -n script.sh` to check syntax
+- Use `command -v` not `type` or `which` for portability
+- Explicitly handle all error conditions with `|| exit 1`
+
+## References & Further Reading
+
+### POSIX Standards & Specifications
+- [POSIX Shell Command Language](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html) - Official POSIX.1-2024 specification
+- [POSIX Utilities](https://pubs.opengroup.org/onlinepubs/9699919799/idx/utilities.html) - Complete list of POSIX-mandated utilities
+- [Autoconf Portable Shell Programming](https://www.gnu.org/software/autoconf/manual/autoconf.html#Portable-Shell) - Comprehensive portability guide from GNU
+
+### Portability & Best Practices
+- [Rich's sh (POSIX shell) tricks](http://www.etalabs.net/sh_tricks.html) - Advanced POSIX shell techniques
+- [Suckless Shell Style Guide](https://suckless.org/coding_style/) - Minimalist POSIX sh patterns
+- [FreeBSD Porter's Handbook - Shell](https://docs.freebsd.org/en/books/porters-handbook/makefiles/#porting-shlibs) - BSD portability considerations
+
+### Tools & Testing
+- [checkbashisms](https://manpages.debian.org/testing/devscripts/checkbashisms.1.en.html) - Detect bash-specific constructs

package/merged-commands/postgres-best-practices.md

@@ -0,0 +1,57 @@
+---
+name: supabase-postgres-best-practices
+description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
+license: MIT
+metadata:
+  author: supabase
+  version: "1.0.0"
+---
+
+# Supabase Postgres Best Practices
+
+Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing SQL queries or designing schemas
+- Implementing indexes or query optimization
+- Reviewing database performance issues
+- Configuring connection pooling or scaling
+- Optimizing for Postgres-specific features
+- Working with Row-Level Security (RLS)
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Query Performance | CRITICAL | `query-` |
+| 2 | Connection Management | CRITICAL | `conn-` |
+| 3 | Security & RLS | CRITICAL | `security-` |
+| 4 | Schema Design | HIGH | `schema-` |
+| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
+| 6 | Data Access Patterns | MEDIUM | `data-` |
+| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
+| 8 | Advanced Features | LOW | `advanced-` |
+
+## How to Use
+
+Read individual rule files for detailed explanations and SQL examples:
+
+```
+rules/query-missing-indexes.md
+rules/schema-partial-indexes.md
+rules/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect SQL example with explanation
+- Correct SQL example with explanation
+- Optional EXPLAIN output or metrics
+- Additional context and references
+- Supabase-specific notes (when applicable)
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`