spectoflow 0.22.5 → 0.23.1

package/bin/spectoflow.js

@@ -10,6 +10,7 @@ const detect = require('../lib/detect');
 const ownership = require('../lib/ownership');
 const manifest = require('../lib/manifest');
 const registry = require('../lib/registry');
+const initLib = require('../lib/init');
 const mcp = require('../lib/mcp');
 const { startRun } = require('../templates/dashboard/runner');
 const { buildCustomizePrompt } = require('../templates/lib/customize-prompts');
@@ -94,125 +95,16 @@ function probeDashboard(port, timeoutMs = 500) {
   });
 }
 
-function copyDir(src, dst) {
-  fs.mkdirSync(dst, { recursive: true });
-  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
-    const s = path.join(src, e.name), d = path.join(dst, e.name);
-    if (e.isDirectory()) copyDir(s, d);
-    else if (!fs.existsSync(d)) fs.copyFileSync(s, d);
-  }
-}
-
-// Existing project: give id-less checkbox tasks a stable id, in place.
-const ID_RE = /^[A-Za-z]{1,5}-?\d+[A-Za-z]?$/;
-function normalizePlans(root, config) {
-  const dirName = store.resolvePlansDir(root, config || store.readConfig(root));
-  const dir = path.join(root, dirName);
-  if (!fs.existsSync(dir)) return 0;
-  let added = 0, seq = 1;
-  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md'))) {
-    const fp = path.join(dir, f);
-    const lines = fs.readFileSync(fp, 'utf8').split('\n');
-    let touched = false;
-    for (let i = 0; i < lines.length; i++) {
-      const m = lines[i].match(/^(\s*- \[[ xX]\]\s+)(\S+)(\s.*)?$/);
-      if (m && !ID_RE.test(m[2])) {
-        const id = 'T-' + String(seq++).padStart(3, '0');
-        lines[i] = `${m[1]}${id} ${m[2]}${m[3] || ''}`;
-        touched = true; added++;
-      } else if (m) { seq++; }
-    }
-    if (touched) fs.writeFileSync(fp, lines.join('\n'));
-  }
-  return added;
-}
-
 function init() {
   const target = path.resolve(argv[1] && !argv[1].startsWith('--') ? argv[1] : '.');
   const agentsArg = (argv.find((a) => a.startsWith('--agent=')) || '').split('=')[1];
-  fs.mkdirSync(target, { recursive: true });
-  const notes = [];
-
-  // explicit --agent wins; otherwise detect installed agents; otherwise fall back to claude + codex
-  let agents, detected = [];
-  if (agentsArg) {
-    agents = agentsArg.split(',');
-  } else {
-    detected = detect.detectAgents(target);
-    agents = detected.length ? detected : ['claude', 'codex'];
-    notes.push(detected.length
-      ? `Detected agent(s): ${detected.join(', ')} — active: ${agents[0]}.`
-      : 'No agent CLI detected — defaulted to claude + codex.');
-  }
-
-  // preserve an existing CLAUDE.md
-  const claude = path.join(target, 'CLAUDE.md');
-  if (fs.existsSync(claude) && !fs.existsSync(claude + '.tomerge')) {
-    fs.renameSync(claude, claude + '.tomerge');
-    notes.push('Existing CLAUDE.md preserved as CLAUDE.md.tomerge — your agent merges it on first run.');
-  }
-
-  // canonical framework → .spectoflow/
-  const spectoflowDir = path.join(target, '.spectoflow');
-  copyDir(TPL, spectoflowDir);
-
-  // record the install baseline so `update` can tell untouched framework files from user edits
-  const frameworkFiles = ownership.listFrameworkFiles(TPL);
-  manifest.writeManifest(spectoflowDir, {
-    version: VERSION,
-    files: manifest.hashFileMap(spectoflowDir, frameworkFiles),
-  });
-
-  // set the active agent and seed runner commands from the selected/detected agents
-  const cfgPath = path.join(spectoflowDir, 'config.json');
-  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-  cfg.agent = agents[0];
-  cfg.runners = { ...cfg.runners, ...adapters.defaultRunners(agents) };
-  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
-
-  // artifact folders — reuse an existing differently-named folder (e.g. a project that already
-  // keeps its plans in `plan/`, singular) instead of always forcing the plans/specs convention;
-  // mkdir is a no-op when the resolved folder already exists.
-  const plansDirName = store.resolvePlansDir(target, cfg);
-  const specsDirName = store.resolveSpecsDir(target, cfg);
-  fs.mkdirSync(path.join(target, specsDirName), { recursive: true });
-  fs.mkdirSync(path.join(target, plansDirName), { recursive: true });
-  if (plansDirName !== 'plans') notes.push(`Using existing '${plansDirName}/' as the plans folder (set plansDir in config.json to override).`);
-  if (specsDirName !== 'specs') notes.push(`Using existing '${specsDirName}/' as the specs folder (set specsDir in config.json to override).`);
-
-  // existing project: id-normalize any plans already there
-  const added = normalizePlans(target, cfg);
-  if (added) notes.push(`Normalized ${added} existing task(s) with stable ids.`);
-
-  // per-agent shims
-  const written = adapters.generate(target, agents);
-
-  // wire Playwright MCP into the project's MCP config so the E2E agent can drive a real browser and
-  // generate/run Playwright tests. Idempotent + non-destructive: never touches an existing entry.
-  // npx fetches the server on first use, so this config IS the whole install — spectoflow stays
-  // zero-dep (this writes into the user's project, never into spectoflow).
-  const mcpTargets = [path.join(target, '.mcp.json')];
-  if (agents.includes('cursor')) mcpTargets.push(path.join(target, '.cursor', 'mcp.json'));
-  for (const fp of mcpTargets) {
-    const rel = path.relative(target, fp).split(path.sep).join('/');
-    const r = mcp.mergeMcpServer(fp, 'playwright', mcp.PLAYWRIGHT_MCP);
-    if (r === 'created' || r === 'added') notes.push(`Wired Playwright MCP into ${rel} (npx @playwright/mcp — for the E2E agent; commit it to share).`);
-    else if (r === 'skipped') notes.push(`Left ${rel} as-is (couldn't parse it) — add a 'playwright' MCP server yourself for browser-driven E2E.`);
-  }
-
-  // gitignore the volatile runtime
-  const gi = path.join(target, '.gitignore');
-  const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
-  for (const line of ['.spectoflow/runtime.json', '.spectoflow/.dashboard.lock']) {
-    if (!giText.includes(line)) fs.appendFileSync(gi, ((fs.existsSync(gi) && fs.readFileSync(gi, 'utf8').length) ? '\n' : '') + line + '\n');
-  }
-
+  const r = initLib.runInit({ target, templatesDir: TPL, version: VERSION, agentsArg });
   console.log(logo());
-  console.log(`${c.g('✓')} installed in ${c.bold(target)}`);
+  console.log(`${c.g('✓')} installed in ${c.bold(r.target)}`);
   console.log(`  ${c.dim('.spectoflow/')}   framework — brain, workflow, agents, skills, policy, dashboard, config`);
   console.log(`  ${c.dim('specs/ plans/')}  markdown artifacts (your source of truth)`);
-  written.forEach((w) => console.log(`  ${c.cy('+')} ${w}`));
-  notes.forEach((n) => console.log(`  ${c.y('!')} ${c.dim(n)}`));
+  r.written.forEach((w) => console.log(`  ${c.cy('+')} ${w}`));
+  r.notes.forEach((n) => console.log(`  ${c.y('!')} ${c.dim(n)}`));
   const port = resolvePort(argv);
   console.log(`\n${c.bold('Next')}`);
   console.log(`  ${c.dim('1)')} Open your agent here — or just say what you want to build.`);
@@ -254,21 +146,27 @@ async function update() {
   if (r.newSidecar.length && !dryRun) console.log(`  ${c.y('→')} ${c.dim(`${r.newSidecar.length} *.new file(s) to review and merge — or re-run: spectoflow update --force`)}`);
   console.log('');
 
-  // A running dashboard has the OLD framework code loaded into memory (Node caches `require()`d
-  // modules at process start) — new bytes on disk change nothing until it restarts. Do that
-  // automatically so an update always actually takes effect, instead of leaving a confusing
-  // half-updated dashboard (new static files, stale server logic) until someone thinks to restart.
+  // A running hub has the OLD framework code loaded into memory (Node caches `require()`d modules
+  // per project on first open) — new bytes on disk change nothing until that project's cached code
+  // is invalidated. Do that via a surgical per-project reload so an update always actually takes
+  // effect, without restarting the whole hub (which would disturb every other project open in it).
   if (!dryRun && changed) {
-    const lock = path.join(root, '.spectoflow', '.dashboard.lock');
+    const lockPath = registry.hubLockPath();
     let info = null;
-    try { info = JSON.parse(fs.readFileSync(lock, 'utf8')); } catch {}
+    try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
     if (info && info.port && (await probeDashboard(info.port, 2000))) {
-      console.log(`  ${c.dim('Dashboard is running — restarting it on port ' + info.port + ' to apply the update…')}`);
-      // Restart on the SAME port it was already on, not resolvePort(argv)'s default — `update`
-      // itself was never given a --port, so a naive restartDashboard() would silently move a
-      // non-default-port dashboard back to 4319.
-      argv.push(`--port=${info.port}`);
-      await restartDashboard();
+      const entry = registry.findByPath(root);
+      if (entry) {
+        try {
+          const res = await fetch(`http://localhost:${info.port}/api/hub/reload/${entry.id}`, { method: 'POST' });
+          const body = await res.json().catch(() => ({}));
+          console.log(`  ${c.dim(body.reloaded
+            ? 'Hub is running — reloaded this project\'s server code (other open projects unaffected).'
+            : 'Hub is running, but this project wasn\'t loaded in it yet — nothing to reload.')}`);
+        } catch {
+          console.log(`  ${c.y('!')} Hub is running on port ${info.port} but the reload request failed — restart it yourself if changes don't seem to take effect: ${c.g('spectoflow dashboard restart')}`);
+        }
+      }
     }
   }
 }
@@ -358,26 +256,31 @@ async function runCustomize(kind) {
   process.exitCode = code;
 }
 
-// Start in the background and return control. Probes first so a second start just reports the running
-// one instead of spawning a duplicate (and never crashes on EADDRINUSE).
+// Start in the background and return control. Registers (or touches) the current folder in the
+// global registry first, then either joins an already-running hub or spawns a new one — probing first
+// so a second start just reports the running one instead of spawning a duplicate.
 async function startDashboard() {
-  const port = resolvePort(argv);
-  const url = `http://localhost:${port}`;
-  if (await probeDashboard(port)) {
-    console.log(`${c.g('●')} dashboard already running → ${c.bold(url)}`);
+  const root = process.cwd();
+  const entry = registry.addProject(root);
+  const boardUrl = (p) => `http://localhost:${p}/p/${entry.id}/board`;
+  const lockPath = registry.hubLockPath();
+  let info = null;
+  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  if (info && info.port && await probeDashboard(info.port)) {
+    console.log(`${c.g('●')} hub already running → ${c.bold(boardUrl(info.port))}`);
     return printDashboardCommands();
   }
-  const local = path.resolve('.spectoflow', 'dashboard', 'server.js');
-  const bundled = path.join(TPL, 'dashboard', 'server.js');
+  const port = resolvePort(argv);
+  const hubPath = path.join(KIT, 'lib', 'hub-server.js');
   const env = Object.assign({}, process.env, { SPECTOFLOW_PORT: String(port) });
-  const child = spawn('node', [fs.existsSync(local) ? local : bundled], { detached: true, stdio: 'ignore', env });
-  child.unref();                                   // let this CLI exit while the server keeps running
+  const child = spawn('node', [hubPath], { detached: true, stdio: 'ignore', env });
+  child.unref();                                   // let this CLI exit while the hub keeps running
   // Confirm it actually came up (a still-releasing port from a just-stopped instance, or any other
   // startup error, would otherwise print a false "started" while the detached process silently died).
   let up = false;
   for (let i = 0; i < 20 && !up; i++) { await new Promise((r) => setTimeout(r, 250)); up = await probeDashboard(port, 300); }
-  if (up) console.log(`${c.g('✓')} dashboard started → ${c.bold(url)}  ${c.dim('(pid ' + child.pid + ')')}`);
-  else console.log(`${c.y('!')} spawned (pid ${child.pid}) but it isn't responding on ${url} yet — check ${c.g('spectoflow dashboard status')} in a moment, or its own output if something's wrong.`);
+  if (up) console.log(`${c.g('✓')} hub started → ${c.bold(boardUrl(port))}  ${c.dim('(pid ' + child.pid + ')')}`);
+  else console.log(`${c.y('!')} spawned (pid ${child.pid}) but it isn't responding on http://localhost:${port} yet — check ${c.g('spectoflow dashboard status')} in a moment, or its own output if something's wrong.`);
   printDashboardCommands();
 }
 
@@ -390,12 +293,13 @@ function printDashboardCommands() {
 }
 
 async function dashboardStatus() {
-  const port = resolvePort(argv);
+  const lockPath = registry.hubLockPath();
+  let info = null;
+  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
-  let pid = null;
-  try { pid = JSON.parse(fs.readFileSync(path.join(process.cwd(), '.spectoflow', '.dashboard.lock'), 'utf8')).pid; } catch {}
-  if (running) console.log(`${c.g('●')} dashboard running → ${c.bold('http://localhost:' + port)}${pid ? c.dim(' (pid ' + pid + ')') : ''}`);
-  else console.log(`${c.dim('○')} dashboard not running`);
+  if (running) console.log(`${c.g('●')} hub running → ${c.bold('http://localhost:' + port)}${info && info.pid ? c.dim(' (pid ' + info.pid + ')') : ''}`);
+  else console.log(`${c.dim('○')} hub not running`);
 }
 
 async function restartDashboard() {
@@ -408,28 +312,27 @@ async function restartDashboard() {
   return startDashboard();
 }
 
-// Stop the running dashboard: read the pidfile it wrote, verify it's actually up, then terminate it
+// Stop the running hub: read the global lock it wrote, verify it's actually up, then terminate it
 // and clear the lock. Safe against a stale lock (a recycled pid) because it only kills when the port
 // still responds.
 async function stopDashboard() {
-  const root = process.cwd();
-  const lock = path.join(root, '.spectoflow', '.dashboard.lock');
+  const lockPath = registry.hubLockPath();
   let info = null;
-  try { info = JSON.parse(fs.readFileSync(lock, 'utf8')); } catch {}
+  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
   const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
   if (!running) {
-    if (info) { try { fs.unlinkSync(lock); } catch {} }   // stale lock
-    return console.log('No spectoflow dashboard is running.');
+    if (info) { try { fs.unlinkSync(lockPath); } catch {} }   // stale lock
+    return console.log('No spectoflow hub is running.');
   }
   if (info && info.pid) {
     try {
-      process.kill(info.pid);                  // SIGTERM → server clears its own lock (POSIX)
-      try { fs.unlinkSync(lock); } catch {}     // and we clear it too (Windows has no real signals)
-      return console.log(`spectoflow dashboard stopped (pid ${info.pid}, was on http://localhost:${port}).`);
+      process.kill(info.pid);                  // SIGTERM → hub clears its own lock (POSIX)
+      try { fs.unlinkSync(lockPath); } catch {}     // and we clear it too (Windows has no real signals)
+      return console.log(`spectoflow hub stopped (pid ${info.pid}, was on http://localhost:${port}).`);
     } catch {}
   }
-  console.log(`A dashboard is responding on http://localhost:${port} but isn't stoppable via the lock file — stop it where you launched it (Ctrl+C).`);
+  console.log(`A hub is responding on http://localhost:${port} but isn't stoppable via the lock file — stop it where you launched it (Ctrl+C).`);
 }
 
 async function status() {
@@ -445,7 +348,10 @@ async function status() {
   console.log(`${(p.config && p.config.projectType) || 'project'} — mode ${p.config.mode} · lang ${p.config.language}`);
   console.log(`${done}/${tasks.length} tasks done · ${p.specs.length} spec(s) · ${p.agents.length} agents · ${p.skills.length} skills`);
   tasks.filter((t) => t.status === 'in_progress').forEach((t) => console.log(`  > in progress: ${t.id} ${t.title}`));
-  const port = resolvePort(argv);
+  const lockPath = registry.hubLockPath();
+  let info = null;
+  try { info = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch {}
+  const port = (info && info.port) || resolvePort(argv);
   const running = await probeDashboard(port);
   console.log(`dashboard: ${running ? `running → http://localhost:${port}` : 'not running'}`);
 }

package/lib/hub-server.js

@@ -0,0 +1,258 @@
+'use strict';
+/*
+ * The multi-project hub's server process — global (ships under lib/, never vendored into a
+ * project's .spectoflow/). Registry-driven: resolves a project's root + route logic on demand from
+ * ~/.spectoflow/projects.json (see lib/registry.js), keyed by the opaque id in /p/<id>/... URLs.
+ * Each project's own vendored handlers.js is require()'d dynamically by absolute path — Node's
+ * require cache keys by resolved path, so two different projects' identically-named handlers.js
+ * files are cached and run completely independently (see docs/multi-project-hub-design.md).
+ *
+ * URL scheme (settled in the design doc): pages use a path prefix (/p/<id>/board, bookmarkable on
+ * their own); every /api/* call instead takes a ?p=<id> query param (smaller client diff, and
+ * /api/events already needed a query-param shape for its per-project SSE subscription either way).
+ * A legacy no-prefix route (e.g. /board, a bookmark from before the hub existed) 302s to the
+ * most-recently-opened project, or to the hub root if none are registered yet.
+ *
+ * GET / serves hub.html — the landing page listing every registered project, with an "+ Add project"
+ * flow (browse the filesystem server-side, or paste a path; either way auto-inits a plain folder) —
+ * see /api/hub/* below and docs/multi-project-hub-design.md §3bis.
+ */
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const registry = require('./registry');
+
+const PORT = process.env.SPECTOFLOW_PORT ? Number(process.env.SPECTOFLOW_PORT) : 4319;
+const PUBLIC = path.join(__dirname, '..', 'templates', 'dashboard', 'public');
+const TEMPLATES = path.join(__dirname, '..', 'templates');
+const VERSION = require('../package.json').version;
+const MIME = { '.html':'text/html; charset=utf-8', '.css':'text/css; charset=utf-8', '.js':'application/javascript; charset=utf-8', '.png':'image/png', '.svg':'image/svg+xml', '.ico':'image/x-icon', '.woff2':'font/woff2', '.woff':'font/woff' };
+function sendJSON(res,code,obj){ res.writeHead(code,{'Content-Type':'application/json; charset=utf-8'}); res.end(JSON.stringify(obj)); }
+function body(req) { return new Promise((r) => { let b = ''; req.on('data', (c) => b += c); req.on('end', () => { try { r(JSON.parse(b || '{}')); } catch { r({}); } }); }); }
+
+// id -> { id, root, handlers, clients:Set, emit }, populated lazily on first request for that id and
+// kept alive for the process's life (registries are small; no need to tear down on last-tab-close).
+const projects = new Map();
+function getProject(id) {
+  if (projects.has(id)) return projects.get(id);
+  const entry = registry.listProjects().find((p) => p.id === id);
+  if (!entry) return null;
+  const handlersPath = path.join(entry.path, '.spectoflow', 'dashboard', 'handlers.js');
+  let createHandlers;
+  try { ({ createHandlers } = require(handlersPath)); }
+  catch { return null; } // project's folder moved/deleted, or predates the handlers.js split
+  const handlers = createHandlers(entry.path);
+  const clients = new Set();
+  const emit = (obj) => { const line = 'data: ' + JSON.stringify(obj) + '\n\n'; for (const res of clients) res.write(line); };
+  handlers.onBoot();
+  handlers.watchDirs.forEach((d) => {
+    const dir = path.join(entry.path, d);
+    if (fs.existsSync(dir)) { try { fs.watch(dir, { recursive: false }, () => emit({ type: 'change' })); } catch (_) {} }
+  });
+  const proj = { id, root: entry.path, handlers, clients, emit };
+  projects.set(id, proj);
+  return proj;
+}
+
+// Only called after getProject(id) already returned null — figures out WHY, so the 404 points the
+// user at the right fix instead of a bare "unknown project". The two common real causes: never
+// registered at all, vs. registered but this project predates handlers.js (needs `spectoflow
+// update`) or its folder moved/was deleted.
+function projectErrorMessage(id) {
+  const entry = registry.listProjects().find((p) => p.id === id);
+  if (!entry) return 'Unknown project.';
+  if (!fs.existsSync(entry.path)) return `Project "${entry.name}" is registered, but its folder no longer exists at ${entry.path}.`;
+  const handlersPath = path.join(entry.path, '.spectoflow', 'dashboard', 'handlers.js');
+  if (!fs.existsSync(handlersPath)) return `Project "${entry.name}" needs an update — run \`spectoflow update\` inside it, then reload this page.`;
+  return `Project "${entry.name}" is registered, but its dashboard code failed to load — check its .spectoflow/dashboard/handlers.js for errors.`;
+}
+
+// Clears every require.cache entry under this project's own .spectoflow/ tree (its vendored
+// handlers.js and everything IT requires — orchestrator.js, runner.js, files.js, summarize.js,
+// lib/store.js, lib/agents-registry.js) and drops its cached Map entry. The require cache keys by
+// absolute path, so this can never touch another project's identically-named files. Returns false
+// (a harmless no-op, not an error) if this id was never loaded — nothing to invalidate.
+function reloadProject(id) {
+  const proj = projects.get(id);
+  if (!proj) return false;
+  const prefix = path.join(proj.root, '.spectoflow') + path.sep;
+  for (const key of Object.keys(require.cache)) {
+    if (key.startsWith(prefix)) delete require.cache[key];
+  }
+  projects.delete(id);
+  return true;
+}
+
+// ---- hub API: list/add/remove registered projects, browse the filesystem to find one ----
+function projectStats(root) {
+  // Best-effort — a moved/deleted/corrupt project must never break the whole listing.
+  try {
+    const store = require(path.join(root, '.spectoflow', 'lib', 'store.js'));
+    const plans = store.readPlans(root);
+    let total = 0, done = 0;
+    for (const pl of plans) for (const ph of pl.phases) for (const t of ph.tasks) { total++; if (t.status === 'done') done++; }
+    return { total, done };
+  } catch { return null; }
+}
+function listHubProjects() {
+  return registry.listProjects().map((p) => ({ ...p, stats: projectStats(p.path) }));
+}
+function listRoots() {
+  const home = os.homedir();
+  const roots = [{ name: path.basename(home) || home, path: home }];
+  if (process.platform === 'win32') {
+    for (const code of 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') {
+      const drive = `${code}:\\`;
+      if (fs.existsSync(drive)) roots.push({ name: drive, path: drive });
+    }
+  } else if (home !== '/') {
+    roots.push({ name: '/', path: '/' });
+  }
+  return roots;
+}
+function browseDirs(reqPath) {
+  if (!reqPath) return { entries: listRoots(), parent: null, current: null };
+  let abs;
+  try { abs = path.resolve(reqPath); } catch { return { error: 'Invalid path.' }; }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return { error: 'Not a folder.' };
+  let names;
+  try { names = fs.readdirSync(abs, { withFileTypes: true }); } catch { return { error: 'Cannot read this folder.' }; }
+  const entries = names.filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+    .map((e) => ({ name: e.name, path: path.join(abs, e.name) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const parent = path.dirname(abs) !== abs ? path.dirname(abs) : null;
+  return { entries, parent, current: abs };
+}
+function addHubProject(rawPath) {
+  let abs;
+  try { abs = path.resolve(rawPath); } catch { return { error: 'Invalid path.' }; }
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return { error: 'That folder does not exist.' };
+  const hasSpectoflow = fs.existsSync(path.join(abs, '.spectoflow'));
+  if (!hasSpectoflow) {
+    const { runInit } = require('./init');
+    runInit({ target: abs, templatesDir: TEMPLATES, version: VERSION });
+  }
+  const entry = registry.addProject(abs);
+  return { entry, initialized: !hasSpectoflow };
+}
+async function handleHubApi(req, res, u) {
+  const p = u.pathname;
+  if (p === '/api/hub/projects' && req.method === 'GET') { sendJSON(res, 200, { projects: listHubProjects() }); return true; }
+  if (p === '/api/hub/projects' && req.method === 'POST') {
+    const { path: rawPath } = await body(req);
+    if (!rawPath || !String(rawPath).trim()) { sendJSON(res, 400, { error: 'A folder path is required.' }); return true; }
+    const r = addHubProject(String(rawPath).trim());
+    if (r.error) { sendJSON(res, 400, r); return true; }
+    sendJSON(res, 200, r); return true;
+  }
+  if (/^\/api\/hub\/projects\/[^/]+$/.test(p) && req.method === 'DELETE') {
+    const id = decodeURIComponent(p.split('/')[4] || '');
+    const ok = registry.removeProject(id);
+    sendJSON(res, ok ? 200 : 404, ok ? { ok: true } : { error: 'No project registered with that id.' });
+    return true;
+  }
+  if (p === '/api/hub/browse' && req.method === 'GET') {
+    const reqPath = u.searchParams.get('path') || '';
+    const r = browseDirs(reqPath);
+    sendJSON(res, r.error ? 400 : 200, r);
+    return true;
+  }
+  if (/^\/api\/hub\/reload\/[^/]+$/.test(p) && req.method === 'POST') {
+    const id = decodeURIComponent(p.split('/')[4] || '');
+    const reloaded = reloadProject(id);
+    sendJSON(res, 200, { ok: true, reloaded });
+    return true;
+  }
+  return false;
+}
+
+// Serves one static asset (or the SPA index.html fallback for an extensionless path) from the
+// shared, globally-installed PUBLIC dir — identical logic to templates/dashboard/server.js's own,
+// just factored into a function since both the root-level and /p/<id>/-prefixed requests need it.
+function serveStatic(reqPath, req, res) {
+  const file = reqPath === '/' ? '/index.html' : reqPath;
+  const full = path.join(PUBLIC, path.normalize(file).replace(/^(\.\.[/\\])+/, ''));
+  if (!full.startsWith(PUBLIC)) { res.writeHead(403); return res.end('Forbidden'); }
+  const noCache = { 'Cache-Control': 'no-store, must-revalidate' };
+  fs.readFile(full, (err, data) => {
+    if (err) {
+      if (req.method === 'GET' && !path.extname(reqPath)) {
+        return fs.readFile(path.join(PUBLIC, 'index.html'), (e2, d2) => {
+          if (e2) { res.writeHead(404); return res.end('Not found'); }
+          res.writeHead(200, Object.assign({ 'Content-Type': MIME['.html'] }, noCache)); res.end(d2);
+        });
+      }
+      res.writeHead(404); return res.end('Not found');
+    }
+    const ext = path.extname(full);
+    const headers = ext === '.woff2' || ext === '.woff' ? { 'Cache-Control': 'public, max-age=604800' } : noCache;
+    res.writeHead(200, Object.assign({ 'Content-Type': MIME[ext] || 'application/octet-stream' }, headers)); res.end(data);
+  });
+}
+
+const PROJECT_PREFIX = /^\/p\/([0-9a-f]{6})(\/.*)?$/;
+
+const LOCK = registry.hubLockPath();
+function writeLock(){ try{ fs.mkdirSync(path.dirname(LOCK),{recursive:true}); fs.writeFileSync(LOCK, JSON.stringify({ pid:process.pid, port:PORT, url:`http://localhost:${PORT}`, startedAt:new Date().toISOString() })+'\n'); }catch{} }
+function clearLock(){ try{ const l=JSON.parse(fs.readFileSync(LOCK,'utf8')); if(l.pid===process.pid) fs.unlinkSync(LOCK); }catch{} }
+process.on('exit', clearLock);
+['SIGINT','SIGTERM'].forEach((s)=> process.on(s, ()=>{ clearLock(); process.exit(0); }));
+
+const server = http.createServer(async (req, res) => {
+  const u = new URL(req.url, `http://localhost:${PORT}`);
+  const p = u.pathname;
+  try {
+    const m = p.match(PROJECT_PREFIX);
+
+    if (p === '/api/events') {
+      const id = u.searchParams.get('p');
+      const proj = id && getProject(id);
+      if (!proj) return sendJSON(res, 404, { error: projectErrorMessage(id) });
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+      res.write('data: ' + JSON.stringify({ type: 'hello' }) + '\n\n');
+      proj.clients.add(res); req.on('close', () => proj.clients.delete(res));
+      return;
+    }
+
+    if (p.startsWith('/api/hub/')) {
+      const handled = await handleHubApi(req, res, u);
+      if (handled) return;
+      res.writeHead(404); return res.end('Not found');
+    }
+
+    if (p.startsWith('/api/')) {
+      const id = u.searchParams.get('p');
+      const proj = id && getProject(id);
+      if (!proj) return sendJSON(res, 404, { error: projectErrorMessage(id) });
+      const handled = await proj.handlers.handleApi(req, res, u, proj.emit);
+      if (handled) return;
+      res.writeHead(404); return res.end('Not found');
+    }
+
+    if (m) {
+      const id = m[1];
+      const proj = getProject(id);
+      if (!proj) { res.writeHead(404); return res.end(projectErrorMessage(id)); }
+      registry.touchProject(id);
+      return serveStatic(m[2] || '/', req, res);
+    }
+
+    if (p === '/') {
+      return serveStatic('/hub.html', req, res);
+    }
+
+    if (!path.extname(p)) {
+      // legacy no-prefix bookmark (e.g. /board from before the hub existed)
+      const rows = registry.listProjects();
+      const dest = rows.length ? `/p/${rows[0].id}/board` : '/';
+      res.writeHead(302, { Location: dest }); return res.end();
+    }
+
+    // a real static asset (styles.css, app.js, fonts) requested without a /p/<id> prefix — every
+    // page's own asset links are root-absolute, so this is the common case for every page load.
+    return serveStatic(p, req, res);
+  } catch (e) { sendJSON(res, 500, { error: String(e && e.message || e) }); }
+});
+
+server.listen(PORT, () => { writeLock(); console.log(`spectoflow · hub → http://localhost:${PORT}`); });

package/lib/init.js

@@ -0,0 +1,116 @@
+'use strict';
+/*
+ * Scaffolds .spectoflow/ into a target folder — the logic behind `spectoflow init`, extracted from
+ * bin/spectoflow.js so server code (the hub's Add Project auto-init step, sub-project 4) can call it
+ * too, without any CLI argv/console.log coupling. bin/spectoflow.js's init() is now a thin wrapper:
+ * parse argv, call runInit(), print the result.
+ */
+const fs = require('fs');
+const path = require('path');
+const detect = require('./detect');
+const adapters = require('./adapters');
+const ownership = require('./ownership');
+const manifest = require('./manifest');
+const mcp = require('./mcp');
+const store = require('../templates/lib/store');
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name), d = path.join(dst, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else if (!fs.existsSync(d)) fs.copyFileSync(s, d);
+  }
+}
+
+// Existing project: give id-less checkbox tasks a stable id, in place.
+const ID_RE = /^[A-Za-z]{1,5}-?\d+[A-Za-z]?$/;
+function normalizePlans(root, config) {
+  const dirName = store.resolvePlansDir(root, config || store.readConfig(root));
+  const dir = path.join(root, dirName);
+  if (!fs.existsSync(dir)) return 0;
+  let added = 0, seq = 1;
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+    const fp = path.join(dir, f);
+    const lines = fs.readFileSync(fp, 'utf8').split('\n');
+    let touched = false;
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^(\s*- \[[ xX]\]\s+)(\S+)(\s.*)?$/);
+      if (m && !ID_RE.test(m[2])) {
+        const id = 'T-' + String(seq++).padStart(3, '0');
+        lines[i] = `${m[1]}${id} ${m[2]}${m[3] || ''}`;
+        touched = true; added++;
+      } else if (m) { seq++; }
+    }
+    if (touched) fs.writeFileSync(fp, lines.join('\n'));
+  }
+  return added;
+}
+
+function runInit({ target, templatesDir, version, agentsArg }) {
+  fs.mkdirSync(target, { recursive: true });
+  const notes = [];
+
+  let agents, detected = [];
+  if (agentsArg) {
+    agents = agentsArg.split(',');
+  } else {
+    detected = detect.detectAgents(target);
+    agents = detected.length ? detected : ['claude', 'codex'];
+    notes.push(detected.length
+      ? `Detected agent(s): ${detected.join(', ')} — active: ${agents[0]}.`
+      : 'No agent CLI detected — defaulted to claude + codex.');
+  }
+
+  const claude = path.join(target, 'CLAUDE.md');
+  if (fs.existsSync(claude) && !fs.existsSync(claude + '.tomerge')) {
+    fs.renameSync(claude, claude + '.tomerge');
+    notes.push('Existing CLAUDE.md preserved as CLAUDE.md.tomerge — your agent merges it on first run.');
+  }
+
+  const spectoflowDir = path.join(target, '.spectoflow');
+  copyDir(templatesDir, spectoflowDir);
+
+  const frameworkFiles = ownership.listFrameworkFiles(templatesDir);
+  manifest.writeManifest(spectoflowDir, {
+    version,
+    files: manifest.hashFileMap(spectoflowDir, frameworkFiles),
+  });
+
+  const cfgPath = path.join(spectoflowDir, 'config.json');
+  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  cfg.agent = agents[0];
+  cfg.runners = { ...cfg.runners, ...adapters.defaultRunners(agents) };
+  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+
+  const plansDirName = store.resolvePlansDir(target, cfg);
+  const specsDirName = store.resolveSpecsDir(target, cfg);
+  fs.mkdirSync(path.join(target, specsDirName), { recursive: true });
+  fs.mkdirSync(path.join(target, plansDirName), { recursive: true });
+  if (plansDirName !== 'plans') notes.push(`Using existing '${plansDirName}/' as the plans folder (set plansDir in config.json to override).`);
+  if (specsDirName !== 'specs') notes.push(`Using existing '${specsDirName}/' as the specs folder (set specsDir in config.json to override).`);
+
+  const added = normalizePlans(target, cfg);
+  if (added) notes.push(`Normalized ${added} existing task(s) with stable ids.`);
+
+  const written = adapters.generate(target, agents);
+
+  const mcpTargets = [path.join(target, '.mcp.json')];
+  if (agents.includes('cursor')) mcpTargets.push(path.join(target, '.cursor', 'mcp.json'));
+  for (const fp of mcpTargets) {
+    const rel = path.relative(target, fp).split(path.sep).join('/');
+    const r = mcp.mergeMcpServer(fp, 'playwright', mcp.PLAYWRIGHT_MCP);
+    if (r === 'created' || r === 'added') notes.push(`Wired Playwright MCP into ${rel} (npx @playwright/mcp — for the E2E agent; commit it to share).`);
+    else if (r === 'skipped') notes.push(`Left ${rel} as-is (couldn't parse it) — add a 'playwright' MCP server yourself for browser-driven E2E.`);
+  }
+
+  const gi = path.join(target, '.gitignore');
+  const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+  for (const line of ['.spectoflow/runtime.json', '.spectoflow/.dashboard.lock']) {
+    if (!giText.includes(line)) fs.appendFileSync(gi, ((fs.existsSync(gi) && fs.readFileSync(gi, 'utf8').length) ? '\n' : '') + line + '\n');
+  }
+
+  return { target, agents, detected, written, notes };
+}
+
+module.exports = { runInit };

package/lib/registry.js

@@ -20,6 +20,9 @@ function registryDir(baseDir) {
 function registryPath(baseDir) {
   return path.join(registryDir(baseDir), REGISTRY_FILE);
 }
+function hubLockPath(baseDir) {
+  return path.join(registryDir(baseDir), 'hub.lock');
+}
 
 function readRegistry(baseDir) {
   try { return JSON.parse(fs.readFileSync(registryPath(baseDir), 'utf8')); }
@@ -94,5 +97,5 @@ function listProjects(baseDir) {
 
 module.exports = {
   readRegistry, writeRegistry, genId, addProject, removeProject, touchProject,
-  findByPath, listProjects, registryPath,
+  findByPath, listProjects, registryPath, hubLockPath,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.22.5",
+  "version": "0.23.1",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",

package/templates/dashboard/public/app.js

@@ -15,6 +15,23 @@ let attnFilter = 'open';                          // attention tab filter — cl
 // apply the persisted design skin as early as possible (before the first paint of app-driven DOM)
 (function(){ try{ const d=localStorage.getItem('spf-design'); if(d) document.documentElement.setAttribute('data-design',d); }catch{} })();
 
+// The project this dashboard tab is showing — derived once from the URL's /p/<id>/... prefix. The
+// hub-server's legacy-route redirect (sub-project 3) guarantees a bookmark without this prefix never
+// reaches this file directly; it 302s to a /p/<id>/... URL first. Null when served by the older
+// single-project templates/dashboard/server.js (no prefix at all) — every helper below no-ops in
+// that case, preserving today's exact single-project behavior.
+const PROJECT_ID = (() => { const m = location.pathname.match(/^\/p\/([0-9a-f]{6})(?:\/|$)/); return m ? m[1] : null; })();
+// Every /api/* fetch/EventSource call funnels its URL through this — the one place a project id gets
+// attached, so no call site can forget it. Handles both "no query string yet" (?p=) and "already has
+// one" (&p=, e.g. '/api/agentfile?path=...').
+function withProject(url) { if (!PROJECT_ID) return url; return url + (url.includes('?') ? '&' : '?') + 'p=' + encodeURIComponent(PROJECT_ID); }
+// Prefixes an app-internal path (e.g. '/board', '/custom/x') with /p/<id> for history.pushState/
+// replaceState — every page navigation this file performs stays within the current project.
+function projectPath(rest) { return PROJECT_ID ? '/p/' + PROJECT_ID + rest : rest; }
+// location.pathname's segments with a leading /p/<id> stripped, if present — the single place that
+// strip happens, so tabFromPath()/taskFromPath() never have to know about the prefix twice.
+function pathSegments() { const s = location.pathname.split('/').filter(Boolean); return (s[0] === 'p' && s[1]) ? s.slice(2) : s; }
+
 const $ = (s,r=document)=>r.querySelector(s);
 const $$ = (s,r=document)=>[...r.querySelectorAll(s)];
 const el=(t,c,x)=>{const e=document.createElement(t); if(c)e.className=c; if(x!=null)e.textContent=x; return e;};
@@ -22,7 +39,7 @@ const allTasks=()=> (P.plans||[]).flatMap(pl=>pl.phases.flatMap(ph=>ph.tasks.map
 const runtimeTests=(id)=> (P.runtime&&P.runtime.tests&&P.runtime.tests[id])||null;
 
 async function load(){
-  const r = await fetch('/api/project'); P = await r.json(); render();
+  const r = await fetch(withProject('/api/project')); P = await r.json(); render();
   if(openTaskId) openDrawer(openTaskId,true);
 }
 // Coalesce bursts of SSE 'change'/'message' events into one reload so the board doesn't
@@ -30,7 +47,7 @@ async function load(){
 let loadTimer=null;
 function scheduleLoad(){ clearTimeout(loadTimer); loadTimer=setTimeout(load,180); }
 function connect(){
-  const es = new EventSource('/api/events');
+  const es = new EventSource(withProject('/api/events'));
   es.onopen = ()=>{ $('#sync').classList.remove('offline'); $('#syncLabel').textContent='live'; };
   es.onmessage = (ev)=>{
     let m; try{ m=JSON.parse(ev.data); }catch{ return; }
@@ -123,32 +140,32 @@ async function doRun(promptEl,agentEl){
   promptEl=promptEl||$('#runPrompt'); agentEl=agentEl||$('#runAgent');
   const prompt=promptEl.value.trim(); if(!prompt) return;
   const agent=agentEl.value;
-  await fetch('/api/run',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({prompt,agent})});
+  await fetch(withProject('/api/run'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({prompt,agent})});
   promptEl.value=''; // the prompt renders as a bubble from the message log
 }
 async function doOrchestrate(promptEl){
   if(isChatBusy()) return;
   promptEl=promptEl||$('#runPrompt');
   const prompt=promptEl.value.trim(); if(!prompt) return;
-  await fetch('/api/orchestrate',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({request:prompt})});
+  await fetch(withProject('/api/orchestrate'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({request:prompt})});
   promptEl.value='';
 }
-async function approve(decision){ await fetch('/api/orchestrate/approve',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({decision})}); }
+async function approve(decision){ await fetch(withProject('/api/orchestrate/approve'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({decision})}); }
 // ---- chat context management: condense the log via the agent, or wipe it (Chat tab only — the
 // floating widget stays "quick access", full controls live where there's room to read them) ----
 async function summarizeChat(agentEl){
   if(isChatBusy()) return;
   const agent=(agentEl||$('#tabRunAgent'))?.value;
   flash();
-  await fetch('/api/chat/summarize',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({agent})});
+  await fetch(withProject('/api/chat/summarize'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({agent})});
 }
 async function clearChat(){
   flash();
-  await fetch('/api/chat/clear',{method:'POST'});
+  await fetch(withProject('/api/chat/clear'),{method:'POST'});
 }
-async function patchTask(id,patch){ flash(); await fetch('/api/task/'+encodeURIComponent(id),{method:'PATCH',headers:{'Content-Type':'application/json'},body:JSON.stringify(patch)}); }
-async function addComment(id,text,action){ flash(); await fetch('/api/task/'+encodeURIComponent(id)+'/comment',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({text,action})}); }
-async function toggleStep(name){ flash(); await fetch('/api/workflow/toggle',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({name})}); }
+async function patchTask(id,patch){ flash(); await fetch(withProject('/api/task/'+encodeURIComponent(id)),{method:'PATCH',headers:{'Content-Type':'application/json'},body:JSON.stringify(patch)}); }
+async function addComment(id,text,action){ flash(); await fetch(withProject('/api/task/'+encodeURIComponent(id)+'/comment'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({text,action})}); }
+async function toggleStep(name){ flash(); await fetch(withProject('/api/workflow/toggle'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({name})}); }
 function flash(){ const s=$('#sync'); s.classList.add('saving'); $('#syncLabel').textContent='writing…'; setTimeout(()=>{ s.classList.remove('saving'); $('#syncLabel').textContent='live'; },800); }
 
 // ---- "agent is running" state — no visible feedback used to exist between clicking Send/
@@ -731,7 +748,7 @@ function editAttn(it,txtNode){
   ta.addEventListener('blur',save);
   ta.addEventListener('keydown',e=>{ if((e.metaKey||e.ctrlKey)&&e.key==='Enter'){ e.preventDefault(); save(); } if(e.key==='Escape'){ done=true; renderAttention(); } });
 }
-async function addAttn(text){ flash(); await fetch('/api/attention',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({text})}); }
+async function addAttn(text){ flash(); await fetch(withProject('/api/attention'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({text})}); }
 
 // ---- Backlog "+ Add task" — a manual checkbox task, no agent involved ----
 function openBacklogAddForm(){
@@ -756,7 +773,7 @@ async function submitBacklogAdd(){
   const owner=($('#blAddOwner').value||'').trim();
   const level=$('#blAddLevel').value;
   flash();
-  const r=await fetch('/api/task',{method:'POST',headers:{'Content-Type':'application/json'},
+  const r=await fetch(withProject('/api/task'),{method:'POST',headers:{'Content-Type':'application/json'},
     body:JSON.stringify({title, phase:phase||undefined, owner:owner||undefined, level})});
   if(!r.ok){
     const j=await r.json().catch(()=>({}));
@@ -765,9 +782,9 @@ async function submitBacklogAdd(){
   }
   closeBacklogAddForm();
 }
-async function patchAttn(id,patch){ flash(); await fetch('/api/attention/'+encodeURIComponent(id),{method:'PATCH',headers:{'Content-Type':'application/json'},body:JSON.stringify(patch)}); }
-async function deleteAttn(id){ flash(); await fetch('/api/attention/'+encodeURIComponent(id),{method:'DELETE'}); }
-async function promoteAttn(id){ flash(); await fetch('/api/attention/'+encodeURIComponent(id)+'/promote',{method:'POST'}); }
+async function patchAttn(id,patch){ flash(); await fetch(withProject('/api/attention/'+encodeURIComponent(id)),{method:'PATCH',headers:{'Content-Type':'application/json'},body:JSON.stringify(patch)}); }
+async function deleteAttn(id){ flash(); await fetch(withProject('/api/attention/'+encodeURIComponent(id)),{method:'DELETE'}); }
+async function promoteAttn(id){ flash(); await fetch(withProject('/api/attention/'+encodeURIComponent(id)+'/promote'),{method:'POST'}); }
 
 // ---- Settings tab + topbar quick-switch: change autonomy mode + output language (writes config.json) ----
 // Mode/language can be changed from two places — the Settings tab (#setMode/#setLang) and the
@@ -826,13 +843,13 @@ function showAgentError(msg){
 async function saveAgent(id){
   if(!id) return;
   flash();
-  const r=await fetch('/api/settings',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({agent:id})});
+  const r=await fetch(withProject('/api/settings'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({agent:id})});
   if(!r.ok){ const body=await r.json().catch(()=>({})); showAgentError(body.error||t('topbar.agent.none')); setAgentSelects(); return; }
 }
 // ---- design skins (data-design) — switchable, persisted per viewer + as the project default ----
 function currentDesign(){ return document.documentElement.getAttribute('data-design')||'console'; }
 function applyDesign(id){ document.documentElement.setAttribute('data-design',id); try{ localStorage.setItem('spf-design',id); }catch{} }
-async function saveDesign(id){ applyDesign(id); if(P) render(); /* re-read token colours into the SVG charts */ flash(); try{ await fetch('/api/settings',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({design:id})}); }catch{} }
+async function saveDesign(id){ applyDesign(id); if(P) render(); /* re-read token colours into the SVG charts */ flash(); try{ await fetch(withProject('/api/settings'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({design:id})}); }catch{} }
 
 function renderSettings(){
   const c=(P&&P.config)||{};
@@ -864,7 +881,7 @@ function renderSettings(){
 async function saveSettings(){
   flash();
   const mode=($('#setMode')||$('#topMode')).value, language=($('#setLang')||$('#topLang')).value;
-  await fetch('/api/settings',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({mode,language})});
+  await fetch(withProject('/api/settings'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({mode,language})});
   const s=$('#settingsSaved'); if(s){ s.hidden=false; setTimeout(()=>{ s.hidden=true; },1500); }
 }
 
@@ -1032,7 +1049,7 @@ function renderCustomize(){
 async function czSubmit(kind,description,agent){
   const cfg=CZ_KINDS.find((c)=>c.kind===kind);
   const prompt=description?cfg.promptAdd(description):cfg.promptAuto;
-  await fetch('/api/run',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({prompt,agent})});
+  await fetch(withProject('/api/run'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({prompt,agent})});
   const root=$('#czRoot'); if(root) root.dataset.open='';
   navigateTab('chat');
 }
@@ -1046,17 +1063,17 @@ const ROUTES=['board','requests','attention','backlog','workflow','team','files'
 // under that name still land on the Personalize tab instead of a blank panel.
 function normalizeTab(t){ return t==='settings'?'personalize':t; }
 function tabFromPath(){
-  const s=location.pathname.split('/').filter(Boolean);
+  const s=pathSegments();
   if(s[0]==='custom'&&s[1]) return 'custom:'+decodeURIComponent(s[1]);
   const t=normalizeTab(s[0]);
   return ROUTES.includes(t)?t:null;
 }
-function taskFromPath(){ const s=location.pathname.split('/').filter(Boolean); return (ROUTES.includes(s[0])&&s[1])?decodeURIComponent(s[1]):null; }
+function taskFromPath(){ const s=pathSegments(); return (ROUTES.includes(s[0])&&s[1])?decodeURIComponent(s[1]):null; }
 function navigateTab(tabId,push){
   activeTab=tabId; try{ localStorage.setItem('spf-tab',tabId); }catch{}
   if(push!==false){
     const isCustom=tabId.indexOf('custom:')===0;
-    history.pushState(null,'', isCustom ? '/custom/'+encodeURIComponent(tabId.slice(7)) : '/'+tabId);
+    history.pushState(null,'', projectPath(isCustom ? '/custom/'+encodeURIComponent(tabId.slice(7)) : '/'+tabId));
   }
   applyActiveTab();
   closeNav(); // a tab pick closes the mobile menu
@@ -1163,7 +1180,7 @@ async function openFileDrawer(kind,obj){
   sec.append(body); b.append(sec);
   $('#drawer').setAttribute('aria-hidden','false');
   try{
-    const r=await fetch('/api/agentfile?path='+encodeURIComponent(rel));
+    const r=await fetch(withProject('/api/agentfile?path='+encodeURIComponent(rel)));
     const data=await r.json().catch(()=>({}));
     if(!r.ok){ body.innerHTML=''; body.append(el('div','empty', data.error||t('drawer.loadError'))); return; }
     body.innerHTML=mdLite(data.content||'');
@@ -1325,7 +1342,7 @@ let filesSelectedDir=''; // '' = project root — the folder + File/+ Folder cre
 const filesOpenDirs=new Set(); // persists which tree folders are expanded across a refresh
 async function loadFilesTree(){
   try{
-    const r=await fetch('/api/files/tree'); const d=await r.json().catch(()=>({}));
+    const r=await fetch(withProject('/api/files/tree')); const d=await r.json().catch(()=>({}));
     filesTreeData = (r.ok && Array.isArray(d.tree)) ? d.tree : [];
   }catch{ filesTreeData=filesTreeData||[]; }
   renderFilesTree();
@@ -1488,7 +1505,7 @@ async function openFilesFile(relPath){
   const box=$('#filesContent'); box.innerHTML='';
   box.append(el('div','files-empty',t('drawer.loading')));
   let data;
-  try{ const r=await fetch('/api/files/read?'+new URLSearchParams({path:relPath})); data=await r.json().catch(()=>({})); if(!r.ok) throw new Error(data.error||'error'); }
+  try{ const r=await fetch(withProject('/api/files/read?'+new URLSearchParams({path:relPath}))); data=await r.json().catch(()=>({})); if(!r.ok) throw new Error(data.error||'error'); }
   catch(err){ box.innerHTML=''; box.append(el('div','files-empty',err.message||t('files.loadError'))); return; }
   box.innerHTML='';
   const bar=el('div','files-toolbar-row');
@@ -1515,7 +1532,7 @@ function filesDiscardBtn(relPath){
 }
 async function filesSave(relPath,content,actions){
   try{
-    const r=await fetch('/api/files/write',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({path:relPath,content})});
+    const r=await fetch(withProject('/api/files/write'),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({path:relPath,content})});
     const d=await r.json().catch(()=>({}));
     if(!r.ok) throw new Error(d.error||'error');
     filesOpenDirty=false; filesSavedTip(actions);
@@ -1610,7 +1627,7 @@ async function submitFilesCreate(){
   const kind=filesCreateKind;
   const endpoint = kind==='dir' ? '/api/files/mkdir' : '/api/files/write';
   const payload = kind==='dir' ? {path:rel} : {path:rel,content:''};
-  const r=await fetch(endpoint,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(payload)});
+  const r=await fetch(withProject(endpoint),{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(payload)});
   const d=await r.json().catch(()=>({}));
   if(!r.ok){ if(err){ err.textContent=d.error||t('files.saveError'); err.hidden=false; } return; }
   closeFilesCreateForm();
@@ -1623,7 +1640,7 @@ function openDrawer(id,keep){
   // function calls it repeatedly below; shadowing it with a task variable would break every call.
   const task=allTasks().find(x=>x.id===id); if(!task) return;
   openTaskId=id;
-  if(!keep && taskFromPath()!==id) history.pushState(null,'','/'+activeTab+'/'+encodeURIComponent(id));
+  if(!keep && taskFromPath()!==id) history.pushState(null,'',projectPath('/'+activeTab+'/'+encodeURIComponent(id)));
   const b=$('#drawerBody'); const prev=keep?$('.drawer-panel').scrollTop:0; b.innerHTML='';
   b.append(el('div','d-id',task.id+' · '+(task.level||'standard')+' · '+task.file));
   b.append(el('div','d-title',task.title));
@@ -1657,7 +1674,7 @@ function openDrawer(id,keep){
   $('#drawer').setAttribute('aria-hidden','false');
   if(keep) $('.drawer-panel').scrollTop=prev;
 }
-function closeDrawer(){ if(taskFromPath()) history.pushState(null,'','/'+activeTab); openTaskId=null; $('#drawer').setAttribute('aria-hidden','true'); }
+function closeDrawer(){ if(taskFromPath()) history.pushState(null,'',projectPath('/'+activeTab)); openTaskId=null; $('#drawer').setAttribute('aria-hidden','true'); }
 const cssv=(v)=> getComputedStyle(document.documentElement).getPropertyValue(v).trim()||'#888';
 
 // tabs — activeTab is the single source of truth (persisted), so a click sets it and applies it,
@@ -1707,7 +1724,7 @@ const brandLogo=$('.brand-logo'); if(brandLogo) brandLogo.addEventListener('clic
 applyActiveTab(); // sync to the resolved tab before the first render
 // an old bookmark/share to the pre-rename "/settings" URL: swap the address bar to the real
 // route once resolved, so the visible URL matches the "Personalize" tab it landed on.
-if(location.pathname.split('/').filter(Boolean)[0]==='settings') history.replaceState(null,'','/personalize');
+if(pathSegments()[0]==='settings') history.replaceState(null,'',projectPath('/personalize'));
 // filters (status chips + search) — client-side only, does not write anything
 $$('#statusChips .fchip').forEach(b=> b.addEventListener('click', ()=>{ filter.status=b.dataset.status; renderBoard(); }));
 $('#search').addEventListener('input', e=>{ filter.q=e.target.value; renderBoard(); });

package/templates/dashboard/public/hub.html

@@ -0,0 +1,69 @@
+<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>spectoflow · projects</title>
+  <link rel="icon" type="image/png" href="/logo-dark.png" />
+  <link rel="icon" type="image/png" media="(prefers-color-scheme: dark)" href="/logo-white.png" />
+  <link rel="stylesheet" href="/styles.css" />
+</head>
+<body class="hub-body">
+  <header class="hub-header">
+    <div class="hub-brand">
+      <img class="brand-logo-img is-dark" src="/logo-white.png" alt="" />
+      <img class="brand-logo-img is-light" src="/logo-dark.png" alt="" />
+      <span class="hub-brand-name">spectoflow</span>
+    </div>
+    <button class="hub-theme-toggle" id="hubThemeToggle" aria-label="Toggle theme" title="Toggle theme">◐</button>
+  </header>
+
+  <main class="hub-main">
+    <div class="hub-titlebar">
+      <h1>Your projects</h1>
+      <button class="hub-add-btn" id="hubAddBtn">+ Add project</button>
+    </div>
+
+    <div id="hubEmpty" class="hub-empty" hidden>
+      <p class="hub-empty-title">No projects yet</p>
+      <p class="hub-empty-sub">Add your first project to get started — point spectoflow at any folder on your computer.</p>
+      <button class="hub-add-btn hub-add-btn-lg" id="hubAddBtnEmpty">+ Add your first project</button>
+    </div>
+
+    <div id="hubGrid" class="hub-grid"></div>
+  </main>
+
+  <div id="hubModal" class="hub-modal" hidden>
+    <div class="hub-modal-card">
+      <div class="hub-modal-head">
+        <h2>Add a project</h2>
+        <button class="hub-modal-close" id="hubModalClose" aria-label="Close">&times;</button>
+      </div>
+      <div class="hub-modal-tabs">
+        <button class="hub-modal-tab is-active" data-mode="browse">Browse</button>
+        <button class="hub-modal-tab" data-mode="paste">Paste a path</button>
+      </div>
+
+      <div id="hubBrowsePane" class="hub-modal-pane">
+        <div class="hub-browse-crumb" id="hubBrowseCrumb"></div>
+        <div class="hub-browse-list" id="hubBrowseList"></div>
+        <div class="hub-browse-footer">
+          <span class="hub-browse-current" id="hubBrowseCurrent"></span>
+          <button class="hub-add-btn" id="hubBrowseUse">Use this folder</button>
+        </div>
+      </div>
+
+      <div id="hubPastePane" class="hub-modal-pane" hidden>
+        <label class="hub-paste-label" for="hubPasteInput">Folder path</label>
+        <input class="hub-paste-input" id="hubPasteInput" type="text" placeholder="e.g. C:\Users\you\Projects\my-app" autocomplete="off" spellcheck="false" />
+        <button class="hub-add-btn" id="hubPasteUse">Use this path</button>
+      </div>
+
+      <p class="hub-modal-error" id="hubModalError" hidden></p>
+      <p class="hub-modal-status" id="hubModalStatus" hidden></p>
+    </div>
+  </div>
+
+  <script src="/hub.js"></script>
+</body>
+</html>

package/templates/dashboard/public/hub.js

@@ -0,0 +1,134 @@
+'use strict';
+(function () {
+  const s = localStorage.getItem('spf-theme');
+  if (s) document.documentElement.setAttribute('data-theme', s);
+})();
+(function () {
+  const grid = document.getElementById('hubGrid');
+  const empty = document.getElementById('hubEmpty');
+  const modal = document.getElementById('hubModal');
+  const modalError = document.getElementById('hubModalError');
+  const modalStatus = document.getElementById('hubModalStatus');
+  const browsePane = document.getElementById('hubBrowsePane');
+  const pastePane = document.getElementById('hubPastePane');
+  const browseCrumb = document.getElementById('hubBrowseCrumb');
+  const browseList = document.getElementById('hubBrowseList');
+  const browseCurrent = document.getElementById('hubBrowseCurrent');
+  let browsePath = null; // null = show starting points (home dir / drives)
+
+  function esc(s) { return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])); }
+  function timeAgo(iso) {
+    if (!iso) return '';
+    const ms = Date.now() - new Date(iso).getTime();
+    const m = Math.floor(ms / 60000);
+    if (m < 1) return 'just now';
+    if (m < 60) return m + 'm ago';
+    const h = Math.floor(m / 60);
+    if (h < 24) return h + 'h ago';
+    return Math.floor(h / 24) + 'd ago';
+  }
+
+  async function loadProjects() {
+    const r = await fetch('/api/hub/projects');
+    const data = await r.json();
+    const rows = data.projects || [];
+    empty.hidden = rows.length > 0;
+    grid.innerHTML = rows.map((p) => {
+      const pct = p.stats && p.stats.total ? Math.round(100 * p.stats.done / p.stats.total) : null;
+      return `<div class="hub-card" data-id="${p.id}">
+        <a class="hub-card-open" href="/p/${p.id}/board">
+          <div class="hub-card-name">${esc(p.name)}</div>
+          <div class="hub-card-path">${esc(p.path)}</div>
+          ${pct !== null ? `<div class="hub-card-progress"><div class="hub-card-progress-fill" style="width:${pct}%"></div></div><div class="hub-card-pct">${pct}% · ${p.stats.done}/${p.stats.total} tasks</div>` : ''}
+          <div class="hub-card-meta">Opened ${esc(timeAgo(p.lastOpened))}</div>
+        </a>
+        <button class="hub-card-remove" data-remove="${p.id}" title="Remove from this list" aria-label="Remove ${esc(p.name)}">&times;</button>
+      </div>`;
+    }).join('');
+  }
+
+  // No native confirm() — it blocks the tab (and this codebase never uses it, see D46). A second
+  // click within 3s on the same remove button confirms; the button flips to a checkmark meanwhile.
+  let pendingRemoveId = null;
+  function confirmRemove(id) {
+    if (pendingRemoveId === id) { pendingRemoveId = null; return true; }
+    pendingRemoveId = id;
+    const btn = grid.querySelector('[data-remove="' + id + '"]');
+    if (btn) {
+      const orig = btn.textContent;
+      btn.textContent = '✓'; btn.title = 'Click again to confirm';
+      setTimeout(() => { if (btn.textContent === '✓') btn.textContent = orig; }, 3000);
+    }
+    return false;
+  }
+  grid.addEventListener('click', async (e) => {
+    const btn = e.target.closest('[data-remove]');
+    if (!btn) return;
+    e.preventDefault();
+    const id = btn.getAttribute('data-remove');
+    if (!confirmRemove(id)) return;
+    await fetch('/api/hub/projects/' + encodeURIComponent(id), { method: 'DELETE' });
+    loadProjects();
+  });
+
+  function openModal() { modal.hidden = false; modalError.hidden = true; modalStatus.hidden = true; browsePath = null; loadBrowse(); }
+  function closeModal() { modal.hidden = true; }
+  document.getElementById('hubAddBtn').addEventListener('click', openModal);
+  document.getElementById('hubAddBtnEmpty').addEventListener('click', openModal);
+  document.getElementById('hubModalClose').addEventListener('click', closeModal);
+  modal.addEventListener('click', (e) => { if (e.target === modal) closeModal(); });
+
+  document.querySelectorAll('.hub-modal-tab').forEach((tab) => {
+    tab.addEventListener('click', () => {
+      document.querySelectorAll('.hub-modal-tab').forEach((t) => t.classList.remove('is-active'));
+      tab.classList.add('is-active');
+      const mode = tab.getAttribute('data-mode');
+      browsePane.hidden = mode !== 'browse';
+      pastePane.hidden = mode !== 'paste';
+    });
+  });
+
+  async function loadBrowse() {
+    const q = browsePath ? ('?path=' + encodeURIComponent(browsePath)) : '';
+    const r = await fetch('/api/hub/browse' + q);
+    const data = await r.json();
+    if (data.error) { browseList.innerHTML = '<p class="hub-browse-empty">' + esc(data.error) + '</p>'; return; }
+    browsePath = data.current || null;
+    browseCurrent.textContent = browsePath || 'Choose a starting point';
+    // A drive root (D:\) or similar has no OS-level parent (data.parent is null) but the picker must
+    // never dead-end there — "Up" from any real folder always goes somewhere: its real parent, or
+    // back to the starting points list if there isn't one. Only hide it once we're AT that list.
+    const showUp = browsePath !== null;
+    browseCrumb.innerHTML = showUp ? `<button class="hub-crumb-up" id="hubCrumbUp">&larr; Up</button>` : '';
+    const up = document.getElementById('hubCrumbUp');
+    if (up) up.addEventListener('click', () => { browsePath = data.parent || null; loadBrowse(); });
+    browseList.innerHTML = (data.entries || []).map((e) =>
+      `<button class="hub-browse-item" data-path="${esc(e.path)}">${esc(e.name)}</button>`
+    ).join('') || '<p class="hub-browse-empty">No sub-folders here.</p>';
+    browseList.querySelectorAll('[data-path]').forEach((el) => {
+      el.addEventListener('click', () => { browsePath = el.getAttribute('data-path'); loadBrowse(); });
+    });
+  }
+
+  async function submitPath(p) {
+    modalError.hidden = true; modalStatus.hidden = false; modalStatus.textContent = 'Adding…';
+    const r = await fetch('/api/hub/projects', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ path: p }) });
+    const data = await r.json();
+    if (!r.ok) { modalStatus.hidden = true; modalError.hidden = false; modalError.textContent = data.error || 'Could not add that folder.'; return; }
+    location.href = '/p/' + data.entry.id + '/board';
+  }
+  document.getElementById('hubBrowseUse').addEventListener('click', () => { if (browsePath) submitPath(browsePath); });
+  document.getElementById('hubPasteUse').addEventListener('click', () => {
+    const v = document.getElementById('hubPasteInput').value.trim();
+    if (v) submitPath(v);
+  });
+
+  document.getElementById('hubThemeToggle').addEventListener('click', () => {
+    const cur = document.documentElement.getAttribute('data-theme');
+    const next = cur === 'dark' ? 'light' : 'dark';
+    document.documentElement.setAttribute('data-theme', next);
+    localStorage.setItem('spf-theme', next);
+  });
+
+  loadProjects();
+})();

package/templates/dashboard/public/index.html

@@ -18,6 +18,7 @@
         <img class="brand-logo-img is-dark" src="/logo-white.png" alt="spectoflow" />
         <img class="brand-logo-img is-light" src="/logo-dark.png" alt="spectoflow" />
       </a>
+      <a class="hub-back-link" href="/" title="Back to your projects" aria-label="Back to your projects">⌂</a>
       <div class="brand-text">
         <div class="brand-line">
           <span class="brand-name">spectoflow</span>

package/templates/dashboard/public/styles.css

@@ -968,3 +968,62 @@ body.booting .wf-step2 { opacity:0; animation:rise .4s cubic-bezier(.2,.8,.2,1)
 
 /* Phase progress: cap the list so a big project (many phases) doesn't dominate the overview */
 .bars-block.scroll-cap { max-height:340px; overflow-y:auto; padding-right:6px; }
+
+/* ---- Hub landing page (multi-project) — reuses the same tokens as the per-project dashboard,
+   deliberately simpler: no per-design skins, no tabs, just a calm project picker. ---- */
+.hub-body { min-height:100%; display:flex; flex-direction:column; }
+.hub-header { display:flex; align-items:center; justify-content:space-between; padding:16px 24px; border-bottom:1px solid var(--line); }
+.hub-brand { display:flex; align-items:center; gap:9px; font-weight:700; }
+.hub-brand .brand-logo-img { width:22px; height:22px; }
+.hub-brand-name { font-size:15px; }
+.hub-theme-toggle { width:32px; height:32px; border-radius:8px; border:1px solid var(--line); background:var(--surface); color:var(--ink); cursor:pointer; font-size:14px; }
+.hub-main { flex:1; max-width:1080px; width:100%; margin:0 auto; padding:32px 24px 60px; }
+.hub-titlebar { display:flex; align-items:center; justify-content:space-between; gap:16px; margin-bottom:24px; flex-wrap:wrap; }
+.hub-titlebar h1 { font-size:24px; font-weight:700; margin:0; }
+.hub-add-btn { font-family:var(--sans); font-size:13.5px; font-weight:600; padding:9px 16px; border-radius:9px; border:1px solid transparent; background:var(--signal); color:var(--on-accent); cursor:pointer; transition:filter .15s; }
+.hub-add-btn:hover { filter:brightness(1.08); }
+.hub-add-btn-lg { padding:12px 22px; font-size:14.5px; margin-top:14px; }
+.hub-empty { text-align:center; padding:60px 20px; border:1px dashed var(--line); border-radius:var(--radius); }
+.hub-empty-title { font-size:18px; font-weight:700; margin:0 0 8px; }
+.hub-empty-sub { color:var(--muted); font-size:13.5px; max-width:420px; margin:0 auto; }
+.hub-grid { display:grid; grid-template-columns:repeat(auto-fill,minmax(260px,1fr)); gap:14px; }
+.hub-card { position:relative; background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); transition:border-color .15s,transform .15s; }
+.hub-card:hover { border-color:var(--signal); transform:translateY(-1px); }
+.hub-card-open { display:block; padding:16px; text-decoration:none; color:inherit; }
+.hub-card-name { font-size:15px; font-weight:700; color:var(--ink); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.hub-card-path { font-family:var(--mono); font-size:10.5px; color:var(--faint); margin-top:4px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.hub-card-progress { height:5px; border-radius:999px; background:var(--surface-2); margin-top:12px; overflow:hidden; }
+.hub-card-progress-fill { height:100%; background:var(--s-done); border-radius:999px; }
+.hub-card-pct { font-family:var(--mono); font-size:10.5px; color:var(--muted); margin-top:6px; }
+.hub-card-meta { font-size:11px; color:var(--faint); margin-top:10px; }
+.hub-card-remove { position:absolute; top:8px; right:8px; width:22px; height:22px; border-radius:999px; border:1px solid var(--line); background:var(--surface-2); color:var(--muted); cursor:pointer; font-size:13px; line-height:1; }
+.hub-card-remove:hover { color:var(--s-blocked); border-color:var(--s-blocked); }
+
+.hub-modal { position:fixed; inset:0; background:rgba(0,0,0,.5); display:flex; align-items:center; justify-content:center; z-index:20; padding:20px; }
+.hub-modal[hidden] { display:none; }
+.hub-modal-card { background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); box-shadow:var(--shadow); width:100%; max-width:460px; max-height:86vh; display:flex; flex-direction:column; padding:20px; }
+.hub-modal-head { display:flex; align-items:center; justify-content:space-between; margin-bottom:14px; }
+.hub-modal-head h2 { font-size:16px; margin:0; }
+.hub-modal-close { width:28px; height:28px; border-radius:8px; border:1px solid var(--line); background:var(--surface-2); color:var(--ink); cursor:pointer; font-size:16px; line-height:1; }
+.hub-modal-tabs { display:flex; gap:6px; margin-bottom:14px; }
+.hub-modal-tab { flex:1; font-family:var(--sans); font-size:12.5px; font-weight:600; padding:7px 10px; border-radius:8px; border:1px solid var(--line); background:var(--surface-2); color:var(--muted); cursor:pointer; }
+.hub-modal-tab.is-active { background:var(--signal); border-color:var(--signal); color:var(--on-accent); }
+.hub-modal-pane { display:flex; flex-direction:column; gap:10px; min-height:0; }
+.hub-modal-pane[hidden] { display:none; }
+.hub-browse-crumb { min-height:20px; }
+.hub-crumb-up { font-family:var(--mono); font-size:11.5px; color:var(--cool); background:none; border:0; cursor:pointer; padding:0; }
+.hub-browse-list { display:flex; flex-direction:column; gap:4px; max-height:220px; overflow-y:auto; border:1px solid var(--line); border-radius:9px; padding:6px; }
+.hub-browse-item { text-align:left; font-family:var(--sans); font-size:13px; padding:7px 9px; border-radius:6px; border:0; background:none; color:var(--ink); cursor:pointer; }
+.hub-browse-item:hover { background:var(--surface-2); }
+.hub-browse-empty { color:var(--faint); font-size:12.5px; padding:6px 2px; margin:0; }
+.hub-browse-footer { display:flex; align-items:center; gap:10px; justify-content:space-between; }
+.hub-browse-current { font-family:var(--mono); font-size:10.5px; color:var(--muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; flex:1; }
+.hub-paste-label { font-size:12px; color:var(--muted); }
+.hub-paste-input { font-family:var(--mono); font-size:13px; padding:9px 11px; border-radius:8px; border:1px solid var(--line); background:var(--surface-2); color:var(--ink); }
+.hub-modal-error { color:var(--s-blocked); font-size:12.5px; margin:4px 0 0; }
+.hub-modal-status { color:var(--muted); font-size:12.5px; margin:4px 0 0; }
+
+/* "back to hub" — plain link next to the brand logo on the per-project dashboard; a full navigation
+   (not SPA), since leaving to the hub means leaving this project's dashboard entirely. */
+.hub-back-link { display:flex; align-items:center; justify-content:center; width:26px; height:26px; border-radius:7px; color:var(--muted); text-decoration:none; font-size:15px; flex-shrink:0; transition:background .15s,color .15s; }
+.hub-back-link:hover { background:var(--surface-2); color:var(--ink); }