From dfb33f7d57e22ea847e7ec4c04e3001539b5ab24 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Sun, 6 Sep 2026 16:20:27 -0700 Subject: [PATCH] Docs: clarify live mode development scope (#753) Document the local-development boundary and route production inspection to URL detection or the extension. Keep manual CSP allowances development-only. Related to #539. AI assistance: Codex, under maintainer direction. --- README.md | 6 ++++++ skill/reference/live-setup.md | 2 ++ skill/reference/live.md | 2 ++ 3 files changed, 10 insertions(+) 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 ` or the browser extension, not the live helper. Do not disable browser security or weaken production CSP to enable live mode. + 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.