docs(pgpm): skill accepts a developer's own Postgres; never stop what owns 5432

.agents/skills/pgpm/SKILL.md

@@ -30,7 +30,11 @@ Use this skill when:
 # 1. Install pgpm
 npm install -g pgpm
 
-# 2. Start a local PostgreSQL container
+# 2. Get a PostgreSQL to work against.
+#    Already running one (e.g. `pg_isready -h localhost -p 5432` answers)? Use it:
+#    export PGHOST/PGPORT/PGUSER/PGPASSWORD for a superuser and skip this whole step
+#    (including `pgpm env`). Do not stop the developer's server or start Docker on top of it.
+#    Otherwise, start the pgpm container and load its connection vars:
 pgpm docker start
 eval "$(pgpm env)"
 
@@ -152,7 +156,7 @@ pgpm handles extension creation during deploy. Declare extensions in your `.cont
 ## Essential Development Workflow
 
 ```bash
-# Start PostgreSQL and load environment
+# Start PostgreSQL and load environment (skip both if PG* already point at your own server)
 pgpm docker start
 eval "$(pgpm env)"
 
@@ -331,13 +335,15 @@ In `noTty` mode, `inquirerer` uses defaults where available and throws with the
 
 | Issue | Quick Fix |
 |-------|-----------|
-| Can't connect to database | `pgpm docker start && eval "$(pgpm env)"` |
+| Can't connect to database | `pg_isready -h $PGHOST -p $PGPORT`; if nothing is listening, `pgpm docker start && eval "$(pgpm env)"` |
 | `PGHOST` not set | `eval "$(pgpm env)"` — must use `eval`, not run in subshell |
+| Developer already runs Postgres on 5432 | Use it: `export PGHOST=localhost PGPORT=5432 PGUSER=<superuser> PGPASSWORD=...` then `pgpm admin-users bootstrap --yes`. No Docker needed |
 | Transaction aborted in tests | Use `db.beforeEach()` / `db.afterEach()` savepoint pattern |
 | Tests interfere with each other | Ensure every test file has `beforeEach`/`afterEach` hooks |
 | Module not found during deploy | Verify `.control` file exists and workspace structure is correct |
 | Dependency not found | Check `.control` `requires` uses control names, not npm names |
-| Port 5432 already in use | `lsof -i :5432` then stop conflicting process |
+| Port 5432 already in use | If it's a Postgres, use it (row above) — never stop a developer's server. Want the pgpm container anyway? `pgpm docker start --port 5433` and `export PGPORT=5433` |
+| `pnpm install` fails with `ERR_PNPM_IGNORED_BUILDS` | Add the package to `pnpm-policy.yaml` (`allowBuilds` with a reason, or `false`) and `pnpm run policy`. Don't run `pnpm approve-builds` |
 | `Invalid line format` in pgpm.plan | Dependencies `[...]` must come right after change name, before timestamp |
 | `CREATE OR REPLACE` error | Remove `OR REPLACE` — pgpm is deterministic |
 | Container won't start | `pgpm docker start --recreate` for a fresh container |

.agents/skills/pgpm/references/docker.md

@@ -14,6 +14,12 @@ Use this skill when:
 
 ## Quick Start
 
+Docker is optional. If a PostgreSQL server is already running (check with
+`pg_isready -h localhost -p 5432`), export `PGHOST`/`PGPORT`/`PGUSER`/`PGPASSWORD` for a
+superuser and skip this reference entirely — do not stop that server to make room for
+the container. If you want both, start the container on another port (`--port 5433`)
+and `export PGPORT=5433`.
+
 ### Start PostgreSQL Container
 
 ```bash
@@ -115,7 +121,7 @@ If you see errors like "unrecognized parameter security_invoker", ensure you're
 | Issue | Solution |
 |-------|----------|
 | "Docker is not installed" | Install Docker Desktop or Docker Engine |
-| "Port already in use" | Use `--port` to specify a different port, or stop the conflicting container |
+| "Port already in use" | If it's a running Postgres, use it (export PG*) instead of Docker; otherwise `--port 5433` + `export PGPORT=5433`. Never stop a developer's own server |
 | Container won't start | Check `docker logs postgres` for errors |
 | "Container already exists" | Use `--recreate` to remove and recreate |
 | Permission denied | Ensure Docker daemon is running and user has permissions |

.agents/skills/pgpm/references/env.md

@@ -26,6 +26,18 @@ This sets the following environment variables:
 - `PGPASSWORD=password`
 - `PGDATABASE=postgres`
 
+These are the `pgpm docker start` defaults — `pgpm env` is for the pgpm container.
+
+### Using Your Own PostgreSQL
+
+If PostgreSQL is already running locally, skip both `pgpm docker start` and `pgpm env`
+(it would overwrite your connection vars with the container's). Just export your own:
+
+```bash
+export PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=yourpassword
+pgpm admin-users bootstrap --yes   # once
+```
+
 ### Run Command with Environment
 
 ```bash

.agents/skills/pgpm/references/troubleshooting.md

@@ -262,15 +262,34 @@ pgpm docker start
 port 5432 is already in use
 ```
 
-**Solution:**
+**Solution:** first find out whether it is already a PostgreSQL server:
+
 ```bash
-# Find what's using the port
-lsof -i :5432
+pg_isready -h localhost -p 5432
+```
 
-# Either stop that process or use a different port
-# Edit docker-compose.yml to use different port
+If it answers, the developer runs their own Postgres — use it instead of Docker. Never
+stop or kill it to free the port. Ask for (or use) superuser credentials and skip
+`pgpm docker start`:
+
+```bash
+export PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=yourpassword
+pgpm admin-users bootstrap --yes     # once: roles pgpm and pgsql-test expect
 ```
 
+Do not run `eval "$(pgpm env)"` in this case — it emits the container's connection
+vars and would overwrite yours.
+
+If you want the pgpm container *alongside* an existing server, move it and match the port:
+
+```bash
+pgpm docker start --port 5433
+export PGPORT=5433
+```
+
+Only if `lsof -i :5432` shows something that is not Postgres should you consider
+stopping that process.
+
 ### Volume Permission Issues
 
 **Symptom:**
@@ -296,7 +315,7 @@ pgpm docker start
 | Transaction aborted | Use savepoint pattern |
 | Tests interfere | Check beforeEach/afterEach hooks |
 | Module not found | Verify workspace structure |
-| Port in use | `lsof -i :5432` then stop conflicting process |
+| Port in use | `pg_isready -h localhost -p 5432` — if it's Postgres, use it (export PG*); else `pgpm docker start --port 5433` + `PGPORT=5433` |
 
 ## Getting Help