webcake-landing-mcp 1.0.21 → 1.0.23

package/README.md

@@ -221,7 +221,8 @@ lands in logs). Any header that's missing falls back to the matching env var:
 | `x-webcake-env` | `WEBCAKE_ENV` | named environment (`local`/`staging`/`prod`) |
 | `x-webcake-org-id` | `WEBCAKE_ORG_ID` | default org |
 | `x-webcake-api-base` | `WEBCAKE_API_BASE` | overrides the env preset's API base |
-| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | overrides the env preset's app base |
+| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | overrides the env preset's SPA base (login connect page) |
+| `x-webcake-builder-base` | `WEBCAKE_BUILDER_BASE` | overrides the builder host used for editor/preview links |
 
 > The reference + generation tools (`get_generation_guide`, `list_elements`, `validate_page`, …) need **no
 > token** — only the persistence tools (`create_page`, `update_page`, …) use it. Without a JWT, those return
@@ -290,7 +291,8 @@ flow can also be done entirely in the SPA, no backend route needed.)
 | `WEBCAKE_API_BASE` | No* | Backend base URL, e.g. `http://localhost:5800`. Required to persist (or set `WEBCAKE_ENV`). |
 | `WEBCAKE_JWT` | No* | Account JWT (dashboard auth). Required to persist — expires, refresh when needed. |
 | `WEBCAKE_ORG_ID` | No | Default organization id for `create_page` (overridden by its `organization_id` arg). Omit → personal page. |
-| `WEBCAKE_APP_BASE` | No | Optional base used to build editor/preview URLs in the result. |
+| `WEBCAKE_APP_BASE` | No | Optional SPA base — used for the browser `login` connect page. |
+| `WEBCAKE_BUILDER_BASE` | No | Optional builder host for the editor/preview links in the result. Defaults to the env preset, else derived from the API host (`api.x`→`builder.x`). |
 | `WEBCAKE_CONFIG_DIR` | No | Dir for the saved `auth.json` written by `login` (default `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` and `WEBCAKE_JWT` are only needed for the persistence tools. The reference and
@@ -304,11 +306,13 @@ flow can also be done entirely in the SPA, no backend route needed.)
 Instead of setting both base URLs by hand, pick a named environment — one source of
 truth for the API + app bases:
 
-| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) |
-|-------------------------|-------------------------------|-------------------------------|
-| `local` | `http://localhost:5800` | `http://localhost:5173` |
-| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` |
-| `prod` | `https://api.webcake.io` | `https://webcake.io` |
+| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) | Builder base (`WEBCAKE_BUILDER_BASE`) |
+|-------------------------|-------------------------------|-------------------------------|----------------------------------------|
+| `local` | `http://localhost:5800` | `http://localhost:5173` | `http://builder.localhost:5800` |
+| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` | `https://builder.staging.webcake.io` |
+| `prod` | `https://api.webcake.io` | `https://webcake.io` | `https://builder.webcake.io` |
+
+> The **editor/preview link** returned after `create_page`/`update_page` opens on the **builder host** (above), not the API or SPA base.
 
 ```bash
 npx -y webcake-landing-mcp login --env local       # connect against your local SPA + API

package/README.vi.md

@@ -221,7 +221,8 @@ Header nào thiếu sẽ fallback về biến env tương ứng:
 | `x-webcake-env` | `WEBCAKE_ENV` | môi trường có tên (`local`/`staging`/`prod`) |
 | `x-webcake-org-id` | `WEBCAKE_ORG_ID` | org mặc định |
 | `x-webcake-api-base` | `WEBCAKE_API_BASE` | ghi đè API base của preset |
-| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | ghi đè app base của preset |
+| `x-webcake-app-base` | `WEBCAKE_APP_BASE` | ghi đè SPA base của preset (trang connect khi `login`) |
+| `x-webcake-builder-base` | `WEBCAKE_BUILDER_BASE` | ghi đè host builder dùng cho link editor/preview |
 
 > Tool tham chiếu + generation (`get_generation_guide`, `list_elements`, `validate_page`, …) **không cần
 > token** — chỉ tool lưu trữ (`create_page`, `update_page`, …) mới dùng. Không có JWT thì các tool đó trả
@@ -285,7 +286,8 @@ SPA cũng được, khỏi cần route backend.)
 | `WEBCAKE_API_BASE` | Không* | Base URL backend, ví dụ `http://localhost:5800`. Cần để lưu trang (hoặc đặt `WEBCAKE_ENV`). |
 | `WEBCAKE_JWT` | Không* | JWT tài khoản (auth dashboard). Cần để lưu trang — sẽ hết hạn, làm mới khi cần. |
 | `WEBCAKE_ORG_ID` | Không | Organization mặc định cho `create_page` (bị ghi đè bởi tham số `organization_id`). Bỏ trống → trang cá nhân. |
-| `WEBCAKE_APP_BASE` | Không | Base tuỳ chọn để dựng URL editor/preview trong kết quả. |
+| `WEBCAKE_APP_BASE` | Không | SPA base tuỳ chọn — dùng cho trang connect khi `login` qua trình duyệt. |
+| `WEBCAKE_BUILDER_BASE` | Không | Host builder tuỳ chọn cho link editor/preview trong kết quả. Mặc định lấy theo preset môi trường, nếu không thì suy ra từ host API (`api.x`→`builder.x`). |
 | `WEBCAKE_CONFIG_DIR` | Không | Thư mục chứa `auth.json` do `login` ghi (mặc định `~/.webcake-landing-mcp`). |
 
 > \* `WEBCAKE_API_BASE` và `WEBCAKE_JWT` chỉ cần cho các tool lưu trữ. Các tool tham chiếu và kiểm tra
@@ -299,11 +301,13 @@ SPA cũng được, khỏi cần route backend.)
 Thay vì đặt thủ công cả hai base URL, hãy chọn một môi trường có tên — một nguồn sự thật duy nhất
 cho API + app base (mặc định là `prod`):
 
-| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) |
-|-------------------------|-------------------------------|-------------------------------|
-| `local` | `http://localhost:5800` | `http://localhost:5173` |
-| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` |
-| `prod` *(mặc định)* | `https://api.webcake.io` | `https://webcake.io` |
+| `--env` / `WEBCAKE_ENV` | API base (`WEBCAKE_API_BASE`) | App base (`WEBCAKE_APP_BASE`) | Builder base (`WEBCAKE_BUILDER_BASE`) |
+|-------------------------|-------------------------------|-------------------------------|----------------------------------------|
+| `local` | `http://localhost:5800` | `http://localhost:5173` | `http://builder.localhost:5800` |
+| `staging` | `https://api.staging.webcake.io` | `https://staging.webcake.io` | `https://builder.staging.webcake.io` |
+| `prod` *(mặc định)* | `https://api.webcake.io` | `https://webcake.io` | `https://builder.webcake.io` |
+
+> **Link editor/preview** trả về sau `create_page`/`update_page` mở trên **host builder** (bảng trên), không phải API hay SPA base.
 
 ```bash
 npx -y webcake-landing-mcp login --env local       # đăng nhập vào SPA + API local

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.23",
+    "d": "07/06/2026",
+    "type": "Added",
+    "en": "The GET / guide page now includes a dark/light theme toggle button in the header; the preference is saved in localStorage and applied before the…",
+    "vi": "Trang hướng dẫn GET / nay có nút chuyển chế độ sáng/tối trong header; lựa chọn được lưu vào localStorage và áp dụng trước khi trang hiển thị để…"
+  },
+  {
+    "v": "1.0.22",
+    "d": "07/06/2026",
+    "type": "Added",
+    "en": "New WEBCAKE_BUILDER_BASE environment variable, x-webcake-builder-base HTTP header, and ?builder_base= query parameter set the page-builder host used…",
+    "vi": "Biến môi trường WEBCAKE_BUILDER_BASE mới, HTTP header x-webcake-builder-base, và tham số truy vấn ?builder_base= cho phép đặt host của page-builder…"
+  },
   {
     "v": "1.0.21",
     "d": "07/06/2026",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "new_element for list-product now seeds a default styles.colorBtn (rgba(246,4,87,1)) so generated product-list button labels have a visible accent…",
     "vi": "new_element cho list-product nay gán sẵn styles.colorBtn mặc định (rgba(246,4,87,1)) để nhãn nút của danh sách sản phẩm có màu nhấn nhìn thấy được…"
-  },
-  {
-    "v": "1.0.17",
-    "d": "07/06/2026",
-    "type": "Fixed",
-    "en": "get_element and get_generation_guide no longer suggest https://picsum.photos as an alternative image placeholder; agents are now directed to use…",
-    "vi": "get_element và get_generation_guide không còn gợi ý https://picsum.photos làm ảnh placeholder thay thế; agent nay được hướng dẫn chỉ dùng…"
-  },
-  {
-    "v": "1.0.16",
-    "d": "06/06/2026",
-    "type": "Changed",
-    "en": "The server icon (served at /favicon.svg and embedded in serverInfo.icons) has been refined to the official Webcake brand mark: a green-gradient…",
-    "vi": "Icon server (phục vụ tại /favicon.svg và nhúng trong serverInfo.icons) đã được tinh chỉnh về đúng logo thương hiệu Webcake: ô bo góc gradient xanh…"
   }
 ]

package/dist/http.js

@@ -45,6 +45,7 @@ const QUERY_AUTH = {
     api_base: "x-webcake-api-base",
     org_id: "x-webcake-org-id",
     app_base: "x-webcake-app-base",
+    builder_base: "x-webcake-builder-base",
 };
 function applyQueryAuth(req) {
     const q = (req.url ?? "").indexOf("?");

package/dist/persistence/config.js

@@ -18,7 +18,9 @@
  *   WEBCAKE_API_BASE  e.g. http://localhost:5800   (required to call the backend)
  *   WEBCAKE_JWT       the account JWT               (required to call the backend)
  *   WEBCAKE_ORG_ID    optional default organization id for create_page
- *   WEBCAKE_APP_BASE  optional base for editor/preview URLs in the result
+ *   WEBCAKE_APP_BASE  optional SPA base (used for the login connect page)
+ *   WEBCAKE_BUILDER_BASE  optional builder host for editor/preview URLs in the result
+ *                     (defaults to the env preset, else derived from the API host)
  *   WEBCAKE_CONFIG_DIR  optional dir for the saved auth.json (default ~/.webcake-landing-mcp)
  */
 import { homedir } from "node:os";
@@ -29,12 +31,14 @@ import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
  * base URLs. Selecting one (via the `--env` flag, WEBCAKE_ENV, the `x-webcake-env`
  * header, or `?env=` in the URL) fills in both bases so callers don't repeat them.
  * Explicit WEBCAKE_API_BASE / WEBCAKE_APP_BASE (or per-request overrides) win over
- * the preset. `apiBase` is the backend; `appBase` is the SPA (editor/preview/connect).
+ * the preset. `apiBase` is the backend; `appBase` is the SPA (login connect page);
+ * `builderBase` is the page builder host that serves the `/editor/v2` URL returned
+ * after create/update (a distinct host — NOT the API and NOT the SPA).
  */
 export const ENVIRONMENTS = {
-    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173" },
-    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io" },
-    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io" },
+    local: { apiBase: "http://localhost:5800", appBase: "http://localhost:5173", builderBase: "http://builder.localhost:5800" },
+    staging: { apiBase: "https://api.staging.webcake.io", appBase: "https://staging.webcake.io", builderBase: "https://builder.staging.webcake.io" },
+    prod: { apiBase: "https://api.webcake.io", appBase: "https://webcake.io", builderBase: "https://builder.webcake.io" },
 };
 export const ENV_NAMES = Object.keys(ENVIRONMENTS);
 /** True when `v` names a known environment (local|staging|prod). */
@@ -45,6 +49,23 @@ export function isEnvName(v) {
 export function resolveEnv(name) {
     return isEnvName(name) ? ENVIRONMENTS[name] : undefined;
 }
+/**
+ * Derive the page-builder host from the API base when no preset / explicit value is
+ * given: `api.<domain>` → `builder.<domain>`, otherwise `builder.<host>` (so
+ * `http://localhost:5800` → `http://builder.localhost:5800`, matching the presets).
+ */
+export function deriveBuilderBase(apiBase) {
+    if (!apiBase)
+        return undefined;
+    try {
+        const u = new URL(apiBase);
+        u.hostname = u.hostname.startsWith("api.") ? `builder.${u.hostname.slice(4)}` : `builder.${u.hostname}`;
+        return u.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function readConfig(overrides = {}) {
     const saved = readSavedConfig();
     // A named environment supplies default base URLs; explicit values still win.
@@ -58,12 +79,22 @@ export function readConfig(overrides = {}) {
         missing.push("WEBCAKE_JWT");
     if (missing.length)
         return { config: null, missing };
+    const cleanBase = base.replace(/\/+$/, "");
+    // The editor/preview URL lives on the builder host (e.g. builder.localhost:5800),
+    // not the API base (5800) nor the SPA (5173). Resolve it explicitly so the link
+    // returned to the user opens in the page builder.
+    const builderBase = (overrides.builderBase ??
+        process.env.WEBCAKE_BUILDER_BASE ??
+        preset?.builderBase ??
+        saved.builderBase ??
+        deriveBuilderBase(cleanBase))?.replace(/\/+$/, "");
     return {
         config: {
-            base: base.replace(/\/+$/, ""),
+            base: cleanBase,
             jwt: jwt,
             orgId: overrides.orgId ?? process.env.WEBCAKE_ORG_ID ?? saved.orgId,
             appBase: (overrides.appBase ?? process.env.WEBCAKE_APP_BASE ?? preset?.appBase ?? saved.appBase)?.replace(/\/+$/, ""),
+            builderBase,
         },
         missing: [],
     };
@@ -79,7 +110,8 @@ function header(headers, name) {
  *   x-webcake-org-id     organization id
  *   x-webcake-env        named environment (local|staging|prod) for the base URLs
  *   x-webcake-api-base   backend base URL (overrides the env preset)
- *   x-webcake-app-base   editor/preview URL base (overrides the env preset)
+ *   x-webcake-app-base   SPA base used for the login connect page (overrides the preset)
+ *   x-webcake-builder-base  builder host for editor/preview URLs (overrides the preset)
  * Any header that is absent falls back to the corresponding env var in readConfig.
  */
 export function configFromHeaders(headers) {
@@ -90,6 +122,7 @@ export function configFromHeaders(headers) {
         jwt: header(headers, "x-webcake-jwt") ?? bearer,
         orgId: header(headers, "x-webcake-org-id"),
         appBase: header(headers, "x-webcake-app-base"),
+        builderBase: header(headers, "x-webcake-builder-base"),
         env: header(headers, "x-webcake-env"),
     };
 }

package/dist/persistence/webcake-client.js

@@ -15,6 +15,33 @@ function authHeaders(config, orgId) {
         headers["x-org-id"] = `${org}`;
     return headers;
 }
+/**
+ * Resolve the editor/preview link the backend returns onto the page-builder host
+ * (config.builderBase, e.g. builder.localhost:5800), NOT the API base. The backend
+ * may return either a path (`/editor/v2/<id>`) or an absolute URL on its own host
+ * (`http://localhost:5800/editor/v2/<id>`) — in both cases we keep only the
+ * path+query and re-root it on the builder host.
+ */
+export function toEditorUrl(config, raw) {
+    if (!raw)
+        return raw;
+    const builder = config.builderBase ?? config.appBase;
+    if (!builder)
+        return raw;
+    let pathQuery = raw;
+    if (/^https?:\/\//i.test(raw)) {
+        try {
+            const u = new URL(raw);
+            pathQuery = u.pathname + u.search + u.hash;
+        }
+        catch {
+            /* not a parseable URL — use as-is */
+        }
+    }
+    if (!pathQuery.startsWith("/"))
+        pathQuery = `/${pathQuery}`;
+    return `${builder.replace(/\/+$/, "")}${pathQuery}`;
+}
 /** Build (but do not send) the create request — used for dry-run previews. */
 export function buildRequest(config, name, source, orgId) {
     return {
@@ -88,7 +115,6 @@ export async function createPage(config, name, source, orgId) {
     const pageId = data?.page_id;
     const editorPath = data?.editor_url;
     const previewPath = data?.preview_url;
-    const app = config.appBase;
     if (!res.ok || !pageId) {
         // The backend's failure envelope is { success:false, message } on 422; auth
         // plugs return plain-text 401/403 (json is null). Surface the real reason
@@ -105,8 +131,8 @@ export async function createPage(config, name, source, orgId) {
         ok: true,
         status: res.status,
         page_id: pageId,
-        editor_url: app && editorPath ? `${app}${editorPath}` : editorPath,
-        preview_url: app && previewPath ? `${app}${previewPath}` : previewPath,
+        editor_url: toEditorUrl(config, editorPath),
+        preview_url: toEditorUrl(config, previewPath),
         organization_id: (orgId ?? config.orgId) ?? null,
         raw: data,
     };
@@ -190,7 +216,6 @@ export async function updatePageSource(config, pageId, source) {
     }
     const data = json?.data ?? json;
     const pageIdOut = data?.page_id;
-    const app = config.appBase;
     if (!res.ok || !pageIdOut) {
         const backendMsg = json?.message ?? json?.reason ?? (json ? undefined : text.slice(0, 200));
         return {
@@ -204,8 +229,8 @@ export async function updatePageSource(config, pageId, source) {
         ok: true,
         status: res.status,
         page_id: pageIdOut,
-        editor_url: app && data?.editor_url ? `${app}${data.editor_url}` : data?.editor_url,
-        preview_url: app && data?.preview_url ? `${app}${data.preview_url}` : data?.preview_url,
+        editor_url: toEditorUrl(config, data?.editor_url),
+        preview_url: toEditorUrl(config, data?.preview_url),
         organization_id: data?.organization_id ?? null,
         raw: data,
     };

package/dist/smoke.js

@@ -5,6 +5,7 @@
 import { createElement, CONTAINER_TYPES, FIELD_TYPES, LIBRARY, ELEMENT_TYPES, ELEMENTS, } from "./domains/landing/elements/index.js";
 import { validatePage, pageSchema } from "./domains/landing/validate.js";
 import { readConfig, resolveEnv, ENV_NAMES } from "./persistence/config.js";
+import { toEditorUrl } from "./persistence/webcake-client.js";
 let failures = 0;
 const check = (name, cond, extra) => {
     if (cond) {
@@ -212,7 +213,7 @@ check("clean form has no binding warnings", rbg.warnings.length === 0, rbg.warni
 console.log("== config: named environment presets (local/staging/prod) ==");
 {
     // Deterministic: isolate from any ambient WEBCAKE_* and the saved auth.json on the dev box.
-    for (const k of ["WEBCAKE_API_BASE", "WEBCAKE_APP_BASE", "WEBCAKE_ENV", "WEBCAKE_JWT", "WEBCAKE_ORG_ID"])
+    for (const k of ["WEBCAKE_API_BASE", "WEBCAKE_APP_BASE", "WEBCAKE_BUILDER_BASE", "WEBCAKE_ENV", "WEBCAKE_JWT", "WEBCAKE_ORG_ID"])
         delete process.env[k];
     process.env.WEBCAKE_CONFIG_DIR = "/nonexistent/webcake-smoke";
     check("env names are local/staging/prod", setEq(new Set(ENV_NAMES), ["local", "staging", "prod"]), ENV_NAMES);
@@ -224,6 +225,20 @@ console.log("== config: named environment presets (local/staging/prod) ==");
     check("readConfig(env=local) fills api+app base", local?.base === "http://localhost:5800" && local?.appBase === "http://localhost:5173", local);
     check("explicit base overrides the preset", readConfig({ env: "prod", base: "http://x:1", jwt: "t" }).config?.base === "http://x:1");
     check("unknown env leaves base missing", readConfig({ env: "bogus", jwt: "t" }).missing.includes("WEBCAKE_API_BASE"));
+    // builder host for editor/preview URLs (distinct from the api + app bases)
+    check("env presets carry builder bases", resolveEnv("prod")?.builderBase === "https://builder.webcake.io" && resolveEnv("local")?.builderBase === "http://builder.localhost:5800");
+    check("readConfig(env=prod) sets builderBase", prod?.builderBase === "https://builder.webcake.io", prod);
+    check("readConfig(env=local) sets builderBase", local?.builderBase === "http://builder.localhost:5800", local);
+    check("readConfig(env=staging) sets builderBase", readConfig({ env: "staging", jwt: "t" }).config?.builderBase === "https://builder.staging.webcake.io");
+    check("builderBase derives from a custom api base (api. → builder.)", readConfig({ base: "https://api.example.com", jwt: "t" }).config?.builderBase === "https://builder.example.com");
+    check("builderBase derives from a localhost api base", readConfig({ base: "http://localhost:5800", jwt: "t" }).config?.builderBase === "http://builder.localhost:5800");
+    check("explicit builderBase overrides the preset", readConfig({ env: "prod", builderBase: "https://b.test", jwt: "t" }).config?.builderBase === "https://b.test");
+    // editor/preview link is re-rooted on the builder host, whether the backend
+    // returns a path or an absolute URL on its own host.
+    const localCfg = readConfig({ env: "local", jwt: "t" }).config;
+    check("editor url from a path → builder host", toEditorUrl(localCfg, "/editor/v2/abc") === "http://builder.localhost:5800/editor/v2/abc");
+    check("editor url from an absolute api url → builder host", toEditorUrl(localCfg, "http://localhost:5800/editor/v2/abc?x=1") === "http://builder.localhost:5800/editor/v2/abc?x=1");
+    check("editor url passthrough when empty", toEditorUrl(localCfg, undefined) === undefined);
 }
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/dist/web-guide.js

@@ -24,6 +24,9 @@
 import { readFileSync } from "node:fs";
 import { ICON_SVG } from "./branding.js";
 const MCP_REMOTE_URL = "https://webcake.io/mcp-remote";
+// The "configure every IDE" one-liner — rendered as a code block (with a copy
+// button) rather than long inline code, which wrapped messily on mobile.
+const INSTALL_ALL_CMD = "npx -y webcake-landing-mcp install --ide all --env prod --jwt <TOKEN>";
 const GITHUB_URL = "https://github.com/vuluu2k/webcake-landing-mcp";
 const NPM_URL = "https://www.npmjs.com/package/webcake-landing-mcp";
 const DOCS_URL = `${GITHUB_URL}#readme`;
@@ -58,6 +61,11 @@ const ICONS = {
     arrow: '<path d="M5 12h14"/><path d="m12 5 7 7-7 7"/>',
     clock: '<circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/>',
     globe: '<circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"/><path d="M2 12h20"/>',
+    bulb: '<path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/>',
+    server: '<rect width="20" height="8" x="2" y="2" rx="2"/><rect width="20" height="8" x="2" y="14" rx="2"/><path d="M6 6h.01"/><path d="M6 18h.01"/>',
+    window: '<rect x="2" y="4" width="20" height="16" rx="2"/><path d="M2 9h20"/><path d="M6 6.5h.01"/><path d="M9 6.5h.01"/>',
+    moon: '<path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/>',
+    sun: '<circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/>',
 };
 function icon(name) {
     return `<svg class="i" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${ICONS[name] ?? ""}</svg>`;
@@ -136,6 +144,14 @@ const T = {
         leadPost: " của bạn. Không kéo thả, không cài server — kết nối một lần là xong.",
         ctaStart: "Bắt đầu kết nối",
         ctaStar: "Star trên GitHub",
+        flowH2: "Mô hình hoạt động",
+        flow: [
+            { icon: "bulb", t: "Bạn", s: "ý tưởng" },
+            { icon: "brain", t: "Trợ lý AI", s: "Claude · Cursor" },
+            { icon: "server", t: "MCP", s: "webcake-landing" },
+            { icon: "window", t: "WebCake", s: "trang thật" },
+        ],
+        flowCap: "Bạn mô tả bằng lời → AI học mô hình thật từ MCP → MCP dựng JSON + kiểm tra → lưu thành trang thật trên WebCake. Bạn nhận link, mở editor, publish.",
         howH2: "Cách hoạt động",
         how: [
             {
@@ -172,7 +188,7 @@ const T = {
             '<b>Làm theo hỏi đáp:</b> chọn môi trường (<code class="inl">prod</code>) → đăng nhập Webcake qua trình duyệt (hoặc dán JWT) → chọn IDE (Claude Desktop / Cursor / Claude Code…).',
             '<b>Khởi động lại IDE</b> → thấy <code class="inl">webcake-landing</code> trong danh sách MCP là xong.',
         ],
-        m1Note: 'Muốn cấu hình mọi IDE một phát: <code class="inl">npx -y webcake-landing-mcp install --ide all --env prod --jwt &lt;TOKEN&gt;</code>',
+        m1Note: "Muốn cấu hình mọi IDE một phát:",
         m2Tag: "Cách ② · URL remote — không cần cài gì",
         m2Sub: "Hợp khi máy không có Node.js, dùng theo nhóm, hoặc dùng claude.ai trên web.",
         m2Steps: [
@@ -206,6 +222,14 @@ const T = {
         leadPost: ". No drag-and-drop, no server to host — connect once and you're set.",
         ctaStart: "Get connected",
         ctaStar: "Star on GitHub",
+        flowH2: "How it flows",
+        flow: [
+            { icon: "bulb", t: "You", s: "your idea" },
+            { icon: "brain", t: "AI assistant", s: "Claude · Cursor" },
+            { icon: "server", t: "MCP", s: "webcake-landing" },
+            { icon: "window", t: "WebCake", s: "a real page" },
+        ],
+        flowCap: "You describe it in words → the AI learns the real model from the MCP → the MCP builds the JSON + validates → it's saved as a real WebCake page. You get a link, open the editor, publish.",
         howH2: "How it works",
         how: [
             {
@@ -242,7 +266,7 @@ const T = {
             '<b>Follow the prompts:</b> pick an environment (<code class="inl">prod</code>) → sign in to Webcake in the browser (or paste a JWT) → pick your IDE (Claude Desktop / Cursor / Claude Code…).',
             '<b>Restart your IDE</b> → see <code class="inl">webcake-landing</code> in the MCP list and you\'re done.',
         ],
-        m1Note: 'Configure every IDE at once: <code class="inl">npx -y webcake-landing-mcp install --ide all --env prod --jwt &lt;TOKEN&gt;</code>',
+        m1Note: "Configure every IDE at once:",
         m2Tag: "Way ② · Remote URL — nothing to install",
         m2Sub: "Best when you have no Node.js, work in a team, or use claude.ai on the web.",
         m2Steps: [
@@ -354,6 +378,7 @@ export function guideHtml(origin, lang = "vi") {
 <html lang="${L}"><head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1">
+<script>(function(){try{var t=localStorage.getItem('wc-theme');if(t==='dark'||t==='light')document.documentElement.setAttribute('data-theme',t);}catch(e){}})();</script>
 <title>${m.title}</title>
 <meta name="description" content="${m.desc}">
 <meta name="keywords" content="${m.keywords}">
@@ -381,10 +406,15 @@ export function guideHtml(origin, lang = "vi") {
 <meta name="twitter:image" content="${ogImage}">
 <script type="application/ld+json">${jsonLdScript}</script>
 <style>
+  /* Light defaults. Dark applies via OS preference OR a forced [data-theme="dark"]
+     (the toggle); [data-theme="light"] forces light even on a dark OS. */
   :root{--g:#1DB954;--g7:#178f43;--ink:#11231b;--mut:#5e6d65;--bg:#f5f9f7;--card:#ffffff;
-    --line:rgba(16,40,30,.09);--glass-hi:transparent;--shadow:0 1px 2px rgba(16,40,30,.05),0 6px 20px -12px rgba(16,40,30,.18);--code:#0e1714}
-  @media(prefers-color-scheme:dark){:root{--ink:#e8f0ec;--mut:#9aaba2;--bg:#0b110e;--card:#141b17;
-    --line:rgba(255,255,255,.07);--glass-hi:transparent;--shadow:0 1px 2px rgba(0,0,0,.3),0 8px 24px -14px rgba(0,0,0,.7);--code:#070f0b;--g7:#5ee08a}}
+    --line:rgba(16,40,30,.09);--shadow:0 1px 2px rgba(16,40,30,.05),0 6px 20px -12px rgba(16,40,30,.18);--code:#0e1714;
+    --ic-fg:#178f43;--btn-hover:#178f43}
+  @media(prefers-color-scheme:dark){:root:not([data-theme="light"]){--ink:#e8f0ec;--mut:#9aaba2;--bg:#0b110e;--card:#141b17;
+    --line:rgba(255,255,255,.07);--shadow:0 1px 2px rgba(0,0,0,.3),0 8px 24px -14px rgba(0,0,0,.7);--code:#070f0b;--g7:#5ee08a;--ic-fg:#6fe79a;--btn-hover:#21c264}}
+  :root[data-theme="dark"]{--ink:#e8f0ec;--mut:#9aaba2;--bg:#0b110e;--card:#141b17;
+    --line:rgba(255,255,255,.07);--shadow:0 1px 2px rgba(0,0,0,.3),0 8px 24px -14px rgba(0,0,0,.7);--code:#070f0b;--g7:#5ee08a;--ic-fg:#6fe79a;--btn-hover:#21c264}
   *{box-sizing:border-box}
   html{scroll-behavior:smooth}
   body{margin:0;font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;color:var(--ink);
@@ -405,9 +435,15 @@ export function guideHtml(origin, lang = "vi") {
   header .logo{width:50px;height:50px;border-radius:14px;overflow:hidden;flex:0 0 auto;
     box-shadow:0 6px 16px -4px rgba(29,185,84,.4)}
   header .logo svg{width:100%;height:100%;display:block}
-  .langsw{margin-left:auto;align-self:flex-start;font-size:.82rem;font-weight:700;color:var(--g7);text-decoration:none;
+  .hgrow{flex:1 1 auto;min-width:0}
+  .controls{margin-left:auto;flex:0 0 auto;display:flex;align-items:center;gap:8px}
+  .langsw{font-size:.82rem;font-weight:700;color:var(--g7);text-decoration:none;white-space:nowrap;
     border:1px solid var(--line);background:var(--card);padding:7px 12px;border-radius:999px;display:inline-flex;align-items:center;gap:6px}
   .langsw:hover{border-color:var(--g)}
+  .iconbtn{width:36px;height:36px;flex:0 0 auto;display:grid;place-items:center;cursor:pointer;color:var(--g7);
+    border:1px solid var(--line);background:var(--card);border-radius:10px;transition:border-color .15s ease,color .15s ease}
+  .iconbtn:hover{border-color:var(--g)}
+  .iconbtn svg{width:17px;height:17px}
   h1{font-size:1.78rem;margin:0;font-weight:800;letter-spacing:-.02em}
   .sub{color:var(--mut);margin:3px 0 0;font-size:.98rem}
   .lead{font-size:1.16rem;margin:20px 0 18px;max-width:60ch}
@@ -420,9 +456,8 @@ export function guideHtml(origin, lang = "vi") {
   .dot{width:8px;height:8px;border-radius:50%;background:var(--g);box-shadow:0 0 0 0 rgba(29,185,84,.5);animation:pulse 2s infinite}
   @keyframes pulse{70%{box-shadow:0 0 0 7px rgba(29,185,84,0)}100%{box-shadow:0 0 0 0 rgba(29,185,84,0)}}
   h2{font-size:1.32rem;margin:46px 0 16px;font-weight:800;letter-spacing:-.01em}
-  .ic{width:42px;height:42px;border-radius:12px;display:grid;place-items:center;flex:0 0 auto;color:var(--g7);
+  .ic{width:42px;height:42px;border-radius:12px;display:grid;place-items:center;flex:0 0 auto;color:var(--ic-fg);
     background:rgba(29,185,84,.11);border:1px solid var(--line);transition:transform .2s ease}
-  @media(prefers-color-scheme:dark){.ic{color:#6fe79a}}
   .ic .i{width:22px;height:22px}
   .grid{display:grid;gap:16px;grid-template-columns:1fr 1fr 1fr}
   @media(max-width:720px){.grid{grid-template-columns:1fr}}
@@ -431,21 +466,50 @@ export function guideHtml(origin, lang = "vi") {
   .card h3{margin:0 0 6px;font-size:1.04rem}
   .card p{color:var(--mut);font-size:.93rem;margin:0}
   .tag{display:inline-flex;align-items:center;gap:9px;font-size:.82rem;font-weight:800;color:var(--g7);
-    text-transform:uppercase;letter-spacing:.04em}
+    text-transform:uppercase;letter-spacing:.04em;flex-wrap:wrap}
   .tag .ic{width:30px;height:30px;border-radius:9px}
   .tag .ic .i{width:16px;height:16px}
   pre{margin:0;background:var(--code);color:#e8f0ec;border-radius:11px;padding:12px 14px;overflow-x:auto;
     border:1px solid rgba(255,255,255,.06);font:600 .82rem/1.5 ui-monospace,SFMono-Regular,Menlo,monospace}
+  /* Copy button injected onto every <pre> by the inline script */
+  .codewrap{position:relative}
+  .codewrap pre{padding-right:46px}
+  .copy{position:absolute;top:8px;right:8px;width:30px;height:30px;display:grid;place-items:center;cursor:pointer;
+    border:1px solid rgba(255,255,255,.15);border-radius:8px;background:rgba(255,255,255,.06);color:#cfe9d8;
+    transition:background .15s ease,color .15s ease,border-color .15s ease}
+  .copy:hover{background:rgba(255,255,255,.13);color:#fff}
+  .copy svg{width:15px;height:15px}
+  .copy.done{color:#5ee08a;border-color:rgba(94,224,138,.55)}
   .feat{list-style:none;padding:0;margin:0;display:grid;gap:12px}
   .feat li{display:flex;gap:13px;align-items:center;font-size:.97rem;padding:13px 16px}
   .feat li b{color:var(--ink)}
   .cta-row{display:flex;gap:12px;flex-wrap:wrap;margin:22px 0 6px}
+  /* Flow diagram: nodes connected by wires with a traveling "packet" */
+  .flow{display:flex;align-items:flex-start;gap:0;padding:24px 18px 18px;overflow-x:auto}
+  .flow .node{flex:0 0 auto;display:flex;flex-direction:column;align-items:center;gap:8px;text-align:center;width:104px}
+  .flow .node .ic{width:54px;height:54px;border-radius:16px}
+  .flow .node .ic .i{width:27px;height:27px}
+  .flow .node b{font-size:.93rem}
+  .flow .node span{font-size:.75rem;color:var(--mut)}
+  .flow .wire{flex:1 1 auto;min-width:30px;position:relative;height:2px;margin-top:27px;
+    background:linear-gradient(90deg,var(--line),rgba(29,185,84,.45),var(--line))}
+  .flow .wire .pkt{position:absolute;top:50%;left:0;width:9px;height:9px;margin:-5px 0 0 -4px;border-radius:50%;
+    background:var(--g);box-shadow:0 0 9px 1px rgba(29,185,84,.7)}
+  .flow .wire::after{content:"";position:absolute;right:-1px;top:50%;width:7px;height:7px;margin-top:-4px;
+    border-top:2px solid var(--g7);border-right:2px solid var(--g7);transform:rotate(45deg)}
+  .flow-cap{color:var(--mut);font-size:.9rem;margin:2px 2px 0;max-width:68ch}
+  @media(prefers-reduced-motion:no-preference){
+    .flow .wire .pkt{animation:pkt 2.4s ease-in-out infinite}
+    @keyframes pkt{0%{left:0;opacity:0}12%{opacity:1}88%{opacity:1}100%{left:100%;opacity:0}}
+    .flow .node .ic{animation:nodepop 2.4s ease-in-out infinite}
+  }
+  @media(prefers-reduced-motion:reduce){.flow .wire .pkt{display:none}}
+  @keyframes nodepop{0%,100%{box-shadow:none}50%{box-shadow:0 0 0 4px rgba(29,185,84,.12)}}
   .btn{display:inline-flex;align-items:center;gap:9px;padding:11px 19px;border-radius:11px;cursor:pointer;
     background:var(--g);color:#fff;text-decoration:none;font-weight:700;font-size:.93rem;
     box-shadow:0 4px 12px -4px rgba(29,185,84,.5);transition:transform .15s ease,background .15s ease}
   .btn .i{width:18px;height:18px}
-  .btn:hover{transform:translateY(-1px);background:var(--g7)}
-  @media(prefers-color-scheme:dark){.btn:hover{background:#21c264}}
+  .btn:hover{transform:translateY(-1px);background:var(--btn-hover)}
   .btn.ghost{background:var(--card);color:var(--ink);border:1px solid var(--line);box-shadow:none}
   .btn.ghost:hover{border-color:var(--g);background:var(--card)}
   .uses{display:grid;gap:14px;grid-template-columns:1fr 1fr;padding:0;margin:0;list-style:none}
@@ -462,15 +526,16 @@ export function guideHtml(origin, lang = "vi") {
   .msub{color:var(--mut);font-size:.92rem;margin:.5rem 0 1.2rem}
   .steps{list-style:none;margin:0;padding:0;display:grid;gap:16px}
   .steps li{display:flex;gap:14px}
-  .steps .n{flex:0 0 auto;width:28px;height:28px;border-radius:50%;color:var(--g7);
+  .steps .n{flex:0 0 auto;width:28px;height:28px;border-radius:50%;color:var(--ic-fg);
     background:rgba(29,185,84,.12);border:1px solid var(--line);
     font:800 .85rem/1 system-ui;display:flex;align-items:center;justify-content:center}
-  @media(prefers-color-scheme:dark){.steps .n{color:#6fe79a}}
   .steps .body{flex:1;min-width:0;font-size:.95rem}
   .steps .body pre{margin-top:9px}
   .steps .body .btn{margin-top:10px}
-  code.inl{background:rgba(29,185,84,.13);color:var(--g7);padding:1px 6px;border-radius:6px;font-size:.85em;font-weight:600}
+  code.inl{background:rgba(29,185,84,.13);color:var(--g7);padding:1px 6px;border-radius:6px;font-size:.85em;font-weight:600;
+    overflow-wrap:anywhere;word-break:break-word}
   .note{font-size:.86rem;color:var(--mut);margin-top:10px}
+  .note + pre,.note + .codewrap{margin-top:9px}
   details{padding:2px 18px;margin-bottom:11px}
   details summary{cursor:pointer;font-weight:600;padding:15px 0;list-style:none;display:flex;align-items:center;gap:10px}
   details summary::-webkit-details-marker{display:none}
@@ -509,6 +574,31 @@ export function guideHtml(origin, lang = "vi") {
   @keyframes blink{50%{opacity:.55}}
   .cl-more{display:inline-flex;align-items:center;gap:6px;margin-top:6px;font-size:.86rem;font-weight:600;color:var(--g7);text-decoration:none}
   .cl-more:hover{gap:9px}
+  @media(max-width:640px){
+    .wrap{padding:30px 15px 56px}
+    /* Header: logo + controls on the top row, title drops to its own full line */
+    header{flex-wrap:wrap;gap:12px}
+    .hgrow{order:2;flex:1 1 100%}
+    h1{font-size:1.4rem}
+    h2{font-size:1.2rem;margin:34px 0 14px}
+    .lead{font-size:1.05rem}
+    .method{padding:18px 15px}
+    .card{padding:18px}
+    .cl-wrap{padding:18px 16px 10px}
+    .langsw{padding:6px 10px}
+    .uses li,.feat li{padding:14px}
+    /* Flow diagram: stack vertically (the horizontal row overflows narrow screens) */
+    .flow{flex-direction:column;align-items:stretch;overflow:visible;padding:16px}
+    .flow .node{flex-direction:row;width:auto;align-items:center;gap:13px;text-align:left}
+    .flow .node .ic{width:44px;height:44px;border-radius:13px}
+    .flow .node .ic .i{width:22px;height:22px}
+    .flow .node b{font-size:.95rem}
+    .flow .node span{font-size:.8rem}
+    .flow .wire{flex:0 0 auto;width:2px;height:20px;min-width:0;margin:3px 0 3px 21px;
+      background:linear-gradient(var(--line),var(--g))}
+    .flow .wire::after{content:none}
+    .flow .wire .pkt{display:none}
+  }
   @media(prefers-reduced-motion:no-preference){
     @supports (animation-timeline:view()){
       .reveal{animation:rise linear both;animation-timeline:view();animation-range:entry 0% entry 32%}
@@ -524,11 +614,14 @@ export function guideHtml(origin, lang = "vi") {
 
   <header class="hero-in">
     <span class="logo">${ICON_SVG}</span>
-    <div>
+    <div class="hgrow">
       <h1>Webcake Landing MCP</h1>
       <p class="sub">${t.sub}</p>
     </div>
-    <a class="langsw" href="${otherHref}" hreflang="${otherLang}" rel="alternate">${icon("globe")} ${t.switchLabel}</a>
+    <div class="controls">
+      <button class="iconbtn" id="theme" type="button" aria-label="Toggle theme" title="Theme">${icon("moon")}</button>
+      <a class="langsw" href="${otherHref}" hreflang="${otherLang}" rel="alternate">${icon("globe")} ${t.switchLabel}</a>
+    </div>
   </header>
 
   <p class="hero-in" style="display:flex;gap:9px;flex-wrap:wrap"><span class="pill"><span class="dot"></span> ${t.running}</span>${CHANGELOG[0] ? `<span class="pill">v${CHANGELOG[0].v}</span>` : ""}</p>
@@ -540,6 +633,17 @@ export function guideHtml(origin, lang = "vi") {
     <a class="btn ghost" href="${GITHUB_URL}">${icon("star")} ${t.ctaStar}</a>
   </div>
 
+  <h2 class="reveal">${t.flowH2}</h2>
+  <div class="glass flow reveal">
+    ${t.flow
+        .map((n, i) => `<div class="node"><span class="ic" style="animation-delay:${(i * 0.8).toFixed(1)}s">${icon(n.icon)}</span><b>${n.t}</b><span>${n.s}</span></div>` +
+        (i < t.flow.length - 1
+            ? `<div class="wire"><i class="pkt" style="animation-delay:${(i * 0.8).toFixed(1)}s"></i></div>`
+            : ""))
+        .join("\n    ")}
+  </div>
+  <p class="flow-cap reveal">${t.flowCap}</p>
+
   <h2 class="reveal">${t.howH2}</h2>
   <div class="grid">
     ${t.how
@@ -563,6 +667,7 @@ export function guideHtml(origin, lang = "vi") {
       ${steps(t.m1Steps.map(fill))}
     </ol>
     <p class="note">${t.m1Note}</p>
+    <pre>${INSTALL_ALL_CMD}</pre>
   </div>
 
   <div class="glass card method reveal">
@@ -608,7 +713,36 @@ export function guideHtml(origin, lang = "vi") {
     <a href="${selfPath === "/" ? "/health" : "/health"}">Health</a>
   </footer>
 
-</div></body></html>`;
+</div>
+<script>
+(function(){
+  var COPY='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
+  var DONE='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>';
+  function copyText(t){
+    if(navigator.clipboard&&navigator.clipboard.writeText){return navigator.clipboard.writeText(t);}
+    return new Promise(function(res,rej){try{var ta=document.createElement('textarea');ta.value=t;ta.style.position='fixed';ta.style.opacity='0';document.body.appendChild(ta);ta.select();document.execCommand('copy');document.body.removeChild(ta);res();}catch(e){rej(e);}});
+  }
+  document.querySelectorAll('pre').forEach(function(pre){
+    var w=document.createElement('div');w.className='codewrap';
+    pre.parentNode.insertBefore(w,pre);w.appendChild(pre);
+    var b=document.createElement('button');b.type='button';b.className='copy';b.title='Copy';b.setAttribute('aria-label','Copy');b.innerHTML=COPY;
+    b.addEventListener('click',function(){
+      copyText(pre.innerText).then(function(){b.classList.add('done');b.innerHTML=DONE;setTimeout(function(){b.classList.remove('done');b.innerHTML=COPY;},1400);}).catch(function(){});
+    });
+    w.appendChild(b);
+  });
+
+  // Dark / light toggle — overrides the OS preference and persists the choice.
+  var SUN='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></svg>';
+  var MOON='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/></svg>';
+  var html=document.documentElement, tBtn=document.getElementById('theme');
+  function effective(){return html.getAttribute('data-theme')||(window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light');}
+  function paint(){if(tBtn)tBtn.innerHTML=effective()==='dark'?SUN:MOON;}
+  paint();
+  if(tBtn)tBtn.addEventListener('click',function(){var next=effective()==='dark'?'light':'dark';html.setAttribute('data-theme',next);try{localStorage.setItem('wc-theme',next);}catch(e){}paint();});
+})();
+</script>
+</body></html>`;
 }
 /**
  * The social-card image served at `/og.svg` and referenced by the page's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "type": "module",
   "bin": {