@ruaruababa/vibe-kit 1.0.0

package/skills/php-pro/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: php-pro
+description: Write idiomatic PHP code with generators, iterators, SPL data
+  structures, and modern OOP features. Use PROACTIVELY for high-performance PHP
+  applications.
+metadata:
+  model: inherit
+---
+
+## Use this skill when
+
+- Working on php pro tasks or workflows
+- Needing guidance, best practices, or checklists for php pro
+
+## Do not use this skill when
+
+- The task is unrelated to php 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`.
+
+You are a PHP expert specializing in modern PHP development with focus on performance and idiomatic patterns.
+
+## Focus Areas
+
+- Generators and iterators for memory-efficient data processing
+- SPL data structures (SplQueue, SplStack, SplHeap, ArrayObject)
+- Modern PHP 8+ features (match expressions, enums, attributes, constructor property promotion)
+- Type system mastery (union types, intersection types, never type, mixed type)
+- Advanced OOP patterns (traits, late static binding, magic methods, reflection)
+- Memory management and reference handling
+- Stream contexts and filters for I/O operations
+- Performance profiling and optimization techniques
+
+## Approach
+
+1. Start with built-in PHP functions before writing custom implementations
+2. Use generators for large datasets to minimize memory footprint
+3. Apply strict typing and leverage type inference
+4. Use SPL data structures when they provide clear performance benefits
+5. Profile performance bottlenecks before optimizing
+6. Handle errors with exceptions and proper error levels
+7. Write self-documenting code with meaningful names
+8. Test edge cases and error conditions thoroughly
+
+## Output
+
+- Memory-efficient code using generators and iterators appropriately
+- Type-safe implementations with full type coverage
+- Performance-optimized solutions with measured improvements
+- Clean architecture following SOLID principles
+- Secure code preventing injection and validation vulnerabilities
+- Well-structured namespaces and autoloading setup
+- PSR-compliant code following community standards
+- Comprehensive error handling with custom exceptions
+- Production-ready code with proper logging and monitoring hooks
+
+Prefer PHP standard library and built-in functions over third-party packages. Use external dependencies sparingly and only when necessary. Focus on working code over explanations.

package/skills/posix-shell-pro/SKILL.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/skills/postgresql/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: postgresql
+description: Design a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features
+---
+
+# PostgreSQL Table Design 
+
+## Use this skill when
+
+- Designing a schema for PostgreSQL
+- Selecting data types and constraints
+- Planning indexes, partitions, or RLS policies
+- Reviewing tables for scale and maintainability
+
+## Do not use this skill when
+
+- You are targeting a non-PostgreSQL database
+- You only need query tuning without schema changes
+- You require a DB-agnostic modeling guide
+
+## Instructions
+
+1. Capture entities, access patterns, and scale targets (rows, QPS, retention).
+2. Choose data types and constraints that enforce invariants.
+3. Add indexes for real query paths and validate with `EXPLAIN`.
+4. Plan partitioning or RLS where required by scale or access control.
+5. Review migration impact and apply changes safely.
+
+## Safety
+
+- Avoid destructive DDL on production without backups and a rollback plan.
+- Use migrations and staging validation before applying schema changes.
+
+## Core Rules
+
+- Define a **PRIMARY KEY** for reference tables (users, orders, etc.). Not always needed for time-series/event/log data. When used, prefer `BIGINT GENERATED ALWAYS AS IDENTITY`; use `UUID` only when global uniqueness/opacity is needed.
+- **Normalize first (to 3NF)** to eliminate data redundancy and update anomalies; denormalize **only** for measured, high-ROI reads where join performance is proven problematic. Premature denormalization creates maintenance burden.
+- Add **NOT NULL** everywhere it’s semantically required; use **DEFAULT**s for common values.
+- Create **indexes for access paths you actually query**: PK/unique (auto), **FK columns (manual!)**, frequent filters/sorts, and join keys.
+- Prefer **TIMESTAMPTZ** for event time; **NUMERIC** for money; **TEXT** for strings; **BIGINT** for integer values, **DOUBLE PRECISION** for floats (or `NUMERIC` for exact decimal arithmetic).
+
+## PostgreSQL “Gotchas”
+
+- **Identifiers**: unquoted → lowercased. Avoid quoted/mixed-case names. Convention: use `snake_case` for table/column names.
+- **Unique + NULLs**: UNIQUE allows multiple NULLs. Use `UNIQUE (...) NULLS NOT DISTINCT` (PG15+) to restrict to one NULL.
+- **FK indexes**: PostgreSQL **does not** auto-index FK columns. Add them.
+- **No silent coercions**: length/precision overflows error out (no truncation). Example: inserting 999 into `NUMERIC(2,0)` fails with error, unlike some databases that silently truncate or round.
+- **Sequences/identity have gaps** (normal; don't "fix"). Rollbacks, crashes, and concurrent transactions create gaps in ID sequences (1, 2, 5, 6...). This is expected behavior—don't try to make IDs consecutive.
+- **Heap storage**: no clustered PK by default (unlike SQL Server/MySQL InnoDB); `CLUSTER` is one-off reorganization, not maintained on subsequent inserts. Row order on disk is insertion order unless explicitly clustered.
+- **MVCC**: updates/deletes leave dead tuples; vacuum handles them—design to avoid hot wide-row churn.
+
+## Data Types
+
+- **IDs**: `BIGINT GENERATED ALWAYS AS IDENTITY` preferred (`GENERATED BY DEFAULT` also fine); `UUID` when merging/federating/used in a distributed system or for opaque IDs. Generate with `uuidv7()` (preferred if using PG18+) or `gen_random_uuid()` (if using an older PG version).
+- **Integers**: prefer `BIGINT` unless storage space is critical; `INTEGER` for smaller ranges; avoid `SMALLINT` unless constrained.
+- **Floats**: prefer `DOUBLE PRECISION` over `REAL` unless storage space is critical. Use `NUMERIC` for exact decimal arithmetic.
+- **Strings**: prefer `TEXT`; if length limits needed, use `CHECK (LENGTH(col) <= n)` instead of `VARCHAR(n)`; avoid `CHAR(n)`. Use `BYTEA` for binary data. Large strings/binary (>2KB default threshold) automatically stored in TOAST with compression. TOAST storage: `PLAIN` (no TOAST), `EXTENDED` (compress + out-of-line), `EXTERNAL` (out-of-line, no compress), `MAIN` (compress, keep in-line if possible). Default `EXTENDED` usually optimal. Control with `ALTER TABLE tbl ALTER COLUMN col SET STORAGE strategy` and `ALTER TABLE tbl SET (toast_tuple_target = 4096)` for threshold. Case-insensitive: for locale/accent handling use non-deterministic collations; for plain ASCII use expression indexes on `LOWER(col)` (preferred unless column needs case-insensitive PK/FK/UNIQUE) or `CITEXT`.
+- **Money**: `NUMERIC(p,s)` (never float).
+- **Time**: `TIMESTAMPTZ` for timestamps; `DATE` for date-only; `INTERVAL` for durations. Avoid `TIMESTAMP` (without timezone). Use `now()` for transaction start time, `clock_timestamp()` for current wall-clock time.
+- **Booleans**: `BOOLEAN` with `NOT NULL` constraint unless tri-state values are required.
+- **Enums**: `CREATE TYPE ... AS ENUM` for small, stable sets (e.g. US states, days of week). For business-logic-driven and evolving values (e.g. order statuses) → use TEXT (or INT) + CHECK or lookup table.
+- **Arrays**: `TEXT[]`, `INTEGER[]`, etc. Use for ordered lists where you query elements. Index with **GIN** for containment (`@>`, `<@`) and overlap (`&&`) queries. Access: `arr[1]` (1-indexed), `arr[1:3]` (slicing). Good for tags, categories; avoid for relations—use junction tables instead. Literal syntax: `'{val1,val2}'` or `ARRAY[val1,val2]`.
+- **Range types**: `daterange`, `numrange`, `tstzrange` for intervals. Support overlap (`&&`), containment (`@>`), operators. Index with **GiST**. Good for scheduling, versioning, numeric ranges. Pick a bounds scheme and use it consistently; prefer `[)` (inclusive/exclusive) by default.
+- **Network types**: `INET` for IP addresses, `CIDR` for network ranges, `MACADDR` for MAC addresses. Support network operators (`<<`, `>>`, `&&`).
+- **Geometric types**: `POINT`, `LINE`, `POLYGON`, `CIRCLE` for 2D spatial data. Index with **GiST**. Consider **PostGIS** for advanced spatial features.
+- **Text search**: `TSVECTOR` for full-text search documents, `TSQUERY` for search queries. Index `tsvector` with **GIN**. Always specify language: `to_tsvector('english', col)` and `to_tsquery('english', 'query')`. Never use single-argument versions. This applies to both index expressions and queries.
+- **Domain types**: `CREATE DOMAIN email AS TEXT CHECK (VALUE ~ '^[^@]+@[^@]+$')` for reusable custom types with validation. Enforces constraints across tables.
+- **Composite types**: `CREATE TYPE address AS (street TEXT, city TEXT, zip TEXT)` for structured data within columns. Access with `(col).field` syntax.
+- **JSONB**: preferred over JSON; index with **GIN**. Use only for optional/semi-structured attrs. ONLY use JSON if the original ordering of the contents MUST be preserved.
+- **Vector types**: `vector` type by `pgvector` for vector similarity search for embeddings.
+
+
+### Do not use the following data types
+- DO NOT use `timestamp` (without time zone); DO use `timestamptz` instead.
+- DO NOT use `char(n)` or `varchar(n)`; DO use `text` instead.
+- DO NOT use `money` type; DO use `numeric` instead.
+- DO NOT use `timetz` type; DO use `timestamptz` instead.
+- DO NOT use `timestamptz(0)` or any other precision specification; DO use `timestamptz` instead
+- DO NOT use `serial` type; DO use `generated always as identity` instead.
+
+
+## Table Types
+
+- **Regular**: default; fully durable, logged.
+- **TEMPORARY**: session-scoped, auto-dropped, not logged. Faster for scratch work.
+- **UNLOGGED**: persistent but not crash-safe. Faster writes; good for caches/staging.
+
+## Row-Level Security
+
+Enable with `ALTER TABLE tbl ENABLE ROW LEVEL SECURITY`. Create policies: `CREATE POLICY user_access ON orders FOR SELECT TO app_users USING (user_id = current_user_id())`. Built-in user-based access control at the row level.
+
+## Constraints
+
+- **PK**: implicit UNIQUE + NOT NULL; creates a B-tree index.
+- **FK**: specify `ON DELETE/UPDATE` action (`CASCADE`, `RESTRICT`, `SET NULL`, `SET DEFAULT`). Add explicit index on referencing column—speeds up joins and prevents locking issues on parent deletes/updates. Use `DEFERRABLE INITIALLY DEFERRED` for circular FK dependencies checked at transaction end.
+- **UNIQUE**: creates a B-tree index; allows multiple NULLs unless `NULLS NOT DISTINCT` (PG15+). Standard behavior: `(1, NULL)` and `(1, NULL)` are allowed. With `NULLS NOT DISTINCT`: only one `(1, NULL)` allowed. Prefer `NULLS NOT DISTINCT` unless you specifically need duplicate NULLs.
+- **CHECK**: row-local constraints; NULL values pass the check (three-valued logic). Example: `CHECK (price > 0)` allows NULL prices. Combine with `NOT NULL` to enforce: `price NUMERIC NOT NULL CHECK (price > 0)`.
+- **EXCLUDE**: prevents overlapping values using operators. `EXCLUDE USING gist (room_id WITH =, booking_period WITH &&)` prevents double-booking rooms. Requires appropriate index type (often GiST).
+
+## Indexing
+
+- **B-tree**: default for equality/range queries (`=`, `<`, `>`, `BETWEEN`, `ORDER BY`)
+- **Composite**: order matters—index used if equality on leftmost prefix (`WHERE a = ? AND b > ?` uses index on `(a,b)`, but `WHERE b = ?` does not). Put most selective/frequently filtered columns first.
+- **Covering**: `CREATE INDEX ON tbl (id) INCLUDE (name, email)` - includes non-key columns for index-only scans without visiting table.
+- **Partial**: for hot subsets (`WHERE status = 'active'` → `CREATE INDEX ON tbl (user_id) WHERE status = 'active'`). Any query with `status = 'active'` can use this index.
+- **Expression**: for computed search keys (`CREATE INDEX ON tbl (LOWER(email))`). Expression must match exactly in WHERE clause: `WHERE LOWER(email) = 'user@example.com'`.
+- **GIN**: JSONB containment/existence, arrays (`@>`, `?`), full-text search (`@@`)
+- **GiST**: ranges, geometry, exclusion constraints
+- **BRIN**: very large, naturally ordered data (time-series)—minimal storage overhead. Effective when row order on disk correlates with indexed column (insertion order or after `CLUSTER`).
+
+## Partitioning
+
+- Use for very large tables (>100M rows) where queries consistently filter on partition key (often time/date).
+- Alternate use: use for tables where data maintenance tasks dictates e.g. data pruned or bulk replaced periodically
+- **RANGE**: common for time-series (`PARTITION BY RANGE (created_at)`). Create partitions: `CREATE TABLE logs_2024_01 PARTITION OF logs FOR VALUES FROM ('2024-01-01') TO ('2024-02-01')`. **TimescaleDB** automates time-based or ID-based partitioning with retention policies and compression.
+- **LIST**: for discrete values (`PARTITION BY LIST (region)`). Example: `FOR VALUES IN ('us-east', 'us-west')`.
+- **HASH**: for even distribution when no natural key (`PARTITION BY HASH (user_id)`). Creates N partitions with modulus.
+- **Constraint exclusion**: requires `CHECK` constraints on partitions for query planner to prune. Auto-created for declarative partitioning (PG10+).
+- Prefer declarative partitioning or hypertables. Do NOT use table inheritance.
+- **Limitations**: no global UNIQUE constraints—include partition key in PK/UNIQUE. FKs from partitioned tables not supported; use triggers.
+
+## Special Considerations
+
+### Update-Heavy Tables
+
+- **Separate hot/cold columns**—put frequently updated columns in separate table to minimize bloat.
+- **Use `fillfactor=90`** to leave space for HOT updates that avoid index maintenance.
+- **Avoid updating indexed columns**—prevents beneficial HOT updates.
+- **Partition by update patterns**—separate frequently updated rows in a different partition from stable data.
+
+### Insert-Heavy Workloads
+
+- **Minimize indexes**—only create what you query; every index slows inserts.
+- **Use `COPY` or multi-row `INSERT`** instead of single-row inserts.
+- **UNLOGGED tables** for rebuildable staging data—much faster writes.
+- **Defer index creation** for bulk loads—>drop index, load data, recreate indexes.
+- **Partition by time/hash** to distribute load. **TimescaleDB** automates partitioning and compression of insert-heavy data.
+- **Use a natural key for primary key** such as a (timestamp, device_id) if enforcing global uniqueness is important many insert-heavy tables don't need a primary key at all.
+- If you do need a surrogate key, **Prefer `BIGINT GENERATED ALWAYS AS IDENTITY` over `UUID`**.
+
+### Upsert-Friendly Design
+
+- **Requires UNIQUE index** on conflict target columns—`ON CONFLICT (col1, col2)` needs exact matching unique index (partial indexes don't work).
+- **Use `EXCLUDED.column`** to reference would-be-inserted values; only update columns that actually changed to reduce write overhead.
+- **`DO NOTHING` faster** than `DO UPDATE` when no actual update needed.
+
+### Safe Schema Evolution
+
+- **Transactional DDL**: most DDL operations can run in transactions and be rolled back—`BEGIN; ALTER TABLE...; ROLLBACK;` for safe testing.
+- **Concurrent index creation**: `CREATE INDEX CONCURRENTLY` avoids blocking writes but can't run in transactions.
+- **Volatile defaults cause rewrites**: adding `NOT NULL` columns with volatile defaults (e.g., `now()`, `gen_random_uuid()`) rewrites entire table. Non-volatile defaults are fast.
+- **Drop constraints before columns**: `ALTER TABLE DROP CONSTRAINT` then `DROP COLUMN` to avoid dependency issues.
+- **Function signature changes**: `CREATE OR REPLACE` with different arguments creates overloads, not replacements. DROP old version if no overload desired.
+
+## Generated Columns
+
+- `... GENERATED ALWAYS AS (<expr>) STORED` for computed, indexable fields. PG18+ adds `VIRTUAL` columns (computed on read, not stored).
+
+## Extensions
+
+- **`pgcrypto`**: `crypt()` for password hashing.
+- **`uuid-ossp`**: alternative UUID functions; prefer `pgcrypto` for new projects.
+- **`pg_trgm`**: fuzzy text search with `%` operator, `similarity()` function. Index with GIN for `LIKE '%pattern%'` acceleration.
+- **`citext`**: case-insensitive text type. Prefer expression indexes on `LOWER(col)` unless you need case-insensitive constraints.
+- **`btree_gin`/`btree_gist`**: enable mixed-type indexes (e.g., GIN index on both JSONB and text columns).
+- **`hstore`**: key-value pairs; mostly superseded by JSONB but useful for simple string mappings.
+- **`timescaledb`**: essential for time-series—automated partitioning, retention, compression, continuous aggregates.
+- **`postgis`**: comprehensive geospatial support beyond basic geometric types—essential for location-based applications.
+- **`pgvector`**: vector similarity search for embeddings.
+- **`pgaudit`**: audit logging for all database activity.
+
+## JSONB Guidance
+
+- Prefer `JSONB` with **GIN** index.
+- Default: `CREATE INDEX ON tbl USING GIN (jsonb_col);` → accelerates:
+  - **Containment** `jsonb_col @> '{"k":"v"}'`
+  - **Key existence** `jsonb_col ? 'k'`, **any/all keys** `?\|`, `?&`
+  - **Path containment** on nested docs
+  - **Disjunction** `jsonb_col @> ANY(ARRAY['{"status":"active"}', '{"status":"pending"}'])`
+- Heavy `@>` workloads: consider opclass `jsonb_path_ops` for smaller/faster containment-only indexes:
+  - `CREATE INDEX ON tbl USING GIN (jsonb_col jsonb_path_ops);`
+  - **Trade-off**: loses support for key existence (`?`, `?|`, `?&`) queries—only supports containment (`@>`)
+- Equality/range on a specific scalar field: extract and index with B-tree (generated column or expression):
+  - `ALTER TABLE tbl ADD COLUMN price INT GENERATED ALWAYS AS ((jsonb_col->>'price')::INT) STORED;`
+  - `CREATE INDEX ON tbl (price);`
+  - Prefer queries like `WHERE price BETWEEN 100 AND 500` (uses B-tree) over `WHERE (jsonb_col->>'price')::INT BETWEEN 100 AND 500` without index.
+- Arrays inside JSONB: use GIN + `@>` for containment (e.g., tags). Consider `jsonb_path_ops` if only doing containment.
+- Keep core relations in tables; use JSONB for optional/variable attributes.
+- Use constraints to limit allowed JSONB values in a column e.g. `config JSONB NOT NULL CHECK(jsonb_typeof(config) = 'object')`
+
+
+## Examples
+
+### Users
+
+```sql
+CREATE TABLE users (
+  user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  email TEXT NOT NULL UNIQUE,
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX ON users (LOWER(email));
+CREATE INDEX ON users (created_at);
+```
+
+### Orders
+
+```sql
+CREATE TABLE orders (
+  order_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+  user_id BIGINT NOT NULL REFERENCES users(user_id),
+  status TEXT NOT NULL DEFAULT 'PENDING' CHECK (status IN ('PENDING','PAID','CANCELED')),
+  total NUMERIC(10,2) NOT NULL CHECK (total > 0),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX ON orders (user_id);
+CREATE INDEX ON orders (created_at);
+```
+
+### JSONB
+
+```sql
+CREATE TABLE profiles (
+  user_id BIGINT PRIMARY KEY REFERENCES users(user_id),
+  attrs JSONB NOT NULL DEFAULT '{}',
+  theme TEXT GENERATED ALWAYS AS (attrs->>'theme') STORED
+);
+CREATE INDEX profiles_attrs_gin ON profiles USING GIN (attrs);
+```