chore: migrate repository to standard knowledge base layout

skills/postgresql/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: postgresql
+description: "PostgreSQL database skill: psql usage, schema design, SQL queries, DDL/DML, transactions, RETURNING, indexing, EXPLAIN, permissions, libpq connection basics, and performance troubleshooting."
+---
+
+# postgresql Skill
+
+Use this skill to design, query, debug, and operate PostgreSQL databases with evidence-based SQL and safe production habits.
+
+## When to Use This Skill
+
+Trigger when any of these applies:
+- Writing or reviewing PostgreSQL SQL, DDL, DML, indexes, views, transactions, or migrations.
+- Using `psql`, connection strings, `libpq`, or PostgreSQL client behavior.
+- Debugging slow queries, locking, permissions, schema/search path, connection failures, or data-modifying statements.
+- Designing normalized schema, constraints, keys, and query plans.
+- Explaining PostgreSQL-specific features such as `RETURNING`, CTEs, roles, or `EXPLAIN`.
+
+## Not For / Boundaries
+
+- Not for destructive production changes without backups, migration plan, and rollback path.
+- Do not expose database passwords, connection strings with secrets, dumps containing private data, or production credentials.
+- Prefer explicit transactions and small verified changes for DDL/DML that touches real data.
+- Required inputs: PostgreSQL version, schema/table definitions, query, expected result, observed error or plan, data volume, and environment.
+- When docs or behavior differ by version, verify against the installed server with `SHOW server_version;`.
+
+## Quick Reference
+
+### Common Patterns
+
+**Connect with psql**
+```bash
+psql "postgresql://user@localhost:5432/mydb"
+```
+
+**Check server version**
+```sql
+SHOW server_version;
+```
+
+**Create a table with a generated id**
+```sql
+CREATE TABLE users (
+  id serial PRIMARY KEY,
+  firstname text NOT NULL,
+  lastname text NOT NULL
+);
+```
+
+**Insert and return generated data**
+```sql
+INSERT INTO users (firstname, lastname)
+VALUES ('Joe', 'Cool')
+RETURNING id;
+```
+
+**Update and inspect changed rows**
+```sql
+UPDATE products
+SET price = price * 1.10
+WHERE price <= 99.99
+RETURNING name, price AS new_price;
+```
+
+**Create an index**
+```sql
+CREATE INDEX test1_id_index ON test1 (id);
+```
+
+**Read a query plan**
+```sql
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT * FROM users WHERE lastname = 'Cool';
+```
+
+**Use a transaction guard for data changes**
+```sql
+BEGIN;
+UPDATE users SET lastname = 'Checked' WHERE id = 1 RETURNING *;
+ROLLBACK;
+```
+
+**Harden search path for untrusted schemas**
+```sql
+SELECT pg_catalog.set_config('search_path', '', false);
+```
+
+## Examples
+
+### Example 1: Add a Safe Migration
+
+- Input: new table requirement and target PostgreSQL version.
+- Steps:
+  1. Write `CREATE TABLE` with primary key, `NOT NULL`, and constraints.
+  2. Add indexes only for known query predicates.
+  3. Run migration in a transaction in staging and verify with `\d`.
+- Expected output / acceptance: migration is reversible or has a rollback plan and schema matches expected constraints.
+
+### Example 2: Debug a Slow Query
+
+- Input: SQL query, table definitions, estimated data volume, and current indexes.
+- Steps:
+  1. Run `EXPLAIN (ANALYZE, BUFFERS)` on a safe environment.
+  2. Identify sequential scans, bad row estimates, sort/hash spills, or missing predicates.
+  3. Propose the smallest index/query rewrite and re-run the plan.
+- Expected output / acceptance: before/after plan evidence shows lower runtime or IO for the target workload.
+
+### Example 3: Validate Data-Modifying SQL
+
+- Input: `UPDATE` or `DELETE` statement for production data.
+- Steps:
+  1. Convert the predicate to a `SELECT count(*)` and inspect sample rows.
+  2. Run inside `BEGIN` with `RETURNING` on a staging or transaction-guarded session.
+  3. Commit only after row count and returned rows match the expected blast radius.
+- Expected output / acceptance: affected rows are known before commit and the rollback path is explicit.
+
+## References
+
+- `references/index.md`: navigation for local PostgreSQL references.
+- `references/getting_started.md`: psql, tutorial SQL, build/install, and basics.
+- `references/sql.md`: SQL language, DDL/DML, `RETURNING`, monitoring, and advanced examples.
+
+## Maintenance
+
+- Sources: local `references/` extracted from PostgreSQL documentation.
+- Last updated: 2026-04-28
+- Known limits: server behavior depends on PostgreSQL version, extensions, configuration, statistics, and workload; validate with live plans.

skills/postgresql/references/index.md

@@ -0,0 +1,11 @@
+# Postgresql Documentation Index
+
+## Categories
+
+### Getting Started
+**File:** `getting_started.md`
+**Pages:** 36
+
+### Sql
+**File:** `sql.md`
+**Pages:** 460