alexshapalov · Oct 27, 2026 · Nov 4, 2026
diff --git a/docs/pgx/local-dev/claude-plugin.md b/docs/pgx/local-dev/claude-plugin.md
@@ -73,16 +73,17 @@ branch. See [agents.md](agents.md) for what that gives you.
 Check what is installed:
 
 ```sh
-claude plugin list             # pgx@pgx-plugin  Version: 0.1.2  Status: enabled
+claude plugin list             # pgx@pgx-plugin  Version: 0.1.3  Status: enabled
 claude plugin details pgx      # Component inventory: Skills (1) pgx, Hooks (0), MCP servers (0)
 ```
 
 ## What the plugin contains
 
 - `skills/pgx/`: the Skill, its eleven reference documents and two helper
   scripts, identical to `skills/pgx/` at the repository root.
-- `.claude-plugin/plugin.json`: name `pgx`, version `0.1.2` (the Skill's
-  version), display name, links.
+- `.claude-plugin/plugin.json`: name `pgx`, version `0.1.3` (the Skill's
+  version; it moves independently of the PGX runtime version, which the
+  skill requires to be 0.1.2 or newer), display name, links.
 - `README.md`.
 
 In `pgrundev/pgx-plugin` additionally `LICENSE` (the AGPL-3.0 text the
@@ -254,7 +255,7 @@ CLI does not check and a security scan. Values for the form:
 | Plugin name / display name | `pgx` / "PGX — Postgres for Agents" (read from `plugin.json`) |
 | Description | PGX gives every Claude Code agent its own isolated, disposable PostgreSQL-compatible database. Agents can run migrations, tests, and experiments in parallel without database conflicts. No Docker or cloud account required. Built in Rust. |
 | Category | Developer tools, or Databases if the form offers it |
-| Version | 0.1.2 |
+| Version | 0.1.3 (plugin and skill); requires PGX runtime 0.1.2 or newer |
 | License | AGPL-3.0 (`LICENSE` in the repository, `license` in `plugin.json`) |
 | Documentation / support | https://github.com/pgrundev/pgx (`documentationUrl`, `supportUrl` in `plugin.json`) |
 | Icon | none yet; the directory takes the icon from the first submission only, so add a square PNG (512–2048 px) as `.claude-plugin/icon.png` in `plugins/pgx` before submitting if one is wanted |

diff --git a/plugins/pgx/.claude-plugin/plugin.json b/plugins/pgx/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "pgx",
   "displayName": "PGX — Postgres for Agents",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Isolated, disposable PostgreSQL-compatible databases for AI coding agents.",
   "author": {
     "name": "PGRunDev",

diff --git a/plugins/pgx/README.md b/plugins/pgx/README.md
@@ -61,8 +61,9 @@ or just describe database work ("run the pending migrations and the tests",
 "set up Postgres for my agents"); Claude selects the skill when it is relevant.
 
 The first activation in a project walks through detection of the existing
-database setup, a check for the PGX runtime (offering `npm i -g pgxdb` or the
-official installer if it is missing), a schema-only template copied from your
+database setup, a check for the PGX runtime (offering `npm i -g pgxdb@0.1.2`
+if it is missing, or telling you how to run the official installer yourself),
+a schema-only template copied from your
 existing PostgreSQL or a fresh PGX database, and a one-time `pgx agent setup`.
 From then on every new Claude Code session in that project starts with
 `DATABASE_URL` pointing at its own branch, and every subagent that session
@@ -82,15 +83,23 @@ automatically. Nothing in the plugin needs to be configured by hand.
 - No database engine. The `pgx` binary is installed separately when the
   skill first needs it. The skill asks before downloading anything.
 
-## What runs on your machine
+## What runs on your machine, and what it reads
 
 Everything is local. The skill runs the `pgx` CLI against the PGX runtime on
-`127.0.0.1`; it does not call any network service of its own. Database
-credentials for agent branches are generated by PGX, exported into the
-session's environment by the hooks that `pgx agent setup` installs, and never
-written into the conversation; your existing PostgreSQL is read with
-`pg_dump --schema-only` to build a template, and its data is copied only when
-you explicitly approve it. Branches expire on their own (idle TTL, then a
+`127.0.0.1`; it does not call any network service of its own. The only
+downloads are the ones you approve: `npm i -g pgxdb@0.1.2` (pinned) when
+the runtime is missing, or the official installer that you run yourself.
+
+To find your project's database, `detect-project.sh` reads `DATABASE_URL`
+from the environment and from `.env`, `.env.local`, `.env.development` and
+`.env.test` if they exist, and prints only the host, port and database name
+(never the password or the URL). When you ask for a template of that
+database, the connection string is passed from your environment or file
+straight to `pgx copy` on this machine, which runs `pg_dump --schema-only`
+against it; it is never printed into the conversation and never sent
+anywhere else. Its data is copied only when you explicitly approve it.
+Credentials for agent branches are generated by PGX and exported into the
+session's environment by the hooks that `pgx agent setup` installs. Branches expire on their own (idle TTL, then a
 short grace period after the session ends) and the PGX supervisor removes
 them. Removing the plugin (`/plugin uninstall pgx@pgx-plugin`) removes the
 skill only; databases, templates, `.pgx.toml` and the PGX runtime stay, and
@@ -112,8 +121,9 @@ differ. Report issues and send changes to pgrundev/pgx.
 - `/pgx:pgx` is not offered: `claude plugin list` should show the plugin
   enabled; restart the session after installing.
 - "PGX not found" or "too old": install or upgrade the runtime
-  (`npm i -g pgxdb@latest` or `curl -fsSL https://pgx.dev/install | sh`), then
-  run the skill again. It needs 0.1.2 or newer for subagent isolation.
+  (`npm i -g pgxdb@0.1.2`, or run the installer from https://pgx.dev/install
+  in your own shell), then run the skill again. It needs 0.1.2 or newer for
+  subagent isolation.
 - A session's `DATABASE_URL` still points at your real database: the project
   has not run `pgx agent setup` yet, or the session started before it did.
   `pgx agent doctor` reports the project's state.

diff --git a/plugins/pgx/skills/pgx/SKILL.md b/plugins/pgx/skills/pgx/SKILL.md
@@ -14,7 +14,7 @@ description: >
 license: AGPL-3.0
 metadata:
   author: pgrundev
-  version: "0.1.2"
+  version: "0.1.3"
   homepage: https://pgx.dev
   repository: https://github.com/pgrundev/pgx
 ---
@@ -111,11 +111,13 @@ unreadable `pgx --json version`. It reads the
 structured version only: `pgx agent --help` prints the global help on every
 version and proves nothing. If `pgx` is missing or too old,
 follow [references/installation.md](references/installation.md): prefer an
-installed binary, then `npm i -g pgxdb` (Node 18+), then the official
-installer `curl -fsSL https://pgx.dev/install | sh`. Supported: macOS arm64,
-Linux amd64, Linux arm64. PGX picks a free port and never disturbs a
-PostgreSQL on 5432. Installing is a network download: follow the host's
-approval flow and say what will be installed and where.
+installed binary, then `npm i -g pgxdb@0.1.2` (Node 18+, pinned to the
+version this skill needs). The official installer at https://pgx.dev/install
+is something the user runs in their own shell; never pipe a download into a
+shell on the user's behalf. Supported: macOS arm64, Linux amd64, Linux
+arm64. PGX picks a free port and never disturbs a PostgreSQL on 5432.
+Installing is a network download: follow the host's approval flow and say
+what will be installed and where.
 
 ### 3. Prepare the source template
 

diff --git a/plugins/pgx/skills/pgx/references/installation.md b/plugins/pgx/skills/pgx/references/installation.md
@@ -17,7 +17,7 @@ malformed, always with one JSON line. It compares `pgx --json version` →
 `pgx_version` as semver (`PGX_MIN_VERSION` overrides the floor). Do not use
 `pgx agent --help` as the test: `--help` prints the global help on every
 version. An older binary: upgrade with the method it was installed with
-(`npm i -g pgxdb@latest`, or the installer again) and run the check again;
+(`npm i -g pgxdb@0.1.2`, or the installer again) and run the check again;
 if the upgrade still reports 0.1.0, the newer package is not yet on that
 channel and the user should install from the GitHub release.
 
@@ -26,14 +26,17 @@ channel and the user should install from the GitHub release.
 1. **A binary that is already on the machine** (a previous install under
    `~/.local/bin/pgx`, Homebrew, or `~/.pgx/dist/<version>/bin/pgx`). Prefer
    it; do not download twice.
-2. **npm**, when Node.js 18+ is present: `npm i -g pgxdb` installs the
-   `pgxdb` and `pgx` commands; the first run downloads the native release
-   tarball into `~/.pgx/dist/<version>`. `npx pgxdb@latest` works without a
-   global install but gives you `npx pgxdb …` instead of `pgx …`.
-3. **The official installer**: `curl -fsSL https://pgx.dev/install | sh`.
-   Verified release assets from github.com/pgrundev/pgx; installs under
-   `~/.pgx/dist/<version>` and links `pgx` into `~/.local/bin` (override with
-   `PGX_BIN_DIR`). No root.
+2. **npm**, when Node.js 18+ is present: `npm i -g pgxdb@0.1.2` installs
+   the `pgxdb` and `pgx` commands; the first run downloads the native release
+   tarball into `~/.pgx/dist/<version>`. Always pin the exact version (the
+   one `check-pgx.sh` asks for), never `@latest`. `npx pgxdb@0.1.2` works
+   without a global install but gives you `npx pgxdb …` instead of `pgx …`.
+3. **The official installer**, run by the user in their own shell:
+   `curl -fsSL https://pgx.dev/install | sh`. Tell the user the command and
+   what it does; do not run it yourself and never pipe a download into a
+   shell on the user's behalf. Verified release assets from
+   github.com/pgrundev/pgx; installs under `~/.pgx/dist/<version>` and links
+   `pgx` into `~/.local/bin` (override with `PGX_BIN_DIR`). No root.
 
 Nothing else. No third-party scripts, no building from source for a user who
 just wants a database (that is for contributors).

diff --git a/plugins/pgx/skills/pgx/references/security.md b/plugins/pgx/skills/pgx/references/security.md
@@ -18,8 +18,10 @@ runs in real projects that hold real credentials and real data.
 6. **No deletions of developer data.** Never drop databases you did not
    create in this task, never `pgx init --force`, never remove a PGX home,
    never `pgx stop --force` a runtime other sessions use.
-7. **Only official installation channels.** `npm i -g pgxdb`,
-   `curl -fsSL https://pgx.dev/install | sh`, or an existing binary.
+7. **Only official installation channels.** An existing binary, or
+   `npm i -g pgxdb@0.1.2` (always an exact version). The installer at
+   https://pgx.dev/install is for the user to run in their own shell; never
+   pipe a download into a shell on the user's behalf.
 8. **Preserve the user's hooks and settings.** `pgx agent install` merges;
    `uninstall` removes only PGX entries. Do not hand-edit hook files.
 9. **Never weaken sandboxes.** Explain the Codex network setting; do not set

diff --git a/plugins/pgx/skills/pgx/scripts/check-pgx.sh b/plugins/pgx/skills/pgx/scripts/check-pgx.sh
@@ -11,7 +11,7 @@ MIN=${PGX_MIN_VERSION:-0.1.2}
 esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
 path=$(command -v pgx 2>/dev/null || true)
 if [ -z "$path" ]; then
-  printf '{"ok":false,"reason":"missing","min":"%s","hint":"install PGX: npm i -g pgxdb (Node 18+) or curl -fsSL https://pgx.dev/install | sh"}\n' "$MIN"; exit 3
+  printf '{"ok":false,"reason":"missing","min":"%s","hint":"install PGX: npm i -g pgxdb@%s (Node 18+), or run the installer from https://pgx.dev/install in your own shell"}\n' "$MIN" "$MIN"; exit 3
 fi
 out=$(pgx --json version 2>/dev/null || true)
 ver=$(printf '%s' "$out" | sed -nE 's/.*"pgx_version":"([0-9]+\.[0-9]+\.[0-9]+)[^"]*".*/\1/p' | head -1)
@@ -36,4 +36,4 @@ if vcmp "$ver" "0.1.1"; then
 else
   why="PGX $ver has no pgx agent"
 fi
-printf '{"ok":false,"reason":"too_old","version":"%s","path":"%s","min":"%s","hint":"%s; upgrade to %s or newer with the method it was installed with (npm i -g pgxdb@latest, or the installer again)"}\n' "$ver" "$(esc "$path")" "$MIN" "$why" "$MIN"; exit 2
+printf '{"ok":false,"reason":"too_old","version":"%s","path":"%s","min":"%s","hint":"%s; upgrade to %s or newer with the method it was installed with (npm i -g pgxdb@%s, or the installer again)"}\n' "$ver" "$(esc "$path")" "$MIN" "$why" "$MIN" "$MIN"; exit 2
diff --git a/skills/pgx/SKILL.md b/skills/pgx/SKILL.md
@@ -14,7 +14,7 @@ description: >
 license: AGPL-3.0
 metadata:
   author: pgrundev
-  version: "0.1.2"
+  version: "0.1.3"
   homepage: https://pgx.dev
   repository: https://github.com/pgrundev/pgx
 ---
@@ -111,11 +111,13 @@ unreadable `pgx --json version`. It reads the
 structured version only: `pgx agent --help` prints the global help on every
 version and proves nothing. If `pgx` is missing or too old,
 follow [references/installation.md](references/installation.md): prefer an
-installed binary, then `npm i -g pgxdb` (Node 18+), then the official
-installer `curl -fsSL https://pgx.dev/install | sh`. Supported: macOS arm64,
-Linux amd64, Linux arm64. PGX picks a free port and never disturbs a
-PostgreSQL on 5432. Installing is a network download: follow the host's
-approval flow and say what will be installed and where.
+installed binary, then `npm i -g pgxdb@0.1.2` (Node 18+, pinned to the
+version this skill needs). The official installer at https://pgx.dev/install
+is something the user runs in their own shell; never pipe a download into a
+shell on the user's behalf. Supported: macOS arm64, Linux amd64, Linux
+arm64. PGX picks a free port and never disturbs a PostgreSQL on 5432.
+Installing is a network download: follow the host's approval flow and say
+what will be installed and where.
 
 ### 3. Prepare the source template
 

diff --git a/skills/pgx/references/installation.md b/skills/pgx/references/installation.md
@@ -17,7 +17,7 @@ malformed, always with one JSON line. It compares `pgx --json version` →
 `pgx_version` as semver (`PGX_MIN_VERSION` overrides the floor). Do not use
 `pgx agent --help` as the test: `--help` prints the global help on every
 version. An older binary: upgrade with the method it was installed with
-(`npm i -g pgxdb@latest`, or the installer again) and run the check again;
+(`npm i -g pgxdb@0.1.2`, or the installer again) and run the check again;
 if the upgrade still reports 0.1.0, the newer package is not yet on that
 channel and the user should install from the GitHub release.
 
@@ -26,14 +26,17 @@ channel and the user should install from the GitHub release.
 1. **A binary that is already on the machine** (a previous install under
    `~/.local/bin/pgx`, Homebrew, or `~/.pgx/dist/<version>/bin/pgx`). Prefer
    it; do not download twice.
-2. **npm**, when Node.js 18+ is present: `npm i -g pgxdb` installs the
-   `pgxdb` and `pgx` commands; the first run downloads the native release
-   tarball into `~/.pgx/dist/<version>`. `npx pgxdb@latest` works without a
-   global install but gives you `npx pgxdb …` instead of `pgx …`.
-3. **The official installer**: `curl -fsSL https://pgx.dev/install | sh`.
-   Verified release assets from github.com/pgrundev/pgx; installs under
-   `~/.pgx/dist/<version>` and links `pgx` into `~/.local/bin` (override with
-   `PGX_BIN_DIR`). No root.
+2. **npm**, when Node.js 18+ is present: `npm i -g pgxdb@0.1.2` installs
+   the `pgxdb` and `pgx` commands; the first run downloads the native release
+   tarball into `~/.pgx/dist/<version>`. Always pin the exact version (the
+   one `check-pgx.sh` asks for), never `@latest`. `npx pgxdb@0.1.2` works
+   without a global install but gives you `npx pgxdb …` instead of `pgx …`.
+3. **The official installer**, run by the user in their own shell:
+   `curl -fsSL https://pgx.dev/install | sh`. Tell the user the command and
+   what it does; do not run it yourself and never pipe a download into a
+   shell on the user's behalf. Verified release assets from
+   github.com/pgrundev/pgx; installs under `~/.pgx/dist/<version>` and links
+   `pgx` into `~/.local/bin` (override with `PGX_BIN_DIR`). No root.
 
 Nothing else. No third-party scripts, no building from source for a user who
 just wants a database (that is for contributors).

diff --git a/skills/pgx/references/security.md b/skills/pgx/references/security.md
@@ -18,8 +18,10 @@ runs in real projects that hold real credentials and real data.
 6. **No deletions of developer data.** Never drop databases you did not
    create in this task, never `pgx init --force`, never remove a PGX home,
    never `pgx stop --force` a runtime other sessions use.
-7. **Only official installation channels.** `npm i -g pgxdb`,
-   `curl -fsSL https://pgx.dev/install | sh`, or an existing binary.
+7. **Only official installation channels.** An existing binary, or
+   `npm i -g pgxdb@0.1.2` (always an exact version). The installer at
+   https://pgx.dev/install is for the user to run in their own shell; never
+   pipe a download into a shell on the user's behalf.
 8. **Preserve the user's hooks and settings.** `pgx agent install` merges;
    `uninstall` removes only PGX entries. Do not hand-edit hook files.
 9. **Never weaken sandboxes.** Explain the Codex network setting; do not set

diff --git a/skills/pgx/scripts/check-pgx.sh b/skills/pgx/scripts/check-pgx.sh
@@ -11,7 +11,7 @@ MIN=${PGX_MIN_VERSION:-0.1.2}
 esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
 path=$(command -v pgx 2>/dev/null || true)
 if [ -z "$path" ]; then
-  printf '{"ok":false,"reason":"missing","min":"%s","hint":"install PGX: npm i -g pgxdb (Node 18+) or curl -fsSL https://pgx.dev/install | sh"}\n' "$MIN"; exit 3
+  printf '{"ok":false,"reason":"missing","min":"%s","hint":"install PGX: npm i -g pgxdb@%s (Node 18+), or run the installer from https://pgx.dev/install in your own shell"}\n' "$MIN" "$MIN"; exit 3
 fi
 out=$(pgx --json version 2>/dev/null || true)
 ver=$(printf '%s' "$out" | sed -nE 's/.*"pgx_version":"([0-9]+\.[0-9]+\.[0-9]+)[^"]*".*/\1/p' | head -1)
@@ -36,4 +36,4 @@ if vcmp "$ver" "0.1.1"; then
 else
   why="PGX $ver has no pgx agent"
 fi
-printf '{"ok":false,"reason":"too_old","version":"%s","path":"%s","min":"%s","hint":"%s; upgrade to %s or newer with the method it was installed with (npm i -g pgxdb@latest, or the installer again)"}\n' "$ver" "$(esc "$path")" "$MIN" "$why" "$MIN"; exit 2
+printf '{"ok":false,"reason":"too_old","version":"%s","path":"%s","min":"%s","hint":"%s; upgrade to %s or newer with the method it was installed with (npm i -g pgxdb@%s, or the installer again)"}\n' "$ver" "$(esc "$path")" "$MIN" "$why" "$MIN" "$MIN"; exit 2