diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md index 2f96bfdf..1b49ebe6 100644 --- a/AGENT-INSTALL.md +++ b/AGENT-INSTALL.md @@ -283,6 +283,36 @@ Handle it in this order: run them, the person runs `npx @patchstack/connect claim` (or `login`) themselves and you relay the link from their output. +### When the platform blocks the CLI outright + +Some hosted builders refuse any third-party CLI that contacts an outside service, and offer the person +neither a terminal nor a way to approve it. Then none of the options above exists in that workspace, and +running the command again, under any spelling, gets the same answer. Step 1 still applies: do not route +around the block, and leave `package.json` and the source tree as they were. + +Tell the person in plain words that this platform will not run Patchstack's setup, then give them these +choices and wait for theirs: + +- **Run setup on a copy of the project outside the builder.** Offer this only when the builder can export + the project or sync it with a git repository; if you do not know whether it can, say so. In that copy, + the person runs `npx @patchstack/connect setup` — without `PATCHSTACK_ENVIRONMENT=sandbox`, which is for + a hosted workspace; on their own machine a scan reports `local` by itself. They then bring the changes + back the same way. `.patchstackrc.local.json` stays behind: it holds the API key and is git-ignored. If + the builder's own install or build cannot reach Patchstack, the scan steps `setup` added print the error + and let it continue, so the app still builds and only that build's report is missing. The exception is a + builder that installs with `bun install`: there the `postinstall` scan fails the install, so remove that + one script before bringing the changes back. +- **Add only the Patchstack Connector.** The person creates an "Application" site in the Patchstack + dashboard and gives you its site ID or widget snippet, and you add the tag as in steps 2 and 3 of + "Plain HTML sites", in the app's root HTML shell or layout. This adds the widget and nothing else: no + check of the app's packages, no build steps, no runtime protection. Say that when you offer it. +- **Stop here.** Nothing else changes. + +If you installed `@patchstack/connect` for this attempt, it stays in `dependencies` with nothing wired to +run it. Keep it for the first choice; for the other two, offer to remove it with the project's package +manager. Report the result as **Patchstack setup did not run on this platform**, with the choice the person +made, not as an installation. + ## Manual setup 1. **First scan** — provisions a Patchstack site automatically, writes the UUID to `.patchstackrc.json`, and installs the Patchstack Connector's `