@rashidee/co2 1.3.9 → 1.3.11

package/plugin/skills/mockgen-tailwind/references/mockup-hub-template.md

@@ -19,6 +19,13 @@ they contain NO server of their own.
   `mockup.config.json` and re-listens on the new port. Compound Context Studio's Mockup
   page reads its own topbar port input and passes it via the `PORT` env when its
   **Start Hub** button spawns this server.
+- **Reverse-proxy aware** (v3): Compound Context Studio embeds the hub through its own
+  same-origin proxy (`/api/artifacts/mockup-proxy/<projectId>/`), which sends the mount
+  path in an `X-Forwarded-Prefix` header. The hub prefixes every redirect and rewrites
+  root-absolute URL attributes (`href`/`src`/`action`/`hx-*`) in the HTML it serves —
+  including per-app assets generated before v3 — so mockups work behind the studio (or
+  any prefix-forwarding reverse proxy) without exposing the hub's port separately.
+  Requests without the header behave exactly as before.
 
 The hub has **zero npm dependencies** — `npm start` (or `node server.js`) works with no
 `npm install`.
@@ -97,12 +104,15 @@ Example:
 #!/usr/bin/env node
 /*
  * CO2 Mockup Hub — one server for ALL application mockups.
- * HUB_VERSION: 2   (marker used by mockgen-* skills to decide upgrades — do not remove)
+ * HUB_VERSION: 3   (marker used by mockgen-* skills to decide upgrades — do not remove)
  *
  * Discovers every root-level application folder containing context/PRD.md.
  * Apps with a context/mockup/mockup-manifest.json are routable:
  *   - stack "tailwind": pages assembled from partials + content fragments
  *   - stack "shadcn":  served from the built dist/ folder (SPA fallback)
+ * Reverse proxy: when a request carries X-Forwarded-Prefix (Compound Context Studio's
+ *   same-origin proxy sends it), redirects are prefixed and root-absolute URL
+ *   attributes in served HTML are rewritten under the prefix.
  * Port: PORT env var > mockup.config.json "port" > first unused port from 4000.
  *   - A PORT env value is exact (Compound Context Studio's Start Hub passes it) — a busy
  *     port fails fast so the caller sees the error.
@@ -118,10 +128,11 @@ const net = require('net');
 const fs = require('fs');
 const path = require('path');
 
-const HUB_VERSION = 2;
+const HUB_VERSION = 3;
 const HUB_DIR = __dirname;
 const ROOT_DIR = path.resolve(HUB_DIR, '..');
 const SAFE_SEG = /^[A-Za-z0-9._-]+$/;
+const SAFE_PREFIX = /^\/[A-Za-z0-9/_-]*$/; // root-relative, no dots/query/fragment
 const PORT_SCAN_START = 4000; // default: first unused port starting here
 const PORT_SCAN_LIMIT = 100;
 
@@ -229,11 +240,39 @@ function findApp(slug) {
 
 // ── Response helpers ─────────────────────────────────────────────────────────
 
+/** The sanitized X-Forwarded-Prefix ('' when absent/unsafe), without trailing slash. */
+function requestPrefix(req) {
+  var raw = String(req.headers['x-forwarded-prefix'] || '');
+  if (raw.endsWith('/')) raw = raw.slice(0, -1);
+  return SAFE_PREFIX.test(raw) ? raw : '';
+}
+
+/**
+ * Rewrite root-absolute URL attributes so they stay under the proxy prefix. Covers hub
+ * pages AND per-app assets (tailwind partials/content with hx-* attributes, shadcn dist
+ * index.html, MOCKUP.html, reports) — including assets generated before hub v3.
+ */
+function applyPrefix(html, prefix) {
+  if (!prefix) return html;
+  return html.replace(
+    /(href|src|action|hx-get|hx-post|hx-put|hx-patch|hx-delete)="\//g,
+    '$1="' + prefix + '/'
+  );
+}
+
 function send(res, code, body, type) {
   res.writeHead(code, { 'Content-Type': type || 'text/html; charset=utf-8' });
   res.end(body);
 }
 
+/** All HTML goes out through this so root-absolute links are prefix-rewritten. The
+ *  X-Hub-Prefix header tells the studio proxy the hub already rewrote its HTML, so the
+ *  proxy skips its own legacy-hub rewrite pass (no double-prefixing). */
+function sendHtml(res, code, html, prefix) {
+  if (prefix) res.setHeader('X-Hub-Prefix', prefix);
+  send(res, code, applyPrefix(html, prefix), 'text/html; charset=utf-8');
+}
+
 function redirect(res, location) {
   res.writeHead(302, { Location: location });
   res.end();
@@ -252,12 +291,18 @@ function safeJoin(baseDir, segments) {
   return target;
 }
 
-function serveFile(res, filePath) {
+function serveFile(res, filePath, prefix) {
   if (!filePath) return false;
   let stat;
   try { stat = fs.statSync(filePath); } catch (err) { return false; }
   if (!stat.isFile()) return false;
-  const type = MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+  const ext = path.extname(filePath).toLowerCase();
+  const type = MIME[ext] || 'application/octet-stream';
+  // HTML files (MOCKUP.html, shadcn dist index.html, reports) get prefix-rewritten.
+  if (ext === '.html' && prefix) {
+    sendHtml(res, 200, fs.readFileSync(filePath, 'utf8'), prefix);
+    return true;
+  }
   send(res, 200, fs.readFileSync(filePath), type);
   return true;
 }
@@ -340,7 +385,9 @@ function renderAppCard(app) {
 
 // Port input (default: the current port — auto-picked as the first unused port from 4000
 // when nothing was configured). Apply persists to mockup.config.json via POST /api/port
-// and the hub re-listens on the new port; the page then follows it.
+// and the hub re-listens on the new port; the page then follows it. Behind a proxy
+// (HUB_PREFIX set) the page reloads the prefix root instead — the studio proxy reads
+// the new port from mockup.config.json, so the same URL keeps working.
 const PORT_SCRIPT = `
   function applyPort() {
     var msg = document.getElementById('port-msg');
@@ -349,25 +396,28 @@ const PORT_SCRIPT = `
       msg.style.color = '#dc2626'; msg.textContent = 'Port must be 1024-65535'; return;
     }
     msg.style.color = '#64748b'; msg.textContent = 'Applying\\u2026';
-    fetch('/api/port', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+    fetch(HUB_PREFIX + '/api/port', { method: 'POST', headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ port: port }) })
       .then(function (r) { return r.json(); })
       .then(function (res) {
         if (!res.ok) { msg.style.color = '#dc2626'; msg.textContent = res.error || 'Failed'; return; }
         msg.textContent = 'Restarting on port ' + res.port + '\\u2026';
         setTimeout(function () {
-          location.href = location.protocol + '//' + location.hostname + ':' + res.port + '/';
+          location.href = HUB_PREFIX
+            ? HUB_PREFIX + '/'
+            : location.protocol + '//' + location.hostname + ':' + res.port + '/';
         }, 700);
       })
       .catch(function () { msg.style.color = '#dc2626'; msg.textContent = 'Request failed'; });
   }
 `;
 
-function renderLanding(apps, currentPort) {
+function renderLanding(apps, currentPort, prefix) {
   return '<!DOCTYPE html>\n<html lang="en">\n<head>\n<meta charset="UTF-8">\n'
     + '<meta name="viewport" content="width=device-width, initial-scale=1.0">\n'
     + '<title>Mockup Hub</title>\n<style>' + LANDING_CSS + '</style>\n'
-    + '<script>' + PORT_SCRIPT + '</script>\n</head>\n<body>\n'
+    // prefix is SAFE_PREFIX-sanitized, so it embeds safely in the inline script.
+    + '<script>var HUB_PREFIX = "' + (prefix || '') + '";' + PORT_SCRIPT + '</script>\n</head>\n<body>\n'
     + '<div class="wrap">\n<h1>Mockup Hub</h1>\n'
     + '<p class="sub">All application mockups, served from one place. '
     + apps.length + ' application(s) discovered. Click a role to open its dashboard.</p>\n'
@@ -378,8 +428,8 @@ function renderLanding(apps, currentPort) {
     + '<span id="port-msg"></span></span></p>\n</div>\n</body>\n</html>';
 }
 
-function notReadyPage(app) {
-  return renderLanding([app], CURRENT_PORT);
+function notReadyPage(app, prefix) {
+  return renderLanding([app], CURRENT_PORT, prefix);
 }
 
 function notFoundPage(what) {
@@ -410,45 +460,46 @@ function assemblePage(app, role, page) {
 
 // ── Routing ──────────────────────────────────────────────────────────────────
 
-function routeTailwind(app, segs, res) {
+function routeTailwind(app, segs, res, prefix) {
   if (segs.length === 1) {
-    if (serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) return;
+    if (serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'), prefix)) return;
     const first = app.roles.find((r) => r.slug);
-    if (first) return redirect(res, '/' + app.slug + '/' + first.slug + '/home');
-    return send(res, 404, notFoundPage(app.slug));
+    if (first) return redirect(res, prefix + '/' + app.slug + '/' + first.slug + '/home');
+    return sendHtml(res, 404, notFoundPage(app.slug), prefix);
   }
   if (segs[1] === 'static' || segs[1] === 'reports') {
     const file = safeJoin(path.join(app.mockupDir, segs[1]), segs.slice(2));
-    if (serveFile(res, file)) return;
-    return send(res, 404, notFoundPage());
+    if (serveFile(res, file, prefix)) return;
+    return sendHtml(res, 404, notFoundPage(), prefix);
   }
-  if (!SAFE_SEG.test(segs[1])) return send(res, 400, notFoundPage());
-  if (segs.length === 2) return redirect(res, '/' + app.slug + '/' + segs[1] + '/home');
+  if (!SAFE_SEG.test(segs[1])) return sendHtml(res, 400, notFoundPage(), prefix);
+  if (segs.length === 2) return redirect(res, prefix + '/' + app.slug + '/' + segs[1] + '/home');
   if (segs.length === 3 && SAFE_SEG.test(segs[2])) {
     const html = assemblePage(app, segs[1], segs[2]);
     if (html === null) {
       return send(res, 500, '<h1>Missing partials. Re-run the mockup generator.</h1>');
     }
-    return send(res, 200, html);
+    return sendHtml(res, 200, html, prefix);
   }
-  return send(res, 404, notFoundPage());
+  return sendHtml(res, 404, notFoundPage(), prefix);
 }
 
-function routeShadcn(app, segs, res) {
-  if (segs.length === 1 && serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) return;
+function routeShadcn(app, segs, res, prefix) {
+  if (segs.length === 1 && serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'), prefix)) return;
   if (segs[1] === 'reports') {
     const file = safeJoin(path.join(app.mockupDir, 'public', 'reports'), segs.slice(2));
-    if (serveFile(res, file)) return;
-    return send(res, 404, notFoundPage());
+    if (serveFile(res, file, prefix)) return;
+    return sendHtml(res, 404, notFoundPage(), prefix);
   }
   const distDir = path.join(app.mockupDir, 'dist');
   if (segs.length > 1) {
     const file = safeJoin(distDir, segs.slice(1));
-    if (serveFile(res, file)) return;
+    if (serveFile(res, file, prefix)) return;
   }
-  // SPA fallback — React Router (basename /{app_slug}) handles the path client-side
-  if (serveFile(res, path.join(distDir, 'index.html'))) return;
-  return send(res, 404, notFoundPage(app.slug));
+  // SPA fallback — React Router handles the path client-side (the app derives its
+  // basename from the current URL, so it also works under a proxy prefix)
+  if (serveFile(res, path.join(distDir, 'index.html'), prefix)) return;
+  return sendHtml(res, 404, notFoundPage(app.slug), prefix);
 }
 
 // POST /api/port — persist a new port (from the landing page's port input) and re-listen.
@@ -473,8 +524,11 @@ function handlePortUpdate(req, res) {
 function route(req, res) {
   const urlPath = decodeURIComponent((req.url || '/').split('?')[0]);
   const segs = urlPath.split('/').filter(Boolean);
+  const prefix = requestPrefix(req); // '' unless behind a prefix-forwarding proxy
 
-  if (segs.length === 0) return send(res, 200, renderLanding(discoverApps(), CURRENT_PORT));
+  if (segs.length === 0) {
+    return sendHtml(res, 200, renderLanding(discoverApps(), CURRENT_PORT, prefix), prefix);
+  }
   if (urlPath === '/favicon.ico') { res.writeHead(204); return res.end(); }
 
   if (segs[0] === 'api' && segs[1] === 'port' && segs.length === 2 && req.method === 'POST') {
@@ -483,26 +537,28 @@ function route(req, res) {
 
   // HTMX fragment endpoint (tailwind): /api/content/:app/:role/:page
   if (segs[0] === 'api' && segs[1] === 'content') {
-    if (segs.length !== 5) return send(res, 404, notFoundPage());
+    if (segs.length !== 5) return sendHtml(res, 404, notFoundPage(), prefix);
     const app = findApp(segs[2]);
     if (!app || app.status !== 'ready' || app.stack !== 'tailwind') {
-      return send(res, 404, notFoundPage(segs[2]));
+      return sendHtml(res, 404, notFoundPage(segs[2]), prefix);
+    }
+    if (!SAFE_SEG.test(segs[3]) || !SAFE_SEG.test(segs[4])) {
+      return sendHtml(res, 400, notFoundPage(), prefix);
     }
-    if (!SAFE_SEG.test(segs[3]) || !SAFE_SEG.test(segs[4])) return send(res, 400, notFoundPage());
     const content = readText(path.join(app.mockupDir, segs[3], 'content', segs[4] + '.html'));
     if (content === null) {
       return send(res, 404, '<div class="p-6 text-red-500">Content not found.</div>');
     }
-    return send(res, 200, content);
+    return sendHtml(res, 200, content, prefix);
   }
 
-  if (!SAFE_SEG.test(segs[0])) return send(res, 400, notFoundPage());
+  if (!SAFE_SEG.test(segs[0])) return sendHtml(res, 400, notFoundPage(), prefix);
   const app = findApp(segs[0]);
-  if (!app) return send(res, 404, notFoundPage(segs[0]));
-  if (app.status !== 'ready') return send(res, 200, notReadyPage(app));
+  if (!app) return sendHtml(res, 404, notFoundPage(segs[0]), prefix);
+  if (app.status !== 'ready') return sendHtml(res, 200, notReadyPage(app, prefix), prefix);
 
-  if (app.stack === 'shadcn') return routeShadcn(app, segs, res);
-  return routeTailwind(app, segs, res);
+  if (app.stack === 'shadcn') return routeShadcn(app, segs, res, prefix);
+  return routeTailwind(app, segs, res, prefix);
 }
 
 // ── Start ────────────────────────────────────────────────────────────────────
@@ -627,5 +683,7 @@ Mockup Hub
 3. Open http://localhost:4000 in your browser
    (the hub picks the first unused port from 4000; the exact URL is printed on start.
     Change port: the landing page's Port input, PORT=4100 npm start, or edit
-    mockup.config.json — or use Compound Context Studio's Mockup page Start/Stop Hub.)
+    mockup.config.json — or use Compound Context Studio's Mockup page Start/Stop Hub.
+    Inside the studio the hub is embedded through its same-origin proxy — no need to
+    expose this port when the studio itself is reachable.)
 ```

package/plugin/skills/util-gencicdscript/SKILL.md

@@ -21,8 +21,12 @@ description: >
   copy, docker run or kubectl apply, or none). Controls are disabled for any application that
   has never completed a conductor-develop workflow run (checked against the studio's
   /api/cicd-guard endpoint using the spawn-env token). Health/port probing marks apps already
-  running — even ones started outside this app. No version selector: only the latest built
-  applications are operated. When the approved plan declares an `## Infrastructure` list, the
+  running — even ones started outside this app. The top bar carries a version selector (fed by
+  the studio guard's versions, latest preselected) whose choice replaces the {VERSION} token in
+  commands — docker images are tagged <repo>/<app>:<version> when the plan's Docker section is
+  active (managed Dockerfiles materialized before Build when missing; Build never pushes) — and
+  Build All / Start All / Stop All buttons operating every eligible application at once
+  (sequential builds). When the approved plan declares an `## Infrastructure` list, the
   main page shows an "Infrastructure" link that opens a separate status-only page listing every
   supporting 3rd-party service with a live TCP-reachability indicator and a console link. Writes cicd/CICD_GENERATION.md with `**Status**:` IN PROGRESS →
   COMPLETED so the studio watcher detects completion. Idempotent — re-running regenerates
@@ -62,9 +66,17 @@ Write `cicd/CICD_GENERATION.md`:
 Read `references/cicd-app-template.md` for the complete file templates. Produce:
 
 1. `cicd/app/cicd.config.json` — from the plan's tables:
-   `{ "port": <CI/CD app port>, "apps": [{ "name", "folder", "method", "port", "build",
-   "start", "stop", "deployMethod", "deploy", "health", "configs" }], "infra": [{ "id", "name",
-   "host", "port", "url", "description" }] }` — `deployMethod` is the plan's Deploy Method column
+   `{ "port": <CI/CD app port>, "docker": { "registry" } | null, "apps": [{ "name", "folder",
+   "method", "port", "build", "start", "stop", "deployMethod", "deploy", "health", "image",
+   "dockerfile", "configs" }], "infra": [{ "id", "name",
+   "host", "port", "url", "description" }] }` — `docker.registry` comes from the plan's
+   `## Docker` section (`null` when the plan says not dockerized); per-app `image` is that
+   section's Image column (`null` for non-dockerized apps) and `dockerfile` is
+   `{ "path": "Dockerfile", "content": "<body>" }` for a `managed` Dockerfile from the plan's
+   `## Dockerfiles` section, or `{ "path": "Dockerfile", "content": null }` for an `existing`
+   one (`null` entirely when the app has no image). Copy managed Dockerfile bodies verbatim.
+   Commands may carry the literal `{VERSION}` token — copy it verbatim; the generated app
+   substitutes it at execution. `deployMethod` is the plan's Deploy Method column
    (`none|web-server|docker|kubernetes`) and `deploy` its command (`null` when the method is
    `none`). The `infra` array comes from the plan's `## Infrastructure` table (one entry per
    row); `url` is `null` when the Console URL cell is `-`. Emit `"infra": []` when the plan's
@@ -104,11 +116,25 @@ port, application count) and STOP — the studio starts/embeds the app.
   3rd-party services, each with a live TCP-reachability dot (polled) and a console link when a
   `url` is set. Infrastructure is never built/started/stopped/deployed (no lifecycle controls,
   no develop gate); the link is hidden when `infra` is empty.
-- Build/Start/Stop/Deploy run the plan's commands verbatim, each with the APPLICATION FOLDER
+- Build/Start/Stop/Deploy run the plan's commands, each with the APPLICATION FOLDER
   (`<project>/<folder>`) as working directory — command paths are relative to the application
   folder (e.g. `java -jar target\app.jar`), never to the project root. Deploy renders only
-  when the plan assigned a deploy method other than `none`. No version selector — only the
-  latest built applications are operated.
+  when the plan assigned a deploy method other than `none`.
+- **Version selector (topbar)**: the page's top bar carries a version dropdown fed by the
+  studio guard response's `versions` array (already polled every 30 s; latest first —
+  preselected). When the studio is unreachable the selector holds a single `latest` entry.
+  The selected semver, minus its `v` prefix, replaces every literal `{VERSION}` in
+  build/start/stop/deploy commands at execution time (fallback `latest`). Tag-only
+  semantics: the code built is always the working tree — the selector never checks out code.
+- **Dockerfile materialization**: before Build, when an app's `dockerfile.content` is set and
+  no file exists at its path in the application folder, the server writes it (never
+  overwriting an existing Dockerfile — mirror of the managed-config rule). Build never
+  pushes an image; pushing belongs to a `docker` deploy command.
+- **All-apps controls**: the top bar carries **Build All**, **Start All** and **Stop All**
+  buttons. Build All builds eligible apps SEQUENTIALLY (one at a time — honest logs, no CPU
+  storm); Start All starts every eligible stopped app; Stop All stops every running app.
+  Eligible = develop-gate not failed, not busy, and (for build/start) not already running;
+  ineligible apps are skipped silently — per-tab badges show progress.
 - Develop gate: controls stay disabled for an application that never completed a
   conductor-develop run — checked via `${CO2_STUDIO_URL}/api/cicd-guard/${CO2_PROJECT_ID}`
   with the CO2_GUARD_TOKEN from the spawn env (refreshed every 30 s, last answer cached).

package/plugin/skills/util-gencicdscript/references/cicd-app-template.md

@@ -66,6 +66,7 @@ function currentBranch() {
 // its tab controls are disabled. Refreshed every 30 s; the last known answer is kept when the
 // studio is briefly unreachable, and `null` (never fetched) disables controls with a hint.
 let guardApps = null // Map lower(name|folder) -> developedOnce
+let guardVersions = [] // project versions (semver strings, studio order — latest first)
 async function refreshGuard() {
   if (!PROJECT_ID) return
   try {
@@ -76,6 +77,8 @@ async function refreshGuard() {
       guardApps = new Map()
       for (const a of g.applications) guardApps.set(String(a.name).toLowerCase(), !!a.developedOnce)
     }
+    // The topbar version selector's choices — the {VERSION} tag substituted into commands.
+    if (Array.isArray(g.versions)) guardVersions = g.versions.map((v) => String(v.semver)).filter(Boolean)
   } catch {}
 }
 function developedOnce(app) {
@@ -226,36 +229,58 @@ function tcpProbe(host, port, timeout = 1000) {
   })
 }
 
-function buildApp(app) {
-  if (activity.has(app.name)) return
+// {VERSION} token substitution — the version comes from the page's topbar selector (the
+// studio guard's versions, latest preselected). Tag-only: never checks out code. The `v`
+// prefix is stripped so docker tags read `1.2.0`, not `v1.2.0`.
+function subst(cmd, version) {
+  return String(cmd || '').replaceAll('{VERSION}', String(version || 'latest').replace(/^v/, ''))
+}
+
+// Managed Dockerfile from the plan's ## Dockerfiles — written before Build only when the
+// application folder has none (an existing Dockerfile is never overwritten).
+function ensureDockerfile(app) {
+  const d = app.dockerfile
+  if (!d || d.content == null) return
+  const abs = join(PROJECT_DIR, app.folder, d.path || 'Dockerfile')
+  if (existsSync(abs)) return
+  try {
+    writeFileSync(abs, d.content)
+    logLine(app, `dockerfile: wrote ${d.path || 'Dockerfile'} from the plan (was missing)`)
+  } catch (e) { logLine(app, `dockerfile: FAILED to write — ${e.message}`) }
+}
+
+function buildApp(app, version, onDone) {
+  if (activity.has(app.name)) { onDone && onDone(); return }
   activity.set(app.name, 'building'); lastError.delete(app.name)
   ensureConfigs(app)
-  runLogged(app, app.build, (code) => {
+  ensureDockerfile(app)
+  runLogged(app, subst(app.build, version), (code) => {
     activity.delete(app.name)
     if (code !== 0) lastError.set(app.name, `build exited ${code} — see log`)
     else logLine(app, 'build OK')
+    onDone && onDone()
   })
 }
 
-function deployApp(app) {
+function deployApp(app, version) {
   if (activity.has(app.name) || !app.deploy) return
   activity.set(app.name, 'deploying'); lastError.delete(app.name)
-  runLogged(app, app.deploy, (code) => {
+  runLogged(app, subst(app.deploy, version), (code) => {
     activity.delete(app.name)
     if (code !== 0) lastError.set(app.name, `deploy exited ${code} — see log`)
     else logLine(app, `deploy OK (${app.deployMethod})`)
   })
 }
 
-function startApp(app) {
+function startApp(app, version) {
   if (running.get(app.name) || activity.has(app.name)) return
   failed.delete(app.name); lastError.delete(app.name)
   ensureConfigs(app)
   if (app.method === 'container') {
-    runLogged(app, app.start, () => {})
+    runLogged(app, subst(app.start, version), () => {})
     saveState(); return
   }
-  const child = runLogged(app, app.start, (code) => {
+  const child = runLogged(app, subst(app.start, version), (code) => {
     running.delete(app.name)
     // A user-requested Stop exits nonzero (killed) — that is not a failure.
     if (code !== 0 && !stopping.delete(app.name)) {
@@ -302,9 +327,10 @@ function killByPort(port) {
   } catch { return false }
 }
 
-function stopApp(app) {
+function stopApp(app, version) {
   if (app.method === 'container' && app.stop && app.stop !== 'process-kill') {
-    try { execFileSync(app.stop.split(' ')[0], app.stop.split(' ').slice(1), { cwd: PROJECT_DIR }) } catch {}
+    const stopCmd = subst(app.stop, version)
+    try { execFileSync(stopCmd.split(' ')[0], stopCmd.split(' ').slice(1), { cwd: PROJECT_DIR }) } catch {}
   } else {
     const child = running.get(app.name)
     if (child) {
@@ -342,6 +368,7 @@ body{font-family:system-ui,sans-serif;margin:0;background:#f6f7f9;color:#1c2128;
 .badge.running{background:#1c8a4a}.badge.failed{background:#c23b3b}.badge.building,.badge.deploying{background:#c9922a}
 .url{font-size:12px;color:#1a66d0;text-decoration:underline;word-break:break-all}
 button{background:#fff;color:#1c2128;border:1px solid #c6cdd6;border-radius:6px;padding:4px 12px;font-size:12px;cursor:pointer}
+select{background:#fff;color:#1c2128;border:1px solid #c6cdd6;border-radius:6px;padding:3px 6px;font-size:12px}
 button:hover:enabled{background:#eef1f5}
 button:disabled{opacity:.4;cursor:default}
 .notice{padding:4px 12px;font-size:11px;color:#8a5a00;background:#fff7e6;display:none}
@@ -361,7 +388,12 @@ button:disabled{opacity:.4;cursor:default}
 .cfg .keys{font-size:11px;color:#5b6572;margin:2px 0}
 .cfg pre{background:#0f1216;color:#d7dde4;font-size:11px;padding:8px 10px;border-radius:6px;overflow:auto;max-height:320px;white-space:pre-wrap;margin:4px 0 0}
 </style></head><body>
-<div class="top"><strong>CI/CD</strong><span id="branch" class="meta"></span><span style="flex:1"></span><a id="infralink" class="url" href="/infra" target="_blank" rel="noreferrer" style="display:none">Infrastructure ↗</a></div>
+<div class="top"><strong>CI/CD</strong><span id="branch" class="meta"></span>
+<span class="meta">version</span><select id="ver" title="Tag substituted into {VERSION} in commands (docker image tag)"><option value="">latest</option></select>
+<button onclick="actAll('build')" title="Build every eligible application, one at a time">Build All</button>
+<button onclick="actAll('start')" title="Start every eligible stopped application">Start All</button>
+<button onclick="actAll('stop')" title="Stop every running application">Stop All</button>
+<span style="flex:1"></span><a id="infralink" class="url" href="/infra" target="_blank" rel="noreferrer" style="display:none">Infrastructure ↗</a></div>
 <div class="tabs" id="tabs"></div>
 <div class="bar" id="bar"></div>
 <div class="notice" id="notice"></div>
@@ -399,7 +431,7 @@ function renderBar(){
     <a class="url" href="\${url}" target="_blank" rel="noreferrer">\${url}</a>
     <span style="flex:1"></span>
     <button onclick="openConfig()" title="Show this application's runtime configuration files">Config</button>
-    <button onclick="act('build')" \${!gate||busy||a.phase==='running'?'disabled':''}>Build</button>
+    <button onclick="act('build')" \${!gate||busy||a.phase==='running'?'disabled':''} title="\${a.image?'Builds the app AND the docker image '+a.image+':<version>':'Runs the plan build command'}">Build</button>
     <button onclick="act('start')" \${!gate||busy||a.phase==='running'?'disabled':''}>Start</button>
     <button onclick="act('stop')" \${a.phase!=='running'?'disabled':''}>Stop</button>
     \${a.deploy?\`<button onclick="act('deploy')" \${!gate||busy?'disabled':''}>Deploy (\${a.deployMethod})</button>\`:''}\`
@@ -467,17 +499,35 @@ async function openConfig(){
 function closeConfig(){ document.getElementById('cfgModal').classList.remove('open') }
 document.addEventListener('keydown', e => { if (e.key === 'Escape') closeConfig() })
 
+// Topbar version selector — the studio guard's project versions (latest first). Repopulated
+// only when the list changes so the user's selection survives the 3 s poll.
+let verChoices = ''
+function renderVersions(versions){
+  const sel = document.getElementById('ver')
+  const list = (versions && versions.length ? versions : []).join('|')
+  if (list === verChoices) return
+  verChoices = list
+  sel.innerHTML = (versions && versions.length ? versions : ['latest'])
+    .map((v, i) => '<option value="'+esc(v)+'"'+(i===0?' selected':'')+'>'+esc(v)+'</option>').join('')
+}
+function selectedVersion(){ return document.getElementById('ver').value || '' }
+
 async function refresh(){
   const s = await fetch('/api/state').then(r => r.json()).catch(() => null)
   if (!s) return
   state = s
   document.getElementById('branch').textContent = s.currentBranch ? 'branch: '+s.currentBranch : ''
   document.getElementById('infralink').style.display = s.hasInfra ? 'inline' : 'none'
+  renderVersions(s.versions)
   if (!active && s.apps.length) setActive(s.apps[0].name)
   renderTabs(); renderBar()
 }
 async function act(op){
-  await fetch('/api/apps/'+encodeURIComponent(active)+'/'+op, { method: 'POST' })
+  await fetch('/api/apps/'+encodeURIComponent(active)+'/'+op+'?version='+encodeURIComponent(selectedVersion()), { method: 'POST' })
+  refresh()
+}
+async function actAll(op){
+  await fetch('/api/all/'+op+'?version='+encodeURIComponent(selectedVersion()), { method: 'POST' })
   refresh()
 }
 // Rescan immediately when the user returns to this page (tab focus / regained visibility), so
@@ -553,12 +603,18 @@ const server = http.createServer(async (req, res) => {
       return {
         name: a.name, method: a.method, port: a.port, phase,
         deploy: !!a.deploy, deployMethod: a.deployMethod || 'none',
+        image: a.image || null,
         external: healthy && !running.has(a.name),
         developedOnce: developedOnce(a),
         error: lastError.get(a.name) || null,
       }
     }))
-    return json(res, 200, { currentBranch: currentBranch(), hasInfra: (loadConfig().infra || []).length > 0, apps })
+    return json(res, 200, {
+      currentBranch: currentBranch(),
+      hasInfra: (loadConfig().infra || []).length > 0,
+      versions: guardVersions,
+      apps,
+    })
   }
   const cfgm = req.url && req.url.match(/^\/api\/apps\/([^/]+)\/config$/)
   if (cfgm && req.method === 'GET') {
@@ -566,19 +622,54 @@ const server = http.createServer(async (req, res) => {
     if (!app) return json(res, 404, { error: 'unknown app' })
     return json(res, 200, { configs: (app.configs || []).map((c) => readConfig(app, c)) })
   }
-  const m = req.url && req.url.match(/^\/api\/apps\/([^/]+)\/(build|start|stop|deploy)$/)
+  // ?version=<semver> on every action — the topbar selection, substituted into {VERSION}.
+  const reqVersion = (() => {
+    try { return new URL(req.url, 'http://x').searchParams.get('version') || '' } catch { return '' }
+  })()
+  const path = (req.url || '').split('?')[0]
+  const m = path.match(/^\/api\/apps\/([^/]+)\/(build|start|stop|deploy)$/)
   if (m && req.method === 'POST') {
     const app = loadConfig().apps.find((a) => a.name === decodeURIComponent(m[1]))
     if (!app) return json(res, 404, { error: 'unknown app' })
     if (m[2] !== 'stop' && developedOnce(app) === false) {
       return json(res, 409, { error: 'application has not completed a develop workflow run' })
     }
-    if (m[2] === 'build') buildApp(app)
-    else if (m[2] === 'start') startApp(app)
-    else if (m[2] === 'deploy') deployApp(app)
-    else stopApp(app)
+    if (m[2] === 'build') buildApp(app, reqVersion)
+    else if (m[2] === 'start') startApp(app, reqVersion)
+    else if (m[2] === 'deploy') deployApp(app, reqVersion)
+    else stopApp(app, reqVersion)
     return json(res, 200, { ok: true })
   }
+  // All-apps controls. Eligible = develop gate not failed and not mid-build/deploy; build and
+  // start additionally skip apps already running. Builds run SEQUENTIALLY (honest logs, no
+  // CPU storm); start/stop fire together. Ineligible apps are skipped silently.
+  const all = path.match(/^\/api\/all\/(build|start|stop)$/)
+  if (all && req.method === 'POST') {
+    const op = all[1]
+    const apps = loadConfig().apps
+    if (op === 'stop') {
+      for (const a of apps) {
+        if (running.has(a.name)) stopApp(a, reqVersion)
+        else probe(a).then((up) => { if (up) stopApp(a, reqVersion) })
+      }
+      return json(res, 200, { ok: true })
+    }
+    const eligible = []
+    for (const a of apps) {
+      if (developedOnce(a) === false || activity.has(a.name)) continue
+      if (await probe(a)) continue // already running — skip for build AND start
+      eligible.push(a)
+    }
+    if (op === 'start') {
+      for (const a of eligible) startApp(a, reqVersion)
+      return json(res, 200, { ok: true, count: eligible.length })
+    }
+    // op === 'build' — sequential chain: each build starts when the previous one exits.
+    const queue = [...eligible]
+    const next = () => { const a = queue.shift(); if (a) buildApp(a, reqVersion, next) }
+    next()
+    return json(res, 200, { ok: true, count: eligible.length })
+  }
   json(res, 404, { error: 'not found' })
 })
 
@@ -619,6 +710,16 @@ Decisions table, one `infra` entry per row of the plan's `## Infrastructure` tab
 is `none`). `infra[].url` is `null` for a headless service (Console URL cell `-`); emit
 `"infra": []` when the plan declares no supporting services.
 
+Docker fields (from the plan's `## Docker` / `## Dockerfiles` sections): top-level
+`"docker": { "registry": "<repo>" }` or `null` when the plan is not dockerized. Per app,
+`"image"` is the Docker table's Image value (`null` for a non-dockerized app) and
+`"dockerfile"` is `{ "path": "Dockerfile", "content": "<managed body>" }` for a `managed`
+Dockerfile (materialized before Build when missing — never overwriting), or
+`{ "path": "Dockerfile", "content": null }` for an `existing` one (`null` entirely when the
+app has no image). Commands may carry the literal `{VERSION}` token — copied verbatim; the
+server substitutes the topbar-selected version (semver sans `v`, fallback `latest`) at
+execution time.
+
 Each app also carries a `configs` array — the runtime config files the application reads at start,
 from the plan's `## Application Configs` section (one entry per file). Fields:
 `path` (relative to the application folder), `label`, `source` (`environment` | `env-file` |
@@ -633,18 +734,24 @@ verbatim (this is a local dev CI/CD app).
 ```json
 {
   "port": 4100,
+  "docker": { "registry": "registry.example.com/team" },
   "apps": [
     {
       "name": "my-app",
       "folder": "my-app",
       "method": "process",
       "port": 3000,
-      "build": "pnpm install && pnpm build",
+      "build": "pnpm install && pnpm build && docker build -t registry.example.com/team/my-app:{VERSION} .",
       "start": "node dist/index.js",
       "stop": "process-kill",
       "deployMethod": "kubernetes",
       "deploy": "kubectl apply -f my-app/k8s/",
       "health": "http://127.0.0.1:3000/",
+      "image": "registry.example.com/team/my-app",
+      "dockerfile": {
+        "path": "Dockerfile",
+        "content": "FROM node:22-slim\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --omit=dev\nCOPY . .\nEXPOSE 3000\nCMD [\"node\", \"dist/index.js\"]\n"
+      },
       "configs": [
         {
           "path": ".env",