diff --git a/README.md b/README.md
index 8279af3..ae3c2b3 100644
--- a/README.md
+++ b/README.md
@@ -69,3 +69,38 @@ bun run --cwd examples/component-showcase check
Review representative component pages at mobile, tablet, and desktop widths and
in light, dark, keyboard-only, and reduced-motion modes before publishing.
+
+## Design Studio on the deployed site
+
+The navigation opens `/design-studio/`. It includes guided alternatives, decision
+locks, natural-language edits, component recipes, previews and portable exports.
+Drafts and incomplete source edits remain in each browser's local storage; use
+Export raw draft before clearing browser data or changing the site's origin.
+The hosted demo uses local rule generation, needs no AI credentials, and cannot
+apply designs to server files or access agent workspaces.
+
+On the VM, pull this repository and use Bun 1.3 or newer:
+
+```sh
+git pull --ff-only
+bun install --frozen-lockfile
+bun run check
+PORT=3000 bun run start
+```
+
+`start` runs the production component site and an export-only Studio sidecar
+bound to loopback port 4320. Include `deploy/nginx-design-studio.conf` inside your
+existing nginx server block, retain its existing component-site proxy, validate
+with `nginx -t`, then reload nginx. The proxy must preserve `/design-studio/` and
+Host, and pass Origin unchanged. If port 4320 is occupied, set DESIGN_STUDIO_PORT
+and update the proxy upstream to the same port. Manage the `bun run start`
+process using your existing service manager and restart it after each build.
+
+The private `@wrnexus` registry is configured in `.npmrc`. Supply registry
+credentials on the VM through its user configuration or secret store; no tokens
+are committed. Dependencies are pinned and bun.lock is the deployment lock.
+A refreshed package-lock.json is retained for npm tooling, but Bun runs the app.
+
+After deployment, check `/`, a component playground and `/design-studio/`.
+Create a draft, generate alternatives, open a preview, export JSON, then reload
+and confirm draft recovery. Existing Studio drafts on other origins remain there.
diff --git a/app/layouts/showcase.wrn b/app/layouts/showcase.wrn
index c0db2c9..0862aa6 100644
--- a/app/layouts/showcase.wrn
+++ b/app/layouts/showcase.wrn
@@ -9,7 +9,7 @@ layout Showcase {