Polish env-builder UX with quick guide and required selector

README.md

@@ -241,7 +241,7 @@ Configure password access and network restrictions:
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `OPENCLAW_PASSWORD` | — | Enable simple password auth instead of token |
+| `OPENCLAW_PASSWORD` | — | Enable simple password auth instead of token (applies only when `GATEWAY_TOKEN` is empty) |
 | `TRUSTED_PROXIES` | — | Comma-separated IPs of HF proxies |
 | `ALLOWED_ORIGINS` | — | Comma-separated allowed origins for Control UI |
 | `CLOUDFLARE_KEEPALIVE_ENABLED` | `true` | Set to `false` to disable the automatic Cloudflare KeepAlive worker |

env-builder.html

@@ -775,6 +775,9 @@ body {
   flex-shrink: 0;
 }
 .tag-legend[open] .legend-hint { opacity: 0; }
+.toolbar-hint { color: var(--muted); font-size: 12px; margin-right: 10px; white-space: nowrap; }
+.quick-guide { margin: 0; padding-left: 18px; color: var(--muted); display: grid; gap: 6px; font-size: 12.5px; }
+.quick-guide strong { color: var(--text); }
 .legend-body {
   padding: 8px 12px 10px;
   border-top: 1px solid var(--border);
@@ -834,6 +837,7 @@ body {
 
     <!-- toolbar -->
     <div class="toolbar">
+      <div class="toolbar-hint">Tip: Start with <strong>⚡ Required</strong>, then fill keys and click <strong># Generate Bundle</strong>.</div>
       <div class="search-wrap">
         <span class="search-icon">⌕</span>
         <input id="search" type="text" placeholder="Search variables…" autocomplete="off" spellcheck="false">
@@ -841,6 +845,7 @@ body {
 
       <div class="tb-sep"></div>
 
+      <button id="selectRequired" class="btn" title="Select all critical variables first">⚡ Required</button>
       <button id="selectCommon" class="btn">★ Common</button>
       <button id="selectVisible" class="btn">☑ Visible</button>
       <button id="clearAll" class="btn btn-ghost">✕ Clear</button>
@@ -893,6 +898,20 @@ body {
         <div class="panel-scroll">
 
           <!-- Summary -->
+          <div class="pblock">
+            <div class="pblock-head">
+              <span class="pblock-title">🧭 Quick Guide</span>
+            </div>
+            <div class="pblock-body">
+              <ol class="quick-guide">
+                <li>Click <strong>⚡ Required</strong> to select must-have vars.</li>
+                <li>Fill values in selected cards (search works by key/tag/group).</li>
+                <li>Click <strong># Generate Bundle</strong> and copy Bundle/Env line.</li>
+                <li>Paste into HF Space variables or use <strong>↓ Import & Apply</strong>.</li>
+              </ol>
+            </div>
+          </div>
+
           <div class="pblock">
             <div class="pblock-head">
               <span class="pblock-title">📊 Summary</span>

env-builder.js

@@ -2115,7 +2115,7 @@ function cardHTML(f, origIdx = 0) {
   const tm = TAG_META[f.tag] || TAG_META.optional;
   const badge = `<span class="badge ${tm.cls}">${tm.lbl}</span>`;
 
-  return `<div class="env-card" data-row data-orig-idx="${origIdx}" data-group="${esc(f.g)}" data-search="${esc((f.g + ' ' + f.k + ' ' + (f.lbl || '') + ' ' + (f.tag || '')).toLowerCase())}">
+  return `<div class="env-card" data-row data-orig-idx="${origIdx}" data-group="${esc(f.g)}" data-search="${esc((f.g + ' ' + f.k + ' ' + (f.lbl || '') + ' ' + (f.tag || '')).toLowerCase())}" data-tag="${esc(f.tag || 'optional')}">
     <div class="card-top">
       <input type="checkbox" class="card-check" data-check="${esc(f.k)}" ${f.common ? 'data-common="1"' : ''}>
       <div class="card-info">
@@ -2465,6 +2465,12 @@ refresh();
 
 // ── Events ──
 $('search').oninput = filter;
+$('selectRequired').onclick = () => {
+  document.querySelectorAll('[data-row][data-tag="critical"] [data-check]').forEach(c => c.checked = true);
+  sortAllSections();
+  markSelected();
+  refresh();
+};
 $('selectCommon').onclick = () => {
   document.querySelectorAll('[data-common="1"]').forEach(c => c.checked = true);
   sortAllSections();

health-server.js

@@ -664,11 +664,11 @@ const server = http.createServer(async (req, res) => {
       const body = await readBody(req);
       const token = decodeURIComponent((body.match(/(?:^|&)token=([^&]*)/) || [])[1] || "").replace(/\+/g, " ");
       if (safeEqual(token, GATEWAY_TOKEN)) {
-        const cookie = `hc_env_auth=${encodeURIComponent(GATEWAY_TOKEN)}; Path=/env-builder; HttpOnly; SameSite=Strict; Max-Age=86400`;
+        const cookie = `hc_env_auth=${encodeURIComponent(GATEWAY_TOKEN)}; Path=/; HttpOnly; SameSite=Strict; Max-Age=86400`;
         res.writeHead(302, { Location: "/env-builder", "Set-Cookie": cookie, "Cache-Control": "no-store" });
         return res.end();
       }
-      res.writeHead(200, { "Content-Type": "text/html" });
+      res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
       return res.end(renderEnvBuilderLogin(true));
     }
     res.writeHead(302, { Location: "/env-builder", "Cache-Control": "no-store" });
@@ -676,31 +676,31 @@ const server = http.createServer(async (req, res) => {
   }
 
   if (pathname === "/env-builder/logout") {
-    res.writeHead(302, { Location: "/env-builder", "Set-Cookie": "hc_env_auth=; Path=/env-builder; HttpOnly; Max-Age=0", "Cache-Control": "no-store" });
+    res.writeHead(302, { Location: "/env-builder", "Set-Cookie": "hc_env_auth=; Path=/; HttpOnly; Max-Age=0", "Cache-Control": "no-store" });
     return res.end();
   }
 
   if (pathname === "/env-builder" || pathname === "/env-builder/") {
     if (isDirectHfSpaceRequest) {
-      res.writeHead(200, { "Content-Type": "text/html" });
+      res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
       return res.end(renderPrivateRedirect(HF_SPACE_URL));
     }
     if (!isEnvBuilderAuthed(req)) {
-      res.writeHead(200, { "Content-Type": "text/html" });
+      res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
       return res.end(renderEnvBuilderLogin(false));
     }
-    res.writeHead(200, { "Content-Type": "text/html" });
+    res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
     return res.end(renderEnvBuilder());
   }
 
   if (pathname === "/env-builder.js") {
     if (!isEnvBuilderAuthed(req)) {
-      res.writeHead(401, { "Content-Type": "text/plain" });
+      res.writeHead(401, { "Content-Type": "text/plain", "Cache-Control": "no-store", "Vary": "Cookie" });
       return res.end("Unauthorized");
     }
     try {
       const js = fs.readFileSync(require("path").join(__dirname, "env-builder.js"), "utf8");
-      res.writeHead(200, { "Content-Type": "application/javascript" });
+      res.writeHead(200, { "Content-Type": "application/javascript", "Cache-Control": "no-store", "Vary": "Cookie" });
       return res.end(js);
     } catch (exc) {
       res.writeHead(404, { "Content-Type": "text/plain" });

start.sh

@@ -676,7 +676,7 @@ CONFIG_JSON=$(jq \
    | (if $spaceHost != "" then
         .gateway.controlUi.allowedOrigins = ["https://" + $spaceHost]
       else . end)
-   | (if $password != "" then
+   | (if ($password != "" and (.gateway.auth.token // "") == "") then
         .gateway.auth.mode = "password" | .gateway.auth.password = $password
       else . end)' <<<"$CONFIG_JSON")