@rashidee/co2 1.3.7 → 1.3.9

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

@@ -1,498 +1,631 @@
-# Mockup Hub — Single Node Server for ALL Application Mockups
-
-The Mockup Hub is ONE zero-dependency Node.js application at `<root>/mockup/` that serves
-the mockups of EVERY application in the project. Per-application mockup folders
-(`<app_folder>/context/mockup/`) contain ONLY assets (HTML/CSS/JS/images + a manifest) —
-they contain NO server of their own.
-
-- **Tailwind mockups** (`mockgen-tailwind`): the hub assembles shell + header + sidebar +
-  content + footer server-side at `/{app_slug}/{role}/{page}`.
-- **shadcn mockups** (`mockgen-shadcn`): the hub serves the app's built `dist/` folder at
-  `/{app_slug}/...` with SPA fallback to `dist/index.html`.
-- **Landing page** at `/`: dynamically lists ALL applications and their roles. Roles are
-  clickable only when the app's mockup is ready; otherwise they render as disabled
-  (grayed, no `href`) chips with a status hint ("Mockups not generated yet" /
-  "Build required").
-- **Port** is configurable: `PORT` env var → `mockup.config.json` `port` → default `3000`.
-
-The hub has **zero npm dependencies** — `npm start` (or `node server.js`) works with no
-`npm install`.
-
-## File Structure
-
-```
-<root>/
-  mockup/                     # ← the hub (this template)
-    server.js                 # zero-dependency Node HTTP server
-    package.json              # no dependencies; "start": "node server.js"
-    mockup.config.json        # { "port": 3000 } — user-editable
-    .gitignore
-  1_first_app/
-    context/mockup/           # assets only (+ mockup-manifest.json)
-  2_second_app/
-    context/mockup/
-```
-
-## Ensure-Hub Rules (run by every mockgen-* execution, including module-filtered runs)
-
-1. If `<root>/mockup/server.js` does NOT exist: create ALL four hub files from the
-   templates below.
-2. If it exists: read the `HUB_VERSION` constant in the existing `server.js`.
-   - Existing version **< template version** → overwrite `server.js` and `package.json`
-     with the templates (upgrade).
-   - Existing version **>= template version**, or no marker found (user-customized) →
-     leave `server.js` and `package.json` untouched.
-3. `mockup.config.json`: create ONLY if missing. NEVER overwrite an existing one — it
-   holds the user's port choice. It is per-machine and gitignored.
-4. `.gitignore`: create ONLY if missing.
-5. Never place per-application assets inside `<root>/mockup/`. Conversely, everything the
-   hub generates or needs (config, logs, any `node_modules/`) stays inside `<root>/mockup/`
-   and is covered by its `.gitignore`.
-
-## mockup-manifest.json Schema (written to `<app_folder>/context/mockup/`)
-
-Every mockgen-* run writes/updates this file. The hub uses it for discovery, routing and
-the landing page.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `app` | string | App slug used in URLs = app folder name minus leading `<number>_` (e.g. `hub_middleware`) |
-| `appName` | string | Display name (e.g. "Hub Middleware") |
-| `description` | string | Short app description from PRD.md |
-| `stack` | string | `"tailwind"` or `"shadcn"` |
-| `version` | string | Target version the mockups were generated for (e.g. `v1.0.3`) |
-| `generatedAt` | string | ISO date of the last generation |
-| `roles` | array | One entry per role: `{ "name", "slug", "screens" }`. `slug` uses the stack's convention — snake_case (tailwind) or kebab-case (shadcn). `screens` = number of screens generated for the role |
-| `reports` | array (optional) | Report layout file names, if any |
-
-Example:
-
-```json
-{
-  "app": "hub_middleware",
-  "appName": "Hub Middleware",
-  "description": "Central middleware for labour mobility data exchange.",
-  "stack": "tailwind",
-  "version": "v1.0.3",
-  "generatedAt": "2026-07-12",
-  "roles": [
-    { "name": "Hub Administrator", "slug": "hub_administrator", "screens": 12 },
-    { "name": "Hub Operation Support", "slug": "hub_operation_support", "screens": 9 }
-  ],
-  "reports": ["staff_allocation_summary.html"]
-}
-```
-
-## server.js Template
-
-```javascript
-#!/usr/bin/env node
-/*
- * CO2 Mockup Hub — one server for ALL application mockups.
- * HUB_VERSION: 1   (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)
- * Port: PORT env var > mockup.config.json "port" > 3000.
- */
-'use strict';
-
-const http = require('http');
-const fs = require('fs');
-const path = require('path');
-
-const HUB_VERSION = 1;
-const HUB_DIR = __dirname;
-const ROOT_DIR = path.resolve(HUB_DIR, '..');
-const SAFE_SEG = /^[A-Za-z0-9._-]+$/;
-
-function resolvePort() {
-  const envPort = parseInt(process.env.PORT || '', 10);
-  if (Number.isInteger(envPort) && envPort > 0) return envPort;
-  try {
-    const cfg = JSON.parse(fs.readFileSync(path.join(HUB_DIR, 'mockup.config.json'), 'utf8'));
-    const cfgPort = parseInt(cfg.port, 10);
-    if (Number.isInteger(cfgPort) && cfgPort > 0) return cfgPort;
-  } catch (err) { /* missing/invalid config — use default */ }
-  return 3000;
-}
-
-const MIME = {
-  '.html': 'text/html; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.js': 'text/javascript; charset=utf-8',
-  '.mjs': 'text/javascript; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.ico': 'image/x-icon',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.ttf': 'font/ttf',
-  '.map': 'application/json',
-  '.txt': 'text/plain; charset=utf-8',
-  '.pdf': 'application/pdf',
-};
-
-// ── Discovery ────────────────────────────────────────────────────────────────
-
-function titleCase(slug) {
-  return slug.replace(/[_-]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-function rolesFromPrd(appDir) {
-  try {
-    const prd = fs.readFileSync(path.join(appDir, 'context', 'PRD.md'), 'utf8');
-    const names = new Set();
-    for (const line of prd.split('\n')) {
-      if (line.includes('~~')) continue; // skip strikethrough (deprecated) items
-      const m = line.match(/As an? (.+?) user/);
-      if (m) names.add(m[1].trim());
-    }
-    return Array.from(names).map((name) => ({ name, slug: null, screens: 0 }));
-  } catch (err) {
-    return [];
-  }
-}
-
-function discoverApps() {
-  let entries;
-  try { entries = fs.readdirSync(ROOT_DIR, { withFileTypes: true }); } catch (err) { return []; }
-  const apps = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const appDir = path.join(ROOT_DIR, entry.name);
-    if (!fs.existsSync(path.join(appDir, 'context', 'PRD.md'))) continue;
-    const slug = entry.name.replace(/^\d+_/, '');
-    const mockupDir = path.join(appDir, 'context', 'mockup');
-    let manifest = null;
-    try {
-      manifest = JSON.parse(fs.readFileSync(path.join(mockupDir, 'mockup-manifest.json'), 'utf8'));
-    } catch (err) { /* mockups not generated yet */ }
-    let status = 'not-generated';
-    if (manifest && manifest.stack === 'shadcn') {
-      status = fs.existsSync(path.join(mockupDir, 'dist', 'index.html')) ? 'ready' : 'build-required';
-    } else if (manifest) {
-      status = fs.existsSync(path.join(mockupDir, 'partials', 'shell.html')) ? 'ready' : 'not-generated';
-    }
-    apps.push({
-      slug,
-      folder: entry.name,
-      appName: (manifest && manifest.appName) || titleCase(slug),
-      description: (manifest && manifest.description) || '',
-      version: (manifest && manifest.version) || '',
-      stack: manifest ? manifest.stack : null,
-      status,
-      mockupDir,
-      roles: manifest ? (manifest.roles || []) : rolesFromPrd(appDir),
-    });
-  }
-  return apps.sort((a, b) => a.folder.localeCompare(b.folder));
-}
-
-function findApp(slug) {
-  return discoverApps().find((a) => a.slug === slug) || null;
-}
-
-// ── Response helpers ─────────────────────────────────────────────────────────
-
-function send(res, code, body, type) {
-  res.writeHead(code, { 'Content-Type': type || 'text/html; charset=utf-8' });
-  res.end(body);
-}
-
-function redirect(res, location) {
-  res.writeHead(302, { Location: location });
-  res.end();
-}
-
-function escapeHtml(s) {
-  return String(s)
-    .replace(/&/g, '&amp;').replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-function safeJoin(baseDir, segments) {
-  if (!segments.every((s) => SAFE_SEG.test(s))) return null;
-  const target = path.normalize(path.join(baseDir, segments.join(path.sep)));
-  if (target !== baseDir && !target.startsWith(baseDir + path.sep)) return null;
-  return target;
-}
-
-function serveFile(res, filePath) {
-  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';
-  send(res, 200, fs.readFileSync(filePath), type);
-  return true;
-}
-
-function readText(filePath) {
-  try { return fs.readFileSync(filePath, 'utf8'); } catch (err) { return null; }
-}
-
-// ── Landing page ─────────────────────────────────────────────────────────────
-
-const LANDING_CSS = `
-  * { box-sizing: border-box; margin: 0; }
-  body { font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
-         background: #f1f5f9; color: #0f172a; padding: 40px 20px; }
-  .wrap { max-width: 960px; margin: 0 auto; }
-  h1 { font-size: 26px; margin-bottom: 4px; }
-  .sub { color: #64748b; font-size: 14px; margin-bottom: 28px; }
-  .card { background: #fff; border: 1px solid #e2e8f0; border-radius: 12px;
-          padding: 20px; margin-bottom: 16px; }
-  .card h2 { font-size: 18px; display: inline; }
-  .meta { color: #94a3b8; font-size: 12px; margin-left: 8px; }
-  .badge { display: inline-block; font-size: 11px; padding: 2px 8px; border-radius: 999px;
-           margin-left: 8px; vertical-align: 2px; }
-  .badge.ready { background: #dcfce7; color: #166534; }
-  .badge.pending { background: #fef3c7; color: #92400e; }
-  .hint { color: #94a3b8; font-size: 12px; margin-top: 10px; }
-  .hint code { background: #f1f5f9; padding: 1px 5px; border-radius: 4px; }
-  .roles { margin-top: 12px; display: flex; flex-wrap: wrap; gap: 8px; }
-  .role { display: inline-block; font-size: 13px; padding: 6px 14px; border-radius: 8px;
-          border: 1px solid #cbd5e1; text-decoration: none; color: #0f172a; }
-  a.role:hover { border-color: #2563eb; color: #2563eb; }
-  .role.disabled { color: #cbd5e1; border-color: #e2e8f0; cursor: not-allowed; }
-  .index-link { font-size: 12px; margin-left: 8px; }
-  .foot { color: #94a3b8; font-size: 12px; text-align: center; margin-top: 28px; }
-`;
-
-function renderRoleChips(app) {
-  if (!app.roles.length) {
-    return '<span class="role disabled">No roles found</span>';
-  }
-  return app.roles.map((role) => {
-    if (app.status === 'ready' && role.slug) {
-      return '<a class="role" href="/' + app.slug + '/' + role.slug + '/home">'
-        + escapeHtml(role.name) + ' &rarr;</a>';
-    }
-    return '<span class="role disabled" aria-disabled="true">' + escapeHtml(role.name) + '</span>';
-  }).join('\n      ');
-}
-
-function renderAppCard(app) {
-  const badge = app.status === 'ready'
-    ? '<span class="badge ready">Ready' + (app.stack ? ' · ' + escapeHtml(app.stack) : '') + '</span>'
-    : (app.status === 'build-required'
-      ? '<span class="badge pending">Build required</span>'
-      : '<span class="badge pending">Not generated yet</span>');
-  const indexLink = app.status === 'ready'
-    ? '<a class="index-link" href="/' + app.slug + '">screen index</a>' : '';
-  let hint = '';
-  if (app.status === 'build-required') {
-    hint = '<p class="hint">Run <code>cd ' + escapeHtml(app.folder)
-      + '/context/mockup &amp;&amp; npm install &amp;&amp; npm run build</code> to make this app viewable.</p>';
-  } else if (app.status === 'not-generated') {
-    hint = '<p class="hint">Run a <code>mockgen-*</code> skill for this application to generate its mockups.</p>';
-  }
-  return '<div class="card">\n'
-    + '  <h2>' + escapeHtml(app.appName) + '</h2>'
-    + (app.version ? '<span class="meta">' + escapeHtml(app.version) + '</span>' : '')
-    + badge + indexLink + '\n'
-    + (app.description ? '  <p class="sub" style="margin:6px 0 0">' + escapeHtml(app.description) + '</p>\n' : '')
-    + '  <div class="roles">\n      ' + renderRoleChips(app) + '\n  </div>\n'
-    + hint + '\n</div>';
-}
-
-function renderLanding(apps) {
-  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</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'
-    + apps.map(renderAppCard).join('\n')
-    + '\n<p class="foot">CO2 Mockup Hub v' + HUB_VERSION
-    + ' &middot; port via PORT env or mockup.config.json</p>\n</div>\n</body>\n</html>';
-}
-
-function notReadyPage(app) {
-  return renderLanding([app]);
-}
-
-function notFoundPage(what) {
-  return '<!DOCTYPE html><html><body style="font-family:sans-serif;padding:40px">'
-    + '<h1>404 — Not found' + (what ? ': ' + escapeHtml(what) : '') + '</h1>'
-    + '<p><a href="/">Back to Mockup Hub</a></p></body></html>';
-}
-
-// ── Tailwind assembly ────────────────────────────────────────────────────────
-
-function assemblePage(app, role, page) {
-  const dir = app.mockupDir;
-  const shell = readText(path.join(dir, 'partials', 'shell.html'));
-  let header = readText(path.join(dir, 'partials', 'header.html'));
-  const sidebar = readText(path.join(dir, 'partials', 'sidebar-' + role + '.html'));
-  const footer = readText(path.join(dir, 'partials', 'footer.html'));
-  const content = readText(path.join(dir, role, 'content', page + '.html'));
-  if (!shell || !header || !sidebar || !footer) return null;
-  header = header.replace(/\{\{ROLE\}\}/g, role).replace(/\{\{APP_SLUG\}\}/g, app.slug);
-  const body = content
-    || '<div class="p-6 text-red-500">Page not found: ' + escapeHtml(page) + '</div>';
-  return shell
-    .replace('{{HEADER}}', header)
-    .replace('{{SIDEBAR}}', sidebar.replace(/\{\{APP_SLUG\}\}/g, app.slug))
-    .replace('{{CONTENT}}', body)
-    .replace('{{FOOTER}}', footer);
-}
-
-// ── Routing ──────────────────────────────────────────────────────────────────
-
-function routeTailwind(app, segs, res) {
-  if (segs.length === 1) {
-    if (serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) 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 (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 (!SAFE_SEG.test(segs[1])) return send(res, 400, notFoundPage());
-  if (segs.length === 2) return redirect(res, '/' + 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 send(res, 404, notFoundPage());
-}
-
-function routeShadcn(app, segs, res) {
-  if (segs.length === 1 && serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) 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());
-  }
-  const distDir = path.join(app.mockupDir, 'dist');
-  if (segs.length > 1) {
-    const file = safeJoin(distDir, segs.slice(1));
-    if (serveFile(res, file)) 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));
-}
-
-function route(req, res) {
-  const urlPath = decodeURIComponent((req.url || '/').split('?')[0]);
-  const segs = urlPath.split('/').filter(Boolean);
-
-  if (segs.length === 0) return send(res, 200, renderLanding(discoverApps()));
-  if (urlPath === '/favicon.ico') { res.writeHead(204); return res.end(); }
-
-  // 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());
-    const app = findApp(segs[2]);
-    if (!app || app.status !== 'ready' || app.stack !== 'tailwind') {
-      return send(res, 404, notFoundPage(segs[2]));
-    }
-    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);
-  }
-
-  if (!SAFE_SEG.test(segs[0])) return send(res, 400, notFoundPage());
-  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.stack === 'shadcn') return routeShadcn(app, segs, res);
-  return routeTailwind(app, segs, res);
-}
-
-// ── Start ────────────────────────────────────────────────────────────────────
-
-const PORT = resolvePort();
-const server = http.createServer((req, res) => {
-  try {
-    route(req, res);
-  } catch (err) {
-    send(res, 500, '<h1>500 — Hub error</h1><pre>' + escapeHtml(err && err.stack || err) + '</pre>');
-  }
-});
-
-server.listen(PORT, () => {
-  console.log('');
-  console.log('  CO2 Mockup Hub v' + HUB_VERSION + ' running at:');
-  console.log('  -> http://localhost:' + PORT);
-  console.log('');
-  console.log('  Serving mockups for all applications under: ' + ROOT_DIR);
-  console.log('  Change port: PORT env var, or "port" in mockup.config.json');
-  console.log('');
-});
-```
-
-## package.json Template
-
-```json
-{
-  "name": "co2-mockup-hub",
-  "private": true,
-  "version": "1.0.0",
-  "description": "CO2 Mockup Hub — single server for all application mockups",
-  "main": "server.js",
-  "scripts": {
-    "start": "node server.js"
-  }
-}
-```
-
-## mockup.config.json Template
-
-Create only if missing — never overwrite (it stores the user's port choice).
-
-```json
-{
-  "port": 3000
-}
-```
-
-Port precedence at startup: `PORT` env var (e.g. `PORT=4000 npm start`) →
-`mockup.config.json` `port` → `3000`.
-
-## .gitignore Template
-
-Everything npm- or machine-generated inside `<root>/mockup/` stays inside `<root>/mockup/`
-and is gitignored there. The hub has zero dependencies, so `node_modules/` normally never
-exists — the rule is a safety net in case a user installs packages. `mockup.config.json`
-is per-machine (each machine keeps its own port choice; the skills recreate it if missing),
-so it is gitignored too.
-
-```
-node_modules/
-package-lock.json
-mockup.config.json
-.DS_Store
-*.log
-```
-
-## Quick Start (for output summaries)
-
-```
-Mockup Hub
-==========
-1. cd <root>/mockup
-2. npm start          (zero dependencies — no npm install required)
-3. Open http://localhost:3000 in your browser
-   (change port: PORT=4000 npm start, or edit mockup.config.json)
-```
+# Mockup Hub — Single Node Server for ALL Application Mockups
+
+The Mockup Hub is ONE zero-dependency Node.js application at `<root>/mockup/` that serves
+the mockups of EVERY application in the project. Per-application mockup folders
+(`<app_folder>/context/mockup/`) contain ONLY assets (HTML/CSS/JS/images + a manifest) —
+they contain NO server of their own.
+
+- **Tailwind mockups** (`mockgen-tailwind`): the hub assembles shell + header + sidebar +
+  content + footer server-side at `/{app_slug}/{role}/{page}`.
+- **shadcn mockups** (`mockgen-shadcn`): the hub serves the app's built `dist/` folder at
+  `/{app_slug}/...` with SPA fallback to `dist/index.html`.
+- **Landing page** at `/`: dynamically lists ALL applications and their roles. Roles are
+  clickable only when the app's mockup is ready; otherwise they render as disabled
+  (grayed, no `href`) chips with a status hint ("Mockups not generated yet" /
+  "Build required").
+- **Port** is configurable: `PORT` env var → `mockup.config.json` `port` → auto-pick the
+  first **unused port starting from 4000**. The landing page carries a **port input text**
+  (defaulting to the current port) whose Apply action persists the choice to
+  `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.
+
+The hub has **zero npm dependencies** — `npm start` (or `node server.js`) works with no
+`npm install`.
+
+## File Structure
+
+```
+<root>/
+  mockup/                     # ← the hub (this template)
+    server.js                 # zero-dependency Node HTTP server
+    package.json              # no dependencies; "start": "node server.js"
+    mockup.config.json        # { "port": 4000 } — user-editable (first unused port ≥ 4000)
+    .gitignore
+  1_first_app/
+    context/mockup/           # assets only (+ mockup-manifest.json)
+  2_second_app/
+    context/mockup/
+```
+
+## Ensure-Hub Rules (run by every mockgen-* execution, including module-filtered runs)
+
+1. If `<root>/mockup/server.js` does NOT exist: create ALL four hub files from the
+   templates below.
+2. If it exists: read the `HUB_VERSION` constant in the existing `server.js`.
+   - Existing version **< template version** → overwrite `server.js` and `package.json`
+     with the templates (upgrade).
+   - Existing version **>= template version**, or no marker found (user-customized) →
+     leave `server.js` and `package.json` untouched.
+3. `mockup.config.json`: create ONLY if missing. NEVER overwrite an existing one — it
+   holds the user's port choice. It is per-machine and gitignored. When creating it, set
+   `port` to the **first unused port starting from 4000** (default `4000`; if you cannot
+   check, just write `4000` — the server auto-scans upward from a busy config port at
+   startup and writes the effective port back).
+4. `.gitignore`: create ONLY if missing.
+5. Never place per-application assets inside `<root>/mockup/`. Conversely, everything the
+   hub generates or needs (config, logs, any `node_modules/`) stays inside `<root>/mockup/`
+   and is covered by its `.gitignore`.
+
+## mockup-manifest.json Schema (written to `<app_folder>/context/mockup/`)
+
+Every mockgen-* run writes/updates this file. The hub uses it for discovery, routing and
+the landing page.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `app` | string | App slug used in URLs = app folder name minus leading `<number>_` (e.g. `hub_middleware`) |
+| `appName` | string | Display name (e.g. "Hub Middleware") |
+| `description` | string | Short app description from PRD.md |
+| `stack` | string | `"tailwind"` or `"shadcn"` |
+| `version` | string | Target version the mockups were generated for (e.g. `v1.0.3`) |
+| `generatedAt` | string | ISO date of the last generation |
+| `roles` | array | One entry per role: `{ "name", "slug", "screens" }`. `slug` uses the stack's convention — snake_case (tailwind) or kebab-case (shadcn). `screens` = number of screens generated for the role |
+| `reports` | array (optional) | Report layout file names, if any |
+
+Example:
+
+```json
+{
+  "app": "hub_middleware",
+  "appName": "Hub Middleware",
+  "description": "Central middleware for labour mobility data exchange.",
+  "stack": "tailwind",
+  "version": "v1.0.3",
+  "generatedAt": "2026-07-12",
+  "roles": [
+    { "name": "Hub Administrator", "slug": "hub_administrator", "screens": 12 },
+    { "name": "Hub Operation Support", "slug": "hub_operation_support", "screens": 9 }
+  ],
+  "reports": ["staff_allocation_summary.html"]
+}
+```
+
+## server.js Template
+
+```javascript
+#!/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)
+ *
+ * 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)
+ * 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.
+ *   - A config/auto port scans upward from a busy port; the effective port is written
+ *     back to mockup.config.json so probes and the next start agree.
+ *   - The landing page has a port input (POST /api/port) that persists a new port and
+ *     re-listens on it.
+ */
+'use strict';
+
+const http = require('http');
+const net = require('net');
+const fs = require('fs');
+const path = require('path');
+
+const HUB_VERSION = 2;
+const HUB_DIR = __dirname;
+const ROOT_DIR = path.resolve(HUB_DIR, '..');
+const SAFE_SEG = /^[A-Za-z0-9._-]+$/;
+const PORT_SCAN_START = 4000; // default: first unused port starting here
+const PORT_SCAN_LIMIT = 100;
+
+/** { port, source: 'env' | 'config' | 'auto' } — env is exact, config/auto may scan. */
+function resolvePort() {
+  const envPort = parseInt(process.env.PORT || '', 10);
+  if (Number.isInteger(envPort) && envPort > 0) return { port: envPort, source: 'env' };
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(HUB_DIR, 'mockup.config.json'), 'utf8'));
+    const cfgPort = parseInt(cfg.port, 10);
+    if (Number.isInteger(cfgPort) && cfgPort > 0) return { port: cfgPort, source: 'config' };
+  } catch (err) { /* missing/invalid config — auto-pick */ }
+  return { port: PORT_SCAN_START, source: 'auto' };
+}
+
+function persistPort(port) {
+  try {
+    fs.writeFileSync(
+      path.join(HUB_DIR, 'mockup.config.json'),
+      JSON.stringify({ port: port }, null, 2) + '\n'
+    );
+  } catch (err) { /* read-only folder — the port still applies for this run */ }
+}
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.map': 'application/json',
+  '.txt': 'text/plain; charset=utf-8',
+  '.pdf': 'application/pdf',
+};
+
+// ── Discovery ────────────────────────────────────────────────────────────────
+
+function titleCase(slug) {
+  return slug.replace(/[_-]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function rolesFromPrd(appDir) {
+  try {
+    const prd = fs.readFileSync(path.join(appDir, 'context', 'PRD.md'), 'utf8');
+    const names = new Set();
+    for (const line of prd.split('\n')) {
+      if (line.includes('~~')) continue; // skip strikethrough (deprecated) items
+      const m = line.match(/As an? (.+?) user/);
+      if (m) names.add(m[1].trim());
+    }
+    return Array.from(names).map((name) => ({ name, slug: null, screens: 0 }));
+  } catch (err) {
+    return [];
+  }
+}
+
+function discoverApps() {
+  let entries;
+  try { entries = fs.readdirSync(ROOT_DIR, { withFileTypes: true }); } catch (err) { return []; }
+  const apps = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const appDir = path.join(ROOT_DIR, entry.name);
+    if (!fs.existsSync(path.join(appDir, 'context', 'PRD.md'))) continue;
+    const slug = entry.name.replace(/^\d+_/, '');
+    const mockupDir = path.join(appDir, 'context', 'mockup');
+    let manifest = null;
+    try {
+      manifest = JSON.parse(fs.readFileSync(path.join(mockupDir, 'mockup-manifest.json'), 'utf8'));
+    } catch (err) { /* mockups not generated yet */ }
+    let status = 'not-generated';
+    if (manifest && manifest.stack === 'shadcn') {
+      status = fs.existsSync(path.join(mockupDir, 'dist', 'index.html')) ? 'ready' : 'build-required';
+    } else if (manifest) {
+      status = fs.existsSync(path.join(mockupDir, 'partials', 'shell.html')) ? 'ready' : 'not-generated';
+    }
+    apps.push({
+      slug,
+      folder: entry.name,
+      appName: (manifest && manifest.appName) || titleCase(slug),
+      description: (manifest && manifest.description) || '',
+      version: (manifest && manifest.version) || '',
+      stack: manifest ? manifest.stack : null,
+      status,
+      mockupDir,
+      roles: manifest ? (manifest.roles || []) : rolesFromPrd(appDir),
+    });
+  }
+  return apps.sort((a, b) => a.folder.localeCompare(b.folder));
+}
+
+function findApp(slug) {
+  return discoverApps().find((a) => a.slug === slug) || null;
+}
+
+// ── Response helpers ─────────────────────────────────────────────────────────
+
+function send(res, code, body, type) {
+  res.writeHead(code, { 'Content-Type': type || 'text/html; charset=utf-8' });
+  res.end(body);
+}
+
+function redirect(res, location) {
+  res.writeHead(302, { Location: location });
+  res.end();
+}
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function safeJoin(baseDir, segments) {
+  if (!segments.every((s) => SAFE_SEG.test(s))) return null;
+  const target = path.normalize(path.join(baseDir, segments.join(path.sep)));
+  if (target !== baseDir && !target.startsWith(baseDir + path.sep)) return null;
+  return target;
+}
+
+function serveFile(res, filePath) {
+  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';
+  send(res, 200, fs.readFileSync(filePath), type);
+  return true;
+}
+
+function readText(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch (err) { return null; }
+}
+
+// ── Landing page ─────────────────────────────────────────────────────────────
+
+const LANDING_CSS = `
+  * { box-sizing: border-box; margin: 0; }
+  body { font-family: -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+         background: #f1f5f9; color: #0f172a; padding: 40px 20px; }
+  .wrap { max-width: 960px; margin: 0 auto; }
+  h1 { font-size: 26px; margin-bottom: 4px; }
+  .sub { color: #64748b; font-size: 14px; margin-bottom: 28px; }
+  .card { background: #fff; border: 1px solid #e2e8f0; border-radius: 12px;
+          padding: 20px; margin-bottom: 16px; }
+  .card h2 { font-size: 18px; display: inline; }
+  .meta { color: #94a3b8; font-size: 12px; margin-left: 8px; }
+  .badge { display: inline-block; font-size: 11px; padding: 2px 8px; border-radius: 999px;
+           margin-left: 8px; vertical-align: 2px; }
+  .badge.ready { background: #dcfce7; color: #166534; }
+  .badge.pending { background: #fef3c7; color: #92400e; }
+  .hint { color: #94a3b8; font-size: 12px; margin-top: 10px; }
+  .hint code { background: #f1f5f9; padding: 1px 5px; border-radius: 4px; }
+  .roles { margin-top: 12px; display: flex; flex-wrap: wrap; gap: 8px; }
+  .role { display: inline-block; font-size: 13px; padding: 6px 14px; border-radius: 8px;
+          border: 1px solid #cbd5e1; text-decoration: none; color: #0f172a; }
+  a.role:hover { border-color: #2563eb; color: #2563eb; }
+  .role.disabled { color: #cbd5e1; border-color: #e2e8f0; cursor: not-allowed; }
+  .index-link { font-size: 12px; margin-left: 8px; }
+  .foot { color: #94a3b8; font-size: 12px; text-align: center; margin-top: 28px; }
+  .portbox { display: inline-flex; align-items: center; gap: 6px; margin-left: 10px; }
+  .portbox input { width: 64px; font-size: 12px; padding: 3px 6px; border: 1px solid #cbd5e1;
+                   border-radius: 6px; color: #0f172a; }
+  .portbox button { font-size: 12px; padding: 3px 10px; border: 1px solid #cbd5e1;
+                    border-radius: 6px; background: #fff; cursor: pointer; }
+  .portbox button:hover { border-color: #2563eb; color: #2563eb; }
+  #port-msg { font-size: 12px; margin-left: 6px; }
+`;
+
+function renderRoleChips(app) {
+  if (!app.roles.length) {
+    return '<span class="role disabled">No roles found</span>';
+  }
+  return app.roles.map((role) => {
+    if (app.status === 'ready' && role.slug) {
+      return '<a class="role" href="/' + app.slug + '/' + role.slug + '/home">'
+        + escapeHtml(role.name) + ' &rarr;</a>';
+    }
+    return '<span class="role disabled" aria-disabled="true">' + escapeHtml(role.name) + '</span>';
+  }).join('\n      ');
+}
+
+function renderAppCard(app) {
+  const badge = app.status === 'ready'
+    ? '<span class="badge ready">Ready' + (app.stack ? ' · ' + escapeHtml(app.stack) : '') + '</span>'
+    : (app.status === 'build-required'
+      ? '<span class="badge pending">Build required</span>'
+      : '<span class="badge pending">Not generated yet</span>');
+  const indexLink = app.status === 'ready'
+    ? '<a class="index-link" href="/' + app.slug + '">screen index</a>' : '';
+  let hint = '';
+  if (app.status === 'build-required') {
+    hint = '<p class="hint">Run <code>cd ' + escapeHtml(app.folder)
+      + '/context/mockup &amp;&amp; npm install &amp;&amp; npm run build</code> to make this app viewable.</p>';
+  } else if (app.status === 'not-generated') {
+    hint = '<p class="hint">Run a <code>mockgen-*</code> skill for this application to generate its mockups.</p>';
+  }
+  return '<div class="card">\n'
+    + '  <h2>' + escapeHtml(app.appName) + '</h2>'
+    + (app.version ? '<span class="meta">' + escapeHtml(app.version) + '</span>' : '')
+    + badge + indexLink + '\n'
+    + (app.description ? '  <p class="sub" style="margin:6px 0 0">' + escapeHtml(app.description) + '</p>\n' : '')
+    + '  <div class="roles">\n      ' + renderRoleChips(app) + '\n  </div>\n'
+    + hint + '\n</div>';
+}
+
+// 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.
+const PORT_SCRIPT = `
+  function applyPort() {
+    var msg = document.getElementById('port-msg');
+    var port = parseInt(document.getElementById('hub-port').value, 10);
+    if (!port || port < 1024 || port > 65535) {
+      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' },
+      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 + '/';
+        }, 700);
+      })
+      .catch(function () { msg.style.color = '#dc2626'; msg.textContent = 'Request failed'; });
+  }
+`;
+
+function renderLanding(apps, currentPort) {
+  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'
+    + '<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'
+    + apps.map(renderAppCard).join('\n')
+    + '\n<p class="foot">CO2 Mockup Hub v' + HUB_VERSION
+    + '<span class="portbox">Port <input id="hub-port" type="text" inputmode="numeric" value="'
+    + (currentPort || '') + '"> <button type="button" onclick="applyPort()">Apply</button>'
+    + '<span id="port-msg"></span></span></p>\n</div>\n</body>\n</html>';
+}
+
+function notReadyPage(app) {
+  return renderLanding([app], CURRENT_PORT);
+}
+
+function notFoundPage(what) {
+  return '<!DOCTYPE html><html><body style="font-family:sans-serif;padding:40px">'
+    + '<h1>404 — Not found' + (what ? ': ' + escapeHtml(what) : '') + '</h1>'
+    + '<p><a href="/">Back to Mockup Hub</a></p></body></html>';
+}
+
+// ── Tailwind assembly ────────────────────────────────────────────────────────
+
+function assemblePage(app, role, page) {
+  const dir = app.mockupDir;
+  const shell = readText(path.join(dir, 'partials', 'shell.html'));
+  let header = readText(path.join(dir, 'partials', 'header.html'));
+  const sidebar = readText(path.join(dir, 'partials', 'sidebar-' + role + '.html'));
+  const footer = readText(path.join(dir, 'partials', 'footer.html'));
+  const content = readText(path.join(dir, role, 'content', page + '.html'));
+  if (!shell || !header || !sidebar || !footer) return null;
+  header = header.replace(/\{\{ROLE\}\}/g, role).replace(/\{\{APP_SLUG\}\}/g, app.slug);
+  const body = content
+    || '<div class="p-6 text-red-500">Page not found: ' + escapeHtml(page) + '</div>';
+  return shell
+    .replace('{{HEADER}}', header)
+    .replace('{{SIDEBAR}}', sidebar.replace(/\{\{APP_SLUG\}\}/g, app.slug))
+    .replace('{{CONTENT}}', body)
+    .replace('{{FOOTER}}', footer);
+}
+
+// ── Routing ──────────────────────────────────────────────────────────────────
+
+function routeTailwind(app, segs, res) {
+  if (segs.length === 1) {
+    if (serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) 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 (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 (!SAFE_SEG.test(segs[1])) return send(res, 400, notFoundPage());
+  if (segs.length === 2) return redirect(res, '/' + 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 send(res, 404, notFoundPage());
+}
+
+function routeShadcn(app, segs, res) {
+  if (segs.length === 1 && serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) 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());
+  }
+  const distDir = path.join(app.mockupDir, 'dist');
+  if (segs.length > 1) {
+    const file = safeJoin(distDir, segs.slice(1));
+    if (serveFile(res, file)) 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));
+}
+
+// POST /api/port — persist a new port (from the landing page's port input) and re-listen.
+function handlePortUpdate(req, res) {
+  let body = '';
+  req.on('data', (chunk) => { body += chunk; });
+  req.on('end', () => {
+    let port = NaN;
+    try { port = parseInt(JSON.parse(body).port, 10); } catch (err) { /* invalid JSON */ }
+    if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+      return send(res, 400, JSON.stringify({ ok: false, error: 'Port must be 1024-65535' }),
+        'application/json; charset=utf-8');
+    }
+    persistPort(port);
+    send(res, 200, JSON.stringify({ ok: true, port: port }), 'application/json; charset=utf-8');
+    if (port !== CURRENT_PORT) {
+      setTimeout(() => { server.close(() => listenOn(port, false)); }, 200);
+    }
+  });
+}
+
+function route(req, res) {
+  const urlPath = decodeURIComponent((req.url || '/').split('?')[0]);
+  const segs = urlPath.split('/').filter(Boolean);
+
+  if (segs.length === 0) return send(res, 200, renderLanding(discoverApps(), CURRENT_PORT));
+  if (urlPath === '/favicon.ico') { res.writeHead(204); return res.end(); }
+
+  if (segs[0] === 'api' && segs[1] === 'port' && segs.length === 2 && req.method === 'POST') {
+    return handlePortUpdate(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());
+    const app = findApp(segs[2]);
+    if (!app || app.status !== 'ready' || app.stack !== 'tailwind') {
+      return send(res, 404, notFoundPage(segs[2]));
+    }
+    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);
+  }
+
+  if (!SAFE_SEG.test(segs[0])) return send(res, 400, notFoundPage());
+  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.stack === 'shadcn') return routeShadcn(app, segs, res);
+  return routeTailwind(app, segs, res);
+}
+
+// ── Start ────────────────────────────────────────────────────────────────────
+
+let CURRENT_PORT = 0;
+const server = http.createServer((req, res) => {
+  try {
+    route(req, res);
+  } catch (err) {
+    send(res, 500, '<h1>500 — Hub error</h1><pre>' + escapeHtml(err && err.stack || err) + '</pre>');
+  }
+});
+
+/** True when a TCP connect to 127.0.0.1:<port> is answered (something listens there).
+ *  Needed besides the bind error: Windows lets a wildcard bind coexist with another
+ *  process's 127.0.0.1-specific bind, so a plain listen() would "succeed" while
+ *  http://localhost:<port> still hits the other app. */
+function tcpBusy(port, cb) {
+  const sock = net.connect({ host: '127.0.0.1', port: port, timeout: 400 });
+  sock.once('connect', function () { sock.destroy(); cb(true); });
+  sock.once('timeout', function () { sock.destroy(); cb(false); });
+  sock.once('error', function () { cb(false); });
+}
+
+/**
+ * Listen on `port`; when `scan` is true a busy port tries the next one (bounded). The
+ * effective port is written back to mockup.config.json so probes and restarts agree.
+ * An exact (PORT env) port never scans — the caller asked for THAT port.
+ */
+function listenOn(port, scan) {
+  tcpBusy(port, (busy) => {
+    if (busy) {
+      if (scan && port < PORT_SCAN_START + PORT_SCAN_LIMIT) return listenOn(port + 1, true);
+      console.error('  CO2 Mockup Hub failed to listen on port ' + port + ': already in use');
+      process.exit(1);
+    }
+    server.removeAllListeners('error'); // drop stale handlers from prior attempts/restarts
+    server.once('error', (err) => {
+      if (scan && err && err.code === 'EADDRINUSE' && port < PORT_SCAN_START + PORT_SCAN_LIMIT) {
+        return listenOn(port + 1, true);
+      }
+      console.error('  CO2 Mockup Hub failed to listen on port ' + port + ': ' + (err && err.code || err));
+      process.exit(1);
+    });
+    // Bind the IPv4 wildcard explicitly — a bare listen(port) grabs the IPv6 wildcard on
+    // some hosts and would miss IPv4 conflicts entirely.
+    server.listen(port, '0.0.0.0', () => {
+      CURRENT_PORT = port;
+      persistPort(port);
+      console.log('');
+      console.log('  CO2 Mockup Hub v' + HUB_VERSION + ' running at:');
+      console.log('  -> http://localhost:' + port);
+      console.log('');
+      console.log('  Serving mockups for all applications under: ' + ROOT_DIR);
+      console.log('  Change port: the landing page port input, PORT env var, or "port" in mockup.config.json');
+      console.log('');
+    });
+  });
+}
+
+const resolved = resolvePort();
+// env = exact (fail fast when busy); config/auto = scan upward from the resolved port.
+listenOn(resolved.port, resolved.source !== 'env');
+```
+
+## package.json Template
+
+```json
+{
+  "name": "co2-mockup-hub",
+  "private": true,
+  "version": "1.0.0",
+  "description": "CO2 Mockup Hub — single server for all application mockups",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js"
+  }
+}
+```
+
+## mockup.config.json Template
+
+Create only if missing — never overwrite (it stores the user's port choice). When
+creating, set `port` to the first unused port starting from 4000 (write `4000` if you
+cannot check — the server scans upward from a busy config port and writes the effective
+port back).
+
+```json
+{
+  "port": 4000
+}
+```
+
+Port precedence at startup: `PORT` env var (e.g. `PORT=4100 npm start` — exact, fails
+fast when busy; Compound Context Studio's Start Hub passes the port this way) →
+`mockup.config.json` `port` → first unused port starting from `4000`. The landing page's
+port input (POST `/api/port`) persists a new port and re-listens on it.
+
+## .gitignore Template
+
+Everything npm- or machine-generated inside `<root>/mockup/` stays inside `<root>/mockup/`
+and is gitignored there. The hub has zero dependencies, so `node_modules/` normally never
+exists — the rule is a safety net in case a user installs packages. `mockup.config.json`
+is per-machine (each machine keeps its own port choice; the skills recreate it if missing),
+so it is gitignored too.
+
+```
+node_modules/
+package-lock.json
+mockup.config.json
+.DS_Store
+*.log
+```
+
+## Quick Start (for output summaries)
+
+```
+Mockup Hub
+==========
+1. cd <root>/mockup
+2. npm start          (zero dependencies — no npm install required)
+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.)
+```