diff --git a/.changes/sql-server/work-resolve-issue-issue-9898-4b7e2c19.md b/.changes/sql-server/work-resolve-issue-issue-9898-4b7e2c19.md
new file mode 100644
index 0000000000..7522da68b8
--- /dev/null
+++ b/.changes/sql-server/work-resolve-issue-issue-9898-4b7e2c19.md
@@ -0,0 +1,9 @@
+---
+bump: minor
+---
+
+### Added
+
+- The `setup` skill (`/sql-server:setup check|apply --config <path>`). `check` runs `skills/setup/scripts/check-setup.mjs`, which prints a PASS, FAIL or INFO row for Node.js, the config against `config.v1.schema.json`, each environment, each credential variable (set or not, never its value) and the server copy in the plugin data directory, then a `claude mcp add` command per environment that names each credential as `--env 'NAME=${NAME}'`. It exits 1 on a FAIL row, such as a config with a literal password. With an environment already registered, `check` also lists the principal's database permissions through its `query` tool. `apply` copies the server into the plugin data directory and runs `npm ci` there, then runs each registration command at user scope once the user confirms; project scope is refused ([#9898](https://github.com/melodic-software/claude-code-plugins/issues/9898)).
+- `reference/azure-sql-database.md`: a free Azure SQL Database for a trial (`--use-free-limit true --free-limit-exhaustion-behavior AutoPause`), a read-only Entra contained user in `db_datareader`, the config entry, and what differs from a local SQL Server, `READ_COMMITTED_SNAPSHOT` being on by default there.
+- The README's Setup section and a list of the limits of each guarantee, from ADR 0086 and the read-safety measurement.
diff --git a/docs/catalog.md b/docs/catalog.md
index 10eab5a69e..217182df1d 100644
--- a/docs/catalog.md
+++ b/docs/catalog.md
@@ -40,7 +40,7 @@ plugin manifests and kept in sync by CI. Never hand-edit it; the category vocabu
 - [`source-control`](../plugins/source-control): Git and GitHub delivery: /commit (convention-checked subject, Co-authored-by trailer, surgical staging), /pull-request (prep, create, CI monitoring, review triage, merge, CI logs), /babysit-prs (safe-by-default PR fleet loop, opt-in worker and autopilot tiers), /babysit-loop (merge lane; merge is human until the repo adopts it), /worktree, /resolve-conflicts (intent-first), /check, and /setup (layered source-control.md convention config; Conventional Commits by default).
 - [`implementation`](../plugins/implementation): Disciplined implementation stage: execute approved plans inline (`/implementation:implement`) or via orchestrated worker subagents (`/implementation:implement-dispatch`) with incremental validation, TDD-by-default cadence, green-checkpoint commits, scope-fence drift detection, and divergence detection that routes back to planning. Build/test/lint, testing, and outcome verification live in the companion `toolchain`, `testing`, and `verification` plugins, invoked when installed.
 - [`toolchain`](../plugins/toolchain): Repo-agnostic polyglot verification toolchain: build + test + lint for changed files across .NET, Python, TypeScript, Bash, PowerShell, Markdown, Go, YAML, and cross-cutting surfaces (`/toolchain:check`, `/toolchain:lint` with format-only `--fix` and gated `--code-fix`), `/toolchain:setup` for the per-ecosystem command config, `/toolchain:ratchet` for a CI ceiling on a count, and a turn-end Stop hook that warns when the recorded check or lint result is not a pass.
-- [`sql-server`](../plugins/sql-server): Read-only SQL Server and Azure SQL Database access for agents, bounded by a read-only database principal (ADR 0086). This release ships the versioned config schema, its loader, the single-statement reject list, the stdio MCP server with its fixed query, list_objects and describe_object tools, and the tedious executor with per-call transaction guards; the setup skill comes later.
+- [`sql-server`](../plugins/sql-server): Read-only SQL Server and Azure SQL Database access for agents, bounded by a read-only database principal (ADR 0086). This release ships the versioned config schema, its loader, the single-statement reject list, the stdio MCP server with its fixed query, list_objects and describe_object tools, the tedious executor with per-call transaction guards, and a setup skill that checks a config and registers each environment by reference.
 - [`wizard`](../plugins/wizard): Scripts that walk a human through manual steps an agent cannot do: provisioning infrastructure or credentials, CI secrets, third-party dashboards, one-off migrations. /wizard:generate scopes stages from the repo (.env key names only), builds an interactive bash wizard on a hardened library (TTY-only prompts, hidden secret entry, 0600 .env writes), and shows the stages for approval first; the human runs it. /wizard:unattended writes a PowerShell script the human launches once.
 - [`developer-experience`](../plugins/developer-experience): Helps a team build and maintain its own developer tooling: setup records the team's tooling conventions, build-cli builds command-line tools to them, and audit-tools inventories a repository's scripts, CLIs, hooks and skills and reports what to fix.
 
diff --git a/plugins/sql-server/.claude-plugin/plugin.json b/plugins/sql-server/.claude-plugin/plugin.json
index 0fb74971d6..b7ef49ec07 100644
--- a/plugins/sql-server/.claude-plugin/plugin.json
+++ b/plugins/sql-server/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "sql-server",
   "version": "0.3.2",
-  "description": "Read-only SQL Server and Azure SQL Database access for agents, bounded by a read-only database principal (ADR 0086). This release ships the versioned config schema, its loader, the single-statement reject list, the stdio MCP server with its fixed query, list_objects and describe_object tools, and the tedious executor with per-call transaction guards; the setup skill comes later.",
+  "description": "Read-only SQL Server and Azure SQL Database access for agents, bounded by a read-only database principal (ADR 0086). This release ships the versioned config schema, its loader, the single-statement reject list, the stdio MCP server with its fixed query, list_objects and describe_object tools, the tedious executor with per-call transaction guards, and a setup skill that checks a config and registers each environment by reference.",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"
diff --git a/plugins/sql-server/README.md b/plugins/sql-server/README.md
index 59dcff4123..07de88a360 100644
--- a/plugins/sql-server/README.md
+++ b/plugins/sql-server/README.md
@@ -4,8 +4,33 @@ Read-only access to SQL Server-family databases (a local SQL Server container, A
 for agents. The design is [ADR 0086](../../docs/adr/0086-bound-the-sql-server-read-tier-by-a-read-only-principal-and-fixed-registrations.md).
 
 This release ships the versioned config schema, its loader, the single-statement reject list, the
-stdio MCP server with its three tools, and the executor that runs each call on SQL Server through
-`tedious`. The setup skill comes in a later release, so the plugin is off by default.
+stdio MCP server with its three tools, the executor that runs each call on SQL Server through
+`tedious`, and the `setup` skill that checks a config and registers its environments. The plugin
+is off by default.
+
+## Setup
+
+1. Create a read-only principal on the server (for Azure SQL Database, see
+   [reference/azure-sql-database.md](reference/azure-sql-database.md), which also covers a free
+   database for a trial).
+2. Write a config file outside your project directory (see [Config](#config)).
+3. Run `/sql-server:setup check --config <path>`, then `/sql-server:setup apply --config <path>`.
+   `apply` installs the server into the plugin's data directory, which keeps its path across
+   plugin updates, and prints one `claude mcp add` command per environment, which it runs once you
+   confirm. The command names each credential by reference, `--env 'NAME=${NAME}'`, never by
+   value, and `apply` reads each registration back to confirm it. Project scope is refused, because
+   the agent can edit the repository.
+
+The check is a script you can run on its own. From a checkout of this repository:
+
+```bash
+node plugins/sql-server/skills/setup/scripts/check-setup.mjs --config <path> [--environment <name>] [--data-dir <dir>]
+```
+
+It prints one PASS, FAIL or INFO row for Node.js, the config, each environment, each credential
+variable (set or not, never its value) and, with `--data-dir`, the installed server copy, then each
+environment's `claude mcp add` command. It exits 1 when a row fails, as it does for a config with a
+literal password, and writes nothing.
 
 ## The server
 
@@ -82,8 +107,9 @@ its managed identity client id, when given) to `tedious`'s `token-credential` au
 
 The executor loads `tedious` and `@azure/identity`, the dependencies in `package.json`, on the
 first call, so the server starts without them and a call made before they are installed fails
-with a tool error saying so. `package-lock.json` pins their whole tree, and Claude Code installs
-that tree when it copies the plugin into its cache.
+with a tool error saying so. `package-lock.json` pins their whole tree. Claude Code installs that
+tree when it copies the plugin into its cache, and `/sql-server:setup apply` installs it with
+`npm ci` into the server copy in the plugin's data directory, the copy a registration runs.
 
 ### The reject list
 
@@ -107,6 +133,27 @@ What the list lets through, because it is a heuristic:
   `SELECT 1 AS a RECEIVE TOP(1) * FROM q`. The read-only principal, which holds no `RECEIVE` or
   `ALTER` permission, is what refuses it.
 
+### Limits of the guarantees
+
+- **Other databases on the server.** The allow-list refuses a `database` argument outside it, but
+  a three-part name such as `other.dbo.t` is stopped only by what `other` lets the principal do.
+  Check the principal's access in every database on the server, system databases included.
+- **Lock hold before the row cap fires.** The measurement shows a capped read returning promptly
+  with no transaction left open, for a fast consumer and no writer. How long a slow or paused
+  consumer holds locks before the cap fires was not measured.
+- **Load per registration.** Each registration runs one process per client session, and each
+  process holds at most two connections, so a session with three registrations can hold six. The
+  measurement blocked no request with up to 2 processes and a few briefly at 8.
+- **Locking reads on SQL Server.** `READ_COMMITTED_SNAPSHOT` is off by default on SQL Server, so a
+  `READ COMMITTED` read takes shared locks until its statement ends and the lock timeout, the
+  request timeout and the row cap bound how long it blocks a writer. Azure SQL Database turns it on
+  by default and reads row versions instead.
+- **Entra tokens.** Whether a connection that stays busy past its token's expiry keeps working is
+  not verified.
+- **Not covered.** Windows integrated and Kerberos authentication. Azure SQL Managed Instance and
+  other SQL Server hosts reachable over TCP are expected to work with the same two auth types, but
+  are not tested.
+
 ## Config
 
 One JSON file, validated by [`schemas/config.v1.schema.json`](schemas/config.v1.schema.json)
diff --git a/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/case.yaml b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/case.yaml
new file mode 100644
index 0000000000..2547ff1917
--- /dev/null
+++ b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/case.yaml
@@ -0,0 +1,35 @@
+schema_version: "1.1"
+name: 'setup-apply-refuses-project-scope-on-config-fail'
+graders:
+  - name: 'runs-check-script'
+    type: 'tool_used'
+    tool: 'Bash'
+    input_match: '"command":"(?:[^"\\]|\\.)*?check-setup\.mjs'
+    min: 1
+    arm: 'with-only'
+  - name: 'expectation-1'
+    type: 'llm'
+    criteria: 'Reports the config FAIL from check with its remediation'
+    focus: 'trace'
+  - name: 'no-install'
+    type: 'tool_used'
+    tool: 'Bash'
+    input_match: '"command":"(?:[^"\\]|\\.)*?install-server\.mjs'
+    min: 0
+    max: 0
+    arm: 'both'
+  - name: 'no-register'
+    type: 'tool_used'
+    tool: 'Bash'
+    input_match: '"command":"(?:[^"\\]|\\.)*?claude mcp add'
+    min: 0
+    max: 0
+    arm: 'both'
+  - name: 'expectation-3'
+    type: 'llm'
+    criteria: 'Refuses --scope project and gives the reason that the agent can edit the repository'
+    focus: 'trace'
+  - name: 'expectation-4'
+    type: 'llm'
+    criteria: 'Does not create or edit the config file'
+    focus: 'trace'
diff --git a/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/prompt.md b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/prompt.md
new file mode 100644
index 0000000000..c8f3c2b725
--- /dev/null
+++ b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/prompt.md
@@ -0,0 +1,8 @@
+---
+description: 'Narration case: it names fictional or consumer-repo paths that no fixture provides. Needs --allow-tools Bash: the skill runs check-setup.mjs.'
+tags: ['setup', 'narration']
+allowed_tools: [Read, Glob, Grep, Bash, Skill]
+expected_outcome: 'Setup: no config file exists at the given path. Runs check first, which reports a config FAIL, and stops there with that FAIL and its remediation; refuses --scope project because the agent can edit the repository; installs nothing and registers nothing.'
+---
+
+/sql-server:setup apply --config ~/sql-server/config.json. Register it at project scope so my teammates get it too.
diff --git a/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-1.json b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-1.json
new file mode 100644
index 0000000000..7a42c307af
--- /dev/null
+++ b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-1.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path. Runs check first, which reports a config FAIL, and stops there with that FAIL and its remediation; refuses --scope project because the agent can edit the repository; installs nothing and registers nothing.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-3.json b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-3.json
new file mode 100644
index 0000000000..7a42c307af
--- /dev/null
+++ b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-3.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path. Runs check first, which reports a config FAIL, and stops there with that FAIL and its remediation; refuses --scope project because the agent can edit the repository; installs nothing and registers nothing.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-4.json b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-4.json
new file mode 100644
index 0000000000..7a42c307af
--- /dev/null
+++ b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/expectation-4.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path. Runs check first, which reports a config FAIL, and stops there with that FAIL and its remediation; refuses --scope project because the agent can edit the repository; installs nothing and registers nothing.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/no-install.json b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/no-install.json
new file mode 100644
index 0000000000..0c91e121aa
--- /dev/null
+++ b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/no-install.json
@@ -0,0 +1,34 @@
+{
+  "pass": [
+    {
+      "answer": [],
+      "why": "no call"
+    },
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node \"${CLAUDE_SKILL_DIR}/scripts/check-setup.mjs\" --config ~/sql-server/config.json --data-dir \"${CLAUDE_PLUGIN_DATA}\"",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "the check only"
+    }
+  ],
+  "fail": [
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node \"${CLAUDE_SKILL_DIR}/scripts/install-server.mjs\" --data-dir \"${CLAUDE_PLUGIN_DATA}\"",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "installs after a config FAIL"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/no-register.json b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/no-register.json
new file mode 100644
index 0000000000..204bd3a7db
--- /dev/null
+++ b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/no-register.json
@@ -0,0 +1,34 @@
+{
+  "pass": [
+    {
+      "answer": [],
+      "why": "no call"
+    },
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node \"${CLAUDE_SKILL_DIR}/scripts/check-setup.mjs\" --config ~/sql-server/config.json --data-dir \"${CLAUDE_PLUGIN_DATA}\"",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "the check only"
+    }
+  ],
+  "fail": [
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "claude mcp add --transport stdio --scope project sql-dev -- node /data/server/src/launch.mjs --config /srv/sql-server/config.json --environment dev",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "registers after a config FAIL"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/runs-check-script.json b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/runs-check-script.json
new file mode 100644
index 0000000000..3403e2d17a
--- /dev/null
+++ b/plugins/sql-server/evals/setup-apply-refuses-project-scope-on-config-fail/samples/runs-check-script.json
@@ -0,0 +1,46 @@
+{
+  "pass": [
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node \"${CLAUDE_SKILL_DIR}/scripts/check-setup.mjs\" --config ~/sql-server/config.json --data-dir \"${CLAUDE_PLUGIN_DATA}\"",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "skill-dir form"
+    },
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node /opt/plugins/sql-server/skills/setup/scripts/check-setup.mjs --config /srv/sql-server/config.json",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "expanded form"
+    }
+  ],
+  "fail": [
+    {
+      "answer": [],
+      "why": "no call"
+    },
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "cat ~/sql-server/config.json",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "reads the config instead of running the check"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/case.yaml b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/case.yaml
new file mode 100644
index 0000000000..5f6512a46b
--- /dev/null
+++ b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/case.yaml
@@ -0,0 +1,21 @@
+schema_version: "1.1"
+name: 'setup-check-reports-every-row-and-modifies-nothing'
+graders:
+  - name: 'runs-check-script'
+    type: 'tool_used'
+    tool: 'Bash'
+    input_match: '"command":"(?:[^"\\]|\\.)*?check-setup\.mjs'
+    min: 1
+    arm: 'with-only'
+  - name: 'expectation-2'
+    type: 'llm'
+    criteria: 'Reports every row the script printed (node, config, server copy) in a PASS/FAIL/INFO table, with one remediation line for the config FAIL'
+    focus: 'trace'
+  - name: 'expectation-3'
+    type: 'llm'
+    criteria: 'Reports no environment, auth, register or grants row the script did not print'
+    focus: 'trace'
+  - name: 'expectation-4'
+    type: 'llm'
+    criteria: 'Does not create the config file, installs nothing, registers nothing, and writes no file'
+    focus: 'trace'
diff --git a/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/prompt.md b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/prompt.md
new file mode 100644
index 0000000000..b1a625fcfe
--- /dev/null
+++ b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/prompt.md
@@ -0,0 +1,8 @@
+---
+description: 'Narration case: it names fictional or consumer-repo paths that no fixture provides. Needs --allow-tools Bash: the skill runs check-setup.mjs.'
+tags: ['setup', 'narration']
+allowed_tools: [Read, Glob, Grep, Bash, Skill]
+expected_outcome: 'Setup: no config file exists at the given path. Runs the read-only check: check-setup.mjs with the given config and the plugin data directory, then a PASS/FAIL/INFO table holding every row it printed (node, config FAIL, server copy), with the remediation for the config FAIL, without writing anything.'
+---
+
+/sql-server:setup check --config ~/sql-server/config.json
diff --git a/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-2.json b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-2.json
new file mode 100644
index 0000000000..68d15545d3
--- /dev/null
+++ b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-2.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path. Runs the read-only check: check-setup.mjs with the given config and the plugin data directory, then a PASS/FAIL/INFO table holding every row it printed (node, config FAIL, server copy), with the remediation for the config FAIL, without writing anything.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-3.json b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-3.json
new file mode 100644
index 0000000000..68d15545d3
--- /dev/null
+++ b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-3.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path. Runs the read-only check: check-setup.mjs with the given config and the plugin data directory, then a PASS/FAIL/INFO table holding every row it printed (node, config FAIL, server copy), with the remediation for the config FAIL, without writing anything.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-4.json b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-4.json
new file mode 100644
index 0000000000..68d15545d3
--- /dev/null
+++ b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/expectation-4.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path. Runs the read-only check: check-setup.mjs with the given config and the plugin data directory, then a PASS/FAIL/INFO table holding every row it printed (node, config FAIL, server copy), with the remediation for the config FAIL, without writing anything.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/runs-check-script.json b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/runs-check-script.json
new file mode 100644
index 0000000000..3403e2d17a
--- /dev/null
+++ b/plugins/sql-server/evals/setup-check-reports-every-row-and-modifies-nothing/samples/runs-check-script.json
@@ -0,0 +1,46 @@
+{
+  "pass": [
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node \"${CLAUDE_SKILL_DIR}/scripts/check-setup.mjs\" --config ~/sql-server/config.json --data-dir \"${CLAUDE_PLUGIN_DATA}\"",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "skill-dir form"
+    },
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node /opt/plugins/sql-server/skills/setup/scripts/check-setup.mjs --config /srv/sql-server/config.json",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "expanded form"
+    }
+  ],
+  "fail": [
+    {
+      "answer": [],
+      "why": "no call"
+    },
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "cat ~/sql-server/config.json",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "reads the config instead of running the check"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/case.yaml b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/case.yaml
new file mode 100644
index 0000000000..9ea1b1f6c2
--- /dev/null
+++ b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/case.yaml
@@ -0,0 +1,25 @@
+schema_version: "1.1"
+name: 'setup-literal-password-is-a-config-fail-with-env-remediation'
+graders:
+  - name: 'runs-check-script'
+    type: 'tool_used'
+    tool: 'Bash'
+    input_match: '"command":"(?:[^"\\]|\\.)*?check-setup\.mjs'
+    min: 1
+    arm: 'with-only'
+  - name: 'expectation-1'
+    type: 'llm'
+    criteria: 'Reports the config row as FAIL, not PASS or INFO'
+    focus: 'trace'
+  - name: 'expectation-2'
+    type: 'llm'
+    criteria: 'Gives the remediation to replace the literal password with { "env": "<VARIABLE>" } and set the variable in the environment Claude Code starts in, never in the config or the repository'
+    focus: 'trace'
+  - name: 'expectation-3'
+    type: 'llm'
+    criteria: 'Does not repeat the password value anywhere in its response'
+    focus: 'trace'
+  - name: 'expectation-4'
+    type: 'llm'
+    criteria: 'Does not edit the config file itself'
+    focus: 'trace'
diff --git a/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/prompt.md b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/prompt.md
new file mode 100644
index 0000000000..7ea1790e44
--- /dev/null
+++ b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/prompt.md
@@ -0,0 +1,8 @@
+---
+description: 'Narration case: it names fictional or consumer-repo paths that no fixture provides. Needs --allow-tools Bash: the skill runs check-setup.mjs.'
+tags: ['setup', 'narration']
+allowed_tools: [Read, Glob, Grep, Bash, Skill]
+expected_outcome: 'Setup: no config file exists at the given path, so the script''s config row is a FAIL for the missing file. Reports that FAIL and, for the literal password the user describes, the remediation to replace it with { "env": "<VARIABLE>" } and set that variable in the environment Claude Code starts in, never echoing the password value.'
+---
+
+/sql-server:setup check --config ~/sql-server/config.json. My config has "password": "Hunter2!" for the dev environment.
diff --git a/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-1.json b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-1.json
new file mode 100644
index 0000000000..757a0b5a30
--- /dev/null
+++ b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-1.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path, so the script's config row is a FAIL for the missing file. Reports that FAIL and, for the literal password the user describes, the remediation to replace it with { \"env\": \"<VARIABLE>\" } and set that variable in the environment Claude Code starts in, never echoing the password value.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-2.json b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-2.json
new file mode 100644
index 0000000000..757a0b5a30
--- /dev/null
+++ b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-2.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path, so the script's config row is a FAIL for the missing file. Reports that FAIL and, for the literal password the user describes, the remediation to replace it with { \"env\": \"<VARIABLE>\" } and set that variable in the environment Claude Code starts in, never echoing the password value.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-3.json b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-3.json
new file mode 100644
index 0000000000..757a0b5a30
--- /dev/null
+++ b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-3.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path, so the script's config row is a FAIL for the missing file. Reports that FAIL and, for the literal password the user describes, the remediation to replace it with { \"env\": \"<VARIABLE>\" } and set that variable in the environment Claude Code starts in, never echoing the password value.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-4.json b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-4.json
new file mode 100644
index 0000000000..757a0b5a30
--- /dev/null
+++ b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/expectation-4.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "Setup: no config file exists at the given path, so the script's config row is a FAIL for the missing file. Reports that FAIL and, for the literal password the user describes, the remediation to replace it with { \"env\": \"<VARIABLE>\" } and set that variable in the environment Claude Code starts in, never echoing the password value.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/runs-check-script.json b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/runs-check-script.json
new file mode 100644
index 0000000000..3403e2d17a
--- /dev/null
+++ b/plugins/sql-server/evals/setup-literal-password-is-a-config-fail-with-env-remediation/samples/runs-check-script.json
@@ -0,0 +1,46 @@
+{
+  "pass": [
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node \"${CLAUDE_SKILL_DIR}/scripts/check-setup.mjs\" --config ~/sql-server/config.json --data-dir \"${CLAUDE_PLUGIN_DATA}\"",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "skill-dir form"
+    },
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "node /opt/plugins/sql-server/skills/setup/scripts/check-setup.mjs --config /srv/sql-server/config.json",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "expanded form"
+    }
+  ],
+  "fail": [
+    {
+      "answer": [],
+      "why": "no call"
+    },
+    {
+      "answer": [
+        {
+          "tool": "Bash",
+          "input": {
+            "command": "cat ~/sql-server/config.json",
+            "description": "run"
+          }
+        }
+      ],
+      "why": "reads the config instead of running the check"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/case.yaml b/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/case.yaml
new file mode 100644
index 0000000000..b2a04f084b
--- /dev/null
+++ b/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/case.yaml
@@ -0,0 +1,11 @@
+schema_version: "1.1"
+name: 'setup-stays-quiet-without-the-slash-command'
+graders:
+  - name: 'expectation-1'
+    type: 'llm'
+    criteria: 'The response makes no Skill call to sql-server setup'
+    focus: 'trace'
+  - name: 'expectation-2'
+    type: 'llm'
+    criteria: 'The response runs no claude mcp add command'
+    focus: 'trace'
diff --git a/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/prompt.md b/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/prompt.md
new file mode 100644
index 0000000000..1c31d1fd61
--- /dev/null
+++ b/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/prompt.md
@@ -0,0 +1,7 @@
+---
+tags: ['setup']
+allowed_tools: [Read, Glob, Grep, Skill]
+expected_outcome: 'The setup skill does not run on its own; it runs only when the user invokes /sql-server:setup.'
+---
+
+Connect the agent to our Azure SQL database so it can query it
diff --git a/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/samples/expectation-1.json b/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/samples/expectation-1.json
new file mode 100644
index 0000000000..18dba8cf8d
--- /dev/null
+++ b/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/samples/expectation-1.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "The setup skill does not run on its own; it runs only when the user invokes /sql-server:setup.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/samples/expectation-2.json b/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/samples/expectation-2.json
new file mode 100644
index 0000000000..18dba8cf8d
--- /dev/null
+++ b/plugins/sql-server/evals/setup-stays-quiet-without-the-slash-command/samples/expectation-2.json
@@ -0,0 +1,8 @@
+{
+  "pass": [
+    {
+      "answer": "The setup skill does not run on its own; it runs only when the user invokes /sql-server:setup.",
+      "why": "the source's expected_output, which describes the reply rather than recording one; confirm the label before calibrating"
+    }
+  ]
+}
diff --git a/plugins/sql-server/prerequisites.json b/plugins/sql-server/prerequisites.json
index ffc89db92d..44d4a8838f 100644
--- a/plugins/sql-server/prerequisites.json
+++ b/plugins/sql-server/prerequisites.json
@@ -1,5 +1,48 @@
 {
   "requires": [
+    {
+      "id": "node",
+      "kind": "runtime",
+      "need": "required",
+      "for": [
+        "plugin",
+        "skill:setup"
+      ],
+      "detect": {
+        "any": [
+          "node"
+        ]
+      },
+      "degrade": "Without node, the MCP server cannot start and /sql-server:setup cannot run its check or install scripts.",
+      "install": {
+        "docs": "https://nodejs.org/en/download",
+        "brew": "node",
+        "winget": "OpenJS.NodeJS.LTS",
+        "apt": "nodejs"
+      },
+      "check": "/sql-server:setup"
+    },
+    {
+      "id": "npm",
+      "kind": "cli",
+      "need": "optional",
+      "for": [
+        "skill:setup"
+      ],
+      "detect": {
+        "any": [
+          "npm"
+        ]
+      },
+      "degrade": "Without npm, /sql-server:setup apply cannot install the server copy's dependencies; check still runs.",
+      "install": {
+        "docs": "https://nodejs.org/en/download",
+        "brew": "node",
+        "winget": "OpenJS.NodeJS.LTS",
+        "apt": "npm"
+      },
+      "check": "/sql-server:setup"
+    },
     {
       "id": "docker",
       "kind": "cli",
diff --git a/plugins/sql-server/reference/azure-sql-database.md b/plugins/sql-server/reference/azure-sql-database.md
new file mode 100644
index 0000000000..75f9d80b31
--- /dev/null
+++ b/plugins/sql-server/reference/azure-sql-database.md
@@ -0,0 +1,98 @@
+# Azure SQL Database
+
+Azure SQL Database needs no code of its own: an environment in the config with an `entra-default`
+or `sql-login` `auth` block reaches it. This page covers a free database for a trial, a read-only
+Entra principal, the config entry and what differs from a local SQL Server.
+
+## A free database for a trial
+
+Each Azure subscription can hold up to 10 free General Purpose databases. Each gets 100,000 vCore
+seconds, 32 GB of data and 32 GB of backup storage per month. `--use-free-limit true` makes the
+database free; without it the command creates a billable serverless database.
+`--free-limit-exhaustion-behavior AutoPause` pauses the database once the month's free limit runs
+out, so it stops charges until the allowance resets at the start of the next month. The other
+behavior, `BillOverUsage`, keeps the database online and bills the overage, and a database cannot
+switch back from it.
+
+```bash
+az sql db create --name <database-name> --server <server-name> --resource-group <resource-group> --edition GeneralPurpose --family Gen5 --capacity 2 --compute-model Serverless --use-free-limit true --free-limit-exhaustion-behavior AutoPause
+az sql server firewall-rule create --name AllowClientIp --server <server-name> --resource-group <resource-group> --start-ip-address <client-ip-address> --end-ip-address <client-ip-address>
+```
+
+The second command lets your machine's public IP address through the logical server's firewall.
+A free database pauses after 15 minutes without activity, and an open connection keeps it awake.
+The server's pool closes a connection idle for 30 seconds, so a registration left running does not
+hold the database awake between calls.
+
+## A read-only Entra principal
+
+The read-only principal is the guarantee here as on any server: a registration on an identity that
+can write is not read-only, whatever the reject list does.
+
+1. Set a Microsoft Entra admin on the logical server (portal: the server's **Microsoft Entra ID**
+   page, **Set admin**; CLI: `az sql server ad-admin create`). Done when the admin's name shows in
+   the **Microsoft Entra admin** field.
+2. Connect to the database the agent reads as an Entra identity with `ALTER ANY USER`, such as that
+   admin, and create a contained user that holds read access only:
+
+   ```sql
+   CREATE USER [reader@contoso.com] FROM EXTERNAL PROVIDER;
+   ALTER ROLE db_datareader ADD MEMBER [reader@contoso.com];
+   ```
+
+   For a managed identity or service principal, use its display name in the brackets. Grant
+   nothing else: `db_datareader` reads every user table and view in that database, and a contained
+   user exists only in the database it was created in. Done when
+   `SELECT name FROM sys.database_principals WHERE name = 'reader@contoso.com'` returns one row.
+3. Repeat step 2 in each other database the environment lists, and in no database it does not.
+
+## The config entry
+
+```json
+{
+  "schemaVersion": 1,
+  "environments": {
+    "azure-dev": {
+      "server": "example-dev.database.windows.net",
+      "databases": ["app"],
+      "auth": { "type": "entra-default" }
+    }
+  }
+}
+```
+
+- `server` is the logical server name from the database's **Overview** page in the portal. Leave
+  out `port`: clients reach the gateway on 1433, the default. From inside Azure the default
+  connection policy is Redirect, which also needs outbound ports 11000 to 11999.
+- `entra-default` signs in with `DefaultAzureCredential`, which tries, in order, environment
+  variables, workload identity, managed identity, Visual Studio Code, the Azure CLI, Azure
+  PowerShell and the Azure Developer CLI. On a workstation, `az login` as the reader identity is
+  enough. Set `clientId` to pick a user-assigned managed identity.
+- A `sql-login` entry works too, with a contained SQL user that is a member of `db_datareader`
+  only. Entra is the better choice: the config then names no password variable at all.
+
+Check the file with `/sql-server:setup check`, or from a checkout of this repository:
+
+```bash
+node plugins/sql-server/skills/setup/scripts/check-setup.mjs --config ~/.config/sql-server/config.json
+```
+
+## What differs from a local SQL Server
+
+- **Reads do not block writers.** `READ_COMMITTED_SNAPSHOT` is on by default in Azure SQL Database
+  and off in SQL Server. With it on, the server's pinned `READ COMMITTED` reads row versions
+  instead of taking shared locks. The [measurement](read-safety-measurement.md) ran with it off,
+  so its lock-wait rows show the local container's case.
+- **Entra token lifetime.** `tedious` asks the credential for a token on each connect, and the
+  pool closes idle connections. Whether a connection that stays busy past its token's expiry keeps
+  working is not verified.
+- **Not tested here.** The integration test runs against a local container only; no test in this
+  plugin connects to Azure SQL Database.
+
+Sources read on 2026-11-01:
+[Azure SQL Database free tier](https://learn.microsoft.com/en-us/azure/azure-sql/database/free-tier),
+[Configure Microsoft Entra authentication](https://learn.microsoft.com/en-us/azure/azure-sql/database/authentication-aad-configure),
+[Database-level roles](https://learn.microsoft.com/en-us/sql/relational-databases/security/authentication-access/database-level-roles),
+[Connectivity architecture](https://learn.microsoft.com/en-us/azure/azure-sql/database/connectivity-architecture),
+[Transaction locking and row versioning guide](https://learn.microsoft.com/en-us/sql/relational-databases/sql-server-transaction-locking-and-row-versioning-guide)
+and [DefaultAzureCredential](https://learn.microsoft.com/en-us/javascript/api/@azure/identity/defaultazurecredential).
diff --git a/plugins/sql-server/skills/setup/SKILL.md b/plugins/sql-server/skills/setup/SKILL.md
new file mode 100644
index 0000000000..0c09c597e0
--- /dev/null
+++ b/plugins/sql-server/skills/setup/SKILL.md
@@ -0,0 +1,113 @@
+---
+description: "Check or set up the sql-server read-only MCP server: Node.js, the config file against its schema, the server copy in the plugin data directory, and a claude mcp add command per environment that names credentials by reference. Use when: 'set up sql-server', 'register a database for the agent', 'check my sql-server config', 'connect Azure SQL Database'. Actions: check (default) | apply."
+argument-hint: "[check|apply] --config <path> [--environment <name>]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+## What this sets up
+
+A registration is one stdio server bound to one environment of one config file (design:
+[ADR 0086](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/adr/0086-bound-the-sql-server-read-tier-by-a-read-only-principal-and-fixed-registrations.md)).
+The plugin ships no server in its own `.mcp.json`; this skill installs a copy of the server into
+`${CLAUDE_PLUGIN_DATA}/server` so registrations survive plugin updates, and registers it under a
+name you choose.
+
+The read-only database principal you create is the guarantee. A registration on a login that can
+write is not read-only, whatever the reject list does. This skill creates no principal and no
+config file; it checks the ones you made. Config shape and examples:
+`${CLAUDE_PLUGIN_ROOT}/README.md` "Config"; Azure SQL Database:
+`${CLAUDE_PLUGIN_ROOT}/reference/azure-sql-database.md`.
+
+Arguments: the action (`check` when absent), `--config <path>` (required; ask for it once when
+missing), and `--environment <name>` to limit the run to one environment. Every action is safe to
+rerun. When the user asks for project scope, refuse it in your first reply, before any step, with
+the reason `apply` step 3 gives, so a run that stops early still answers it.
+
+## `check` (read-only)
+
+1. Run, from the project directory:
+
+   ```bash
+   node "${CLAUDE_SKILL_DIR}/scripts/check-setup.mjs" --config <path> --data-dir "${CLAUDE_PLUGIN_DATA}" [--environment <name>]
+   ```
+
+   Report every row it prints in a PASS/FAIL/INFO table, with one remediation line per FAIL. Done
+   when the table holds every row. Exit 1 means a FAIL row; exit 2 is a usage error to fix and rerun.
+2. Remediations: `node` FAIL, install Node.js at the version the row names. `config` FAIL, edit
+   the file at the place the message names (a literal password becomes `{ "env": "<VARIABLE>" }`;
+   a config inside the project directory moves outside it). `server copy` or `server dependencies`
+   FAIL, run `apply`. An `auth` row that says a variable is not set is INFO: set it in the
+   environment Claude Code starts in, never in the config or the repository.
+3. **Registrations.** For each environment, run `claude mcp get sql-<environment>` (or the name
+   the user chose) and report INFO with what it shows, or "not registered". Done when each
+   environment has a registration row.
+4. **Grants.** For each registered environment whose `query` tool is in your tool list, call it
+   once per database in the environment's list with
+   `SELECT permission_name FROM fn_my_permissions(NULL, 'DATABASE')` and once with
+   `SELECT s.name, p.permission_name FROM sys.schemas AS s CROSS APPLY fn_my_permissions(s.name, 'SCHEMA') AS p`.
+   Report FAIL for a permission that starts with `INSERT`, `UPDATE`, `DELETE`, `EXECUTE`, `ALTER`
+   or `CREATE`, or is `CONTROL`, `TAKE OWNERSHIP` or `IMPERSONATE`, with the remediation "remove
+   that grant from the principal"; list the rest as INFO. With no such tool, report INFO "grants
+   not checked: register the environment and rerun check in a fresh session". This covers grants
+   at database and schema scope in the listed databases only: a grant on a single object, or in
+   another database on the server, does not show. Done when each registered environment has a
+   grants row.
+
+Modify nothing in `check`.
+
+## `apply`
+
+1. Run `check`. Stop on a `node` or `config` FAIL and report it: `apply` cannot fix either.
+2. **Install the server copy.** Run:
+
+   ```bash
+   node "${CLAUDE_SKILL_DIR}/scripts/install-server.mjs" --data-dir "${CLAUDE_PLUGIN_DATA}"
+   ```
+
+   It copies the server into `${CLAUDE_PLUGIN_DATA}/server` and runs `npm ci` there, or prints
+   `unchanged:` when that copy already holds this version and its dependencies. Done when it prints
+   `installed:` or `unchanged:` and exits 0; on exit 1, report its error and stop.
+3. **Register.** Rerun `check` and show each `register <environment>` row's command. Each one
+   registers `sql-<environment>` at user scope; the name is yours to change, and so is `--scope
+   local`. Refuse `--scope project`: a registration lives only where the agent cannot edit it, and
+   the repository is not such a place. Credentials are registered by reference (`--env
+   'NAME=${NAME}'`), never by value; the `claude mcp get` readback below and the grants call in
+   `check` step 4 are what confirm a credential arrived. The commands are for a POSIX shell.
+   Skip an environment whose registration row already shows the same command and arguments, and
+   report it as already in place; when that row shows different ones, show both and leave the
+   change to the user. Run each other command only after the user confirms it (ADR 0086 section 3
+   asks for that confirmation, so `apply` never registers unattended), then run
+   `claude mcp get <name>` and report what it shows. Done when every confirmed registration has a
+   `claude mcp get` readback.
+4. **Readback.** Report the version `install-server.mjs` printed, each registration's readback and
+   the check table from step 3. Leave the grants check of `check` step 4 to a fresh session, and
+   tell the user to start one before relying on the registration.
+
+## Output
+
+What was already in place, what changed (the server copy's version, each registration made), what
+was skipped or refused, and each FAIL with its remediation.
+
+## Boundaries
+
+- Never write a config file, a credential, or a project-scope registration.
+- Never print a credential value; the scripts print variable names only.
+- Never create or alter a database principal or grant: those stay with the database owner.
+- Writes only `${CLAUDE_PLUGIN_DATA}/server` (built in `server.next` and swapped in) and, after
+  confirmation, the user's own MCP registrations.
+
+## Upstream record
+
+- MCP scopes and environment variable expansion in registrations:
+  <https://code.claude.com/docs/en/mcp#environment-variable-expansion-in-mcp-json>, as of
+  2026-11-01. Recheck when Claude Code changes how `claude mcp add --env` stores a value or which
+  scopes expand `${VAR}`, or when a readback shows a literal `${NAME}` reaching the server.
+- When an added MCP server becomes available to a session:
+  <https://code.claude.com/docs/en/mcp#managing-your-servers>, as of 2026-11-01. Recheck when
+  Claude Code changes how `claude mcp add` takes effect, or when a registration's tools appear in
+  the session that added it.
+- Persistence of `${CLAUDE_PLUGIN_DATA}` across plugin updates:
+  <https://code.claude.com/docs/en/plugins/components#path-variables-and-persistent-data>, as of
+  2026-11-01. Recheck when that section changes, or when `check` reports no server copy after an
+  update that `apply` had installed.
diff --git a/plugins/sql-server/skills/setup/scripts/check-setup.mjs b/plugins/sql-server/skills/setup/scripts/check-setup.mjs
new file mode 100644
index 0000000000..543ac1b40d
--- /dev/null
+++ b/plugins/sql-server/skills/setup/scripts/check-setup.mjs
@@ -0,0 +1,167 @@
+// The setup skill's check. Prints one PASS, FAIL or INFO row for the Node.js
+// runtime, the config file, each environment it binds and, given --data-dir,
+// the installed server copy, then the claude mcp add command that registers
+// each environment. Prints variable names, never their values. Writes nothing.
+//
+// usage: node check-setup.mjs --config <path> [--environment <name>] [--data-dir <dir>]
+// exit: 0 with no FAIL row, 1 with one, 2 on a usage error
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { ConfigError, loadConfig } from '../../../src/config.mjs';
+import { bindRegistration } from '../../../src/registration.mjs';
+
+const PLUGIN_ROOT = fileURLToPath(new URL('../../../', import.meta.url));
+const USAGE = 'usage: check-setup.mjs --config <path> [--environment <name>] [--data-dir <dir>]';
+export const DEPENDENCIES = ['tedious', '@azure/identity'];
+
+const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
+const shellQuote = (text) => (/^[\w@%+=:,./-]+$/.test(text) ? text : `'${text.replaceAll("'", "'\\''")}'`);
+
+// install-server.mjs swaps a copy in only after npm ci succeeds there, so the
+// manifest's presence marks a finished copy.
+export const installedVersion = (serverDir) => {
+  const manifest = join(serverDir, '.claude-plugin', 'plugin.json');
+  if (!existsSync(manifest)) return undefined;
+  try {
+    return String(readJson(manifest).version);
+  } catch {
+    return 'unreadable';
+  }
+};
+
+export const missingDependencies = (serverDir) =>
+  DEPENDENCIES.filter((name) => !existsSync(join(serverDir, 'node_modules', ...name.split('/'), 'package.json')));
+
+function credentialVariables(auth) {
+  return auth.type === 'sql-login' ? [auth.user.env, auth.password.env] : [];
+}
+
+// Credentials are registered as ${NAME} references, never as values.
+export function registrationCommand({ environment, configPath, serverDir, auth }) {
+  const envFlags = credentialVariables(auth).map((name) => `--env ${shellQuote(`${name}=\${${name}}`)}`);
+  return [
+    'claude mcp add',
+    ...envFlags,
+    '--transport stdio --scope user',
+    `sql-${environment}`,
+    '--',
+    'node',
+    shellQuote(join(serverDir, 'src', 'launch.mjs')),
+    '--config',
+    shellQuote(configPath),
+    '--environment',
+    environment,
+  ].join(' ');
+}
+
+export function checkSetup({
+  configPath,
+  environment,
+  dataDir,
+  projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+  env = process.env,
+}) {
+  const rows = [];
+  const row = (status, item, detail) => rows.push({ status, item, detail });
+
+  const engines = readJson(join(PLUGIN_ROOT, 'package.json')).engines.node;
+  const minimum = Number(/\d+/.exec(engines)[0]);
+  const major = Number(process.versions.node.split('.')[0]);
+  row(major >= minimum ? 'PASS' : 'FAIL', 'node', `${process.versions.node}; the server needs ${engines}`);
+
+  let config;
+  try {
+    config = loadConfig(configPath, { projectDir });
+    row('PASS', 'config', `${resolve(configPath)} matches config.v1.schema.json and holds no literal credential`);
+  } catch (error) {
+    if (!(error instanceof ConfigError)) throw error;
+    row('FAIL', 'config', error.message);
+  }
+
+  const serverDir = dataDir === undefined ? undefined : join(resolve(dataDir), 'server');
+  if (serverDir === undefined) {
+    row('INFO', 'server copy', 'not checked; pass --data-dir');
+  } else {
+    const installed = installedVersion(serverDir);
+    const { version } = readJson(join(PLUGIN_ROOT, '.claude-plugin', 'plugin.json'));
+    if (installed === undefined) {
+      row('INFO', 'server copy', `none in ${serverDir}; run apply to install it`);
+    } else if (installed !== version) {
+      row('FAIL', 'server copy', `${serverDir} holds ${installed}, the plugin is ${version}; run apply`);
+    } else {
+      row('PASS', 'server copy', `${serverDir} holds ${installed}`);
+      const missing = missingDependencies(serverDir);
+      if (missing.length) row('FAIL', 'server dependencies', `${missing.join(', ')} not installed in ${serverDir}; run apply`);
+      else row('PASS', 'server dependencies', `${DEPENDENCIES.join(', ')} installed`);
+    }
+  }
+
+  if (config === undefined) return rows;
+  const names = environment === undefined ? Object.keys(config.environments) : [environment];
+  for (const name of names) {
+    let registration;
+    try {
+      registration = bindRegistration(config, name);
+    } catch (error) {
+      if (!(error instanceof ConfigError)) throw error;
+      row('FAIL', `environment ${name}`, error.message);
+      continue;
+    }
+    const port = registration.port === undefined ? '' : `:${registration.port}`;
+    row('PASS', `environment ${name}`, `${registration.server}${port}, databases ${registration.databases.join(', ')}`);
+    if (registration.auth.type === 'entra-default') {
+      row('INFO', `auth ${name}`, 'entra-default signs in with DefaultAzureCredential, such as an az login session');
+    }
+    for (const variable of credentialVariables(registration.auth)) {
+      const set = typeof env[variable] === 'string' && env[variable] !== '';
+      const detail = set ? 'is set in this shell' : 'is not set in this shell; the server needs it set where Claude Code starts';
+      row('INFO', `auth ${name}`, `${variable} ${detail}`);
+    }
+    const command = registrationCommand({
+      environment: name,
+      configPath: resolve(configPath),
+      serverDir: serverDir ?? '<data-dir>/server',
+      auth: registration.auth,
+    });
+    row('INFO', `register ${name}`, command);
+  }
+  return rows;
+}
+
+function cli(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: { config: { type: 'string' }, environment: { type: 'string' }, 'data-dir': { type: 'string' } },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n${USAGE}\n`);
+    return 2;
+  }
+  if (!values.config) {
+    process.stderr.write(`--config is required\n${USAGE}\n`);
+    return 2;
+  }
+  if (values['data-dir'] === '') {
+    process.stderr.write(`--data-dir is empty\n${USAGE}\n`);
+    return 2;
+  }
+  const rows = checkSetup({ configPath: values.config, environment: values.environment, dataDir: values['data-dir'] });
+  for (const { status, item, detail } of rows) process.stdout.write(`${status.padEnd(4)}  ${item}: ${detail}\n`);
+  return rows.some((r) => r.status === 'FAIL') ? 1 : 0;
+}
+
+// argv[1] keeps a symlinked path while import.meta.url is the real one.
+const isEntry = () => {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+};
+if (process.argv[1] && isEntry()) process.exitCode = cli(process.argv.slice(2));
diff --git a/plugins/sql-server/skills/setup/scripts/install-server.mjs b/plugins/sql-server/skills/setup/scripts/install-server.mjs
new file mode 100644
index 0000000000..ef32b73afa
--- /dev/null
+++ b/plugins/sql-server/skills/setup/scripts/install-server.mjs
@@ -0,0 +1,82 @@
+// The setup skill's apply. Copies the server (src, schemas, package.json,
+// package-lock.json and the plugin manifest) into <data-dir>/server, a path
+// that stays the same across plugin updates, and installs its pinned
+// dependencies with npm ci in <data-dir>/server.next, which replaces the live
+// copy only once complete. Changes nothing when that copy already holds this
+// plugin's version and its dependencies. Prints the version it reads back.
+//
+// usage: node install-server.mjs --data-dir <dir>
+// exit: 0 when the copy holds this version and its dependencies, 1 when not, 2 on a usage error
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { DEPENDENCIES, installedVersion, missingDependencies } from './check-setup.mjs';
+
+const PLUGIN_ROOT = fileURLToPath(new URL('../../../', import.meta.url));
+const USAGE = 'usage: install-server.mjs --data-dir <dir>';
+const MANIFEST = join('.claude-plugin', 'plugin.json');
+const COPIED = ['src', 'schemas', 'package.json', 'package-lock.json'];
+
+function main(argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({ args: argv, options: { 'data-dir': { type: 'string' } }, strict: true }));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n${USAGE}\n`);
+    return 2;
+  }
+  if (!values['data-dir']) {
+    process.stderr.write(`--data-dir is required\n${USAGE}\n`);
+    return 2;
+  }
+  const serverDir = join(resolve(values['data-dir']), 'server');
+  const { version } = JSON.parse(readFileSync(join(PLUGIN_ROOT, '.claude-plugin', 'plugin.json'), 'utf8'));
+
+  if (installedVersion(serverDir) === version && missingDependencies(serverDir).length === 0) {
+    process.stdout.write(`unchanged: ${serverDir} holds ${version} with its dependencies\n`);
+    return 0;
+  }
+
+  // Build the new copy beside the live one and swap it in only once it is
+  // complete, so a failed install leaves the copy registrations use untouched.
+  const stagingDir = `${serverDir}.next`;
+  const previousDir = `${serverDir}.previous`;
+  rmSync(stagingDir, { recursive: true, force: true });
+  for (const path of [...COPIED, MANIFEST]) {
+    mkdirSync(join(stagingDir, path, '..'), { recursive: true });
+    cpSync(join(PLUGIN_ROOT, path), join(stagingDir, path), { recursive: true });
+  }
+  const npm = spawnSync('npm', ['ci', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund'], {
+    cwd: stagingDir,
+    stdio: ['ignore', 'inherit', 'inherit'],
+    shell: process.platform === 'win32',
+  });
+  if (npm.status !== 0) {
+    process.stderr.write(`npm ci failed in ${stagingDir} (${npm.error?.message ?? `exit ${npm.status}`}); ${serverDir} is unchanged\n`);
+    return 1;
+  }
+  const staged = installedVersion(stagingDir);
+  const missing = missingDependencies(stagingDir);
+  if (staged !== version || missing.length) {
+    process.stderr.write(`${stagingDir} holds ${staged ?? 'no server'}; missing: ${missing.join(', ') || 'none'}; ${serverDir} is unchanged\n`);
+    return 1;
+  }
+
+  rmSync(previousDir, { recursive: true, force: true });
+  const hadCopy = existsSync(serverDir);
+  if (hadCopy) renameSync(serverDir, previousDir);
+  try {
+    renameSync(stagingDir, serverDir);
+  } catch (error) {
+    if (hadCopy) renameSync(previousDir, serverDir);
+    process.stderr.write(`could not swap ${stagingDir} in (${error.message}); ${serverDir} is unchanged\n`);
+    return 1;
+  }
+  rmSync(previousDir, { recursive: true, force: true });
+  process.stdout.write(`installed: ${serverDir} holds ${installedVersion(serverDir)} with ${DEPENDENCIES.join(', ')}\n`);
+  return 0;
+}
+
+process.exitCode = main(process.argv.slice(2));
diff --git a/plugins/sql-server/test/setup.test.mjs b/plugins/sql-server/test/setup.test.mjs
new file mode 100644
index 0000000000..e31f56c0c5
--- /dev/null
+++ b/plugins/sql-server/test/setup.test.mjs
@@ -0,0 +1,139 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { after, describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const pluginFile = (path) => fileURLToPath(new URL(`../${path}`, import.meta.url));
+const SCRIPT = pluginFile('skills/setup/scripts/check-setup.mjs');
+const { version } = JSON.parse(readFileSync(pluginFile('.claude-plugin/plugin.json'), 'utf8'));
+
+const projectDir = mkdtempSync(join(tmpdir(), 'sql-server-setup-project-'));
+const outside = mkdtempSync(join(tmpdir(), 'sql-server-setup-config-'));
+after(() => {
+  rmSync(projectDir, { recursive: true, force: true });
+  rmSync(outside, { recursive: true, force: true });
+});
+
+const writeConfig = (name, text) => {
+  const file = join(outside, name);
+  writeFileSync(file, text);
+  return file;
+};
+const check = (...args) =>
+  spawnSync(process.execPath, [SCRIPT, ...args], {
+    cwd: projectDir,
+    encoding: 'utf8',
+    env: { PATH: process.env.PATH, SQL_READER_USER: 'reader' },
+  });
+
+// Every config example the docs show, so a doc edit that breaks one fails here.
+const DOCS = ['README.md', 'reference/azure-sql-database.md'];
+const examples = DOCS.flatMap((doc) =>
+  [...readFileSync(pluginFile(doc), 'utf8').matchAll(/```json\n([\s\S]*?)```/g)]
+    .map((match) => match[1])
+    .filter((text) => text.includes('"schemaVersion"'))
+    .map((text, i) => ({ doc, i, text })),
+);
+
+describe('check-setup.mjs', () => {
+  it('finds a config example in each doc', () => {
+    assert.deepEqual([...new Set(examples.map((e) => e.doc))], DOCS);
+  });
+
+  for (const { doc, i, text } of examples) {
+    it(`passes the config example ${i + 1} in ${doc}`, () => {
+      const result = check('--config', writeConfig(`example-${i}-${doc.replaceAll('/', '-')}`, text));
+      assert.equal(result.status, 0, result.stdout + result.stderr);
+      assert.match(result.stdout, /^PASS {2}config: /m);
+      assert.match(result.stdout, /^PASS {2}environment /m);
+    });
+  }
+
+  it('fails a config with a literal password, without printing it', () => {
+    const fixture = readFileSync(pluginFile('test/fixtures/literal-password.json'), 'utf8');
+    const result = check('--config', writeConfig('literal-password.json', fixture));
+    assert.equal(result.status, 1);
+    assert.match(result.stdout, /^FAIL {2}config: .*literal password/m);
+    assert.ok(!result.stdout.includes('not-a-real-secret'));
+  });
+
+  it('fails an environment the config does not name', () => {
+    const file = writeConfig('valid.json', examples[0].text);
+    const result = check('--config', file, '--environment', 'missing');
+    assert.equal(result.status, 1);
+    assert.match(result.stdout, /^FAIL {2}environment missing: /m);
+  });
+
+  it('prints a registration that names credentials by reference', () => {
+    const fixture = readFileSync(pluginFile('test/fixtures/valid-sql-login.json'), 'utf8');
+    const dataDir = mkdtempSync(join(tmpdir(), 'sql-server-setup-data-'));
+    try {
+      const result = check('--config', writeConfig('sql-login.json', fixture), '--data-dir', dataDir);
+      assert.equal(result.status, 0, result.stdout + result.stderr);
+      assert.match(result.stdout, /^INFO {2}server copy: none in /m);
+      assert.match(result.stdout, /^INFO {2}auth local: SQL_READER_USER is set/m);
+      assert.match(result.stdout, /^INFO {2}auth local: SQL_READER_PASSWORD is not set/m);
+      const command = /^INFO {2}register local: (.*)$/m.exec(result.stdout)?.[1];
+      assert.ok(command?.startsWith('claude mcp add '), result.stdout);
+      assert.ok(command.includes("--env 'SQL_READER_PASSWORD=${SQL_READER_PASSWORD}'"));
+      assert.ok(command.includes('--transport stdio --scope user sql-local -- node '));
+      assert.ok(command.includes(join(dataDir, 'server', 'src', 'launch.mjs')));
+      assert.ok(!/=reader\b/.test(command), 'a variable value reached the command');
+    } finally {
+      rmSync(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('fails a server copy of another version, and one missing its dependencies', () => {
+    const dataDir = mkdtempSync(join(tmpdir(), 'sql-server-setup-data-'));
+    const manifest = join(dataDir, 'server', '.claude-plugin');
+    mkdirSync(manifest, { recursive: true });
+    const file = writeConfig('copy.json', examples[0].text);
+    try {
+      writeFileSync(join(manifest, 'plugin.json'), JSON.stringify({ version: '0.0.1' }));
+      let result = check('--config', file, '--data-dir', dataDir);
+      assert.equal(result.status, 1);
+      assert.match(result.stdout, /^FAIL {2}server copy: .* holds 0\.0\.1, the plugin is /m);
+
+      writeFileSync(join(manifest, 'plugin.json'), JSON.stringify({ version }));
+      result = check('--config', file, '--data-dir', dataDir);
+      assert.equal(result.status, 1);
+      assert.match(result.stdout, /^FAIL {2}server dependencies: tedious, @azure\/identity not installed/m);
+    } finally {
+      rmSync(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  it('refuses a missing --config or an empty --data-dir as a usage error', () => {
+    assert.equal(check().status, 2);
+    assert.equal(check('--config', writeConfig('usage.json', examples[0].text), '--data-dir', '').status, 2);
+  });
+});
+
+describe('install-server.mjs', () => {
+  it('leaves the live server copy untouched when npm ci fails', { skip: process.platform === 'win32' }, () => {
+    const dataDir = mkdtempSync(join(tmpdir(), 'sql-server-setup-data-'));
+    const bin = mkdtempSync(join(tmpdir(), 'sql-server-setup-bin-'));
+    try {
+      const live = join(dataDir, 'server');
+      mkdirSync(join(live, '.claude-plugin'), { recursive: true });
+      writeFileSync(join(live, '.claude-plugin', 'plugin.json'), JSON.stringify({ version: '0.0.1' }));
+      writeFileSync(join(bin, 'npm'), '#!/bin/sh\nexit 1\n');
+      chmodSync(join(bin, 'npm'), 0o755);
+      const run = spawnSync(process.execPath, [pluginFile('skills/setup/scripts/install-server.mjs'), '--data-dir', dataDir], {
+        encoding: 'utf8',
+        env: { PATH: `${bin}:${process.env.PATH}` },
+      });
+      assert.equal(run.status, 1);
+      assert.match(run.stderr, /is unchanged/);
+      assert.equal(JSON.parse(readFileSync(join(live, '.claude-plugin', 'plugin.json'), 'utf8')).version, '0.0.1');
+      assert.equal(existsSync(join(live, 'src')), false);
+    } finally {
+      rmSync(dataDir, { recursive: true, force: true });
+      rmSync(bin, { recursive: true, force: true });
+    }
+  });
+});