diff --git a/src/content/docs/FAQ Troubleshooting/Errors/error-ai-assistant-blocked-patchstack-connect-install.md b/src/content/docs/FAQ Troubleshooting/Errors/error-ai-assistant-blocked-patchstack-connect-install.md
new file mode 100644
index 00000000..8f3b55c6
--- /dev/null
+++ b/src/content/docs/FAQ Troubleshooting/Errors/error-ai-assistant-blocked-patchstack-connect-install.md
@@ -0,0 +1,12 @@
+---
+title: "Error: my AI assistant blocked the @patchstack/connect install"
+excerpt: "Claude Code or another coding assistant refused to run npm install or npx @patchstack/connect setup"
+hidden: false
+createdAt: "Wed Sep 30 2026 00:00:00 GMT+0000 (Coordinated Universal Time)"
+updatedAt: "Wed Sep 30 2026 00:00:00 GMT+0000 (Coordinated Universal Time)"
+---
+Some coding assistants, Claude Code among them, stop commands that download or run a package from npm. That can block `npm install --save-dev @patchstack/connect` or `npx @patchstack/connect setup` part-way through connecting a JavaScript or Node.js project.
+
+Running the blocked command yourself is fine. In Claude Code, type it in the prompt with `!` in front — for example `! npx @patchstack/connect setup` — so it runs in your session and Claude can see the output and finish the install.
+
+See [My AI assistant blocked a Connect command](/getting-started/installing-patchstack/ai-assistant-blocked-a-command/) for the full steps, including other assistants and a permission rule that lets Claude Code run the Connect commands itself.
diff --git a/src/content/docs/Getting Started/Installing Patchstack/ai-assistant-blocked-a-command.mdx b/src/content/docs/Getting Started/Installing Patchstack/ai-assistant-blocked-a-command.mdx
new file mode 100644
index 00000000..c5a5f10b
--- /dev/null
+++ b/src/content/docs/Getting Started/Installing Patchstack/ai-assistant-blocked-a-command.mdx
@@ -0,0 +1,110 @@
+---
+title: "My AI assistant blocked a Connect command"
+excerpt: "Claude Code or another coding assistant refused to run npm install or npx @patchstack/connect setup. Run the command yourself — in Claude Code, with the ! prefix — and let the assistant carry on."
+hidden: false
+createdAt: "Wed Sep 30 2026 00:00:00 GMT+0000 (Coordinated Universal Time)"
+updatedAt: "Wed Sep 30 2026 00:00:00 GMT+0000 (Coordinated Universal Time)"
+sidebar:
+ order: 7.5
+ label: "AI assistant blocked a command"
+---
+
+import { Steps, Aside } from '@astrojs/starlight/components';
+
+Coding assistants such as Claude Code check each shell command before running it, and some of those checks stop a command that downloads or runs a package from npm. Installing [`@patchstack/connect`](/getting-started/installing-patchstack/installing-on-javascript-node-projects/) involves both, so the install can stop part-way with a message like one of these:
+
+```text
+Auto mode's safety check blocked the install and flagged it as bringing
+untrusted code into the project. Nothing has changed.
+```
+
+```text
+I installed @patchstack/connect as a dependency, but I haven't set it up.
+My permission check blocked running the package's own setup command, because
+that means running code downloaded from npm on your machine.
+```
+
+The commands that usually get stopped are the install itself (`npm install --save-dev @patchstack/connect`, or the `pnpm`, `yarn` or `bun` equivalent) and `npx @patchstack/connect setup`.
+
+**Running the command yourself is fine.** It is the same command the assistant was about to run, it changes only what [`setup` is documented to change](/getting-started/installing-patchstack/installing-on-javascript-node-projects/#install), and it sends Patchstack dependency names and versions only — see [Security and data handling](/getting-started/installing-patchstack/installing-on-javascript-node-projects/#security-and-data-handling).
+
+
+
+## In Claude Code: run it with `!`
+
+Type the command in the Claude Code prompt with `!` in front of it. Claude Code runs it in your session straight away, without the permission check, and the output lands in the conversation — so Claude sees the result and can finish the rest of the install.
+
+
+
+1. **Run whichever command was blocked.** If the install was blocked, install the package with the project's package manager:
+
+ ```text
+ ! npm install --save-dev @patchstack/connect
+ ```
+
+ If the install went through and `setup` was blocked, run `setup`:
+
+ ```text
+ ! npx @patchstack/connect setup
+ ```
+
+ If the message you pasted from the app carried a claim token (you ticked **Connect this website to my account automatically**), keep it on the command so the site is created attached to your account:
+
+ ```text
+ ! npx @patchstack/connect setup --claim-token
+ ```
+
+2. **Let Claude continue.** Once the command finishes, tell Claude to carry on — for example with the prompt below. It picks up from the output it can now see: finishing anything `setup` lists as missing, running the build, and handing you the dashboard link.
+
+3. **Check server-side protection, if your app has a server.** For an Express, Fastify, or other server app, confirm the protection is wired up:
+
+ ```text
+ ! npx @patchstack/connect protect --check
+ ```
+
+
+
+```text
+I ran the blocked Patchstack command myself; the output is above. Please
+continue the @patchstack/connect install from there: finish anything setup
+lists as missing, run the complete production build, and give me the
+Patchstack dashboard link. Tell me if any other command is blocked instead of
+reporting the install as complete.
+```
+
+### Allow the Connect commands for this project
+
+If you would rather Claude Code ran the Connect commands itself — for example because you reinstall or rescan often — add an allow rule to `.claude/settings.json` in the project, then ask Claude to retry:
+
+```json
+{
+ "permissions": {
+ "allow": [
+ "Bash(npx @patchstack/connect:*)"
+ ]
+ }
+}
+```
+
+Add the rule yourself. Claude Code will usually decline to edit its own permissions to get past a check that has just stopped it.
+
+## In other assistants and site builders
+
+Codex, OpenCode, Gemini CLI, Cursor and the rest each have their own approval settings, but the fix is the same: run the blocked command yourself from the project folder, then tell the assistant it has been run.
+
+
+
+1. Open a terminal in the project folder — the one containing `package.json`.
+2. Run the command the assistant was blocked on, using the project's package manager (check the lockfile: `package-lock.json` is npm, `pnpm-lock.yaml` is pnpm, `yarn.lock` is yarn, `bun.lock` or `bun.lockb` is bun).
+3. Paste the command's output into the chat along with the prompt above, so the assistant continues from where the command left off instead of starting again.
+
+
+
+Site builders such as Lovable, GoDaddy Airo and Hostinger Horizons do not always give you a terminal. If yours has none and the assistant cannot run the install, ask it to name the exact step it cannot perform — the [builder context](/getting-started/installing-patchstack/troubleshooting-javascript-node-projects/#tell-your-builder-what-project-this-is) snippets help with that.
+
+## Still stuck?
+
+- `npx @patchstack/connect guide` prints a project-aware checklist of what is present and what is missing, so you can see how far the install got.
+- [Troubleshooting JS / Node.js](/getting-started/installing-patchstack/troubleshooting-javascript-node-projects/) covers what can go wrong after the install: a widget that never appears, a stale published build, or an outdated Connect version.
diff --git a/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md b/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md
index fa8725af..e73c44d1 100644
--- a/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md
+++ b/src/content/docs/Getting Started/Installing Patchstack/installing-on-javascript-node-projects.md
@@ -30,6 +30,8 @@ npm install --save-dev @patchstack/connect # or: pnpm add -D / yarn add -D / b
npx --no-install patchstack-connect setup
```
+If your coding assistant refuses to run either command — Claude Code's permission check sometimes stops installs from npm — run it yourself; see [My AI assistant blocked a Connect command](/getting-started/installing-patchstack/ai-assistant-blocked-a-command/).
+
`setup` applies a bounded, idempotent set of changes and nothing else:
1. **Scans the lockfile and sends the dependency manifest** (package names and versions) to Patchstack.
@@ -121,7 +123,7 @@ Reporting stops immediately. Local removal does not delete the site record on Pa
## Troubleshooting
-A widget that never appears, a published site serving an old build, a broken config file, or a Connect install stuck on an old version are all covered — with copy-paste prompts for AI site builders — in [Troubleshooting JavaScript / Node.js projects](/getting-started/installing-patchstack/troubleshooting-javascript-node-projects/).
+A widget that never appears, a published site serving an old build, a broken config file, or a Connect install stuck on an old version are all covered — with copy-paste prompts for AI site builders — in [Troubleshooting JavaScript / Node.js projects](/getting-started/installing-patchstack/troubleshooting-javascript-node-projects/). If the assistant never got that far because it would not run `npm install` or `setup`, see [My AI assistant blocked a Connect command](/getting-started/installing-patchstack/ai-assistant-blocked-a-command/).
## How this relates to host-level npm protection
diff --git a/src/content/docs/Getting Started/Installing Patchstack/troubleshooting-javascript-node-projects.mdx b/src/content/docs/Getting Started/Installing Patchstack/troubleshooting-javascript-node-projects.mdx
index 90213d68..c104e120 100644
--- a/src/content/docs/Getting Started/Installing Patchstack/troubleshooting-javascript-node-projects.mdx
+++ b/src/content/docs/Getting Started/Installing Patchstack/troubleshooting-javascript-node-projects.mdx
@@ -13,6 +13,8 @@ import { Steps, Aside } from '@astrojs/starlight/components';
This page covers the problems that come up after connecting a JavaScript or Node.js project with [`@patchstack/connect`](/getting-started/installing-patchstack/installing-on-javascript-node-projects/): a Patchstack Connector that never appears, a widget that appears twice, a published site still serving an old integration, a build that broke after a config change, a Connect install stuck on an old version, and an update that will not take because the package manager is holding the release back.
+If the install never finished because your AI assistant refused to run `npm install` or `npx @patchstack/connect setup`, start with [My AI assistant blocked a Connect command](/getting-started/installing-patchstack/ai-assistant-blocked-a-command/) instead.
+
Every section ends with a **prompt you can paste into your site builder's AI chat**. The prompts are deliberately explicit about proving the result, because builder assistants otherwise tend to report the version they remember, or stop after editing one file.