Skip to content

The design language that makes your AI harness better at design.

JavaScript

Docs: clarify live mode development scope (#753)

Paul Bakausdfb33f7d57e2
diff --git a/README.md b/README.md
index 92541b799..d0bf44edb 100644
--- a/README.md
+++ b/README.md
@@ -426,6 +426,12 @@ npx impeccable install
npx impeccable update
```
+## Live mode and production sites
+
+Live mode edits a local checkout through a development server or local static HTML. Injecting its localhost HTTP helper into a deployed production site, including an HTTPS site, is not supported. Do not disable browser security or weaken production CSP to make it work.
+
+For production inspection, use `npx impeccable detect https://example.com` or the browser extension. These inspect the rendered page; they do not provide live variant editing or write changes back to your source.
+
## CLI
Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness. `npx impeccable` is a small shim that runs the same engine binary the skill uses (installed as a platform-specific optional dependency, or fetched once into `~/.impeccable/bin/`); Node is needed only for `npx` itself, and you can also download the binary directly and put it on your PATH.
diff --git a/skill/reference/live-setup.md b/skill/reference/live-setup.md
index c1e6d1931..274f8c3bd 100644
--- a/skill/reference/live-setup.md
+++ b/skill/reference/live-setup.md
@@ -42,6 +42,8 @@ On every boot the project is scanned for HTML files under common page roots (`pu
## CSP detection (first-time only)
+Keep all allowances below development-only, including manual middleware and meta-tag edits. Do not change a deployed production site's CSP to load the localhost helper; see [live.md](live.md) for production inspection alternatives.
+
If `config.cspChecked === true`, skip this whole section; the user was already asked once.
```bash
diff --git a/skill/reference/live.md b/skill/reference/live.md
index ea7d75f70..5823d3407 100644
--- a/skill/reference/live.md
+++ b/skill/reference/live.md
@@ -4,6 +4,8 @@ Interactive live variant mode: select elements in the browser, pick a design act
A running dev server with HMR (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser. If the dev server's default port is busy, the app is very likely ALREADY running; probe the default URL before spawning a second server.
+Live editing requires a local checkout; injection into deployed production sites (including HTTPS) is unsupported. For production inspection, use `{{scripts_path}}/impeccable detect <url>` or the browser extension, not the live helper. Do not disable browser security or weaken production CSP to enable live mode.
+
<codex>
Codex: run live helper commands, the app dev server, and any dependency-installing setup with `sandbox_permissions: "require_escalated"` from the start; live mode depends on localhost and package-manager network access that the sandbox blocks.
</codex>